syydaniel/kazi

卡字

Kazivideos folgen dem Beat, Erklärvideos dem Wort. Die KI, die Animationscode schreibt, hört keinen Ton; sie kann nur raten, wohin der Zuschauer in dieser Sekunde sehen soll.

卡字 dreht die Reihenfolge um: Zuerst kommt der Ton, dann das Bild – das Bild folgt immer dem Ton. Zuerst wird berechnet, in welcher Sekunde jedes Wort gesprochen wird; dann wird aus einer Tabelle abgelesen, auf welchem Frame die Aktion stattfindet.

Diese Anleitung ist für dich (die KI). Details zu jedem Schritt findest du in docs/ – lies sie, wenn du sie brauchst, nicht auf einmal. Die folgenden Verzeichnisse tools/, starter/, docs/ befinden sich alle im selben Verzeichnis wie diese Datei. Ersetze sie bei der Verwendung durch den vollständigen Pfad.

Sechs Schritte, vier Pausen

Schritt	Was zu tun ist	Ergebnis	Details
1 Skript	Schreibe, wie gesprochen wird; pro Satz ein Schlüsselwort; getrennte Versionen für Voice-Over und Untertitel	script.txt	docs/01_Skript.md
⏸ Pause 1	Zeige das Skript dem Nutzer und warte auf sein OK
2 Voice-Over	Generiere mehrere Versionen pro Satz; ein anderes KI-Modell hört zurück und bewertet; behalte die beste	vo/lines/	docs/02_Voice-Over.md
⏸ Pause 2	Lass den Nutzer den gesamten Voice-Over anhören
3 Zeiterfassung	Das Ausrichtungsmodell markiert für jedes Wort die Start- und Endzeit	timeline.json	docs/03_Zeiterfassung.md
4 Bild	Zeichne Verben; die Aktion setzt 3 Frames vor dem ersten Zeichen des Schlüsselworts ein	Code + Rendering	docs/04_Bild.md
⏸ Pause 3	Erstelle zunächst einen 20- bis 30-sekündigen Sample-Clip für den Nutzer	out/sample.mp4
5 Ton	Hintergrundmusik weicht dem Voice-Over; Soundeffekte werden aus Animations-Cues gelesen	Gemischte Tonspur	docs/05_Ton.md
6 Prüfung und Veröffentlichung	Messe Frame für Frame: Trefferquote, schwarze Frames, Einzelframes, Flackern, Lautstärke; bereite Titel, Cover und Beschreibung vor	out/final.mp4 + Prüfbericht	docs/06_Prüfung_Veröffentlichung.md
⏸ Pause 4	Übergib den finalen Clip und den Prüfbericht an den Nutzer

Wenn der Nutzer ausdrücklich „Mach ohne Pause, mach einfach durch“ sagt, können die Pausen übersprungen werden. Schritt 6 muss jedoch immer ausgeführt werden, und die Ergebnisse müssen in die endgültige Antwort einfließen. Wenn der Nutzer bereits einen fertigen Voice-Over hat, überspringe Schritt 2 und beginne direkt mit Schritt 3 (timeline.py --whole).

Vor Arbeitsbeginn

1. Führe python tools/doctor.py aus, um zu prüfen, was fehlt. Voice-Over und Zeitachsen-Ausrichtung wurden nur auf Macs mit Apple Silicon getestet; für andere Plattformen folge den Ersatzlösungen und informiere den Nutzer.
2. Frage (nur, was der Nutzer nicht schon gesagt hat): Worum geht es? Für wen? Wie lang? Quer- oder Hochformat? Hast du eine eigene Sprachprobe (ca. 10 Sekunden saubere Aufnahme + Transkript)?
3. Erstelle die Projektverzeichnisstruktur (siehe unten). Alle Zwischendateien bleiben erhalten; jede Version des Sample-Clips separat speichern, nicht überschreiben.

Projekt/
  script.txt          Skript (Format siehe docs/01)
  vo/                 Voice-Over: lines/ eine wav pro Satz, takes/ alle Versionen
  timeline.json       Start- und Endzeit jedes Satzes und jedes Wortes
  film/               Bildprojekt (standardmäßig Remotion-Vorlage aus starter/)
  audio/              Hintergrundmusik, Soundeffekte, Mix
  out/                Sample-Clips, Final-Clip, Prüfbericht

