remotion-dev/remotion · error · Error

Tried to simultaneously mount ${numberOfAudioTags + 1} <Html

Error message

Tried to simultaneously mount ${numberOfAudioTags + 1} <Html5Audio /> tags at the same time. With the current settings, the maximum amount of <Html5Audio /> tags is limited to ${numberOfAudioTags} at the same time. Remotion pre-mounts silent audio tags to help avoid browser autoplay restrictions. See https://remotion.dev/docs/player/autoplay#using-the-numberofsharedaudiotags-prop for more information on how to increase this limit.

What it means

Remotion pre-mounts a fixed number of silent <audio> tags (numberOfSharedAudioTags, default 0 in many setups, higher in Player) to work around browser autoplay policies. When more <Html5Audio> elements mount simultaneously than available tags, registerAudio cannot find a free slot and throws. The limit exists because each audio tag is a pre-allocated, reused resource.

Source

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

		});
	}, [refs]);

	const registerAudio = useCallback(
		(options: {
			aud: AudioHTMLAttributes<HTMLAudioElement>;
			audioId: string;
			premounting: boolean;
			postmounting: boolean;
		}) => {
			const {aud, audioId, premounting, postmounting} = options;
			const found = audios.current?.find((a) => a.audioId === audioId);
			if (found) {
				return found;
			}

			const firstFreeAudio = takenAudios.current.findIndex((a) => a === false);
			if (firstFreeAudio === -1) {
				throw new Error(
					`Tried to simultaneously mount ${
						numberOfAudioTags + 1
					} <Html5Audio /> tags at the same time. With the current settings, the maximum amount of <Html5Audio /> tags is limited to ${numberOfAudioTags} at the same time. Remotion pre-mounts silent audio tags to help avoid browser autoplay restrictions. See https://remotion.dev/docs/player/autoplay#using-the-numberofsharedaudiotags-prop for more information on how to increase this limit.`,
				);
			}

			const {id, ref, mediaElementSourceNode} = refs[firstFreeAudio];
			const cloned = [...takenAudios.current];
			cloned[firstFreeAudio] = id;
			takenAudios.current = cloned;

			const newElem: AudioElem = {
				props: aud,
				id,
				el: ref,
				audioId,
				mediaElementSourceNode,
				premounting,

View on GitHub (pinned to 78fe4bb3fd)

Solutions

Increase numberOfSharedAudioTags on <Player> to at least the maximum number of <Html5Audio> tags that play at once (see https://remotion.dev/docs/player/autoplay#using-the-numberofsharedaudiotags-prop).
Stagger audio with <Sequence> so fewer tags are simultaneous.
Consolidate overlapping audio into a single pre-mixed track.

Example fix

// before
<Player numberOfSharedAudioTags={2} component={Comp} ... />
// Comp renders 4 <Html5Audio> at once

// after
<Player numberOfSharedAudioTags={4} component={Comp} ... />

Defensive patterns

Strategy: validation

Validate before calling

const maxSimultaneous = countSimultaneousAudio(composition);
// ensure numberOfSharedAudioTags >= maxSimultaneous before mounting <Player>

Prevention

Count the maximum number of <Html5Audio> tags that overlap at any frame and set numberOfSharedAudioTags higher.
Stagger audio with <Sequence> to reduce simultaneous tags.
Add a runtime check in dev that warns when the count approaches the limit.

When it happens

Trigger: Mounting N+1 <Html5Audio> components at the same frame when numberOfSharedAudioTags is N. Common with many overlapping audio tracks, a music+voice+sfx layer, or dynamically rendered lists of audio elements.

Common situations: Adding a new voiceover track on top of existing music and SFX; rendering a list of audio tags from data; default Player numberOfSharedAudioTags being too low for a scene with many simultaneous sounds.

Related errors

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