threerocks/sweety-handdraw-video

给一个主题、一篇文章或完整故事，做成边画边讲的有声视频。

Agent 负责理解内容、写口播、设计分镜和生成插画；本地工具负责逐笔描线、填色、手写文字、配音对齐与导出。画什么、用什么画风、讲多久，按内容决定。

看有声样片 · 安装与环境 · 开始制作 · 全部制作选项 · 常见问题 · 关注作者

封板版本：v1.2；最新补丁：v1.2.3（2026-10-13）。单套黑边字幕、完整旁白流程、制作选项与素材按需缓存纳入本次封板；以包内 VERSION 和 Git 标签为准。

从蛇与锯子的冲突，讲到愤怒如何放大伤害。适合先看短片的叙事密度、画面部位的出现顺序，以及旁白和落笔的配合。使用淡彩叙事插画、毛笔手部与无底板字幕。

播放或下载完整 MP4

冷色棱角插画，女性手部，连续女声旁白。展示同一条故事内的画面一致性，以及完整旁白先生成、画面随后对齐的制作方式。当前女声暂时保留，听感仍待后续调整；原片音色参考继续保存在本地。本次只修字幕，音轨字节保持不变。

播放或下载完整 MP4

这两条 MP4 均为 1920×1080、30fps，保留制作时的预告水印；水印文字不代表当前发布时间。GIF 是成片的无声节选，判断音色和节奏请播放完整视频。

适合知识讲解、故事寓言、观点表达、产品原理和教学内容。优势在于把口播、画面与绘制过程放在同一条制作流程里：

• 画风跟随内容：21 个库内入口，也可让模型独立设计，或提供自定义方向。
• 整篇声音先行：保留句间停顿和换气，再安排画面与字幕，避免逐页拼配音产生固定空白。
• 按部位画出来：先按语义部位完成轮廓，再按相同顺序填色；文字逐字绘制，笔画间抬笔。
• 可以定位修改：保留脚本、素材、声音、时间戳和检查记录，修字幕不必重新生图。
• 运行与观感分别检查：文件能播放、声音清楚、剧情画对，是不同检查项。

它仍是需要 Agent、图像生成与本地运行环境的制作 Skill；成片不使用外部图生视频模型。当前主渲染实现是 Python / Pillow / SciPy / FFmpeg。

内置 omniailab-ai-director 的导演方法，用在创作规划、分镜和最终审片。模型要把判断落实到具体画面与时间线：

可以在需求里指定导演处理方式，例如“直接从冲突开始”“按老师讲题的顺序做对照”“关键结果出来后留时间看清”“保留原文结尾”。未指定时，模型根据内容规划，不硬套固定页数和每页时长。

导演判断写进创作方案，由本地渲染执行；不是一个独立运行的导演模型，也不自动启用上游影视生成平台。更广泛的导演资料按需取用，不能等同于本项目已验证了上游的全部影视能力。详见 创作与分镜 与 依赖分工。

具备 Node.js / npm 的环境可使用：

npx skills add threerocks/sweety-handdraw-video --skill sweety-handdraw-video

此命令安装仓库当前公开内容。需要固定本版时，使用 v1.2.3 安装包。

手动安装：将包内的 sweety-handdraw-video 整个文件夹放入宿主的个人 Skills 目录。Codex 示例：~/.codex/skills/sweety-handdraw-video。更新前备份旧目录；仅复制 SKILL.md 会缺少脚本、素材和内置依赖。

在仓库根目录安装渲染依赖：

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r skills/sweety-handdraw-video/scripts/requirements.txt
python skills/sweety-handdraw-video/scripts/validate_package.py

以上是 macOS / Linux 命令。依赖版本范围：Pillow >=10,<12，NumPy >=1.24,<3，SciPy >=1.10,<2，requests >=2.31,<3。Python 渲染依赖的安装不会同时装好配音模型、字体、FFmpeg、Bun 或 ExifTool。

音色与配音后端分开选择。 六款内置音色提供真实的参考音频与同文试听，后端负责把本次正文生成声音。也可以导入自己的参考，或沿用已验收的本机主力声音。

VoiceStudio 需要 /engines/tts、/generate 及可选 /transcribe 接口。任意同名软件不一定兼容。两条生成路径都先提交完整脚本，再核对漏读、重复、尾音和时间戳。

为什么保留这几条路径？ 本项目引入 VoxCPM2 是为了改善长段旁白的自然度与参考音色延续，并在作者的 Mac 上实际测试 MLX 8-bit 路径；当前新版女声暂用，作者仍认为听感有差距，后续会继续调整。VoiceStudio 则保留已经可用的本机服务，避免要求所有用户更换声音环境。已有满意的整篇旁白时，直接复用可以省去再次合成。这里没有宣称一个后端在所有声音、稿件和机器上都更优。

本地合成便于保留参考、参数和生成记录，这条路径无需另接云端 TTS 账号；代价是需要自行准备模型与计算资源。VoiceStudio 是服务接口，Qwen3-TTS / VoxCPM2 才是模型，不能把服务名称、音色名称和模型名称混为一谈。

