remotion-dev/remotion · error

Expected video config

Error message

Expected video config

What it means

AudioWaveform in Remotion Studio renders an audio waveform on the timeline, and it needs the current video configuration (fps, dimensions, etc.) via Internals.useUnsafeVideoConfig(). The hook returns null when the component is rendered outside a Remotion composition context. Since a waveform is meaningless without a composition, the component throws 'Expected video config' instead of rendering garbage.

Source

Thrown at packages/studio/src/components/AudioWaveform.tsx:77

}> = ({
	src,
	height,
	startFrom,
	durationInFrames,
	displayOffsetInFrames,
	displayDurationInFrames,
	visualizationWidth,
	volume,
	doesVolumeChange,
	muted,
	playbackRate,
	loopDisplay,
}) => {
	const [peaks, setPeaks] = useState<Float32Array | null>(null);
	const [error, setError] = useState<Error | null>(null);
	const vidConf = Internals.useUnsafeVideoConfig();
	if (vidConf === null) {
		throw new Error('Expected video config');
	}

	const waveformSampleRate = Math.ceil(
		vidConf.fps * TIMELINE_FRAME_WIDTH_AT_MAX_ZOOM,
	);

	const waveformCanvas = useRef<HTMLCanvasElement>(null);
	const volumeCanvas = useRef<HTMLCanvasElement>(null);
	const shouldRenderVolumeOverlay =
		doesVolumeChange && typeof volume === 'string';
	const parsedVolume = useMemo(() => parseVolume(volume), [volume]);
	const visibleVolume = useMemo((): WaveformVolume => {
		if (muted) {
			return 0;
		}

		return getVisibleWaveformVolume({
			displayDurationInFrames,

View on GitHub (pinned to a6a7485a9a)

Solutions

1. Ensure AudioWaveform is only rendered inside a composition context (e.g. within a Sequence/composition subtree in Studio)
2. Guard the render site: only mount AudioWaveform when a video config is available (check the Studio composition state first)
3. If used in tests/storybook, wrap the component with the Remotion context providers that supply a video config
4. Upgrade Remotion Studio packages in lockstep — mismatched @remotion/* versions can leave the context undefined

Example fix

// before
<AudioWaveform src={src} />
// after
{vidConf ? <AudioWaveform src={src} /> : null}

const vidConf = Internals.useUnsafeVideoConfig();
if (vidConf === null) {
  // don't render the waveform
  return null;
}

const hasVideoConfig = (c: unknown): c is VideoConfig =>
  c !== null && typeof c === 'object' && typeof (c as VideoConfig).fps === 'number';

try {
  renderWaveform(vidConf);
} catch (err) {
  if (err instanceof Error && err.message === 'Expected video config') {
    setError(err);
    return null;
  }
  throw err;
}

When it happens

Trigger: AudioWaveformInner (or AudioWaveform) is mounted while useUnsafeVideoConfig() returns null — i.e. outside a <Composition>/player context, or in a part of the Studio tree rendered before composition metadata is available.

Common situations: Rendering the component in a Storybook/test harness without a Remotion root; nesting it outside <RemotionRoot>/Sequence context; Studio internal state where no composition is selected; version upgrades that changed context provisioning.

Related errors

• <Clipper> has been removed as of Remotion v4.0.228. The nati
• useLogLevel must be used within a LogLevelProvider
• useMountTime must be used within a LogLevelProvider
• useCurrentFrame can only be called inside a component that w
• useCurrentFrame() can only be called inside a component that

AI-assisted analysis of remotion-dev/remotion@a6a7485a9a (2026-09-02). Data as JSON: /api/errors/1e3d5538de823b4f. Report an issue: GitHub.