Skip to main content

Combatting autoplay issues

Browsers place restrictions on websites that play audio without user interaction. Read on how to properly use the Remotion Player so you don't run into a browser policy.

Trigger the play from a user event​

Don't autoplay audio on site load, or else browsers will block the audio. Instead, display a play button or use the controls prop.

Pass the event to the play() or toggle() method​

The play must be initialized from a user gesture, for example a mouse click. You should get a Javascript event like a MouseEvent from it. Pass this event to the play() or toggle() function so audio may play automatically.

tsx
import { PlayerRef } from "@remotion/player";
import { useRef } from "react";
 
export const App: React.FC = () => {
  const ref = useRef<PlayerRef>(null);
 
  return (
    <button
      onClickCapture={(e) => {
        const { current } = ref;
        // Pass the event to .play(), .pause() or .toggle()
        current?.play(e);
      }}
    >
      Play
    </button>
  );
};
tsx
import { PlayerRef } from "@remotion/player";
import { useRef } from "react";
 
export const App: React.FC = () => {
  const ref = useRef<PlayerRef>(null);
 
  return (
    <button
      onClickCapture={(e) => {
        const { current } = ref;
        // Pass the event to .play(), .pause() or .toggle()
        current?.play(e);
      }}
    >
      Play
    </button>
  );
};
info

Prefer the onClickCapture event instead of the onClick event to make the event propagation work properly in Safari.

Use the numberOfSharedAudioTags property​

If your audio does not enter the video immediately (say the few seconds of the video are silent, but then the audio fades in), it technically doesn't start based on an user integration. To combat this issue, you can use the numberOfSharedAudioTags property. This will play some silent audio on the first play with user interaction, and then reuse that tag to play your deferred audio playback.

You can have as many silent audio tags as you want. Set numberOfSharedAudioTags={2} to prepare two shared audio tags. Be mindful: If you set this props and you render more <Audio/> than there are shared audio tags, an exception will be thrown.

warning

Due to a bug on our side, this prop does not work well before Remotion v3.1.5. Upgrade to receive the bugfix.

Controlling the behavior of autoplay failuresv4.0.187​

If the browser blocks a video from being autoplayed due to it having sound, the video will be muted and will be retried once.
If you want to handle the error yourself, you can pass a callback to the onAutoPlayError prop of <OffthreadVideo> and <Video>.