Turn Hand-Drawn Story Illustrations into 35–45 Second Line-Reveal Videos with HyperFrames
Learn how to transform 7–9 hand-drawn story illustrations into a 35–45 second vertical video with line-reveal and gradual-coloring effects using HyperFrames.
Introduction
Creating engaging short-form videos from hand-drawn illustrations can be a tedious process, especially when you want to achieve a polished line-reveal and gradual-coloring effect. The open-source project handdraw-story-video by xiejunjie524 simplifies this workflow, allowing you to turn 7–9 hand-drawn story illustrations into a 35–45 second vertical video with a smooth left-to-right line reveal followed by a gradual color fill.
This tool is built on top of HyperFrames, a framework for generating frame-by-frame animations, and uses GSAP for animation control. It is designed for developers and content creators who want to automate the video production pipeline for hand-drawn stories.
Key Features
- Default Output: 40 seconds, 720×960 resolution, 30 fps — optimized for vertical platforms like TikTok, Instagram Reels, and YouTube Shorts.
- Single Source Image: Each scene uses one independent color illustration. The tool extracts a perfectly aligned line art version locally.
- Consistent Animation Direction: Both line art and color fill progress from left to right, avoiding repeated calls to image generation models.
- Optional Subtitles: Supports story subtitles and in-scene text elements.
- Automatic Validation: Checks duration, duplicate assets, subtitle line count, and font size range.
- No Vendor Lock-in: Does not bind to any specific image generation service, music source, or private API.
Prerequisites
Before you start, ensure you have the following installed:
- Python 3.10+
- Node.js 18+
- FFmpeg
- HyperFrames
- GSAP 3 (installed via npm, subject to its license)
Quick Start
1. Clone the Repository
git clone https://github.com/xiejunjie524/handdraw-story-video.git
cd handdraw-story-video
2. Set Up a Virtual Environment
python -m venv .venv
# On Windows:
.venv\Scripts\activate
# On macOS/Linux:
source .venv/bin/activate
3. Install Dependencies
pip install -r requirements.txt
npm install gsap
4. Create a Story Configuration
Copy the template and fill in your story details:
cp templates/story-template.json story.json
5. Prepare Your Illustrations
For each scene, you need a single 1K color illustration. Then extract the line art:
python scripts/make_lineart.py assets/images/scene-01-color.png assets/images/scene-01-line.png
6. Set Up HyperFrames and GSAP
mkdir -p hyperframes/assets/vendor
cp node_modules/gsap/dist/gsap.min.js hyperframes/assets/vendor/gsap.min.js
For Windows PowerShell:
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
7. Generate the Video
Place your images and background music (with proper licensing) in hyperframes/assets/, ensure paths match your story.json, then run:
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
Important: Do not overwrite old renders; use a new output filename each time.
Story Configuration
A minimal scene configuration looks like this:
{
"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}
}
For a complete field reference and storyboarding rules, see docs/story-spec.md. A runnable example is available at examples/soy-milk-at-4am/story.json.
Scene Composition Guidelines
To achieve the best visual results, follow these guidelines:
- Scene Count: 8 scenes, each approximately 5 seconds. Each scene must have a distinct composition — do not rely on cropping or scaling to fill time.
- Subject Placement: The main subject should be in the lower 45%–55% of the frame, leaving ample white space (paper-like background).
- Complexity: Maximum 2–3 characters per frame, with two key background anchors. Avoid crowds, dense buildings, or large black lines.
- Subtitles: Maximum 3 lines, each no more than ~18 Chinese characters.
- Music: Choose music that fits the story; do not hardcode a specific BGM into the template.
Codex Skill Integration
The repository root is structured as a Codex Skill. You can copy or link it to $CODEX_HOME/skills/handdraw-good-deed-story and then trigger it with a prompt like "Create a 40-second heartwarming story with line-reveal and gradual coloring."
Licensing and Attribution
- Code: Released under the MIT License.
- Third-party Assets: Generated images, fonts, GSAP, music, and other third-party materials are not automatically covered by the MIT license. You must comply with their respective licenses and terms.
- No Included Secrets: The repository does not contain API keys, browser sessions, reference videos, downloaded music, or full render history.
Conclusion
The handdraw-story-video project provides a streamlined, open-source pipeline for creating engaging hand-drawn story videos. By automating the line art extraction, animation direction, and validation, it saves significant time and effort. Whether you are a developer looking to integrate this into a larger workflow or a content creator wanting to produce consistent, high-quality videos, this tool is a solid foundation.
Start by cloning the repository, preparing your illustrations, and following the quick start guide. With a bit of configuration, you can turn your hand-drawn stories into polished short-form videos ready for social media.