An agent skill and Python/JavaScript toolkit for continuous score-synchronized videos, structural navigation, and matching covers, built from MusicXML/MXL, an original score PDF, and a real recording.
中文说明如下。Music engraving is powered by Verovio. Code uses the MIT license; bundled Source Han Serif fonts retain their SIL OFL license.
- 单列流动原生乐谱、固定蓝色时间线、持续音符高亮。
- 真实录音多阶段对齐、装饰音处理、局部约束和音频诊断。
- 稳定声部集合、平滑布局、滑动换章、持续材料配色。
- 双层曲式进度条、中文结构提示。
- 可选 PDF 导赏：增量右栏、持久关键词色、固定谱面标签、协同走线与原生对照谱例。
- 完整材料染色、紧凑纵向排版和基于实际可见性的标签/连线寿命。
- 2160p60 HEVC 4:4:4 10-bit MOV、无损音频、内嵌章节和B站章节文本。
- 当前作品真实谱面生成16:9和4:3封面。
- 审片、冻结、分块续渲、缓存清理和组件指纹。
仓库只包含通用工具、样式、字体和合成测试，没有具体作品的原谱、转录、音频、成片、时间锚点或历史项目配置。
这不是任意录音的一键完美对齐器。PDF校勘、演奏路线、曲式、配色和实际录音复核仍由agent或人工完成。相同原料重新分析也不保证重现另一个项目的全部人工判断；精确重放依赖该项目保存的已审数据。
| 组件 | 要求 |
|---|---|
| 系统 | POSIX；已验证锁定依赖可解析于Apple Silicon macOS 13+、Linux x86_64 |
| Python | 3.14，推荐uv管理独立环境 |
| Node.js | 22或以上，无npm依赖 |
| FFmpeg/FFprobe | FFmpeg含libx265及yuv444p10le支持 |
| 浏览器 | Chrome/Chromium，可用SCORE_SYNC_CHROME指定 |
| 字体 | 随包思源宋体2.003，保留原许可 |
当前不支持原生Windows；WSL和Intel Mac未完成安装/渲染验证。Intel Mac锁定依赖缺少部分wheel，不能承诺直接安装。依赖解析验证不等于跨平台完整渲染验证。
先安装uv、Node.js、FFmpeg及Chrome/Chromium，再克隆：
git clone https://github.com/tofucurd/score-sync-video.git
cd score-sync-video
python3 scripts/bootstrap.py
.runtime/bin/python scripts/score_sync.py doctorbootstrap建立仓库内.runtime，不改系统Python。doctor只检查环境，不渲染。浏览器不在默认位置时设置：
export SCORE_SYNC_CHROME=/absolute/path/to/chromium作为agent skill使用时，把仓库放进支持SKILL.md的技能目录，或让agent读取SKILL.md。例如放到~/.codex/skills/score-sync-video后用$score-sync-video调用；已有同名目录时不要直接覆盖。
.runtime/bin/python scripts/score_sync.py init \
--project /absolute/my-project/project.json \
--score /absolute/materials/score.mxl \
--pdf /absolute/materials/original.pdf \
--audio /absolute/materials/performance.flac \
--title "作品名称" --composer "作曲家"
.runtime/bin/python scripts/score_sync.py prepare --project /absolute/my-project/project.json
.runtime/bin/python scripts/score_sync.py align --project /absolute/my-project/project.json多个乐章重复提供--score和--audio，PDF可共用。项目建在仓库之外，原素材保持只读。随后由agent核对原谱和完整录音、修正候选、补全结构/颜色/封面及真实审核记录。
.runtime/bin/python scripts/score_sync.py preflight --project /absolute/my-project/project.json
.runtime/bin/python scripts/score_sync.py preview --project /absolute/my-project/project.json三名真实审阅者复核整套预览，用户确认后记录实际原话并渲染：
.runtime/bin/python scripts/score_sync.py approve \
--project /absolute/my-project/project.json --statement "用户实际确认这套预览的原话"
.runtime/bin/python scripts/score_sync.py render --project /absolute/my-project/project.json不能伪造review JSON跳过工作。暂停后用resume，状态用status；clean只列缓存，clean --apply才删除可重建缓存。默认保留25GiB可用空间。
.runtime/bin/python -m pytest tests -q
node --check scripts/browser_render.mjs
node --check scripts/browser_guide.mjs
node --test tests/test_guide_runtime.mjs
python3 scripts/check_package.py测试使用合成数据和短合成音频，不渲染完整视频。组件变更后运行python3 scripts/release_manifest.py刷新指纹。CI验证依赖安装、测试、JS语法和包内容，不代替实际作品同步验收。
代码和原创文档使用MIT。Verovio是LGPLv3外部依赖，思源宋体使用SIL OFL 1.1。第三方软件及用户提供的乐谱、录音不受项目MIT许可重新授权，详见第三方声明。
Optional vocal sidebars and native material-region coloring are bundled and wired into the renderer. See presentation layers for full-movement inputs, the stable-layout compiler, source bindings and review limits. No work-specific lyrics, translations or theme maps are distributed.
Release 1.1.0 adds an opt-in guide compiler and the production-derived guide renderer. It contains reusable algorithms, not the original work’s commentary or annotation map. The new integration has lightweight checks only; see the validation record before adopting it for a new work.