🎥 Make videos programmatically with React
Docs: Explain reusable and connected compositions
JonnyBurgercd3c424fa10d
diff --git a/packages/brand/src/DocsAnimations/ConnectedCompositions.tsx b/packages/brand/src/DocsAnimations/ConnectedCompositions.tsxnew file mode 100644index 0000000000..43c0f05c61--- /dev/null+++ b/packages/brand/src/DocsAnimations/ConnectedCompositions.tsx@@ -0,0 +1,68 @@+import type {ReactNode} from 'react';+import {Composition, Interactive, useVideoConfig} from 'remotion';++type TitleProps = {+ readonly children: ReactNode;+ readonly color: string;+};++const TitleInner = ({children, color}: TitleProps) => (+ <div+ style={{+ fontFamily: 'Arial, sans-serif',+ fontSize: 80,+ textAlign: 'center',+ color,+ }}+ >+ {children}+ </div>+);++export const Title = Interactive.withSchema({+ Component: TitleInner,+ componentName: 'Title',+ schema: {+ ...Interactive.childrenSchema,+ color: {type: 'color', default: '#0b84f3', description: 'Text color'},+ },+ wrapInSequence: true,+ layout: 'absolute-fill',+});++const MyVideo = () => {+ const {fps} = useVideoConfig();++ return (+ <>+ <Title color="#0b84f3" durationInFrames={2 * fps}>+ Hello+ </Title>+ <Title color="#9b5de5" from={2 * fps} durationInFrames={2 * fps}>+ World+ </Title>+ </>+ );+};++export const ConnectedCompositionExamples = () => (+ <>+ <Composition+ id="MyVideo"+ component={MyVideo}+ width={1280}+ height={720}+ fps={30}+ durationInFrames={120}+ />+ <Composition+ id="Title"+ component={Title}+ width={1280}+ height={720}+ fps={30}+ durationInFrames={60}+ defaultProps={{children: 'Hello World!', color: '#0b84f3'}}+ />+ </>+);diff --git a/packages/brand/src/DocsAnimations/Root.tsx b/packages/brand/src/DocsAnimations/Root.tsxindex 21bf7e5fc7..64ad62ab3e 100644--- a/packages/brand/src/DocsAnimations/Root.tsx+++ b/packages/brand/src/DocsAnimations/Root.tsx@@ -3,6 +3,7 @@ import {AnimatingPropertiesGraph,AnimatingPropertiesText,} from './AnimatingProperties';+import {ConnectedCompositionExamples} from './ConnectedCompositions';const transparentVideoMetadata = () => ({defaultCodec: 'vp9' as const,@@ -13,6 +14,9 @@ const transparentVideoMetadata = () => ({export const DocsAnimationCompositions = () => {return (<Folder name="DocsAnimations">+ <Folder name="ConnectedCompositions">+ <ConnectedCompositionExamples />+ </Folder><Compositionid="AnimatingPropertiesGraphLight"component={AnimatingPropertiesGraph}diff --git a/packages/brand/src/DocsAnimations/connected-compositions.ts b/packages/brand/src/DocsAnimations/connected-compositions.tsnew file mode 100644index 0000000000..e1a40c103c--- /dev/null+++ b/packages/brand/src/DocsAnimations/connected-compositions.ts@@ -0,0 +1,4 @@+import {registerRoot} from 'remotion';+import {ConnectedCompositionExamples} from './ConnectedCompositions';++registerRoot(ConnectedCompositionExamples);diff --git a/packages/docs/docs/sequences.mdx b/packages/docs/docs/sequences.mdxindex 7ad3f7b33a..1c1537b369 100644--- a/packages/docs/docs/sequences.mdx+++ b/packages/docs/docs/sequences.mdx@@ -6,77 +6,250 @@ sidebar_label: Reuse componentscrumb: 'The power of React'----```twoslash include example-import {interpolate, useCurrentFrame} from 'remotion'--const Title: React.FC<{title: string}> = ({title}) => {- const frame = useCurrentFrame()- const opacity = interpolate(frame, [0, 20], [0, 1], {extrapolateRight: 'clamp'})-- return (- <div style={{opacity, textAlign: "center", fontSize: "7em"}}>{title}</div>- );-}-// - Title+React is perfect for reusing, parametrizing, and composing components with multiple levels of depth.+You can use the regular React primitives for this.++Start with a component that accepts `children` and a `color`. Reuse it with different props:++```tsx twoslash title="MyVideo.tsx"+import type {CSSProperties, ReactNode} from 'react';++type TitleProps = {+ readonly children: ReactNode;+ readonly color: string;+ readonly style?: CSSProperties;+};++const Title = ({children, color, style}: TitleProps) => (+ <div+ style={{+ fontFamily: 'Arial, sans-serif',+ fontSize: 80,+ textAlign: 'center',+ color,+ ...style,+ }}+ >+ {children}+ </div>+);++export const MyVideo = () => (+ <>+ <Title color="#0b84f3">Hello</Title>+ <Title color="#9b5de5">World</Title>+ </>+);```-React components allow us to encapsulate video logic and reuse the same visuals multiple times.+Both titles are visible at the same time. Changing the component updates every instance; changing one instance's props only affects that instance.-Consider a title - to make it reusable, factor it out into its own component:+## Add timing primitives-```tsx twoslash title="MyComposition.tsx"-import {interpolate, useCurrentFrame} from 'remotion';+Use [`Interactive.withSchema()`](/docs/interactive-with-schema) with `wrapInSequence: true` to add [timing props](/docs/timing).+Rename the function to `TitleInner`, and export the wrapper:-const Title: React.FC<{title: string}> = ({title}) => {- const frame = useCurrentFrame();- const opacity = interpolate(frame, [0, 20], [0, 1], {- extrapolateRight: 'clamp',- });+```twoslash include timed-title+import type {CSSProperties, ReactNode} from 'react';+import {Interactive} from 'remotion';- return (- <div style={{opacity, textAlign: 'center', fontSize: '7em'}}>{title}</div>- );+type TitleProps = {+ readonly children: ReactNode;+ readonly color: string;+ readonly style?: CSSProperties;};+const TitleInner = ({children, color, style}: TitleProps) => (+ <div+ style={{+ fontFamily: 'Arial, sans-serif',+ fontSize: 80,+ textAlign: 'center',+ color,+ ...style,+ }}+ >+ {children}+ </div>+);+// - inner++export const Title = Interactive.withSchema({+ Component: TitleInner,+ componentName: 'Title',+ schema: {},+ wrapInSequence: true,+});+```++```tsx twoslash title="Title.tsx"+// @include: timed-title-inner+// ---cut---+export const Title = Interactive.withSchema({+ Component: TitleInner,+ componentName: 'Title',+ schema: {},+ wrapInSequence: true,+});+```++Forward the `style` prop to the outer `<div>` as shown in the first example.+The wrapper uses it to apply transforms and other visual edits.++You can now put the titles on the timeline by passing `from` and `durationInFrames` directly:++```tsx twoslash title="MyVideo.tsx"+// @filename: Title.tsx+// @include: timed-title+// @filename: MyVideo.tsx+// ---cut---+import {useVideoConfig} from 'remotion';+import {Title} from './Title';+export const MyVideo = () => {+ const {fps} = useVideoConfig();+return (<>- <Title title="Hello World" />+ <Title color="#0b84f3" durationInFrames={2 * fps}>+ Hello+ </Title>+ <Title color="#9b5de5" from={2 * fps} durationInFrames={2 * fps}>+ World+ </Title></>);};```-To render multiple instances of the title, duplicate the `<Title>` component.+## Add parameterization interactivity-You can also use the [`<Sequence>`](/docs/sequence) component to limit the duration of the first title and time-shift the appearance of the second title.+The props already let you parameterize the component in code.+Describe them in the `schema` to make them editable in the [Remotion Studio](/docs/studio):-```tsx twoslash-// @include: example-Title+```tsx twoslash title="Title.tsx"+// @include: timed-title-inner// ---cut----import {Sequence} from 'remotion';+export const Title = Interactive.withSchema({+ Component: TitleInner,+ componentName: 'Title',+ schema: {+ ...Interactive.childrenSchema,+ color: {type: 'color', default: '#0b84f3', description: 'Text color'},+ },+ wrapInSequence: true,+});+```-export const MyVideo = () => {- return (- <>- <Sequence durationInFrames={40}>- <Title title="Hello" />- </Sequence>- <Sequence from={40}>- <Title title="World" />- </Sequence>- </>- );+`Interactive.childrenSchema` adds an editable text field, and `color` adds a color picker in the [Studio](/docs/studio).++## Connected compositions++If a component is also registered as a [composition](/docs/idea#compositions), it gets special treatment in the Remotion [Studio](/docs/studio).++Instead of repeating all children, only a single item is being displayed.+You can double-click an item to jump to the composition and edit the children on the composition's own timeline.++<img src="/img/connected-compositions.webp" alt="Two Title tracks in the Studio timeline, each with the connected composition icon next to its name." width={512} height={58} />++If you are familiar with After Effects, this is a similar concept to "Pre-Composing" layers, except that in Remotion, they are also parameterizable.++To set up a connected composition, we recommend you base it off a `absolute-fill` layout:++```twoslash include connected-title+import type {ReactNode} from 'react';+import {Interactive} from 'remotion';++type TitleProps = {+ readonly children: ReactNode;+ readonly color: string;};++const TitleInner = ({children, color}: TitleProps) => (+ <div+ style={{+ fontFamily: 'Arial, sans-serif',+ fontSize: 80,+ textAlign: 'center',+ color,+ }}+ >+ {children}+ </div>+);++export const Title = Interactive.withSchema({+ Component: TitleInner,+ componentName: 'Title',+ schema: {+ ...Interactive.childrenSchema,+ color: {type: 'color', default: '#0b84f3', description: 'Text color'},+ },+ wrapInSequence: true,+ layout: 'absolute-fill',+});```-You should see two titles appearing after each other.+```tsx twoslash title="Title.tsx"+import type {ReactNode} from 'react';+import {Interactive} from 'remotion';-Note that the value of [`useCurrentFrame()`](/docs/use-current-frame) has been shifted in the second instance, so that it returns `0` only when the absolute time is `40`. Before that, the sequence was not mounted at all.+type TitleProps = {+ readonly children: ReactNode;+ readonly color: string;+};++const TitleInner = ({children, color}: TitleProps) => (+ <div+ style={{+ fontFamily: 'Arial, sans-serif',+ fontSize: 80,+ textAlign: 'center',+ color,+ }}+ >+ {children}+ </div>+);++export const Title = Interactive.withSchema({+ Component: TitleInner,+ componentName: 'Title',+ schema: {+ ...Interactive.childrenSchema,+ color: {type: 'color', default: '#0b84f3', description: 'Text color'},+ },+ wrapInSequence: true,+ layout: 'absolute-fill',+});+```++and add a [`<Composition>`](/docs/composition) registering your component:++```tsx twoslash title="Root.tsx"+// @filename: Title.tsx+// @include: connected-title+// @filename: Root.tsx+// ---cut---+import {Composition} from 'remotion';+import {Title} from './Title';++<Composition+ id="Title"+ component={Title}+ width={1280}+ height={720}+ fps={30}+ durationInFrames={60}+ defaultProps={{children: 'Hello World!', color: '#0b84f3'}}+/>+```-Sequences by default are absolutely positioned - you can use [`layout="none"`](/docs/sequence#layout) to make them render like a regular `<div>`.+You need to set a fixed width, height, and frame rate for the composition, even if it is different than the parent video's settings.## See also-- [`<Sequence>` component](/docs/sequence)-- [How do I combine compositions?](/docs/miscellaneous/snippets/combine-compositions)+- [`Interactive.withSchema()`](/docs/interactive-with-schema)+- [`InteractivitySchema`](/docs/interactivity-schema)+- [Timing and trimming](/docs/timing)+- [Interactivity best practices](/docs/studio/interactivity-best-practices)diff --git a/packages/docs/static/img/connected-compositions.webp b/packages/docs/static/img/connected-compositions.webpnew file mode 100644index 0000000000..a20e60dabeBinary files /dev/null and b/packages/docs/static/img/connected-compositions.webp differ