adao-max/agent-skills

Programmatisches Erklärvideo

Umgebung

• Manim installieren: uv tool install manim. Falls pycairo „pkg-config“ nicht findet, zuerst brew install pkgconf ausführen.
• Sprachausgabe und Transkription mittels MiniMax-Befehlszeilentool mmx. Installation: npm install -g mmx-cli, dann mit mmx auth login --api-key <Ihr MiniMax API-Key> anmelden. Falls mmx „nicht angemeldet“ oder „Kontoguthaben unzureichend“ meldet, den Benutzer benachrichtigen und anhalten.
• contact_sheet.py benötigt Pillow aus dem System-Python sowie ffmpeg und ffprobe (brew install ffmpeg).
• macOS verwendet standardmäßig PingFang SC. Unter Linux zuerst eine chinesische Schriftart installieren, z. B. fonts-noto-cjk (Debian/Ubuntu). Die Basisklasse prüft die Verfügbarkeit der Schriftart und bricht bei Fehlen ab. Benutzerdefinierte Schriftarten werden über EXPLAINER_CN_FONT und EXPLAINER_EN_FONT festgelegt; die Schriftart muss alle im Text vorkommenden Zeichen unterstützen. Für andere Systeme Manim, Pillow und FFmpeg mit dem entsprechenden Paketmanager installieren.
• Die meisten 3Blue1Brown-Beispiele im Netz nutzen manimlib; deren API unterscheidet sich von Manim Community – nicht direkt übernehmen.
• scripts/ dieses Skills:
  • gen_audio.py: Erzeugt Sprachausgabe und wortgenaue Zeitstempel.
  • explainer_base.py: Szenenbasisklasse, Untertitelaufteilung, Timing, Layout und Bereinigung.
  • contact_sheet.py: Erstellt Kontaktabzüge aus Animationsknoten und längsten Untertiteln pro Segment, priorisiert zweizeilige Untertitel.
  • verify_video.py: Prüft Schriftzeichen, Audiospur-Zeiten und Dekodierung des fertigen Videos.
  • test_subtitles.py: Reproduziert alte Fehler mit echtem Manim-Rendering und verifiziert Untertitel-Regressionen.

Ablauf

Das Projektverzeichnis liegt unter ~/video-studio/explainers/<Thema>/.

1. Gliederung schreiben. Nach dem Schema „Problemstellung → konkretes Beispiel → wie sich das Beispiel verändert → allgemeine Regel → neues Beispiel zur Überprüfung → Beantwortung der Eingangsfrage“ in 5 bis 10 Abschnitte unterteilen, jeder Abschnitt behandelt nur einen Punkt. Falls die Gesamtlänge 3 Minuten überschreitet, die Gliederung zuerst vom Benutzer bestätigen lassen.
2. narration.json erstellen. Schlüssel sind die Abschnittsnamen (s1, s2, …), Werte der Sprechertext. Den Sprechertext in gesprochener Sprache, kurzen Sätzen und einem Gedanken pro Satz verfassen. Falls das Skill chinese-writing-style installiert ist, danach richten; 3 bis 6 Sätze pro Abschnitt. Wenn TTS ein bestimmtes englisches Wort oder eine Abkürzung falsch aussprechen könnte, den Wert als {"text": "Text für Bildschirm und Ausrichtung", "tts": "Aussprache für TTS"} angeben.
3. python3 <skill>/scripts/gen_audio.py <Projektverzeichnis> ausführen. Standardstimme für Erklärtexte ist Chinese (Mandarin)_Warm_Girl. Jahreszahlen, Daten und andere Zahlen in tts in chinesischer Lesart angeben; text behält arabische Ziffern auf dem Bildschirm. Nur bestimmte Abschnitte neu erstellen mit --only s3,s5. Falls die Ausgabe „Transkript und Sprechertext stimmen nicht überein“ lautet, prüfen, ob TTS ein Schlüsselwort falsch gelesen hat. Falls ja, tts des betreffenden Abschnitts korrigieren und mit --only wiederholen. Fehlende Wortzeitstempel vorher durch Transkription ergänzen; Untertitel dürfen nicht nach Zeichenanzahl pro Abschnitt geschätzt und dann ausgeliefert werden.
4. Gemeinsame scripts/explainer_base.py per symbolischem Link einbinden, dann scene.py schreiben. Bei bestehenden Projekten zuerst lokale Untertitel-Implementierungen sowie start/finish-Überschreibungen entfernen, die Bildlogik beibehalten, dann alte Basisklasse sichern und durch den Link ersetzen. Das Projekt enthält nur die erklärenden Szenen; die Untertitel werden von der Basisklasse einheitlich generiert.
5. Im Projektverzeichnis manim -ql --disable_caching scene.py <Klassenname> ausführen. Bei Fehler „Bild hinkt hinterher“ die run_time der entsprechenden Animation verkürzen oder die Animation entfernen und neu rendern.
6. python3 <skill>/scripts/contact_sheet.py <Vorschauvideodatei> <Projektverzeichnis> ausführen und jede Zusammenstellung prüfen. Auf Untertitellayout, Überlappungen und Pfeilrichtungen achten. Zeitlich geschätzte Animationsphrasen anhand der vorherigen und nächsten Zeichenzeit in audio/<Abschnittsname>.words.json überprüfen.
7. manim --resolution 1920,1080 --frame_rate 30 --disable_caching scene.py <Klassenname> ausführen. -qh erzeugt 60 fps – nicht verwenden. Mit dem Python-Interpreter, in dem Manim installiert ist, <skill>/scripts/verify_video.py <Fertiges Video> <Projektverzeichnis> ausführen. Der zu uv tool install manim gehörende Interpreter ist $(uv tool dir)/manim/bin/python.
8. Der Prüfbefehl muss mit Exit-Code 0 beenden und qa/video-check.json muss "passed": true enthalten. Bei Fehlern in Zeichen, Audiospur-Zeiten oder Untertitelpositionierung den Bericht, Screenshots und die zugehörige words.json prüfen, korrigieren und neu rendern/validieren. Geschätzte Untertitel dürfen nicht allein auf Basis von Screenshots freigegeben werden.
9. Nach bestandener Prüfung die Datei als <Thema>-Erklaerung.mp4 kopieren, den Pfad dem Benutzer mitteilen und, falls die Umgebung Dateien versenden kann, direkt senden. Die Low-Res-Vorschau unter media/ löschen.

