Sachin-pro-dev/PITCHFRAME-push-to-prod

Code-Generierung und Rendern

Du verwandelst eine Kurzbeschreibung in plan.json und renderst sie. Das Referenzprojekt implementiert bereits die Launch-Video-Grammatik – du übergibst ihm Daten, schreibst kein Video von Grund auf neu.

Das Qualitätsniveau des Referenzprojekts ist das Qualitätsniveau jedes Videos, das dieses Tool jemals produzieren wird. Daher ist die starke Vorgabe: schreibe plan.json, ändere nichts anderes. Jede Zeile maßgeschneiderter Animation, die du einem Durchlauf hinzufügst, ist Qualität, die nie das nächste Video erreicht, und eine neue Möglichkeit, dass der Render fehlschlägt.

Der Dateibaum

pitchframe/
├── plan.json               ← der Szenenplan. Das ist das Video.
├── palette.json            ← extrahierte Farben. Daten, niemals Prosa.
├── public/assets/*.png     ← aufgenommene Screenshots.
├── scripts/
│   ├── extract-palette.mjs ← tailwind → CSS-Vars → Live-URL
│   ├── apply-palette.mjs   ← schreibt src/theme.ts aus palette.json
│   └── capture.mjs         ← Dev-Server + Playwright-Aufnahme
├── src/
│   ├── Root.tsx            ← registriert die LaunchVideo-Komposition
│   ├── LaunchVideo.tsx     ← ordnet Beats Sequences zu. Besitzt den Cross-Dissolve.
│   ├── theme.ts            ← GENERIERT. Jede Farbe wird hier aufgelöst.
│   ├── lib/
│   │   ├── types.ts        ← der Plan-Vertrag
│   │   └── motion.ts       ← Easing, Überblendungen, Klick-Puls, gehaltenes Driften
│   ├── components/         ← Hintergrund, Cursor, FocusOverlay, Zoom, Panel, …
│   └── scenes/
│       ├── TypographyBeat.tsx
│       ├── InteractionBeat.tsx   ← der Heldenmoment
│       ├── UIBeat.tsx
│       └── CTABeat.tsx
└── output.mp4

Den Plan schreiben

Lade pitchframe-launch-video für die Struktur und das Schema. Die Kurzversion:

• Vier Teile – Setup, Held, Auszahlung, CTA. In dieser Reihenfolge. Immer.
• Genau ein interaction-Beat, und er bekommt mindestens 30 % der Frames.
• Die Dauer stammt aus dem thesis_weight der Kurzbeschreibung, nicht aus einem Standardwert.
• Kopiere video_thesis und hero_moment in den Plan, damit der Kritikdurchlauf das Video mit der Behauptung abgleichen kann.

Berechne die Arithmetik vor dem Rendern

Ein fehlgeschlagener Render kostet zwei Minuten; ein Plan, dessen Beats driften, kostet einen erneuten Render plus die Zeit, es zu bemerken. Überprüfe von Hand, jedes Mal:

• Beate sind zusammenhängend – jeder frames[0] entspricht dem vorherigen frames[1].
• Erster Beat beginnt bei 0; letzter Beat endet genau bei total_frames.
• total_frames === duration_seconds * fps.
• Kein Typografie-Beat unter 45 Frames.
• Interaktions-Beat ≥ 30 % von total_frames.

Überlege Koordinaten, rate nicht

target_element.coordinates und zoom_target sind Prozente des Screenshots. Sie sind Behauptungen darüber, wo die interessanten Pixel sind, und ein Brennpunkt, der 10 % daneben liegt, zentriert die Heldenaufnahme auf leeres Chrome.

Öffne den Screenshot, finde das Element, rechne in Prozente um und prüfe das Ergebnis gegen das, was der Beat zeigen soll. Wenn die Konsequenz einer Aktion woanders als am Ziel auftritt – das Ziel eines Drags, ein Feld, das sich woanders aktualisiert – richte zoom_target auf die Konsequenz, nicht auf das, was der Cursor berührt hat.

Farben: niemals im Plan, niemals in einer Komponente

theme.ts wird von apply-palette.mjs aus palette.json generiert. Es ist der einzige Ort, an dem eine Farbe festgehalten wird.

node pitchframe/scripts/extract-palette.mjs      # → palette.json
node pitchframe/scripts/apply-palette.mjs        # → src/theme.ts

Regeln, die daraus folgen:

• Setze niemals eine Farbe in plan.json. Der Plan sagt, welches Wort akzentuiert wird; das Theme sagt, was der Akzent ist.
• Setze niemals ein Farb-Literal in eine Komponente. Wenn du einen Farbton brauchst, den das Theme nicht bereitstellt, füge einen abgeleiteten Token zum Generator hinzu, damit jedes zukünftige Video ihn ebenfalls erhält.
• Bearbeite theme.ts niemals von Hand. Es wird beim nächsten Generieren überschrieben.

Wenn die Videos zweier Produkte gleich gefärbt aussehen, wurde theme.ts nicht neu generiert. Das ist das Erste, was zu überprüfen ist, bevor du irgendetwas anderes anfasst.

Der Render

cd pitchframe && npx remotion render LaunchVideo output.mp4

Drei Prüfungen zuvor, die eine Sekunde kosten und einen zwei Minuten langen fehlgeschlagenen Render ersparen:

1. plan.json wird geparst; die obige Arithmetik stimmt.
2. Jeder im Plan benannte Screenshot existiert in public/assets/. Ein Interaktions-Beat benötigt sowohl before_screenshot als auch after_screenshot.
3. node_modules existiert in pitchframe/. Wenn nicht, führe dort zuerst npm install aus.

Erwarte 20–60 Sekunden für ein 20-Sekunden-Video.

Wenn der Render fehlschlägt

Lies den tatsächlichen Fehler, bevor du etwas änderst.

Symptom	Ursache	Lösung
Cannot find module '../plan.json'	Gerüst unvollständig	Führe erneut npx pitchframe install aus
Cannot find name 'ACCENT' etc.	theme.ts nicht generiert	Führe apply-palette.mjs aus
Timeout beim Verzögern des Render wegen Schriftarten	Offline oder eine Schriftart nicht auf Google Fonts	Setze fonts.sans auf Inter in palette.json und generiere neu
Bilddecodierungsfehler	Beschädigter oder unvollständiger Screenshot	Nimm diesen Screenshot erneut auf
Abweichung der Kompositionsdauer	total_frames stimmt nicht mit den Beats überein	Korrigiere die Arithmetik
OOM / Chrome-Absturz	Riesige Screenshots	Verkleinere alles über ~4000px Breite; --concurrency=2

Reagiere nie auf einen Render-Fehler, indem du die Komposition umschreibst. Korrigiere die Daten.

Wenn der Render zweimal fehlschlägt, halte an und bewahre die Beweise. Lass plan.json, palette.json und die Assets an Ort und Stelle und sage, welche Datei zu betrachten ist. Ein fehlgeschlagener Render mit einem überprüfbaren Plan ist wiederherstellbar; einer, der durch ein Umschreiben „repariert“ wurde, nicht.

Wenn du doch die Komponenten anfassen musst

Nur, wenn ein Plan etwas benötigt, das die Beat-Komponenten nicht ausdrücken können. Drei Regeln, falls du dorthin gelangst:

1. Füge hinzu, schreibe nie um. Eine neue Kamerabewegung ist ein Eintrag in SHOTS in lib/camera.ts, keine umstrukturierte Komponente – und sie muss in pitchframe-motion-language aufgeführt sein, sonst wird sie nie ausgewählt.
2. Verwende lib/motion.ts und lib/camera.ts. EASE, EASE_OUT, clickPulse, heldDrift, entranceBlur sind das Genre. Handgestricktes Easing führt dazu, dass ein Beat so aussieht, als käme er aus einem anderen Video. Federn, Bounces und elastische Kurven sind verboten. Es gibt genau ein Kamerasystem. Füge außerhalb von Stage.tsx kein perspective oder eine 3D-Transformation hinzu; dieses Repository hatte einmal zwei, sie drifteten auseinander, und die Aufnahmen sahen nicht mehr aus, als wären sie von derselben Person gefilmt worden.
3. Halte es datengetrieben. Alles, was du hinzufügst, muss über ein Feld in plan.json erreichbar sein. Wenn die einzige Möglichkeit, es auszulösen, die Bearbeitung der Komponente ist, ist es eine einmalige Sache und gehört nicht ins Referenzprojekt.

Hier immer falsch: ein Farb-Literal; der Produktname oder -text fest in einer Komponente codiert; eine neue Top-Level-Komposition; Änderung des 1920×1080‑/30fps‑Vertrags; Importieren einer Animationsbibliothek.

Das Hinzufügen eines Beat-Typs ist fast immer die falsche Antwort. Das Schema hat vier, weil ein Launch-Video vier braucht. Ein neuer Beat-Typ ist meist ein Feature-Beat im Kostüm, und sobald das Schema eine Feature-Liste ausdrücken kann, enthalten Pläne eine.

Nach einem erfolgreichen Render

Melde den Pfad und den Bearbeitungshinweis:

Fertig. Video bereit unter ./pitchframe/output.mp4

Zum Bearbeiten einfach sagen:
  "den Heldenmoment länger halten"
  "auf das geänderte Feld zoomen"

Die Bearbeitung erfolgt durch pitchframe-editing, nicht durch erneutes Ausführen der Pipeline.