Skip to content

🎥 Make videos programmatically with React

19.3 KB
Raw Blame
import type {ComponentType, LazyExoticComponent, RefObject} from 'react';
import React, {
	forwardRef,
	useCallback,
	useEffect,
	useImperativeHandle,
	useLayoutEffect,
	useMemo,
	useRef,
	useState,
} from 'react';
import type {
	AnyZodObject,
	CompProps,
	LogLevel,
	PlaybackRateContextValue,
	PlayableMediaTag,
	SetTimelineContextValue,
	TimelineContextValue,
} from 'remotion';
import {Composition, Internals} from 'remotion';
import {NoReactInternals} from 'remotion/no-react';
import type {BrowserMediaControlsBehavior} from './browser-mediasession.js';
import {PlayerEmitterProvider} from './EmitterProvider.js';
import type {RenderMuteButton} from './MediaVolumeSlider.js';
import {playerCssClassname} from './player-css-classname.js';
import type {PlayerRef, RenderCustomControls} from './player-methods.js';
import type {
	RenderFullscreenButton,
	RenderPlayPauseButton,
} from './PlayerControls.js';
import type {PosterFillMode, RenderLoading, RenderPoster} from './PlayerUI.js';
import PlayerUI from './PlayerUI.js';
import type {RenderVolumeSlider} from './render-volume-slider.js';
import {PLAYER_COMP_ID, SharedPlayerContexts} from './SharedPlayerContext.js';
import type {TimelineSequenceObserver} from './timeline-sequence-observer-context.js';
import {TimelineSequenceObserverContext} from './timeline-sequence-observer-context.js';
import {acknowledgeRemotionLicenseMessage} from './use-remotion-license-acknowledge.js';
import type {PropsIfHasProps} from './utils/props-if-has-props.js';
import {validateInOutFrames} from './utils/validate-in-out-frame.js';
import {validateInitialFrame} from './utils/validate-initial-frame.js';
import {validatePlaybackRate} from './utils/validate-playbackrate.js';
import {
	validateDefaultAndInputProps,
	validateDimension,
	validateDurationInFrames,
	validateFps,
} from './validate.js';

export type ErrorFallback = (info: {error: Error}) => React.ReactNode;

export type PlayerProps<
	Schema extends AnyZodObject,
	Props extends Record<string, unknown>,
> = {
	readonly durationInFrames: number;
	readonly compositionWidth: number;
	readonly compositionHeight: number;
	readonly fps: number;
	readonly showVolumeControls?: boolean;
	readonly controls?: boolean;
	readonly errorFallback?: ErrorFallback;
	readonly style?: React.CSSProperties;
	readonly loop?: boolean;
	readonly autoPlay?: boolean;
	readonly allowFullscreen?: boolean;
	readonly clickToPlay?: boolean;
	readonly doubleClickToFullscreen?: boolean;
	readonly spaceKeyToPlayOrPause?: boolean;
	readonly numberOfSharedAudioTags?: number;
	readonly playbackRate?: number;
	/**
	 * Preserve @remotion/media audio pitch when changing the Player playback rate.
	 * @default false
	 */
	readonly preservePitch?: boolean;
	readonly renderLoading?: RenderLoading;
	readonly moveToBeginningWhenEnded?: boolean;
	readonly className?: string;
	readonly initialFrame?: number;
	readonly renderPoster?: RenderPoster;
	readonly showPosterWhenPaused?: boolean;
	readonly showPosterWhenEnded?: boolean;
	readonly showPosterWhenUnplayed?: boolean;
	readonly showPosterWhenBuffering?: boolean;
	readonly showPosterWhenBufferingAndPaused?: boolean;
	readonly inFrame?: number | null;
	readonly outFrame?: number | null;
	readonly initiallyShowControls?: number | boolean;
	readonly renderPlayPauseButton?: RenderPlayPauseButton;
	readonly renderFullscreenButton?: RenderFullscreenButton;
	readonly renderMuteButton?: RenderMuteButton;
	readonly renderVolumeSlider?: RenderVolumeSlider;
	readonly renderCustomControls?: RenderCustomControls;
	readonly alwaysShowControls?: boolean;
	readonly schema?: Schema;
	readonly initiallyMuted?: boolean;
	readonly showPlaybackRateControl?: boolean | number[];
	readonly posterFillMode?: PosterFillMode;
	readonly bufferStateDelayInMilliseconds?: number;
	readonly defaultPremountInSeconds?: number;
	readonly hideControlsWhenPointerDoesntMove?: boolean | number;
	readonly overflowVisible?: boolean;
	readonly browserMediaControlsBehavior?: BrowserMediaControlsBehavior;
	readonly overrideInternalClassName?: string;
	readonly logLevel?: LogLevel;
	readonly noSuspense?: boolean;
	readonly acknowledgeRemotionLicense?: boolean;
	readonly audioLatencyHint?: AudioContextLatencyCategory;
	readonly sampleRate?: number;
	readonly volumePersistenceKey?: string;
	readonly initialVolume?: number;
	readonly _experimentalKeepAudioContextAlive?: boolean;
} & CompProps<Props> &
	PropsIfHasProps<Schema, Props>;

