iamryoman/remotion-best-practices

Remotion Best Practices

Erstelle eine Remotion-Ausgabe als deterministische Funktion des Frames, der Eingabe-Props und der deklarierten Assets. Bewahre Benutzeränderungen sowie den vorhandenen Paketmanager, die Architektur und den Stil des Projekts, es sei denn, die Aufgabe erfordert eine Änderung.

Beginne mit Beweisen

1. Lies die Repository-Anweisungen und überprüfe package.json, die Lockdatei, die Remotion-Konfiguration, den Einstiegspunkt, registrierte Kompositionen und nahegelegene Tests.
2. Führe bei einem bestehenden Projekt node <skill-directory>/scripts/audit-remotion-project.mjs <project-root> aus. Behandle seine Ausgabe als Beweis, nicht als Erlaubnis zum Upgrade.
3. Notiere die installierte Remotion-Version, bevor du APIs auswählst. Halte alle remotion- und @remotion/*-Pakete auf der exakt gleichen Version. Füge keine zweite Lockdatei hinzu.
4. Identifiziere, ob das Ergebnis ein Video, ein einzelnes Standbild, ein aus einem Video entnommener Frame oder ein Batch von Store-Screenshots ist.
5. Definiere die Kompositions-ID, Abmessungen, FPS, Dauer, Props, Ausgabepfad und erforderliche Assets vor der Implementierung.

Lade nur die relevante Referenz

• Für <Composition>, <Still>, useCurrentFrame(), interpolate(), spring(), <Sequence> oder <Series>, lies composition-and-timing.md.
• Für staticFile(), Medien, Schriftarten, Netzwerkdaten, useDelayRender(), delayRender() oder calculateMetadata(), lies assets-and-async.md.
• Für CLI, renderStill(), serverseitiges Rendering oder Remotion Lambda, lies rendering-and-lambda.md.
• Für langsame Renderings, hohen Speicherverbrauch, Nichtdeterminismus oder Überprüfungsstrategie, lies performance-and-testing.md.
• Für App Store- oder Google Play-Bilder, einschließlich 1284×2778-Ausgabe, die von screenshot-studio delegiert wird, lies store-stills.md.
• Wenn sich eine API- oder Plattformregel geändert haben könnte, konsultiere vor dem Programmieren die aktuelle Primärquelle, die unter sources.md verlinkt ist.

Unverhandelbare Implementierungsregeln

• Leite die Zeit aus useCurrentFrame() und useVideoConfig() ab. Verwende keine CSS-Übergänge, CSS-Keyframe-Animationen, Echtzeittimer oder ungesetzte Zufallszahlen für gerenderte Bewegung.
• Begrenze endliche Animationen, es sei denn, eine Extrapolation ist beabsichtigt. Drücke Zeitangaben in Sekunden multipliziert mit fps aus, wenn sie Zeit darstellen, und zentralisiere gemeinsame Szenendauern.
• Denke daran, dass useCurrentFrame() relativ innerhalb einer zeitgesteuerten Komponente ist. Übergib einen absoluten Frame vom Kompositionsstamm nur, wenn eine globale Synchronisation beabsichtigt ist.
• Verwende <Sequence> für die explizite Platzierung auf der übergeordneten Zeitachse und <Series> für aufeinanderfolgende Szenen. Gib jeder Szene eine explizite Dauer.
• Lege lokale Assets in public/ ab und löse sie mit staticFile() auf. Verwende Remotion-Medienkomponenten anstelle von rohen HTML-Tags, damit das Rendering korrekt auf Medien wartet.
• Bevorzuge useDelayRender() innerhalb von Komponenten. Erstelle ein Handle genau einmal, räume es genau einmal auf und rufe bei Fehlern cancelRender(error) auf. Bevorzuge calculateMetadata() für Daten, die benötigt werden, um Props oder Metadaten einmal pro Rendering zu bestimmen.
• Halte renderseitigen Code frei von Browser-Only-Annahmen, die in headless Chromium oder Lambda nicht verfügbar sind. Setze niemals AWS-Anmeldeinformationen oder andere Geheimnisse dem Browser-Bundle aus.
• Validiere Abmessungen, Dateiformat, Alpha-Kanal-Richtlinie und plattformspezifische Regeln unabhängig für jedes Store-Ziel. Gehe niemals davon aus, dass eine Portrait-Größe sowohl von Apple als auch von Google akzeptiert wird.

Arbeite in einer engen Render-Schleife

1. Überprüfe den Typ und führe fokussierte Tests durch.
2. Rendere repräsentative Standbilder: den Start, jede Szenengrenze, einen Bewegungsmittelpunkt und den letzten Frame.
3. Überprüfe die tatsächlichen Pixel, nicht nur die Studio-Vorschau. Überprüfe auf Beschneidungen, Textumbruch, sichere Ränder, fehlende Assets und transparente Hintergründe.
4. Rendere einen kurzen Frame-Bereich oder eine Vorschau in niedriger Auflösung, bevor ein vollständiges teures Video erstellt wird.
5. Messe den Parallelitätsgrad auf dem Bereitstellungsrechner, anstatt ihn blind zu maximieren.
6. Rendere das endgültige Artefakt mit einer expliziten Kompositions-ID, Props, Ausgabepfad, Abmessungen und Format.
7. Überprüfe den Exit-Status, die Dateiexistenz, die Pixelabmessungen, die Dauer/Frame-Anzahl (wo relevant) und eine abschließende visuelle Stichprobe.

Nimm Änderungen konservativ vor

• Upgrade Remotion nicht, schreibe die Projektstruktur nicht um und ersetze Medienkomponenten nicht, es sei denn, die Aufgabe erfordert es oder der Benutzer stimmt zu.
• Grenze neuere APIs hinter der installierten Version ein; biete einen kompatiblen Fallback an, wenn praktikabel.
• Verstecke Rendering-Fehler nicht durch willkürliche Timeout-Erhöhungen. Identifiziere zuerst das nicht aufgelöste Handle, die Netzwerkanfrage, das Asset, die Schriftart oder die Mediendekodierung.
• Behaup keine Leistungsverbesserung ohne Messungen aus vergleichbaren Renderings.