alecs5am/ralphy

Editor-Playbook

Lies dies, wenn: „Video komponieren“, „Rendern durchführen“, „Rendern“, „Vorschau“, „Untertitel korrigieren“, „Audiomischung“, „Endschnitt“, „Übergänge straffen“.

Composer + Renderer. Ich nehme scenario.json + asset-manifest.json, erstelle eine HTML-Komposition mit GSAP und rendere ein MP4 über HyperFrames. Ich generiere keine Medien – das macht der Art Director. Ich füge zusammen, timing, übergänge, untertitel, mische, sanity-check.

STOP-Regel. Nur via ralphy render rendern. FFmpeg nur via ralphy audio / ralphy video. Kein direktes bunx hyperframes render außerhalb des Debuggings, keine ad-hoc ffmpeg-Shells – jedes Rezept ist ein Verb, das automatisch loggt. AGENTS-Invariante #2.

Engine

HyperFrames ist die einzige Render-Engine. Jedes Projekt muss .ralphy/workspaces/<ws>/projects/<id>/index.html ausliefern. Siehe hyperframes für Kompositionsregeln, GSAP-Timelines, Registry-Blöcke, Untertitel, Übergänge, Audiomischung.

CLI-Kochbuch

Nur via ralphy render rendern. FFmpeg nur via ralphy audio / ralphy video. Niemals bunx hyperframes render direkt außerhalb des Debuggings aufrufen und niemals ad-hoc ffmpeg shellen – jedes Rezept unten ist ein Verb, das automatisch loggt.

# Finaler Render
ralphy render <project-id> [--loudnorm]
ralphy render <project-id> --fps 60 --quality high

# Untertitel
ralphy generate captions --project <id> --audio <vo.mp3>     # → captions.json (Caption[])
# HyperFrames liefert auch einen integrierten Wort-für-Wort-Transkriber:
bunx hyperframes transcribe --in <vo.wav> -o captions.json

# Audio-Rezepte – wrappen cli/lib/ffmpeg-recipes.ts
ralphy audio loudnorm  --in <vo.mp3>  --out <vo-norm.mp3>           # -16 LUFS für TikTok / Reels
ralphy audio sidechain --voice <vo>   --music <m> --out <mix.mp3>   # Musik unter VO ducken
ralphy audio concat    --files a.mp3,b.mp3,c.mp3 --out concat.mp3   # verlustfreies Zusammenfügen

# Video-Rezepte
ralphy video extract-segment --in <src.mp4> --start 1.2 --end 4.5 --out <seg.mp4>
ralphy video burn-subs       --in <src.mp4> --srt <subs.srt> --out <final.mp4>   # letzter Schritt
ralphy video tonemap-hdr     --in <hdr.mp4> --out <sdr.mp4>                       # HDR → Rec.709
ralphy video concat          --files a.mp4,b.mp4 --out concat.mp4

# HyperFrames-Iterationsschleife (nur im Vordergrund – kein automatisches Studio)
bunx hyperframes preview .ralphy/workspaces/<ws>/projects/<id>
bunx hyperframes lint    .ralphy/workspaces/<ws>/projects/<id>
bunx hyperframes inspect .ralphy/workspaces/<ws>/projects/<id>
bunx hyperframes add <block-slug> .ralphy/workspaces/<ws>/projects/<id>

# Eingaben/Ausgaben inspizieren
ralphy project show <id> --assets        # asset-manifest vor dem Komponieren
ralphy project show <id> --status        # was erledigt / fehlt
ralphy project log <id> --type generations --limit 50    # ffmpeg + Render-Einträge

Für HyperFrames-API-Details (Kompositionsregeln, GSAP-Timelines, Untertitel, Übergänge, Registry-Blöcke) lies hyperframes – das ist das Referenzhandbuch, nicht dieses Playbook.

Erweitern eines stilisierten Clips (i2v-Letztbild-Anker + volle 15s-Blöcke)

Wenn der Benutzer darum bittet, einen vorhandenen stilisierten Clip (Toon, Malerisch, Spider-Verse / Arcane-Stil) zu „erweitern“ / verlängern, erstelle keinen frischen, nicht verbundenen Clip – verankere einen neuen i2v-Clip am letzten Frame des vorhandenen, damit die Verbindung nahtlos ist:

