Skip to main content

Fallback from @remotion/media to <OffthreadVideo> or <Html5Audio>

Sometimes, a media file cannot be embedded using @remotion/media's <Video> and <Audio> tags.
In such cases, a fallback to <OffthreadVideo> or <Html5Audio> from the remotion package is attempted.

When a fallback is attempted​

Here are some cases where @remotion/media may fall back to <OffthreadVideo> or <Html5Audio> from remotion:

  • The resource fails to load due to CORS restrictions
  • The container format is not supported by Mediabunny
  • The codec cannot be decoded by WebCodecs (e.g. a H.265 stream during rendering)
  • The video has an alpha channel and the browser does not support WebGL which is required to decode the alpha channel. The default configuration of the headless browser does not have WebGL enabled.

Observing when a fallback happens​

If @remotion/media falls back to another tag, then a warning message will be logged in the render:

Cannot decode /public/video-h265.mp4, falling back to <OffthreadVideo>

If you are rendering on an environment where the logs are not immediately visible (e.g. Lambda), observe whether a fallback has happened by visiting the logs (e.g. CloudWatch).

Preventing a fallback from happening​

To prevent <Video> from falling back to <OffthreadVideo>, set the disallowFallbackToOffthreadVideo prop:

No fallback to OffthreadVideo
tsx
import {Video} from '@remotion/media';
 
export const MyComp: React.FC = () => {
  return <Video src="https://remotion.media/video.mp4" disallowFallbackToOffthreadVideo />;
};

To prevent <Audio> from falling back to <Html5Audio> from remotion, set the disallowFallbackToHtml5Audio prop:

No fallback to HTML5 audio tag
tsx
import {Audio} from '@remotion/media';
 
export const MyComp: React.FC = () => {
  return <Audio src="https://remotion.media/audio.mp3" disallowFallbackToHtml5Audio />;
};

If a fallback is prevented, the render will be cancelled instead.