企业官网建设流程全解析

一个 GET 请求拿到逐字时间轴歌词：接入 Folia 本机歌词接口（32109 端口）

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

Folia 是一款主打歌词动画的本地 / Navidrome / 多平台在线音乐播放器，其 Electron 桌面端内置了歌词接口 API：向127.0.0.1:32109发一个 GET，就能拿到当前播放歌曲的逐字时间轴、翻译和背景人声，无需鉴权。

先看到效果：一条 curl 验证

服务启用后，最简调用就是一行命令（无查询参数、无请求体）：

$ curl http://127.0.0.1:32109/v1/lyric {"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":"你好，世界"}]}

有歌词时返回上面这种紧凑 JSON 对象；没有歌词时响应体就是 JSONnull（同样是 200 OK）。逐字数组words[]里的每个字/词都带startTime/endTime，拿到手就能直接做逐字高亮。

功能边界：这个本机接口能访问什么

该服务仅由 FoliaElectron 桌面端（Windows / macOS / Linux）提供，Web 版没有。服务端只绑定 IPv4 回环地址，局域网和其他设备一律访问不到；客户端请写死127.0.0.1，不要依赖localhost的解析结果（可能落到 IPv6）。若32109被其他程序占用，启用会失败，设置页会给出对应错误。

两步打开它：启用与确认监听

1. 进入设置 → 连接与集成 → 歌词接口，打开"启用歌词接口"开关；或者在命令面板执行"歌词接口"命令直接切换。
2. 确认已生效：开关打开后，设置页的歌词接口卡片会直接显示接口地址http://127.0.0.1:32109/v1/lyric，旁边带"运行中"状态徽标，点复制按钮即可把地址拷到剪贴板；若端口被占用，卡片下方会显示红色错误文本。

设置会被持久化，下次启动 Folia 时自动尝试监听同一端口，不用每次重开开关。

数据契约：字段单位与空返回

顶层字段：

歌词行（lines[]）字段：

⚠️ 全接口最容易被忽略的一点：行/字时间是秒，顶层offset是毫秒，混算会整体错位。

逐行来源歌词（如普通 LRC）也会带words[]——Folia 会在歌词流水线里把文本拆成逐字并合成时间，此时wordByWord为false，例如：

{ "offset": 0, "wordByWord": false, "lines": [ { "text": "这是一行歌词", "startTime": 3.2, "endTime": 7.8, "words": [ { "text": "这", "startTime": 3.2, "endTime": 3.89 } ] } ] }

状态码：

避坑清单

• 返回的是数据快照而非实时流：不含播放进度、当前行索引，也不能控制播放。
• 当前行要自己算：用播放时间(秒) - offset / 1000与行时间去匹配；切歌靠每 500–1000 ms 轮询一次并比较响应内容（数据只在切歌、歌词加载完成、调整偏移时更新）。
• 必须处理200 + null：没在播放、歌词加载中、歌曲无歌词都会返回null，不是故障。
• wordByWord: false表示逐字时间是行时间估算值，别当精确逐字时间用。
• ⚠️ 安全红线：这是无鉴权接口，不要用端口转发、反向代理或防火墙规则把它暴露到局域网或外网。

适合谁用

• 桌面歌词悬浮窗：轮询接口、按播放时间定位当前行，用words[]渲染卡拉OK式逐字高亮。
• OBS / 直播歌词源：接口已开Access-Control-Allow-Origin: *，本机 HTML 页面可直接跨域 fetch，把歌词同步到直播画面。
• 跨程序歌词同步与校对：直接复用这份已归一化的逐字结构，省掉自己解析 LRC/YRC 的功夫。

收尾：继续深挖

• 完整字段定义与兼容性策略：docs/lyric-api.md
• 服务端实现：electron/lyricApi.cjs
• 前端状态同步：src/hooks/useLyricApiPublisher.ts

现在就去 Folia 设置里打开开关，用一条 curl 把第一条逐字时间轴拉下来。

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