Skip to content

🎥 Make videos programmatically with React

20.7 KB
Raw Blame
import React, {forwardRef, useCallback, useContext} from 'react';
import {resolveComponentIdentity} from './component-identity.js';
import type {
	JsxComponentIdentity,
	SequenceControls,
} from './CompositionManager.js';
import {CompositionManager} from './CompositionManagerContext.js';
import {addSequenceStackTraces} from './enable-sequence-stack-traces.js';
import {Freeze} from './freeze.js';
import {
	backgroundSchema,
	baseSchema,
	borderRadiusSchema,
	borderSchema,
	captionsSchema,
	childrenSchema,
	cropSchema,
	premountSchema,
	sequenceSchema,
	svgPaintSchema,
	svgStrokeSchema,
	textSchema,
	transformSchema,
	type InteractivitySchema,
} from './interactivity-schema.js';
import {resolveSequenceDuration} from './resolve-sequence-duration.js';
import type {AbsoluteFillLayout, SequenceProps} from './Sequence.js';
import {Sequence, SequenceWithoutSchema} from './Sequence.js';
import {useCropStyle} from './use-crop-style.js';
import {usePremounting} from './use-premounting.js';
import {
	withInteractivitySchema,
	type WithInteractivitySchemaOptions,
} from './with-interactivity-schema.js';

type InteractiveHtmlTag =
	| 'a'
	| 'article'
	| 'aside'
	| 'button'
	| 'code'
	| 'div'
	| 'em'
	| 'footer'
	| 'h1'
	| 'h2'
	| 'h3'
	| 'h4'
	| 'h5'
	| 'h6'
	| 'header'
	| 'label'
	| 'li'
	| 'main'
	| 'nav'
	| 'ol'
	| 'p'
	| 'pre'
	| 'section'
	| 'small'
	| 'span'
	| 'strong'
	| 'ul';

type InteractiveSvgTag =
	| 'circle'
	| 'ellipse'
	| 'g'
	| 'line'
	| 'path'
	| 'rect'
	| 'svg'
	| 'text';

type InteractiveTag = InteractiveHtmlTag | InteractiveSvgTag;

type ElementForTag<Tag extends InteractiveTag> =
	Tag extends keyof HTMLElementTagNameMap
		? HTMLElementTagNameMap[Tag]
		: Tag extends keyof SVGElementTagNameMap
			? SVGElementTagNameMap[Tag]
			: Element;

export type InteractiveBaseProps = Pick<
	SequenceProps,
	| 'durationInFrames'
	| 'from'
	| 'trimBefore'
	| 'playbackRate'
	| 'loop'
	| 'freeze'
	| 'hidden'
	| 'name'
	| 'showInTimeline'
>;

export type InteractiveTransformProps = Pick<AbsoluteFillLayout, 'style'>;

export type InteractiveCropProps = Pick<
	SequenceProps,
	'cropLeft' | 'cropRight' | 'cropTop' | 'cropBottom'
>;

export type InteractivePremountProps = Pick<
	AbsoluteFillLayout,
	| 'premountFor'
	| 'postmountFor'
	| 'styleWhilePremounted'
	| 'styleWhilePostmounted'
>;

type InteractiveManagedProps = InteractiveBaseProps &
	InteractiveCropProps &
	InteractivePremountProps;

type InteractiveElementProps<Tag extends InteractiveTag> = Omit<
	React.ComponentPropsWithoutRef<Tag>,
	keyof InteractiveManagedProps
> &
	InteractiveManagedProps;

type InteractiveElementComponent<Tag extends InteractiveTag> =
	React.ComponentType<
		InteractiveElementProps<Tag> & React.RefAttributes<ElementForTag<Tag>>
	>;

type RemotionComponentIdentityPackage = 'remotion' | `@remotion/${string}`;

const sourcePathToIdentityPrefix = (
	packageName: RemotionComponentIdentityPackage,
): string => {
	if (packageName === 'remotion') {
		return 'dev.remotion.remotion';
	}

	if (packageName.startsWith('@remotion/')) {
		const normalizedPackageName = packageName
			.slice('@remotion/'.length)
			.replace(/-([a-z])/g, (_, char: string) => char.toUpperCase());
		return `dev.remotion.${normalizedPackageName}`;
	}

	throw new Error(`Unsupported Remotion package name: ${packageName}`);
};

