Folia 歌词接口 × lia.lines把当前播放歌词挂上 QuickShell 顶栏的完整指南【免费下载链接】folia-major专注于绚丽的歌词动画效果的本地音乐/navidrome/第三方多平台在线音乐播放器项目地址: https://gitcode.com/GitHub_Trending/fo/folia-major如果你在用 Folia 配合 omarchy 4 / QuickShell 桌面Folia 歌词接口和官方插件 lia.lines 的组合值得认真了解。它让 Folia 桌面端把当前歌曲的歌词数据推送到127.0.0.1:32109插件在顶部状态栏实时展示并支持暂停 / 播放操作——从此不用开着 Folia 窗口抬眼就能看到正在唱到哪一句。先说清楚你将得到什么多屏听歌的人大概都有同一种别扭Folia 窗口开在副屏或者干脆被最小化想确认一句歌词、或者想暂停就得切过去操作一遍。lia.lines 解决的就是这件事顶栏常驻一行歌词跟随 Folia 的播放内容自动滚动更新和 Folia 内部的逐字时间轴同源顶栏直接控制播放暂停 / 播放不用再打开主窗口未播放时不空着Folia 没有在播歌时插件退化为一个简易 MPRIS 媒体信息组件显示当前媒体元信息也就是说桌面顶栏从「状态栏」升级成了「歌词栏」成本只是装一个插件、开一个开关。folia-v1-lyric 接口数据是怎么流到顶栏的lia.lines 不依赖任何额外服务它的全部数据来源是 Folia 桌面端内置的一个本机 HTTP 端点GET http://127.0.0.1:32109/v1/lyric这个端点只监听回环地址127.0.0.1、固定端口32109、无需鉴权。服务器在局域网里看不到它天然安全客户端拿到的也不是什么私有协议就是一份普通的 JSON 歌词快照。整条链路非常干净Folia 播放歌曲 → 内置歌词接口发布快照 → lia.lines 轮询读取 → 顶栏渲染返回的数据做了「脱敏」处理接口实现位于 electron/lyricApi.cjs。Folia 内部渲染用的歌词对象其实很「重」——带着renderHints、分块、视觉效果、内部 ID 等字段这些对桌面插件毫无意义还可能随版本漂移。lyricApi.cjs里的sanitizeLyricData会把它们全部剥掉只保留一份稳定的公开字段字段单位说明offset毫秒你在歌词面板里为这首歌设置的时间偏移正值延后、负值提前lines秒按时间排序的歌词行含text/startTime/endTime/ 逐字wordswordByWord—true为数据源原生逐字时间false表示 Folia 根据行时间合成的估算逐字时间title/artist—可选歌词数据附带时才有这里有一个值得注意的细节offset是专门给外部消费者准备的。lia.lines 这类客户端拿不到 Folia 内部的当前播放时间靠它来校正「歌词时间轴 vs 实际进度」的偏差你在应用里调过偏移顶栏显示会自动跟着校正口型对不上基本不会出现。前端侧src/hooks/useLyricApiPublisher.ts 负责把渲染进程里的歌词对象和偏移量同步发布给这个接口——切歌、歌词加载完成、调整偏移时数据才更新而不是跟着播放进度逐帧刷所以外部轮询的开销很低。快速配置三步把歌词挂上顶栏第 1 步在 Folia 中启用歌词接口打开 Folia 桌面端进入设置 → 连接与集成 → 歌词接口 → 启用歌词接口这个设置会被持久化之后每次启动 Folia 都会自动尝试监听32109。不想翻设置页的话也可以直接打开命令面板执行「歌词接口」命令一键切换命令注册见 src/components/command-palette/commands/settingsCommands.ts。第 2 步安装 lia.lines 插件omarchy 用户打开官方插件市场搜索lia.folia-lyrics一键安装其他 QuickShell 环境手动部署官方插件仓库 lia.lines按仓库说明放到你的插件目录插件本身无需写任何代码装完即出现在顶栏配置里。这个集成的官方说明在技术文档 docs/technical.md 的「Quickshell 歌词插件」一节。第 3 步验证接口与顶栏效果终端里敲一下确认接口活着curl http://127.0.0.1:32109/v1/lyric有歌词时返回歌词 JSON 快照没在播放 / 歌词加载中 / 歌曲无歌词时返回 JSONnull这是正常的200响应不代表故障顶栏随后自动开始滚动歌词播放状态、歌词文本跟随 Folia 更新。常见故障排查现象原因与处理顶栏一直不显示歌词先确认歌词接口开关已打开再确认当前歌曲确实有可用歌词设置页提示「接口不可用」32109被别的程序占用了。释放端口后在设置里关闭再重新启用接口curl返回null或顶栏空白正常没在播放、歌词还在加载、或这首歌没有歌词顶栏歌词和口型对不上检查 Folia 里的歌词偏移接口offset字段携带该值插件会自行校正curl直接连接失败接口没启用、Folia 没运行或者请求了错误地址务必用完整127.0.0.1别依赖localhost的解析结果进阶自己动手写一个消费者理解了这个接口之后你会发现它其实是个面向本机程序的「歌词只读 API」lia.lines 只是第一个消费者。接口约定写在 docs/lyric-api.md里面有完整的字段表、响应示例和多语言调用示例。几个写第三方客户端时的要点轮询即可500–1000 ms 一次足够数据只在切歌、歌词加载、调整偏移时变化高频轮询纯属浪费时间单位别混offset是毫秒行 / 逐字的startTime/endTime是秒自己按播放时间匹配歌词时用播放时间(秒) - offset / 1000wordByWord: false是估算值表示逐字时间由行时间合成不要当原生精确逐字时间用别把它转发出去无鉴权接口的安全性建立在「只监听回环」上不要经端口转发或反向代理暴露到不可信网络小结Folia 歌词接口 lia.lines 这套组合的妙处在于几乎零成本不动 Folia 本体、不占窗口焦点只是「开了一个本机端口 装了一个插件」顶栏就常驻了一行和逐字动画同源的歌词。对 omarchy 4 / QuickShell 用户来说这可能是桌面歌词方案里最轻的一条路而如果你愿意多花十分钟读一遍 docs/lyric-api.md同一份 JSON 还能喂给你自己的任何本地小工具。【免费下载链接】folia-major专注于绚丽的歌词动画效果的本地音乐/navidrome/第三方多平台在线音乐播放器项目地址: https://gitcode.com/GitHub_Trending/fo/folia-major创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考