Folia 歌词接口实战：32109 端口一个 GET 请求，拿到带翻译的逐字歌词

【免费下载链接】folia-major专注于绚丽的歌词动画效果的本地音乐/navidrome/第三方多平台在线音乐播放器项目地址: https://gitcode.com/GitHub_Trending/fo/folia-major

想让悬浮窗跟着 Folia 的播放逐字变色？还是把它的歌词数据同步进直播画面？解析器不用自己写。Folia 的本机歌词接口，就是一个开关加一个 GET 请求的事。

两分钟接通：从歌词接口开关到第一条歌词

① 打开 Folia 桌面端（Windows / macOS / Linux 均支持，Web 版不提供），进入设置 → 连接与集成 → 歌词接口，打开"启用歌词接口"开关。习惯命令面板的话，直接搜"歌词接口"命令更快。开关状态会持久化，下次启动自动监听。

② 启用成功后，设置页会直接显示接口地址http://127.0.0.1:32109/v1/lyric，可一键复制。

③ 终端里发一个请求：

curl http://127.0.0.1:32109/v1/lyric

看到 JSON 即成功；返回null只是当前没加载歌词，不是故障。

接口参数一表打尽

⚠️ 32109 被占用会导致启用失败，设置页显示错误；

⚠️ 不要依赖 localhost，直接写死 127.0.0.1。

服务端实现看 electron/lyricApi.cjs，前端状态同步在 src/hooks/useLyricApiPublisher.ts。

歌词 API 响应字段拆解：读懂那个 JSON

顶层字段一览：

每行lines[]内部：

• text：完整歌词文本
  • startTime/endTime：行时间，单位是秒（和 offset 的毫秒不是一回事）
  • words[]：逐字时间轴，每字含text/startTime/endTime
  • translation/romanization：可选的翻译与罗马音
  • backgroundVocals[]：可选的背景人声，自带独立的逐字数组

一个典型响应（节选）：

{ "offset": -250, "wordByWord": true, "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": "你好，世界" } ] }

💡 源歌词只有逐行时间（普通 LRC）时，Folia 也会自动合成出words，所以它几乎总有内容。但此时wordByWord为false，那些逐字时间是估算值，别当精确逐字时间用。

避坑清单：null、轮询与安全红线

• null 必须判空：没歌、加载中、歌曲无歌词都是 null，且仍是 200。
• 轮询就定 500–1000 ms：数据只在切歌、加载完成、调偏移时变化，高频请求没有意义。
• 当前行要自己算：快照不含播放进度和行索引，用播放时间(秒) - offset / 1000比对行时间。
• 逐字时间看情况用：wordByWord为 false 时是行时间估算，敏感场景要降级处理。
• 严禁暴露到外网：无鉴权接口，不要做端口转发或反代出去。

另外接口已开Access-Control-Allow-Origin: *，本机浏览器页面可以直接跨域 fetch，这是 OBS 浏览器源方案能成立的前提。

三个场景，看它能帮你省多少事

• 桌面歌词悬浮窗：轮询接口，按播放时间定位当前行，在悬浮窗渲染逐字高亮。words[]让你直接做出卡拉OK式逐字变色，不用自己估时间。
• OBS / 直播歌词源：写一个本地 HTML 页面 fetch127.0.0.1:32109/v1/lyric，Folia 的歌词动画数据就同步进直播画面，跨域已放行。
• 跨程序歌词同步：外部歌词面板、校对工具直接复用这份归一化数据，省掉自己解析 LRC/YRC 的全部麻烦。

下一步

完整字段定义、更多响应示例和版本兼容策略，都在 docs/lyric-api.md；想看服务端怎么写，入口就是 electron/lyricApi.cjs。打开 Folia 设置，curl 一下，三秒钟看到歌词。

【免费下载链接】folia-major专注于绚丽的歌词动画效果的本地音乐/navidrome/第三方多平台在线音乐播放器项目地址: https://gitcode.com/GitHub_Trending/fo/folia-major