sweety-handdraw-video命令行参考:doctor、build、render、verify、finalize五步生产管线详解
sweety-handdraw-video命令行参考:doctor、build、render、verify、finalize五步生产管线详解
sweety-handdraw-video 是一个把主题、文章或故事做成完整手绘讲解视频的命令行工具:从环境体检、时间线构建、逐帧渲染,到工程校验与交付回执,全部围绕五个子命令展开。本文带你逐一拆解 doctor、build、render、verify、finalize 各自的职责、输入输出与常见报错,帮你少走弯路,一条命令一条命令地把片子做出来。
五个命令的入口都在同一个脚本里:handdraw_video.py,用法统一为:
python3 /path/to/skill/scripts/handdraw_video.py <命令> /path/to/job
其中 /path/to/job 是任务目录,里面必须包含 job.json。各命令的详细参数见 运行格式与命令。
五步管线全景:一张表看懂流程
| 顺序 | 命令 | 一句话职责 | 关键产物 |
|---|---|---|---|
| 1 | doctor |
开工前体检:工具、字体、素材、旁白是否齐全 | JSON 报告(含 ready 标志) |
| 2 | build |
把 job.json 编译成可渲染的时间线与素材 |
work/timeline.json、cover.png、SRT、口播稿 |
| 3 | render |
逐帧绘制并编码 MP4 | outputs/film.mp4(或 --preview 预览片) |
| 4 | verify |
工程校验:完整解码、音频相关性、响度、抽帧 | work/verification.json、review.json 骨架 |
| 5 | finalize |
核对检查记录后生成交付回执 | outputs/verification.json / verification.txt |
整条链路的规则是:任何一步的输入变了(脚本、素材、声音、布局),后面就要重跑。这也是 finalize 会用哈希严格把关的原因。
第一步:doctor 环境预检,先报缺什么
python3 /path/to/skill/scripts/handdraw_video.py doctor /path/to/job
doctor 会输出一份 JSON 报告并检查以下内容(实现见 video_job.py 中的 inspect_environment):
- ffmpeg / ffprobe 是否在 PATH 中找到;
- 中文字体:优先读
job.json的font.path,否则自动探测系统字体; - 素材完整性:封面、每张插画的
source、旁白母带、手部素材逐一核对; - 美术指导记录:图片是否都登记了有效的美术检查记录;
- VoiceStudio 可用性:探测
http://127.0.0.1:3900/engines/tts是否可达; - 旁白文件:完整母带 + 时间戳是否齐全。
两个容易混淆的标志位:
ready: true表示当前任务输入已可离线合成;voice_studio.available: true单独表示还能生成新旁白。
二者不能混用——旁白已经录好的任务,VoiceStudio 离线也可以继续做片。doctor 通过时退出码为 0,缺项时非 0,方便在脚本里串联判断。常见卡点对照见 环境检查表。
第二步:build 构建时间线,把旁白"量"进画面
python3 /path/to/skill/scripts/handdraw_video.py build /path/to/job
build 是整条管线里"最聪明"的一步,它由 video_job.py 中的 FilmBuilder 完成:
- 读取整篇旁白母带,把每一句 beat 的实际起止时间映射到页面;
- 给绘制动作分配时间窗:每个插画部位、每段手写文字按
weight分得绘制窗口,旁白太短装不下画面时会直接报错"too many drawing actions",提醒你简化或合并,而不是截短声音; - 生成全部渲染素材:文字按字形隔离逐字描线、插画按语义部位划分轮廓与填色区间,产出
work/assets/下的位图与路径数据; - 写出时间线与交付文件:
work/timeline.json、outputs/cover.png(1 秒封面:前 0.5 秒静止、后 0.5 秒渐隐)、outputs/editing/transcript.srt和outputs/script.txt。
build 失败大多是内容问题而非环境问题:画布超出边界、beat 缺少动作、字幕事件重叠、封面比例不符、美术记录哈希不匹配等,报错信息会直接指出是哪一条。字段的完整约定见 运行格式,例如生产任务必须提供 narration.source 与 alignment 指向整篇母带和时间戳。
第三步:render 逐帧渲染,编码成片
# 先渲染 15 秒短段自查
python3 /path/to/skill/scripts/handdraw_video.py render /path/to/job --preview --duration 15
# 确认后渲染完整成片
python3 /path/to/skill/scripts/handdraw_video.py render /path/to/job
渲染器 video_renderer.py 按时间线逐帧合成:笔尖沿笔画路径移动、手臂抬笔走位、插画按部位"先轮廓后填色"、字幕以独立排字层叠加,最后通过 FFmpeg 以 libx264(crf 18)+ AAC 192k 编码。开始前它会自动:
- 复核美术指导与素材哈希,防止 build 之后素材被偷换;
- 导出故事板总览
work/review/storyboard-contact.jpg,每页抽一帧拼成检查图; - 对旁白做
loudnorm响度归一后混音为work/mix.wav,并校验混音时长不变。
两个使用要点:
--preview只用于部分区间(可配--start/--duration),输出到work/review/preview.mp4;正式成片必须覆盖完整时间线,否则会报错 "delivery film must include the complete timeline";- 渲染结束会写
work/render-record.json,记录视频 SHA-256 与构建指纹,这是后面verify/finalize对账的依据。
建议先实际看过 15 秒短段(笔尖、手臂、遮挡、字幕可读性),再导出全片。
第四步:verify 工程校验,抽帧留证
# 完整工程校验
python3 /path/to/skill/scripts/handdraw_video.py verify /path/to/job
# 只校验绘制素材(改完素材先跑这个,快)
python3 /path/to/skill/scripts/handdraw_video.py verify /path/to/job --assets-only
verify 由 video_verifier.py 执行,它检查的远不止"文件能打开":
- 像素级路径校验:每个颜色像素必须有真实笔刷覆盖、墨水不能离笔尖太远、字形四边留白、部位顺序不被打乱;
- 视频体检:ffprobe 核对分辨率、帧率、H.264/AAC 编码,音画时长差 < 0.08 秒;
- 完整解码:全片
ffmpeg -f null解码零错误; - 音频对账:编码后音轨与
mix.wav的相关系数须 > 0.99,末句单独再核一次(> 0.98),响度须落在 -20 ~ -14 LUFS; - 抽帧留证:封面加每页末帧解码成
work/review/decoded-contact.jpg供人工复查。
全部通过后,work/verification.json 的 status 会标记为 engineering_passed_review_required,并自动生成 review.json 骨架——content / visual / motion / audio / privacy 五项初始都是 not_checked。工程通过不等于观感验收,这一步必须由人(或 Agent)真正看帧、听音后填写证据,规则详见 检查与返工。
第五步:finalize 交付回执,拒绝"过期"记录
python3 /path/to/skill/scripts/handdraw_video.py finalize /path/to/job
finalize 是最后一道闸,它会依次确认:
verification.json的 status 是工程通过;review.json五项检查全部pass且都写了证据;- 视频哈希、构建指纹、
job.json哈希三者与当前文件完全一致——只要 render 之后改过任何输入,finalize 直接拒绝; - 任务不是离线测试夹具(
runtime_fixture永远不能交付)。
通过后在 outputs/ 下生成两份回执:verification.json(机器可读的完整交付记录)和 verification.txt(含视频 SHA-256、片长、五项检查证据与"未验证或限制"说明的人读版)。
推荐的完整执行顺序
把上面五步串起来,一次标准生产流程如下(另配 voice_studio.py 生成旁白):
# 0. 生成整篇旁白母带与时间戳(已有旁白可跳过)
python3 /path/to/skill/scripts/voice_studio.py /path/to/job --transcribe
# 1~4. 体检、构建、素材快检、短段预览
python3 /path/to/skill/scripts/handdraw_video.py doctor /path/to/job
python3 /path/to/skill/scripts/handdraw_video.py build /path/to/job
python3 /path/to/skill/scripts/handdraw_video.py verify /path/to/job --assets-only
python3 /path/to/skill/scripts/handdraw_video.py render /path/to/job --preview --duration 15
# 5. 看过短段后:整片渲染 → 工程校验 → 人工看帧听音填 review.json → 交付
python3 /path/to/skill/scripts/handdraw_video.py render /path/to/job
python3 /path/to/skill/scripts/handdraw_video.py verify /path/to/job
python3 /path/to/skill/scripts/handdraw_video.py finalize /path/to/job
常见问题速查
| 现象 | 优先检查 |
|---|---|
doctor 报 ready: false |
看报告里的 missing_inputs 与 font_error,缺哪个补哪个 |
ready: true 却生成不了新旁白 |
voice_studio.available 为 false,服务未启动或端口不对 |
build 报 "too many drawing actions" |
该句旁白太短,简化画面或把多句合并为 visual_groups |
render 报 "Use --preview for partial renders" |
整片渲染不能带 --start/--duration,去掉或用预览模式 |
verify 报 "Inputs changed after rendering" |
build 之后动过素材或脚本,重跑 build + render |
finalize 拒绝交付 |
review.json 五项没写齐证据,或视频被重新渲染过 |
更多边界与硬性约束(片尾保护、字幕唯一性、音频层策略)见 声音与收尾、字幕与片尾设计 与 连续旁白约定;整体制作要求见 SKILL.md。
小结
sweety-handdraw-video 的五步管线把"能跑"和"好看"分开验收:doctor 保证起跑条件、build 把声音量进画面、render 逐帧兑现绘制计划、verify 用哈希和像素证据锁住工程质量、finalize 则确保交付的正是你检查过的那一版。按顺序执行、失败就修对应层,是它一贯的工作方式。


