Skip to content

πŸŽ₯ Make videos programmatically with React

remotion: Inherit Sequence props in Track

Jonny Burger32da8cbe83fb
diff --git a/packages/core/src/Track.tsx b/packages/core/src/Track.tsx
index 41b145c794..88ece41657 100644
--- a/packages/core/src/Track.tsx
+++ b/packages/core/src/Track.tsx
@@ -1,27 +1,75 @@
import React, {useContext, useMemo, useState} from 'react';
import {addSequenceStackTraces} from './enable-sequence-stack-traces.js';
-import {sequenceSchema} from './interactivity-schema.js';
-import {SequenceWithoutSchema, type SequenceProps} from './Sequence.js';
+import {
+ sequenceSchema,
+ type InteractivitySchema,
+} from './interactivity-schema.js';
+import {
+ SequenceWithoutSchema,
+ type AbsoluteFillLayout,
+ type SequenceProps,
+} from './Sequence.js';
import {
ExperimentalTracksEnabledContext,
TimelineTrackContext,
} from './timeline-track-context.js';
import {withInteractivitySchema} from './with-interactivity-schema.js';
-export type TrackProps = Pick<
+type TrackContainerProps = AbsoluteFillLayout &
+ Pick<SequenceProps, 'cropLeft' | 'cropRight' | 'cropTop' | 'cropBottom'>;
+
+export type TrackProps = Omit<
SequenceProps,
- | 'children'
- | 'name'
- | 'from'
- | 'durationInFrames'
- | 'hidden'
- | 'showInTimeline'
->;
+ keyof TrackContainerProps | `_remotionInternal${string}` | 'outlineRef'
+> &
+ (
+ | (TrackContainerProps & {layout: 'absolute-fill'})
+ | ({layout?: 'none'} & {
+ [Key in Exclude<keyof TrackContainerProps, 'layout'>]?: never;
+ })
+ );
+
+// A packed row has no container bar to drag. Expose its linear timing in the
+// inspector, but keep looping and freezing as programmatic operations.
+const {freeze: _freeze, ...trackSequenceSchema} = sequenceSchema;
const trackSchema = {
- name: sequenceSchema.name,
- hidden: sequenceSchema.hidden,
-};
+ ...trackSequenceSchema,
+ from: {
+ ...sequenceSchema.from,
+ description: 'Start',
+ hiddenFromList: false,
+ keyframable: false,
+ },
+ durationInFrames: {
+ ...sequenceSchema.durationInFrames,
+ description: 'Duration',
+ hiddenFromList: false,
+ keyframable: false,
+ },
+ trimBefore: {
+ ...sequenceSchema.trimBefore,
+ description: 'Trim before',
+ hiddenFromList: false,
+ keyframable: false,
+ },
+ layout: {
+ ...sequenceSchema.layout,
+ default: 'none',
+ variants: {
+ ...sequenceSchema.layout.variants,
+ 'absolute-fill': {
+ ...sequenceSchema.layout.variants['absolute-fill'],
+ // Switching to layout="none" must remove the entire container
+ // props, including CSS properties without individual controls.
+ style: {type: 'hidden'},
+ className: {type: 'hidden'},
+ styleWhilePremounted: {type: 'hidden'},
+ styleWhilePostmounted: {type: 'hidden'},
+ },
+ },
+ },
+} as const satisfies InteractivitySchema;
// Series variants share the Track foundation while retaining their own
// Sequence props, layout defaults, and interactivity schemas.
@@ -41,6 +89,7 @@ export const TrackWithoutSchema: React.FC<SequenceProps> = ({
return (
<TimelineTrackContext.Provider value={value}>
<SequenceWithoutSchema
+ _remotionInternalDocumentationLink="https://www.remotion.dev/docs/track"
{...props}
name={name}
layout={layout}
diff --git a/packages/core/src/use-schema.ts b/packages/core/src/use-schema.ts
index 7c2f957d53..e5060c26e2 100644
--- a/packages/core/src/use-schema.ts
+++ b/packages/core/src/use-schema.ts
@@ -388,12 +388,20 @@ export const computeEffectiveSchemaValuesDotNotation = ({
merged[key] = value;
}
- for (const key of Object.keys(overrideValues)) {
- if (schema[key]?.type === 'enum') {
+ for (const [key, field] of Object.entries(schema)) {
+ if (
+ field.type === 'enum' &&
+ (key in overrideValues ||
+ // Inspector edits update the source status before hot reload supplies
+ // the new props. Remove the previous variant's props during this preview.
+ (propStatus?.[key]?.status === 'static' &&
+ (merged[key] ?? field.default) !==
+ (currentValue[key] ?? field.default)))
+ ) {
const propsToDeleteForKey = findPropsToDelete({
schema,
key,
- value: merged[key],
+ value: merged[key] ?? field.default,
});
for (const propToDelete of propsToDeleteForKey) {
propsToDelete.add(propToDelete);
diff --git a/packages/docs/docs/track.mdx b/packages/docs/docs/track.mdx
new file mode 100644
index 0000000000..ace313f706
--- /dev/null
+++ b/packages/docs/docs/track.mdx
@@ -0,0 +1,151 @@
+---
+image: /generated/articles-docs-track.png
+title: '<Track>'
+crumb: 'remotion'
+---
+
+# &lt;Track&gt;<AvailableFrom v="4.0.534" />
+
+`<Track>` applies [`<Sequence>`](/docs/sequence) timing to its children and groups their clips on one Studio timeline row.
+Enable [`Config.setExperimentalTracksEnabled(true)`](/docs/config#setexperimentaltracksenabled) to use the packed timeline presentation.
+
+```tsx twoslash title="MyComposition.tsx"
+import {Sequence, Track} from 'remotion';
+
+export const MyComposition = () => (
+ <Track name="Scenes" from={30} trimBefore={15} playbackRate={2} durationInFrames={90}>
+ <Sequence durationInFrames={45}>
+ <div>Intro</div>
+ </Sequence>
+ <Sequence from={45} durationInFrames={90}>
+ <div>Main scene</div>
+ </Sequence>
+ </Track>
+);
+```
+
+The track is visible on composition frames 30–74. Its children start at local frame 15 and advance twice as fast: the intro ends at composition frame 45, and the main scene is clipped at frame 75.
+
+## Props
+
+### `children?`
+
+Content to group. Descendants that create timeline clips share the track row. Nested tracks create their own rows.
+
+### `name?`
+
+The track label. Defaults to `"Track"`.
+
+### `from?`
+
+The start frame in the parent timeline. Defaults to `0`. See [`<Sequence from>`](/docs/sequence#from).
+
+### `durationInFrames?`
+
+The number of child frames to display. Defaults to the remaining parent duration. See [`<Sequence durationInFrames>`](/docs/sequence#durationinframes).
+
+### `hidden?`
+
+Hide the track's content while keeping its timeline header. Defaults to `false`.
+
+### `showInTimeline?`
+
+Show the track and its children in the packed timeline. Defaults to `true`.
+
+## Inherited props<AvailableFrom v="4.0.535" />
+
+These props use the same behavior as [`<Sequence>`](/docs/sequence).
+
+### `trimBefore?`
+
+Advance the child clock without moving the track's start. Defaults to `0`. See [`trimBefore`](/docs/sequence#trimbefore).
+
+### `playbackRate?`
+
+Scale the child clock and the duration of its clips. Defaults to `1`. See [`playbackRate`](/docs/sequence#playbackrate).
+
+### `loop?`
+
+Repeat the selected child range until the parent ends. Defaults to `false` and requires a finite `durationInFrames`. See [`loop`](/docs/sequence#loop).
+
+### `freeze?`
+
+Hold the children at a local frame. Defaults to `null`. See [`freeze`](/docs/sequence#freeze).
+
+### `layout?`
+
+Defaults to `"none"`, so the track adds no container element. Set `layout="absolute-fill"` to create a container for styling, cropping, premounting, or postmounting.
+
+### `style?`
+
+Styles for the container. Requires `layout="absolute-fill"`. See [`style`](/docs/sequence#style).
+
+### `className?`
+
+A CSS class for the container. Requires `layout="absolute-fill"`.
+
+### `width?`
+
+Override the width returned by [`useVideoConfig()`](/docs/use-video-config). Also sets the container width when `layout="absolute-fill"`.
+
+### `height?`
+
+Override the height returned by [`useVideoConfig()`](/docs/use-video-config). Also sets the container height when `layout="absolute-fill"`.
+
+### `cropLeft?`
+
+Crop the left edge as a fraction between `0` and `1`. Defaults to `0` and requires `layout="absolute-fill"`. See [cropping](/docs/sequence#cropleft).
+
+### `cropRight?`
+
+Crop the right edge. Same range, default, and layout requirement as `cropLeft`.
+
+### `cropTop?`
+
+Crop the top edge. Same range, default, and layout requirement as `cropLeft`.
+
+### `cropBottom?`
+
+Crop the bottom edge. Same range, default, and layout requirement as `cropLeft`.
+
+### `premountFor?`
+
+Mount the children before the track starts. Requires `layout="absolute-fill"`. See [`premountFor`](/docs/sequence#premountfor).
+
+### `postmountFor?`
+
+Keep the children mounted after the track ends. Defaults to `0` and requires `layout="absolute-fill"`. See [`postmountFor`](/docs/sequence#postmountfor).
+
+### `styleWhilePremounted?`
+
+Override container styles while premounted. Requires `layout="absolute-fill"`. See [`styleWhilePremounted`](/docs/sequence#stylewhilepremounted).
+
+### `styleWhilePostmounted?`
+
+Override container styles while postmounted. Requires `layout="absolute-fill"`. See [`styleWhilePostmounted`](/docs/sequence#stylewhilepostmounted).
+
+### `controls?`
+
+Pass controls from [`Interactive.withSchema()`](/docs/interactive-with-schema) when using a track inside a custom interactive component.
+
+## Studio interactions<AvailableFrom v="4.0.535" />
+
+Select the track header to edit its start, duration, trim, playback rate, and layout in the inspector. With `layout="absolute-fill"`, the existing Sequence controls for transforms, opacity, background, borders, cropping, and premounting are available.
+
+Switching to `layout="none"` removes the container's styles, class name, crop, and mounting props. Undo restores them.
+
+Child clips can be moved and trimmed using their own timeline handles. The track container's timing is edited in the inspector; splitting the container is unavailable.
+
+Set `loop` and `freeze` in code. When either is active, the packed timeline displays one block for the track and hides its descendant rows. A repeated or frozen child does not have a single advancing interval that a packed clip could accurately represent.
+
+`className`, `width`, `height`, `postmountFor`, and the styles applied during premounting or postmounting remain code-only. Packed rows do not display premount bars.
+
+## Compatibility
+
+<CompatibilityTable chrome firefox safari player studio clientSideRendering serverSideRendering hideServers />
+
+## See also
+
+- [`<Sequence>`](/docs/sequence)
+- [`<Series>`](/docs/series)
+- [Experimental timeline tracks](/docs/options/experimental-tracks)
diff --git a/packages/docs/sidebars.ts b/packages/docs/sidebars.ts
index 2d51feafea..d0877dd107 100644
--- a/packages/docs/sidebars.ts
+++ b/packages/docs/sidebars.ts
@@ -184,6 +184,7 @@ const sidebars: SidebarsConfig = {
'solid',
'staticfile',
'still',
+ 'track',
'use-buffer-state',
'use-current-frame',
'use-current-scale',
diff --git a/packages/docs/src/data/articles.ts b/packages/docs/src/data/articles.ts
index f0789111bf..bf028e06ca 100644
--- a/packages/docs/src/data/articles.ts
+++ b/packages/docs/src/data/articles.ts
@@ -11019,4 +11019,13 @@ export const articles = [
noAi: false,
slug: 'prompts/submit',
},
+ {
+ id: 'track',
+ title: '<Track>',
+ relativePath: 'docs/track.mdx',
+ compId: 'articles-docs-track',
+ crumb: 'remotion',
+ noAi: false,
+ slug: 'track',
+ },
];
diff --git a/packages/docs/static/generated/articles-docs-track.png b/packages/docs/static/generated/articles-docs-track.png
new file mode 100644
index 0000000000..779e2ede48
Binary files /dev/null and b/packages/docs/static/generated/articles-docs-track.png differ
diff --git a/packages/example/src/TrackSequenceProps.tsx b/packages/example/src/TrackSequenceProps.tsx
index d4260bf927..ce283082d0 100644
--- a/packages/example/src/TrackSequenceProps.tsx
+++ b/packages/example/src/TrackSequenceProps.tsx
@@ -17,11 +17,11 @@ export const TrackSequenceProps: React.FC = () => {
style={{
position: 'absolute',
inset: 0,
- padding: 48,
+ padding: 32,
backgroundColor: '#141b24',
color: '#eef3fa',
fontFamily: 'Arial, sans-serif',
- fontSize: 24,
+ fontSize: 20,
}}
>
<div style={{fontSize: 36, fontWeight: 700, marginBottom: 16}}>
@@ -29,12 +29,12 @@ export const TrackSequenceProps: React.FC = () => {
</div>
<FrameClock label="Composition frame" />
<div style={{fontSize: 20, color: '#acb8c8', marginTop: 16}}>
- Track: from 30, duration 90. Visible on composition frames 30–119.
+ Track: from 30, trim 15, duration 90, speed 2. Visible on frames 30–74.
</div>
<div
style={{
position: 'relative',
- height: 280,
+ height: 260,
marginTop: 28,
border: '1px solid #445164',
borderRadius: 12,
@@ -42,43 +42,103 @@ export const TrackSequenceProps: React.FC = () => {
}}
>
<div style={{padding: 28, color: '#acb8c8'}}>
- Track content is absent before frame 30 and from frame 120 onward.
+ Premounted on frames 15–29, postmounted on frames 75–89.
</div>
- <Track name="Timed Track" from={30} durationInFrames={90}>
- <div
- style={{
- position: 'absolute',
- inset: 0,
- padding: 28,
- backgroundColor: '#243345',
- }}
- >
- <FrameClock label="Track local frame" />
- <div style={{marginTop: 24}}>
- <Sequence name="Child A" durationInFrames={45} layout="none">
- <div style={{color: '#7de1c0', marginBottom: 12}}>
- Child A β€” Track frames 0–44
- </div>
- <FrameClock label="Child A local frame" />
- </Sequence>
- <Sequence
- name="Child B clipped by Track"
- from={45}
- durationInFrames={90}
- layout="none"
- >
- <div style={{color: '#e8bf7d', marginBottom: 12}}>
- Child B β€” starts at Track frame 45
- </div>
- <FrameClock label="Child B local frame" />
- <div style={{fontSize: 20, marginTop: 16}}>
- Its 90-frame duration is clipped when the Track ends.
- </div>
- </Sequence>
- </div>
+ <Track
+ name="Timed Track"
+ from={30}
+ trimBefore={15}
+ playbackRate={2}
+ durationInFrames={90}
+ layout="absolute-fill"
+ className="track-sequence-container"
+ premountFor={15}
+ postmountFor={15}
+ style={{display: 'block', padding: 28, backgroundColor: '#243345'}}
+ styleWhilePremounted={{opacity: 0.15}}
+ styleWhilePostmounted={{opacity: 0.15}}
+ >
+ <FrameClock label="Track local frame" />
+ <div style={{marginTop: 24}}>
+ <Sequence name="Child A" durationInFrames={45} layout="none">
+ <div style={{color: '#7de1c0', marginBottom: 12}}>
+ Child A β€” composition frames 30–44
+ </div>
+ <FrameClock label="Child A local frame" />
+ </Sequence>
+ <Sequence
+ name="Child B clipped by Track"
+ from={45}
+ durationInFrames={90}
+ layout="none"
+ >
+ <div style={{color: '#e8bf7d', marginBottom: 12}}>
+ Child B β€” composition frames 45–74
+ </div>
+ <FrameClock label="Child B local frame" />
+ <div style={{fontSize: 20, marginTop: 16}}>
+ Its 90-frame duration is clipped when the Track ends.
+ </div>
+ </Sequence>
</div>
</Track>
</div>
+ <div style={{display: 'flex', gap: 20, marginTop: 20}}>
+ <div style={{position: 'relative', width: 590, height: 140}}>
+ <Track
+ name="Looped Track (code only)"
+ from={15}
+ trimBefore={10}
+ durationInFrames={30}
+ playbackRate={2}
+ loop
+ layout="absolute-fill"
+ width={590}
+ height={140}
+ cropRight={0.02}
+ style={{display: 'block', padding: 20, backgroundColor: '#254a42'}}
+ >
+ <FrameClock label="Looped Track frame" />
+ <Sequence
+ name="Loop first half"
+ durationInFrames={25}
+ layout="none"
+ >
+ First half (local frames 10–24)
+ </Sequence>
+ <Sequence
+ name="Loop second half"
+ from={25}
+ durationInFrames={15}
+ layout="none"
+ >
+ Second half (local frames 25–39)
+ </Sequence>
+ </Track>
+ </div>
+ <div style={{position: 'relative', width: 590, height: 140}}>
+ <Track
+ name="Frozen Track (code only)"
+ from={15}
+ durationInFrames={90}
+ freeze={20}
+ layout="absolute-fill"
+ style={{display: 'block', padding: 20, backgroundColor: '#4a3c25'}}
+ >
+ <FrameClock label="Frozen Track frame" />
+ <Sequence
+ name="Frozen visible child"
+ durationInFrames={30}
+ layout="none"
+ >
+ Held inside the first child at frame 20.
+ </Sequence>
+ <Sequence name="Frozen inactive child" from={30} layout="none">
+ This child should stay hidden.
+ </Sequence>
+ </Track>
+ </div>
+ </div>
<div style={{marginTop: 28, fontSize: 20, color: '#acb8c8'}}>
The hidden Track keeps its timeline header. Its red content stays
hidden.
diff --git a/packages/studio/src/components/Timeline/TimelineSequence.tsx b/packages/studio/src/components/Timeline/TimelineSequence.tsx
index 1ac49a5fcd..807958e292 100644
--- a/packages/studio/src/components/Timeline/TimelineSequence.tsx
+++ b/packages/studio/src/components/Timeline/TimelineSequence.tsx
@@ -51,6 +51,7 @@ import {
} from '../../helpers/timeline-layout';
import {useMediaMetadata} from '../../helpers/use-media-metadata';
import {useRuntimeValueSelector} from '../../helpers/use-runtime-values';
+import {SnowflakeIcon} from '../../icons/snowflake';
import {SetSelectedModalContext} from '../../state/modals';
import {ActionTooltip} from '../ActionTooltip';
import {AudioWaveform} from '../AudioWaveform';
@@ -555,7 +556,11 @@ const TimelineSequenceBar: React.FC<{
/>
) : null}
<ActionTooltip
- label={s.displayName}
+ label={
+ s.timelineTrack.role === 'track' && frozenFrame !== null
+ ? `${s.displayName} (frozen at frame ${frozenFrame})`
+ : s.displayName
+ }
shortcut={null}
delay={250}
dismissOnClick
@@ -580,6 +585,18 @@ const TimelineSequenceBar: React.FC<{
'linear-gradient(to right, black calc(100% - 5px), transparent)',
}}
>
+ {s.timelineTrack.role === 'track' && frozenFrame !== null ? (
+ <SnowflakeIcon
+ aria-label={`Frozen at frame ${frozenFrame}`}
+ color={getTimelineColor(false, false)}
+ style={{
+ width: 12,
+ height: 12,
+ marginRight: 4,
+ verticalAlign: 'middle',
+ }}
+ />
+ ) : null}
{s.timelineTrack.role === 'overlay' ? 'Overlay' : s.displayName}
</span>
</ActionTooltip>
diff --git a/packages/studio/src/components/Timeline/TimelineSequenceRightEdgeDragHandle.tsx b/packages/studio/src/components/Timeline/TimelineSequenceRightEdgeDragHandle.tsx
index effae3eabf..ac54446910 100644
--- a/packages/studio/src/components/Timeline/TimelineSequenceRightEdgeDragHandle.tsx
+++ b/packages/studio/src/components/Timeline/TimelineSequenceRightEdgeDragHandle.tsx
@@ -432,7 +432,7 @@ const getMinimumSequenceDuration = ({
export const isTimelineSequenceDurationDraggable = (sequence: TSequence) => {
const isInteractiveCascadingSequence = isCascadingSequence(sequence);
- if (sequence.loopDisplay) {
+ if (sequence.loopDisplay || sequence.timelineTrack?.role === 'track') {
return false;
}
@@ -456,6 +456,7 @@ export const canResizeTimelineSequenceDuration = ({
export const isTimelineSequenceLeftEdgeDraggable = (sequence: TSequence) => {
return (
+ sequence.timelineTrack?.role !== 'track' &&
(!sequence.isInsideSeries || isCascadingSequence(sequence)) &&
Boolean(sequence.controls) &&
(sequence.type === 'sequence' ||
@@ -516,7 +517,11 @@ export const getTimelineSequenceEndFieldValue = ({
};
const isFromDraggableSequence = (sequence: TSequence) => {
- return !sequence.isInsideSeries && Boolean(sequence.controls);
+ return (
+ !sequence.isInsideSeries &&
+ sequence.timelineTrack?.role !== 'track' &&
+ Boolean(sequence.controls)
+ );
};
export const getTimelineSequenceDurationDragValue = ({
diff --git a/packages/studio/src/components/Timeline/split-selected-timeline-item.ts b/packages/studio/src/components/Timeline/split-selected-timeline-item.ts
index e52865fc8b..48286600ee 100644
--- a/packages/studio/src/components/Timeline/split-selected-timeline-item.ts
+++ b/packages/studio/src/components/Timeline/split-selected-timeline-item.ts
@@ -82,6 +82,16 @@ export const getTimelineSequenceSplitEligibility = ({
};
}
+ if (
+ sequence.timelineTrack?.role === 'track' ||
+ sequence.controls?.componentIdentity === 'dev.remotion.remotion.Track'
+ ) {
+ return {
+ canSplit: false,
+ reason: 'Track containers cannot be split from the Studio',
+ };
+ }
+
if (!Number.isInteger(splitFrame)) {
return {
canSplit: false,
diff --git a/packages/studio/src/components/Timeline/timeline-track-groups.ts b/packages/studio/src/components/Timeline/timeline-track-groups.ts
index 17cce072eb..b54b3710c5 100644
--- a/packages/studio/src/components/Timeline/timeline-track-groups.ts
+++ b/packages/studio/src/components/Timeline/timeline-track-groups.ts
@@ -39,8 +39,12 @@ export const filterTimelineTrackContents = (
if (ancestor.timelineTrack) {
if (
ancestor.timelineTrack.role === 'track' &&
- !ancestor.showInTimeline
+ (!ancestor.showInTimeline ||
+ ancestor.loopDisplay !== undefined ||
+ ancestor.frozenFrame !== null)
) {
+ // Repeated or frozen child clocks cannot be represented by one
+ // advancing clip interval. Show the transformed container instead.
return [];
}
@@ -129,6 +133,14 @@ export const getTimelineDisplayRows = (
if (!group) {
rows.push({track, items: null, auxiliaryRows: []});
} else if (group.role === 'track') {
+ if (
+ track.sequence.loopDisplay !== undefined ||
+ track.sequence.frozenFrame !== null
+ ) {
+ rows.push({track, items: [track], auxiliaryRows: []});
+ continue;
+ }
+
const items = groupedItems.get(group.id) ?? [];
const auxiliaryRows: TimelineTrackWithDisplayGroup[][] = [];
for (const item of items) {
diff --git a/packages/studio/src/components/Timeline/use-sequence-freeze-frame-menu-item.ts b/packages/studio/src/components/Timeline/use-sequence-freeze-frame-menu-item.ts
index fa2e6fb249..0d51e0bb73 100644
--- a/packages/studio/src/components/Timeline/use-sequence-freeze-frame-menu-item.ts
+++ b/packages/studio/src/components/Timeline/use-sequence-freeze-frame-menu-item.ts
@@ -7,7 +7,11 @@ import type {ComboboxValue} from '../NewComposition/ComboBox';
import {saveSequenceProps, type SetPropStatuses} from './save-sequence-prop';
export const shouldShowFreezeFrameMenuItem = (sequence: TSequence): boolean => {
- return sequence.type !== 'audio';
+ return (
+ sequence.type !== 'audio' &&
+ sequence.timelineTrack?.role !== 'track' &&
+ sequence.controls?.componentIdentity !== 'dev.remotion.remotion.Track'
+ );
};
export const isSequenceVisibleAtTimelinePosition = ({