项目状态 - ZLHad/OpenVideoHarness GitHub Wiki
English · 中文
截至 2026-10-03，合并到 PR #50 为止，另含介绍片 v5。最新版本是 v0.2.1（2026-09-30），main 上还有一长串尚未发版的改动。每一处改动都记在 CHANGELOG.md，接下来的计划见路线图。
能用、测过的
| 部分 | 现状 |
|---|---|
| 工作流 | CLAUDE.md 路由表、9 份类型文档（09 实验性）、playbook 00–12、11 个模板、关卡 ① 的立意卡、标出底线条目的 20 条清单、8 个维度的打分层、带决定优先审阅页的导演模式、一开始就定的规格（字号下限按在哪看分档）、24 个镜头配方和 8 条全片骨架。五支 showcase 都是 agent 只读这些文档做出来的。 |
| 命令行 | bin/vh 以及 bin/vh help 列出的命令。每个 PR 都会在 Linux 和 macOS 上跑 tools/ci.sh：检查 shell、Python、JS 语法，禁止只在单一平台存在的命令，核对文档和命令行是否一致，对 help、每个命令的 -h、types、effort、style list、new（含 --watch、--res 和风格参考）、style apply、install-skill、tts 的依赖选择、mux、gif、recipes、storyboard、review 和 readcheck 做冒烟测试（分镜页第二次渲出来必须逐字节相同），并静态扫描每个 Blender 风格场景、检查它的 GPL 文件头。 |
| 配音 | 端到端测过：qwen（中英）、say、edge（英文）、gemini（中英，2026-09-30 实测，包括双人对话、整段合成和设计音色），以及 --align gemini。gemini-lite 走同一个接口，但没有单独的实测记录。 |
| 字幕、配乐、音效、混音、合成、质检 | 端到端测过。showcase 00–03 的四支片子和 31 个样片都用 profile 混音，WAV 和 mp4 都过了质检：没有数字静音，每个卡点在 1 帧以内，−14 LUFS，AAC 编码之后真峰值低于 −1.5 dBTP，每次重建字节相同。介绍片 v5 用 promo profile 混音，检查结果见它的 README。 |
| 音效 | 21 个内置音效。每个事件按这个声音在片子里走的一条路取自己的 variant，可以按动作塑形，bin/vh sfx audition 能把一个家族排出来听；同一个声音连着三次以上一样时，bin/vh qa 会提醒。当时的 28 个样片和 00–03 都按它重渲过，没有出现重复提醒。 |
| 配乐引擎 | 乐器声部、动机、动态、物理建模的拨弦和音符表都是确定的，每次引擎改动都验证过旧谱子渲出来字节不变。检查靠测量：音高、音量、衰减、可重复性。 |
| 风格 | 31 个预设，各有真渲样片和自己的配乐，都做过音频质检和确定性检查；tabletop-miniature 是 Blender 场景。 |
| 确定性 | ClaudeAnimationBase 的帧在不同启动、不同渲染顺序下逐像素一致，--soft-gl 和 Mac 的 GPU 上都验证过。样片在 CPU 上渲、编码单线程，不同次运行、不同 worker 数下逐字节一致（抽查了其中 9 个）。Blender 的同一帧用 CPU 上的 Cycles 渲两次逐像素相同（同一测试里 Metal 是 92 dB，EEVEE 是 85 dB），所以 Blender 样片在 CPU 上渲。介绍片的开场在 Metal 上渲：在新进程里乱序重渲的 3 帧都在 45 dB 线以上。 |
| 色彩 | 交付的 mp4 都是有限范围的 BT.709，四个色彩标签写全，手绘引擎也是。2026-10-01 的审计发现有两支 showcase（01 和 03）不合这条规矩，已经重新编码。bin/vh check 现在会报告色彩格式。 |
实验性的，或还没实测的
- 第 09 类，剪辑你自己的素材（video-types/09）：根据同类项目的调研写的。阈值只在合成材料上标定过，没有剪过真实素材，也没在剪辑软件里打开过导出的文件。文档里描述的工具（缺口测量、逐接缝指标、剪辑清单编译器）还不存在，
transcript-cut.mjs是快速路线。 - Blender 指南（engines/blender.md）：部分已实测。维护者的 Mac 装上了 Blender 5.2.2，风格样片
tabletop-miniature和介绍片 15.8 秒的开场都是用它渲的；冒烟测试的结果（CPU、Metal、EEVEE 上的确定性，速度，沙箱，字体，API 改动）和百万个点的大场景踩过的坑都写回了指南，并有标注。冒烟测试里还有几项、指南自己的 build 和 render 命令还没跑过。沙箱只有 macOS 有（sandbox-exec）；在 Linux 上只渲你读过的 Blender 场景。 - 生成式视频加代码（playbook/05）：已经按任务重写，带日期的市场页和台账页对着官方页面核对过（2026-10-01），三个辅助工具（
tools/motion.py、tools/match_grade.py、tools/grain_est.py）在合成片段上验证过。还没有调用过任何视频模型，所以凡是涉及真实生成素材的阈值，在第一个真实项目之前都只是猜测。 dashscope和elevenlabs配音：照官方文档写的，还没对真实接口跑过。ElevenLabs 的逐字符时间会拼成词（PR #7，已合并），同样没实测。- 带人声的歌曲：ElevenLabs Music 和本地歌曲模型只留了接口，歌曲目前从 Suno 这类服务导入。
- 3D 和着色器短片：还没有类型文档，只有一个现成例子（showcase 04，带 Blender 开场）。
- Linux：CI 覆盖，在 Ubuntu 24.04 上配环境时修过一批问题。这些修复在
main上，还没打版本。Linux 上没有本地配音。
已知局限
- 样片评分：还没有一个样片每一项都 ≥ 8，最低分的中位数约为 6，最新的三个最低分都是 7（styles/README.md）。
- 先有立意的效果还没怎么量过：研究笔记 06 用两个一句话需求、每边各做两支片子来比：两次 reviewer 都觉得工作流做的那支更有新意，但两次都选了只守底线的那支去发；平均分只差 0.3 和 0.7，很可能在每次运行的波动之内。
- 定稿的混音还没有人用耳朵判过。 agent 听不见，所以样片配乐和片子的混音都是量出来的。维护者听过 00–03 最初的候选混音和 02 里被标出来的几处旁白，没有从头到尾听过现在这版定稿的 profile 混音；样片也没有记录逐对的听测结论。配乐之间那把 7 个特征的距离尺子，听不出旋律和和声。
- Qwen3-TTS 0.6B 念英文短句：念完可能还拖几秒含糊声。已有的应对：英文默认音色换成 Aiden（Ryan 在 8 次运行、40 句里出错 9 句，Aiden 25 句没有出错）；裁掉每句首尾的空白；
--align gemini会标出拖尾的句子。被标出来的句子重跑，或者换 1.7B 模型、改用gemini。 - 音频质检的盲区：抽吸检查会漏掉又长又浅的凹陷，只能靠 −12 dB 的掉音检查兜底；卡点检查按全片最响的起音归一化，而且分不清它找到的是谁的起音，所以一个卡点可能靠配乐自己的起音，或同一个音效的第二个音就过了；爆音只是警告，要人耳复听。
- 混音 profile 是往中间拉的：每个音效只向它那一类的范围走一半，所以设计得离谱的
gain_db照样看得出来；低频的重击要加 1–4 kHz 的一层，不能靠增益；配乐自己的空间（混响、宽度）还没接进bin/vh music。 - 节拍检测：切分节奏的曲子，
bin/vh beats可能把 BPM 报成一半；和底鼓同一音区的拨弦 bass 会被当成底鼓。 - 内置转场音效的落点：plain 的
whoosh能量峰在落点后约 34 毫秒，塑形过或换了 variant 的扫音落在自己最响的 50 毫秒中间；swish_rev、tape和riser在落点上结束，能量峰在前面（swish_rev约 100–280 毫秒，tape约 0.5 秒）；shimmer从落点开始，最响处在落点后约 50–400 毫秒。 - Gemini 限额：Tier 1 每分钟只能转写 10 次、每天约 100 次，长稿子会碰到 429 等待，日配额用完时会中止（之后可以用
--resume接着跑）。 - 文档语言：工作流文档以中文为主；README、CHANGELOG、showcase 的说明和研究笔记有英文版。
- Windows 不在支持范围内：环境要求写的是 macOS 或 Linux，CI 也只跑这两个。
平台
每个 PR 都会在 ubuntu-latest 和 macos-latest 上跑 tools/ci.sh；在 macOS 上还会用系统自带的 /bin/bash 3.2 跑 bin/vh，因为 Mac 用户默认用的就是它。两项检查都通过，才能合进 main。
版本
| 版本 | 日期 | 主要内容 |
|---|---|---|
| v0.1.0 | 2026-09-29 | 首次公开发布：8 类视频的路由、三道人工关卡、playbook 00–08、含 20 条清单的 7 个模板、11 个案例拆解、声音工具（配音、字幕、配乐、15 个音效、混音）、bin/vh、一键安装、showcase 00–03 |
| v0.2.0 | 2026-09-29 | 努力程度三档；介绍片；风格库（26 个预设，各带样片）；7 个维度的打分层；bin/vh qa；Gemini TTS；参考仓库增加到 30 个 |
| v0.2.1 | 2026-09-30 | 可导演、能卡拍的旁白；--align gemini；双人对话；bin/vh voices；bin/vh readcheck；28 种风格 |
| Unreleased | 在 main 上 |
导演模式、看图做决定的工具、先有立意、规格先定、镜头配方和全片骨架、四篇新的 playbook、混音 profile、更大的配乐引擎和音效 variant、每个样片和每支片子的声音、31 种风格（其中一个用 Blender 渲）、介绍片 v5、第 09 类和 Blender 指南、安装和镜像文档、研究笔记（见下表）；另有每个命令的 -h、Linux 修复、v0.2.1 全面复查后的修复、CI 和分支规则、给视频模型写运镜、ElevenLabs 词级时间、社区文件，以及标准 MIT 许可证（import bpy 的文件是 GPL-3.0-or-later） |
每个版本都是一个带 v* tag 的 GitHub Release，发布说明就是 CHANGELOG 里对应的一节。
main 上已有、还没发版的内容
| 方面 | 落地了什么 | PR |
|---|---|---|
| 导演模式 | 十二件事的 own / review / delegate（立意和规格是后来加的），检查点 E0–E5，bin/vh review 审阅页，DECISIONS.md，旁白稿、角色、标题封面三个模板 |
#19 |
| 先有立意 | playbook 12 和关卡 ① 的立意卡；清单里的底线条目单独标出，其余口味规则都是立意可以改的默认值；第 8 个评分维度"立意"；五支社区作品的案例拆解；五条从立意出发的全片骨架；研究笔记 06，工作流对比只守底线的 A/B | #44、#43、#45、#46 |
| 规格先定 | BRIEF 里的 Watch on 和 Resolution，由 bin/vh new 填（--watch、--res）；字号下限按在哪看分档；4K 按 1080p 写、出片时渲成两倍大 |
#47 |
| 看图做决定的工具 | bin/vh storyboard、rhythm、style compare 和 apply、cover-preview、music --roll 和 --length、readcheck --budget 和 HyperFrames 时间、new --aspect 和 --dir |
#25 |
| 命令行 | bin/vh <命令> -h 只打印用法，不再真的运行；hf-init 的脚手架字体取本机字体，不走 Google Fonts；check 报告色彩格式；readcheck 把标了 data-read="subtitle" 的字幕按字幕规则查，captions 会延长太短的字幕 |
#50、#35、#37、#38 |
| 镜头配方 | 24 个配方、八条全片骨架（三条按能量弧，五条从立意出发）、bin/vh recipes list 和 check |
#27、#45 |
| playbook | 09 叙事、10 钩子与封面、11 作曲、12 立意 | #23、#44 |
| 配乐 | 乐器声部、节奏型和总线；物理建模的拨弦；动机、动态和停顿；按音符驱动画面的音符表 | #13、#16、#20、#24、#41 |
| 混音和音效 | profile、混音报告、更严的卡点检查；每个事件自己的音效 variant、塑形、六个新转场（共 21 个内置音效）、sfx audition、重复提醒 |
#21、#39 |
| 风格 | 第一个用 Blender 渲的样片 tabletop-miniature（Blender 样片场景，在沙箱里渲）；pastel-ui 和 y2k-chrome（共 31 个）；预设作为参考挂到项目上，不再当模板 |
#42、#49、#48 |
| 媒体 | 28 个样片的配乐；showcase 00–03 的声音，之后 00–03 和样片都按新的音效引擎重渲；02 和 03 的词级时间；手绘引擎、01 和 03 改成 BT.709 | #31、#32、#40、#36、#28 |
| 介绍片 | v5：开场 15.8 秒用代码驱动 Blender，用同一个相机交给 WebGL，再接一镜到底的正文；v3 留在 v3/ |
showcase/04 |
| 渲染 | 样片在 CPU 上渲，逐字节一致 | #17 |
| 实验性 | 第 09 类、Blender 指南、按任务重写的生成片段一章（带市场页、台账页和三个工具） | #30、#29、#26 |
| 文档 | 会下载什么、国内网络镜像、HyperFrames 入门；研究笔记；README 的样片一支一行，带需求、做法和声音 | #22、#33、#34 |
怎么发版
- 每处改动都通过 squash 合并的 PR 进
main，所以一个 PR 在main上只留一个提交。 - 用户能感知到的改动，在同一个 PR 里往 CHANGELOG 的 Unreleased 下记一笔。
- 发版时，把 Unreleased 改成带日期的版本号标题。
- 每个版本打一个
v*tag，由两个规则集保护：只有管理员能创建，任何人都不能移动或删除。具体步骤见 CONTRIBUTING.md。