export type PlayerPropsWithoutZod<Props extends Record<string, unknown>> =
	PlayerProps<AnyZodObject, Props>;

export const componentOrNullIfLazy = <Props,>(
	props: CompProps<Props>,
): ComponentType<Props> | null => {
	if ('component' in props) {
		return props.component as ComponentType<Props>;
	}

	return null;
};

const TimelineSequenceObserverComponent: React.FC<{
	readonly onTimelineSequenceChange: TimelineSequenceObserver;
}> = ({onTimelineSequenceChange}) => {
	const registry = React.useContext(Internals.SequenceRegistryContext);

	useLayoutEffect(() => {
		if (registry === null) {
			throw new Error(
				'Timeline sequence observer requires a sequence registry',
			);
		}

		const publish = () => onTimelineSequenceChange(registry.getSnapshot());
		const unsubscribe = registry.subscribe(publish);
		publish();
		return unsubscribe;
	}, [onTimelineSequenceChange, registry]);

	return null;
};

const PlayerFn = <
	Schema extends AnyZodObject,
	Props extends Record<string, unknown>,
>(
	{
		durationInFrames,
		compositionHeight,
		compositionWidth,
		fps,
		inputProps,
		style,
		controls = false,
		loop = false,
		autoPlay = false,
		showVolumeControls = true,
		allowFullscreen = true,
		clickToPlay,
		doubleClickToFullscreen = false,
		spaceKeyToPlayOrPause = true,
		moveToBeginningWhenEnded = true,
		numberOfSharedAudioTags = NoReactInternals.ENABLE_V5_BREAKING_CHANGES
			? 0
			: 5,
		errorFallback = () => '⚠️',
		playbackRate = 1,
		preservePitch = false,
		renderLoading,
		className,
		showPosterWhenUnplayed,
		showPosterWhenEnded,
		showPosterWhenPaused,
		showPosterWhenBuffering,
		showPosterWhenBufferingAndPaused,
		initialFrame,
		renderPoster,
		inFrame,
		outFrame,
		initiallyShowControls,
		renderFullscreenButton,
		renderPlayPauseButton,
		renderVolumeSlider,
		renderCustomControls,
		alwaysShowControls = false,
		initiallyMuted = false,
		showPlaybackRateControl = false,
		posterFillMode = 'player-size',
		bufferStateDelayInMilliseconds,
		defaultPremountInSeconds = NoReactInternals.DEFAULT_PREMOUNT_IN_SECONDS,
		hideControlsWhenPointerDoesntMove = true,
		overflowVisible = false,
		renderMuteButton,
		browserMediaControlsBehavior: passedBrowserMediaControlsBehavior,
		overrideInternalClassName,
		logLevel = 'info',
		noSuspense,
		acknowledgeRemotionLicense,
		audioLatencyHint = 'playback',
		sampleRate = 48000,
		volumePersistenceKey,
		initialVolume,
		_experimentalKeepAudioContextAlive = false,
		...componentProps
	}: PlayerProps<Schema, Props>,
	ref: RefObject<PlayerRef>,
) => {
	NoReactInternals.validateDefaultPremountInSeconds(defaultPremountInSeconds);

	if (typeof window !== 'undefined') {
		window.remotion_isPlayer = true;
	}

	const onTimelineSequenceChange = React.useContext(
		TimelineSequenceObserverContext,
	);

	// @ts-expect-error
	if (componentProps.defaultProps !== undefined) {
		throw new Error(
			'The <Player /> component does not accept `defaultProps`, but some were passed. Use `inputProps` instead.',
		);
	}

	const componentForValidation = componentOrNullIfLazy(
		componentProps,
	) as ComponentType<unknown> | null;

	// @ts-expect-error
	if (componentForValidation?.type === Composition) {
		throw new TypeError(
			`'component' should not be an instance of <Composition/>. Pass the React component directly, and set the duration, fps and dimensions as separate props. See https://www.remotion.dev/docs/player/examples for an example.`,
		);
	}

	if (componentForValidation === Composition) {
		throw new TypeError(
			`'component' must not be the 'Composition' component. Pass your own React component directly, and set the duration, fps and dimensions as separate props. See https://www.remotion.dev/docs/player/examples for an example.`,
		);
	}

	useState(() =>
		acknowledgeRemotionLicenseMessage(
			Boolean(acknowledgeRemotionLicense),
			logLevel,
		),
	);

	const component = Internals.useLazyComponent({
		compProps: componentProps,
		componentName: 'Player',
		noSuspense: Boolean(noSuspense),
	}) as LazyExoticComponent<ComponentType<unknown>>;

	validateInitialFrame({initialFrame, durationInFrames});

	const [frame, setFrame] = useState<Record<string, number>>(() => ({
		[PLAYER_COMP_ID]: initialFrame ?? 0,
	}));
	const seek = Internals.useTimelineSeek(setFrame);
	const frameRef = useRef(frame);
	frameRef.current = frame;
	const rootRef = useRef<PlayerRef>(null);
	const audioAndVideoTags = useRef<PlayableMediaTag[]>([]);
	const playingStore = useMemo(
		() => Internals.createRuntimeValueStore({playing: false}),
		[],
	);
	const bufferingStore = useMemo(
		() => Internals.createRuntimeValueStore({buffering: false}),
		[],
	);
	const readIsPlaying = useCallback(
		() => playingStore.store.getSnapshot().playing,
		[playingStore],
	);
	const readIsBuffering = useCallback(
		() => bufferingStore.store.getSnapshot().buffering,
		[bufferingStore],
	);
	const [currentPlaybackRate, setCurrentPlaybackRate] = useState(playbackRate);

	if (typeof compositionHeight !== 'number') {
		throw new TypeError(
			`'compositionHeight' must be a number but got '${typeof compositionHeight}' instead`,
		);
	}

	if (typeof compositionWidth !== 'number') {
		throw new TypeError(
			`'compositionWidth' must be a number but got '${typeof compositionWidth}' instead`,
		);
	}

	validateDimension(
		compositionHeight,
		'compositionHeight',
		'of the <Player /> component',
	);
	validateDimension(
		compositionWidth,
		'compositionWidth',
		'of the <Player /> component',
	);
	validateDurationInFrames(durationInFrames, {
		component: 'of the <Player/> component',
		allowFloats: false,
	});
	validateFps(fps, 'as a prop of the <Player/> component', false);
	validateDefaultAndInputProps(inputProps, 'inputProps', null);

	validateInOutFrames({
		durationInFrames,
		inFrame,
		outFrame,
	});

	if (typeof controls !== 'boolean' && typeof controls !== 'undefined') {
		throw new TypeError(
			`'controls' must be a boolean or undefined but got '${typeof controls}' instead`,
		);
	}

	if (typeof preservePitch !== 'boolean') {
		throw new TypeError(
			`'preservePitch' must be a boolean but got '${typeof preservePitch}' instead`,
		);
	}

	if (typeof autoPlay !== 'boolean' && typeof autoPlay !== 'undefined') {
		throw new TypeError(
			`'autoPlay' must be a boolean or undefined but got '${typeof autoPlay}' instead`,
		);
	}

	if (typeof loop !== 'boolean' && typeof loop !== 'undefined') {
		throw new TypeError(
			`'loop' must be a boolean or undefined but got '${typeof loop}' instead`,
		);
	}

	if (
		typeof doubleClickToFullscreen !== 'boolean' &&
		typeof doubleClickToFullscreen !== 'undefined'
	) {
		throw new TypeError(
			`'doubleClickToFullscreen' must be a boolean or undefined but got '${typeof doubleClickToFullscreen}' instead`,
		);
	}

	if (
		typeof showVolumeControls !== 'boolean' &&
		typeof showVolumeControls !== 'undefined'
	) {
		throw new TypeError(
			`'showVolumeControls' must be a boolean or undefined but got '${typeof showVolumeControls}' instead`,
		);
	}

	if (
		typeof allowFullscreen !== 'boolean' &&
		typeof allowFullscreen !== 'undefined'
	) {
		throw new TypeError(
			`'allowFullscreen' must be a boolean or undefined but got '${typeof allowFullscreen}' instead`,
		);
	}

	if (typeof clickToPlay !== 'boolean' && typeof clickToPlay !== 'undefined') {
		throw new TypeError(
			`'clickToPlay' must be a boolean or undefined but got '${typeof clickToPlay}' instead`,
		);
	}

	if (
		typeof spaceKeyToPlayOrPause !== 'boolean' &&
		typeof spaceKeyToPlayOrPause !== 'undefined'
	) {
		throw new TypeError(
			`'spaceKeyToPlayOrPause' must be a boolean or undefined but got '${typeof spaceKeyToPlayOrPause}' instead`,
		);
	}

	if (
		typeof sampleRate !== 'number' ||
		!Number.isFinite(sampleRate) ||
		Number.isNaN(sampleRate) ||
		sampleRate <= 0 ||
		sampleRate % 1 !== 0
	) {
		throw new TypeError(
			`'sampleRate' must be a positive integer but got '${sampleRate}' instead`,
		);
	}

	if (
		typeof initialVolume !== 'undefined' &&
		typeof initialVolume !== 'number'
	) {
		throw new TypeError(
			`'initialVolume' must be a number or undefined but got '${typeof initialVolume}' instead`,
		);
	}

	if (
		typeof initialVolume === 'number' &&
		(!Number.isFinite(initialVolume) ||
			Number.isNaN(initialVolume) ||
			initialVolume < 0 ||
			initialVolume > 1)
	) {
		throw new TypeError(
			`'initialVolume' must be between 0 and 1 but got '${initialVolume}' instead`,
		);
	}

	if (
		typeof numberOfSharedAudioTags !== 'number' ||
		numberOfSharedAudioTags % 1 !== 0 ||
		!Number.isFinite(numberOfSharedAudioTags) ||
		Number.isNaN(numberOfSharedAudioTags) ||
		numberOfSharedAudioTags < 0
	) {
		throw new TypeError(
			`'numberOfSharedAudioTags' must be an integer but got '${numberOfSharedAudioTags}' instead`,
		);
	}

	validatePlaybackRate(currentPlaybackRate);

	useEffect(() => {
		setCurrentPlaybackRate(playbackRate);
	}, [playbackRate]);

	useImperativeHandle(ref, () => rootRef.current as PlayerRef, []);

	useState(() => {
		Internals.playbackLogging({
			logLevel,
			message: `[player] Mounting <Player>. User agent = ${
				typeof navigator === 'undefined' ? 'server' : navigator.userAgent
			}`,
			tag: 'player',
			mountTime: Date.now(),
		});
	});

	const timelineContextValue = useMemo((): TimelineContextValue => {
		return {
			frame,
			isPlaying: readIsPlaying,
			isInsideFreeze: false,
			audioAndVideoTags,
		};
	}, [frame, readIsPlaying]);

	const playbackRateContextValue = useMemo((): PlaybackRateContextValue => {
		return {
			playbackRate: currentPlaybackRate,
			setPlaybackRate: setCurrentPlaybackRate,
		};
	}, [currentPlaybackRate]);

	const setTimelineContextValue = useMemo((): SetTimelineContextValue => {
		return {
			setFrameWithoutSeek: setFrame,
			seek,
			setPlaying: (updater) => {
				const current = playingStore.store.getSnapshot().playing;
				const next = typeof updater === 'function' ? updater(current) : updater;
				if (current !== next) {
					playingStore.setSnapshot({playing: next});
				}
			},
			setBuffering: (buffering) => {
				if (readIsBuffering() !== buffering) {
					bufferingStore.setSnapshot({buffering});
				}
			},
			subscribePlaying: playingStore.store.subscribe,
			subscribeBuffering: bufferingStore.store.subscribe,
			isPlaying: readIsPlaying,
			isBuffering: readIsBuffering,
			frameRef,
			audioAndVideoTags,
		};
	}, [
		bufferingStore,
		seek,
		setFrame,
		frameRef,
		playingStore,
		readIsBuffering,
		readIsPlaying,
	]);

	if (typeof window !== 'undefined') {
		// eslint-disable-next-line react-hooks/rules-of-hooks
		useLayoutEffect(() => {
			// Inject CSS only on client, and also only after the Player has hydrated
			Internals.CSSUtils.injectCSS(
				Internals.CSSUtils.makeDefaultPreviewCSS(
					`.${playerCssClassname(overrideInternalClassName)}`,
					'#fff',
				),
			);
		}, [overrideInternalClassName]);
	}

	const actualInputProps = useMemo(() => inputProps ?? {}, [inputProps]);

	const browserMediaControlsBehavior: BrowserMediaControlsBehavior =
		useMemo(() => {
			return (
				passedBrowserMediaControlsBehavior ?? {
					mode: 'prevent-media-session',
				}
			);
		}, [passedBrowserMediaControlsBehavior]);

	const player = (
		<Internals.IsPlayerContextProvider>
			<Internals.SetTimelineContext.Provider value={setTimelineContextValue}>
				<SharedPlayerContexts
					timelineContext={timelineContextValue}
					playbackRateContext={playbackRateContextValue}
					preservePitch={preservePitch}
					component={component}
					compositionHeight={compositionHeight}
					compositionWidth={compositionWidth}
					durationInFrames={durationInFrames}
					fps={fps}
					numberOfSharedAudioTags={numberOfSharedAudioTags}
					initiallyMuted={initiallyMuted}
					logLevel={logLevel}
					audioLatencyHint={audioLatencyHint}
					sampleRate={sampleRate}
					_experimentalKeepAudioContextAlive={
						_experimentalKeepAudioContextAlive
					}
					volumePersistenceKey={volumePersistenceKey}
					initialVolume={initialVolume}
					inputProps={actualInputProps}
					audioEnabled
				>
					<PlayerEmitterProvider currentPlaybackRate={currentPlaybackRate}>
						<PlayerUI
							ref={rootRef}
							posterFillMode={posterFillMode}
							renderLoading={renderLoading}
							autoPlay={Boolean(autoPlay)}
							loop={Boolean(loop)}
							controls={Boolean(controls)}
							errorFallback={errorFallback}
							style={style}
							inputProps={actualInputProps}
							allowFullscreen={Boolean(allowFullscreen)}
							moveToBeginningWhenEnded={Boolean(moveToBeginningWhenEnded)}
							clickToPlay={
								typeof clickToPlay === 'boolean'
									? clickToPlay
									: Boolean(controls)
							}
							showVolumeControls={Boolean(showVolumeControls)}
							doubleClickToFullscreen={Boolean(doubleClickToFullscreen)}
							spaceKeyToPlayOrPause={Boolean(spaceKeyToPlayOrPause)}
							playbackRate={currentPlaybackRate}
							className={className ?? undefined}
							showPosterWhenUnplayed={Boolean(showPosterWhenUnplayed)}
							showPosterWhenEnded={Boolean(showPosterWhenEnded)}
							showPosterWhenPaused={Boolean(showPosterWhenPaused)}
							showPosterWhenBuffering={Boolean(showPosterWhenBuffering)}
							showPosterWhenBufferingAndPaused={Boolean(
								showPosterWhenBufferingAndPaused,
							)}
							renderPoster={renderPoster}
							inFrame={inFrame ?? null}
							outFrame={outFrame ?? null}
							initiallyShowControls={initiallyShowControls ?? true}
							renderFullscreen={renderFullscreenButton ?? null}
							renderPlayPauseButton={renderPlayPauseButton ?? null}
							renderMuteButton={renderMuteButton ?? null}
							renderVolumeSlider={renderVolumeSlider ?? null}
							renderCustomControls={renderCustomControls ?? null}
							alwaysShowControls={alwaysShowControls}
							showPlaybackRateControl={showPlaybackRateControl}
							bufferStateDelayInMilliseconds={
								bufferStateDelayInMilliseconds ?? 300
							}
							hideControlsWhenPointerDoesntMove={
								hideControlsWhenPointerDoesntMove
							}
							overflowVisible={overflowVisible}
							browserMediaControlsBehavior={browserMediaControlsBehavior}
							overrideInternalClassName={overrideInternalClassName ?? undefined}
							noSuspense={Boolean(noSuspense)}
						/>
					</PlayerEmitterProvider>
				</SharedPlayerContexts>
			</Internals.SetTimelineContext.Provider>
		</Internals.IsPlayerContextProvider>
	);

	return (
		<Internals.DefaultPremountContext.Provider value={defaultPremountInSeconds}>
			{onTimelineSequenceChange ? (
				<Internals.SequenceRegistrationContext.Provider value>
					<Internals.SequenceManagerProvider>
						<TimelineSequenceObserverComponent
							onTimelineSequenceChange={onTimelineSequenceChange}
						/>
						{player}
					</Internals.SequenceManagerProvider>
				</Internals.SequenceRegistrationContext.Provider>
			) : (
				player
			)}
		</Internals.DefaultPremountContext.Provider>
	);
};

const forward = forwardRef as <T, P = {}>(
	render: (props: P, ref: React.RefObject<T>) => React.ReactElement | null,
) => (props: P & React.RefAttributes<T>) => React.ReactElement | null;

/*
 * @description A component which can be rendered in a regular React App to display a Remotion video.
 * @see [Documentation](https://www.remotion.dev/docs/player/player)
 */
export const Player = forward(PlayerFn);