Folia PlayerCap 教程：逐字歌词动画零门槛接入 OBS 直播画面

Folia PlayerCap 教程：逐字歌词动画零门槛接入 OBS 直播画面

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

Folia 内置 PlayerCap 源，把逐字歌词动画变成一页透明背景的网页，直接喂给 OBS 浏览器源。不用窗口捕获、不用截图，粘一条 URL，直播画面就跟着音乐逐字发光。

为什么选 PlayerCap 而不是窗口捕获

做过播放器上屏的人大概都被窗口捕获坑过：分辨率缩放后动画发糊，主题随封面换色时颜色还会"冻"在半路。

PlayerCap 走的是另一条路——Folia 不交给 OBS 一帧像素，而是给一个活网页：透明背景、歌词逐词动、配色跟着封面实时派生。页面永远和音乐同步，因为渲染源头就是同一份事件流。

工作原理：一条不断线的 WebSocket 数据流

Folia 先请求localhost:8765的/service-status接口，拿到这台 PlayerCap 服务支持的播放器列表（见连接层实现），然后建立一条 WebSocket 长连接——约等于一条不挂断的电话线，歌曲信息、逐句逐字歌词、播放进度、暂停恢复都顺着它推过来。

这些事件在 playerCapSession 里被归约成一份干净的播放状态，页面层通过 usePlayerCapSource 消费，再渲染成 OBS 专用舞台页，配色按封面自动算。整个过程不截你的窗。

三步配置：从设置面板到 OBS 浏览器源

在设置里找到舞台源：打开 设置 → 集成，在 Web 舞台源下拉里选中Nexus PlayerCap。播放界面左下角会立刻切进舞台模式，这就是效果预览，相当于本地小样。

把连接参数填对：PlayerCap 地址留空即走默认localhost:8765，失焦自动保存并重连。播放器选"跟随默认"就跟着服务当前活跃的那个走；选项列表要等连接建立后才可点。时间轴默认play_time，忽略播放器清除默认开启。

把地址交给 OBS：点设置面板里的"复制 OBS URL"，在 OBS 新建浏览器源、粘贴即可。cfg参数携带外观短码；只有当你把地址、播放器等改成非默认值时，URL 才会附带nxpcPlayer、nxpcBasis、nxpcSticky之类的连接参数，默认配置下 URL 干干净净（构建逻辑见 currentObsUrl）。

细节怎么调：主题模式与时间轴对齐

• 主题模式：static把当前主题烧进 URL，OBS 里颜色固定；builtin（默认）按封面为每首歌派生配色；ai在 builtin 基础上每首歌调 AI 重新生成主题。
• 时间轴对不齐：逐字时机偏了的话，切到timestamp走原始 on-beat 时间轴，再用全局歌词偏移手动微调；play_time则沿用 PlayerCap 各播放器调教好的提前量。
• sticky 开关：想暂停休息时歌词留在直播画面就保持"忽略播放器清除"开启，关掉则暂停后舞台随之清空。

这些设置都持久化在本地（见 useStageSettingsStore），改完地址连接会自动重启，不用手动重配。

常见问题：连不上、没歌词、下拉是灰的

先开 OBS 还是先开 PlayerCap？不用纠结，探测和重连每 2 秒自动重试，而且内部代号机制保证你快速切换地址时不会留下并发连接。

连接成功却没歌词？纯音乐或无歌词曲目的正常状态，换一首有歌词的即可，界面上会显示"已连接，等待歌词"。

掉线弹了提示？那只是通知，后台重连不会停，无需手动干预。

改了地址没反应？地址是失焦才保存的，填完点一下别处才生效。

一条 URL，就把逐字歌词动效从本地播放窗原封不动搬进了直播画面。下次开播前，记得先给 OBS 加一个浏览器源 🎧

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