sweety-handdraw-video README

The project's README from github.com/threerocks/sweety-handdraw-video. As one markdown file: README.md.

sweety-handdraw-video · 手绘口播

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

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

那条死于愤怒的蛇

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

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

精选样片

《那条死于愤怒的蛇》 · 49 秒

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

蛇:实际描绘过程

播放或下载完整 MP4

《快乐囚禁你的方式》 · 1 分 52 秒

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

快乐囚禁你的方式

狼:实际描绘过程

播放或下载完整 MP4

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

更多题材:概念讲解与较长叙事

《墨菲定律》:约 2 分 05 秒,8 个画面、24 段口播,解释准备如何降低失误的代价。使用淡彩速写、女性碎钻长甲手及笔杆文字。它是公开 v1.0.0 的历史样片,不代表最新的连续旁白流程。

墨菲定律

下载《墨菲定律》 · 查看《不是你在努力,是有人想让你努力》的作者展示帖

较长样片用于展示叙事跨度,不代表短观点也应做成长视频。

它适合做什么

输入 交付方向
一个主题 整理讲解路线,设计生活场景、机制与行动建议
一篇文章或参考资料 保留重要事实、数字和限定,改成适合听与看的口播
完整故事或定稿 按原文制作;要求保留原文时,不擅自重写
已认可的图、声音和稿件 复用素材,针对字幕、手部、画面或时间线进行修订

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

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

导演如何参与制作

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

导演判断 在手绘口播中的执行方式
受众与目标 明确观众看完应理解什么,决定切入点与信息密度
叙事路线 故事保留行动与因果;原理可用对照、变化或操作过程;用户定稿与原文要求优先
分镜与画面作用 每幅图说明它比直接显示这句话多解释了什么,列出必须可见的动作、接触与结果
构图和一致性 确定主次、角色与道具参考、色彩、留白,避免跨画面随意漂移
节奏和声画关系 一个完整意思讲完再换场;按实际旁白决定描线、填色、关键字和停留时间
成片审查 查看缺失的剧情动作、重复信息、遮挡、阅读时间与声音对应,失败时修改受影响部分

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

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

安装与环境

1. 安装 Skill

具备 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 会缺少脚本、素材和内置依赖。

2. 确认运行条件

条件 用途与边界
能读取 Skill、执行本地命令的 Agent 当前完整制作实测使用 Codex。其他宿主、模型组合尚未完成相同验证
可用的图像生成能力 默认 Codex 内置生图;仅有文字聊天能力不足以完成新插画
Python 3.9+ 本地绘制与合成;建议使用独立虚拟环境
Pillow、NumPy、SciPy、requests 由随包 scripts/requirements.txt 安装
FFmpeg 与 ffprobe 合成、编码、解码与音视频检查
中文字体 正文手写字与常规字幕分开配置;不随包分发系统商业字体
Bun 与 ExifTool 运行 sweety-image-privacy 清理图片元数据并保存审计记录
一种可用配音路径 已配置的本地 VoxCPM2、兼容的 VoiceStudio,或已核对的完整旁白与时间戳
Node.js / npm(可选) 仅用于上面的安装命令;手动安装不依赖它

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

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。

3. 选择配音路径

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

路径 需要准备 已验证范围
VoxCPM2 本地适配器 Apple Silicon Mac、独立 MLX 环境、mlx-audio / mlx / soundfile、已下载模型与真实路径 本项目使用 VoxCPM2-8bit MLX;当前适配器不是 Windows / NVIDIA 部署方案
VoiceStudio 本机服务 能提供兼容 HTTP API 的本机服务,已配置 TTS 引擎 默认 http://127.0.0.1:3900;已对接 mlx-audio / Qwen3-TTS-12Hz-1.7B-Base-bf16
现成整篇旁白 已检查的音频及其时间戳 可离线编排和渲染;本次无需重新合成声音

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 秒,随后采用模型根据内容拟定的方案。说“全部自动选择”会直接继续。广告与水印默认不加。

全部制作选项

项目 可以怎么选
内容 主题、资料、文章、完整故事;明确要求原文时保留原文
导演与叙事 指定受众、切入点、叙事顺序、信息密度、强调与收尾;也可委托模型根据内容规划
画风 指定库内编号、模型从库内匹配、模型独立设计、自定义描述
手部 六款手臂预设、仅画笔;支持有定位参数的自定义素材
声音 六款可下载合成参考、自行导入原片参考、已验收的本机声音、现成旁白
笔杆文字 最多 16 个 Unicode 字符;空白即不加;长文字需检查实际可读性
水印 最多 180 字符,支持换行;低对比、缓慢浮动;空白即不加
字幕 默认白字黑边;quiet 无底板 / plate 有底板;全程只允许一套字幕
正文文字 手写关键句与插画分别编排;字形四边预留余量
画布与帧率 默认 1920×1080、30fps;其他尺寸需重新检查构图、字号与遮挡
节奏 根据旁白时间戳安排描线、填色、文字、抬笔和停留;可提出快慢要求
音乐与音效 默认纯旁白;必要音效逐项说明用途,背景音乐不自动添加
封面与片尾 1 秒封面;默认片尾停留 0.45 秒;结束语须写入完整旁白
修订 可复用已通过的图和声音;相关素材改变后重新检查受影响部分

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