1. Extrahiere den letzten Frame: ralphy video extract-segment (oder ein ffmpeg -sseof-Tail-Frame-Grab via eines ralphy video-Rezepts) der letzten ~0,15s → ein PNG.
2. Gib dieses PNG als --first-frame eines neuen ralphy generate video-i2v-Aufrufs auf bytedance/seedance-2.0 an. Der neue Clip startet auf dem echten letzten Frame, sodass der Schnitt unsichtbar ist. (Stilisierte/malerische Anker lösen Seedances fotorealistischen Personenfilter nicht aus – dieser Filter feuert nur auf fotorealistische menschliche Gesichter, siehe feedback_seedance_rejects_realistic_people.)
3. Standardmäßig die Erweiterung auf einen vollen 15s-Block, nicht 5s. Kurze Erweiterungen wirken gehetzt und verlieren an Dynamik; ein 15s-Block bietet Raum für einen echten Beat (z. B. Solo → Kamerafahrt, die die Menge enthüllt → Finale) und der stilisierte Stil kommt bei actionreichen langen Blöcken stärker zur Geltung als bei statischen Weitwinkelaufnahmen. Betone eine bewegte Kamera (Orbit / Kran) für Dynamik. Behalte die SUBJECT / STYLE / AUDIO-POLICY-Prompt-Blöcke wörtlich über die Blöcke hinweg bei.
4. ralphy video concat die Blöcke, generiere einen Musikteppich neu, der auf die GESAMTE neue Länge zugeschnitten ist, wobei der Höhepunkt auf das Finale ausgerichtet ist, dann ralphy audio sidechain (Musik unter VO ducken) und kopiere nach render/final.mp4.

Gilt NICHT für: fotorealistische menschliche Clips (Seedance lehnt den Anker ab – stattdessen via kwaivgi/kling-v3.0-pro erweitern); langsame statische / dialoggetriebene Beats, bei denen eine 5s-Erweiterung die richtige Länge ist; Fälle, in denen der neue Beat ein harter Szenenwechsel und keine Fortsetzung ist (dann ist es eine neue Szene, keine Erweiterung, und der Letztbild-Anker ist unnötig).

Unterdokumente (bei Bedarf lesen)

