handdraw-story-video

将手绘的故事插图转化为时长 35 到 45 秒的动画视频，其中包含逐行显示画面和渐变色彩效果。

Github地址

https://github.com/xiejunjie524/handdraw-story-video

特点

  • 默认 40 秒、720×960、30 fps，适合竖屏平台
  • 每幕使用一张独立彩色母图，本地提取完全对齐的线稿
  • 线稿和颜色统一从左向右推进，不重复调用生图模型
  • 支持可选故事字幕和画面内道具文字
  • 自动检查时长、重复素材、字幕行数与字号范围
  • 不绑定生图服务、音乐来源或私有 API

环境要求

  • Python 3.10+ Python 3.10 及以上版本
  • Node.js 18+ Node.js 18 及以上版本
  • FFmpeg
  • HyperFrames 超帧
  • GSAP 3（通过 npm 安装，遵守其许可条款）

快速开始

1
2
3
4
5
git clone https://github.com/xiejunjie524/handdraw-story-video.git
cd handdraw-story-videopython -m venv .venv
# Windows: .venv\Scripts\activate
# macOS/Linux: source .venv/bin/activate
pip install -r requirements.txtnpm install gsap
  1. 复制模板并填写故事：
1
cp templates/story-template.json story.json
  1. 每幕只生成一张 1K 彩色母图，再提取对齐线稿：
1
python scripts/make_lineart.py assets/images/scene-01-color.png assets/images/scene-01-line.png
  1. 准备 HyperFrames 目录和 GSAP：
1
mkdir -p hyperframes/assets/vendorcp node_modules/gsap/dist/gsap.min.js hyperframes/assets/vendor/gsap.min.js

Windows PowerShell 可使用： Windows PowerShell 可以使用：

1
2
New-Item -ItemType Directory -Force hyperframes/assets/vendor | Out-Null
Copy-Item node_modules/gsap/dist/gsap.min.js hyperframes/assets/vendor/gsap.min.js
  1. 把图片和已获授权的 BGM 放到 hyperframes/assets/，确保路径与 story.json 一致，然后生成页面：
1
python scripts/build_story.py story.json hyperframes/index.html --check-assetsnpx hyperframes check hyperframes/index.html --jsonnpx hyperframes render hyperframes/index.html --output renders/story-v1.mp4 --workers 1

不要覆盖旧成片；每次使用新的输出文件名。

故事配置

最小场景结构：

1
{  "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}}

完整字段和分镜规则见 docs/story-spec.md，可运行示例见 examples/soy-milk-at-4am/story.json。