Skip to content

🎥 Make videos programmatically with React

Skills: Author editable timeline items as separate JSX nodes

JonnyBurger9964686ef2b5
diff --git a/packages/docs/docs/studio/interactivity-best-practices.mdx b/packages/docs/docs/studio/interactivity-best-practices.mdx
index a9c758a8be..dce2f1f015 100644
--- a/packages/docs/docs/studio/interactivity-best-practices.mdx
+++ b/packages/docs/docs/studio/interactivity-best-practices.mdx
@@ -16,6 +16,35 @@ By writing Remotion markup in a specific way, the [Remotion Studio](/docs/studio
If the markup is too complex for the Studio to make it interactive, then the values become grayed out.
Use the [`/remotion-interactivity` skill](/docs/ai/skills#remotion-interactivity) skill to instruct an agent to restructure the markup to make it editable.
+## 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 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 built-in media components, [`<Sequence>`](/docs/sequence),
+[`<Series.Sequence>`](/docs/series),
+[`<TransitionSeries.Sequence>`](/docs/transitions/transitionseries) and custom
+components.
+
+```tsx title="Separate source nodes"
+<Series>
+ <Series.Sequence name="Introduction" durationInFrames={90}>
+ <Introduction />
+ </Series.Sequence>
+ <Series.Sequence name="Demo" durationInFrames={150}>
+ <Demo />
+ </Series.Sequence>
+</Series>
+```
+
+A `.map()` or another programmatic loop would create both runtime sequences
+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 names,
+timing, ordering, deletion or duplication in the Studio.
+
## Make an HTML element interactive using `Interactive`
Every HTML and SVG element such as `<div>` can be turned interactive using `Interactive`:
diff --git a/packages/skills/skills/remotion-best-practices/SKILL.md b/packages/skills/skills/remotion-best-practices/SKILL.md
index 4d49a5abd3..57a0cc91af 100644
--- a/packages/skills/skills/remotion-best-practices/SKILL.md
+++ b/packages/skills/skills/remotion-best-practices/SKILL.md
@@ -79,7 +79,7 @@ The preview also has a more intuitive rendering interface, so consider using it
npx remotion render
```
-For more options, see [Rendering](../remotion-render/SKILL.md).
+For more options, see [Rendering](./remotion-render/SKILL.md).
For advanced rendering beyond simple `npx remotion render`, see: [Rendering Best Practices](./remotion-render/SKILL.md)
diff --git a/packages/skills/skills/remotion-create/SKILL.md b/packages/skills/skills/remotion-create/SKILL.md
index 247909d855..aaae0eec1c 100644
--- a/packages/skills/skills/remotion-create/SKILL.md
+++ b/packages/skills/skills/remotion-create/SKILL.md
@@ -43,9 +43,16 @@ npm i
Keep the scaffold and add React Markup.
Follow [Remotion React Markup Best Practices](../remotion-markup/SKILL.md) and [Video Layout Rules](video-layout.md) for video-first layout and text sizing guidance.
+## Is this a timeline of clips?
+
+If the video arranges multiple video or audio clips on a timeline, follow
+[Video editing](../remotion-markup/video-editing.md) before writing the
+timeline. Give every clip that should be edited independently its own authored
+JSX node.
+
## Is this a multi-scene video?
-If this is a video with multiple subsequence videos, follow guidance at [Multi-scene videos](../remotion-markup/multi-scene-video.md).
+If this is a video with multiple subsequent scenes, follow guidance at [Multi-scene videos](../remotion-markup/multi-scene-video.md).
## Interactivity Best Practices
diff --git a/packages/skills/skills/remotion-interactivity/SKILL.md b/packages/skills/skills/remotion-interactivity/SKILL.md
index 33cb245141..b3b35e9e85 100644
--- a/packages/skills/skills/remotion-interactivity/SKILL.md
+++ b/packages/skills/skills/remotion-interactivity/SKILL.md
@@ -13,6 +13,35 @@ By writing Remotion markup in a specific way, the Remotion Studio is able to rec
If the markup is too complex for the Studio to make it interactive, then the values become grayed out.
+## 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 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 built-in media components, `<Sequence>`, `<Series.Sequence>`,
+`<TransitionSeries.Sequence>` and custom components.
+
+For example, author an editable timeline like this:
+
+```tsx title="Separate source nodes"
+<Series>
+ <Series.Sequence name="Introduction" durationInFrames={90}>
+ <Introduction />
+ </Series.Sequence>
+ <Series.Sequence name="Demo" durationInFrames={150}>
+ <Demo />
+ </Series.Sequence>
+</Series>
+```
+
+A `.map()` or another programmatic loop would create both runtime sequences
+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 names,
+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`:
diff --git a/packages/skills/skills/remotion-markup/SKILL.md b/packages/skills/skills/remotion-markup/SKILL.md
index 8a03e07e15..5c73e5a98f 100644
--- a/packages/skills/skills/remotion-markup/SKILL.md
+++ b/packages/skills/skills/remotion-markup/SKILL.md
@@ -23,6 +23,12 @@ Use `Easing.bezier()` and `Easing.spring()` to customize timing.
Structure your markup according to [Remotion Interactivity Best Practices](../remotion-interactivity/SKILL.md)
+The Studio edits the JSX source node that created an item. Author every 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.
+
```tsx
import { useCurrentFrame, Easing, interpolate, Interactive } from "remotion";
@@ -110,6 +116,9 @@ 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
```tsx
@@ -265,10 +274,6 @@ See [embedding-videos.md](embedding-videos.md) for advanced knowledge about embe
See [audio.md](audio.md) for advanced audio features like trimming, volume, speed, pitch.
-## Video editing
-
-See [video-editing.md](video-editing.md) for structuring editable video timelines in Remotion Studio.
-
## Cropping
See [cropping.md](cropping.md) if needing to crop the visible rectangle of a component.
diff --git a/packages/skills/skills/remotion-markup/multi-scene-video.md b/packages/skills/skills/remotion-markup/multi-scene-video.md
index b6e87f472e..58d194880e 100644
--- a/packages/skills/skills/remotion-markup/multi-scene-video.md
+++ b/packages/skills/skills/remotion-markup/multi-scene-video.md
@@ -3,6 +3,13 @@
Put each substantial scene in its own component and file.
Register those components as [connected compositions](connected-compositions.md) so each scene has an editable Studio timeline.
+Treat the parent timeline as an editable document: Author every scene that
+should be edited independently as a separate `<Sequence>`, `<Series.Sequence>`
+or `<TransitionSeries.Sequence>` JSX node. Keep its `name` and
+`durationInFrames` inline so the node has its own source-editing target.
+Programmatic rendering is suitable only when the generated scenes are
+intentionally controlled as one source template.
+
Use `<TransitionSeries>` when the scenes may have transitions.
Install `@remotion/transitions` if it is missing.
Give each sequence an inline `durationInFrames` value so Studio can edit its timing.
diff --git a/packages/skills/skills/remotion-markup/video-editing.md b/packages/skills/skills/remotion-markup/video-editing.md
index a13b70de53..766a23eb11 100644
--- a/packages/skills/skills/remotion-markup/video-editing.md
+++ b/packages/skills/skills/remotion-markup/video-editing.md
@@ -1,90 +1,135 @@
-Remotion can be used for bare-bones video editing in the Studio. Choose the source structure based on the editing behavior you want:
+# Editable video timelines
-- Use independently positioned clips when moving or resizing one clip should not affect any other clip.
-- Use ripple editing when changing one clip's duration should reposition every clip after it.
+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.
-Keep every editable clip as its own authored JSX node. Do not generate editable clips with `.map()` or another programmatic loop.
+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 `<Series>` for consecutive clips when changing one clip's duration should
+ reposition every later clip.
+- Use `<TransitionSeries>` when consecutive clips also need transitions or
+ overlays.
## Independently positioned clips
-Place every `<Video>` directly in the composition and hardcode its timing props. `from={0}` may be omitted:
+Place every `<Video>` directly in the composition and hardcode its timing
+props. `from={0}` may be omitted:
```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}
/>
-<Video
- src="https://remotion.media/video.webm"
- trimBefore={58}
- from={234}
- durationInFrames={72}
-/>
-<Video
- src="https://remotion.media/video.mp4"
- trimBefore={180}
- from={306}
- durationInFrames={60}
-/>
```
- `from` is the clip's absolute start frame in its parent timeline.
- `durationInFrames` is how many frames the clip remains visible.
- `trimBefore` is how many source frames are skipped before playback begins.
-- Each `<Video>` must be a separate JSX node. Add a descriptive `name` when useful in the Studio timeline.
-- `from`, `durationInFrames`, and `trimBefore` must be hardcoded frame values. Do not compute them.
+- Keep `name`, `from`, `durationInFrames` and `trimBefore` inline on each clip.
- Import `<Video>` from `@remotion/media`.
-Moving or resizing one of these clips does not reposition later clips. Gaps and overlaps are therefore allowed.
+Moving or resizing one of these clips does not reposition later clips. Gaps and
+overlaps are therefore allowed.
-## Ripple editing with `TransitionSeries`
+## Consecutive clips with `Series`
-“Ripple editing” is the standard video-editing term for changing one clip and automatically shifting everything after it.
-In Remotion, a `<TransitionSeries>` provides this sequential, cascading timing model while also allowing transitions between clips.
+Use `<Series>` when the clips should remain adjacent and do not need
+transitions:
-Read [transitions.md](transitions.md) for transition types, timing options, installation instructions, and composition-duration calculation.
+```tsx
+<Series>
+ <Series.Sequence name="Opening" durationInFrames={78}>
+ <Video
+ src="https://remotion.media/video.mp4"
+ trimBefore={0}
+ />
+ </Series.Sequence>
+ <Series.Sequence name="Interview" durationInFrames={66}>
+ <Video
+ src="https://remotion.media/video.webm"
+ trimBefore={12}
+ />
+ </Series.Sequence>
+ <Series.Sequence name="Closing" durationInFrames={90}>
+ <Video
+ src="https://remotion.media/video.mp4"
+ trimBefore={72}
+ />
+ </Series.Sequence>
+</Series>
+```
-Keep the markup like this:
+The `<Series.Sequence>` is the editable clip row. Changing its
+`durationInFrames` repositions every later sequence. Do not set `from` on a
+`<Series.Sequence>`; the series calculates each start frame.
+
+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:
+
+```tsx
+<Series.Sequence name="Product demo" durationInFrames={150}>
+ <ProductDemo />
+</Series.Sequence>
+```
+
+## Consecutive clips with transitions
+
+Use `<TransitionSeries>` when the timeline needs transitions or overlays.
+Preserve the same one-source-node-per-clip structure:
```tsx
<TransitionSeries name="Video timeline">
- <TransitionSeries.Sequence name="Clip 1" durationInFrames={39}>
+ <TransitionSeries.Sequence name="Opening" durationInFrames={78}>
<Video
src="https://remotion.media/video.mp4"
trimBefore={0}
/>
</TransitionSeries.Sequence>
- <TransitionSeries.Sequence name="Clip 2" durationInFrames={45}>
+ <TransitionSeries.Transition
+ presentation={fade()}
+ timing={linearTiming({durationInFrames: 12})}
+ />
+ <TransitionSeries.Sequence name="Interview" durationInFrames={66}>
<Video
src="https://remotion.media/video.webm"
- trimBefore={8}
- />
- </TransitionSeries.Sequence>
- <TransitionSeries.Sequence name="Clip 3" durationInFrames={43}>
- <Video
- src="https://remotion.media/video.mp4"
- trimBefore={60}
+ trimBefore={12}
/>
</TransitionSeries.Sequence>
</TransitionSeries>
```
-- The `<TransitionSeries.Sequence>` is the editable clip row in the Studio timeline.
-- Dragging its right edge changes `durationInFrames` and repositions every later sequence.
-- Do not set `from` on `<TransitionSeries.Sequence>`; the series calculates each start frame.
-- Hardcode all numeric values.
-- Do not programmatically create multiple `<TransitionSeries.Sequence>` (no `.map`). Each instance must be hard-coded.
-- Import `<Video>` from `@remotion/media`. Import `<TransitionSeries>` from `@remotion/transitions`. If needing to install: `npx remotion add @remotion/media @remotion/transitions`
+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.
+
+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.