Communitygithub.com

DrChunChihChen/procedural-cartoon-video

使用 Python Pycairo、Gemini 3.8 Flash TTS 與 FFmpeg 自動化生成高質感向量卡通導覽與教學解說短影片。當使用者提到「做影片」、「製作動畫」、「卡通影片」、「教學影片」、「短片製作」、「videokit」、「小半天影片」、「碳導遊」或需要從腳本、配音、角色繪製到最終 MP4 輸出的完整管線時使用。

procedural-cartoon-video 是什么?

procedural-cartoon-video is a Antigravity agent skill that 使用 Python Pycairo、Gemini 3.8 Flash TTS 與 FFmpeg 自動化生成高質感向量卡通導覽與教學解說短影片。當使用者提到「做影片」、「製作動畫」、「卡通影片」、「教學影片」、「短片製作」、「videokit」、「小半天影片」、「碳導遊」或需要從腳本、配音、角色繪製到最終 MP4 輸出的完整管線時使用。.

兼容平台~Claude Code~Codex CLI~Cursor✓Antigravity✓Gemini CLI
npx skills add DrChunChihChen/procedural-cartoon-video

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

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

  1. Generate TTS request files:
    python3 tools/make_payloads.py ep1
    
    Note: Style prompts (e.g., authentic Taiwanese Mandarin, lively young guide) must be placed in the instructions field. Do NOT put them in input, or they will be spoken aloud.
  2. Batch request voice:
    bash tools/tts.sh ep1
    
  3. Pitch quality check (F0 Pitch Check):
    python3 tools/f0.py tts_ep1/*.pcm
    
    • Male voice Puck normal 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.
  4. Speed-up and format:
    bash tools/prep.sh ep1
    
    Outputs files with atempo=1.1 speed-up to ep1/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_host at 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:
    1. Any tofu squares (missing glyphs) in text.
    2. Content exceeding canvas boundaries or overlapping text strings.
    3. Bottom cards must not intrude into the subtitle area (must not go below y=610).
    4. Right-side cards must not collide with the permanent host character.

Stage 6: Final Video Rendering and FFmpeg Integrity Validation

  1. Render MP4:
    python3 ep1.py
    
    The engine automatically composites 1280×720 H.264 video, burns in subtitles, mixes BGM (automatically lowers volume) and packages AAC audio.
  2. Lossless integrity check:
    ffmpeg -v error -i output_filename.mp4 -f null -
    
    No errors in terminal means perfect audio-video sync and flawless packaging.

Core API Quick Reference

FeatureSyntaxDescription
Progress calcprog(u, t0, d=0.5)Starting at t0 sec, takes d sec to go from 0 to 1
Bounce scalepop(ctx, cx, cy, p)Bounce-enter around center point (with back curve)
Keyword alignep.kw(sc, "text", nth=0)Precisely calculate when the word is spoken (auto-advanced by 0.25 sec)
Rounded rectrrect(ctx, x, y, w, h, r)Define rounded rectangle path
Fill & strokefillstroke(ctx, fill, stroke, lw=5)Fill and dark stroke simultaneously
Single line texttext(ctx, s, x, y, size, col, align='c')Draw text; alignment options: 'l' (left), 'c' (center), 'r' (right)
Chip labelchip(ctx, "Label", x, y, p, col, size=30)Pop-up capsule card
Popup panelif panel(ctx, x, y, w, h, p): ... ctx.restore()Content white-background panel (must pair with restore)
Bottom-right hostcorner(ctx, T, m)Draw a miniature permanent host in the bottom-right corner
Chapter title cardstation_card(ctx, u, station_num, "Station Name")Centered large-text card appearing at chapter start (first 1.9 sec)
Key takeaways outrooutro_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)

  1. Subtitle safety zone:
    • The bottom y = 648 ~ 702 area is reserved for automatic subtitles.
    • All info panels, data cards, and button bottoms must strictly NOT exceed y = 610!
  2. Special symbols & emoji prohibition:
    • Pycairo under the Noto Sans CJK TC font cannot render emoji (e.g., ✨, 📜, 🌱) and special Unicode arrows (➔, ➜); they will appear as ugly tofu squares.
    • Alternatives: Use -> for arrows or call the arrow() function; use star() function for stars; use the plain ASCII symbol × or mark(ctx, x, y, False, p) for X marks.
  3. Keyword precision:
    • The phrase in ep.kw(sc, phrase) must be an exact substring of the corresponding line in script.json. No extra characters, missing characters, or added punctuation; otherwise it will cause the program to halt.

Reference Documents & Example Resources

相关技能