一个 GET 请求拿到逐字时间轴歌词接入 Folia 本机歌词接口32109 端口【免费下载链接】folia-major专注于绚丽的歌词动画效果的本地音乐/navidrome/第三方多平台在线音乐播放器项目地址: https://gitcode.com/GitHub_Trending/fo/folia-majorFolia 是一款主打歌词动画的本地 / 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拿到手就能直接做逐字高亮。功能边界这个本机接口能访问什么项目值监听地址127.0.0.1仅 IPv4 回环端口32109固定路径/v1/lyric请求方法GET另支持OPTIONS预检鉴权无数据格式JSONUTF-8该服务仅由 FoliaElectron 桌面端Windows / macOS / Linux提供Web 版没有。服务端只绑定 IPv4 回环地址局域网和其他设备一律访问不到客户端请写死127.0.0.1不要依赖localhost的解析结果可能落到 IPv6。若32109被其他程序占用启用会失败设置页会给出对应错误。两步打开它启用与确认监听进入设置 → 连接与集成 → 歌词接口打开启用歌词接口开关或者在命令面板执行歌词接口命令直接切换。确认已生效开关打开后设置页的歌词接口卡片会直接显示接口地址http://127.0.0.1:32109/v1/lyric旁边带运行中状态徽标点复制按钮即可把地址拷到剪贴板若端口被占用卡片下方会显示红色错误文本。设置会被持久化下次启动 Folia 时自动尝试监听同一端口不用每次重开开关。数据契约字段单位与空返回顶层字段字段类型含义offsetnumber用户为当前歌曲手动设置的歌词偏移单位毫秒正延后负提前未调整为 0linesarray按时间排序的歌词行wordByWordbooleantrue数据源原生逐字时间falseFolia 依据逐行时间合成的估算值title/artiststring?歌曲标题与艺术家为空时不返回歌词行lines[]字段字段类型含义textstring该行完整歌词文本startTime/endTimenumber行起止时间单位秒words[]array逐字时间轴每项含text/startTime/endTime秒translation/romanizationstring?翻译与罗马音/音译可选backgroundVocals[]array?背景人声每段自带独立的逐字数组⚠️ 全接口最容易被忽略的一点行/字时间是秒顶层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 } ] } ] }状态码状态码场景200成功响应体为歌词对象或null204CORS 预检通过无响应体404路径不存在405/v1/lyric使用了不支持的方法连接失败无状态码接口未启用、Folia 未运行或端口被占用避坑清单返回的是数据快照而非实时流不含播放进度、当前行索引也不能控制播放。当前行要自己算用播放时间(秒) - 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考