Video durch Code

Video durch Code Fähigkeit

Ein ausführbares Toolkit und Produktionsworkflow für Mensch-KI-Teams, die deterministische Videos in Code erstellen. Der gesamte Szenencode verbleibt im Repository oder Projektarbeitsbereich; alle generierten Medien, Audioaufnahmen, Standbilder und Verifikationsbelege werden in einem expliziten externen $PROD-Verzeichnis abgelegt.

Arbeitsablauf: Brief → Audio & Timing → Stil & Prompt → 3 Design-Standbilder → Szenencode → Determinismus- & Textbegrenzungs-Gate → Vollrender → Verifikation & Kontaktbogen → Lieferbeleg

---

1. Umgebung & Rauchtest

Stelle vor dem Bau eines neuen Films sicher, dass die Starter-Abhängigkeiten installiert sind und der 4-Sekunden-Rauchtest vom Repository-Root aus bestanden wird:

cd starter && npm ci && cd ..
node tests/runtime-contract.mjs

---

2. Produktionsverzeichnis & Absicht (RUNBOOK.md §1–2)

1. Wähle ein absolutes Produktionsverzeichnis außerhalb des Code-Checkouts:

   PROD="/absolute/path/to/video-outputs/<project-slug>"
   mkdir -p "$PROD"/{audio,analysis,stills,renders,checks}
   

2. Kopiere templates/brief.md nach "$PROD/brief.md" und fülle Zielgruppe, Kernaussage, Seitenverhältnis (1920x1080 Querformat oder 1080x1920 Hochformat), Dauer, Sprach-/Musikquelle und Sicherheitsbereich-Ränder aus.

---

3. Audio-Identität & Timing (docs/04-music-audio-and-timing.md, docs/05-narration-and-captions.md)

Animiere niemals mit geschätzten Zeitstempeln. Messe zuerst die tatsächliche Audiodatei und zeichne ihren SHA-256-Hash auf:

uv run tools/timing/audio-identity.py "$PROD/audio/source.wav" \
  --out "$PROD/analysis/identity.json" --copy-wav "$PROD/analysis/analysis.wav"

• Gesprochene Erzählung:
  • Synthetisiere mit lokalem Kokoro ONNX TTS (mit < 4 Wortfragment-Zusammenführung und --say say.json phonetischem Wörterbuch): uv run tools/timing/kokoro-narrate.py script.txt --out-dir "$PROD/audio" --voice af_heart --say say.json
  • Verifiziere die gesprochene Audio-Rückführung mit lokalem whisper-cli: uv run tools/verify/verify-narration.py "$PROD/audio/narration.wav" "$PROD/audio/timing.json"
  • Überprüfe Skripte/Texte auf wörtliche N-Gramm-Übernahme im Vergleich zum Referenztext: python3 tools/verify/check-lift.py candidate.txt reference.txt
• Musik-/Lyrik-/Stem-reaktive Spuren:
  • Trenne 6 Stems mit Demucs (vocals, drums, bass, guitar, piano, other) und normalisiere auf 44,1 kHz WAV: uv run --python 3.12 tools/timing/separate-stems.py "$PROD/audio/song.mp3" --out-dir "$PROD/analysis"
  • Extrahiere 120 Hz Stem-Hüllkurven, monotone musikalische Zeit tau, Beat/Takt-Phase, Stille, features.f32 und 100 fps Gitarren-Tonhöhe/Vibrato: uv run --python 3.12 tools/timing/analyze-stems.py "$PROD/analysis" --fps 120 --stem-pitch
  • Richte Wort-für-Wort-Text aus (whisper-cli, mlx-whisper, faster-whisper oder acoustic Gesangsband-Energie-Warping): uv run tools/timing/align-words.py "$PROD/analysis/stems/vocals.wav" --script lyrics.txt --backend whisper-cli --out "$PROD/analysis/words.json"
  • Leichte Single-File-Cues / Beat-Grid / Visualizer-Hüllkurve:
    • uv run tools/timing/cue-extract.py "$PROD/audio/song.mp3" --out "$PROD/analysis/cues.json"
    • uv run --python 3.12 tools/timing/beat-grid.py "$PROD/analysis/analysis.wav" --out "$PROD/analysis/beats.json"
    • python3 tools/build-visualizer.py "$PROD/analysis/analysis.wav" --out "$PROD/analysis/features.js"