Die wichtigsten Regeln pro Schritt

Skript (Details in docs/01)

• Schreibe, wie gesprochen wird. Maximal 22 Zeichen zwischen zwei Satzzeichen; kurze und lange Sätze abwechseln. Das Ohr hört nur einmal.
• Pro Satz nur ein Schlüsselwort markieren: *Schlüsselwort*. Das Bild trifft auf dieses Wort. Maximal ein Schlüsselwort pro Untertitel.
• Wenn Aussprache und Untertitel unterschiedlich sind, schreibe {Aussprache=>Untertitel}, z. B. {F F M peg=>FFmpeg}.
• Sätze vollständig formulieren: Subjekt, Objekt, Maßangaben nicht weglassen; Verben vorzugsweise aus zwei oder mehr Zeichen; einzelne und mehrfache Zeichen abwechseln; Schlüsselwörter nicht aus einem Zeichen. Pausen nach Sinn setzen (siehe Pausentabelle in docs/01).
• Polyphone Zeichen, die leicht falsch ausgesprochen werden, bereits im Skript ersetzen (Ersatztabelle in docs/02).
• Nach dem Schreiben python tools/lint_script.py script.txt ausführen – es prüft auf zu lange Atemzüge, zu lange Untertitel, mehrere Schlüsselwörter pro Satz und schätzt die Dauer.

Voice-Over

• python tools/voice.py script.txt vo --ref Sprachprobe.wav: Generiere 4 Versionen pro Satz; wandle sie per Spracherkennung zurück in Text und vergleiche mit dem Original; verwirf falsch ausgesprochene Versionen und behalte die beste.
• Polyphone Zeichen oder Wörter, die anders klingen, werden im Erkennungsergebnis sichtbar; passe den Satz oder die Aussprache an, anstatt es zu erzwingen.
• Für eine insgesamt schnellere Geschwindigkeit verwende tools/tempo.py (Tempoänderung ohne Tonhöhenänderung), keine Neugenerierung.
• python tools/pace.py vo_fast vo_paced: Normalisiere Pausen. Miss Stille am Satzanfang und -ende sowie an Satzzeichen im Satz; kürze zu lange und ergänze zu kurze Stille; ändere nur die Stille, nicht die Stimme.
• tools/polyphone.py extrahiert polyphone Zeichen, die falsch ausgesprochen werden könnten, und erstellt ein Hörbeispiel; es kann Fehlalarme und Fehler geben – letztlich entscheidet das menschliche Gehör.

Zeiterfassung

• python tools/timeline.py script.txt vo_paced timeline.json --wav vo_paced/narration.wav --speech-gap – erhält die Start- und Endzeit jedes Satzes und jedes Wortes sowie eine Liste der Schlüsselwörter. --speech-gap sorgt dafür, dass die Pausen im Skript der hörbaren Stille entsprechen.
• Alle zeitrahmenspezifischen Momente im Bild werden aus dieser Tabelle abgelesen. Nicht nach Wortzahl schätzen. Nach zehn Sätzen beträgt der Fehler bereits mehr als drei Sekunden.

Bild

• Lege zuerst den Bildstil fest. Unsicher? Durchstöbere den Code-Stil-Katalog unter https://github.com/syydaniel/awesome-code-animation ; wähle zuerst den Stil, dann das Werkzeug. Ohne besonderen Grund die starter/-Vorlage (Remotion) verwenden.
• Zeichne Verben, keine Nomen. „Volumen vergrößern“ erfordert den Vorgang des Vergrößerns, keine Illustration eines Eisblocks. Tabelle mit gebräuchlichen Verben in docs/04.
• Zeitkonstanten (bei 60 fps): Der Frame, in dem die Aktion eintrifft, liegt 3 Frames vor dem Start des ersten Zeichens des Schlüsselworts (hit()); erlaubt sind 6 Frames früher bis 1 Frame später. Neu erscheinende Elemente erscheinen mindestens 12 Frames vor dem Schlüsselwort.
• Beim Schlüsselwort muss das Bild merklich mehr Bewegung zeigen als in der vorherigen Sekunde. Wenn die ganze Zeit Bewegung herrscht oder die Bewegung nur zu Satzbeginn einmal auftritt, passt die Synchronisation nicht.
• Maximal 4 Info-Blöcke pro Bildschirm; bereits gesprochene vollständige Sätze nicht mehr einblenden, nur das Schlüsselwort.
• Ein durchgängiges Element (ein kleines Männchen, eine Farbe, eine Form) finden; die Kamera zoomt und folgt dem Fokus; Übergänge zwischen zwei Bildern nach Möglichkeit über ein Element im Bild.
• Untertitel: Maximal 16 Zeichen, Kommas und Punkte entfernen; Zeichen werden je nach tatsächlicher Sprechzeit von hell zu dunkel, Schlüsselwörter wechseln die Farbe.
• Nach jedem Abschnitt eine kurze Szene rendern und mit tools/kazi_check.py messen, bevor es weitergeht.

