常见问题 - ZLHad/OpenVideoHarness GitHub Wiki

English · 中文

不能直接看。它把渲染出来的静帧拼起来看：联系表看构图，一串连续帧（strip）看时序，局部 crop 看细节。声音靠读数据：转写文本、时间戳、响度、起音点。Gemini 可以选用来读整支视频，但大约每秒只取一帧，只能发现叙事层面的问题和大致的音画错位。正因为看不全，才需要那一整套检查，见工作原理。

不需要。渲染在无头 Chrome 或 Manim 里跑，有 GPU 时 WebGL 会快一些。没有 GPU 的机器上，bin/vh doctor 会告诉你软件模拟的 WebGL 能不能用，能用就加 --soft-gl 渲染（慢一些，结果照样确定）。本地配音（Qwen3-TTS）需要 Apple Silicon；其他机器用 edge 或云端音色。Blender 只用在要路径追踪的镜头上，CPU 和 GPU 都能渲；在 Mac 上，冒烟测试里 Metal 比 CPU 快好几倍。

Claude Code 和 Codex 可以直接用：安装脚本会给两者都注册 skill，AGENTS.md 和 CLAUDE.md 内容相同。其他能读 markdown、能跑 shell 命令的 coding agent，也能照着同一套文档做。showcase 里的片子是用 Claude Opus 5.5 做的。

纯代码这条路不花钱：渲染、本地 Qwen3-TTS、say、edge、配乐、音效、混音、质检都免费。要花钱或按量计费的有：云端配音（gemini 有免费档，另有 dashscope、elevenlabs）、--align gemini（免费档不收费，付费档约每分钟音频 0.005 美元）、生成式视频、歌曲生成服务。凡是要花钱的，agent 会在关卡 ① 单独列出来并估算费用，你同意了才动。Gemini 的最新价格见 playbook/04。

仓库的原创内容（包括风格预设）是 MIT 许可；调用 Blender Python API 的文件除外（样片渲染器的 blender_render.py、tabletop-miniature/swatch.py 这类 Blender 风格场景、介绍片的 galaxy.py），按 Blender 对公开发布的 bpy 脚本的要求，是 GPL-3.0-or-later。有几个预设改写自 lemo-opuscar 早期 CC BY 4.0 的快照，保留了相应署名。预设描述的是语法，不照搬角色、logo 和镜头；但你自己片子里放什么，要你自己把关：字体引用的是你本机装的，不随仓库分发，要自己确认许可；每个素材的来源都记进 NOTES.md。references/repos/ 里的参考仓库不属于本仓库，有些没有许可证或者禁止商用，只读、不复用。逐个仓库的结论见 community-skills.md 第 5 节和 ACKNOWLEDGMENTS.md。另外，商用配音避开 fish-speech、F5-TTS 的权重和 ChatTTS，它们是非商用许可；如果选 Remotion 引擎，超过 3 人的公司需要购买 Remotion 的授权。

因为越早改越便宜：改分镜只要几分钟，改写好的代码要几个小时。立意和大纲、分镜、初版三处停下来，让你的判断用在最省工的地方。

不用。关卡 ① agent 会给 2–3 张立意卡：每张是一句话的点子，让形式本身就在讲内容，写明由它推出的画面和钩子，配一帧画面。选一张，在回复里换掉它的风格预设或钩子都行；你自己带着立意来，它就直接写进 BRIEF。见工作原理。

能。说"快速出一版"（努力程度 quick），或者在对话里明确说不用审。agent 会把你的原话和日期记进 REVIEW.md，被跳过的关卡由全新上下文的 reviewer 代审。agent 不能自己决定跳过。

一个开关，三档：quick、standard（默认）、studio。它决定停下来问你几次、立意怎么给你看（每张一帧画面，studio 每张一段 10–20 秒的草图）、自查查多细、独立打分做几轮、声音做到什么程度、最后交付什么。30 秒的片子大约分别要 10–30 分钟、1–2 小时、3 小时以上。完整规则用 bin/vh effort 查看。

