remotion-dev/remotion · critical · Error

useMediaPlayback must be used inside a

Error message

useMediaPlayback must be used inside a <BufferingContext>

What it means

useMediaPlayback reads the BufferingContextReact context and throws if it is null. The provider is installed by Remotion's internal <BufferingContext> wrapper (set up by wrap-remotion-context / the Player and Studio trees). Seeing this means an Audio/Video media component is rendering outside that provider tree — typically because useMediaPlayback was called directly, or a media tag was rendered without the Remotion context wrapper.

Solutions

1. Do not call useMediaPlayback directly — use the public <Audio>/<Video> components, which set up the provider themselves.
2. Deduplicate Remotion: run `npm ls @remotion/core` and ensure a single resolved version; add an override/resolutions field if needed.
3. In tests, wrap the component under test in the Remotion test providers (see packages/core/src/test helpers using BufferingProvider).
4. If you forked a preview component, re-wrap it in <BufferingContextReact.Provider>.

Example fix

// before (test)
render(<Video src={url} />);

// after
render(
  <BufferingProvider>
    <Video src={url} />
  </BufferingProvider>
);

// Do not call useMediaPlayback directly. Use the public <Audio>/<Video> components.
// If testing, ensure a single Remotion version is installed:
// `npm ls @remotion/core` should list one resolved version.

When it happens

Trigger: Calling the internal useMediaPlayback hook directly in user code; rendering <AudioForPreview>/<VideoForPreview> (or Audio/Video in preview mode) without the buffering provider; multiple Remotion versions so the provider from one version does not satisfy the consumer from another; unit tests mounting media components without the test harness providers.

Common situations: Duplicate @remotion/core installations (context identity mismatch); importing internal preview components and using them standalone; test setups missing <RemotionRoot>/buffering providers; bundler misconfiguration that splits Remotion into two copies.

Related errors

• Called useVideoConfig() outside a Remotion composition.
• No video config found. Likely reasons:- You are probably…
• Tried to enable the buffering state, but a Remotion context…
• Expected video config
• No ref found

AI-assisted analysis of remotion-dev/remotion@b2f4e34732 (2026-08-12). Data as JSON: /api/errors/930345a2aa6108c4. Report an issue: GitHub.

Appendix: source

Thrown at packages/core/src/use-media-playback.ts:70

export const useMediaPlayback = ({
	mediaRef,
	src,
	mediaType,
	playbackRate: localPlaybackRate,
	preservePitch = true,
	onlyWarnForMediaSeekingError,
	acceptableTimeshift,
	pauseWhenBuffering,
	isPremounting,
	isPostmounting,
	onAutoPlayError,
}: {
	mediaRef: RefObject<HTMLVideoElement | HTMLAudioElement | null>;
	src: string | undefined;
	mediaType: 'audio' | 'video';
	playbackRate: number;
	preservePitch: boolean | undefined;
	onlyWarnForMediaSeekingError: boolean;
	acceptableTimeshift: number | null;
	pauseWhenBuffering: boolean;
	isPremounting: boolean;
	isPostmounting: boolean;
	onAutoPlayError: null | (() => void);
}) => {
	const {playbackRate: globalPlaybackRate} = usePlaybackRate();
	const frame = useCurrentFrame();
	const absoluteFrame = useTimelinePosition();
	const playing = usePlaying();
	const playerBuffering = useBuffering();
	const {fps} = useVideoConfig();
	const mediaStartsAt = useMediaStartsAt();
	const lastSeekDueToShift = useRef<number | null>(null);
	const lastSeek = useRef<number | null>(null);
	const logLevel = useLogLevel();
	const mountTime = useMountTime();

View on GitHub (pinned to b2f4e34732)