Folia歌词接口API详解127.0.0.1:32109第三方程序接入指南【免费下载链接】folia-major专注于绚丽的歌词动画效果的本地音乐/navidrome/第三方多平台在线音乐播放器项目地址: https://gitcode.com/GitHub_Trending/fo/folia-majorFolia 歌词接口 API 是 Folia 桌面端内置的本机只读 HTTP 服务监听在127.0.0.1:32109第三方程序只需一个 GET 请求http://127.0.0.1:32109/v1/lyric无需鉴权即可拿到当前正在播放歌曲的完整歌词数据——包括逐字时间轴、翻译、罗马音和背景人声。无论你想做一个桌面歌词悬浮窗、OBS 歌词源还是自制歌词同步工具这个 Folia 歌词接口都能让你快速完成对接。Folia 是什么为什么需要歌词接口Folia 是一款专注于绚丽歌词动画的本地音乐 / Navidrome / 多平台在线音乐播放器支持网易云、酷狗、QQ 音乐、Navidrome 和本地音乐库核心卖点是全屏沉浸式歌词动画。它的歌词数据在内部已经过统一流水线处理逐行 LRC 会被自动拆分成逐字时间轴多音源歌词也会归一化成同一结构。而 Folia 歌词接口 API 正是把这份加工好的歌词数据开放给外部程序的官方通道。歌词接口基本信息一览歌词接口是 FoliaElectron 桌面端Windows / macOS / Linux提供的本机服务Web 版不提供。项目值监听地址127.0.0.1仅 IPv4 回环固定端口32109接口路径/v1/lyric请求方法GET另有OPTIONS预检鉴权无数据格式JSONUTF-8⚠️ 注意两点服务只监听127.0.0.1局域网和其他设备无法访问客户端请写死127.0.0.1地址不要依赖localhost的 DNS 解析。如果32109端口被其他程序占用启用会失败设置页会显示对应错误需释放端口后重新启用。接口服务端的完整实现位于 electron/lyricApi.cjs前端状态同步逻辑在 src/hooks/useLyricApiPublisher.ts。一键启用歌词接口的步骤启用只需两步设置会持久化下次启动 Folia 时自动监听打开 Folia 桌面端进入设置 → 连接与集成 → 歌词接口打开启用歌词接口开关或者从命令面板执行歌词接口命令快速切换。启用成功后设置页会直接显示接口地址http://127.0.0.1:32109/v1/lyric可一键复制。该开关的实现见 src/components/modal/settings/IntegrationSettingsSubview.tsx。如何调用接口获取当前歌词请求方式curl http://127.0.0.1:32109/v1/lyric无任何查询参数、无请求体。Python 里则是import requests lyrics requests.get(http://127.0.0.1:32109/v1/lyric, timeout2).json()响应结构速览有歌词时返回一个精简后的 JSON 对象没有加载歌词时返回null仍是 200 OK不是故障字段类型说明offsetnumber用户手动设置的歌词偏移单位毫秒正延后负提前linesarray按时间排序的歌词行wordByWordbooleantrue数据源原生逐字时间falseFolia 根据逐行时间合成title/artiststring?歌曲标题与艺术家为空时不返回每行歌词lines[]包含text完整歌词文本startTime/endTime单位秒words[]逐字时间轴每字含text/startTime/endTimetranslation/romanization可选翻译与罗马音backgroundVocals[]可选背景人声自带独立的逐字数组一个典型的逐字歌词响应长这样节选{ offset: -250, wordByWord: true, title: Example Song, artist: Example Artist, lines: [ { text: Hello world, startTime: 12.4, endTime: 15.1, words: [ { text: Hello, startTime: 12.4, endTime: 13.5 }, { text: world, startTime: 13.5, endTime: 15.1 } ], translation: 你好世界 } ] } 即使原始歌词只有逐行时间普通 LRCFolia 也会自动合出逐字数组所以words几乎总是有内容——但此时wordByWord为false表示逐字时间是估算值不应当作精确逐字时间使用。状态码与接入注意事项状态码含义200成功返回歌词对象或null204CORS 预检通过404路径不存在405方法不支持接入时最容易踩的坑官方文档 docs/lyric-api.md 中都有明确说明接口返回的是数据快照不含播放进度、当前行索引也不能控制播放必须处理null没歌、歌词加载中、歌曲无歌词都会返回null自行计算当前行按播放时间(秒) - offset / 1000与歌词行时间比对感知切歌靠轮询建议每 500–1000 ms 低频请求一次并比较内容因为数据只在切歌、歌词加载完成、调整偏移时更新安全红线这是无鉴权本地接口千万不要通过端口转发或反向代理把它暴露到外网。另外接口已开启Access-Control-Allow-Origin: *本机浏览器页面如自制 HTML 歌词页、OBS 浏览器源可以直接跨域 fetch 读取。适合谁用三类典型场景桌面歌词工具轮询接口 → 按播放时间定位当前行 → 在悬浮窗渲染逐字高亮words[]让你轻松做到卡拉OK式逐字变色OBS / 直播歌词源写一个本地 HTML 页面 fetch127.0.0.1:32109/v1/lyric即可把 Folia 的歌词动画数据同步到直播画面跨程序歌词同步其他播放器正在用的外部歌词面板、歌词校对工具都可以直接复用这份已归一化的逐字数据省去自己解析 LRC/YRC 的麻烦。小结Folia 歌词接口 API 用固定端口32109 单一 GET 路径 无鉴权的设计把接入成本降到了最低开一个开关、发一个请求就能拿到带逐字时间轴、翻译、背景人声的完整歌词快照。完整的字段定义、响应示例和版本兼容策略建议直接阅读官方文档 docs/lyric-api.md接口实现可参考 electron/lyricApi.cjs。现在就去 Folia 设置里打开开关用一行curl验证你的第一条歌词吧【免费下载链接】folia-major专注于绚丽的歌词动画效果的本地音乐/navidrome/第三方多平台在线音乐播放器项目地址: https://gitcode.com/GitHub_Trending/fo/folia-major创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
