项目概述

Handdraw Story Video 是一个开源项目，可将 7–9 张手绘故事母图自动转化为 35–45 秒竖屏短视频。画面效果为黑白线稿从左到右逐渐显现，随后在同方向上逐步填入低饱和色彩，呈现出类似手绘动画的独特质感。

该项目由开发者 xiejunjie524 在 GitHub 上发布，采用 MIT 许可协议，自发布以来已获得 665 颗星标和 99 个 Fork，社区反响热烈。项目底层基于 HyperFrames 渲染引擎和 GSAP 动画库，不绑定任何特定的生图服务或音乐来源，用户可以自由选择自己的创作工具链。

示例作品「凌晨四点的豆浆」预览
示例作品「凌晨四点的豆浆」：8 幕故事从线稿到上色的完整效果

核心功能与特点

自动线稿显现 + 渐进上色

用户只需为每一幕准备一张彩色母图，项目内置的 make_lineart.py 脚本可自动从彩色母图中提取对齐线稿。在最终成片中，线稿从左向右依次出现，上色图层沿相同方向推进，整个过程无需反复调用生图模型。

竖屏短视频优化

  • 默认规格：40 秒时长、720×960 像素、30 fps，适配抖音、快手、视频号等竖屏平台
  • 字幕控制：每幕支持最多 3 行字幕，每行不超过约 18 个中文字符，自动检查行数与字号
  • 素材检查：内置时长、重复素材、字幕行数与字号范围等自动校验

可安装 Codex Skill

项目仓库本身符合 Codex Skill 结构。用户可将仓库复制或链接到 $CODEX_HOME/skills/ 目录下，之后只需说一句「做一个 40 秒线稿逐渐上色的暖心故事」即可触发完整的生成流程。这对不熟悉命令行操作的创作者尤其友好。

快速上手步骤

  1. 克隆项目并安装依赖：
git clone https://github.com/xiejunjie524/handdraw-story-video.git
cd handdraw-story-video
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
npm install gsap
  1. 配置故事：复制模板并填写剧本设定
cp templates/story-template.json story.json
  1. 准备素材：每幕生成一张 1K 彩色母图，提取对齐线稿
python scripts/make_lineart.py scene-01-color.png scene-01-line.png
  1. 生成视频：执行构建脚本并调用 HyperFrames 渲染
python scripts/build_story.py story.json hyperframes/index.html --check-assets
npx hyperframes check hyperframes/index.html --json
npx hyperframes render hyperframes/index.html --output renders/story-v1.mp4 --workers 1

故事配置详解

故事配置文件为 JSON 格式，每个场景包含以下关键字段：

{
  "id": "scene-1",
  "duration": 5,
  "caption_lines": ["凌晨四点，", "他总会经过那家早餐店。"],
  "line_image": "assets/images/scene-01-line.png",
  "color_image": "assets/images/scene-01-color.png",
  "crop": {"scale": 1, "x": 0, "y": 0}
}

8 幕通常各约 5 秒，每幕必须是不同构图，不能靠裁切或缩放凑时长。主体通常位于画面下方 45%–55%，保留大面积纸白留白。单帧最多 2–3 人、两个关键背景锚点，避免人群、密集建筑和大块黑线。

画面设计原则

  • 每幕使用独立彩色母图，保持构图多样性
  • 主体位于画面下方 45%–55%，保留留白
  • 单帧最多 2–3 个角色、2 个锚点
  • 字幕最多 3 行，每行约 18 个字符
  • 每幕需体现独立故事推进，不可重复使用同一构图

适用场景与注意事项

该工具特别适合以下内容类型：

  • 治愈故事：日常暖心小故事、亲情友情叙事
  • 知识科普：用故事方式讲解知识点，增加趣味性
  • 品牌叙事：品牌故事、产品介绍等内容营销
  • 动画短片创作：独立创作者的低成本动画短视频方案

需要注意的是，项目代码以 MIT 许可发布，但生成图片、字体、GSAP、音乐及其他第三方素材不自动获得 MIT 授权，使用者须遵守各自提供方和素材来源的条款。项目不包含任何 API 密钥、浏览器会话或参考视频素材。

版权与授权说明

本项目使用 MIT 开源协议。使用者需自行确保所用素材（图片、字体、音乐等）拥有合法授权。GSAP 动画库通过 npm 安装，需遵守其许可条款。生成内容仅限合法用途，运营短视频账号时需遵守各平台规则。本工具仅提供技术能力，内容合规性由使用者自行负责。

项目链接

GitHub 仓库：github.com/xiejunjie524/handdraw-story-video

平台注意事项

使用本工具创作的短视频在发布至抖音、快手、视频号等平台时，应遵守各平台的原创内容政策。AI 辅助生成的线稿动画本质上属于原创素材二次创作，建议在平台规则允许范围内合理使用。涉及商业用途时，需确认所有素材（含母图、音乐、字体）均已获得完整授权。