const makeRemotionComponentIdentity = ({
	packageName,
	componentName,
}: {
	readonly packageName: RemotionComponentIdentityPackage;
	readonly componentName: string;
}): JsxComponentIdentity => {
	return `${sourcePathToIdentityPrefix(packageName)}.${componentName}`;
};

const interactiveElementSchema = {
	...baseSchema,
	...premountSchema,
	...transformSchema,
	...cropSchema,
} as const satisfies InteractivitySchema;

const interactiveBackgroundElementSchema = {
	...interactiveElementSchema,
	...backgroundSchema,
} as const satisfies InteractivitySchema;

const interactiveBorderElementSchema = {
	...interactiveBackgroundElementSchema,
	...borderSchema,
	...borderRadiusSchema,
} as const satisfies InteractivitySchema;

const interactiveTextElementSchema = {
	...interactiveBorderElementSchema,
	...textSchema,
	...childrenSchema,
} as const satisfies InteractivitySchema;

const interactiveSvgTextElementSchema = {
	...interactiveElementSchema,
	...svgPaintSchema,
	...textSchema,
	...childrenSchema,
} as const satisfies InteractivitySchema;

const interactiveSvgElementSchema = {
	...interactiveElementSchema,
	...svgPaintSchema,
} as const satisfies InteractivitySchema;

const interactiveSvgPathElementSchema = {
	...interactiveSvgElementSchema,
	d: {
		type: 'svg-path',
		default: undefined,
		description: 'Path',
		keyframable: true,
	},
} as const satisfies InteractivitySchema;

const interactiveSvgStrokeElementSchema = {
	...interactiveElementSchema,
	...svgStrokeSchema,
} as const satisfies InteractivitySchema;

const interactiveSvgRootElementSchema = {
	...interactiveBorderElementSchema,
	...svgPaintSchema,
} as const satisfies InteractivitySchema;

const setRef = <ElementType,>(
	ref: React.ForwardedRef<ElementType>,
	value: ElementType | null,
) => {
	if (typeof ref === 'function') {
		ref(value);
	} else if (ref) {
		ref.current = value;
	}
};

type NonIntrinsicComponent<Component extends React.ElementType> = Component &
	React.ComponentType<React.ComponentProps<Component>>;

type KeysOfUnion<Props> = Props extends unknown ? keyof Props : never;

type ComponentWithoutReservedProps<
	Component extends React.ElementType,
	ReservedKey extends PropertyKey,
> = NonIntrinsicComponent<Component> &
	(Extract<
		KeysOfUnion<React.ComponentPropsWithoutRef<Component>>,
		ReservedKey
	> extends never
		? unknown
		: never);

type WithSchemaReservedKey =
	| keyof InteractiveBaseProps
	| keyof InteractiveCropProps
	| keyof InteractivePremountProps
	| 'controls';

type IsAny<Value> = 0 extends 1 & Value ? true : false;

type StyleMemberAcceptsCssProperties<Style> =
	IsAny<Style> extends true
		? true
		: Style extends unknown
			? [Style] extends [null | undefined]
				? false
				: Exclude<keyof React.CSSProperties, keyof Style> extends never
					? React.CSSProperties extends Style
						? true
						: false
					: false
			: never;

type StyleAcceptsCssProperties<Style> =
	true extends StyleMemberAcceptsCssProperties<Style> ? true : false;

type PropsBranchAcceptsStyle<Props> = Props extends unknown
	? 'style' extends keyof Props
		? StyleAcceptsCssProperties<Props[Extract<'style', keyof Props>]>
		: false
	: never;

type EveryPropsBranchAcceptsStyle<Props> = [Props] extends [never]
	? false
	: false extends PropsBranchAcceptsStyle<Props>
		? false
		: true;

type ComponentAcceptingStyle<
	Component extends React.ElementType,
	ReservedKey extends PropertyKey,
