{"record":{"id":"16123b9217d63abb","repo":"remotion-dev/remotion","slug":"the-freeze-prop-is-not-supported-on-html5audio","errorCode":null,"errorMessage":"The \"freeze\" prop is not supported on <Html5Audio />. Use <Sequence freeze={...}> to freeze media playback.","messagePattern":"The \"freeze\" prop is not supported on <Html5Audio />\\. Use <Sequence freeze=(.+?)> to freeze media playback\\.","errorType":"exception","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"packages/core/src/audio/html5-audio.tsx","lineNumber":61,"sourceCode":"\t\tpauseWhenBuffering,\n\t\tshowInTimeline,\n\t\tonError: onRemotionError,\n\t\tfreeze,\n\t\t...otherProps\n\t} = propsWithFreeze;\n\tconst {loop, freeze: _freeze, ...propsOtherThanLoop} = propsWithFreeze;\n\tconst {fps} = useVideoConfig();\n\tconst environment = useRemotionEnvironment();\n\tconst shouldPauseWhenBuffering = resolveV5Default(pauseWhenBuffering);\n\n\tif (environment.isClientSideRendering) {\n\t\tthrow new Error(\n\t\t\t'<Html5Audio> is not supported in @remotion/web-renderer. Use <Audio> from @remotion/media instead. See https://remotion.dev/docs/client-side-rendering/limitations',\n\t\t);\n\t}\n\n\tif (typeof freeze !== 'undefined') {\n\t\tthrow new TypeError(\n\t\t\t'The \"freeze\" prop is not supported on <Html5Audio />. Use <Sequence freeze={...}> to freeze media playback.',\n\t\t);\n\t}\n\n\tconst {durations, setDurations} = useContext(DurationsContext);\n\tif (typeof props.src !== 'string') {\n\t\tthrow new TypeError(\n\t\t\t`The \\`<Html5Audio>\\` tag requires a string for \\`src\\`, but got ${JSON.stringify(\n\t\t\t\tprops.src,\n\t\t\t)} instead.`,\n\t\t);\n\t}\n\n\tconst preloadedSrc = usePreload(props.src);\n\n\tconst onError: React.ReactEventHandler<HTMLAudioElement> = useCallback(\n\t\t(e) => {\n\t\t\t// eslint-disable-next-line no-console","sourceCodeStart":43,"sourceCodeEnd":79,"githubUrl":"https://github.com/remotion-dev/remotion/blob/78fe4bb3fdb5a2cd68724393d63cb223db333fa7/packages/core/src/audio/html5-audio.tsx#L43-L79","documentation":"Html5Audio is Remotion's lower-level audio element that wraps a native <audio> tag for preview/rendering. The 'freeze' prop is intentionally unsupported on it because freezing media playback must be coordinated at the Sequence level, not on individual media tags. Passing freeze directly to Html5Audio is rejected at mount so users reach for the correct primitive: <Sequence freeze={...}>.","triggerScenarios":"Rendering <Html5Audio src={...} freeze /> or <Html5Audio src={...} freeze={true} />. Also triggered by spreading an object that contains a freeze key into <Html5Audio {...spread} />, or by copying props from a <Video>/<Img> element (which do accept freeze) onto an audio element.","commonSituations":"Porting a <Video freeze> snippet to audio; using a shared prop object across media types; upgrading from a version where freeze was silently ignored on audio; auto-generating JSX from a template that injects freeze on every media tag.","solutions":["Remove the freeze prop from <Html5Audio> and wrap it in <Sequence freeze={frame}>...<Html5Audio .../>...</Sequence> instead.","If the prop arrived via a spread, destructure freeze out before passing the rest to <Html5Audio>.","Audit shared media-prop objects and split freeze out for audio consumers."],"exampleFix":"// before\n<Html5Audio src={audioUrl} freeze />\n\n// after\n<Sequence freeze={frame}>\n  <Html5Audio src={audioUrl} />\n</Sequence>","handlingStrategy":"type-guard","validationCode":"const isHtml5AudioProps = (p: Record<string, unknown>): boolean =>\n  !('freeze' in p) || p.freeze === undefined;\nif (!isHtml5AudioProps(props)) {\n  // strip freeze or wrap in <Sequence freeze>\n}","typeGuard":"const isFreezeFree = (\n  p: Record<string, unknown>,\n): p is Omit<typeof p, 'freeze'> => !('freeze' in p) || p.freeze === undefined;","tryCatchPattern":null,"preventionTips":["Never copy media props from <Video>/<Img> onto <Html5Audio> without filtering freeze.","Keep audio-specific prop objects separate from video prop objects.","Use TypeScript's exactOptionalPropertyTypes to surface unwanted freeze at compile time."],"tags":["audio","props","validation","react","html5-audio"],"backgroundTag":null,"analyzedSha":"78fe4bb3fdb5a2cd68724393d63cb223db333fa7","analyzedAt":"2026-08-12T17:18:50.444Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}