Procedural Vector Cartoon Video Kit
This skill provides a pure code-driven, zero-external-asset (lossless vector) pipeline for producing cartoon-style educational and walkthrough short videos. Combining Python Pycairo rendering engine, Google Gemini 3.8 Flash TTS voiceover, automatic word-count duration alignment, smart punctuation-based subtitle splitting, and FFmpeg audio-video compositing, it can automatically render 1280×720 (30 fps) HD MP4 videos in minutes.
System Environment Prerequisites
Standard execution environment is macOS:
# 1. System dependencies & fonts (required: Noto Sans CJK TC Traditional Chinese Black)
brew install ffmpeg cairo pkg-config
brew install --cask font-noto-sans-cjk-tc
# 2. Python dependencies
pip3 install pycairo numpy pillow
# 3. OpenRouter API key (for Gemini 3.8 Flash TTS voice generation)
# Write API key to ~/.openrouter_key, ensure no trailing newline
echo "YOUR_OPENROUTER_API_KEY" > ~/.openrouter_key
chmod 600 ~/.openrouter_key
Verify environment: Run python3 example_ds2.py auto. If example_ds2/grid.png is generated successfully, the environment is ready.
Standard Project Directory Structure
my_video_project/
├── engine.py # Core engine: canvas base, subtitle generation, BGM mixing, Episode class, FFmpeg pipeline
├── dc.py # Shared visual template library (opening, roadmap, Q&A, key takeaways...)
├── atian.py (or xd.py / aj.py) # Host character definition (override dc.doctor to swap globally)
├── ep1.py # Current episode scene code (drawing functions s0, s1, s2...)
├── ep1/ # Current episode asset directory
│ ├── script.json # Narration text script (array of strings)
│ ├── c1.pcm ~ cN.pcm # 1.1x speed-processed per-segment audio files (24kHz s16le PCM)
│ └── grid.png # Auto-generated full-scene thumbnail preview (2 frames per scene)
└── tools/
├── make_payloads.py # script.json -> OpenRouter TTS request JSON
├── tts.sh # Call OpenRouter batch generation for 24kHz PCM audio
├── f0.py # Pitch quality check script (median Hz, detect and re-sample drifting sections)
└── prep.sh # 1.1x audio speed-up and rename to c1.pcm ~ cN.pcm
Standard Six-Stage Production Workflow (SOP)
To produce a new episode, strictly follow these six stages:
Stage 1: Script Writing and Scene Division (script.json)
- Create a JSON string array in
ep1/script.json. Each string corresponds to one independent scene. - Recommended word count per narration segment: 30–80 characters (approximately 6–15 seconds of speech), for the most comfortable rhythm.
- Use standard full-width punctuation (
,,。,!,?,:,;). The engine will automatically split subtitles based on punctuation.
Stage 2: TTS Voice Generation, Pitch Quality Check, and 1.1x Speed Optimization
- Generate TTS request files:
Note: Style prompts (e.g., authentic Taiwanese Mandarin, lively young guide) must be placed in thepython3 tools/make_payloads.py ep1instructionsfield. Do NOT put them ininput, or they will be spoken aloud. - Batch request voice:
bash tools/tts.sh ep1 - Pitch quality check (F0 Pitch Check):
python3 tools/f0.py tts_ep1/*.pcm- Male voice
Pucknormal median: 120 Hz ~ 160 Hz. - Strict pitch rule: If any segment exceeds 165 Hz (indicating Gemini drifted to a female voice), re-request that segment individually until the pitch is normal. See audio-tts-pipeline.md for details.
- Male voice
- Speed-up and format:
Outputs files withbash tools/prep.sh ep1atempo=1.1speed-up toep1/c1.pcm~ep1/cN.pcm.
Stage 3: Host Character Binding and Custom Drawing
- Character module must conform to the standard function interface:
def my_host(ctx, x, y, s, t, mouth=0.0, wave=False, point=False, sweat=False, happy=True, look=0.0): - By executing
dc.doctor = my_hostat the bottom of the module, globally replace the host in all templates with one command. - For complete drawing techniques (blinking calculation, rubber-hose arms, RMS volume-driven mouth opening/closing), refer to character-design.md and character_template.py.
Stage 4: Pycairo Visual Scene Code Writing (ep1.py)
- Write a corresponding function for each scene:
def s0(ep, ctx, u, T, m):u: Elapsed seconds within this scene.T: Absolute time in the entire video.m: Real-time voice amplitude (0.0 ~ 1.0).
- Use
ep.kw(sc, "Precise Keyword")to get the exact second when the keyword is spoken, driving card animation appearances. - For key functions and layout APIs, see engine-api.md.
Stage 5: Quick Thumbnail Preview and Visual QA
python3 ep1.py auto
- The engine quickly samples 2 frames per scene throughout the video in under 2 seconds, compositing them into
ep1/grid.png. - Key checks:
- Any tofu squares (missing glyphs) in text.
- Content exceeding canvas boundaries or overlapping text strings.
- Bottom cards must not intrude into the subtitle area (must not go below y=610).
- Right-side cards must not collide with the permanent host character.
Stage 6: Final Video Rendering and FFmpeg Integrity Validation
- Render MP4:
The engine automatically composites 1280×720 H.264 video, burns in subtitles, mixes BGM (automatically lowers volume) and packages AAC audio.python3 ep1.py - Lossless integrity check:
No errors in terminal means perfect audio-video sync and flawless packaging.ffmpeg -v error -i output_filename.mp4 -f null -
Core API Quick Reference
| Feature | Syntax | Description |
|---|---|---|
| Progress calc | prog(u, t0, d=0.5) | Starting at t0 sec, takes d sec to go from 0 to 1 |
| Bounce scale | pop(ctx, cx, cy, p) | Bounce-enter around center point (with back curve) |
| Keyword align | ep.kw(sc, "text", nth=0) | Precisely calculate when the word is spoken (auto-advanced by 0.25 sec) |
| Rounded rect | rrect(ctx, x, y, w, h, r) | Define rounded rectangle path |
| Fill & stroke | fillstroke(ctx, fill, stroke, lw=5) | Fill and dark stroke simultaneously |
| Single line text | text(ctx, s, x, y, size, col, align='c') | Draw text; alignment options: 'l' (left), 'c' (center), 'r' (right) |
| Chip label | chip(ctx, "Label", x, y, p, col, size=30) | Pop-up capsule card |
| Popup panel | if panel(ctx, x, y, w, h, p): ... ctx.restore() | Content white-background panel (must pair with restore) |
| Bottom-right host | corner(ctx, T, m) | Draw a miniature permanent host in the bottom-right corner |
| Chapter title card | station_card(ctx, u, station_num, "Station Name") | Centered large-text card appearing at chapter start (first 1.9 sec) |
| Key takeaways outro | outro_doc(ep, ctx, u, T, m, sc, Title, Subtitle, rows) | Confetti, key bullet points, and next-episode preview ending scene |
Crucial Guardrails (Top 3 Rules to Avoid Pitfalls)
- Subtitle safety zone:
- The bottom
y = 648 ~ 702area is reserved for automatic subtitles. - All info panels, data cards, and button bottoms must strictly NOT exceed y = 610!
- The bottom
- Special symbols & emoji prohibition:
- Pycairo under the
Noto Sans CJK TCfont cannot render emoji (e.g., ✨, 📜, 🌱) and special Unicode arrows (➔, ➜); they will appear as ugly tofu squares. - Alternatives: Use
->for arrows or call thearrow()function; usestar()function for stars; use the plain ASCII symbol×ormark(ctx, x, y, False, p)for X marks.
- Pycairo under the
- Keyword precision:
- The
phraseinep.kw(sc, phrase)must be an exact substring of the corresponding line inscript.json. No extra characters, missing characters, or added punctuation; otherwise it will cause the program to halt.
- The
Reference Documents & Example Resources
- Engine architecture and all built-in geometric components: references/engine-api.md
- Vector character design with breathing/blinking/speech mouth implementation: references/character-design.md
- TTS request spec, F0 pitch algorithm, and audio processing: references/audio-tts-pipeline.md
- Canvas safety zone, missing glyph prevention, and pitfalls checklist: references/layout-and-pitfalls.md
- Character template code: examples/character_template.py
- Minimal full episode template: examples/minimal_episode.py