Files
obs-lowerthird/README.md
T
2026-11-11 21:40:57 +08:00

12 KiB
Raw Blame History

OBS Lower Third · LRC 字幕

OBS 浏览器源用的「下三分之一条 + LRC 字幕」管理系统。

  • 外观预设:自定义 HTML/CSS 模板,用 {{字段名}} 占位。
  • 内容预设:把具体文字填入外观预设,激活后显示在 OBS 中。
  • LRC 字幕(新增):导入 LRC、过滤版权/制作信息、自由选择起止句,打点后第一句立即出现,后续严格按 LRC 时间轴显示。
  • 持久化:所有预设、LRC、设置保存在 data/ 下的 JSON 文件里,不再写死在源代码中。

快速开始

npm install
npm start

默认端口 30001:

页面 地址 用途
管理面板 http://localhost:30001/manage.html 外观 / 内容 / LRC 预设,打点控制
OBS 浏览器源 http://localhost:30001/widget.html 添加到 OBS Browser Source
旧版管理页 http://localhost:30001/admin.html 兼容保留,仅管理外观预设

OBS 中添加 浏览器源(Browser Source),URL 填 http://127.0.0.1:30001/widget.html,建议分辨率与画布一致,勾选「关闭源时关闭页面」可选。页面背景透明,字幕和下三分之一条会直接叠加到画面上。

环境变量:

变量 默认值 说明
PORT 30001 HTTP / WebSocket 端口
DATA_DIR ./data 运行时数据目录

LRC 字幕使用流程

进入管理面板的 「LRC 字幕」 标签页。

1. 导入 LRC

  • 点击「导入 .lrc 文件」,或直接把 LRC 文本粘贴到文本框。
  • 支持标准格式:[mm:ss.xx]、[mm:ss.xxx]、[mm:ss],以及一行多个时间戳([00:12.00][00:45.00]副歌)。
  • 支持增强型逐字时间戳 <00:01.00>:配合「逐字点亮」开关,文字会按标签逐字/逐词点亮;没有增强标签的行整句显示。
  • 自动识别 [ti:] [ar:] [al:] [by:] [offset:] 等元数据并单独展示。

2. 过滤版权信息

默认开启「过滤版权 / 制作信息行」,命中关键词(作词、作曲、编曲、制作人、出品、录音、混音、©、℗、lyrics by …)的行会被剔除,并在「已过滤行」里列出被剔除的内容和原因。

  • 关键词可以在下拉框中自由增删,也可一键恢复默认。
  • 关闭「过滤版权 / 制作信息行」可显示全部时间轴行。
  • 可关闭「忽略无时间戳行」保留没有时间戳的行用于检查。

3. 自由选择范围

  • 起始句 / 结束句:从过滤后的歌词行中选择,显示原始 LRC 时间与歌词内容。
  • 「全选」恢复整首。
  • 选中的范围会即时计算「最终字幕 N 句 / 时长」。
  • 改动 LRC 文本或过滤条件时,范围会自动重置为全部,避免索引错位。

4. 时间对齐

  • 自动偏移:打点开始后,把「起始句」当作 0 点,后续句子按 LRC 原始间隔出现。因此打点瞬间第一句立即显示,不需要手动对齐第一句。
  • 手动偏移:整体提前/延后(毫秒),正数 = 延后。LRC 文件自带的 [offset:] 也会自动生效(正数 = 提前)。
  • 末句停留:最后一句显示多久(默认 4000 ms)后自动隐藏。
  • 首句延迟:播放控制栏中的运行参数,打点后延迟 N 毫秒再开始整条时间轴(默认 0)。

5. 打点播放

在「LRC 字幕」页顶部点击 ▶ 打点开始。

  • 快捷键(焦点不在输入框时):
    • L:打点开始
    • J:暂停 / 继续
    • K:停止
  • 支持暂停、继续、停止;管理页会实时显示当前句、下一句和进度。
  • 左侧预设列表中的「打点」按钮可直接用已保存的配置开始。
  • 编辑中的修改不需要先保存也可以打点(使用当前编辑器配置);点击「保存」后才会持久化。

6. 字幕样式

