remotion-dev/remotion · error · Error

The number of shared audio tags has changed dynamically. Onc

Error message

The number of shared audio tags has changed dynamically. Once you have set this property, you cannot change it afterwards.

What it means

numberOfAudioTags (passed to SharedAudioTagsContextProvider, surfaced via the Player's numberOfSharedAudioTags prop) sets how many silent <audio> tags Remotion pre-mounts to dodge browser autoplay restrictions. The provider captures the initial count in useState and allocates refs/contexts once; a different count on a later render is rejected because the pre-mounted audio infrastructure cannot be safely resized.

Source

Thrown at packages/core/src/audio/shared-audio-tags.tsx:591

		_experimentalKeepAudioContextAlive,
	]);

	return (
		<SharedAudioContext.Provider value={audioContextValue}>
			{children}
		</SharedAudioContext.Provider>
	);
};

export const SharedAudioTagsContextProvider: React.FC<{
	readonly numberOfAudioTags: number;
	readonly children: React.ReactNode;
}> = ({children, numberOfAudioTags}) => {
	const audios = useRef<AudioElem[]>([]);
	const [initialNumberOfAudioTags] = useState(numberOfAudioTags);

	if (numberOfAudioTags !== initialNumberOfAudioTags) {
		throw new Error(
			'The number of shared audio tags has changed dynamically. Once you have set this property, you cannot change it afterwards.',
		);
	}

	const logLevel = useLogLevel();
	const mountTime = useMountTime();
	const env = useRemotionEnvironment();
	const audioCtx = useContext(SharedAudioContext);
	const audioContext = audioCtx?.audioContext ?? null;
	const resume = audioCtx?.resume;

	const [refs] = useState(() => {
		return new Array(numberOfAudioTags).fill(true).map((): Ref => {
			const ref = createRef<HTMLAudioElement>();
			return {
				id: Math.random(),
				ref,
				mediaElementSourceNode: makeSharedElementSourceNode({

View on GitHub (pinned to 78fe4bb3fd)

Solutions

Pass a constant literal for numberOfSharedAudioTags.
If the count must change, remount the Player with a key tied to the value.
Pick a single value that covers your worst-case simultaneous audio count and keep it fixed.

Example fix

// before
<Player numberOfSharedAudioTags={audioCount} ... />

// after
<Player key={audioCount} numberOfSharedAudioTags={audioCount} ... />

Defensive patterns

Strategy: validation

Validate before calling

const AUDIO_TAG_COUNT = 5; // constant
// <Player numberOfSharedAudioTags={AUDIO_TAG_COUNT} key={String(AUDIO_TAG_COUNT)} .../>

Prevention

Pass a literal for numberOfSharedAudioTags.
Size it once to your worst-case simultaneous audio count.
Remount the Player (via key) rather than mutating the value.

When it happens

Trigger: Passing <Player numberOfSharedAudioTags={count} /> where count is React state that changes. Also triggered by deriving the count from window width or a settings panel that updates during playback.

Common situations: Tying audio tag count to a user-configurable setting; re-rendering the Player from a parent that computes the count dynamically; hot-reloading in Studio with a different count.

Related errors

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