Communitygithub.com

Procedural Cartoon Video Kit

Automatisierte Erstellung von hochwertigen Vektor-Cartoon-Erklärvideos mit Python Pycairo, Gemini 3.8 Flash TTS und FFmpeg. Für Nutzer, die „Video erstellen“, „Animation“, „Cartoon“, „Lehrvideo“, „Kurzvideo“, „Videokit“ oder eine vollständige Pipeline von Skript, Sprachausgabe, Charakterzeichnung bis zur finalen MP4-Ausgabe benötigen.

Was ist Procedural Cartoon Video Kit?

Dieses Skill-Set bietet eine rein codegetriebene Pipeline zur Erstellung von Cartoon-Erklär- und Touristenführungsvideos ohne externe Materialabhängigkeiten (verlustfreie Vektorgrafiken). Es kombiniert die Python-Bibliothek Pycairo für die Vektorgrafik-Engine, Google Gemini 3.8 Flash TTS für die Sprachausgabe, automatische Ausrichtung von Textlänge und -dauer, intelligente Untertitelgenerierung auf Basis von Satzzeichen und FFmpeg für die Audio-Video-Synthese. Innerhalb weniger Minuten können hochauflösende MP4-Videos (1280 × 720, 30 fps) vollautomatisch gerendert werden. Die Pipeline ist in sechs standardisierten Phasen organisiert: Skripterstellung, TTS-Spracherzeugung mit Tonhöhenkontrolle, Charakterbindung und -zeichnung, visuelles Szenen-Scripting mit Pycairo, schnelle Vorschau und visuelle Qualitätssicherung sowie finales Rendering und FFmpeg-Überprüfung. Das System unterstützt macOS und erfordert FFmpeg, Cairo, Noto Sans CJK TC-Schriftart, Python-Bibliotheken (pycairo, numpy, pillow) und einen OpenRouter-API-Schlüssel für die TTS-Erzeugung.

Funktioniert mit~Claude Code~Codex CLI~Cursor✓Antigravity✓Gemini CLI
npx skills add DrChunChihChen/procedural-cartoon-video

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

Programmierbares Vektor-Cartoon-Video-Kit (Procedural Cartoon Video Kit)

Dieses Skill bietet eine rein codegetriebene, von externen Materialien unabhängige (verlustfreie reine Vektorgrafiken) Pipeline zur Erstellung von Cartoon-Lehr- und Erklärvideos. Es kombiniert Python Pycairo als Zeichen-Engine, Google Gemini 3.8 Flash TTS für Sprachausgabe, automatische Ausrichtung von Textlänge und -dauer, intelligente Untertitel-Sprechblasen basierend auf Satzzeichen und FFmpeg zur Audio-Video-Synthese. Innerhalb weniger Minuten können automatisch hochauflösende 1280 × 720 (30 fps) MP4-Videos gerendert werden.


Systemvoraussetzungen (Prerequisites)

Standardausführungsumgebung: macOS

# 1. Systemabhängigkeiten und Schriftarten (Erforderlich: Noto Sans CJK TC – traditionelles Chinesisch)
brew install ffmpeg cairo pkg-config
brew install --cask font-noto-sans-cjk-tc

# 2. Python-Bibliotheken
pip3 install pycairo numpy pillow

# 3. OpenRouter API-Schlüssel (für Gemini 3.8 Flash TTS-Spracherzeugung)
# API-Schlüssel in ~/.openrouter_key speichern, ohne Zeilenumbruch
echo "DEIN_OPENROUTER_API_SCHLÜSSEL" > ~/.openrouter_key
chmod 600 ~/.openrouter_key

Umgebung überprüfen: Führe python3 example_ds2.py auto aus. Wenn example_ds2/grid.png erfolgreich erstellt wird, ist die Umgebung einsatzbereit.


Standardprojekt-Verzeichnisstruktur

