GitHub 今日推荐｜sweety-handdraw-video：文章转手绘口播视频

GitHub 今日推荐｜sweety-handdraw-video：文章转手绘口播视频

一句话看懂

项目地址：github.com/threerocks/...

sweety-handdraw-video 将文章或故事转为手绘口播视频。AI Agent 理解内容、撰写脚本、设计分镜、生成插画，Python 在本地渲染完成逐笔描线、填色、配音对齐和字幕，FFmpeg 合成输出。保留脚本、素材、时间戳等元数据，修改局部画面或字幕时可定位重新渲染该段，无需重渲全片。

它解决什么问题

技术文章、产品说明、教学内容转为视频时需要配音、字幕、插图同步。传统流程手工分段录音，每段配一张静态图，句间停顿不连贯，画面替换全靠硬切。外部图生视频模型依赖云端接口，费用不可控，素材不留本地。

sweety-handdraw-video 整篇声音先行，保留句间停顿和换气，再按时间戳安排画面与字幕。Python、Pillow、SciPy、FFmpeg 在本地完成渲染。生成的脚本、素材、时间戳、检查记录全部导出，修改某处时定位该段落重新渲染，已认可的配音和其他画面不受影响。

核心概念速览

Agent：人工智能理解内容、撰写口播、设计分镜、生成插画。内置 omniailab-ai-director 的导演方法。

分镜：根据脚本生成的画面规划，决定每幅图的作用。每幅图需说明它比直接显示这句话多解释了什么，列出必须可见的动作、接触与结果。

按部位画出来：先按语义部位完成轮廓，再按相同顺序填色，文字逐字绘制时笔画间抬笔。保留笔触顺序，避免随意绘制。

笔杆广告：跟随画笔显示的品牌或账号，最多十六个字符。只放在笔杆，不自动加品牌或版权声明。

架构拆解

项目分为四个模块和外部依赖。

sweety-handdraw-video 主 Skill 模块，提供制作接口，协调依赖。调用 Agent 完成内容理解、脚本撰写、分镜设计、插画生成，输出脚本与素材后交给渲染引擎。

hand-drawn-styles 画风库，提供 21 种内置画风入口，包含 20 个编号风格加 3.1 稳定变体。定义样式配方和预览图，供 Agent 在分镜阶段选择或自行设计。

huashu-art-motion 动画渲染引擎，提供时间驱动的逐帧绘制。engine.js 按时间 t 确定性渲染帧，时间轴由节拍或口播时长驱动。render.py 启动本地 HTTP 服务，无头 Chromium 打开 index.html，逐帧调用 window.renderFrame(t)，读取 canvas 像素后管道送 FFmpeg 输出 mp4，最后混入音轨。

assets 存放手部画风、声音、画风预览等素材资源。提供六款手臂预设：深蓝袖女性长甲、儿童彩铅、毛笔、白衬衫、针织袖和仅画笔。

scripts Python 渲染脚本，执行描线、填色、合成、导出。使用 Pillow、NumPy、SciPy、requests 处理图像和数据。

关键实现走读

时间驱动渲染核心

