sweety-handdraw-video命令行参考:doctor、build、render、verify、finalize五步生产管线详解

原创2026-10-25 13:59:491,642 阅读

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 会用哈希严格把关的原因。

sweety-handdraw-video手绘讲解视频支持的多种画风总览

第一步: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 完成:

  1. 读取整篇旁白母带,把每一句 beat 的实际起止时间映射到页面;
  2. 给绘制动作分配时间窗:每个插画部位、每段手写文字按 weight 分得绘制窗口,旁白太短装不下画面时会直接报错"too many drawing actions",提醒你简化或合并,而不是截短声音;
  3. 生成全部渲染素材:文字按字形隔离逐字描线、插画按语义部位划分轮廓与填色区间,产出 work/assets/ 下的位图与路径数据;
  4. 写出时间线与交付文件:work/timeline.json、outputs/cover.png(1 秒封面:前 0.5 秒静止、后 0.5 秒渐隐)、outputs/editing/transcript.srt 和 outputs/script.txt。

build 失败大多是内容问题而非环境问题:画布超出边界、beat 缺少动作、字幕事件重叠、封面比例不符、美术记录哈希不匹配等,报错信息会直接指出是哪一条。字段的完整约定见 运行格式,例如生产任务必须提供 narration.source 与 alignment 指向整篇母带和时间戳。

手绘风格K线图逐笔描线示例,展示render阶段的绘制效果

第三步: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)真正看帧、听音后填写证据,规则详见 检查与返工。

角色形象一致性对比检查示例,用于verify阶段的人工观感核对

第五步:finalize 交付回执,拒绝"过期"记录

python3 /path/to/skill/scripts/handdraw_video.py finalize /path/to/job

finalize 是最后一道闸,它会依次确认:

  1. verification.json 的 status 是工程通过;
  2. review.json 五项检查全部 pass 且都写了证据;
  3. 视频哈希、构建指纹、job.json 哈希三者与当前文件完全一致——只要 render 之后改过任何输入,finalize 直接拒绝;
  4. 任务不是离线测试夹具(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 则确保交付的正是你检查过的那一版。按顺序执行、失败就修对应层,是它一贯的工作方式。

登录后查看全文
sweety-handdraw-video