努力程度管 agent 自己查得多细，导演模式管哪些事由你来定。十二件事可以点名（立意、规格、大纲、风格、主角、主旋律、配音、旁白稿、钩子、分镜、剪辑节奏、标题和封面），每件都可以设成 own（agent 出选项，等你选）、review（它出一个结果接着做，你不反对就算通过）或 delegate（它自己定，理由写进 DECISIONS.md）。"快速出一版，但钩子我来选"这样的话是说得通的。standard 和 studio 的三道关卡照停，导演模式只加停。见工作原理。

你想要，或者精品档的片子要发到 B 站、YouTube 这类能放 4K 的平台时再出。照常按 1080p 写，出片时渲成两倍大（bin/vh new … --res 4k，或 BRIEF 里写 Resolution: 4k），字在屏幕上看起来一样大；draft 和自查仍用 1080p。手绘引擎没有 4K 输出。字该多大看的是在哪看，不是分辨率：见工作原理。

有对应的类型，第 09 类，但它是实验性的。它剪你自己录的口播、访谈、Vlog：删口水词和重录，在测量到的静音缺口处下刀，加字幕和图解，需要的话出竖屏版。你批准了剪辑清单才开始渲染。它目前只在合成材料上调过，所以阈值只是起点，文档里提到的工具也有几样还没写出来。素材是你的脸和你的声音：转写默认在本地做，要用云端服务，agent 会先问你。见视频类型。

纯代码这条路不会。会出门的有：云端配音、--align gemini（它会把你的旁白音频发给 Gemini）、生成式视频，以及模型下载。有一处容易漏：环境里设了 GEMINI_API_KEY 或 GOOGLE_API_KEY 时，hyperframes snapshot 默认会把每一帧发给 Gemini 做描述，除非加 --describe false，仓库的文档和提示里一直带着它。涉及你自己的素材，agent 在送出任何东西之前会先问你。

拉片拆解 1–3 部作品，写 STYLE.md 和 tokens.json，写样片，渲染并检查，重建总览，开 PR。步骤见风格库。

本来应该一样：每一帧都必须是 t 的纯函数。查一查有没有用 Math.random()、Date.now()、CSS transition、@keyframes，或者在帧之间保存了状态。比较时比无损 PNG 帧，不比 MP4，因为视频编码会放大 GPU 带来的细微差异；逐像素相同，或者 PSNR ≥ 45 dB 且肉眼看不出，就算通过。HyperFrames 加 --no-browser-gpu，文字边缘也能做到可重复。更多见排错。

不在仓库里。工具只从环境变量读 key；.env* 文件被 git 忽略，LOCAL.md 只记变量名，不记值。Gemini 的 key 放在请求头里发送，不会出现在 URL 中。

工作流文档本身以中文为主。字幕会正确折行中文（竖屏建议每行 11 个字），Qwen3-TTS 有 5 个中文音色，包括京腔和川话，手绘引擎还能按真实笔顺写汉字。字体方面：HyperFrames 里要显式引入 Noto Sans SC（Google Fonts 的 <link> 或 @font-face）；canvas 上要把片中用到的每个字都预先加载，见排错。

装好之后基本可以。项目用本地装好的引擎渲染，本地配音、配乐、音效、混音都不需要联网。需要联网的有：云端配音和 --align gemini、模型的首次下载、Google Fonts 的 <link>，以及 bin/vh hf-init（它用 npx 拉取 HyperFrames）。

在 projects/<日期>-<名字>/ 下，这个目录不进版本库。draft 和成片在 out/，检查用的图在 out/check/。见快速开始。

有一部分来自测量，写成了实验记录，放在 docs/research/（也有英文版）：混音层级、28 份配乐有多像、同一份代码为什么渲出不同的像素、画面上的字要停多久、配乐的形状，以及先有立意是不是比只守底线好。它们是记录，不是规则，数字主要是仪表读数，不是听测结论。另见工作原理。

还没有。README、CHANGELOG、showcase 的说明和研究笔记有英文版；CLAUDE.md、playbook 和类型文档以中文为主。agent 读哪种都没问题。欢迎帮忙翻译。