VJ Studio

浏览器端歌词可视化与舞台背景合成工具。导入音频和歌词后，可校准时间轴、选择字幕动效与背景，在浏览器中实时预览并导出项目。

推荐使用构建后的单文件版本：outputs/VJ-studio-optimized.html。 根目录的 VJ-studio.html 是参考页面，不是推荐的独立发布入口。

功能

• 导入浏览器支持的音频文件，界面主要面向 MP3、WAV。
• 同时导入音频和 .lrc / .txt 歌词文件。
• 解析标准 LRC：时间标签、[ti:]、[ar:]、[offset:]、一行多个时间标签和毫秒时间。
• 尝试读取内嵌歌词：MP3 ID3v2 USLT / SYLT，以及 MP4 ©lyr 标签。
• 通过 LRC Lib 搜索在线歌词，选择结果后再应用。
• 在时间轴中增删、改写、拖动排序歌词；提供逐行调时和全局偏移。
• 设置提前显示时间，范围 0 至 2 秒，默认 0.5 秒。
• 提供 8 个内置背景、14 套字幕动效、字体和颜色设置，以及 16:9、9:16、1:1 画幅。
• 支持上传不超过 50 MB 的 MP4 循环背景。
• 浏览器自动保存工程，可导出和导入 .vjproj 工程文件。
• 提供舞台预览、音频播放控制和页面内 MP4 导出入口。

快速开始

直接使用发布版

1. 下载仓库，或下载发布包并解压。
2. 使用最新版 Chrome 或 Edge 打开 outputs/VJ-studio-optimized.html。
3. 在首页选择音频，或同时选择音频和歌词文件。
4. 按页面步骤处理歌词、校准时间、配置画面，再进入动态合成预览。

发布版已将核心页面样式、脚本和内置媒体资源打包到一个 HTML 文件中。双击可直接尝试；如果浏览器对本地文件的导入、联网请求或媒体访问有限制，请用本地 HTTP 服务打开该文件。

PowerShell 示例：

cd "C:\path\to\vi-vjstudio"
npx.cmd serve .

随后打开终端输出的本地地址，并访问 /outputs/VJ-studio-optimized.html。

本地开发

需要 Node.js 18 或更高版本。Windows 环境使用 npm.cmd，避免 PowerShell 执行策略拦截 npm.ps1。

git clone https://github.com/glaypan/vi-vjstudio.git
cd vi-vjstudio
npm.cmd install
npm.cmd run build

构建完成后打开：

outputs/VJ-studio-optimized.html

推荐工作流

1. 导入音频

从首页选择音频文件。也可以一次选择一个音频和一个 .lrc 或 .txt 文件，应用会将歌词直接载入时间轴。

建议先使用本地 MP3 或 WAV 完成工程。具体可用格式由浏览器和系统解码器决定，不能保证所有音频容器或编码都可用。

2. 获取歌词

可按以下优先顺序使用：

1. 同时导入本地 LRC。
2. 导入音频后尝试读取内嵌歌词。
3. 在歌词页输入歌名和歌手，搜索 LRC Lib 结果并选择合适版本。
4. 粘贴歌词文本后手动编辑和标记时间。

LRC 示例：

[ti:示例歌曲]
[ar:示例歌手]
[offset:0]
[00:00.00]第一句歌词
[00:05.20]第二句歌词
[00:09.80][00:14.50]重复的一句

内嵌歌词属于可选元数据：不同制作软件写入的标签可能不同，找不到歌词并不表示音频文件损坏。在线搜索需要网络连接，结果数量、版权可用性、接口响应和跨域策略均由 LRC Lib 服务决定。

3. 校准时间轴

播放音频，观察当前高亮行并做校准：

• 使用单行时间输入和微调按钮处理局部误差。
• 使用全局时间轴平移统一前移或后移歌词。
• 通过提前显示设置，让下一句在实际唱到前出现。
• 拖动行项目调整显示顺序，或添加、删除、直接编辑歌词。

“智能对齐”仅用于生成初始时间建议，不是语音识别或精确强制对齐。不同歌曲的前奏、停顿、演唱速度、人声与伴奏比例都会造成明显误差。导出前必须逐段试听并手工校正。

4. 合成画面

在“动态合成”页中：

