threerocks/sweety-handdraw-video

选用指南

AI 根据 README 整理 · 2026/10/21 13:21:47

适用场景

适用于将主题、文章或故事制作成手绘讲解视频，涵盖知识讲解、故事寓言、观点表达等场景，也可用于修订已有素材。

查看 README 依据

| 完整故事或定稿 | 按原文制作；要求保留原文时，不擅自重写 | | 已认可的图、声音和稿件 | 复用素材，针对字幕、手部、画面或时间线进行修订 | 适合知识讲解、故事寓言、观点表达、产品原理和教学内容。优势在于把口播、画面与绘制过程放在同一条制作流程里： - **画风跟随内容**：21 个库内入口，也可让模型独立设计，或提供自定义方向。 - **声音先行、按段生成**：口播按语义段落生成，每段过嗡声 / 底噪 / 削波门禁，拼接停顿实测，再按时间戳安排画面与字幕。 - **像人一样画**：墨线平涂画风整笔描线、先轮廓后细节、抬笔移动、马克笔之字形上色；无轮廓画风由笔刷按部位揭示；汉字按标准笔顺书写。 - **先算预算再出图**：分镜按旁白算出每幅画能画几秒、最多几笔，图按预算设计，不靠压缩时间硬塞。 - **可以定位修改**：保留脚本、素材、声音、时间戳和检查记录，修字幕不必重新生图。 - **运行与观感分别检查**：文件能播放、声音清楚、剧情画对，是不同检查项。 它仍是需要 Agent、图像生成与本地运行环境的制作 Skill；成片不使用外部图生视频模型。当前主渲染实现是 Python / Pillow / SciPy / FFmpeg。 ## 导演如何参与制作

目标用户

面向需要制作手绘讲解视频的创作者，需使用 Codex 或 Claude Code 宿主。

查看 README 依据

导演判断写进创作方案，由本地渲染执行；不是一个独立运行的导演模型，也不自动启用上游影视生成平台。更广泛的导演资料按需取用，不能等同于本项目已验证了上游的全部影视能力。详见 [创作与分镜](skills/sweety-handdraw-video/references/story-design.md) 与 [依赖分工](skills/sweety-handdraw-video/references/dependencies.md)。 ## 安装与环境 ### 1. 安装 Skill 本轮支持 **macOS 与 Linux**，宿主为 **Codex 与 Claude Code**；Windows 暂不承诺。具备 Node.js / npm 时一条命令装到两个宿主： ```bash npx skills add threerocks/sweety-handdraw-video --skill sweety-handdraw-video --agent claude-code codex --global --copy --yes ```

使用方式

通过 Claude Code 输入指令或以特定语法在 Codex 中调用，支持命令行操作。

查看 README 依据

手动安装：将包内的 `sweety-handdraw-video` **整个文件夹**放入宿主的 Skills 目录，例如 `~/.claude/skills/sweety-handdraw-video`（Claude Code）或 `~/.codex/skills/sweety-handdraw-video`（Codex）。更新前备份旧目录；仅复制 `SKILL.md` 会缺少脚本、素材和内置依赖。手部、画风预览与试听已随包提供（约 38 MB），装好即可离线使用，不再依赖首次下载。 在 Claude Code 中直接说“用 sweety-handdraw-video 把……做成手绘视频”或输入 `/sweety-handdraw-video`；在 Codex 中使用 `$sweety-handdraw-video`。 ### 2. 准备运行环境 ```bash bash ~/.claude/skills/sweety-handdraw-video/scripts/setup.sh # 或 Codex 安装目录下的同名脚本 bash ~/.claude/skills/sweety-handdraw-video/scripts/setup.sh --check # 只检查，不安装 ```

部署要求

需要 macOS 或 Linux 系统，以及 Python 3.9+、FFmpeg、中文字体和一种可用的配音路径（如 VoxCPM2 或 VoiceStudio）；也可以使用现成的完整旁白。

查看 README 依据

| Python 3.9+ | 本地绘制与合成；依赖 Pillow、NumPy、SciPy、requests、fontTools，由 `setup.sh` 装入独立虚拟环境 | | FFmpeg 与 ffprobe | 合成、编码、解码与音视频检查 | | 中文字体 | 手写字、字幕、笔杆文字与水印分别选字体，并逐字核对字形覆盖；缺字时构建失败并列出缺失字符与已尝试字体。macOS 优先 Hannotate，Linux 使用 fontconfig 与 Noto CJK；不随包分发系统商业字体 | | 一种可用配音路径 | 已配置的本地 VoxCPM2、兼容的 VoiceStudio，或已核对的完整旁白与时间戳 | | Node.js / npm（可选） | 仅用于上面的安装命令；手动安装不依赖它 | 图片隐私清理已改为纯 Python（`scripts/clean_image.py`），不再需要 Bun 或 ExifTool。制作前运行 `python scripts/handdraw_video.py doctor JOB`：分别报告“能否渲染”“能否生成旁白”与生图能力提示，并对每个缺失项给出修复命令。 ### 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` | | **现成整篇旁白** | 已检查的音频及其时间戳 | 可离线编排和渲染；本次无需重新合成声音 | | **火山豆包 / Gemini TTS（可选）** | 用户自己的密钥，放在环境变量 | 按官方文档实现，只做了模拟 HTTP 测试，本仓库未真实调用；不是默认，本地失败时也不自动改用 |

已知限制

Windows 系统暂不承诺支持；完整流程主要在 Apple Silicon Mac 上验证；配音路径中火山豆包等为可选且未经真实调用。

查看 README 依据

**支持哪些系统和宿主？Windows / Gemini 能用吗？** 本轮支持 macOS 与 Linux、Codex 与 Claude Code。完整成片流程实测来自 Apple Silicon Mac + Codex；Linux 由 CI 与 Ubuntu 容器验证安装、字体发现、回归与离线短片合成，本地 TTS 仍以 Apple Silicon 为主。Claude Code 需要接入生图工具 / MCP 或由你提供插画。Windows 与 Gemini 等其他组合暂不承诺。运行 `bash scripts/setup.sh --check` 与 `doctor` 先确认执行、生图、字体与配音能力。 **为什么没有背景音乐，仍要检查杂音？** 参考音频可能带配乐或噪声，声音合成也可能产生伪影。不添加音乐只说明没有额外混音轨，不证明旁白干净。程序指标和 ASR 不能代替听感验收。 **会按规范汉字笔顺写吗？有橡皮擦转场吗？** 会。GB2312 范围内的汉字按标准笔顺逐笔书写（笔画数据来自 hanzi-writer-data，Arphic 公共许可）；其余字符按字形轮廓描线。橡皮擦转场仍无交付证据，不列为现成功能。 **发布到平台要注意什么？**

**音色与配音后端分开选择。** 六款内置音色提供真实的参考音频与同文试听，后端负责把本次正文生成声音。也可以导入自己的参考，或沿用已验收的本机主力声音。 | 路径 | 需要准备 | 已验证范围 | |---|---|---| | **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` | | **现成整篇旁白** | 已检查的音频及其时间戳 | 可离线编排和渲染；本次无需重新合成声音 | | **火山豆包 / Gemini TTS（可选）** | 用户自己的密钥，放在环境变量 | 按官方文档实现，只做了模拟 HTTP 测试，本仓库未真实调用；不是默认，本地失败时也不自动改用 |