feat: Lyrics
This commit is contained in:
1 parent
6ed3e169e4
commit
82b1fa0d47
17 files changed
+3863
-283
No files matched your search
@@ -0,0 +1,232 @@
|
||||
# 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 字幕是独立图层,可以同时显示;「清空显示」会同时隐藏两者。
|
||||
Reference in new issue
Block a user