模型权重不在 Skill 包内，运行脚本不会自动购买服务、下载模型或切换全局声音引擎。带噪参考可能额外需要人声分离或降噪；HTDemucs / DeepFilterNet3 是本次女声修复使用的可选工具，不是所有用户都必须安装的基础依赖。

硬件实测：当前作者环境为 M3 Max、36GB 内存。使用的 VoxCPM2-8bit 权重约 3.23GB；权重大小不等于运行内存需求。本项目尚未测定 8GB / 16GB 设备的最低可用条件，也不据此给出全机型耗时承诺。

详细接入参数见 本地运行环境 与 环境检查表。

先用几十秒的短主题确认本机环境与画风，再处理长稿。可直接发给 Agent：

使用 $sweety-handdraw-video，把“为什么越生气，越容易做错决定”
做成一段面向普通成年人的手绘讲解。先讲清楚一个机制，控制在约一分钟。
画风、手部、声音和字幕由你根据内容选择，不加广告和水印。

使用 $sweety-handdraw-video，把下面的完整故事做成视频。
正文按原文，不改写。使用自定义淡彩速写、毛笔手部、无底板字幕。
声音使用我已确认的本机参考，不加背景音乐。

【粘贴故事】

使用 $sweety-handdraw-video，把这篇文章做成手绘讲解视频。
保留数字、来源和适用条件。画面用风格 17，手部用仅画笔。
笔杆文字：@leo_xiaolei。水印：@leo_xiaolei。
先检查一个代表场景，确认文字可读后完成整片。

【粘贴文章】

未指定时采用简体中文、1920×1080、30fps。时长由实际口播决定；“约一分钟”是创作目标，不靠拉长空白凑时间。默认有 1 秒封面，前 0.5 秒静止、后 0.5 秒渐隐。

开始时提供六项选择：画风、手部、声音、笔杆广告、水印、字幕。已明确的项目跳过；每个未选项目最多等 60 秒，随后采用模型根据内容拟定的方案。说“全部自动选择”会直接继续。广告与水印默认不加。

以上是制作请求可以表达的选择，不代表每一项都有独立可视化滑块。详细字段见 制作选项、字幕与片尾。

库内为 20 个编号风格 + 3.1 稳定变体，每项附在线真实效果预览与完整配方，图片不再打进代码包。它们是静态美术方向，不表示每一种都已经做过相同强度的视频验证。

不想受风格库限制时，选择“模型推理产出”或给自定义描述。模型仍须写出画风方案、审查实际插画，再制作绘制路径。完整定义见 STYLES.md。

展开 21 种实际画风预览

1 · 极简黑白线条	2 · 蜡笔童涂	3 · 吉卜力风
3.1 · 潦草自画稳定变体	4 · 小豆人涂鸦信息图	5 · MS Paint 烂涂鸦
6 · 圆珠笔单线涂鸦	7 · 蜡笔实拍	8 · 水墨写意
9 · 复古像素	10 · 淡彩速写	11 · 二维水彩
12 · 暖光童画	13 · 北欧纸雕	14 · 北欧绘本水粉
15 · 大鼻软偶	16 · 聚光水粉	17 · 墨线绘本
18 · 暖色扁平绘本	19 · 圆头红线童画	20 · 暖黄墨线小剧场

这些预览展示静态画风；实际绘制节奏以成片为准。

手臂素材按笔尖位置与手腕距离校准，前臂裁切边留在画外。自定义素材需要提供笔尖定位等参数，不能将任意图片直接视为已经适配。笔杆广告只放在笔杆，不自动加品牌或版权声明。

两个独立可选项，默认均为空。样片中的作者宣传文字不属于安装后的强制内容。

例如：“笔杆写 @leo_xiaolei；水印写『手绘口播 · @leo_xiaolei』，淡一点，避开字幕。”也可以明确说“不加广告和水印”。

只保留以下六款，选择器和文字引导使用相同名称与顺序。

前两项播放对应成片节选，其余四款播放同一段文本。成片节选只用于试听，不能反过来当作原片参考继续克隆。逼真女声目前暂用，听感仍待调整；改名不代表新增听感验收。

作者本机已保存两款逼真声音的原始参考，可以直接选择。公共安装包不含这些录音：未导入时可以试听，但不能选择它们生成。导入方法见本地声音运行。个人目录和任务目录只能补充这六项的参考，不能把其他音色或旧名称加回选择器。

可直接指定这六个名称之一，也可委托模型根据稿件选择。已有本机默认声音时优先沿用，本次明确选择优先。声音参考、逐字稿与生成参数分别保留；更换后端或稿件后仍需试听。