内置字幕样式编辑器,全部按预设持久化:

  • 位置(顶部/居中/底部)、水平对齐。
  • 入场动画:淡入 / 上滑 / 缩放 / 模糊 / 弹跳 / 自定义(写 CSS) / 无。
  • 入场时长(enterDurationMs):让模糊、缩放等入场动画放慢,默认 300ms,模糊入场一般 1200–1800ms 更舒服。
  • 入场模糊半径(blurPx):模糊入场与模糊出场共用的最大模糊半径,默认 10px。
  • 入场后回缩:入场动画播完后,文字在 shrinkDurationMs 内缓慢缩放到 holdShrinkTo 倍(1 = 不回缩)。例如 0.94 + 3000ms 就是「缓缓回缩」。控件里有「轻微回缩」快捷按钮。
  • 自动适配单句时长:入场时长 + 回缩时长会与「到下一句的间隔」自动协商。间隔不够时,入场最多占 45%,回缩占用剩余时间(至少 120ms),保证每句都能完整播完入场→回缩,不会出现「回缩刚开始就跳到下一句」。最后一句按「末句停留」计算。
  • 出场动画(outro):整段字幕结束时播放,可选 淡出 / 模糊消散 / 下滑淡出 / 上浮淡出 / 缩小淡出 / 自定义 / 无,配套 出场时长(outDurationMs,默认 260ms)。手动点「停止」也会走完整的出场动画。
  • 字号、字重、字间距、行高、文字颜色。
  • 字体:常用字体快捷选择 + 自定义 CSS font-family。注意 OBS 所在电脑需要安装对应字体,否则回退到系统字体。
  • 背景:支持 rgba() / transparent,可用「显示背景」开关一键禁用(保留颜色配置)。
  • 文字阴影:可编辑具体阴影,可用「文字阴影」开关一键禁用。
  • 「显示下一句」开关:关闭后不再提前显示下一句提示。
  • 「逐字点亮」开关 + 「未唱文字颜色」:增强型 LRC 逐字显示,唱到的字变为主色,未唱的字保持半透明;当前字额外带 .is-current 类可供自定义 CSS 使用。
  • 一行多时间戳(副歌复用)或同一时间点多行(双语)会自动退回整句显示,避免逐字时间错位。
  • 内边距、圆角、最大宽度、距画面边缘距离、下一句缩放/颜色。
  • 自定义 CSS:见下一节。

每条字幕的生命周期是三个阶段,可以用 CSS 钩子分别定制:

阶段 状态类 默认行为
入场 .lrc-state-entering 播放所选入场动画,时长 = enterDurationMs
停留 .lrc-state-hold 保持可读,同时在 shrinkDurationMs 内回缩到 holdShrinkTo
出场 .lrc-state-leaving + .lrc-out-* 播放所选出场动画,时长 = outDurationMs,结束后隐藏

右侧有 16:9 样式预览和「试播本段」,可直接看到入场 → 回缩 → 出场的完整时序;「循环」开着时会反复重播,方便调时长。

7. 自定义动画 / 修饰(CSS)

每个 LRC 预设都带一个「自定义 CSS / 自定义动画」输入框,内容会同时注入管理页预览和 OBS 浏览器源。可用的选择器:

选择器 说明
.lrc-layer 整块字幕层(可用来做背景、发光、定位微调)
.lrc-box 字幕盒(背景、边框、圆角、发光、滤镜)
.lrc-text 当前句文字
.lrc-next 下一句提示
.lrc-word 逐字模式下的每个字/词
.lrc-word.is-pending 还没唱到的字
.lrc-word.is-sung 已经唱到的字
.lrc-word.is-current 当前正在唱的字(用于高亮/放大/发光)
.lrc-anim-custom .lrc-text 选择「自定义」入场动画时的动画目标

示例:

/* 自定义弹跳入场:入场动画选择「自定义」 */
@keyframes myBounce {
  0%   { opacity: 0; transform: translateY(26px) scale(0.9); }
  60%  { opacity: 1; transform: translateY(-6px) scale(1.03); }
  100% { opacity: 1; transform: translateY(0) scale(1); }
}
.lrc-layer.lrc-anim-custom .lrc-text {
  animation: myBounce 0.55s cubic-bezier(0.2, 0.9, 0.3, 1.2) both;
}

