Files
obs-lowerthird/README.md
T
2026-10-24 10:54:52 +08:00

233 lines
11 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# OBS Lower Third · LRC 字幕
OBS 浏览器源用的「下三分之一条 + LRC 字幕」管理系统。
- **外观预设**:自定义 HTML/CSS 模板,用 `{{字段名}}` 占位。
- **内容预设**:把具体文字填入外观预设,激活后显示在 OBS 中。
- **LRC 字幕(新增)**:导入 LRC、过滤版权/制作信息、自由选择起止句,打点后第一句立即出现,后续严格按 LRC 时间轴显示。
- **持久化**:所有预设、LRC、设置保存在 `data/` 下的 JSON 文件里,不再写死在源代码中。
---
## 快速开始
```bash
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)** / 无。
- 字号、字重、字间距、行高、文字颜色。
- 字体:常用字体快捷选择 + 自定义 CSS `font-family`。注意 OBS 所在电脑需要安装对应字体,否则回退到系统字体。
- 背景:支持 `rgba()` / `transparent`,可用「显示背景」开关一键禁用(保留颜色配置)。
- 文字阴影:可编辑具体阴影,可用「文字阴影」开关一键禁用。
- 「显示下一句」开关:关闭后不再提前显示下一句提示。
- 「逐字点亮」开关 + 「未唱文字颜色」:增强型 LRC 逐字显示,唱到的字变为主色,未唱的字保持半透明;当前字额外带 `.is-current` 类可供自定义 CSS 使用。
- 一行多时间戳(副歌复用)或同一时间点多行(双语)会自动退回整句显示,避免逐字时间错位。
- 内边距、圆角、最大宽度、距画面边缘距离、下一句缩放/颜色。
- **自定义 CSS**:见下一节。
右侧有 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` | 选择「自定义」入场动画时的动画目标 |
示例:
```css
/* 自定义弹跳入场:入场动画选择「自定义」 */
@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/ 运行时数据(自动生成,不提交)
```
## 测试
```bash
npm test
```
覆盖 LRC 时间戳解析、元数据、版权过滤、范围/偏移、增强型逐字片段、双语同时间戳合并、样式开关、自定义 CSS、持久化写入/重载、损坏恢复等。
## 说明
- 管理页与 OBS 浏览器源通过 WebSocket 实时同步;断线后都会自动重连并重新同步状态。
- 字幕播放的时间轴在服务器构建,OBS 端通过时钟校准在本地调度,网络抖动不会累积成音画不同步。
- 下三分之一条与 LRC 字幕是独立图层,可以同时显示;「清空显示」会同时隐藏两者。