---

4. Stilauswahl & Prompt-Erstellung (prompts/README.md)

Durchstöbere prompts/styles/INDEX.md (86 verfasste visuelle Stilkarten in 13 Familien) und prompts/briefs/ (5 Format-Briefs: explainer-voiceover, vertical-short, lyric-video, instrumental-visualizer, data-story).

Stelle die kombinierte Spezifikation für den gewählten Stil und das Brief zusammen:

python3 tools/build-prompt.py <style-id> --brief <brief-id> --out "$PROD/style-prompt.md"

---

5. Szenen-Erstellungsvertrag (lib/API.md, docs/06-building-scenes.md, docs/12-advanced-engines-and-benchmarks.md)

Jede Szenen-HTML-Seite lädt lib/harness.js (window.H) und optional:

• lib/sound.js (window.SOUND) — prozedurale Web Audio Synthese
• lib/features.js (window.FEATURES) — 120 Hz binärer features.f32 Stem-Cursor, refraktärer Onset-Puls, monotones tau(t) und words.json Lyrik-Nachschlagewerk
• lib/ink-doodle.js (window.INK) — 8 fps deterministisches Line-Boil, gewackelte Doodle-Primitive, linksbündiges GROSSSCHRIFT-Einblenden marker und Ken Burns plate Kamera
• lib/webgl-post.js (createPost) — 4-stufige Three.js Post-Processing (FxOverShader, UnrealBloomPass, FinalGradeShader mit ACES / paperMode, Luma-only Impact-Inversion, Glitch, Shake, Grain und crisp UI Overlay)

Jede Seite stellt bereit:

• <canvas id="c" width="1920" height="1080"></canvas> (oder 1080 × 1920 für Hochformat)
• window.DURATION (Sekunden) und window.FPS (Standard 30)
• window.__ready (Promise, das nach dem Laden von Schriftarten und gecachten Offscreen-Platten auflöst)
• window.__renderFrame = (t) => { ... } — reine Funktion von t in Sekunden.
  • Starte jeden Frame mit ctx.reset() (oder balanciertem save()/restore()).
  • Verwende H.rng(seed) und H.noise(seed) außerhalb der Frame-Schleife; verändere niemals den veränderlichen Zustand über Frames hinweg.
  • Cache Papier-/Oberflächentexturen einmal mit H.paperTexture(...) oder H.offscreen(key, w, h, fn).
  • Stelle window.__textBounds = () => [...] für geschichtskritischen Text bereit ({text, critical: true, left, right, top, bottom}), damit automatisierte Sicherheitsbereich-Prüfungen jeden Frame verifizieren können.
• window.scoreSound = (k) => { ... } — plant prozedurale Soundereignisse zu festen Timeline-Zeitstempeln (unterdrückt automatisch Hintergrund-/Musik, wenn --voice angegeben wird).

Wichtige Produktionsregeln aus Tests

• Sicherheitsbereich-Ränder & Schriftstärken: Auf macOS Chrome bietet Arial nur die Stärken 400 und 700 (600 wird auf 700 Bold gesetzt und verbreitert Zeilen um ~9 %). Überprüfe immer measureText(s).actualBoundingBox* über alle Frames (x: 80..960, y: 190..1640 für 1080x1920 vertikale Kurzfilme).
• Durchgehende Kamerastile (transit-map, pan-and-zoom): Starte die Kamera-Interpolation bei beat[i].start (niemals beat[i].start - preRoll, wenn i bei beat[i].start wechselt, was einen 1-Frame-Sprung verursacht), blende Beat-lokale Overlays über 0,20 s ein und schütze Weltraum-Beschriftungen, sodass sie nur gezeichnet werden, wenn sie sich innerhalb des beschnittenen Karten-Viewports befinden.