Datei	Wann lesen
editor/render-pipeline.md	Preflight, Kompositionserstellung, Vorschau, Final-Render
editor/vo-sync.md	Auf VO abgestimmte Schnitte – stitch → scribe → slice; reverse-areverse + concat demuxer (AGENTS-Invariante #16)
editor/captions.md	Einbinden von captions.json in eine Untertitelkomponente; Untertitel zuerst, bevor Timing-Konstanten geschrieben werden
editor/transitions.md	Crossfade / Push / Wipe-Muster
editor/audio-mixing.md	VO + Musik + SFX-Pegel, Ducking, Blenden
editor/green-zone.md	Platzierung von Text/Overlays innerhalb der 1080×1920-Sicherheitszone
editor/hard-rules.md	12-Punkte-ffmpeg-/Schnittdisziplin-Checkliste für Finale

Unteraufgaben

Unteraufgabe	Wann	Unterdokumente
preflight	„Bereit zum Rendern?“	render-pipeline
generate-captions	VO fertig, kein captions.json	captions + vo-sync (für auf VO abgestimmte Schnitte)
author-composition	Manifest vollständig, Komposition fehlt	render-pipeline + transitions + hyperframes
preview	„Im Browser ansehen“	render-pipeline + bunx hyperframes preview
final-render	Komposition genehmigt	render-pipeline + hard-rules

Was ich beim Start lese

1. Führe zuerst ralphy editor preflight <id> aus. Einzelner kanonischer Check für Dauern, fps, Codec, Audiospuren, Musiklücke vs. Gesamtcliplänge und Vollständigkeit von Szenario zu Platte. Beendet mit Exit 1 bei Rot – vor dem Komponieren beheben. Ersetzt die ad-hoc ffprobe-Schleife jedes Projekts. (#034)
2. Dann ralphy editor trim-analyze <id>. Batch-Gemini-3.1-Pro-Preview-Visionsdurchlauf über artifacts/videos/ auf Leerlaufzeiten / Höhepunkte / vorgeschlagene trim_in_s / trim_out_s pro Clip. Aggregiert zu artifacts/analysis/summary.json (idempotent via mtime – wiederholte Ausführungen analysieren nur geänderte Clips neu). Verwende --dry-run, um den Plan + Cache-Status zu sehen. Kanonischer Löser für kling/seedance ~1s Überschwingen (#042). (#034)
3. AGENTS.md – Invarianten (kein Auto-Studio, keine Skripte, ralphy render).
4. HyperFrames-Playbook – Referenzhandbuch für HyperFrames-Komposition / Untertitel / Übergänge / GSAP / Registry.
5. Art-Director/Pre-Render-Checkliste – HARTES Snapshot-Review-Gate, das der Art Director vor der Übergabe räumen muss. Wenn du ohne Snapshots auf der Platte hier angekommen bist, springe zurück zum Art Director.
6. .ralphy/workspaces/<ws>/projects/<id>/scenario.json – Struktur und Timings.
7. .ralphy/workspaces/<ws>/projects/<id>/asset-manifest.json – Asset-Pfade.

• .ralphy/workspaces/<ws>/projects/<id>/index.html – die Komposition.
• .ralphy/workspaces/<ws>/projects/<id>/design.md – Brand-Source-of-Truth (HyperFrames-Skill-Gate).
• docs/green-zone.md für Textpositionierung.

Harte Regeln (von AGENTS.md geerbt)

1. ralphy render <id> – der einzige Render-Pfad. Rufe bunx hyperframes render nicht direkt auf (außer zum Debugging).
2. Keine automatisch gestartete Vorschau / Studio. Führe hyperframes preview nicht im Hintergrund aus. Wenn der Benutzer eine Vorschau möchte, sage ihm deutlich, er solle sie im Vordergrund ausführen.
3. Untertitel via ralphy generate captions (Whisper-1 OpenRouter) oder bunx hyperframes transcribe für Wort-für-Wort-Zeitstempel. Führe es AUS, BEVOR du HF-/Remotion-Timing-Konstanten schreibst, wenn die Komposition Untertitel-Overlays hat (AGENTS-Invariante #16). Für auf VO abgestimmte Schnitte insgesamt: zuerst scribe via editor/vo-sync.md. Siehe editor/captions.md.
4. Qualitätsgate vor dem Final-Render – jeder Slot im Manifest muss score >= 7 oder explizite Bypass-Zustimmung haben.
5. FFmpeg-Nachbearbeitung – nur via cli/lib/ffmpeg-recipes.ts. Siehe editor/hard-rules.md (12 Punkte).
6. Bewegungsgrafiken → Kompositionscode, niemals Videomodelle (04.0A.02). Siehe den Entscheidungsbaum unten – animierter Text, kinetische Typografie, Lower Thirds, animierte Diagramme, animierte UI-Mocks, Übergangswipes werden alle als HyperFrames HTML + GSAP komponiert. Sie werden NICHT via ralphy generate video generiert; dieser Pfad ist für Realfilm / Illustration / fotorealistische Szenen reserviert – Pixelinhalt, den das Modell produziert, kein code-komponierte Bewegung.
7. MUSS jede Benutzerfeedback-Runde zum Render loggen via ralphy project log-prompt <id> --text "<wörtlich>" --stage <feedback|approval|critique|rejection> – Rückmeldung zu einem Schnitt, Untertitelkorrektur, Audio-Neumischung, „Kann los“-Genehmigung, Render-killende Kritik. Dieselbe MUSS-loggen-Disziplin wie das Szenarist-Playbook (siehe scenarist.md → „Benutzer-Prompt-Protokollierung“). Spärliche Logs lassen die Postmortem-Schicht raten, welche Renderversion der Benutzer tatsächlich genehmigt hat.
8. Kling + Seedance überschwingen --duration um ~1s. Jeder Clip von kwaivgi/kling-v3.0-pro und bytedance/seedance-2.0 landet ~1s länger als die angeforderte Dauer (tokyo-y2k-001 maß 5s/4s/9s → 6.04/5.04/10.04). Vor dem Komponieren eines Multi-Clip-Schnitts entweder (a) --duration 1s kürzer auf Art-Director-Ebene anfordern oder (b) einen pro-Clip-Vision-Trimm-Durchlauf einplanen. Vollständiges Rezept + Zahlen in editor/render-pipeline.md → Quellclip-Dauer-Überschwingen. Strukturelle Lösung lebt im zukünftigen ralphy editor trim-analyze-Verb (Issue 034).

Pixel vs. Code – der Bewegungsgrafik-Entscheidungsbaum (04.0A.02)

Bevor du eine Szene an ralphy generate video weiterleitest, klassifiziere die Ausgabe:

Muster	Route	Warum
Realfilm-Szene (Person, Raum, Aktion, Wetter, Gameplay-Aufnahme)	ralphy generate video (i2v / t2v)	Modell produziert Pixel, die Code nicht vortäuschen kann
Fotorealistisches Standbild + Parallaxe	ralphy generate image + HyperFrames GSAP-Tween	Bild ist das Asset; Bewegung ist die Komposition
Animierter Text / kinetische Typografie / „WORDS SLAM IN“	HyperFrames-Komponente + GSAP-Timeline	Code steuert Timing und genaue Schreibweise; Videomodell verwischt Buchstaben und verschiebt Schriftarten
Lower Third / Namenskarte / Chyron	HyperFrames HTML + GSAP	Trivial parametrisierbar; Pixel-Route würde Schriftarten bei jeder Generation neu rendern
Animiertes Diagramm / Datenvis	HyperFrames HTML + GSAP / Three.js	Code ist die Quelle der Wahrheit für die Daten; Pixel-Route würde Werte halluzinieren
Animierter UI-Mockup / App-Bildschirm	HyperFrames HTML + GSAP	Pixel-Route erfindet UI-Features; das Ergebnis liest sich wie KI-Schrott
Übergang zwischen zwei Clips	HyperFrames-Shader/Crossfade-Registry-Block	Die beiden Clips sind die Assets; der Übergang ist ein Code-Rezept
Partikel-/FX-Overlay	HyperFrames CSS/SVG/Canvas/WebGPU	Wiederholbar; Pixel-Route ist nicht deterministisch
Lottie-Animation einfügen	HyperFrames lottie-Adapter	Lottie-Datei ist das Asset; Laufzeit spielt sie deterministisch ab

Versteckte Hinweise (der Lint bei bun run lint:templates markiert bekannte Übeltäter in prompts.json): „animierter Text“, „kinetische Typografie“, „Lower Third animiert herein“, „Diagramm animiert herein“, „Logo gleitet herein“, „Übergangswipe“ → diese gehen auf die HTML+GSAP-Seite, nicht zum Videomodell. Wenn du dabei ertappst, einen dieser Ausdrücke als --prompt an ralphy generate video zu schreiben, stoppe und komponiere stattdessen die Komponente.

Cross-Link: lies hyperframes für die API-Details.

Historische Anmerkung (Remotion). Wenn du in einem Pre-92ef823-Branch oder einer Postmortem-Analyse stöberst, die STATIC_ROOT / composition-props.json erwähnt, ist die Legacy-Remotion-Konvention unter editor/render-pipeline.md → Legacy: Remotion STATIC_ROOT-Rezept dokumentiert. Nicht relevant für aktuelle HyperFrames-Arbeit.

Übergabe

• preflight hat fehlende Assets gefunden → Art-Director-Playbook zum Neugenerieren.
• Timings abgedriftet (VO ≠ scenario.duration) → Szenarist-Playbook zum Neutiming der Szenen.
• Nach final-render, wenn es Teil eines Batches ist → Produzent-Playbook.
• Neues HyperFrames-Muster → HyperFrames-Playbook + relevantes Skill-Body (gsap, lottie, animejs, …) vor dem Schreiben von Code.
• Eine Szene schlägt zweimal auf derselben Achse während des Neukomponierens/Neugenerierens fehl – siehe Art-Director-Playbook → Statt Neugenerierung Szene aufteilen. Stoppe das erneute Auffordern; teile in Mikroaufnahmen innerhalb desselben Slot-Budgets auf.