给一个主题、一篇文章或完整故事，做成边画边讲的有声视频。
Agent 负责理解内容、写口播、设计分镜和生成插画；本地工具负责逐笔描线、填色、手写文字、配音对齐与导出。画什么、用什么画风、讲多久，按内容决定。
看有声样片 · 安装与环境 · 开始制作 · 全部制作选项 · 常见问题 · 关注作者
封板版本：v1.2；最新补丁：v1.2.3（2026-10-13）。单套黑边字幕、完整旁白流程、制作选项与素材按需缓存纳入本次封板；以包内
VERSION和 Git 标签为准。
从蛇与锯子的冲突，讲到愤怒如何放大伤害。适合先看短片的叙事密度、画面部位的出现顺序，以及旁白和落笔的配合。使用淡彩叙事插画、毛笔手部与无底板字幕。
冷色棱角插画，女性手部，连续女声旁白。展示同一条故事内的画面一致性，以及完整旁白先生成、画面随后对齐的制作方式。当前女声暂时保留，听感仍待后续调整；原片音色参考继续保存在本地。本次只修字幕，音轨字节保持不变。
这两条 MP4 均为 1920×1080、30fps，保留制作时的预告水印；水印文字不代表当前发布时间。GIF 是成片的无声节选，判断音色和节奏请播放完整视频。
更多题材：概念讲解与较长叙事
《墨菲定律》：约 2 分 05 秒，8 个画面、24 段口播，解释准备如何降低失误的代价。使用淡彩速写、女性碎钻长甲手及笔杆文字。它是公开 v1.0.0 的历史样片，不代表最新的连续旁白流程。
下载《墨菲定律》 · 查看《不是你在努力，是有人想让你努力》的作者展示帖
较长样片用于展示叙事跨度，不代表短观点也应做成长视频。
| 输入 | 交付方向 |
|---|---|
| 一个主题 | 整理讲解路线，设计生活场景、机制与行动建议 |
| 一篇文章或参考资料 | 保留重要事实、数字和限定，改成适合听与看的口播 |
| 完整故事或定稿 | 按原文制作；要求保留原文时，不擅自重写 |
| 已认可的图、声音和稿件 | 复用素材，针对字幕、手部、画面或时间线进行修订 |
适合知识讲解、故事寓言、观点表达、产品原理和教学内容。优势在于把口播、画面与绘制过程放在同一条制作流程里：
- 画风跟随内容：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 会缺少脚本、素材和内置依赖。
| 条件 | 用途与边界 |
|---|---|
| 能读取 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。
音色与配音后端分开选择。 六款内置音色提供真实的参考音频与同文试听，后端负责把本次正文生成声音。也可以导入自己的参考，或沿用已验收的本机主力声音。
| 路径 | 需要准备 | 已验证范围 |
|---|---|---|
| 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 秒；结束语须写入完整旁白 |
| 修订 | 可复用已通过的图和声音；相关素材改变后重新检查受影响部分 |
以上是制作请求可以表达的选择，不代表每一项都有独立可视化滑块。详细字段见 制作选项、字幕与片尾。
| 选择方式 | 依据与执行 |
|---|---|
| 直接选编号 | 用户看真实效果预览并指定，沿用对应完整配方 |
| 库内自动匹配 | 模型根据内容从库内选择，记录理由与完整配方 |
| 模型独立推理 | 独立设计线条、颜色、明暗、材质与背景，不以某个编号兜底 |
| 自定义描述 | 用户描述是画风依据；模型只补足可执行细节，不能因内容偏好擅自换风格 |
库内为 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 · 极简黑白线条 |  2 · 蜡笔童涂 |  3 · 吉卜力风 |
 3.1 · 潦草自画稳定变体 |  4 · 小豆人涂鸦信息图 |  5 · MS Paint 烂涂鸦 |
 6 · 圆珠笔单线涂鸦 |  7 · 蜡笔实拍 |  8 · 水墨写意 |
 9 · 复古像素 |  10 · 淡彩速写 |  11 · 二维水彩 |
 12 · 暖光童画 |  13 · 北欧纸雕 |  14 · 北欧绘本水粉 |
 15 · 大鼻软偶 |  16 · 聚光水粉 |  17 · 墨线绘本 |
 18 · 暖色扁平绘本 |  19 · 圆头红线童画 |  20 · 暖黄墨线小剧场 |