/* 逐字发光 */
.lrc-layer .lrc-word.is-sung {
  text-shadow: 0 0 10px rgba(255, 209, 102, 0.95),
               0 0 24px rgba(255, 92, 141, 0.55);
}
.lrc-layer .lrc-word.is-current {
  color: #ffd166 !important;
}
  • 管理页提供「+ 霓虹发光」「+ 渐变文字」「+ 描边文字」「+ 逐字发光」「+ 弹跳入场」「+ 擦除入场」等一键片段。
  • 背景、颜色、阴影等由内置控件写成内联样式,若要覆盖它们请使用 !important。
  • 为了不影响管理页其他区域,建议所有选择器都以 .lrc-layer 开头;预览容器额外带有 .lrc-preview-layer 类,可写预览专用规则。

持久化

运行时数据全部位于 data/(已被 .gitignore 忽略):

data/
├── appearance-presets.json   # 外观预设(HTML 模板)
├── content-presets.json      # 内容预设
├── lrc-presets.json          # LRC 预设(LRC 原文、过滤条件、范围、样式)
└── settings.json             # 全局设置(自动隐藏时长等)

设计要点:

  • 首次启动自动生成:如果文件不存在,用 seed/ 中的示例数据初始化;之后不再覆盖。
  • 原子写入:先写临时文件再 rename,进程异常不会留下半截 JSON。
  • 损坏自愈:文件无法解析时备份为 *.corrupt-<时间戳>.bak,再用种子数据重建,不会导致服务起不来。
  • 带 schemaVersion:每个文件带版本号,便于后续迁移。
  • 输入校验:所有写入都会经过 lib/lrc.js / lib/models.js 的规整和范围限制。
  • 源码不存业务数据:示例库只放在 seed/,用户数据只放 data/。想恢复默认,停止服务后删除 data/ 再启动即可。

如果要迁移/备份,直接复制 data/ 目录即可。


API 概览

原有接口保持不变,新增 LRC 相关接口:

方法 路径 说明
GET /api/presets 全部外观/内容/LRC 预设 + 运行状态
GET /api/lrc-presets LRC 预设列表
POST /api/lrc-presets 新建 LRC 预设
PUT /api/lrc-presets/:id 更新 LRC 预设
DELETE /api/lrc-presets/:id 删除 LRC 预设(如正在播放会停止)
POST /api/lrc/parse 仅解析/预览:{ source, filters, range, offsetMs, tailMs }
POST /api/lrc-presets/:id/play 打点开始:{ leadInMs, overrides }
POST /api/lrc/pause 暂停
POST /api/lrc/resume 继续
POST /api/lrc/stop 停止
GET /api/lrc/state 当前 LRC 播放状态
GET /api/health 健康检查

WebSocket 消息:

  • activePreset:下三分之一条的当前状态(与原版一致)。
  • lrcState:LRC 播放状态(cues、锚点时间、暂停状态、样式)。
  • clock:客户端时钟校准(管理页/OBS 与服务器时间对齐,保证字幕切换准确)。

项目结构

server.js               Express + WebSocket 服务、API
lib/
  store.js              通用 JSON 持久化(原子写、损坏恢复、schemaVersion)
  lrc.js                LRC 解析、版权过滤、时间轴构建、预设校验
  models.js             外观/内容预设与设置的校验
  seed.js               首次启动种子数据加载
seed/
  defaults.json         默认预设元数据
  default-appearance.html
  default.lrc
public/
  manage.html           管理面板(React + antd)
  widget.html           OBS 浏览器源(下三分之一条 + LRC 字幕层)
  lrc.css               LRC 动画 / 逐字样式(管理页预览与 widget 共用)
  admin.html            旧版管理页
tests/                  单元测试(LRC / 存储)
data/                   运行时数据(自动生成,不提交)

测试

npm test

覆盖 LRC 时间戳解析、元数据、版权过滤、范围/偏移、增强型逐字片段、双语同时间戳合并、样式开关、自定义 CSS、持久化写入/重载、损坏恢复等。

说明

  • 管理页与 OBS 浏览器源通过 WebSocket 实时同步;断线后都会自动重连并重新同步状态。
  • 字幕播放的时间轴在服务器构建,OBS 端通过时钟校准在本地调度,网络抖动不会累积成音画不同步。
  • 下三分之一条与 LRC 字幕是独立图层,可以同时显示;「清空显示」会同时隐藏两者。