1. 从背景列表选择内置背景，或上传自己的循环 MP4 背景。
2. 选择字幕动效；竖排样式适合短句和中文歌词，使用前应在预览中检查可读性。
3. 在字幕样式区调整字体、字号比例、主色和强调色。
4. 选择 16:9、9:16 或 1:1，再检查字幕不会超出安全区域。
5. 播放完整歌曲，确认每段歌词、背景和画幅符合目标屏幕。

字体效果依赖系统已安装字体和浏览器能力。若某个字体在目标电脑上不可用，浏览器会回退到其他字体，字宽、换行和位置可能变化。

5. 导出

在导出前完成完整预览，保证音频、歌词和背景均已重新加载。使用页面的导出入口生成视频时，请保持页面打开、不要让电脑休眠，并优先使用桌面版 Chrome 或 Edge。

视频编码、硬件加速、可用编解码器和最终文件兼容性由浏览器、操作系统和设备决定。请先用一段短音频试导出，再进行完整歌曲导出。

工程保存与恢复

自动保存

应用会把当前工程自动保存在本机浏览器的 IndexedDB 中，键名为 vj-studio-project-v3。重新打开同一浏览器和同一站点/本地文件上下文时，通常可以恢复最近编辑状态。

清除浏览器站点数据、无痕模式、换浏览器或换电脑，都可能使自动保存不可用。因此重要工程应导出 .vjproj 备份。

导出和导入 .vjproj

点击“保存工程”导出工程文件，点击“打开工程”导入。

工程文件保存歌词、时间、字幕样式、背景选择及其他工程元数据；不包含原始音频文件，也不包含自定义上传的背景媒体文件。在另一台电脑或重新打开工程后，需要重新导入本地音频和自定义背景，然后进行预览确认。

浏览器兼容性

• 推荐：桌面版 Chrome、Microsoft Edge 最新稳定版。
• 手机浏览器、Safari 和旧版浏览器可能在本地文件访问、音频解码、视频编码或导出方面存在差异。
• 本地双击运行通常适合试用；若在线歌词搜索或文件导入受浏览器策略影响，请用本地 HTTP 服务启动。
• 内置资源已打包进发布版；选择系统字体或使用在线歌词时，仍可能受本机字体和网络环境影响。

开发、构建与测试

安装依赖后可执行：

# 单元测试
npm.cmd test

# TypeScript 类型检查
npx.cmd tsc --noEmit

# 构建单文件发布版
npm.cmd run build

# Playwright 浏览器端到端测试
npx.cmd playwright test

npm.cmd run build 会生成 outputs/VJ-studio-optimized.html。不要直接手工修改构建产物；应修改 src/ 中源码后重新构建。

目录说明

.
|- src/                         源码：界面、领域逻辑、样式和内置资源
|- tests/                       单元测试与浏览器测试
|- scripts/build-single-html.mjs 单文件构建脚本
|- outputs/                     构建输出
|  `- VJ-studio-optimized.html  推荐的独立使用入口
|- docs/                        产品说明、设计和实施记录
|- VJ-studio.html               参考页面，不作为推荐发布入口
`- package.json                 开发命令与依赖定义

已知限制

• 智能对齐误差可能较大，不能替代人工逐段校准。
• 部分竖排模板在特定歌词长度、字号或背景下可读性较弱，必须通过实际预览确认。
• 字号改变后，当前版本没有通用的自由拖拽字幕定位功能；应通过模板、画幅、字号和颜色调整得到合适构图。
• 某些竖排动效在特定背景或颜色组合下可能不易看见歌词，导出前要完整播放检查。
• 自定义背景仅支持页面定义范围内的 MP4 文件，且大小不超过 50 MB。
• 内嵌歌词读取仅覆盖已实现的标签格式，不保证所有 MP3、MP4 或第三方标签工具生成的文件都能识别。

隐私与网络

本地导入的音频、歌词和工程操作在浏览器中执行。在线歌词搜索会向 LRC Lib API 发送用户输入的歌名与歌手信息。不要在公共电脑上保留敏感工程；完成后可导出 .vjproj，再清除浏览器站点数据。

License

仓库当前未附带许可证文件。发布、复制、修改或商用前，请由仓库所有者补充明确的许可证条款。