HyperFrames Core
Das Ausgabe-Framework ist Remotion. Eine Komposition ist ein React-Komponentenbaum, der mit <Composition> registriert wird; der aktuelle Frame ist die einzige Uhr; die Medienwiedergabe gehört zu Remotions <Video> / <Audio>-Komponenten, nicht zum DOM.
Diese Skill ist der technische Vertrag: wie man ein Projekt baut. Der folgende Text ist die Bauanleitung; Details zu jedem Thema finden sich in references/, bei Bedarf lesen. Andere Belange leben in den benachbarten Domain-Skills: hyperframes-animation, hyperframes-creative, media-use, hyperframes-cli, hyperframes-registry. Die Fähigkeitenkarte in /hyperframes sagt, was jede abdeckt.
Portierungshinweis. Dieser Vertrag ersetzte einen HTML plus
data-*plus pausierten-GSAP-Timeline-Vertrag. Wenn Sie ein Projekt finden, dessenindex.htmldata-composition-id/data-start/data-durationträgt, oder eine Referenzdatei, diewindow.__timelinesbeschreibt, betrachten Sie den alten Vertrag. Lesen Siereferences/legacy-html-contract.md, bevor Sie ihn anfassen.
Referenzen
| Datei | Lesen, um… |
|---|---|
references/minimal-composition.md | vom kleinsten renderbaren Projektskelett zu starten |
references/project-structure.md | src/ anzulegen, Szenen in Komponenten aufzuteilen, monolithisch vs. modular zu entscheiden |
references/timing.md | Sekunden in Frames umzurechnen, eine <Sequence> zu platzieren, <Series> / <TransitionSeries> zu verwenden, eine Szene relativ zu einer anderen zu timen |
references/layers-and-order.md | Schichten zu stapeln, die z-Reihenfolge zu steuern, zwei Szenen auf demselben Zeitabschnitt zu überlappen |
references/props-and-schemas.md | Props zu deklarieren, das Zod-Schema zu schreiben, defaultProps und calculateMetadata zu verdrahten |
references/media.md | <Video> / <OffthreadVideo> / <Audio> / <Img> zu platzieren, zu trimmen, die Lautstärke einzustellen, staticFile zu verwenden |
references/determinism-rules.md | den Render suchbar und reproduzierbar zu halten; die Verbote; asynchrones Asset-Laden via delayRender |
references/editing-recipes.md | Schnitt-/Trim-/Neuordnen-/Neutiming-/Einfrieren-/Kamera-/Masken-/Crossfade-/Audio-Rezepte und deren Grenzen |
references/legacy-html-contract.md | ein Projekt zu erkennen und zu migrieren, das noch auf dem alten HTML + data-*-Vertrag basiert |
references/tailwind.md | in einem Tailwind v4-Projekt zu arbeiten |
references/storyboard-format.md | einen STORYBOARD.md-Plan zu verfassen (+ das geparste Manifest) |
references/review-loop.md | die Plan→Skizze→Bau-Review-Durchläufe auf einem Live-Board durchzuführen |
references/production-loop.md | einen genehmigten Plan in ein ausgeliefertes Video zu überführen |
references/brief-contract.md | die Grundregeln des Briefings: Modenableitung, gemeinsames Feldregister, Frageninvarianten |
references/brief-format.md | BRIEF.md zu verfassen |
references/script-format.md | das optionale SCRIPT.md mit gesperrtem Erzähltext zu verfassen |
references/subagent-dispatch.md | Subagent-Dispatch-Verben auf Ihre Harness abzubilden |
references/frame-worker-core.md | den gemeinsamen Frame-Worker-Rollenvertrag |
Für Animationsspezifika (Spring-Konfigurationen, Easing, Laufzeit-Adapter) gehen Sie zu hyperframes-animation.
Eine Komposition bauen
Die Form eines Projekts
package.json # remotion, react, react-dom; Skripte für studio/render
remotion.config.ts # Renderzeit-Konfiguration (Codec, Bildformat, Tailwind/Webpack-Overrides)
tsconfig.json
public/ # Alles, wogegen staticFile() auflöst
src/
index.ts # registerRoot(Root)
Root.tsx # Jede <Composition> lebt hier
<Name>/
index.tsx # Die Top-Level-Komponente der Komposition
scenes/*.tsx # Eine Komponente pro Szene
schema.ts # Zod-Schema + abgeleiteter Props-Typ
src/index.ts ist der Einstiegspunkt und tut genau eine Sache:
import { registerRoot } from "remotion";
import { Root } from "./Root";
registerRoot(Root);
Die Komposition registrieren
Jedes renderbare Ding ist eine <Composition> in Root.tsx. Die id ist das, was die CLI namentlich rendert.
import { Composition } from "remotion";
import { LaunchVideo } from "./LaunchVideo";
import { launchSchema } from "./LaunchVideo/schema";
const FPS = 30;
export const Root: React.FC = () => (
<>
<Composition
id="launch"
component={LaunchVideo}
durationInFrames={45 * FPS}
fps={FPS}
width={1920}
height={1080}
schema={launchSchema}
defaultProps={{ productName: "Acme", accent: "#5B8CFF" }}
/>
</>
);
durationInFrames ist die Renderlänge. Es sind Frames, nicht Sekunden, und das falsch zu machen ist der häufigste Autorenfehler. Leiten Sie es von einer benannten FPS-Konstanten ab, anstatt 1350 zu schreiben.
Frame ist die einzige Uhr
Jeder animierte Wert ist eine reine Funktion von useCurrentFrame(). Das ist der Vertrag, der einen Render suchbar macht: Der Renderer springt kalt auf Frame 812 und muss dieselben Pixel erhalten, die er beim Durchspielen erhalten würde.
import { AbsoluteFill, useCurrentFrame, useVideoConfig, interpolate, spring } from "remotion";
export const Title: React.FC<{ text: string }> = ({ text }) => {
const frame = useCurrentFrame();
const { fps } = useVideoConfig();
const enter = spring({ frame, fps, config: { damping: 18 } });
const y = interpolate(enter, [0, 1], [40, 0]);
return (
<AbsoluteFill style={{ justifyContent: "center", alignItems: "center" }}>
<h1 style={{ opacity: enter, transform: `translateY(${y}px)` }}>{text}</h1>
</AbsoluteFill>
);
};
Klemmen Sie immer ein interpolate, das einen Frame-Bereich abbildet, sonst extrapoliert der Wert über den Bereich hinaus und ein Einblenden wird zu einer Deckkraft von 4:
const opacity = interpolate(frame, [0, 15], [0, 1], {
extrapolateLeft: "clamp",
extrapolateRight: "clamp",
});
Timing ist <Sequence>
<Sequence> verschiebt seine Kinder zeitlich: Darin gibt useCurrentFrame() 0 am eigenen Start der Sequenz zurück. Diese lokale Neubasierung ist der ganze Sinn, denn eine Szenenkomponente muss nie wissen, wo sie auf der Master-Zeitleiste sitzt.
<AbsoluteFill>
<Sequence durationInFrames={90}>
<Hook />
</Sequence>
<Sequence from={90} durationInFrames={150}>
<Feature />
</Sequence>
<Sequence from={240} durationInFrames={120}>
<Close />
</Sequence>
</AbsoluteFill>
Für eine Reihe von aufeinanderfolgenden Szenen berechnet <Series> die Offsets, sodass eine Daueränderung nicht dazu führt, dass jedes spätere from von Hand korrigiert werden muss:
<Series>
<Series.Sequence durationInFrames={90}><Hook /></Series.Sequence>
<Series.Sequence durationInFrames={150}><Feature /></Series.Sequence>
<Series.Sequence durationInFrames={120}><Close /></Series.Sequence>
</Series>
<Series.Sequence offset={-15}> zieht eine Szene nach vorne, um ihren Vorgänger zu überlappen – so erhalten Sie eine Crossfade-Spanne ohne Arithmetik. Vollständige Details, plus <TransitionSeries> für präsentationsbasierte Übergänge, in references/timing.md.
Layer ersetzen Tracks
Es gibt keinen Track-Index. Stapeln ist die DOM-Reihenfolge innerhalb eines <AbsoluteFill>: spätere Geschwister malen oben. Eine Voiceover-Spur, ein Musikbett und drei visuelle Szenen sind fünf Geschwister.
<AbsoluteFill>
<Audio src={staticFile("music.mp3")} volume={0.18} />
<Audio src={staticFile("vo.mp3")} />
<Sequence durationInFrames={90}><Hook /></Sequence>
<Sequence from={90}><Feature /></Sequence>
<Overlay /> {/* malt oben auf alles darüber */}
</AbsoluteFill>
<Sequence layout="none"> lässt den impliziten <AbsoluteFill>-Wrapper weg. Verwenden Sie es, wenn das Kind am Flex- oder Grid-Layout des Elternteils teilnehmen muss, anstatt absolut positioniert zu sein.
Medien gehören zu Remotion
Greifen Sie niemals zu einem rohen <video>, <audio> oder <img>-Tag. Remotions Komponenten ermöglichen es dem Renderer, Frames deterministisch zu suchen und zu extrahieren.
| Bedarf | Verwenden |
|---|---|
| Video im Render | <OffthreadVideo src> (bevorzugt) |
| Video mit DOM-Level-Steuerung | <Video src> |
| Audio | <Audio src volume trimBefore trimAfter> |
| Standbild | <Img src> |
| Eingebettete Seite | <IFrame src> |
Beliebige Datei unter public/ | staticFile("dir/name.ext") |
<OffthreadVideo> extrahiert Frames mit FFmpeg außerhalb des Browsers, was sowohl schneller als auch genauer zum Rendern ist; greifen Sie nur dann zu <Video>, wenn Sie das echte Element benötigen (z. B. um etwas von seiner currentTime abzuleiten). staticFile() ist für lokale Assets obligatorisch. Ein bloßer String "/music.mp3" funktioniert im Studio und bricht dann in einem Lambda-Render. Trimmen, Lautstärkerampen und Wiedergabegeschwindigkeit finden Sie in references/media.md.
Props und Schema
Kompositionseingaben sind React-Props, typisiert durch ein Zod-Schema, damit Studio bearbeitbare Steuerelemente dafür rendert und eine fehlerhafte --props-Nutzlast laut scheitert, anstatt falsch zu rendern.
import { z } from "zod";
import { zColor } from "@remotion/zod-types";
export const launchSchema = z.object({
productName: z.string(),
accent: zColor(),
features: z.array(z.object({ title: z.string(), body: z.string() })),
});
export type LaunchProps = z.infer<typeof launchSchema>;
Wenn die Dauer von den Props abhängt (eine Feature-Liste unbekannter Länge, eine Audiodatei unbekannter Länge), berechnen Sie sie in calculateMetadata, anstatt eine Schätzung fest zu codieren. Siehe references/props-and-schemas.md.
Nicht verhandelbare Regeln
Stille Fehler, die eine Typüberprüfung nicht abfängt. Vollständige Begründung in references/determinism-rules.md.
- Keine Wanduhr. Kein
Date.now(), keinnew Date(), keineperformance.now(). Die Zeit kommt vonuseCurrentFrame(). - Kein ungesäter Zufall.
Math.random()gibt pro Frame einen anderen Wert, was flackert. Verwenden Sie Remotionsrandom(seed): gleicher Seed, gleicher Wert, jeder Frame und jeder Render. - Keine zustandsgesteuerte Animation.
useState/useReducer/useEffectdürfen nichts Visuelles steuern. Der Renderer mountet Frames außer der Reihe und in parallelen Workern; der durch Vorwärtsspielen aufgebaute Zustand existiert nicht. Leiten Sie stattdessen vonframeab. - Keine CSS-Animationen, Übergänge oder
requestAnimationFrame. Sie laufen auf der eigenen Uhr des Browsers, die der Renderer nicht weiterschaltet. Jede einzelne von ihnen rendert als eingefrorener erster Frame. - Warten Sie auf asynchrone Arbeit mit
delayRender. Ein Fetch, eine Schriftart, ein gemessenes Layout: Rufen SiedelayRender()davor undcontinueRender(handle)danach auf, sonst wird der Frame erfasst, bevor die Arbeit ankommt. - Klemmen Sie Ihre Interpolationen. Ungeklemmtes
interpolateextrapoliert außerhalb des Eingabebereichs. - Absolute Positionierung für alles Animierte. Ein transformiertes Element im normalen Fluss zieht seine Geschwister mit, wenn es sich bewegt.
Vorhandene Kompositionen bearbeiten
- Lesen Sie zuerst die Dateien. Bewahren Sie nicht zusammenhängendes Timing, Props, IDs und Asset-Pfade.
- Stimmen Sie mit der vorhandenen
Composition-idüberein. Die CLI, jedes Render-Skript und CI adressieren Kompositionen darüber. Eine Umbenennung ist eine bahnbrechende Änderung. - Hinzufügen einer Szene: Bevorzugen Sie
<Series>, damit die Offsets neu berechnet werden. In einer manuell offsetierten<Sequence>-Liste korrigieren Sie jedes späterefrom. - Ändern einer Dauer: Prüfen Sie auch
durationInFramesauf der<Composition>. Eine Szene, die über die Kompositionslänge hinausläuft, wird stillschweigend abgeschnitten. - Hinzufügen einer Komponente: Halten Sie sie als reine Funktion von Props und
frame.
Validierung
Der Befehlsdetail befindet sich in hyperframes-cli.
-
npx tsc --noEmit, damit Schema und Prop-Typen tatsächlich übereinstimmen -
npx remotion still <id> out/probe.png --frame <n>an einigen Szenenmittelpunkten, und betrachten Sie jeden -
npx remotion studiozur Überprüfung, damit der Benutzer selbst scruben und Props anpassen kann -
npx remotion render <id>erst, nachdem der Benutzer zugestimmt hat