Skip to content

🎥 Make videos programmatically with React

Skills: Rewrite editable timeline guidance

JonnyBurger9835e1410a57
diff --git a/.agents/skills/remotion-new-markup/SKILL.md b/.agents/skills/remotion-new-markup/SKILL.md
index 761e918d2e..8ac82eeaa7 100644
--- a/.agents/skills/remotion-new-markup/SKILL.md
+++ b/.agents/skills/remotion-new-markup/SKILL.md
@@ -1,16 +1,20 @@
---
name: remotion-new-markup
-description: Write or refactor Remotion markup with Track, connected compositions, and Interactive.create using explicit absolute-fill or none layouts.
+description: Write or refactor editable Remotion markup with appropriate tracks, shared timing boundaries, and connected compositions.
---
# New Remotion markup
-Follow the complete [Track + connected compositions example](../../../packages/skills/skills/remotion-interactivity/timeline-structure.md).
+Read [editable timeline structure](../../../packages/skills/skills/remotion-interactivity/timeline-structure.md)
+before choosing components and wrappers. Start with what should be edited
+together, then choose independent tracks or consecutive sequences. The guide
+includes the complete interactive element, scene, parent, and registration.
-- Put successive scenes in a named `<Track>`, with `from` and `durationInFrames` directly on each instance. Items in a `<Track>` MUST not overlap.
-- Create scenes with `Interactive.create({layout: 'absolute-fill'})`; return a fragment inside and put instance styles on the exported component.
-- Create bounded elements with `Interactive.create({layout: 'none'})`; forward `style` to a plain root.
-- Register the same exported scene and reusable element components as connected compositions, with inline metadata and representative `defaultProps`.
-- Keep each independently editable instance as its own JSX node. Use plain HTML for layout-only containers.
+For footage with synchronized captions or overlays, also read
+[editable video timelines](../../../packages/skills/skills/remotion-markup/video-editing.md).
+For extracting a group into its own timeline, use
+[connected compositions](../../../packages/skills/skills/remotion-markup/connected-compositions.md).
-Use `TransitionSeries` when scenes overlap through transitions. Preserve its specialized sequence boundaries. Avoid extra `Sequence` and `AbsoluteFill` wrappers.
+Verify a structural change in the full composition and any standalone views.
+Preserve the existing edit, and distinguish useful markup grouping from Studio's
+row expansion and layout behavior.
diff --git a/packages/skills/skills/remotion-interactivity/SKILL.md b/packages/skills/skills/remotion-interactivity/SKILL.md
index 681332d21c..56538c0e1a 100644
--- a/packages/skills/skills/remotion-interactivity/SKILL.md
+++ b/packages/skills/skills/remotion-interactivity/SKILL.md
@@ -4,53 +4,22 @@ description: Structure Remotion markup for interactivity
version: 4.0.536
---
-By writing Remotion markup in a specific way, the Remotion Studio is able to recognize the structure of the code and makes it interactive:
+Studio edits the JSX nodes that create timeline items. Structure the code around
+what the user should be able to select, move, trim, or style independently.
+Keep editable values inline on each instance.
-- Allowing items to be selected by clicking on them
-- Allowing drag+drop, resizing and rotation
-- Editing the CSS styles
-- Making keyframes and easing values editable
+Before writing a scene or refactoring its layers, read
+[editable timeline structure](timeline-structure.md). It covers editing units,
+tracks, shared timing, plain layout containers, and a complete component-to-root
+example. For a timeline built from footage, also read
+[editable video timelines](../remotion-markup/video-editing.md).
-If the markup is too complex for the Studio to make it interactive, then the values become grayed out.
+Use [connected compositions](../remotion-markup/connected-compositions.md) when
+a scene or reusable group needs its own timeline. Validate both its standalone
+view and the full parent timeline; a connection alone does not guarantee fewer
+visible rows.
-## Prefer interactive components with their own timelines
-
-Build new compositions with `Track`, connected compositions, and `Interactive.create()`.
-
-Set `layout` explicitly to `'absolute-fill'` for scenes or `'none'` for bounded elements. Register the same exported scene and reusable element components with `Composition`.
-
-Start with the complete [Track + connected compositions example](timeline-structure.md).
-It includes the element, scene, parent timeline, and root registrations.
-
-```tsx title="MyVideo.tsx"
-import {Track, useVideoConfig} from 'remotion';
-import {Chapter} from './Chapter';
-
-export const MyVideo = () => {
- const {fps} = useVideoConfig();
-
- return (
- <Track name="Chapters">
- <Chapter
- name="Opening"
- durationInFrames={3 * fps}
- title="Introduction"
- />
- <Chapter
- name="Feature"
- from={3 * fps}
- durationInFrames={4 * fps}
- title="New features"
- />
- </Track>
- );
-};
-```
-
-Put background and alignment styles on each scene instance, as shown in the
-complete example. Keep layout-only containers as plain HTML.
-
-### Choose schema fields
+## Choose schema fields
Each key in the schema is a prop that Studio can read and edit at the call site.
Props that are not in the schema still work, but are not editable in Studio.
@@ -100,103 +69,6 @@ Nested markup and computed children are currently read-only.
`text-content` is a deprecated alias for the `string` field type.
See [`InteractivitySchema`](https://www.remotion.dev/docs/interactivity-schema) for all options.
-### Register reusable components as connected compositions
-
-Register scenes and reusable elements as standalone compositions. Studio calls
-these **connected compositions**: they can be opened in their own timeline while
-sharing the same component implementation with the parent video.
-
-Define required styles and load fonts inside the component so it works without
-its parent. See
-[parent independence](../remotion-markup/connected-compositions.md#make-the-component-independent-of-its-parent).
-
-Register the same exported component reference that the parent renders. For the
-example above, use `component={Chapter}`, not `ChapterInner` or an inline wrapper.
-`Interactive.create()` provides the sequence, so no extra `<Sequence>` is needed for the connection.
-
-```tsx title="src/Root.tsx"
-import {Composition} from 'remotion';
-import {Chapter} from './Chapter';
-
-export const RemotionRoot = () => (
- <Composition
- id="Chapter"
- component={Chapter}
- width={1280}
- height={720}
- fps={30}
- durationInFrames={90}
- defaultProps={{
- title: 'A new perspective',
- style: {
- backgroundColor: '#111111',
- justifyContent: 'center',
- alignItems: 'center',
- },
- }}
- />
-);
-```
-
-Choose a unique ID, representative inline defaults, and dimensions, fps, and
-duration suitable for previewing the component. Registration defaults do not
-automatically copy props from a parent instance. See
-[connected compositions](../remotion-markup/connected-compositions.md) for
-registration and extraction details.
-
-### Put timing directly on the component
-
-Avoid a separate `<Sequence>` around one component that already accepts timing
-props. Built-in interactive components and custom components made with
-`Interactive.create()` can receive `name`, `from`, `durationInFrames`,
-`trimBefore`, and `playbackRate` directly.
-
-```tsx
-<Chapter
- name="Opening scene"
- from={30}
- durationInFrames={90}
- style={{opacity: 0.9}}
- title="A new perspective"
-/>
-```
-
-For shared scene timing, group the content in a component made with
-`Interactive.create()` and time that instance. Managed roots also accept
-`width` and `height` for `useVideoConfig()`.
-
-Use `<Track>` to put items on the same Studio timeline row.
-Use `<TransitionSeries>` when scenes are sequential.
-
-## Give every independently editable item its own JSX node
-
-The Studio edits the JSX source node that created an item. If multiple runtime
-items come from the same JSX node, they share one source-editing target.
-
-For every composition registration, clip, scene, layer or sequence that should
-be editable on its own, write a separate JSX node and keep its editable props
-on that node. This applies to `<Composition>`, `<Still>`, built-in media
-components, `<Sequence>`, `<TransitionSeries.Sequence>`
-and custom components.
-
-For example, author an editable timeline like this:
-
-```tsx title="Separate source nodes"
-import { Track } from "remotion";
-
-<Track name="Scenes">
- <Introduction name="Introduction" durationInFrames={90} />
- <Demo name="Demo" from={90} durationInFrames={150} />
-</Track>
-```
-
-A `.map()` or another programmatic loop would create multiple runtime items
-from one JSX source node. That is appropriate for repeated output that is
-intentionally controlled as one template, such as visualization bars or
-particles. It is not appropriate when the instances need independent IDs or
-names, props, metadata, timing, ordering, deletion or duplication in the
-Studio.
-
## Make an HTML element interactive using `Interactive`
Every HTML and SVG element (except `<Img>`, it already is interactive) such as `<div>` can be turned interactive using `Interactive`:
@@ -210,7 +82,9 @@ Every HTML and SVG element (except `<Img>`, it already is interactive) such as `
</Interactive.Div>
```
-This allows styles and keyframes to be set in the Studio. Be sensible, if a component has many elements, the timeline might get messy.
+Use this for text or graphics that need independent controls. Keep layout-only
+containers and decorative internals as plain HTML; an interactive component
+already provides controls for its root.
## Prefer inline text
diff --git a/packages/skills/skills/remotion-interactivity/timeline-structure.md b/packages/skills/skills/remotion-interactivity/timeline-structure.md
index d7cf02ed14..31e30a67d5 100644
--- a/packages/skills/skills/remotion-interactivity/timeline-structure.md
+++ b/packages/skills/skills/remotion-interactivity/timeline-structure.md
@@ -1,12 +1,60 @@
-# Track + connected compositions
+# Editable timeline structure
-Use this structure for new compositions: a named `Track`, directly timed scene
-instances, and connected compositions made with `Interactive.create()`. Set
-`layout` explicitly: `'absolute-fill'` for scenes, `'none'` for bounded elements.
+Choose what the user should be able to move, trim, style, duplicate, or delete
+together before adding timeline items. A scene, a captioned shot, a summary
+card, or a sticker with its entrance sound can each be one editable unit.
+Use plain HTML for the layout and decoration inside that unit. Add an
+`Interactive` element when it needs independent selection or controls.
-## Make components interactive with `Interactive.create()`
+Write each independently editable instance as its own JSX node, with a literal
+name and inline timing and appearance props. Reuse the component implementation
+for repeated cards or stickers, but keep their instances separate. Use loops for
+output intentionally controlled as one template, such as particles or chart
+bars, rather than independently editable clips.
-Forward `style` to a plain root. The custom component already owns its timeline row.
+## Choose how items share time
+
+| Editing behavior | Structure |
+| ---------------------------------------------------------------- | ------------------------------------------------------------------- |
+| Items have independent start times and do not overlap | A named `Track`, with timing on each item |
+| Consecutive clips should stay adjacent when one changes duration | `TransitionSeries`, with timing on each `TransitionSeries.Sequence` |
+| Several layers must move, trim, or change speed together | One timed component or `Sequence` containing those layers |
+
+A track is useful for scenes, music segments, cutaways, stickers, or sound
+effects. Group non-overlapping siblings by role instead of giving every item
+its own row. Items that remain visible together need separate tracks or a
+component that contains their shared layout. Staggered entrances do not make
+overlapping cards suitable for one track.
+
+Put timing directly on components that accept it. Avoid a `Sequence` around a
+single timing-capable child just to name or register it. Keep wrappers that
+provide shared timing, dimensions, or `TransitionSeries` behavior. Use
+`layout="none"` on a `Sequence` when it should not introduce a layout element.
+
+For captioned footage and overlays spanning cuts, read
+[editable video timelines](../remotion-markup/video-editing.md).
+
+## Give substantial groups their own timelines
+
+Create a connected composition when a scene or reusable element benefits from
+being edited on its own. Export it with `Interactive.create()` and register the
+same reference with `Composition`.
+
+- Use `layout: 'absolute-fill'` for a scene. Return a fragment and put its
+ background and alignment styles on the instance; the managed root applies them.
+- Use `layout: 'none'` for a bounded element. Forward `style` to its plain root.
+ The component already owns a timeline item, so the root does not need another
+ `Interactive.Div` for the same controls.
+
+Connection enables drill-down and shared implementation. It does not guarantee
+fewer rows in the parent: Studio can display connected children inside a series.
+Choose useful editing boundaries, then inspect the actual parent timeline.
+Do not add wrapper components or hide editable content just to alter row counts.
+
+## Complete example
+
+The title is one editable element. Its scene has a connected timeline, while
+independently timed scenes and music segments each share a named track.
```tsx title="Title.tsx"
import type React from 'react';
@@ -17,7 +65,7 @@ const TitleInner = ({
style,
}: {
readonly children: React.ReactNode;
- readonly style?: React.CSSProperties;
+ readonly style: React.CSSProperties;
}) => <h1 style={{margin: 0, ...style}}>{children}</h1>;
export const Title = Interactive.create({
@@ -30,11 +78,6 @@ export const Title = Interactive.create({
});
```
-## 2. Make scenes interactive: `layout: 'absolute-fill'`
-
-Return a fragment. Put the background and alignment on the scene instance.
-The managed root handles `style`, `width`, and `height`; do not forward them inside.
-
```tsx title="Chapter.tsx"
import {Interactive} from 'remotion';
import {Title} from './Title';
@@ -43,12 +86,7 @@ const ChapterInner = ({title}: {readonly title: string}) => (
<>
<Title
name="Chapter title"
- style={{
- color: 'white',
- fontFamily: 'Arial, sans-serif',
- fontSize: 96,
- fontWeight: 700,
- }}
+ style={{fontFamily: 'Arial, sans-serif', fontSize: 96, color: 'white'}}
>
{title}
</Title>
@@ -65,53 +103,57 @@ export const Chapter = Interactive.create({
});
```
-## 3. Parent: Group items on a `Track`
-
-- Use a `<Track>` to put items on the same timeline row.
-- If items are strictly sequential, use a [`TransitionSeries`](../remotion-markup/transitions.md) instead.
-
-Do not add `Sequence` or `AbsoluteFill` wrappers.
-
```tsx title="MyVideo.tsx"
-import {Track, useVideoConfig} from 'remotion';
+import {Audio} from '@remotion/media';
+import {staticFile, Track, useVideoConfig} from 'remotion';
import {Chapter} from './Chapter';
export const MyVideo = () => {
const {fps} = useVideoConfig();
-
return (
- <Track name="Chapters">
- <Chapter
- name="Opening"
- durationInFrames={3 * fps}
- title="Introduction"
- style={{
- backgroundColor: '#111111',
- justifyContent: 'center',
- alignItems: 'center',
- }}
- />
- <Chapter
- name="Feature"
- from={3 * fps}
- durationInFrames={4 * fps}
- title="New features"
- style={{
- backgroundColor: '#243b53',
- justifyContent: 'center',
- alignItems: 'center',
- }}
- />
- </Track>
+ <>
+ <Track name="Chapters">
+ <Chapter
+ name="Opening"
+ durationInFrames={3 * fps}
+ title="Introduction"
+ style={{
+ backgroundColor: '#111111',
+ justifyContent: 'center',
+ alignItems: 'center',
+ }}
+ />
+ <Chapter
+ name="Feature"
+ from={3 * fps}
+ durationInFrames={4 * fps}
+ title="New features"
+ style={{
+ backgroundColor: '#243b53',
+ justifyContent: 'center',
+ alignItems: 'center',
+ }}
+ />
+ </Track>
+ <Track name="Music">
+ <Audio
+ name="Opening music"
+ src={staticFile('music.mp3')}
+ durationInFrames={2 * fps}
+ />
+ <Audio
+ name="Closing music"
+ src={staticFile('music.mp3')}
+ from={4 * fps}
+ trimBefore={10 * fps}
+ durationInFrames={3 * fps}
+ />
+ </Track>
+ </>
);
};
```
-## 4. Connect the same exported components
-
-Register the scenes and reusable elements alongside the parent. Use the same
-component references and give each registration usable inline defaults.
-
```tsx title="Root.tsx"
import {Composition, Folder} from 'remotion';
import {Chapter} from './Chapter';
@@ -157,10 +199,9 @@ export const RemotionRoot = () => (
defaultProps={{
children: 'Introduction',
style: {
- color: 'white',
fontFamily: 'Arial, sans-serif',
fontSize: 96,
- fontWeight: 700,
+ color: 'white',
},
}}
/>
@@ -168,3 +209,7 @@ export const RemotionRoot = () => (
</>
);
```
+
+Keep metadata and defaults inline on each registration. See
+[connected compositions](../remotion-markup/connected-compositions.md) for
+extracting existing groups and checking both the parent and standalone views.
diff --git a/packages/skills/skills/remotion-markup/SKILL.md b/packages/skills/skills/remotion-markup/SKILL.md
index 613f77aa96..b9488023dc 100644
--- a/packages/skills/skills/remotion-markup/SKILL.md
+++ b/packages/skills/skills/remotion-markup/SKILL.md
@@ -27,17 +27,12 @@ Tailwind animation class will not render correctly, they need to be refactored.
Use `Easing.bezier()` and `Easing.spring()` to customize timing.
-Use `Track` for successive scenes. Make scenes and reusable elements with
-`Interactive.create()`, setting `layout` explicitly to `'absolute-fill'` or
-`'none'`, and register them as connected compositions. Put timing directly on
-each instance. Follow the complete
-[Track + connected compositions example](../remotion-interactivity/timeline-structure.md).
-See [Remotion Interactivity](../remotion-interactivity/SKILL.md) for editable props
-and keyframes.
-
-The Studio edits the JSX source node that created an item. Author every composition registration, clip, scene, layer and sequence that should be editable independently as its own JSX node, with its editable props inline.
-Programmatic loops are suitable when the generated instances are intentionally controlled as one source template, not when users need to edit the instances
-separately.
+Before choosing the markup hierarchy, read
+[editable timeline structure](../remotion-interactivity/timeline-structure.md).
+Choose editing units first, then the tracks or shared timing boundaries they
+need. It includes a complete example with interactive components and their
+registrations. For source-editable styles, schemas, and keyframes, see
+[Remotion Interactivity](../remotion-interactivity/SKILL.md).
```tsx
import { useCurrentFrame, useVideoConfig, Easing, interpolate, Interactive } from "remotion";
@@ -130,160 +125,10 @@ export const MyComposition = () => {
If the composition is primarily a timeline of video or audio clips, read
[video-editing.md](video-editing.md) before choosing its source structure.
-## Example scene
-
-A background video with a lower third.
-The lower third is an interactive component with its own timeline, registered as a [connected composition](connected-compositions.md).
-Its text is passed as `children` and `accentColor` is an editable prop.
-The fade-in is keyframed inline at the call site.
-
-```tsx
-// MyScene.tsx
-import { Video } from "@remotion/media";
-import { Easing, Interactive, interpolate, useCurrentFrame, useVideoConfig } from "remotion";
-import { LowerThird } from "./LowerThird";
-
-const MySceneInner = () => {
- const { fps } = useVideoConfig();
- const frame = useCurrentFrame();
-
- return (
- <>
- <Video
- name="Background"
- src="https://remotion.media/video.mp4"
- objectFit="cover"
- style={{
- position: "absolute",
- width: "100%",
- height: "100%",
- }}
- />
- <LowerThird
- name="Lower third"
- from={1 * fps}
- accentColor="#0b84f3"
- style={{
- opacity: interpolate(frame, [1 * fps, 2 * fps], [0, 1], {
- extrapolateRight: "clamp",
- extrapolateLeft: "clamp",
- easing: Easing.bezier(0.16, 1, 0.3, 1),
- }),
- }}
- >
- Jane Doe, Product Designer
- </LowerThird>
- </>
- );
-};
-
-export const MyScene = Interactive.create({
- Component: MySceneInner,
- layout: "absolute-fill",
-});
-```
-
-```tsx
-// LowerThird.tsx
-import type React from "react";
-import { Interactive, type InteractivitySchema } from "remotion";
-
-type LowerThirdProps = {
- readonly children: React.ReactNode;
- readonly accentColor: string;
- readonly style?: React.CSSProperties;
-};
-
-const LowerThirdInner: React.FC<LowerThirdProps> = ({
- children,
- accentColor,
- style,
-}) => {
- return (
- <div
- style={{
- position: "absolute",
- left: 80,
- bottom: 80,
- display: "flex",
- alignItems: "center",
- gap: 20,
- backgroundColor: "white",
- borderRadius: 16,
- padding: "20px 32px",
- color: "black",
- fontFamily: "Helvetica, Arial, sans-serif",
- fontSize: 48,
- fontWeight: 600,
- ...style,
- }}
- >
- <div
- style={{
- width: 8,
- alignSelf: "stretch",
- borderRadius: 4,
- backgroundColor: accentColor,
- }}
- />
- {children}
- </div>
- );
-};
-
-const lowerThirdSchema = {
- ...Interactive.childrenSchema,
- ...Interactive.textSchema,
- accentColor: {
- type: "color",
- default: "#0b84f3",
- description: "Accent color",
- },
-} as const satisfies InteractivitySchema;
-
-export const LowerThird = Interactive.create({
- Component: LowerThirdInner,
- layout: "none",
- schema: lowerThirdSchema,
-});
-```
-
-```tsx title="src/Root.tsx"
-import { Composition } from "remotion";
-import { LowerThird } from "./LowerThird";
-import { MyScene } from "./MyScene";
-
-export const RemotionRoot: React.FC = () => {
- return (
- <>
- <Composition
- id="MyScene"
- component={MyScene}
- durationInFrames={60}
- fps={30}
- width={1280}
- height={720}
- />
- <Composition
- id="LowerThird"
- component={LowerThird}
- durationInFrames={30}
- fps={30}
- width={1280}
- height={720}
- defaultProps={{
- children: "Jane Doe, Product Designer",
- accentColor: "#0b84f3",
- }}
- />
- </>
- );
-};
-```
-
## Delaying, trimming
-Put timing directly on components that support it. See [Timing props](./timing-props.md) for the supported props, examples, and order of operations.
+Use [sequencing](sequencing.md) to choose the timing boundary and
+[timing props](timing-props.md) for the supported props and order of operations.
## Maps
@@ -299,14 +144,10 @@ See [multi-scene-video.md](multi-scene-video.md) if planning to make a video wit
## Connected compositions
-When a scene or group of layers deserves its own editable timeline, follow [connected-compositions.md](connected-compositions.md). Prefer this structure for substantial scenes in a multi-scene video.
-
-### Pre-compose action
-
-For a Studio request such as `Pre-compose Ambient glow (src/BarChart.tsx:134)`, find the selected sequence markup at the given location. Make a connected composition, following [connected-compositions.md](connected-compositions.md): extract the markup into a named component, preferably make it interactive with `Interactive.create()`, and register the same exported component reference with a unique `<Composition>` in the root. Render the interactive component directly with its timing props, or as the only child of a sequence when that wrapper has a purpose. If the selected node is already a sequence, keep its props and extract its children. The registration needs dimensions, fps, duration, and `defaultProps` equivalent to its parent use. A component extraction without a registered composition does not complete a pre-compose request.
-
-Carry inherited styles such as `fontFamily` and font loading into the extracted
-component; see [parent independence](connected-compositions.md#make-the-component-independent-of-its-parent).
+Read [connected compositions](connected-compositions.md) when a scene or group
+needs its own editable timeline, or when handling a Studio pre-compose request.
+It covers extraction, registration, inherited styles, and verification in both
+the parent and standalone views.
## Voiceover
@@ -466,6 +307,9 @@ This goes for `@remotion/*` packages, `mediabunny`, `@mediabunny/*`, `zod`, and
## Visual checks
-When a visual check is useful, open the [Remotion Studio](../remotion-studio/SKILL.md) for an interactive preview.
+Open the [Remotion Studio](../remotion-studio/SKILL.md) to check visual changes.
+When changing timeline structure, inspect the full composition as well as any
+connected components; verify the visible layers, cut timing, and synchronized
+content.
You can also use [Rendering](../remotion-render/SKILL.md) to inspect one or several frames as images.
diff --git a/packages/skills/skills/remotion-markup/connected-compositions.md b/packages/skills/skills/remotion-markup/connected-compositions.md
index acf7b1d577..57f5e30195 100644
--- a/packages/skills/skills/remotion-markup/connected-compositions.md
+++ b/packages/skills/skills/remotion-markup/connected-compositions.md
@@ -1,23 +1,65 @@
# Connected compositions
-Make every scene and reusable element a connected composition:
+A connected composition lets the user open a scene or element in its own
+Studio timeline while editing the implementation used by the parent video.
+Use it for a substantial scene, a reusable card, or a group that should move
+and be edited together, such as a sticker with its sound or a summary graphic.
+A layout container or decorative detail usually belongs inside that group as
+plain HTML.
-1. Export it with `Interactive.create()`. Set `layout: 'absolute-fill'` for a scene or `layout: 'none'` for a bounded element.
-2. Render the exported component directly inside a named `Track`, with inline timing and props.
-3. Register that same reference in `<Composition component={...}>`, alongside the parent video. Keep metadata and representative `defaultProps` inline.
+## Create the connection
-Follow the complete [Track + connected compositions example](../remotion-interactivity/timeline-structure.md), including `Title.tsx`, `Chapter.tsx`, `MyVideo.tsx`, and `Root.tsx`.
+1. Export the component with `Interactive.create()`. Use `layout: 'absolute-fill'`
+ for a scene or `layout: 'none'` for a bounded element.
+2. Render that exported component in the parent, with its instance props inline.
+ Put timing directly on it, or on the shared `Sequence` or
+ `TransitionSeries.Sequence` that governs its layers.
+3. Register the exact same exported reference in `<Composition component={...}>`.
+ Give the registration a unique literal ID, inline metadata, and representative
+ inline `defaultProps`. Registering an inner component or an inline wrapper
+ does not connect the instance the user sees.
-Double-clicking an instance opens its connected composition. Editing the shared
-component updates both views. Registration defaults do not automatically apply
-to the instances in the parent.
+Follow the [complete timeline example](../remotion-interactivity/timeline-structure.md)
+for the component definitions, parent, and registrations.
+
+Each independently editable instance still needs its own JSX node. Reuse a
+component for repeated units rather than copying its implementation or generating
+all instances from one `.map()` call. Keep editor-owned data at its editable
+source: caption arrays belong inline on the caption component, not behind a
+prop of a generic shot component.
## Make the component independent of its parent
-The parent is not mounted when the connected composition opens on its own.
-Keep required typography in the component and supply background and alignment
-in its inline registration defaults. Load fonts in its module or an imported
-shared module; see [Google fonts](google-fonts.md) and [local fonts](local-fonts.md).
+The parent is not mounted when the standalone composition opens. Load fonts
+inside the component or a shared imported module, and keep required typography
+there. Supply representative content, background, and alignment in the
+registration's defaults. Those defaults do not automatically apply to parent
+instances or copy their props.
+
+Match the parent's fps and dimensions unless a difference is intentional.
+Preserve the source-time offset as well as the duration when the component's
+captions or overlays read original-media frames. The instance's placement in
+the parent timeline does not usually belong in its standalone defaults.
+
+## Extract an existing group
+
+For a pre-compose request, move the selected markup into a named component and
+register it. If the selection already has a meaningful timing wrapper, keep
+that wrapper and its props in place and extract its contents. Preserve trim,
+speed, stacking order, inherited styles, and the duration needed by sound tails.
+A new component file without its registration does not complete the connection.
+
+## Verify both views
+
+Open the full composition and the standalone composition. Check that the group
+looks and sounds the same, that its timeline has useful editing units, and that
+double-clicking the parent instance opens the intended composition. For a
+refactor, compare representative frames and check cut boundaries, captions,
+entrance animations, and audio tails.
-Verify the component by opening its standalone composition. Keep its fps and
-dimensions consistent with the parent unless a difference is intentional.
+Connected compositions provide editing boundaries, not a promise to collapse
+all their rows. Studio's compact-series view can expose connected children.
+Inspect the full-video timeline as well as the standalone view before claiming
+that an extraction reduced clutter. Treat row expansion or unused vertical
+space as a layout issue when the markup already expresses the correct groups;
+avoid extra wrappers or hidden editable layers solely to force a compact view.
diff --git a/packages/skills/skills/remotion-markup/multi-scene-video.md b/packages/skills/skills/remotion-markup/multi-scene-video.md
index 64ce911292..d6b631d903 100644
--- a/packages/skills/skills/remotion-markup/multi-scene-video.md
+++ b/packages/skills/skills/remotion-markup/multi-scene-video.md
@@ -1,32 +1,21 @@
# Multi-scene videos
-Put successive scenes in a named `Track`. Make each scene with
-`Interactive.create({layout: 'absolute-fill'})` and register it as a connected
-composition. Write each instance separately with inline timing and props.
+Give each substantial scene its own component and connect it when it benefits
+from an independent editing timeline. Keep each instance's name, timing, and
+props inline in the parent.
-```tsx title="MyVideo.tsx"
-import {Track, useVideoConfig} from 'remotion';
-import {OpeningScene} from './OpeningScene';
-import {FeatureScene} from './FeatureScene';
+Choose the parent structure from the editing behavior:
-export const MyVideo = () => {
- const {fps} = useVideoConfig();
+- For independent scene start times, use a named `Track` with explicit `from`
+ and `durationInFrames` on each scene. Its items must not overlap.
+- For scenes that should remain adjacent as their durations change, use
+ `TransitionSeries`. Keep each scene inside its own
+ `TransitionSeries.Sequence`, with duration and source trim on that boundary.
+ Add transitions when needed and account for their overlaps in the total
+ composition duration.
- return (
- <Track name="Scenes">
- <OpeningScene name="Opening" durationInFrames={3 * fps} />
- <FeatureScene name="Feature" from={3 * fps} durationInFrames={4 * fps} />
- </Track>
- );
-};
-```
-
-Follow the complete [Track + connected compositions example](../remotion-interactivity/timeline-structure.md)
-for scene definitions and `Root.tsx`. Register `OpeningScene`, `FeatureScene`,
-and `MyVideo` using those same exported component references, with representative
-inline defaults. At 30 fps, this parent lasts 210 frames.
-
-When adding overlapping transitions, use
-[`TransitionSeries`](transitions.md) instead of `Track`. Keep each scene as the
-only child of its `TransitionSeries.Sequence`, and subtract transition overlaps
-from the parent duration.
+Follow [editable timeline structure](../remotion-interactivity/timeline-structure.md)
+for a complete scene, parent, and registration example. See
+[transitions](transitions.md) for transition timing and presentations, and
+[connected compositions](connected-compositions.md) for extraction and
+verification in the full video.
diff --git a/packages/skills/skills/remotion-markup/sequencing.md b/packages/skills/skills/remotion-markup/sequencing.md
index 77d4c68c94..9843a701bd 100644
--- a/packages/skills/skills/remotion-markup/sequencing.md
+++ b/packages/skills/skills/remotion-markup/sequencing.md
@@ -5,47 +5,24 @@ metadata:
tags: sequence, series, timing, delay, trim
---
-Prefer timing props directly on built-in interactive components and custom
-components made with `Interactive.create()`.
-Avoid wrapping a single timing-capable component in a redundant `<Sequence>`.
-Put `name`, `from`, `durationInFrames`, `loop`, and `volume`
-directly on `<Audio>` from `@remotion/media` whenever their combination gives the intended timing.
-
-See [Remotion Interactivity](../remotion-interactivity/SKILL.md) for creating
-schema-wrapped components and [connected compositions](connected-compositions.md)
-for registering them with their own Studio timelines.
-
-```tsx
-// Title and Subtitle are exported with Interactive.create().
-<>
- <Title name="Title" from={30} durationInFrames={60} />
- <Subtitle name="Subtitle" from={60} durationInFrames={60} />
-</>
-```
-
-Use an explicit `<Sequence>` when multiple siblings need one shared clock,
-when overriding dimensions for descendants, or when the child does not accept
-timing props. Its default layout adds an absolutely positioned fill element;
-use `layout="none"` when no layout wrapper is needed.
-
-## TransitionSeries
-
-Use `<TransitionSeries>` for consecutive scenes, with or without transitions. Without a transition, the scenes play without overlap.
-
-```tsx
-import { TransitionSeries } from "@remotion/transitions";
-
-<TransitionSeries>
- <TransitionSeries.Sequence durationInFrames={45}>
- <Intro />
- </TransitionSeries.Sequence>
- <TransitionSeries.Sequence durationInFrames={60}>
- <MainContent />
- </TransitionSeries.Sequence>
- <TransitionSeries.Sequence durationInFrames={30}>
- <Outro />
- </TransitionSeries.Sequence>
-</TransitionSeries>;
-```
-
-The items will be wrapped in an absolute fill element by default when using `<TransitionSeries.Sequence>`, unless the `layout` prop is set to `none`.
+# Choose the timing boundary
+
+Put timing props directly on a built-in interactive component or one made with
+`Interactive.create()` when that item should be edited independently. Set audio
+timing and volume on `Audio` from `@remotion/media`.
+
+Use a shared `Sequence` when several layers must inherit the same trim, speed,
+or start time, when overriding dimensions for descendants, or when the child
+does not accept timing props. Choose `layout="none"` if the group should not
+add a layout element; otherwise its absolute-fill layout also positions the
+contents.
+
+Use `Track` for non-overlapping items with independent positions and
+`TransitionSeries` for consecutive items that should shift together when a
+duration changes. Keep the series' own sequence boundaries, including when a
+child already accepts timing props.
+
+Follow [editable timeline structure](../remotion-interactivity/timeline-structure.md)
+for grouping and examples. See [timing props](timing-props.md) for how `from`,
+`trimBefore`, duration, speed, and looping combine, and
+[editable video timelines](video-editing.md) for synchronized footage and captions.
diff --git a/packages/skills/skills/remotion-markup/video-editing.md b/packages/skills/skills/remotion-markup/video-editing.md
index 69183ed23c..468362310b 100644
--- a/packages/skills/skills/remotion-markup/video-editing.md
+++ b/packages/skills/skills/remotion-markup/video-editing.md
@@ -1,167 +1,142 @@
# Editable video timelines
-The Studio edits the JSX source node that created a timeline item. Every clip
-that should be trimmed, moved, renamed, reordered, duplicated or deleted on its
-own therefore needs its own authored JSX node, with its editable timing props
-written directly on that node.
-
-This source structure is intentional repetition: It gives every runtime clip a
-separate source-editing target. A `.map()` or another programmatic loop instead
-creates multiple runtime clips from one JSX node. Use that only when the
-instances are intentionally controlled as one template and do not need
-independent editing.
-
-Choose the timeline structure based on the editing behavior:
-
-- Use independently positioned clips when moving or resizing one clip should
- not affect any other clip.
-- Use `<TransitionSeries>` for consecutive clips when changing one clip's
- duration should reposition every later clip. It also supports transitions
- and overlays.
-
-Use `const {fps} = useVideoConfig()` in the enclosing composition.
-For trims and other timing props expressed in seconds, use that `fps`
-directly in each clip's JSX, for example `trimBefore={4 * fps}`. Do not use a
-separate fixed `FPS` constant: Studio must be able to update each clip's source
-expression when the user trims or splits it.
-
-## Clips with synchronized captions or overlays
-
-For a clip with synchronized captions or overlays, make a shared timing group
-the editable timeline item. Keep the video and its synchronized layers inside
-one `<Sequence>` for independently positioned clips, or inside the same
-`<TransitionSeries.Sequence>` for consecutive clips.
-
-Put the clip's `trimBefore`, `durationInFrames`, and `playbackRate` on that
-shared parent, plus `from` when using an independently positioned `<Sequence>`.
-Apply the shared timing once, rather than repeating it on the children.
-Moving, trimming, changing the speed, reordering, or deleting the group then
-affects all its layers together. A shared wrapper has a purpose here even
-though the children accept timing props themselves.
-
-Keep each clip's captions in an inline array on its own `<BasicCaptions>` node,
-with timestamps relative to the original media file. Do not put a combined
-caption overlay outside the clip groups. See
-[Displaying captions alongside video content](../remotion-captions/display-captions.md#displaying-captions-alongside-video-content)
-for the complete example.
-
-## Independently positioned clips
-
-For clips without synchronized captions or overlays, place each `<Video>`
-directly in the composition and write its timing props on the JSX node.
-Use literal frame counts when they are already known;
-`from={0}` may be omitted:
+Structure the timeline around the things the user edits together: a captioned
+shot, a set of cutaways, or an independently timed music segment. Write every
+independently editable clip as its own JSX node with inline names and props.
+Use the [timeline structure guide](../remotion-interactivity/timeline-structure.md)
+for choosing tracks, timing groups, and connected compositions.
-```tsx
-<Video
- name="Opening"
- src="https://remotion.media/video.mp4"
- trimBefore={0}
- durationInFrames={78}
-/>
-<Video
- name="Interview"
- src="https://remotion.media/video.webm"
- trimBefore={12}
- from={78}
- durationInFrames={66}
-/>
-<Video
- name="Closing"
- src="https://remotion.media/video.mp4"
- trimBefore={72}
- from={144}
- durationInFrames={90}
-/>
-```
+## Choose the cut behavior
+
+Use a named `Track` for non-overlapping clips with independent start times. Keep
+`from`, `trimBefore`, `durationInFrames`, and `playbackRate` on each clip. Moving
+or resizing one clip then leaves the other start times unchanged.
-- `from` is the clip's absolute start frame in its parent timeline.
-- `durationInFrames` is how many source frames are shown, starting at `trimBefore`. At the default `playbackRate`, this is how long the clip remains visible.
-- `trimBefore` is how many source frames are skipped before playback begins.
-- Keep `name`, `from`, `durationInFrames` and `trimBefore` inline on each clip.
-- Import `<Video>` from `@remotion/media`.
+Use `TransitionSeries` when consecutive clips should remain adjacent. Put
+`durationInFrames` on each `TransitionSeries.Sequence`; the series calculates
+start times and repositions later clips after a duration change. It also handles
+overlapping transitions. Preserve these specialized boundaries when refactoring.
-Moving or resizing one of these clips does not reposition later clips. Gaps and
-overlaps are therefore allowed.
+Get `fps` from `useVideoConfig()` for seconds-to-frames expressions, and keep
+them on the JSX node, such as `trimBefore={4 * fps}`. Literal frame counts are
+appropriate when the edit is already specified in frames.
-## Consecutive clips with `TransitionSeries`
+## Keep synchronized layers on one clock
-Use `<TransitionSeries>` when the clips should remain adjacent. No transition
-components are needed for consecutive playback. The example below has no
-synchronized captions; for captioned clips, put the captions inside each
-sequence and move the video's trim to that shared sequence as described above:
+Put a shot's video, captions, and source-synchronized overlays under one timing
+boundary. Apply `trimBefore`, `durationInFrames`, and `playbackRate` to that
+boundary once. For an independently placed group, also set its `from`.
+
+A `Sequence` is useful here because moving, trimming, retiming, or deleting the
+group affects all its layers. For consecutive shots, use the existing
+`TransitionSeries.Sequence` for the same purpose:
```tsx
-import { TransitionSeries } from "@remotion/transitions";
-
-<TransitionSeries>
- <TransitionSeries.Sequence name="Opening" durationInFrames={78}>
- <Video
- src="https://remotion.media/video.mp4"
- trimBefore={0}
- />
- </TransitionSeries.Sequence>
- <TransitionSeries.Sequence name="Interview" durationInFrames={66}>
- <Video
- src="https://remotion.media/video.webm"
- trimBefore={12}
- />
- </TransitionSeries.Sequence>
- <TransitionSeries.Sequence name="Closing" durationInFrames={90}>
- <Video
- src="https://remotion.media/video.mp4"
- trimBefore={72}
- />
- </TransitionSeries.Sequence>
-</TransitionSeries>
+import {Video} from '@remotion/media';
+import {TransitionSeries} from '@remotion/transitions';
+import {staticFile, useVideoConfig} from 'remotion';
+import {BasicCaptions} from './basic-captions';
+
+export const Interview = () => {
+ const {fps} = useVideoConfig();
+ return (
+ <TransitionSeries name="Interview shots">
+ <TransitionSeries.Sequence
+ name="Opening"
+ trimBefore={4 * fps}
+ durationInFrames={3 * fps}
+ >
+ <Video name="Opening footage" src={staticFile('interview.mp4')} />
+ <BasicCaptions
+ name="Opening captions"
+ width={900}
+ style={{position: 'absolute', bottom: 80, translate: '510px 0px'}}
+ captions={[
+ {
+ text: 'Hello',
+ startMs: 4500,
+ endMs: 4900,
+ timestampMs: 4700,
+ confidence: null,
+ },
+ {
+ text: ' world',
+ startMs: 4900,
+ endMs: 5400,
+ timestampMs: 5150,
+ confidence: null,
+ },
+ ]}
+ />
+ </TransitionSeries.Sequence>
+ <TransitionSeries.Sequence
+ name="Next shot"
+ trimBefore={10 * fps}
+ durationInFrames={2 * fps}
+ >
+ <Video name="Next footage" src={staticFile('interview.mp4')} />
+ <BasicCaptions
+ name="Next captions"
+ width={900}
+ style={{position: 'absolute', bottom: 80, translate: '510px 0px'}}
+ captions={[
+ {
+ text: 'Next',
+ startMs: 10500,
+ endMs: 11000,
+ timestampMs: 10750,
+ confidence: null,
+ },
+ ]}
+ />
+ </TransitionSeries.Sequence>
+ </TransitionSeries>
+ );
+};
```
-The `<TransitionSeries.Sequence>` is the editable clip row. Changing its
-`durationInFrames` repositions every later sequence. Do not set `from` on a
-`<TransitionSeries.Sequence>`; the series calculates each start frame.
+Each caption array stays inline on its own caption node, with timestamps relative
+to the original media file. Passing the array through a generic shot prop removes
+the source array the Caption editor needs. See
+[displaying captions](../remotion-captions/display-captions.md#displaying-captions-alongside-video-content)
+for the caption component and setup.
-Keep every sequence as a separate JSX node with a hardcoded `name` and
-`durationInFrames`. The child may also be a custom clip or scene component:
+## Place overlays at the scope they span
-```tsx
-<TransitionSeries.Sequence name="Product demo" durationInFrames={150}>
- <ProductDemo />
-</TransitionSeries.Sequence>
-```
+Keep a source-synchronized HUD inside its shot. Put a sticker that continues
+across several cuts in the enclosing scene, so the end of the first cut does
+not unmount it. Use that scene's frame coordinates for its timing.
-## Consecutive clips with transitions
+Within a shot or scene, put successive cutaways on a named `Cutaways` track.
+Keep simultaneous visuals on separate tracks. If cutaways cover a speaking
+video, retain the underlying speech or deliberately separate its audio; removing
+an obscured video can also remove the voice.
-Use `<TransitionSeries>` when the timeline needs transitions or overlays.
-Preserve the same one-source-node-per-clip structure. Put a clip's synchronized
-captions inside its sequence and apply shared timing to that parent:
+Group a sticker or other visual with its accompanying sound when they should
+move or be deleted together. Keep their local offsets inside the group. Give
+both the visual and sound their intended durations so the group neither cuts
+off a sound tail nor extends the visual to cover that tail.
-```tsx
-<TransitionSeries name="Video timeline">
- <TransitionSeries.Sequence name="Opening" durationInFrames={78}>
- <Video
- src="https://remotion.media/video.mp4"
- trimBefore={0}
- />
- </TransitionSeries.Sequence>
- <TransitionSeries.Transition
- presentation={fade()}
- timing={linearTiming({durationInFrames: 12})}
- />
- <TransitionSeries.Sequence name="Interview" durationInFrames={66}>
- <Video
- src="https://remotion.media/video.webm"
- trimBefore={12}
- />
- </TransitionSeries.Sequence>
-</TransitionSeries>
-```
+## Put music segments on a shared track
+
+Music clips with gaps or adjacent boundaries can share one named track. They
+remain separately editable, including their source trims and volume envelopes:
+
+See the [complete timeline example](../remotion-interactivity/timeline-structure.md)
+for a music track alongside scene tracks.
+
+Check natural audio durations as well as explicit bounds before putting sounds
+on a track. An item may end exactly where the next begins, but overlapping tails
+need separate tracks. Do not shorten sounds just to make them fit.
+
+## Preserve the edit when restructuring
-The `<TransitionSeries.Sequence>` is the editable clip row. Do not set `from`
-on it; the series calculates the start frame and accounts for transition
-overlaps.
+Keep source trims, cut lengths, playback rates, caption arrays, volume envelopes,
+and stacking order unchanged unless the user requested an edit. Moving content
+under a new timing boundary can change the frame returned by `useCurrentFrame()`;
+preserve the source clock or adjust local offsets deliberately.
-Read [transitions.md](transitions.md) for transition types, imports,
-installation instructions and composition-duration calculation. Import
-`<Video>` from `@remotion/media`, and keep the parent composition's
-`durationInFrames` as an inline literal after accounting for all clip durations
-and transition overlaps.
+Verify the full composition and any connected views, rather than judging the
+result only from a standalone scene. Check visual output and audio around cuts,
+overlay boundaries, and sound tails. Grouping the timeline should preserve the
+existing edit while making its controls easier to use.