// 引擎：时间 t（秒）→ 一帧画面。确定性：同一个 t 永远画出同一帧（随机数全部用种子）。
// 时间轴由节拍网格驱动：128 BPM，每段占若干八分音符（见 eras.js 的 eighths）。
(() => {
const qs = new URLSearchParams(location.search), qw = +qs.get('w'), qh = +qs.get('h');
const [W, H] = qw > 0 && qh > 0 ? [qw, qh] : Array.isArray(window.FILM_SIZE) ? window.FILM_SIZE.map(Number) : [1920, 1080];
window.U.setStage(W, H);
const cv = document.getElementById('c');
cv.width = W; cv.height = H; window.__size = [W, H];
const ctx = cv.getContext('2d');
window.__canvas = cv;

const EIGHTH = 60 / (window.BPM || 128) / 2;
let acc = 0;
for (const e of ERAS) { e.t0 = acc; acc += e.dur != null ? e.dur : e.eighths * EIGHTH; e.t1 = acc; }
window.__total = window.FILM_DURATION || ERAS[ERAS.length - 1].t1;
ERAS[ERAS.length - 1].t1 = 1e9;

做了什么： 根据 URL 参数或默认配置设置画布分辨率（默认 1920×1080），计算时间轴。每段占若干八分音符或明确指定时长，八分音符长度由 BPM（默认 128）计算。累计每段的起止时间 t0 和 t1。

为什么这样写： 同一个 t 必须永远画出同一帧，随机数全部用种子。时间轴由节拍网格驱动，让画面切换和动画节奏与配音对齐。预先计算所有段落的时间边界，渲染时直接查表确定当前段落。

没有它会怎样： 每次渲染相同时刻的画面可能不一致，定位修改时局部重新渲染会产生跳变。时间轴计算分散在渲染循环中会降低帧率，无法保证 60fps 输出。

逐帧渲染和 FFmpeg 合成

#!/usr/bin/env python3
"""逐帧渲染：起本地 http 服务 → 无头 Chromium 打开 index.html → 对每帧调用 window.renderFrame(t)
→ 读 canvas 像素 → 管道送 ffmpeg 出 60fps mp4，最后混入音轨。
"""
with sync_playwright() as p:
    b = p.chromium.launch(args=['--disable-web-security', '--enable-gpu-rasterization', '--ignore-gpu-blocklist'])
    pg = b.new_page(viewport={'width': 1920, 'height': 1080}, device_scale_factor=1)
    grab = '''async (t)=>{ await window.prepare(t); window.renderFrame(t); return window.__canvas.toDataURL('image/png').split(',')[1]; }'''
    ff = subprocess.Popen(['ffmpeg', '-y', '-v', 'error', '-f', 'image2pipe', '-framerate', str(a.fps), '-c:v', 'png', '-i', '-'] + enc + [vid],
                          stdin=subprocess.PIPE)
    for i in range(n0, n1):
        ff.stdin.write(base64.b64decode(pg.evaluate(grab, i / a.fps)))
    ff.stdin.close(); ff.wait()

做了什么： 启动无头 Chromium，打开 index.html，对每一帧调用 window.prepare(t) 和 window.renderFrame(t)，将 canvas 导出为 PNG 的 base64 编码，解码后写入 FFmpeg 的 stdin。FFmpeg 从管道读取 PNG 数据流合成视频。

为什么这样写： 渲染逻辑用 JavaScript 实现在浏览器环境，Chromium 提供完整的 Canvas API 和 GPU 加速。逐帧渲染保证确定性，每帧独立计算无需依赖前一帧状态。管道传输避免磁盘 IO 瓶颈，数千帧的临时 PNG 文件会占用数十 GB 空间。

没有它会怎样： 录屏方案依赖系统实时性能，帧率不稳定，渲染复杂场景时会丢帧或卡顿。逐帧保存再合成需要处理文件命名、清理临时目录、磁盘容量限制。

动手上手

安装项目和依赖：

npx skills add threerocks/sweety-handdraw-video --skill sweety-handdraw-video
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

第一条命令安装主 Skill 模块。第二三条创建并激活 Python 虚拟环境。第四条安装 Pillow、NumPy、SciPy、requests、Playwright 等依赖。第五条验证包完整性。

运行环境：Python 3.9+，作者测试环境为 M3 Max 36GB 内存。VoxCPM2-8bit 配音权重约 3.23GB，需确认存储空间和内存容量。默认输出分辨率 1920×1080，帧率 30fps。

启动制作需要准备主题文章或故事文本，通过对话界面调用 Agent 撰写口播脚本、设计分镜、生成插画，完成后执行渲染命令。输出包含 MP4 视频、封面 PNG、SRT 字幕、口播稿和检查记录。

验证结果：检查配音与字幕是否对齐，手绘笔触是否按部位顺序完成轮廓和填色，文字是否逐字书写，SRT 字幕文件时间戳与实际发音是否匹配。

应用场景

知识讲解：技术文章、产品说明、教学内容转为口播，生成手绘示意图配合配音。检查数字来源、适用条件、画面是否解释清楚机制。适合教育培训机构、教师、技术传播者。

故事寓言：提供完整故事，按原文制作不擅自重写，使用淡彩叙事插画配合旁白。检查剧情动作接触关系是否画对，角色是否跨画面漂移。适合内容创作者、作家、自媒体运营者。

素材复用修订：已认可的图、声音和稿件可复用，只针对字幕、手部画面或时间线修订。适合设计师、插画师批量制作或快速迭代。

产品原理展示：将产品说明文档转化为分镜，配合手绘动画解释功能。适合产品经理或技术传播者快速生成原理解释或案例演示。

独立分析

项目选择本地渲染方案而非调用外部图生视频模型，优势是素材、元数据、渲染参数全部留本地，修改某处时定位重新渲染该段落即可。代价是需自行准备 Python 3.9+ 环境、3.23GB 配音权重、足够的内存（作者测试环境 36GB）、FFmpeg 和 Playwright。整篇声音先行的设计保留句间停顿和换气，画面与字幕按时间戳对齐，比逐页拼配音固定空白更连贯。

当前完整流程验证来自 Apple Silicon Mac 加 Codex，其他环境尚未完成整流程验证。21 种内置画风入口和六款手臂预设覆盖常见场景，支持自定义指令扩展。按字形轮廓逐字绘制不保证规范书法笔顺，重视视觉效果而非书法规范。

项目依赖外部 AI Agent、图像生成模型以及本地运行环境，需自行配置相应依赖。开源不等于全链路免费，模型宿主与生图能力可能收费，本地配音消耗硬件、电力和时间。不是承诺任意输入稳定通过的无人审核批量系统，每条都要检查。

适合需要制作知识讲解、故事寓言、教学内容的创作者、教师、自媒体运营者，愿意投入时间配置环境和审查输出。不适合需要 Windows、Linux 完整验证，或规范书法笔顺，或云端一键服务的用户。

局限与风险

当前完整流程验证来自 Apple Silicon Mac 加 Codex，其他平台尚未完成整流程验证。Windows 和 Linux 环境下 Playwright、FFmpeg、GPU 加速的兼容性需自行测试。

VoxCPM2-8bit 权重约 3.23GB，需确认存储和内存容量，推理速度依赖硬件配置。按字形轮廓逐字绘制不保证规范书法笔顺，适合视觉呈现而非书法教学。笔杆广告最多十六个字符，长文字需检查实际可读性。

不是承诺任意输入稳定通过的无人审核批量系统，每条都要检查关键剧情、数字来源、画面解释是否准确。Agent 生成的分镜和插画可能出现动作接触关系错误、角色跨画面漂移、关键信息缺失。

开源不等于全链路免费，模型宿主与生图能力可能收费，本地配音消耗硬件、电力和时间。项目依赖外部 AI Agent 和图像生成模型，需自行配置 API 密钥、额度和网络访问。

封板版本 v1.2 功能完整，后续更新可能改变接口或依赖，升级前需确认兼容性。制作目录保留中间产物会占用磁盘空间，需定期清理已交付项目的缓存。

结论卡片

sweety-handdraw-video 将文章或故事转为手绘口播视频，Agent 驱动脚本分镜插画设计，Python 本地渲染逐笔描线填色，FFmpeg 合成对齐配音。整篇声音先行保留句间停顿，画面按时间戳对齐。保留脚本素材时间戳元数据，支持定位修改无需重渲全片。21 种内置画风和六款手臂预设覆盖常见场景。适合需要制作知识讲解、故事寓言、教学内容的创作者、教师、自媒体运营者。不适合需要 Windows、Linux 完整验证，或规范书法笔顺，或云端一键服务的用户。本地制作便于保留参考参数和生成记录，代价是需自行准备模型与计算资源。当前完整流程验证来自 Apple Silicon Mac 加 Codex，其他环境尚未完成整流程验证。封板版本 v1.2，最新补丁 v1.2.3。

---

项目地址：github.com/threerocks/...

原文地址：tools.wflynn.cn/aitools/git...

关注公众号「YourTools」，每天推送 GitHub 趋势与开源工具速报：