> = ComponentWithoutReservedProps<Component, ReservedKey> &
	(EveryPropsBranchAcceptsStyle<
		React.ComponentPropsWithoutRef<Component>
	> extends true
		? unknown
		: never);

type WithSchemaOptions<
	Options extends {schema: InteractivitySchema; componentName: string},
	WithDefaults extends boolean,
> = WithDefaults extends true
	? Omit<Options, 'schema' | 'componentName' | 'wrapInSequence'> &
			Partial<Pick<Options, 'schema' | 'componentName'>>
	: Options;

type WithSequence<WithDefaults extends boolean> = {
	<S extends InteractivitySchema, Component extends React.ElementType>(
		options: WithSchemaOptions<
			Omit<
				WithInteractivitySchemaOptions<
					S,
					React.ComponentPropsWithoutRef<Component>
				>,
				'Component' | 'supportsEffects'
			> & {
				readonly Component: ComponentWithoutReservedProps<
					Component,
					WithSchemaReservedKey | 'style' | 'width' | 'height'
				>;
				readonly wrapInSequence: true;
				readonly layout: 'absolute-fill';
			},
			WithDefaults
		>,
	): React.FC<
		React.ComponentPropsWithoutRef<Component> &
			InteractiveBaseProps &
			InteractivePremountProps &
			InteractiveCropProps &
			InteractiveTransformProps &
			Pick<SequenceProps, 'width' | 'height'> & {
				readonly ref?: React.Ref<HTMLDivElement>;
			}
	>;
	<S extends InteractivitySchema, Component extends React.ElementType>(
		options: WithSchemaOptions<
			Omit<
				WithInteractivitySchemaOptions<
					S,
					React.ComponentPropsWithoutRef<Component>
				>,
				'Component' | 'supportsEffects'
			> & {
				readonly Component: ComponentAcceptingStyle<
					Component,
					WithSchemaReservedKey
				>;
				readonly wrapInSequence: true;
				readonly layout?: 'none';
			},
			WithDefaults
		>,
	): React.FC<
		React.ComponentPropsWithRef<Component> &
			InteractiveBaseProps &
			InteractivePremountProps &
			InteractiveCropProps
	>;
};

type WithSchema = WithSequence<false> & {
	<S extends InteractivitySchema, Props extends object>(
		options: WithInteractivitySchemaOptions<S, Props> & {
			readonly wrapInSequence?: false;
			readonly layout?: never;
		},
	): React.ComponentType<Props>;
};

type WithSchemaImplementationOptions = Omit<
	WithInteractivitySchemaOptions<InteractivitySchema, object>,
	'Component' | 'supportsEffects'
> & {
	readonly Component: React.ComponentType<object>;
	readonly supportsEffects?: boolean;
	readonly wrapInSequence?: false | true;
	readonly layout?: 'none' | 'absolute-fill';
};

