remotion-dev/remotion · error · TypeError

useAudioData requires a 'src' parameter

Error message

useAudioData requires a 'src' parameter

What it means

Thrown by the useAudioData() hook when `src` is falsy (line 24-25). It is a TypeError thrown synchronously during render, before any audio work, so React unmounts the component and the error surfaces through the nearest error boundary. The guard exists because the hook cannot delayRender without a target URL.

Source

Thrown at packages/media-utils/src/use-audio-data.ts:25

	sampleRate?: number;
	/**
	 * Captured only from the first render and passed to `fetch()`.
	 * Updates after mount are ignored so hooks do not depend on a new object
	 * identity every render (e.g. inline `{credentials: 'include'}`).
	 */
	requestInit?: RequestInit;
};

/*
 * @description Wraps the getAudioData() function into a hook and does three things: keeps the audio data in a state, wraps the function in a delayRender() / continueRender() pattern, and handles the case where the component gets unmounted while fetching is in progress to prevent React errors.
 * @see [Documentation](https://www.remotion.dev/docs/use-audio-data)
 */
export const useAudioData = (
	src: string,
	options?: UseAudioDataOptions,
): MediaUtilsAudioData | null => {
	if (!src) {
		throw new TypeError("useAudioData requires a 'src' parameter");
	}

	const mountState = useRef({isMounted: true});

	useEffect(() => {
		const {current} = mountState;
		current.isMounted = true;
		return () => {
			current.isMounted = false;
		};
	}, []);

	const [metadata, setMetadata] = useState<MediaUtilsAudioData | null>(null);
	const {delayRender, continueRender} = useDelayRender();
	const sampleRate = options?.sampleRate;
	const [initialRequestInit] = useState(options?.requestInit);

	const fetchMetadata = useCallback(async () => {

View on GitHub (pinned to 78fe4bb3fd)

Solutions

1. Ensure the src argument is a non-empty string before rendering the component that calls useAudioData.
2. Render the hook's component conditionally: only mount it once src is a valid non-empty string.
3. If audio is optional, render a placeholder until src resolves instead of calling the hook with an empty value.
4. Type the prop as string (not string | undefined) at the call site so TypeScript flags the missing value at compile time.

Example fix

// before (src may be empty -> TypeError)
const audio = useAudioData(src);

// after (mount hook only when src is ready)
return src ? <AudioVis src={src} /> : <Placeholder />;
// inside AudioVis:
const audio = useAudioData(src);

// Validate before rendering the component that uses the hook
function isValidSrc(src: unknown): src is string {
  return typeof src === 'string' && src.trim().length > 0;
}

// at the call site:
return isValidSrc(src) ? <AudioConsumer src={src} /> : <Placeholder />;

function isValidAudioSrc(src: unknown): src is string {
  return typeof src === 'string' && src.length > 0;
}

try {
  const audio = useAudioData(src);
} catch (err) {
  // note: this throws during render, so an ErrorBoundary is required to catch it
  throw err;
}

When it happens

Trigger: Calling useAudioData(undefined), useAudioData(null), useAudioData(''), or useAudioData(someProp) where the prop is not yet populated; passing a state variable before it has been set; passing 0 from a numeric id by mistake.

Common situations: Conditional audio where src comes from a fetch that has not resolved yet; defaulting a prop to undefined; passing a numeric index instead of a URL string; copy-paste from a schema where the field is optional.

Related errors

• The `<Html5Audio>` tag requires a string for `src`, but got
• You passed in a a function to the volume prop but it did not
• windowInSeconds cannot be changed dynamically
• inputRange must contain only numbers
• outputStyles must contain only objects

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