Merk-Rap Video (Mathe-Rap)
Verwandle ein beliebiges Wissensthema in ein etwa einminütiges Erklärvideo. Es bleibt im Gedächtnis, weil drei Ebenen aufeinander abgestimmt sind und alle derselben Spur folgen:
- Ohr: Fester Rhythmus, ein Satz pro Takt, durchgehender Reim – einprägsam
- Sprache: 8–10 Zeichen Merkspruch, 2–3 Mal wiederholt, oben im Bild fixiert
- Auge: Zu jedem gesungenen Wort bewegt sich die Grafik einen Schritt weiter – der Betrachter sieht, warum es stimmt
Die Erzählstruktur ist festgelegt: Problem stellen → Falle aufbauen (umständlicher Weg) → Merkspruch geben → Vorführen → Prinzip erklären → Abschluss.
Wer macht was?
| Teil | Wer macht es | Erläuterung |
|---|---|---|
| Merkspruch, Lyrics, Storyboard | Du (KI) schreibst, der Nutzer bestätigt | Regeln unter references/lyrics.md |
| Audio (Stimme + Musik) | Nutzer oder Kunde selbst | Welches Modell, welche Stimme – entscheiden sie. Gib ihnen die Anforderungen aus references/audio.md („Anforderungen an den Kunden“). Dieses Skill wählt keine Plattform für den Nutzer aus und gibt kein Geld automatisch aus |
| Untertitel-Timings | Skript errechnet | Jedes SRT aus beliebigen Tools funktioniert, Tippfehler sind ok |
| Hintergrund-Bilder | Bibliothek wählt automatisch | assets/backgrounds/, nach Einsatzzweck getaggt; du kannst eigene hinzufügen |
| Grafiken, Merkspruch, Formeln, Untertitel | Skript malt Frame für Frame | Du schreibst nur die Dateien storyboard.json und graphics.py |
Umgebung
Führe vor dem ersten Gebrauch den Selbsttest aus; er zeigt dir Schritt für Schritt, was fehlt und wie du es installierst:
python $SKILL/scripts/check_env.py
Erforderlich: Python 3.10+ (pip install pillow numpy librosa pypinyin), ffmpeg / ffprobe, eine chinesische Schriftart mit Fettdruck (systemweit verfügbar wird automatisch gefunden), die Hintergrund-Bibliothek. Die Bibliothek wird in dieser Reihenfolge gesucht: Umgebungsvariable MATH_RAP_LIBRARY → assets/backgrounds/ dieses Skills → globales Verzeichnis ~/.math-rap-video/backgrounds/. Fehlt die Bibliothek, führe python $SKILL/scripts/install.py --library <Bibliothek.zip> aus.
Im folgenden steht $SKILL für das Verzeichnis dieses Skills (der Ordner, in dem diese SKILL.md liegt). Es ist keine voreingestellte Umgebungsvariable: Ersetze es beim Ausführen durch den tatsächlichen Pfad oder setze es einmal (bash: export SKILL="/Pfad/math-rap-video"; PowerShell: $SKILL="C:\Pfad\math-rap-video"). Pfade mit Leerzeichen oder chinesischen Zeichen müssen in Anführungszeichen gesetzt werden. Alle Skripte sind normale Kommandozeilenprogramme (alle unterstützen --help) – jeder, der Befehle ausführen kann (KI oder Mensch), kann sie verwenden.
Ablauf
1 Text + Storyboard ──→ 2 Nutzer liefert Audio ──→ 3 prepare_audio berechnet Timings & prüft
│
4 storyboard.json + graphics.py schreiben ←──────────────────┘
│
5 Check + Vorschaubilder (zum Absegnen) ──→ 6 build_video erstellt Video ──→ 7 Prüfen und ausliefern
Nach jedem Schritt dem Nutzer eine kurze Rückmeldung geben. Schritt 1 und Schritt 5 setzen die Bestätigung des Nutzers voraus, bevor es weitergeht.
Wenn der Nutzer fertige Lyrics und passendes Audio mitbringt (Lyrics sind abgeschlossen, Audio darauf aufgenommen): Kein einziges Zeichen in den Lyrics ändern, sonst passen Bild und Gesang nicht zusammen. Schritt 1 beschränkt sich dann auf: neues Projekt anlegen, Lyrics unverändert in lyrics.md kopieren, am Ende die Storyboard-Tabelle anhängen; die Ergebnisse von check_lyrics.py dienen nur als Referenz – ändere nichts nach Vorschlag. Dann gleich mit Schritt 3 fortfahren.
1. Neues Projekt anlegen, Merkspruch, Lyrics und Storyboard schreiben
python $SKILL/scripts/new_project.py <Projektverzeichnis> # Kopiert das Beispiel (Strecken zählen) als Startpunkt
python $SKILL/scripts/new_project.py <Projektverzeichnis> --blank # Oder mit leerem Template beginnen
Schreibe lyrics.md gemäß references/lyrics.md: Ein Satz = ein Takt, jeder Satz 11–15 Zeichen (Prinzip-Teil 9–11 Zeichen), durchgängiger Reim; Aufbau ist Verse 1 (14 Sätze) + Hook (2 Sätze, Merkspruch solo) + Verse 2 (8 Sätze).
Das Storyboard gehört in den Abschnitt ## Storyboard am Ende von lyrics.md (eine Tabelle: Satznummer, Bildaktion, das Wort, bei dem die Aktion ausgelöst wird). Es dient der Bestätigung durch den Nutzer und als Grundlage für Schritt 4; das Skript liest es nicht.
Nach dem Schreiben führe die Lyrics-Prüfung aus. Korrigiere alles, was als „Muss geändert werden“ markiert ist; prüfe die „Empfehlungen“ einzeln:
python $SKILL/scripts/check_lyrics.py <Projektverzeichnis> # Struktur, Zeichenzahl pro Satz, Reim, leicht verwechselbare Schreibweisen
Jede Zahl in den Beispielen selbst nachrechnen (Skript kann keine Mathematik prüfen). Gib Merkspruch, Lyrics und Storyboard dem Nutzer zur Bestätigung.
2. Nutzer liefert Audio
Gib dem Nutzer die bestätigten Lyrics sowie die „Anforderungen an den Kunden“ aus references/audio.md. Sie können das Audio auf jede erdenkliche Weise erstellen: KI-Musikplattform, echter Rap, TTS oder aufgesprochener Text mit Hintergrundmusik. Was sie zurückgeben:
- Eine oder mehrere Audiodateien (mp3 / wav) mit Stimme. Bei KI-generiertem Audio empfehle 2–3 Versionen zur Auswahl
- Idealerweise auch eine Untertitel-Datei (SRT). Fehlt sie, verwende ein beliebiges Spracherkennungstool, um das Audio einmal zu durchlaufen und ein SRT zu exportieren
Wenn der Nutzer ausdrücklich verlangt, dass du das Lied für ihn erstellst, und dafür einen ElevenLabs-API-Key bereitstellt, kannst du scripts/gen_music.py verwenden (Anleitung unter references/audio.md). Das ist optional – jede Version kostet Guthaben des Nutzers, kläre das vorher.
3. Audio verarbeiten: Timings berechnen und prüfen, ob diese Version verwendbar ist
python $SKILL/scripts/prepare_audio.py <Projektverzeichnis> --audio Lied.mp3 --srt erkennung.srt --bpm 90 --intro-bars 2
Es gleicht die erkannnte Transkription mit den Lyrics ab (Tippfehler, abweichende Worttrennungen sind egal), misst Geschwindigkeit und Takt, schreibt timing.json und kopiert die Audiodatei in das Projektverzeichnis (beim Rendern wird von dort gelesen – daher taucht dort eine Audiodatei auf, das ist normal). Die letzte Zeile gibt eine Bewertung:
- Verwendbar: Weiter. Bei Sätzen mit „niedriger Übereinstimmungsrate“ notieren und den Nutzer beim Ausliefern bitten, diese Stellen anzuhören
- Version wechseln empfohlen (Exit-Code 3): Die Gründe werden aufgelistet – typischerweise wurde ein Satz nicht gesungen, die Stimme setzt zu spät ein, oder das gesamte Stück klingt gequetscht. Wechsle die Audiodatei, erzwinge keine Verwendung
Bei mehreren Audio-Versionen jede als eigene Datei verarbeiten und dann die beste kopieren:
python $SKILL/scripts/prepare_audio.py <Verzeichnis> --audio generiert_01.mp3 --srt 01.srt --bpm 90 --intro-bars 2 --out timing_01.json
python $SKILL/scripts/prepare_audio.py <Verzeichnis> --audio generiert_02.mp3 --srt 02.srt --bpm 90 --intro-bars 2 --out timing_02.json
cp <Verzeichnis>/timing_02.json <Verzeichnis>/timing.json
Wie du auswählst, steht in references/audio.md Abschnitt 3. Kurz: Schließe zuerst alle „Version wechseln empfohlen“-Fälle aus; wähle dann die Version mit der höchsten Übereinstimmungsrate bei den Merkspruch-Sätzen; die Takt-Stabilität kommt erst danach. Wenn sich diese Kriterien widersprechen: Merkspruch-Klarheit vor Takt-Stabilität – das Publikum behält den Merkspruch.
Sonderfälle: Reine Erzählvertontung oder Audio ohne Takt mit --no-beat verarbeiten; falls kein SRT vorhanden ist, kann --grid --entry <Einsatzzeitpunkt der Stimme in Sekunden> als Fallback dienen (pro Satz einen Takt annehmen); --intro-bars schreibt die mit dem Kunden vereinbarte Anzahl von Einleitungstakten (im Beispiel oben sind 2 der Standard, den wir dem Kunden vorgeben). Fehlt eine solche Absprache, weglassen. In der Windows PowerShell funktioniert cp; in cmd ersetze es durch copy.
Audio wechseln bedeutet nur diesen Schritt wiederholen – das Storyboard bleibt unverändert.
4. Storyboard und projektspezifische Grafik schreiben
Lies references/visuals.md und bearbeite dann zwei Dateien im Projektverzeichnis:
storyboard.json: Merkspruch-Banner, Formeln, eingeblendete Wörter, Pfeile, Plan für Hintergrundwechselgraphics.py: Die für dieses Thema spezifische Grafik – implementieresetup(ctx)unddraw(canvas, t, ctx)
Die wichtigste Regel: Zeitangaben immer als Ausdrücke relativ zu den gesungenen Wörtern schreiben, niemals absolute Sekunden einfügen.
| Schreibweise | Bedeutung |
|---|---|
L(6) / E(6) | Anfang / Ende von Satz 6 |
W(9,'四') / W(9,'四',2) | Der Zeitpunkt, an dem im 9. Satz das Zeichen „四“ (bzw. das zweite „四“) gesungen wird |
B, L(6)+2*B | Ein Takt; zwei Takte nach Satz 6 |
So ist die Grafik wirklich am Gesang ausgerichtet, und der Kunde kann in Schritt 3 einfach die Audiodatei wechseln – das Bild muss nicht neu abgestimmt werden.
Die Grafik ist der aufwändigste Schritt. Die Engine bietet bereits viele gängige Zeichenmethoden (Punkte, Linien, Bögen, Winkelbögen, rechte Winkel, Zahlenblöcke, Klammern, mehrfarbige Formeln in einer Zeile, Drehung/Verschiebung, Bewegung auf einem Pfad, gleichmäßige Verteilung). Suche zuerst in references/visuals.md Abschnitt 4 nach fertigen Lösungen, fang nicht bei Null an. Erzeuge nach jedem kleinen Abschnitt eine Vorschau (siehe nächster Schritt) und warte nicht, bis alles fertig ist.
Die zwei häufigsten Fehler – vermeide sie von Anfang an:
- Grafik zu klein / zu fein: Das wird auf dem Handy angesehen. Die Grafik muss mehr als die halbe Bildbreite einnehmen (Breite ≥ 800 oder Höhe ≥ 400). Eine Reihe von Elementen füllst du mit
ctx.spread(n)über die volle Breite. Linienbreite ≥ 9, Schriftgröße ≥ 44. Maße unterreferences/visuals.mdAbschnitt 1 - Jeder Satz braucht eine visuelle Aktion. Grafik, eingeblendetes Wort oder Formel – mindestens eines muss in der Bildmitte erscheinen. Kein Satz darf nur aus Hintergrund und Untertitel bestehen
5. Prüfen und Vorschau
python $SKILL/scripts/overlay_engine.py <Projektverzeichnis> check # Muss: 0 Storyboard-Probleme, 0 Render-Fehler; „Layout-Hinweise“ einzeln prüfen
python $SKILL/scripts/overlay_engine.py <Projektverzeichnis> sheet # Übersichtsbild.jpg: eine Miniatur pro Satz
python $SKILL/scripts/overlay_engine.py <Projektverzeichnis> sheet --pages # Zusätzlich Übersichtsbild_p1.jpg…: große Einzelseiten, damit Text an den Rändern sichtbar wird (das Übersichtsbild wird auch aktualisiert)
python $SKILL/scripts/overlay_engine.py <Projektverzeichnis> frames "L(18)" "L(19)" 0.2 # Storyboard_frame.jpg: eine Animation als Einzelbilder
Öffne die Bilder selbst und prüfe Frame für Frame gegen das Storyboard:
- Übersicht: Ist in jedem Satz alles vorhanden, was dort sein soll? Gibt es leere Kästchen?
- Große Einzelseiten: Überlappt sich Text? Stößt er an das Merkspruch-Banner oder gegen die Untertitel? Sind Linien dick und groß genug?
- Bei Bewegungen, Drehungen oder Einflügen: Prüfe mit
frames, ob etwas auf dem Weg mit anderem kollidiert - Die von
checkgemeldeten „Layout-Hinweise“: Sieh dir jede markierte Stelle an (es meldet: zu nah am Banner, auf Untertiteln, überlappt mit Formeln, berührt den Rand, Grafik zu klein, Bildmitte leer, Text überlappt) - Was
checknicht prüft: Text, der auf Linien oder Farbflächen schwer lesbar ist; falsche Anzahl von grafischen Elementen; Farben, die nicht ausreichend kontrastieren. Das siehst du nur auf den großen Einzelseiten
Bei Fehlern zurück zu Schritt 4. Wenn alles in Ordnung ist, gib das Übersichtsbild dem Nutzer zur Bestätigung und starte die Videoproduktion.
6. Video erstellen
python $SKILL/scripts/build_video.py <Projektverzeichnis> bg # Hintergrund aussuchen und zusammenfügen; gibt aus, welches Material wo verwendet wurde
python $SKILL/scripts/build_video.py <Projektverzeichnis> final 20 30 # Optional: erstmal nur einen 10-Sekunden-Ausschnitt testen
python $SKILL/scripts/build_video.py <Projektverzeichnis> final # Vollvideo (ca. 6–12 Minuten, je nach Rechner); im Hintergrund laufen lassen
python $SKILL/scripts/build_video.py <Projektverzeichnis> sheet # Final_Uebersicht.jpg
python $SKILL/scripts/make_vertical.py <Projektverzeichnis> --title "Titel" # Optional: vertikale Version (Douyin, TikTok, Video-Konto)
bg erkennt automatisch, ob ein Abschnitt grafische Elemente enthält; dann wählt es nur „ruhige“ Hintergrundclips (ohne helle Gesichter) und vermerkt das in der Ausgabeliste. Wenn alle Vorschauen abgeschlossen sind, kannst du auch build_video.py <Projektverzeichnis> all verwenden, um in einem Befehl check + bg + final + Übersichtsbild zu erzeugen. Die vertikale Version platziert das horizontale Video mittig in einer 1080×1920-Leinwand, oben mit Titel, unten mit kleinem Text; der Rest wird mit unscharf vergrößertem Hintergrund gefüllt. Die vertikale Version ordnet die Grafiken nicht neu an. Wenn bei make_vertical.py kein --title angegeben wird, liest es den Wert vertical.title aus storyboard.json; falls auch das fehlt, verwendet es den Titel der Lyric-Datei.
7. Prüfen und ausliefern
Betrachte Final_Uebersicht.jpg: Ist der Hintergrund dunkel genug? Sind Grafik und Schrift klar erkennbar? Liegt ein helles Gesicht aus dem Hintergrund zufällig hinter einem eingeblendeten Wort oder einer Beschriftung? (Falls ja, füge im Hintergrundplan für diesen Satz :quiet oder einen bestimmten Clip hinzu, führe erneut bg und final aus.) Gib dann Final.mp4 an den Nutzer weiter und erkläre:
- Bild und Zeitsteuerung wurden durch das Skript validiert, aber die Synchronisation muss ein Mensch abhören: Bitte achte besonders darauf, dass das Erscheinen des Merkspruchs und der Ergebniszahlen mit dem Gesang übereinstimmt
- Für die in Schritt 3 als „niedrige Übereinstimmungsrate“ markierten Sätze: Bitte höre sie dir gezielt an
Referenzdateien
| Datei | Wann lesen |
|---|---|
references/lyrics.md | Bevor du Merkspruch, Lyrics und Storyboard schreibst |
references/audio.md | Wenn der Nutzer fragt, welches Tool er für Musik/Sprache verwenden soll; wenn du die Audio-Anforderungen an den Kunden senden musst; bei der Prüfung und Auswahl von Audio |
references/visuals.md | Bevor du storyboard.json und graphics.py schreibst (Layout, Felder, Zeichenwerkzeuge, gängige Darstellungen für häufig vorkommende Aufgabentypen) |
references/library.md | Wenn du der Bibliothek neue Clips hinzufügen, neue Hintergründe erzeugen oder unpassende Auswahlen korrigieren willst |
references/troubleshooting.md | Wenn bei einem Schritt ein Fehler auftritt oder das Ergebnis nicht stimmt |
references/teaching.md | Wenn der Nutzer die Prinzipien verstehen, anderen zeigen oder keine Codedateien schreiben möchte (CapCut-Methode) |
references/compatibility.md | Wenn der Nutzer fragt, ob andere KI / andere Modelle das auch können; wenn du das Skill an andere weitergibst |
examples/shuxianduan/ | Vollständiges Beispiel: Lyrics, Storyboard, Grafik. Lies es dir vor dem Schreiben eines neuen Themas komplett durch |
Skript-Übersicht
| Skript | Funktion |
|---|---|
check_env.py | Umgebungs-Selbsttest |
new_project.py | Neues Projektverzeichnis anlegen |
check_lyrics.py | Lyrics-Prüfung |
prepare_audio.py | Audio + Untertitel → timing.json; gibt „verwendbar“ oder „Version wechseln“ aus |
overlay_engine.py | Prüfen, Vorschau, Rendern der Overlay-Schicht |
build_video.py | Hintergrund auswählen, Video zusammensetzen, Übersichtsbild erstellen |
make_vertical.py | Querformat → Hochformat |
library_tool.py | Hintergrund-Bibliothek verwalten (hinzufügen, löschen, Tags ändern, Übersichtsbild) |
gen_music.py | Optional: Lieder mit ElevenLabs generieren |
install.py | Dieses Skill in andere KI-Tools einbinden (Codex, Gemini CLI, opencode usw.) und die Bibliothek bereitstellen |
chat_pack.py | Für reine Chat-KIs: erzeugt Prompt-Pakete (Lyrics schreiben / Bild beschreiben / nach Prüfung korrigieren) |