remotion-dev/remotion · error · Error

Changing the AudioContext sample rate dynamically is not sup

Error message

Changing the AudioContext sample rate dynamically is not supported. The sample rate was initialized with ${initialSampleRate.current} Hz, but ${sampleRate} Hz was passed later.

What it means

The Web Audio AudioContext is constructed once with a fixed sampleRate (derived from the Player's previewSampleRate prop, default 48000). Browsers cannot re-sample an existing context, so Remotion captures the initial rate in a ref and throws if a later render passes a different value. Changing it would require tearing down and recreating the entire audio graph.

Source

Thrown at packages/core/src/audio/use-audio-context.ts:47

	}
};

export const useSingletonAudioContext = ({
	logLevel,
	latencyHint,
	audioEnabled,
	sampleRate,
}: {
	logLevel: LogLevel;
	latencyHint: AudioContextLatencyCategory;
	audioEnabled: boolean;
	sampleRate: number;
}) => {
	const env = useRemotionEnvironment();
	const initialSampleRate = useRef(sampleRate);

	if (sampleRate !== initialSampleRate.current) {
		throw new Error(
			`Changing the AudioContext sample rate dynamically is not supported. The sample rate was initialized with ${initialSampleRate.current} Hz, but ${sampleRate} Hz was passed later.`,
		);
	}

	const context = useMemo(() => {
		if (env.isRendering) {
			return null;
		}

		if (!audioEnabled) {
			return null;
		}

		if (typeof AudioContext === 'undefined') {
			warnOnce(logLevel);
			return null;
		}

View on GitHub (pinned to 78fe4bb3fd)

Solutions

Pass a constant literal for previewSampleRate (48000 is recommended).
If the rate must change, remount the Player with a key tied to the value.
Leave previewSampleRate unset to use the default 48000.

Example fix

// before
<Player previewSampleRate={sampleRate} ... />

// after
<Player key={sampleRate} previewSampleRate={sampleRate} ... />

Defensive patterns

Strategy: validation

Validate before calling

const SAMPLE_RATE = 48000; // constant
// <Player previewSampleRate={SAMPLE_RATE} key={String(SAMPLE_RATE)} .../>

Prevention

Pass a constant for previewSampleRate (48000 recommended).
Do not derive it from the loaded media at runtime.
Remount via key if you truly need a different rate.

When it happens

Trigger: Passing <Player previewSampleRate={rate} /> where rate is React state that changes (e.g. 44100 then 48000). Also triggered by a config-derived sample rate that flips during a session or via hot-reload.

Common situations: Exposing sample rate as a user setting; matching source media sample rate dynamically; switching between 44100 and 48000 based on the loaded clip.

Related errors

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