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
- TTS-Anforderungsdatei erstellen:
Hinweis: Stilhinweise (z. B. authentisches Taiwanesisch, lebhafter Reiseführer) MÜSSEN impython3 tools/make_payloads.py ep1instructions-Feld platziert werden. Sie DÜRFEN NICHT in dasinput-Feld gesetzt werden, sonst werden sie vorgelesen. - Stapelanforderung von Sprachdateien:
bash tools/tts.sh ep1 - 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
- Normalwert für männliche Stimme
- Sprachbeschleunigung und Formatierung:
Beschleunigt die Dateien mitbash tools/prep.sh ep1atempo=1.1und gibt sie alsep1/c1.pcm~ep1/cN.pcmaus.
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_hostaus, 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.pngzusammen. - Wichtige Prüfpunkte:
- Tofu-Blöcke (fehlende Zeichen) im Text.
- Inhalte, die den Zeichenbereich überschreiten oder sich überschneidende Zeichenfolgen.
- Untere Informationskarten, die in den Untertitelbereich eindringen (darf nicht unter y=610 reichen).
- Kollision zwischen rechten Seitenkarten und dauerhaftem unterem Bildschirm-Moderator.
Phase 6: Vollständiges Video-Rendering und FFmpeg-Überprüfung
- Offizielles Rendern in MP4:
Die Engine synthetisiert automatisch das 1280×720 H.264-Video, erstellt Untertitel, mischt Hintergrundmusik (automatisch leiser gestellt) und kapselt AAC-Audio.python3 ep1.py - Integritätsprüfung ohne Verluste:
Keine Fehler im Terminal bedeuten, dass Audio und Video synchron und die Kapselung perfekt ist.ffmpeg -v error -i ausgegebene_datei.mp4 -f null -
Kern-API-Spickzettel
| Funktion | Syntax | Beschreibung |
|---|---|---|
| Fortschrittsberechnung | prog(u, t0, d=0.5) | Beginnt bei Sekunde t0, wird über d Sekunden von 0 auf 1 gehen |
| Springen und Skalieren | pop(ctx, cx, cy, p) | Springt um einen Mittelpunkt herum ein (mit Back-Kurve) |
| Schlüsselwortausrichtung | ep.kw(sc, "Text", nth=0) | Berechnet die genaue Zeit, zu der das Wort gesprochen wird (automatisch 0,25 Sekunden vorgezogen) |
| Abgerundetes Rechteck | rrect(ctx, x, y, w, h, r) | Definiert einen abgerundeten Rechteckspfad |
| Füllen und Umranden | fillstroke(ctx, fill, stroke, lw=5) | Gleichzeitig füllen und mit dunkler Farbe umranden |
| Einzeiliger Text | text(ctx, s, x, y, size, col, align='c') | Zeichnet Text, optional linksbündig 'l', zentriert 'c', rechtsbündig 'r' |
| Kapsel-Tag | chip(ctx, "Tag", x, y, p, col, size=30) | Aufklappbare Kapselkarte |
| Aufklapp-Panel | if panel(ctx, x, y, w, h, p): ... ctx.restore() | Inhalts-Panel mit weißem Hintergrund (muss mit restore gepaart sein) |
| Moderator unten rechts | corner(ctx, T, m) | Zeichnet eine verkleinerte Version des dauerhaften Moderators unten rechts |
| Kapitelüberschrift-Karte | station_card(ctx, u, Stationsnummer, "Stationsname") | Zentriert erscheinende große Karte am Kapitelanfang (erste 1,9 Sekunden) |
| Zusammenfassungs-Ende | outro_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)
- Untertitel-Sicherheitszone:
- Der untere Bereich
y = 648 ~ 702ist ausschließlich für automatische Untertitel reserviert. - Die Unterkanten aller Informationspanels, Datenkarten und Schaltflächen dürfen y=610 streng nicht überschreiten!
- Der untere Bereich
- Verbot von Sonderzeichen und Emojis:
- Pycairo kann unter der Schriftart
Noto Sans CJK TCkeine Emojis (wie ✨, 📜, 🌱) und spezielle Unicode-Pfeile (➔, ➜) rendern und zeigt stattdessen hässliche Tofu-Blöcke an. - Alternative: Verwende für Pfeile
->oder die Funktionarrow(); für Sterne die Funktionstar(); für Kreuze reine alphanumerische Symbole wie×oder die Funktionmark(ctx, x, y, False, p).
- Pycairo kann unter der Schriftart
- Schlüsselwortpräzision:
phraseinep.kw(sc, phrase)MUSS eine genaue Teilzeichenfolge des entsprechenden Textes inscript.jsonsein. Es dürfen keine Zeichen hinzugefügt, weggelassen oder Satzzeichen hinzugefügt werden, da dies sonst zu einem Programmabbruch führt.
Referenzdokumente und Beispielressourcen
- Engine-Architektur und alle integrierten geometrischen Komponenten: references/engine-api.md
- Vektor-Charakterdesign und Implementierung von Atmung/Blinzeln/Sprachmund: references/character-design.md
- TTS-Anforderungsspezifikation, F0-Tonhöhenalgorithmus und Audioverarbeitung: references/audio-tts-pipeline.md
- Zeichenflächensicherheitszone, Vermeidung fehlender Zeichen und Fehlervermeidungsliste: references/layout-and-pitfalls.md
- Charaktervorlagencode: examples/character_template.py
- Minimalistische vollständige Episodenvorlage: examples/minimal_episode.py