Folia歌词接口API详解：127.0.0.1:32109第三方程序接入指南
【免费下载链接】folia-major专注于绚丽的歌词动画效果的本地音乐/navidrome/第三方多平台在线音乐播放器项目地址: https://gitcode.com/GitHub_Trending/fo/folia-major
Folia 歌词接口 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预检） |
| 鉴权 | 无 |
| 数据格式 | JSON，UTF-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", timeout=2).json()响应结构速览
有歌词时返回一个精简后的 JSON 对象；没有加载歌词时返回null（仍是 200 OK，不是故障）：
| 字段 | 类型 | 说明 |
|---|---|---|
offset | number | 用户手动设置的歌词偏移，单位毫秒（正=延后，负=提前） |
lines | array | 按时间排序的歌词行 |
wordByWord | boolean | true=数据源原生逐字时间；false=Folia 根据逐行时间合成 |
title/artist | string? | 歌曲标题与艺术家（为空时不返回） |
每行歌词（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": "你好，世界" } ] }💡 即使原始歌词只有逐行时间（普通 LRC），Folia 也会自动合出逐字数组，所以
words几乎总是有内容——但此时wordByWord为false，表示逐字时间是估算值，不应当作精确逐字时间使用。
状态码与接入注意事项
| 状态码 | 含义 |
|---|---|
200 | 成功，返回歌词对象或null |
204 | CORS 预检通过 |
404 | 路径不存在 |
405 | 方法不支持 |
接入时最容易踩的坑，官方文档 docs/lyric-api.md 中都有明确说明：
- 接口返回的是数据快照：不含播放进度、当前行索引，也不能控制播放；
- 必须处理
null：没歌、歌词加载中、歌曲无歌词都会返回null； - 自行计算当前行：按
播放时间(秒) - offset / 1000与歌词行时间比对； - 感知切歌靠轮询：建议每 500–1000 ms 低频请求一次并比较内容，因为数据只在切歌、歌词加载完成、调整偏移时更新；
- 安全红线：这是无鉴权本地接口，千万不要通过端口转发或反向代理把它暴露到外网。
另外接口已开启Access-Control-Allow-Origin: *，本机浏览器页面（如自制 HTML 歌词页、OBS 浏览器源）可以直接跨域 fetch 读取。
适合谁用：三类典型场景
- 桌面歌词工具：轮询接口 → 按播放时间定位当前行 → 在悬浮窗渲染逐字高亮，
words[]让你轻松做到卡拉OK式逐字变色； - OBS / 直播歌词源：写一个本地 HTML 页面 fetch
127.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），仅供参考
