🎥 Make videos programmatically with React
import {useCallback} from 'react';
import type {AudioHTMLAttributes} from 'react';
import React, {
forwardRef,
useContext,
useImperativeHandle,
useMemo,
useState,
} from 'react';
import {
CommittedMetadataProvider,
type CommittedMetadata,
} from '../committed-metadata.js';
import {getCrossOriginValue} from '../get-cross-origin-value.js';
import {useLogLevel} from '../log-level-context.js';
import {usePreload} from '../prefetch.js';
import {random} from '../random.js';
import {SequenceContent} from '../sequence-activity-context.js';
import {SequenceContext} from '../SequenceContext.js';
import {useVolume} from '../use-amplification.js';
import {
scheduleMediaSourceCleanup,
useMediaDuration,
} from '../use-media-duration.js';
import {useMediaInTimelineRegistration} from '../use-media-in-timeline.js';
import {useMediaPlayback} from '../use-media-playback.js';
import {useMediaTag} from '../use-media-tag.js';
import {useRemotionEnvironment} from '../use-remotion-environment.js';
import {useMediaVolumeState} from '../volume-position-state.js';
import {evaluateVolume} from '../volume-prop.js';
import {warnAboutTooHighVolume} from '../volume-safeguard.js';
import type {IsExact, NativeAudioProps, RemotionAudioProps} from './props.js';
import {useSharedAudio} from './shared-audio-tags.js';
import {useFrameForVolumeProp} from './use-audio-frame.js';
import {useMediaAudioState} from './use-media-audio-state.js';
type AudioForPreviewProps = RemotionAudioProps & {
readonly shouldPreMountAudioTags: boolean;
readonly onDuration: (src: string, durationInSeconds: number) => void;
readonly pauseWhenBuffering: boolean;
readonly _remotionInternalNativeLoopPassed: boolean;
readonly _remotionInternalStack: string | null;
readonly showInTimeline: boolean;
readonly onNativeError: React.ReactEventHandler<HTMLAudioElement>;
};
const AudioForDevelopmentForwardRefFunction: React.ForwardRefRenderFunction<
HTMLAudioElement,
AudioForPreviewProps & {
readonly timelineId: string;
readonly userPreferredVolume: number;
readonly isMutedForPlayback: boolean;
}
> = (props, ref) => {
const [initialShouldPreMountAudioElements] = useState(
props.shouldPreMountAudioTags,
);
if (props.shouldPreMountAudioTags !== initialShouldPreMountAudioElements) {
throw new Error(
'Cannot change the behavior for pre-mounting audio tags dynamically.',
);
}
const logLevel = useLogLevel();
const {
timelineId,
userPreferredVolume,
isMutedForPlayback,
volume,
muted,
playbackRate,
preservePitch,
shouldPreMountAudioTags,
src,
onDuration,
acceptableTimeShiftInSeconds,
_remotionInternalNeedsDurationCalculation,
_remotionInternalNativeLoopPassed,
_remotionInternalStack,
allowAmplificationDuringRender,
name,
pauseWhenBuffering,
showInTimeline,
loopVolumeCurveBehavior,
crossOrigin,
delayRenderRetries,
delayRenderTimeoutInMilliseconds,
toneFrequency,
useWebAudioApi,
onError,
onNativeError,
audioStreamIndex,
...nativeProps
} = props;
// Typecheck that we are not accidentially passing unrecognized props
// to the DOM
const _propsValid: IsExact<
typeof nativeProps,
Omit<NativeAudioProps, 'crossOrigin' | 'src' | 'name' | 'muted'>
> = true;
if (!_propsValid) {
throw new Error('typecheck error');
}
if (!src) {
throw new TypeError("No 'src' was passed to <Html5Audio>.");
}
const preloadedSrc = usePreload(src);
const sequenceContext = useContext(SequenceContext);
warnAboutTooHighVolume(userPreferredVolume);
const crossOriginValue = getCrossOriginValue({
crossOrigin,
requestsVideoFrame: false,
isClientSideRendering: false,
});
const propsToPass = useMemo((): AudioHTMLAttributes<HTMLAudioElement> => {
return {
muted: isMutedForPlayback,
src: preloadedSrc,
loop: _remotionInternalNativeLoopPassed,
crossOrigin: crossOriginValue,
...nativeProps,
};
}, [
_remotionInternalNativeLoopPassed,
isMutedForPlayback,
nativeProps,
preloadedSrc,
crossOriginValue,
]);
// Generate a string that's as unique as possible for this asset
// but at the same time deterministic. We use it to combat strict mode issues.
const id = useMemo(
() =>
`audio-${random(
src ?? '',
)}-${sequenceContext?.relativeFrom}-${sequenceContext?.cumulatedFrom}-${sequenceContext?.durationInFrames}-muted:${
props.muted
}-loop:${props.loop}`,
[
src,
sequenceContext?.relativeFrom,
sequenceContext?.cumulatedFrom,
sequenceContext?.durationInFrames,
props.muted,
props.loop,
],
);
const {
el: audioRef,
mediaElementSourceNode,
cleanupOnMediaTagUnmount,
} = useSharedAudio({
aud: propsToPass,
audioId: id,
premounting: Boolean(sequenceContext?.premounting),
postmounting: Boolean(sequenceContext?.postmounting),
});
// putting playback before useVolume
// because volume looks at playbackrate
useMediaPlayback({
mediaRef: audioRef,
src,
mediaType: 'audio',
playbackRate: playbackRate ?? 1,
preservePitch,
onlyWarnForMediaSeekingError: false,
acceptableTimeshift: acceptableTimeShiftInSeconds ?? null,
isPremounting: Boolean(sequenceContext?.premounting),
isPostmounting: Boolean(sequenceContext?.postmounting),
pauseWhenBuffering,
onAutoPlayError: null,
});
useMediaTag({
id: timelineId,
isPostmounting: Boolean(sequenceContext?.postmounting),
isPremounting: Boolean(sequenceContext?.premounting),
mediaRef: audioRef,
mediaType: 'audio',
onAutoPlayError: null,
});
useVolume({
logLevel,
mediaRef: audioRef,
source: mediaElementSourceNode,
volume: userPreferredVolume,
shouldUseWebAudioApi: useWebAudioApi ?? false,
});
/**
* Effects in React 18 fire twice, and we are looking for a way to only fire it once.
* - useInsertionEffect only fires once. If it's available we are in React 18.
* - useLayoutEffect only fires once in React 17.
*
* Need to import it from React to fix React 17 ESM support.
*/
const effectToUse = React.useInsertionEffect ?? React.useLayoutEffect;
// Disconnecting the SharedElementSourceNodes if the Audio tag unmounts to prevent leak.
// https://github.com/remotion-dev/remotion/issues/6285
// But useInsertionEffect will fire before other effects, meaning the
// nodes might still be used. Using rAF to ensure it's after other effects.
effectToUse(() => {
return scheduleMediaSourceCleanup.bind(null, cleanupOnMediaTagUnmount);
}, [cleanupOnMediaTagUnmount]);
useImperativeHandle(ref, () => {
return audioRef.current as HTMLAudioElement;
}, [audioRef]);
useMediaDuration(audioRef, onDuration, src, true);
if (initialShouldPreMountAudioElements) {
return null;
}
const audio = (
<audio
ref={audioRef}
preload="metadata"
crossOrigin={crossOriginValue}
{...propsToPass}
/>
);
return audio;
};
const AudioForPreviewContent = forwardRef(
AudioForDevelopmentForwardRefFunction,
);
const AudioForPreviewRefForwardingFunction: React.ForwardRefRenderFunction<
HTMLAudioElement,
AudioForPreviewProps
> = (props, ref) => {
const {
volume,
muted,
playbackRate,
src,
name,
_remotionInternalStack,
showInTimeline,
loopVolumeCurveBehavior,
} = props;
const [timelineId] = useState(() => String(Math.random()));
const sequenceContext = useContext(SequenceContext);
const {isStudio} = useRemotionEnvironment();
const [mediaVolume] = useMediaVolumeState();
const volumePropFrame = useFrameForVolumeProp(
loopVolumeCurveBehavior ?? 'repeat',
);
const userPreferredVolume = evaluateVolume({
frame: volumePropFrame,
volume,
mediaVolume,
});
const {isMutedForTimeline, isMutedForPlayback} = useMediaAudioState({
muted: muted ?? false,
volume: userPreferredVolume,
audioEnabled: true,
});
const getStack = useCallback(() => {
return _remotionInternalStack ?? null;
}, [_remotionInternalStack]);
const {registration} = useMediaInTimelineRegistration({
src,
mediaType: 'audio',
playbackRate: playbackRate ?? 1,
displayName: name ?? null,
id: timelineId,
getStack,
showInTimeline,
premountDisplay: sequenceContext?.premountDisplay ?? null,
postmountDisplay: sequenceContext?.postmountDisplay ?? null,
loopDisplay: undefined,
documentationLink: 'https://www.remotion.dev/docs/html5-audio',
muted: isMutedForTimeline,
});
const metadata = useMemo<CommittedMetadata | null>(
() =>
isStudio || registration !== null
? {
type: 'sequence',
id: timelineId,
value: registration,
outlineChildrenRef: null,
}
: null,
[isStudio, registration, timelineId],
);
return (
<CommittedMetadataProvider value={null} _remotionCommitMetadata={metadata}>
<SequenceContent>
<AudioForPreviewContent
{...props}
ref={ref}
timelineId={timelineId}
userPreferredVolume={userPreferredVolume}
isMutedForPlayback={isMutedForPlayback}
/>
</SequenceContent>
</CommittedMetadataProvider>
);
};
export const AudioForPreview = forwardRef(AudioForPreviewRefForwardingFunction);