Skip to main content

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

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

When a fallback is attempted​

Here are some cases where @remotion/media may fall back to <OffthreadVideo> or <Audio> 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)

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 {experimental_Video as 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 <Audio> from remotion, set the disallowFallbackToHtml5Audio prop:

No fallback to HTML5 audio tag
tsx
import {experimental_Audio as 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.