my_video_project/
├── engine.py                  # Kern-Engine: Zeichenfläche, Untertitel, BGM-Synthese, Episode-Klasse, FFmpeg-Pipeline
├── dc.py                      # Gemeinsame visuelle Vorlagenbibliothek (Eröffnung, Route, Q&A, Zusammenfassung…)
├── atian.py (oder xd.py / aj.py) # Charakterdefinition des Moderators (Überschreibt dc.doctor für globalen Charaktertausch)
├── ep1.py                     # Szenencode der jeweiligen Episode (Zeichenfunktionen s0, s1, s2...)
├── ep1/                       # Asset-Verzeichnis der Episode
│   ├── script.json            # Erzähltext-Skript (Array von Zeichenfolgen)
│   ├── c1.pcm ~ cN.pcm        # Sprachdateien nach 1,1-facher Beschleunigung (24 kHz s16le PCM)
│   └── grid.png               # Automatisch erstellte Miniaturansicht des gesamten Videos (2 Frames pro Szene)
└── tools/
    ├── make_payloads.py       # script.json -> OpenRouter TTS-Anforderungs-JSON
    ├── tts.sh                 # Ruft OpenRouter auf, um Stapel von 24-kHz-PCM-Sprachdateien zu generieren
    ├── f0.py                  # Skript zur Tonhöhenprüfung (Median-Hz, erkennt und wiederholt Tonhöhenabtriftungen)
    └── prep.sh                # 1,1-fache Sprachbeschleunigung und Umbenennung in c1.pcm ~ cN.pcm

Standard-Sechs-Phasen-Produktionsablauf (SOP)

Befolge für jede neue Episode strikt die folgenden sechs Phasen:

Phase 1: Skripterstellung und Szenenaufteilung (script.json)

  • Erstelle ein JSON-Array von Zeichenfolgen in ep1/script.json. Jede Zeichenfolge entspricht einer unabhängigen Szene (Scene).
  • Empfohlene Wortanzahl pro Erzählabschnitt: 30 bis 80 Zeichen (Vorlesedauer ca. 6 bis 15 Sekunden) für einen angenehmen Rhythmus.
  • Verwende standardmäßige chinesische Satzzeichen (, 。 ! ? : ;). Die Engine unterteilt automatisch intelligent in Untertitel basierend auf diesen Zeichen.

