remotion-dev/remotion · critical · Error

useMediaPlayback must be used inside a <BufferingContext>

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.

Source

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

	pauseWhenBuffering: boolean;
	isPremounting: boolean;
	isPostmounting: boolean;
	onAutoPlayError: null | (() => void);
}) => {
	const {playbackRate: globalPlaybackRate} = usePlaybackRate();
	const frame = useCurrentFrame();
	const absoluteFrame = useTimelinePosition();
	const [playing] = usePlayingState();
	const buffering = useContext(BufferingContextReact);
	const {fps} = useVideoConfig();
	const mediaStartsAt = useMediaStartsAt();
	const lastSeekDueToShift = useRef<number | null>(null);
	const lastSeek = useRef<number | null>(null);
	const logLevel = useLogLevel();
	const mountTime = useMountTime();

	if (!buffering) {
		throw new Error(
			'useMediaPlayback must be used inside a <BufferingContext>',
		);
	}

	const isVariableFpsVideoMap = useRef<Record<string, boolean>>({});

	const onVariableFpsVideoDetected = useCallback(() => {
		if (!src) {
			return;
		}

		if (isVariableFpsVideoMap.current[src]) {
			return;
		}

		Log.verbose(
			{logLevel, tag: null},
			`Detected ${src} as a variable FPS video. Disabling buffering while seeking.`,

View on GitHub (pinned to 78fe4bb3fd)

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

• Tried to enable the buffering state, but a Remotion context
• No video config found. Likely reasons:- You are probably cal
• Called useVideoConfig() outside a Remotion composition.
• useCurrentScale() was called outside of a Remotion context.
• No src passed

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