这些预览展示静态画风；实际绘制节奏以成片为准。
| 预设 | 标识 |
|---|---|
| 深蓝袖马克笔 | navy |
| 女性柔粉碎钻长甲 | diamond-woman |
| 儿童彩铅 | child-pencil |
| 上官婉儿灵感毛笔 | waner-brush |
| 白衬衫中性笔 | teacher-pen |
| 针织袖钢笔 | cardigan-fountain |
| 仅画笔，不显示手臂 | pen-only |
手臂素材按笔尖位置与手腕距离校准，前臂裁切边留在画外。自定义素材需要提供笔尖定位等参数，不能将任意图片直接视为已经适配。笔杆广告只放在笔杆，不自动加品牌或版权声明。
两个独立可选项，默认均为空。样片中的作者宣传文字不属于安装后的强制内容。
| 选项 | 位置与用途 | 规则 |
|---|---|---|
| 笔杆广告 | 跟随画笔，适合品牌短名或账号 | 最多 16 个字符；保留原文；长文字优先宽笔杆并检查实际可读性 |
| 浮动水印 | 位于画面内，用于账号、归属或简短发布信息 | 最多 180 字符，可换行；默认低对比、缓慢移动，避开底部字幕 |
例如：“笔杆写 @leo_xiaolei；水印写『手绘口播 · @leo_xiaolei』，淡一点，避开字幕。”也可以明确说“不加广告和水印”。
只保留以下六款，选择器和文字引导使用相同名称与顺序。
| 名称 | 试听 | 生产参考 |
|---|---|---|
| 逼真男声 | 《那条死于愤怒的蛇》节选 | 沿用该片原始参考；公共安装需自行导入 |
| 逼真女声 | 《快乐囚禁你的方式》节选 | 沿用当前原片提取人声；公共安装需自行导入 |
| 甜美学姐 | 同文试听 | 可下载合成参考 |
| Iapetus | 同文试听 | 可下载合成参考，并非直接调用 Gemini 原生 TTS |
| 知性女讲师 | 同文试听 | 可下载合成参考 |
| 故事解说 | 同文试听 | 独立保留的合成参考 |
前两项播放对应成片节选，其余四款播放同一段文本。成片节选只用于试听，不能反过来当作原片参考继续克隆。逼真女声目前暂用，听感仍待调整；改名不代表新增听感验收。
作者本机已保存两款逼真声音的原始参考，可以直接选择。公共安装包不含这些录音：未导入时可以试听，但不能选择它们生成。导入方法见本地声音运行。个人目录和任务目录只能补充这六项的参考，不能把其他音色或旧名称加回选择器。
可直接指定这六个名称之一，也可委托模型根据稿件选择。已有本机默认声音时优先沿用，本次明确选择优先。声音参考、逐字稿与生成参数分别保留；更换后端或稿件后仍需试听。
- 确定讲什么。 明确受众、原文约束、关键事实和讲解路线，避免把简单观点拖成长片。
- 确定画什么。 做分镜、美术指导与可绘制计划，生成插画并实际检查关键剧情和接触关系。
- 先把声音做完整。 合成整篇旁白，核对文字、杂音、漏读、重复和片尾，锁定声音母带。
- 用声音安排画面。 按时间戳绘制语义部位、逐字写关键句、填色、排字幕与换场。
- 检查代表场景，再导出全片。 工程检查与实际看图、听音分开记录，失败项修复后再交付。
交付包含 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 distv1.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；缺少指导记录、空文件、提示词改变、图片改变或视觉审查未通过都会停止生产。它约束流程与证据，不能代替模型实际看图。