21 个库内画风入口

选择方式 依据与执行
直接选编号 用户看真实效果预览并指定,沿用对应完整配方
库内自动匹配 模型根据内容从库内选择,记录理由与完整配方
模型独立推理 独立设计线条、颜色、明暗、材质与背景,不以某个编号兜底
自定义描述 用户描述是画风依据;模型只补足可执行细节,不能因内容偏好擅自换风格

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

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

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

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

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

六款手臂与仅画笔

六款手部预设

预设 标识
深蓝袖马克笔 navy
女性柔粉碎钻长甲 diamond-woman
儿童彩铅 child-pencil
上官婉儿灵感毛笔 waner-brush
白衬衫中性笔 teacher-pen
针织袖钢笔 cardigan-fountain
仅画笔,不显示手臂 pen-only

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

笔杆广告与浮动水印

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

选项 位置与用途 规则
笔杆广告 跟随画笔,适合品牌短名或账号 最多 16 个字符;保留原文;长文字优先宽笔杆并检查实际可读性
浮动水印 位于画面内,用于账号、归属或简短发布信息 最多 180 字符,可换行;默认低对比、缓慢移动,避开底部字幕

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

声音目录与参考

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

名称 试听 生产参考
逼真男声 《那条死于愤怒的蛇》节选 沿用该片原始参考;公共安装需自行导入
逼真女声 《快乐囚禁你的方式》节选 沿用当前原片提取人声;公共安装需自行导入
甜美学姐 同文试听 可下载合成参考
Iapetus 同文试听 可下载合成参考,并非直接调用 Gemini 原生 TTS
知性女讲师 同文试听 可下载合成参考
故事解说 同文试听 独立保留的合成参考

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

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

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

从输入到成片

  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。以下五项以固定快照内置,不需要分别安装;运行时不会自动追踪上游更新:

内置项目 用途
sweety-image-art-direction 主体、接触关系、构图、比例与观看主次
hand-drawn-styles 风格配方、参考锚点与预览
omniailab-ai-director 导演规划、叙事、声画关系与终审方法
huashu-art-motion 适用题材下的艺术动效方法
sweety-image-privacy 图像隐私元数据清理与审计;本项目随后移除模拟相机字段

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

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。

v1.2 素材与字幕规则

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

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

每次出图都先做美术指导

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

sweety-handdraw-video (threerocks/sweety-handdraw-video)

Searching Database…

What is this?It's an AI Agent Skill that turns a topic, article, or finished story into a complete hand-drawn narrated video: an agent writes the script and storyboard and generates the illustrations, while local tools trace the strokes, hand-write the text, sync narration and export the final MP4.
Is this a standalone app or something I plug into an AI agent?It is a Skill package meant to be loaded into a coding agent (Codex) rather than run on its own; you drop the folder into the agent's Skills directory and the agent then drives local Python/FFmpeg scripts to actually render the video.
What do I need on my machine besides the agent?Python 3.9+ with Pillow, NumPy, SciPy and requests (installed from the bundled requirements.txt), FFmpeg/ffprobe, Chinese fonts for the handwriting and subtitles, Bun plus ExifTool for image metadata cleanup, and a working voice path (local VoxCPM2, VoiceStudio, or a pre-checked narration track).
Does it work on Windows or with agents other than Codex?The full pipeline has only been fully verified on an Apple Silicon Mac running Codex; Windows and other agent or image-model combinations have not completed full validation, so you should confirm execution, image generation, fonts and voice support before switching setups.
Does it do anything with image metadata or personal recordings?A bundled sub-tool, sweety-image-privacy, strips metadata from every generated image and keeps an audit record, and original voice reference recordings for the showcase videos stay on the author's machine and are not shipped in the public install.
Is this actually free to run end-to-end?The code itself is MIT-licensed and free, but the agent host and image generation capability may require a paid plan, and local voice synthesis still consumes hardware, power and time; the author notes one ~2.5-minute video used under 1% of a $200 subscription quota, which is not a guaranteed cost.
How many art styles and voice options are included?There are 21 built-in illustration styles (from minimalist black-and-white lines to pixel art and watercolor), 6 hand/arm presets or a pen-only mode, and 6 fixed voice options you can pick directly or let the model choose.
If I just need to fix one subtitle, do I have to regenerate everything?No — changes to subtitles, pen-text or watermark/layout reuse the existing images and audio and just re-render; editing the actual narration script, however, usually forces a full voiceover re-synthesis and timeline re-alignment.
Can it reliably produce a whole video series in batch?You can lock a style recipe, image model, character anchors and voice reference for consistency across episodes, but character, plot or voice drift can still occur, so every episode still needs manual review — it is not an unattended batch system.
Creator
threerocks
Size
57.2 MB
Stars
687
Age
6d
Commits · 90 Days