igm61799-cloud/voiceover-to-animation

Voiceover → codierter 2D-Animations-Kurzfilm

Du drehst einen Kurzfilm, keine Diashow. Die Erzählung ist fix; deine Aufgabe ist es, zu erfinden, was der Zuschauer in jedem Moment sieht, es in Code zu zeichnen und ein MP4 zu liefern, dessen Schnitte und visuelle Akzente exakt auf den richtigen Worten landen.

Die gesamte Pipeline ist deterministisch: Jede Szene ist eine reine Funktion der Zeit, sodass jeder Frame für sich gerendert werden kann. Diese eine Eigenschaft liefert dir alles andere – sofortige Standbilder zur Überprüfung, paralleles Rendering, perfekte Audiosynchronisation.

Was auf dem Rechner benötigt wird

Überprüfe diese Dinge vor Beginn; es sind die einzigen beweglichen Teile.

python -c "import faster_whisper, playwright, PIL; print('ok')"
ffmpeg -version

Fehlende Komponenten: pip install faster-whisper playwright pillow, dann python -m playwright install chromium. ffmpeg muss sich im PATH befinden. Wenn etwas nicht installiert werden kann, teile dem Benutzer mit, was fehlt, anstatt auf einen schwächeren Ansatz auszuweichen.

Der Workflow

Halte die Sicht des Benutzers einfach: Er hat Audio übergeben und möchte einen Film. Arbeite diese Schritte der Reihe nach ab und behalte eine sichtbare Aufgabenliste.

1. Zuerst zuhören: Wortzeitabstimmungen

python <skill>/scripts/transcribe.py voiceover.mp3 work

Es gibt Sätze mit Start-/Endzeiten und jedes Wort als word@start aus und speichert work/words.json. Alles Weitere wird auf der Grundlage dieser Zahlen geplant. Beachte die Gesamtdauer.

2. Projekt neben der Audiodatei einrichten

Kopiere <skill>/assets/template/ in den Arbeitsordner, sodass es so aussieht:

voiceover.mp3
render.py
src/index.html  src/engine.js  src/scenes.js  src/main.js

Lies src/engine.js einmal durch (es ist kurz) und überfliege references/engine-api.md, damit du weißt, was du bereits hast: Easing, gesetzter Zufall, eine Kamera, teilweises Zeichnen von Pfaden und druckgrafische Motive (Wolken, Regen, Blitze, Rauch, Skyline).

3. Kunstrichtung festlegen, dann Storyboard gegen die Worte

Wähle EINE visuelle Sprache und halte sie für den gesamten Film durch: eine kleine Palette (fünf oder sechs Farben), eine Behandlung für Kanten und Textur, eine Art, Menschen zu zeichnen. Die Vorlage liefert einen Linolschnitt-/Drucklook (Knochenpapier, marineblaue Tinte, Zinnoberrot, Gold, wackelige handgeschnittene Kanten). Verwende ihn oder gestalte ihn um, indem du die Palette in scenes.js und die POST-Schalter änderst – aber mische keine Stile zwischen den Szenen. Abwechslung entsteht dadurch, welche Farbe in jeder Szene dominiert (eine Nachtszene, eine Papierszene, eine Rotszene), nicht durch eine Änderung der Regeln.

Schreibe dann das Storyboard, bevor du Code schreibst: eine Tabelle mit Einstellungen mit absoluten Start-/Endzeiten, den Worten, die jede Einstellung abdeckt, was auf dem Bildschirm zu sehen ist, und dem genauen Wort, auf das jeder Schlag fällt. Lies references/storyboarding.md, um zu erfahren, wie man Erzählungen in Bilder umwandelt – das ist der Teil, der entscheidet, ob der Film gut wird.

Die Kurzversion:

• Eine Idee pro Phrase. Ein Satz mit drei Klauseln besteht normalerweise aus drei Einstellungen oder drei Schlägen innerhalb einer Einstellung.
• Zeige die Sache, beschrifte sie nicht. Bildschirmtext, der die Erzählung wiederholt, bringt den Zuschauer dazu, zu lesen statt zu schauen. Standardmäßig kein Text; Namen, echte Daten und eine kurze neutrale Beschriftung auf einem Diagramm sind die Ausnahmen. Wenn der Benutzer Textpräferenzen angegeben hat, haben diese Vorrang.
• Gib dem Film eine Grundstruktur: ein wiederkehrendes Motiv oder eine Figur und einen Rückruf am Ende auf etwas vom Anfang.
• Ändere den Maßstab und die Kameraposition gezielt: Totale, Nahaufnahme, Diagramm, Karte, Querschnitt. Zwei aufeinanderfolgende Einstellungen sollten nicht die gleiche Komposition haben.
• Wenn die Erzählung mit einer Pointe endet, füge 1-2 s stille Nachlaufzeit nach dem letzten Wort hinzu, damit das finale Bild wirken kann. render.py füllt das Audio auf.

4. Eine Szene komplett aufbauen, bevor der Rest geschrieben wird

Schreibe die erste Einstellung in src/scenes.js, registriere sie in SHOTS und betrachte sie:

python render.py stills 0.3,1.5,2.9 first

Öffne dann work/first.png mit dem Lese-Werkzeug. Tue dies, bevor du die anderen Szenen codierst: Es beweist die Pipeline und, noch wichtiger, es lässt dich den Stil beurteilen, während eine Änderung noch günstig ist.

5. Schreibe die restlichen Szenen, ein paar auf einmal

Regeln, die das System funktionieren lassen (jede existiert, weil ein Verstoß einen bestimmten Fehler verursacht):