const withSchema: WithSchema = (untypedOptions: unknown) => {
	const options = untypedOptions as WithSchemaImplementationOptions;
	if (!options.wrapInSequence) {
		const LegacyWrapped = withInteractivitySchema(
			options as WithInteractivitySchemaOptions<InteractivitySchema, object>,
		);
		addSequenceStackTraces(LegacyWrapped);

		return LegacyWrapped as React.FC<
			React.ComponentProps<typeof LegacyWrapped>
		>;
	}

	const {
		Component,
		componentName,
		schema,
		wrapInSequence: _,
		layout = 'none',
		...rest
	} = options;
	type ComponentWrappedInSequenceProps = React.ComponentProps<
		typeof Component
	> &
		InteractiveBaseProps &
		InteractivePremountProps &
		InteractiveCropProps &
		Pick<SequenceProps, 'width' | 'height'> & {
			readonly controls: SequenceControls | undefined;
		};
	const ComponentWrappedInSequence = forwardRef<
		unknown,
		ComponentWrappedInSequenceProps
	>((props, ref) => {
		const {canvasContent, compositions} = useContext(CompositionManager);
		// The render callback runs after the exported wrapper has been initialized.
		// eslint-disable-next-line @typescript-eslint/no-use-before-define
		const componentIdentity = resolveComponentIdentity(Wrapped);
		const isCurrentComposition = compositions.some(
			(composition) =>
				canvasContent?.type === 'composition' &&
				composition.id === canvasContent.compositionId &&
				composition.componentFromProps === componentIdentity,
		);
		const {width, height, ...propsWithoutDimensions} = props;
		const {
			durationInFrames,
			from,
			trimBefore,
			playbackRate,
			loop,
			freeze,
			hidden,
			name,
			showInTimeline,
			controls,
			premountFor,
			postmountFor,
			styleWhilePremounted,
			styleWhilePostmounted,
			...componentProps
		} = layout === 'absolute-fill' ? propsWithoutDimensions : props;
		const {
			cropLeft,
			cropRight,
			cropTop,
			cropBottom,
			style,
			...componentPropsWithoutCropping
		} = componentProps as InteractiveCropProps & {
			readonly style?: React.CSSProperties;
			readonly [key: string]: unknown;
		};
		const {
			effectivePremountFor,
			effectivePostmountFor,
			freezeFrame,
			isPremountingOrPostmounting,
			premountingActive,
			postmountingActive,
			premountingStyle,
		} = usePremounting({
			from: from ?? 0,
			durationInFrames: resolveSequenceDuration({
				durationInFrames,
				playbackRate,
				loop,
			}),
			premountFor: premountFor ?? null,
			postmountFor: postmountFor ?? null,
			style: style ?? null,
			styleWhilePremounted: styleWhilePremounted ?? null,
			styleWhilePostmounted: styleWhilePostmounted ?? null,
			hideWhilePremounted: 'opacity',
		});
		const croppedStyle = useCropStyle({
			cropLeft,
			cropRight,
			cropTop,
			cropBottom,
			style: premountingStyle,
			componentName,
		});

		return (
			<Freeze frame={freezeFrame} active={isPremountingOrPostmounting}>
				<SequenceWithoutSchema
					_remotionInternalSingleChildComponent={
						isCurrentComposition ? null : componentIdentity
					}
					layout={layout}
					{...(layout === 'absolute-fill'
						? {
								width,
								height,
								style: {overflow: 'hidden', ...croppedStyle},
								ref: ref as React.ForwardedRef<HTMLDivElement>,
							}
						: {})}
					durationInFrames={durationInFrames}
					from={from}
					trimBefore={trimBefore}
					playbackRate={playbackRate}
					loop={loop}
					freeze={freeze}
					hidden={hidden}
					name={name ?? componentName}
					_remotionInternalDocumentationLink="https://www.remotion.dev/docs/interactive-create"
					showInTimeline={isCurrentComposition ? false : showInTimeline}
					controls={controls}
					_remotionInternalPremountDisplay={effectivePremountFor || null}
					_remotionInternalPostmountDisplay={effectivePostmountFor || null}
					_remotionInternalIsPremounting={premountingActive}
					_remotionInternalIsPostmounting={postmountingActive}
				>
					{React.createElement(Component, {
						...componentPropsWithoutCropping,
						...(layout === 'none'
							? {style: croppedStyle ?? undefined, ref}
							: {}),
					} as React.ComponentProps<typeof Component>)}
				</SequenceWithoutSchema>
			</Freeze>
		);
	});
	const Wrapped = withInteractivitySchema({
		...rest,
		Component: ComponentWrappedInSequence,
		componentName,
		schema: {
			...schema,
			...transformSchema,
			...baseSchema,
			...premountSchema,
			...cropSchema,
		},
		supportsEffects: false,
	});
	addSequenceStackTraces(Wrapped);

	return Wrapped as React.FC<
		React.ComponentProps<typeof Component> &
			InteractiveBaseProps &
			InteractivePremountProps &
			InteractiveCropProps
	>;
};

const create: WithSequence<true> = (untypedOptions: unknown) => {
	const options = untypedOptions as Omit<
		WithSchemaImplementationOptions,
		'schema' | 'componentName' | 'wrapInSequence' | 'supportsEffects'
	> &
		Partial<Pick<WithSchemaImplementationOptions, 'schema' | 'componentName'>>;

	return (withSchema as (options: WithSchemaImplementationOptions) => React.FC)(
		{
			...options,
			wrapInSequence: true,
			schema: options.schema ?? {},
			componentName:
				options.componentName ??
				(options.Component.displayName ||
					options.Component.name?.replace(/(.+)Inner$/, '$1') ||
					'Component'),
		},
	);
};