Phase 2: TTS-Spracherzeugung, Tonhöhenprüfung und 1,1-fache Sprachoptimierung

  1. TTS-Anforderungsdatei erstellen:
    python3 tools/make_payloads.py ep1
    
    Hinweis: Stilhinweise (z. B. authentisches Taiwanesisch, lebhafter Reiseführer) MÜSSEN im instructions-Feld platziert werden. Sie DÜRFEN NICHT in das input-Feld gesetzt werden, sonst werden sie vorgelesen.
  2. Stapelanforderung von Sprachdateien:
    bash tools/tts.sh ep1
    
  3. Tonhöhenprüfung (F0 Pitch Check):
    python3 tools/f0.py tts_ep1/*.pcm
    
    • Normalwert für männliche Stimme Puck: 120 Hz ~ 160 Hz (Median).
    • Strenge Tonhöhenregel: Wenn eine beliebige Datei über 165 Hz liegt (was darauf hindeutet, dass Gemini fälschlicherweise zu einer weiblichen Stimme abgedriftet ist), muss diese Datei einzeln erneut angefordert werden, bis die Tonhöhe normal ist. Siehe audio-tts-pipeline.md
  4. Sprachbeschleunigung und Formatierung:
    bash tools/prep.sh ep1
    
    Beschleunigt die Dateien mit atempo=1.1 und gibt sie als ep1/c1.pcm ~ ep1/cN.pcm aus.

Phase 3: Charakterbindung und individuelle Zeichnung des Moderators

  • Das Charaktermodul muss die standardmäßige Funktionsschnittstelle erfüllen: def my_host(ctx, x, y, s, t, mouth=0.0, wave=False, point=False, sweat=False, happy=True, look=0.0):
  • Führe am Ende des Moduls dc.doctor = my_host aus, um global und mit einem Klick den Moderator in allen Vorlagen auszutauschen.
  • Vollständige Zeichenmethoden (Augenzwinkern, Gummischlaucharme, durch RMS-Lautstärke gesteuerte Mundöffnung) findest du in character-design.md und character_template.py.

Phase 4: Schreiben von Pycairo-Szenencode (ep1.py)

  • Schreibe für jede Szene die entsprechende Funktion def s0(ep, ctx, u, T, m):
    • u: Verstrichene Sekunden innerhalb dieser Szene.
    • T: Absolute vergangene Sekunden im gesamten Video.
    • m: Aktuelle Sprachamplitude (0.0 ~ 1.0).
  • Verwende ep.kw(sc, "präzises Schlüsselwort"), um die genaue Sekunde zu erhalten, zu der der Erzähler dieses Schlüsselwort ausspricht, und um das Erscheinen von Karten zu steuern.
  • Schlüsselfunktionen und Layout-API: Siehe engine-api.md.

Phase 5: Schnelle Miniaturansichten-Vorschau und visuelle Qualitätskontrolle (Preview & QA)

python3 ep1.py auto
  • Die Engine erstellt innerhalb von 2 Sekunden schnelle Stichproben von 2 Frames pro Szene und setzt sie zu ep1/grid.png zusammen.
  • Wichtige Prüfpunkte:
    1. Tofu-Blöcke (fehlende Zeichen) im Text.
    2. Inhalte, die den Zeichenbereich überschreiten oder sich überschneidende Zeichenfolgen.
    3. Untere Informationskarten, die in den Untertitelbereich eindringen (darf nicht unter y=610 reichen).
    4. Kollision zwischen rechten Seitenkarten und dauerhaftem unterem Bildschirm-Moderator.

Phase 6: Vollständiges Video-Rendering und FFmpeg-Überprüfung

  1. Offizielles Rendern in MP4:
    python3 ep1.py
    
    Die Engine synthetisiert automatisch das 1280×720 H.264-Video, erstellt Untertitel, mischt Hintergrundmusik (automatisch leiser gestellt) und kapselt AAC-Audio.
  2. Integritätsprüfung ohne Verluste:
    ffmpeg -v error -i ausgegebene_datei.mp4 -f null -
    
    Keine Fehler im Terminal bedeuten, dass Audio und Video synchron und die Kapselung perfekt ist.

Kern-API-Spickzettel

FunktionSyntaxBeschreibung
Fortschrittsberechnungprog(u, t0, d=0.5)Beginnt bei Sekunde t0, wird über d Sekunden von 0 auf 1 gehen
Springen und Skalierenpop(ctx, cx, cy, p)Springt um einen Mittelpunkt herum ein (mit Back-Kurve)
Schlüsselwortausrichtungep.kw(sc, "Text", nth=0)Berechnet die genaue Zeit, zu der das Wort gesprochen wird (automatisch 0,25 Sekunden vorgezogen)
Abgerundetes Rechteckrrect(ctx, x, y, w, h, r)Definiert einen abgerundeten Rechteckspfad
Füllen und Umrandenfillstroke(ctx, fill, stroke, lw=5)Gleichzeitig füllen und mit dunkler Farbe umranden
Einzeiliger Texttext(ctx, s, x, y, size, col, align='c')Zeichnet Text, optional linksbündig 'l', zentriert 'c', rechtsbündig 'r'
Kapsel-Tagchip(ctx, "Tag", x, y, p, col, size=30)Aufklappbare Kapselkarte
Aufklapp-Panelif panel(ctx, x, y, w, h, p): ... ctx.restore()Inhalts-Panel mit weißem Hintergrund (muss mit restore gepaart sein)
Moderator unten rechtscorner(ctx, T, m)Zeichnet eine verkleinerte Version des dauerhaften Moderators unten rechts
Kapitelüberschrift-Kartestation_card(ctx, u, Stationsnummer, "Stationsname")Zentriert erscheinende große Karte am Kapitelanfang (erste 1,9 Sekunden)
Zusammenfassungs-Endeoutro_doc(ep, ctx, u, T, m, sc, Titel, Untertitel, rows)Konfetti-Regen, stichpunktartige Zusammenfassung und Vorschau auf die nächste Episode als Schlussszene

Drei goldene Regeln zur Vermeidung von Fehlern (Crucial Guardrails)

  1. Untertitel-Sicherheitszone:
    • Der untere Bereich y = 648 ~ 702 ist ausschließlich für automatische Untertitel reserviert.
    • Die Unterkanten aller Informationspanels, Datenkarten und Schaltflächen dürfen y=610 streng nicht überschreiten!
  2. Verbot von Sonderzeichen und Emojis:
    • Pycairo kann unter der Schriftart Noto Sans CJK TC keine Emojis (wie ✨, 📜, 🌱) und spezielle Unicode-Pfeile (➔, ➜) rendern und zeigt stattdessen hässliche Tofu-Blöcke an.
    • Alternative: Verwende für Pfeile -> oder die Funktion arrow(); für Sterne die Funktion star(); für Kreuze reine alphanumerische Symbole wie × oder die Funktion mark(ctx, x, y, False, p).
  3. Schlüsselwortpräzision:
    • phrase in ep.kw(sc, phrase) MUSS eine genaue Teilzeichenfolge des entsprechenden Textes in script.json sein. Es dürfen keine Zeichen hinzugefügt, weggelassen oder Satzzeichen hinzugefügt werden, da dies sonst zu einem Programmabbruch führt.

Referenzdokumente und Beispielressourcen

Verwandte Skills