• Reine Funktionen der Zeit. Eine Einstellung ist function name(g, t, u), wobei t absolute Sekunden und u Sekunden seit Beginn der Einstellung sind. Keine Variablen, die sich zwischen den Frames ansammeln, kein Math.random(), kein Date. Verwende hash(n), noise1(x), rng(seed). Frames werden von mehreren Browsern gleichzeitig in nicht sequenzieller Reihenfolge gerendert; alles, was Zustand speichert, zeigt sich als Flackern oder als nicht übereinstimmende Blöcke.
• Animiere mit absoluten Zeiten. Schreibe E.out(seg(t, 12.62, 13.1)) und verwende Zahlen direkt aus der Wortliste. Wenn der Schnitt sich ändert, bleiben die Schläge auf ihren Worten.
• Alles bewegt sich ein wenig. Ein gehaltener Frame wird als Fehler interpretiert. Gib jeder Einstellung eine langsame Kameradrift (ein 1 + u * .01 Zoom reicht) und etwas sekundäre Bewegung (Regen, Rauch, ein schwingendes Objekt).
• Alles mit Easing. E.out für ankommende Dinge, E.inOut für Kamerafahrten, E.back für Popp-Effekte, E.bounce für Landungen. Lineare Bewegung wirkt mechanisch.
• Zeichne die Welt größer als den Bildausschnitt, wenn die Kamera herauszoomt oder wackelt; fülle Hintergründe und Boden weit über 0..1920 hinaus, sodass nie eine Kante sichtbar wird.
• Einschläge bekommen drei Dinge: einen 2-3 Frame Flash über den ganzen Bildschirm, ein abklingendes Shake und etwas, das reagiert (eine Wolke, ein Rückstoß, ein Farbwechsel).
• Teile Szenencode auf Dateien auf (s1.js, s2.js, ...), sobald eine Datei ein paar hundert Zeilen überschreitet, und füge sie in index.html vor scenes.js ein.

Schreibe zwei oder drei Einstellungen, rendere ein Kontaktblatt, schau nach, korrigiere, fahre fort. Schreibe nicht den gesamten Film blind.

6. Überprüfung mit Standbildern – das sind deine Augen

Du kannst das Video nicht abspielen, daher ist das Kontaktblatt die Überprüfung. Für jede Einstellung nimm mindestens den Start, die Mitte der Hauptaktion und das Ende sowie den genauen Frame jedes Schlags:

python render.py stills 12.2,13.3,14.3,15.4,16.5 act2     # bis zu ~16 Zeitstempel pro Blatt
python render.py sheet 4                                   # gesamter Film, ein Frame alle 4 s

Lies das PNG und überprüfe Einstellung für Einstellung: Ist das Subjekt groß genug, um es auf einen Blick zu erkennen? Ist etwas abgeschnitten, überlappend oder schwebend? Hat das Wichtige Kontrast zu dem, was dahinter ist? Sieht es gestaltet aus, oder ist die Hälfte des Bildschirms leer? Dann korrigiere und rendere die gleichen Zeitstempel erneut. references/pitfalls.md listet die Fehler auf, die leicht zu machen und schwer zu bemerken sind.

Seitenfehler werden von render.py als PAGE ERROR: ausgegeben – ein schwarzer oder halb gezeichneter Frame weist normalerweise auf eine Ausnahme in dieser Einstellung hin.

7. Rendern und überprüfen

python render.py full --workers 8

Führe es im Hintergrund aus; ein 70 s Film hat etwa 2.100 Frames und dauert ein paar Minuten. Es schreibt output.mp4 (1920x1080, H.264 + AAC, Audio auf die volle Länge aufgefüllt). Überprüfe dann die Datei selbst, nicht nur die Standbilder:

ffprobe -v error -show_entries format=duration:stream=codec_name,width,height -of default=nw=1 output.mp4
python render.py sheet 6

Bestätige die Dauer, dass es einen Audiostream gibt und dass das Übersichtsblatt keine leeren Frames enthält. Sage in deinem Bericht deutlich, dass du Standbilder und Dateieigenschaften überprüft hast, aber das Video nicht in Bewegung gesehen hast – der Benutzer sollte es sich einmal ansehen.

8. Übergabe

Gib dem Benutzer den Pfad zu output.mp4, das Übersichtsblatt und einen Satz, wie nach Änderungen neu gerendert wird. src/index.html, in einem Browser geöffnet, ist ein Live-Player mit dem Audio, was die schnellste Möglichkeit für den Benutzer ist, das Timing zu überprüfen.

Ton

Liefere nur das Voiceover aus, es sei denn, der Benutzer hat nach Musik oder Soundeffekten gefragt. Falls doch, füge sie als zusätzliche ffmpeg-Eingaben im finalen Mux hinzu, zeitlich abgestimmt auf dieselbe Schlagliste, die du für die Bilder verwendet hast.

Referenzdateien

• references/storyboarding.md – Erzählung in Einstellungen umwandeln; Schlagpositionierung; visuelle Metaphern; was eine Szene gestaltet wirken lässt. Vor Schritt 3 lesen.
• references/engine-api.md – jeder Helfer in engine.js mit einer einzeiligen Verwendung. Vor Schritt 5 lesen.
• references/pitfalls.md – auf die harte Tour gefundene Fehlermodi mit Korrekturen. Vor Schritt 6 lesen.
• references/example-bells/ – ein vollständiger 71-Sekunden-Film (16 Einstellungen, ~900 Zeilen Szenencode) mit seinem Storyboard. Lese storyboard.md, um das erwartete Planungsniveau zu sehen; öffne die src/s*.js-Dateien, wenn du sehen möchtest, wie ein bestimmter Effekt aufgebaut wurde (eine Kamera, die einer kletternden Figur folgt, eine Explosion, eine Karte, eine Schreibfeder, die eine Linie zeichnet, ein sich verengendes Auge).