---

6. Render-Standbilder, Determinismusprüfung & Master-Render (docs/07-rendering.md)

1. Determinismus beim Springen Gate:

   node starter/determinism.mjs path/to/film.html
   

2. Design-Standbilder Gate (überprüfe Eröffnungs-, mittlere dichte und Endframes vor dem Vollrender):

   node starter/render.mjs path/to/film.html --stills 1.5,12.0,24.0 --outdir "$PROD/stills"
   

3. Voll-MP4-Render:
   • Referenz-Single-Worker Playwright Renderer (Standard 30 fps Canvas2D + prozedurales Audio):

     node starter/render.mjs path/to/film.html \
       --out "$PROD/renders/master.mp4" --fps 30 --audio page \
       --voice "$PROD/audio/narration.wav"
     

   • Multi-Worker GPU WebSocket Renderer (60 fps Three.js / WebGL / kinetische Typografie):

     node tools/render/parallel-ws-render.mjs \
       --url "http://127.0.0.1:5173/?capture=1" --duration <DURATION> --fps 60 --workers 4 \
       --audio "$PROD/analysis/analysis.wav" --out "$PROD/renders/master.mp4"
     

   • Browserloser Python + Pillow rawvideo Renderer (Untertitel-Arbeitsmappen & Tutorials):

     uv run tools/render/workbook-render.py \
       --spec workbook.json --audio "$PROD/audio/narration.wav" --out-dir "$PROD/renders"
     

---

7. Obligatorische Verifikations-Gates (docs/08-verification.md)

Jede Produktion muss diese Prüfungen ausführen und die Ergebnisse in "$PROD/checks/" aufzeichnen, bevor sie übergeben wird:

1. Stream-, Decode-, Sync- & Loudness-Gate:

   uv run tools/verify/verify-video.py "$PROD/renders/master.mp4" \
     --expect-seconds <DURATION> --fps 30 --width <W> --height <H> \
     --json "$PROD/checks/verify-video.json"
   

2. Kontaktbogen visuelle Inspektion:

   uv run tools/verify/contact-sheet.py "$PROD/renders/master.mp4" \
     "$PROD/checks/contact-sheet.jpg" --n 16 --cols 4 --tile-width 270
   

   Überprüfe contact-sheet.jpg und die Szenen-Standbilder visuell auf Textabschneidungen, Beschriftungskollisionen oder unbeabsichtigte leere/eingefrorene Frames.
3. Übergangs- & Schnitthärte-Audit:

   uv run tools/verify/cut-harshness.py "$PROD/renders/master.mp4" \
     --top 15 --json "$PROD/checks/cut-harshness.json"
   

4. Look- & Palette-Diagnostik:

   uv run tools/verify/measure-look.py "$PROD/renders/master.mp4" \
     --samples 16 --json "$PROD/checks/measure-look.json"
   

5. All-Frame-Textbegrenzungs-Audit: Folge dem Muster in tests/layout.mjs, um fillText Tintengrenzen und window.__textBounds() über jeden Frame 0 .. frames-1 zu verifizieren.

---

8. Verpackung & Lieferung (RUNBOOK.md §12)

Vervollständige "$PROD/qa.md" (aus templates/qa.md) und "$PROD/delivery.md" (aus templates/delivery.md). Melde Maschinenverifikation (PASS/WARN-Status) getrennt von der menschlichen kreativen Betrachtung und Hörfreigabe.

Wichtige Referenzen

• README.md — Schnellstart und Kapitelübersicht
• RUNBOOK.md — 12-Schritte-Mensch-KI-Produktionscheckliste
• lib/API.md — Exakter H Grafik- und SOUND prozeduraler Audiovertrag
• examples/README.md — Ausgearbeitete Querformat-, Hochformat- und Stilstudienbeispiele
• docs/10-pitfalls.md — Symptom → Ursache → Reparaturtabelle