Ton

• Hintergrundmusik 12 bis 18 LU unter dem Voice-Over; nach Wortzeit weichen: 0,2 Sekunden vor Satzbeginn absenken, nur bei Satzpausen über 1,2 Sekunden wieder anheben.
• 2 bis 4 Musikpausen im gesamten Film für die wichtigsten Sätze.
• Soundeffekte werden aus den Animations-Cues (Cues) exportiert, in vier Schichten: Treffer, Übergang, Atmosphäre, Foleys. Klangqualität folgt dem Bild.
• Gesamtlautstärke -14 LUFS, wahrer Spitzenpegel max. -1 dBTP, 48 kHz.

Prüfung

• python tools/kazi_check.py out/final.mp4 --timeline timeline.json: Trefferquote, zufällige Baseline, schwarze Frames, Einzelframes, lange Stillstände, Lautstärke, Tonspur, Filmlänge.
• Wenn nicht bestanden, zurück und korrigieren; dann erneut messen. Erst bei vollständigem Bestehen den Nutzer informieren und die Zahlen aus dem Bericht exakt wiedergeben. Nicht „abgeschlossen“ sagen, wenn nicht gemessen wurde.
• Wenn der Nutzer 4K oder HDR wünscht, nach erfolgreicher Prüfung ausführen: tools/master.sh für 4K-Master rendern, tools/hdr/hdr_encode.sh für Dolby Vision 8.4 und HLG. Bei geänderter Farbgebung die neue Hintergrund- und Leuchtfarbe an hdr_mask.py übergeben (siehe docs/06_Prüfung_Veröffentlichung.md).

Werkzeugübersicht

Werkzeug	Zweck
tools/doctor.py	Prüft die Umgebung: Was fehlt, wie installieren
tools/lint_script.py	Prüft das Skript
tools/voice.py	Klont die Stimme, spricht satzweise ein, wählt die beste Version aus mehreren
tools/tempo.py	Ändert die Gesamtgeschwindigkeit ohne Tonhöhenänderung
tools/pace.py	Normalisiert Pausen: Stille am Satzanfang und -ende sowie an Satzzeichen
tools/polyphone.py	Extrahiert polyphone Zeichen, die falsch ausgesprochen werden könnten, erstellt ein Hörbeispiel
tools/timeline.py	Wortgenaue Ausrichtung, generiert timeline.json; --whole für eine einzelne vorhandene Aufnahme
tools/kazi_check.py	Misst Trefferquote und verschiedene harte Fehler
tools/caption_check.py	Misst, ob Untertitel erscheinen, verschwinden, sich wortweise aufhellen und mit dem Voice-Over übereinstimmen
tools/mix.py	Mischt Voice-Over, Hintergrundmusik und Soundeffekte; weicht nach Wortzeit aus; normalisiert die Lautstärke
tools/thin_cues.py	Filtert Soundeffekt-Cues nach Priorität, wenn zu viele vorhanden sind
tools/master.sh	Rendert segmentiert ein 4K-Master; unterbrechbar
tools/hdr/	SDR-Master in HDR: Dolby Vision 8.4 (HLG-Basisschicht) und HLG
starter/	Remotion-Vorlage: time.ts für Zeitabfragen, anim.ts für Kurven und Federn, Untertitel-Komponente

Dem Nutzer bei Übergabe mitteilen

• Pfad, Länge und Auflösung des finalen Clips.
• Trefferquote, zufällige Baseline, wie viel besser als der Zufall; welche Schlüsselwörter nicht getroffen wurden und warum.
• Probleme aus der Prüfung und deren Behebung; noch ungelöste Probleme direkt ansprechen.