1. 确定讲什么。 明确受众、原文约束、关键事实和讲解路线，避免把简单观点拖成长片。
2. 确定画什么。 做分镜、美术指导与可绘制计划，生成插画并实际检查关键剧情和接触关系。
3. 先把声音做完整。 合成整篇旁白，核对文字、杂音、漏读、重复和片尾，锁定声音母带。
4. 用声音安排画面。 按时间戳绘制语义部位、逐字写关键句、填色、排字幕与换场。
5. 检查代表场景，再导出全片。 工程检查与实际看图、听音分开记录，失败项修复后再交付。

交付包含 MP4、封面 PNG、SRT、口播稿与检查记录；制作目录保留素材、配置与时间戳，方便追溯和修订。

一条视频要多久、多少钱？

作者此前对一条约两分半样片的回答是“差不多 10 分钟”；在自己的 200 美元订阅环境中，观察到额度使用“不到 1%”。这是特定作品与账号的自述，未做统一计量，不能换算成固定单价或服务承诺。首次装环境、模型下载、排队、出图重试、配音修复和人工检查都会改变耗时。耗时原回复 · 额度原回复

开源不等于全链路免费。模型宿主与生图能力可能收费；本地配音仍消耗硬件、电力和时间。当前成片流程不额外依赖按视频秒数收费的图生视频服务。

改一句话，要全部重做吗？

只改字幕、笔杆文字、水印或画面布局，可复用未变化的图和声音，重新渲染并检查。修改口播正文会影响连续旁白，通常需要重新生成整篇母带、重做对齐和受影响的时间线；目前不承诺无痕的单句声音替换。

能稳定做系列、批量出片吗？

同一系列可以固定画风配方、生图端、角色锚点、手部与声音参考，并复用已认可素材。仍可能出现角色、剧情或音色漂移，因此每条都要检查。当前不是承诺任意输入稳定通过的无人审核批量系统。

Windows / Linux / Gemini / Claude 能用吗？

当前完整流程验证来自 Apple Silicon Mac + Codex。v1.0.0 曾有 Linux CI 的依赖、回归和短片合成记录；它不等于新版本地 TTS 在 Linux 上通过。Windows 与其他 Agent / 生图组合尚未完成整流程验证。先确认执行、生图、字体与配音能力，再判断能否迁移。

为什么没有背景音乐，仍要检查杂音？

参考音频可能带配乐或噪声，声音合成也可能产生伪影。不添加音乐只说明没有额外混音轨，不证明旁白干净。程序指标和 ASR 不能代替听感验收。

会按规范汉字笔顺写吗？有橡皮擦转场吗？

当前按字形轮廓逐字绘制，不保证规范书法笔顺。橡皮擦转场属于收到的建议，尚无本版本交付证据，不列为现成功能。

安装目录只注册一个 Skill。以下五项以固定快照内置，不需要分别安装；运行时不会自动追踪上游更新：

来源、许可证和固定快照见 依赖说明 与 第三方声明。

python -m unittest discover -s skills/sweety-handdraw-video/scripts -p 'test*.py' -v
python skills/sweety-handdraw-video/scripts/smoke_test.py --output /tmp/handdraw-smoke-new
python3 tools/package.py --output dist

v1.2.3 记录：59 项回归通过、1,215 个内置依赖文件核验、21 个风格预览检查。该结果不能替代视频观感、故事事实、听感或学习效果验收。更多记录见 验证范围。

本次 v1.2 封板包含整篇连续旁白、纯旁白默认、剧情检查与片尾保护、原片参考导入、声音来源追踪、可选离线降噪、本机主力声音目录，以及字幕唯一性和素材缓存检查。此前本地 1.3/1.4/1.4.1 为未公开的开发迭代号；公开标签按本次指定固定为 v1.2。

主项目代码与文档采用 MIT。内置项目保留各自的版权与许可证；AI 生成手部、参考音频等素材不因此获得真人身份或官方角色授权。第三方内容与声音的使用仍需自行确认权利。

感谢 花叔的 huashu-art-motion、OmniAiLab AI 导演、手绘风格库与美术指导提供的方法，也感谢评论区关于停顿、字幕、女声、改稿和运行环境的具体反馈。

觉得有用，给仓库点一个 Star；制作结果与问题欢迎附上版本、运行环境和可复现片段提交 Issue。演示和更新见 @leo_xiaolei。

公开素材独立放在 GitHub Release 附件，手部和声音预设首次使用时按需下载，并核对大小和 SHA-256；有效缓存可离线复用。Netlify 当前因团队额度耗尽暂停，按作者确认暂用 GitHub。原片声音参考仍只存本地。详见托管与缓存。

字幕只由一个图层负责。禁止重复事件、额外内嵌字幕轨和同目录自动加载字幕；编辑文件放入 editing/，预览页不挂字幕轨。最终实际画面仍须检查，不能以程序检查替代观看。

v1.2.1 增加简报和实际提示词的非空检查、内容哈希绑定，以及 7 项针对性回归。封面、正文、角色、道具、新手部、候选、编辑和返工均须先应用内置 sweety-image-art-direction；缺少指导记录、空文件、提示词改变、图片改变或视觉审查未通过都会停止生产。它约束流程与证据，不能代替模型实际看图。