const makeInteractiveElement = <Tag extends InteractiveTag>(
	tag: Tag,
	displayName: string,
	schema: InteractivitySchema,
): InteractiveElementComponent<Tag> => {
	type ElementType = ElementForTag<Tag>;
	type Props = InteractiveElementProps<Tag>;

	const Inner = forwardRef<
		ElementType,
		Props & {
			readonly controls: SequenceControls | undefined;
		}
	>((propsWithControls, ref) => {
		const {
			durationInFrames,
			from,
			premountFor,
			postmountFor,
			styleWhilePremounted,
			styleWhilePostmounted,
			trimBefore,
			playbackRate,
			loop,
			freeze,
			hidden,
			name,
			showInTimeline,
			controls,
			cropLeft,
			cropRight,
			cropTop,
			cropBottom,
			style,
			...props
		} = propsWithControls as Props & {
			readonly controls: SequenceControls | undefined;
		};

		const {
			effectivePremountFor,
			effectivePostmountFor,
			freezeFrame,
			isPremountingOrPostmounting,
			premountingActive,
			postmountingActive,
			premountingStyle,
		} = usePremounting({
			from: from ?? 0,
			durationInFrames: resolveSequenceDuration({
				durationInFrames,
				playbackRate,
				loop,
			}),
			premountFor: premountFor ?? null,
			postmountFor: postmountFor ?? null,
			style: style ?? null,
			styleWhilePremounted: styleWhilePremounted ?? null,
			styleWhilePostmounted: styleWhilePostmounted ?? null,
			hideWhilePremounted: 'opacity',
		});
		const croppedStyle = useCropStyle({
			cropLeft,
			cropRight,
			cropTop,
			cropBottom,
			style: premountingStyle,
			componentName: displayName,
		});
		const callbackRef = useCallback(
			(element: ElementType | null) => {
				setRef(ref, element);
			},
			[ref],
		);

		return (
			<Freeze
				frame={freezeFrame}
				active={isPremountingOrPostmounting}
				_remotionInternalIsPremounting={premountingActive}
			>
				<Sequence
					layout="none"
					from={from ?? 0}
					trimBefore={trimBefore}
					playbackRate={playbackRate}
					loop={loop}
					durationInFrames={durationInFrames}
					freeze={freeze}
					hidden={hidden}
					name={name ?? displayName}
					showInTimeline={showInTimeline ?? true}
					controls={controls}
					_remotionInternalDocumentationLink="https://www.remotion.dev/docs/interactive"
					_remotionInternalPremountDisplay={effectivePremountFor || null}
					_remotionInternalPostmountDisplay={effectivePostmountFor || null}
					_remotionInternalIsPremounting={premountingActive}
					_remotionInternalIsPostmounting={postmountingActive}
				>
					{React.createElement(tag, {
						...props,
						style: croppedStyle ?? undefined,
						ref: callbackRef,
					})}
				</Sequence>
			</Freeze>
		);
	});

	Inner.displayName = displayName;

	const Wrapped = withSchema({
		Component: Inner,
		componentName: displayName,
		componentIdentity: makeRemotionComponentIdentity({
			packageName: 'remotion',
			componentName: displayName.slice(1, -1),
		}),
		schema,
		supportsEffects: false,
	}) as InteractiveElementComponent<Tag>;

	Wrapped.displayName = displayName;

	return Wrapped;
};

const makeInteractiveTextElement = <Tag extends InteractiveTag>(
	tag: Tag,
	displayName: string,
) => {
	return makeInteractiveElement(tag, displayName, interactiveTextElementSchema);
};

const makeInteractiveSvgElement = <Tag extends InteractiveSvgTag>(
	tag: Tag,
	displayName: string,
) => {
	return makeInteractiveElement(tag, displayName, interactiveSvgElementSchema);
};

