sweety-handdraw-video 教程：把主题或文章做成边画边讲的手绘口播视频（2026）
阅读说明
仓库信息查阅日期：2026-10-23；星数、更新时间会变，以仓库页面为准；本文不写价格。
一句话结论
threerocks/sweety-handdraw-video 是给 Codex 和 Claude Code 的手绘口播 Skill。给一个主题、一篇文章或完整故事，Agent 负责理解内容、写口播、设计分镜和生成插画；本地 Python / Pillow / SciPy / FFmpeg 负责逐笔描线、填色、手写文字、配音对齐和导出。成片不使用外部图生视频模型。
适合做知识讲解、故事寓言、观点表达、产品原理和教学内容，并且能准备图像生成与本地配音的人。README 写明完整制作流程在 macOS + Codex 上跑通。在 Claude Code 里做整片时，需要接入生图工具或 MCP，或由用户提供插画。
仓库信息
截至 2026-10-23，星数、最近推送和创建时间取自仓库元数据，日期为北京时间。
| 仓库 | 星数 | 最近推送（北京时间） | 许可 | 创建时间 |
|---|---|---|---|---|
| threerocks/sweety-handdraw-video | 829 | 2026-10-20 | MIT | 2026-10-12 |
仓库描述是：「从主题或文章制作完整手绘讲解视频：按部位描线、逐字书写、VoiceStudio 配音、五项内置制作依赖。」README 当前版本写的是 v1.4.1（2026-10-20），以包内 VERSION 和 Git 标签为准。主项目代码与文档采用 MIT。五项内置依赖保留各自的版权与许可证，见仓库 THIRD_PARTY_NOTICES.md。
它能做什么样的视频
输入和交付方向：
| 输入 | README 写明的交付方向 |
|---|---|
| 一个主题 | 整理讲解路线，设计生活场景、机制与行动建议 |
| 一篇文章或参考资料 | 保留重要事实、数字和限定，改成适合听与看的口播 |
| 完整故事或定稿 | 按原文制作；要求保留原文时，不擅自重写 |
| 已认可的图、声音和稿件 | 复用素材，修订字幕、手部、画面或时间线 |
README 列出的公开样片（页面不嵌入视频）：
| 样片 | README 写明的内容 |
|---|---|
| 《那条死于愤怒的蛇》 | 49 秒。淡彩叙事插画、毛笔手部、无底板字幕。与下一条同为 1920×1080、30fps，由 v1.2 制作 |
| 《快乐囚禁你的方式》 | 1 分 52 秒。冷色棱角插画，女性手部，连续女声旁白。README 写明当前女声暂时保留，听感仍待后续调整 |
| 《墨菲定律》 | 约 2 分 05 秒，8 个画面、24 段口播。淡彩速写、女性碎钻长甲手及笔杆文字。公开 v1.0.0 的历史样片，不代表最新的连续旁白流程。下载说明标为 1080p |
前两条公开 MP4 由 v1.2 制作，逐笔绘制、分段配音等 v1.3 改动不在其中，并保留制作时的预告水印。水印文字不代表当前发布时间。README 写明较长样片用于展示叙事跨度，不代表短观点也应做成长视频。
未指定时，制作说明采用简体中文、1920×1080、30fps。时长由实际口播决定。「约一分钟」是创作目标，不靠拉长空白凑时间。默认有 1 秒封面（前 0.5 秒静止、后 0.5 秒渐隐），默认片尾停留 0.45 秒。默认纯旁白：背景音乐不自动添加；用户提供音乐时，构建会循环接续、淡入淡出，并随旁白压低。
画面按旁白预算设计：先算出每幅能画几秒、最多几笔，再出图。墨线平涂画风整笔描线、先轮廓后细节、抬笔移动，马克笔之字形上色；无轮廓画风由笔刷按部位揭示。汉字在 GB2312 范围内按标准笔顺书写。版本说明还写了拟人绘制时的部位停顿。
21 个库内画风
库内是 20 个编号风格加 3.1 稳定变体。也可以让模型独立设计，或给自定义描述。下表「绘制」一列按 README 的划分：1、4、5、17、19、20 为逐笔绘制（先描线、再上色），其余为揭示。
| 编号 | 画风 | 绘制 |
|---|---|---|
| 1 | 极简黑白线条讲解漫画 | 逐笔绘制 |
| 2 | 蜡笔童涂 | 揭示 |
| 3 | 吉卜力风 | 揭示 |
| 3.1 | 蜡笔童涂·潦草自画稳定变体 | 揭示 |
| 4 | 小豆人黑色涂鸦信息图 | 逐笔绘制 |
| 5 | MS Paint 烂涂鸦 | 逐笔绘制 |
| 6 | 圆珠笔单线涂鸦 | 揭示 |
| 7 | 蜡笔实拍纸张 | 揭示 |
| 8 | 水墨写意 | 揭示 |
| 9 | 复古像素 | 揭示 |
| 10 | 情绪叙事淡彩速写 | 揭示 |
| 11 | 二维水彩 / 复古动画概念稿 | 揭示 |
| 12 | 暖光童画 | 揭示 |
| 13 | 北欧纸雕 | 揭示 |
| 14 | 北欧绘本水粉 | 揭示 |
| 15 | 大鼻软偶 | 揭示 |
| 16 | 聚光水粉立绘 | 揭示 |
| 17 | 墨线绘本 | 逐笔绘制 |
| 18 | 暖色扁平绘本 | 揭示 |
| 19 | 圆头红线极简童画 | 逐笔绘制 |
| 20 | 暖黄墨线情绪小剧场 | 逐笔绘制 |
这些是静态美术方向，不表示每一种都做过相同强度的视频验证。选择器在每张卡片上标明绘制方式，结果写入 style/resolved.json 的 drawing_mode。没指定画风时，模型默认从上色的 4、5、17、19、20 里按内容选；纯黑白的 1 号要写明理由。揭示只能由用户亲自选（点揭示卡，或听过「只能刷出、不能画出」的说明后同意）。模型不会因超时、委托或某张图画不出来而改用揭示。
手部
| 预设 | 标识 |
|---|---|
| 深蓝袖马克笔 | navy |
| 女性柔粉碎钻长甲 | diamond-woman |
| 儿童彩铅 | child-pencil |
| 上官婉儿灵感毛笔 | waner-brush |
| 白衬衫中性笔 | teacher-pen |
| 针织袖钢笔 | cardigan-fountain |
| 仅画笔，不显示手臂 | pen-only |
pen-only 是 navy 同一支笔去掉手臂。自定义素材要提供笔尖定位等参数。笔杆文字最多 16 个 Unicode 字符，水印最多 180 字符、可换行；两项默认都空。字幕默认白字黑边，quiet 为无底板，plate 为有底板，全程只允许一套字幕。
内置 omniailab-ai-director 用在创作规划、分镜和最终审片。判断写进创作方案，由本地渲染执行。README 写明它不是独立运行的导演模型，也不自动启用上游影视生成平台。需求里可以指定处理方式，例如「直接从冲突开始」「按老师讲题的顺序做对照」「关键结果出来后留时间看清」「保留原文结尾」。
需要准备什么
README 写明本轮支持 macOS 与 Linux，宿主为 Codex 与 Claude Code。README 写明完整制作流程在 macOS + Codex 上跑通，范围写的是 Apple Silicon Mac。Linux 由 CI 与 Ubuntu 容器验证安装、字体发现、回归与离线短片合成；本地 TTS 仍以 Apple Silicon 为主。Claude Code 已验证安装与本地脚本。Windows 与 Gemini 等其他组合暂不承诺。
| 条件 | README 写明的用途与边界 |
|---|---|
| 能读 Skill、能执行本地命令的 Agent | Codex 或 Claude Code |
| 图像生成 | Codex 用内置生图。Claude Code 需要接入生图工具或 MCP，或由用户提供插画。脚本无法探测宿主能力；没有生图能力时必须停下说明，不能交付只有文字的视频 |
| Python 3.9+ | 本地绘制与合成。依赖 Pillow、NumPy、SciPy、requests、fontTools，由 setup.sh 装进 ~/.local/share/sweety-handdraw-video/venv |
| FFmpeg 与 ffprobe | 合成、编码、解码与音视频检查。macOS 用 Homebrew；Linux 用 apt，同时装 fonts-noto-cjk 与 fontconfig，并给出 dnf / pacman 对应命令 |
| 中文字体 | 手写字、字幕、笔杆文字与水印分开选字体，并逐字核对字形。缺字时构建失败，并列出缺失字符与已尝试字体。macOS 优先 Hannotate，Linux 使用 fontconfig 与 Noto CJK。不随包分发系统商业字体 |
| 一种配音路径 | 见下表。普通安装不会下载配音模型 |
| Node.js / npm（可选） | 只用于下面的 npx 安装命令。手动安装不依赖它 |
图片隐私清理已改为 scripts/clean_image.py，不再需要 Bun 或 ExifTool。
README 提醒：模型宿主和生图能力可能另行收费。
音色和配音后端分开选。六款内置音色带参考音频和同文试听；后端负责把本次正文生成声音。
| 路径 | 需要准备 | README 写明的范围 |
|---|---|---|
| VoxCPM2 本地适配器 | Apple Silicon Mac、独立 MLX 环境、mlx-audio / mlx / soundfile、已下载模型与真实路径 | 本项目使用 VoxCPM2-8bit MLX。当前适配器不是 Windows / NVIDIA 部署方案。只有在 setup.sh 上显式传入 --voxcpm 才会下载约 3.2 GB 的 VoxCPM2-8bit |
| VoiceStudio 本机服务 | 能提供兼容 HTTP API 的本机服务，已配置 TTS 引擎 | 默认 http://127.0.0.1:3900。已对接 mlx-audio / Qwen3-TTS-12Hz-1.7B-Base-bf16。需要 /engines/tts、/generate，以及可选的 /transcribe。同名软件不一定兼容 |
| 现成整篇旁白 | 已检查的音频及其时间戳 | 可离线编排和渲染，本次无需重新合成声音 |
| 火山豆包 / Gemini TTS（可选） | 用户自己的密钥，放在环境变量 | 按官方文档实现。只做了模拟 HTTP 测试，本仓库未真实调用。不是默认路径，本地失败时也不自动改用 |
生成路径按语义段落逐段提交（每段不超过约 100 字，只在句末切），逐段核对杂音、语速和漏读，不通过换种子重试，再拼成母带并自动写时间戳。模型权重不在 Skill 包内，运行脚本不会自动下载模型或切换全局声音引擎。带噪参考可能要做人声分离或降噪；HTDemucs / DeepFilterNet3 是 README 所述女声修复用过的可选工具，不是人人都要装的基础依赖。
| 声音名称 | README 写明的用法 |
|---|---|
| 逼真男声 | 公共安装可以试听。生成前要自行导入原片参考 |
| 逼真女声 | 同样要自行导入。README 写明目前暂用，听感仍待调整 |
| 磁性解说男声（默认） | 随包合成参考，可直接生成 |
| 儒雅青年 | 随包合成参考，可直接生成 |
| 温柔知性女声 | 随包合成参考，可直接生成 |
| 悬疑故事解说 | 随包合成参考，可直接生成 |
四款合成声音由本机 VoxCPM2 按文字描述设计，没有使用真人、主播或平台音色作参考。也可以导入本人录音或已获授权的声音，导入时声明授权，参考须通过杂音门禁。README 写明所有声音当前都待听感验收。成片节选只用于试听，不能再当作原片参考去克隆。
Skill 只注册一个入口。下面五项以固定快照内置，不必分开安装，运行时也不会自动追踪上游：
| 内置项目 | 用途 |
|---|---|
sweety-image-art-direction | 主体、接触关系、构图、比例与观看主次 |
hand-drawn-styles | 风格配方、参考锚点与预览 |
omniailab-ai-director | 导演规划、叙事、声画关系与终审方法 |
huashu-art-motion | 适用题材下的艺术动效方法 |
sweety-image-privacy | 图像隐私元数据清理与审计 |
安装与第一次运行
README 建议先用几十秒的短主题确认本机环境与画风，再处理长稿。
1. 安装 Skill
具备 Node.js / npm 时，README 的一条命令装到两个宿主：
npx skills add threerocks/sweety-handdraw-video --skill sweety-handdraw-video --agent claude-code codex --global --copy --yes
安装位置：Claude Code 为 ~/.claude/skills/sweety-handdraw-video，Codex 为 ~/.agents/skills/sweety-handdraw-video（该命令写入的通用目录）。只装一个宿主时去掉另一个 --agent 值。不加 --global 则装进当前项目（Claude Code 为 .claude/skills/）。此命令安装仓库当前公开内容。
要固定本版，用 v1.4.1 安装包。全部版本 同页有 SHA256SUMS.txt，README 给出的校验命令是：
shasum -a 256 -c SHA256SUMS.txt
更新仓库不会自动更新已安装的副本。替换完整 Skill 目录后，读取其中的 VERSION，本版应为 1.4.1。
手动安装：把包内的 sweety-handdraw-video 整个文件夹放进宿主的 Skills 目录，例如 ~/.claude/skills/sweety-handdraw-video（Claude Code）或 ~/.codex/skills/sweety-handdraw-video（Codex）。更新前备份旧目录。只复制 SKILL.md 会缺少脚本、素材和内置依赖。手部、画风预览与试听已随包提供（约 38 MB），装好即可离线使用。
2. 准备运行环境
bash ~/.claude/skills/sweety-handdraw-video/scripts/setup.sh # 或 Codex 安装目录下的同名脚本
bash ~/.claude/skills/sweety-handdraw-video/scripts/setup.sh --check # 只检查，不安装
setup.sh 会安装或检查 FFmpeg，在 Skill 目录之外建立上面的 Python 虚拟环境并安装 scripts/requirements.txt，然后核验安装包并报告实际选用的字体。它不会下载配音模型。
3. 制作前检查
README 把检查命令写成相对路径（JOB 是其中的任务目录写法）：
python scripts/handdraw_video.py doctor JOB
它分别报告「能否渲染」「能否生成旁白」和生图能力提示，并对每个缺失项给出修复命令。也可以先跑 bash scripts/setup.sh --check。
4. 按 README 的顺序制作
| 顺序 | README 的做法 |
|---|---|
| 1 | 确定讲什么：受众、原文约束、关键事实和讲解路线 |
| 2 | 先把声音做完整：按语义段落生成并过门禁，拼成母带并自动对齐 |
| 3 | 用分镜算预算再出图。封面、正文、角色、道具等出图前先应用 sweety-image-art-direction；缺少指导记录、空文件、提示词或图片改变、视觉审查未通过，都会停止生产 |
| 4 | 按时间戳描线或揭示插画、按笔顺写关键句、填色、排字幕与换场 |
| 5 | 检查代表场景，再导出全片。工程检查（含声音门禁、字幕同步）与实际看图、听音分开记录 |
交付包含 MP4、封面 PNG、SRT、口播稿与检查记录。制作目录保留素材、配置与时间戳。MP4 写入 AIGC 隐式标识元数据。
在 Claude Code 中直接说「用 sweety-handdraw-video 把……做成手绘视频」，或输入 /sweety-handdraw-video。Codex 中使用 $sweety-handdraw-video。提示词见下一节。
在 Claude Code 里用 Opus 5.5 驱动它
在 Claude Code 里用 /model 选 Opus 5.5，详见 Claude Opus 5.5。
调用入口是 /sweety-handdraw-video，或直接说「用 sweety-handdraw-video 把……做成手绘视频」。开始时提供六项选择：画风、手部、声音、笔杆广告、水印、字幕。已经写明的项目会跳过；每个未选项目最多等 60 秒，随后采用模型根据内容拟定的方案。说「全部自动选择」会直接继续。广告与水印默认不加。
下面三段是 README 的示例，调用名是 Codex 的 $sweety-handdraw-video：
使用 $sweety-handdraw-video，把“为什么越生气，越容易做错决定”
做成一段面向普通成年人的手绘讲解。先讲清楚一个机制，控制在约一分钟。
画风、手部、声音和字幕由你根据内容选择，不加广告和水印。
使用 $sweety-handdraw-video，把下面的完整故事做成视频。
正文按原文，不改写。使用自定义淡彩速写、毛笔手部、无底板字幕。
声音使用我已确认的本机参考，不加背景音乐。
【粘贴故事】
使用 $sweety-handdraw-video，把这篇文章做成手绘讲解视频。
保留数字、来源和适用条件。画面用风格 17，手部用仅画笔。
笔杆文字：@leo_xiaolei。水印：@leo_xiaolei。
先检查一个代表场景，确认文字可读后完成整片。
【粘贴文章】
示例提示词（按 README 写明的用法改写，不是仓库原文）：
使用 /sweety-handdraw-video，把“为什么睡少了更容易发脾气”
做成一段面向普通成年人的手绘讲解。先讲清楚一个机制，控制在约一分钟。
画风用 17，手部用 pen-only，字幕用 quiet，不加广告和水印。
使用 /sweety-handdraw-video，把下面的文章做成手绘讲解视频。
保留数字、来源和适用条件。画面用风格 4，手部用 teacher-pen。
声音使用我已核对的完整旁白和时间戳，本次不重新合成。
字幕用 plate。先检查一个代表场景，确认文字可读后完成整片。
【粘贴文章】
限制与已知问题
- README 写明完整制作流程在 macOS + Codex 上跑通。Claude Code 写明已验证的是安装与本地脚本，使用前要自备生图工具、MCP，或自己的插画。
- 版本说明（v1.4.1）写「原生选项（模型推理/主动选择），默认竖屏 9:16」。后文「开始制作」和制作选项表写的未指定默认值是简体中文、1920×1080、30fps。同一篇 README 里两处都保留着；下一次请求里写明画布尺寸。版本说明还写导演
presentation.mode控制单页疏密，正文没有列出该字段的可选值。 - 其他尺寸要重新检查构图、字号与遮挡。
- 公开的蛇片与「快乐囚禁」样片是 v1.2。蛇片 v1.2 原版旁白带 235 Hz 持续嗡声，v1.3 门禁会拦下这种声音。样片带预告水印。
- 21 个画风入口不等于 21 种都做过同等强度的成片验证。揭示模式不能靠超时或委托自动换上。
- 橡皮擦转场没有交付证据，不列为现成功能。GB2312 以外的字符按字形轮廓描线，不按标准笔顺。
- 同一系列可以固定画风配方、生图端、角色锚点、手部与声音参考。仍可能出现角色、剧情或音色漂移。README 写明当前不是承诺任意输入稳定通过的无人审核批量系统。
- 只改字幕、笔杆文字、水印或画面布局时，可复用未变化的图和声音，再渲染并检查。修改口播正文时，只重新生成文字变了的语义段落（分段位置不变时其余段落复用），再重新拼接母带；换段处的语气衔接仍需试听。
- VoxCPM2 这条适配器不是 Windows / NVIDIA 方案。README 写明作者环境为 M3 Max、36GB 内存；所用 VoxCPM2-8bit 权重约 3.23 GB，权重大小不等于运行内存。尚未测定 8GB / 16GB 设备的最低可用条件，也不给出全机型耗时。
- 火山豆包 / Gemini TTS 不是默认路径，仓库未真实调用。
- 逼真男声、逼真女声的原始参考不在公共安装包里。未导入时可以试听，不能选它们来生成。
- MP4 里的 AIGC 元数据只是文件内的隐式标识。发布到平台时仍须按平台要求声明「AI 生成」。声音、人物和第三方内容的权利需自行确认。
- v1.3 记录写 158 项回归通过（1 项平台用例跳过）、离线冒烟短片通过，并写明该结果不能替代视频观感、故事事实、听感或学习效果验收。v1.4.1 新增的是发布一致性检查和实际画面范围检查。
- 仓库 issue #2（open）：标题是「我明确自己手动选风格和画笔，为啥打自己决定了」。用户指定了风格和画笔，结果仍变成自动决定。
- 仓库 issue #1（open）：标题是「[Windows] 回归测试未关闭 NPZ 文件，临时目录清理触发 WinError 32」。Windows 上回归测试清理临时目录时触发 WinError 32。README 对 Windows 的说法仍是暂不承诺。
常见问题
能不能用 Codex 或 Cursor？
可以按 README 使用 Codex 和 Claude Code。Claude Code 的入口是 /sweety-handdraw-video，Codex 是 $sweety-handdraw-video。README 写明完整制作流程在 macOS + Codex 上跑通；Claude Code 需要生图工具或 MCP，或由用户提供插画。Cursor：README 未写明。Windows 与 Gemini 等其他组合，README 写明暂不承诺。
成品是 HTML 还是 MP4？
交付包含 MP4、封面 PNG、SRT、口播稿与检查记录。当前主渲染实现是 Python / Pillow / SciPy / FFmpeg。制作前用 python scripts/handdraw_video.py doctor JOB 看能否渲染、能否生成旁白。MP4 带 AIGC 隐式标识；发布时仍要按平台规则声明「AI 生成」。
商用和许可怎么算？
README 写明主项目代码与文档采用 MIT。内置项目保留各自的版权与许可证。AI 生成手部、参考音频等素材不因此获得真人身份或官方角色授权。第三方内容与声音的使用仍需自行确认权利。笔杆广告和水印默认不加，样片里的作者宣传文字不属于安装后的强制内容。
中文口播和字幕能做吗？要不要 API key？
未指定时采用简体中文。GB2312 范围内的汉字按标准笔顺逐笔书写，笔画数据来自 hanzi-writer-data（Arphic 公共许可）；其余字符按字形轮廓描线。字幕默认白字黑边，quiet 无底板，plate 有底板，全程只允许一套字幕，由一个图层负责。
配音走 VoxCPM2、本机 VoiceStudio，或已经核对的完整旁白和时间戳时，README 写明本地合成这条路径无需另接云端 TTS 账号。可选的火山豆包 / Gemini TTS 才使用你自己的环境变量密钥，而且不是默认。README 提醒：模型宿主和生图能力可能另行收费。
相关阅读
- 热门项目合集
- 用 Opus 5.5 做视频
- 从提示词到成片
- 场景模板
- 报错与省用量
- 开源 Skill 与工具
- Claude Opus 5.5
- 环境搭建
- 开源 AI 视频 Skill 目录
- Claude Motion（官方功能）
- animate 教程
- ClaudeAnimationBase 教程
- claude-motion-design 教程
- mg-styles-15 教程
- lemo-opuscar 教程
- herk-edit-kit 教程
参考来源
- threerocks/sweety-handdraw-video（查阅日期：2026-10-23）
- 仓库 README.md（查阅日期：2026-10-23）
- 仓库 issue #1、#2 的标题与开关状态（查阅日期：2026-10-23）
- 仓库元数据中的星数、最近推送、创建时间、许可与描述（查阅日期：2026-10-23）