Szenen-Code

from explainer_base import *

class Thema(ExplainerScene):
    def s1(self):
        self.start("s1")              # Sprachausgabe abspielen und synchron Untertitel anzeigen
        titel = cn("Lernrate", 60, HI)
        self.play(Write(titel))
        self.until("Lernrate zu klein")   # Warten, bis der Sprecher diese Phrase erreicht
        self.play(titel.animate.to_edge(UP))
        self.finish()                 # Warten, bis Sprachausgabe beendet, Untertitel löschen und Szene ausblenden

• Jeder Abschnitt erhält eine Methode mit dem gleichen Namen wie der Abschnitt.
• start, finish oder den Untertitel-Updater nicht im Projekt überschreiben. Falls der Benutzer explizit keine Untertitel wünscht, die Klassenattribut SUBTITLES = False setzen.
• Szenenwechsel innerhalb eines Abschnitts: nur die selbst erstellten Objekte ausblenden oder entfernen, die Basisklassen-Untertitel erhalten. Nicht self.mobjects komplett leeren oder self.clear() aufrufen.
• Die Phrase in until muss exakt im text des zugehörigen Abschnitts vorkommen und zwar genau einmal.
• Chinesisch mit cn(), Englisch mit en(). Schriftgröße nicht kleiner als 22.
• Nur die 4 Farben der Basisklasse verwenden: MAIN Hauptfarbe, HI Hervorhebung, OK richtig, BAD falsch. Eine Farbe behält ihre Bedeutung im gesamten Video bei.
• Maximal 3 Elementgruppen pro Bildschirm. Vor neuen Inhalten zuerst die nicht mehr besprochenen Inhalte ausblenden.
• Die unteren 20 % des Bildschirms sind für Untertitel reserviert; Diagramme und Erklärungstext oberhalb dieses Bereichs platzieren.
• Das gerade besprochene Objekt erscheint, ändert seine Farbe oder bewegt sich.

Häufige Fallstricke

• Nach Änderungen am gemeinsamen Untertitel-Code test_subtitles.py mit dem Python-Interpreter ausführen, in dem Manim installiert ist. Es muss Tests für echte Wartezeiten, Abschnittswechsel, zweizeilige Untertitel, wiederholte Kurzphrasen, Seitenumbrüche bei langen Sätzen und unterschiedliche Aussprache bestehen. Das manuelle Setzen von renderer.time und Aufrufen des Updaters allein kann das statische Warteverhalten von Manim nicht validieren.
• Text führt keinen automatischen Zeilenumbruch durch; bei langen Sätzen \n für Zeilenumbrüche verwenden.
• Text, der in einen Rahmen gesetzt wird, mit fit(Text, Rahmenbreite * 0.8) begrenzen.
• Beim Durchstreichen von Optionen mit Cross nur den Text kreuzen, nicht den Pfeil; den Pfeil stattdessen auf BAD-Farbe setzen.
• Um einzelne Wörter in einem Satz einzufärben, Text(..., t2c={"Wort": Farbe}) verwenden.