const makeInteractiveSvgStrokeElement = <Tag extends InteractiveSvgTag>(
	tag: Tag,
	displayName: string,
) => {
	return makeInteractiveElement(
		tag,
		displayName,
		interactiveSvgStrokeElementSchema,
	);
};

/**
 * @description HTML and SVG elements that are registered in the Remotion Studio timeline and can be visually edited.
 */
export const Interactive = {
	baseSchema,
	captionsSchema,
	childrenSchema,
	transformSchema,
	textSchema,
	backgroundSchema,
	borderSchema,
	borderRadiusSchema,
	cropSchema,
	svgPaintSchema,
	svgStrokeSchema,
	premountSchema,
	sequenceSchema,
	/**
	 * @deprecated Use `Interactive.create()` instead: https://www.remotion.dev/docs/interactive-create
	 */
	withSchema,
	/**
	 * @description Creates a component with timing props and editable Studio controls.
	 * @see [Documentation](https://www.remotion.dev/docs/interactive-create)
	 */
	create,
	_internalMakeRemotionComponentIdentity: makeRemotionComponentIdentity,
	A: makeInteractiveTextElement('a', '<Interactive.A>'),
	Article: makeInteractiveTextElement('article', '<Interactive.Article>'),
	Aside: makeInteractiveTextElement('aside', '<Interactive.Aside>'),
	Button: makeInteractiveTextElement('button', '<Interactive.Button>'),
	Circle: makeInteractiveSvgElement('circle', '<Interactive.Circle>'),
	Code: makeInteractiveTextElement('code', '<Interactive.Code>'),
	Div: makeInteractiveTextElement('div', '<Interactive.Div>'),
	Ellipse: makeInteractiveSvgElement('ellipse', '<Interactive.Ellipse>'),
	Em: makeInteractiveTextElement('em', '<Interactive.Em>'),
	Footer: makeInteractiveTextElement('footer', '<Interactive.Footer>'),
	G: makeInteractiveSvgElement('g', '<Interactive.G>'),
	H1: makeInteractiveTextElement('h1', '<Interactive.H1>'),
	H2: makeInteractiveTextElement('h2', '<Interactive.H2>'),
	H3: makeInteractiveTextElement('h3', '<Interactive.H3>'),
	H4: makeInteractiveTextElement('h4', '<Interactive.H4>'),
	H5: makeInteractiveTextElement('h5', '<Interactive.H5>'),
	H6: makeInteractiveTextElement('h6', '<Interactive.H6>'),
	Header: makeInteractiveTextElement('header', '<Interactive.Header>'),
	Label: makeInteractiveTextElement('label', '<Interactive.Label>'),
	Li: makeInteractiveTextElement('li', '<Interactive.Li>'),
	Line: makeInteractiveSvgStrokeElement('line', '<Interactive.Line>'),
	Main: makeInteractiveTextElement('main', '<Interactive.Main>'),
	Nav: makeInteractiveTextElement('nav', '<Interactive.Nav>'),
	Ol: makeInteractiveTextElement('ol', '<Interactive.Ol>'),
	P: makeInteractiveTextElement('p', '<Interactive.P>'),
	Path: makeInteractiveElement(
		'path',
		'<Interactive.Path>',
		interactiveSvgPathElementSchema,
	),
	Pre: makeInteractiveTextElement('pre', '<Interactive.Pre>'),
	Rect: makeInteractiveSvgElement('rect', '<Interactive.Rect>'),
	Section: makeInteractiveTextElement('section', '<Interactive.Section>'),
	Small: makeInteractiveTextElement('small', '<Interactive.Small>'),
	Span: makeInteractiveTextElement('span', '<Interactive.Span>'),
	Strong: makeInteractiveTextElement('strong', '<Interactive.Strong>'),
	Svg: makeInteractiveElement(
		'svg',
		'<Interactive.Svg>',
		interactiveSvgRootElementSchema,
	),
	Text: makeInteractiveElement(
		'text',
		'<Interactive.Text>',
		interactiveSvgTextElementSchema,
	),
	Ul: makeInteractiveTextElement('ul', '<Interactive.Ul>'),
};

export type InteractiveProps<Tag extends InteractiveTag> =
	InteractiveElementProps<Tag>;