Skip to main content

API

<Player />​

A React component which takes the following props:

component or lazyComponent​

Pass a React component in directly or pass a function that returns a dynamic import. Passing neither or both of the props is an error.

note

Pass the same React component that you would pass to a <Composition>. Don't pass in a <Composition> or a component returning <Composition>

durationInFrames​

The duration of the video in frames. Must be an integer and greater than 0.

fps​

The frame rate of the video. Must be a number.

compositionWidth​

The width of the composition in pixels.

compositionHeight​

The height of the composition in pixels.

loop​

optional

Whether the video should restart when it ends. Default false.

autoPlay​

optional

Whether the video should start immediately after loaded. Default false.

controls​

optional

Whether the video should display a seek bar and a play/pause button. Default false.

showVolumeControls​

optional

Whether the video should display a volume slider and a mute button. Only has an effect if controls is also set to true. Default true.

allowFullscreen​

optional

Whether the video can go fullscreen. By default true.

clickToPlay​

optional

A boolean property defining whether you can play, pause or resume the video with a single click into the player. Default true if controls are true, otherwise false.

doubleClickToFullscreen​

optional

A boolean property defining whether you can go fullscreen and exit fullscreen in the video with double click into the player. If enabled, clicking on the video once will delay pausing the video for 200ms to wait for a possible second click. Default false.

spaceKeyToPlayOrPause​

optional

A boolean property defining whether you can play or pause a video using space key. If enabled, playing the video and subsequently pressing the space key pauses and resumes the video. Only works if controls is true. Default true.

inputProps​

optional

Pass props to the component that you have specified using the component prop. The Typescript definition takes the shape of the props that you have given to your component. Default undefined.

style​

optional

A regular style prop for a HTMLDivElement. You can pass a different height and width if you would like different dimensions for the player than the original composition dimensions.

numberOfSharedAudioTags​

optional - available since v.2.3.1

If you use an <Audio /> tag, it might not play in some browsers (specifically iOS Safari) due to browser autoplay policies. This is why the Remotion Player pre-mounts a set of audio tags with silent audio that get played upon user interaction. These audio tags can then be used to play real audio later and will not be subject to the autoplay policy of the browser.

This option controls how many audio tags are being rendered, the default is 5. If you mount more audio tags than shared audio tags are available, then an error will be thrown.

If you'd like to opt out of this behavior, you can pass 0 to mount native audio tags simultaneously as you mount Remotion's <Audio /> tags.

Once you have set this prop, you cannot change it anymore or an error will be thrown.

playbackRate​

optional

A number between -4 and 4 (excluding 0) for the speed that the Player will run the media.

A playbackRate of 2 means the video plays twice as fast. A playbackRate of 0.5 means the video plays twice as slow. A playbackRate of -1 means the video plays in reverse. Note that <Audio/> and <Video/> tags cannot be played in reverse, this is a browser limitation.

Default 1.

errorFallback​

optional

A callback for rendering a custom error message. See Handling errors section for an example.

renderLoading​

optional

A callback function that allows you to return a custom UI that gets displayed while the player is loading.

The first parameter contains the height and width of the player as it gets rendered.

tsx
const MyApp: React.FC = () => {
  // `RenderLoading` type can be imported from "@remotion/player"
  const renderLoading: RenderLoading = useCallback(({ height, width }) => {
    return (
      <AbsoluteFill style={{ backgroundColor: "gray" }}>
        Loading player ({height}x{width})
      </AbsoluteFill>
    );
  }, []);
 
  return (
    <Player
      fps={30}
      component={Component}
      durationInFrames={100}
      compositionWidth={1080}
      compositionHeight={1080}
      renderLoading={renderLoading}
    />
  );
};
tsx
const MyApp: React.FC = () => {
  // `RenderLoading` type can be imported from "@remotion/player"
  const renderLoading: RenderLoading = useCallback(({ height, width }) => {
    return (
      <AbsoluteFill style={{ backgroundColor: "gray" }}>
        Loading player ({height}x{width})
      </AbsoluteFill>
    );
  }, []);
 
  return (
    <Player
      fps={30}
      component={Component}
      durationInFrames={100}
      compositionWidth={1080}
      compositionHeight={1080}
      renderLoading={renderLoading}
    />
  );
};
info

A player needs to be loaded if it contains elements that use React Suspense, or if the lazyComponent props is being used.

PlayerRef​

You may attach a ref to the player and control it in an imperative manner.

tsx
import { useEffect, useRef } from "react";
import { Player, PlayerRef } from "@remotion/player";
import { MyComposition } from "./MyComposition";
 
const MyComp: React.FC = () => {
  const playerRef = useRef<PlayerRef>(null);
 
  useEffect(() => {
    if (playerRef.current) {
      console.log(playerRef.current.getCurrentFrame());
    }
  }, []);
 
  return (
    <Player
      ref={playerRef}
      durationInFrames={30}
      compositionWidth={1080}
      compositionHeight={1080}
      fps={30}
      component={MyComposition}
      // Many other optional props are available.
    />
  );
};
tsx
import { useEffect, useRef } from "react";
import { Player, PlayerRef } from "@remotion/player";
import { MyComposition } from "./MyComposition";
 
const MyComp: React.FC = () => {
  const playerRef = useRef<PlayerRef>(null);
 
  useEffect(() => {
    if (playerRef.current) {
      console.log(playerRef.current.getCurrentFrame());
    }
  }, []);
 
  return (
    <Player
      ref={playerRef}
      durationInFrames={30}
      compositionWidth={1080}
      compositionHeight={1080}
      fps={30}
      component={MyComposition}
      // Many other optional props are available.
    />
  );
};

The following methods are available on the player ref:

pause()​

Pause the video. Nothing happens if the video is already paused.

play()​

Play the video. Nothing happens if the video is already playing.

If you play the video from a user gesture, pass the SyntheticEvent in as an argument so browser autoplay restrictions do not apply.

toggle()​

Pauses the video if it's playing. Plays the video if it's paused.

If you play the video from a user gesture, pass the SyntheticEvent in as an argument so browser autoplay restrictions do not apply.

getCurrentFrame()​

Gets the current postition expressed as the current frame. Divide by the fps you passed to get the time in seconds.

isPlaying()​

Available from v2.5.7

Returns a boolean indicating whether the video is playing.

getContainerNode()​

Available from v2.4.2

Gets the container HTMLDivElement of the player. Useful if you'd like to manually attach listeners to the player element.

tsx
const playerRef = useRef<PlayerRef>(null);
 
useEffect(() => {
  if (!playerRef.current) {
    return;
  }
  const container = playerRef.current.getContainerNode();
  if (!container) {
    return;
  }
 
  const onClick = () => {
    console.log("player got clicked");
  };
 
  container.addEventListener("click", onClick);
  return () => {
    container.removeEventListener("click", onClick);
  };
}, []);
tsx
const playerRef = useRef<PlayerRef>(null);
 
useEffect(() => {
  if (!playerRef.current) {
    return;
  }
  const container = playerRef.current.getContainerNode();
  if (!container) {
    return;
  }
 
  const onClick = () => {
    console.log("player got clicked");
  };
 
  container.addEventListener("click", onClick);
  return () => {
    container.removeEventListener("click", onClick);
  };
}, []);

mute()​

Mutes the video.

unmute()​

Unmutes the video.

getVolume()​

Gets the volume of the video. The volume is a value between 0 and 1 and is initially 1.

setVolume()​

Arguments​

  • volume: number

Set the volume of the video. Must be a value between 0 and 1, otherwise an exception will be thrown.

isMuted()​

Returns a boolean specifying whether the video is muted.

seekTo()​

Arguments​

  • frame: number

Move the position in the video to a specific frame. If the video is playing, it will pause for a brief moment, then start playing again after the seek is completed.

isFullscreen()​

Returns a boolean whether the video is currently playing in fullscreen.

To observe the fullscreen state and react to changes, listen to the fullscreenchange event on the global document.

requestFullscreen()​

Requests the video to go to fullscreen. This method throws if the allowFullscreen prop is false or the browser doesn't support allow the player to go into fullscreen.

exitFullscreen()​

Exit fullscreen mode.

addEventListener()​

Start listening to an event. See the Events section to see the function signature and the available events.

removeEventListener()​

Stop listening to an event. See the Events section to see the function signature and the available events.

Events​

Using a player ref, you can bind event listeners to get notified of certain events of the player.

tsx
const playerRef = useRef<PlayerRef>(null);
 
useEffect(() => {
  if (!playerRef.current) {
    return;
  }
  playerRef.current.addEventListener("play", () => {
    console.log("playing");
  });
  playerRef.current.addEventListener("ratechange", () => {
    console.log("ratechange");
  });
  playerRef.current.addEventListener("pause", () => {
    console.log("pausing");
  });
 
  // See below for difference between `seeked` and `timeupdate`
  playerRef.current.addEventListener("seeked", (e) => {
    console.log("seeked to " + e.detail.frame);
  });
  playerRef.current.addEventListener("timeupdate", (e) => {
    console.log("time has updated to " + e.detail.frame);
  });
  playerRef.current.addEventListener("ended", (e) => {
    console.log("ended");
  });
  playerRef.current.addEventListener("error", (e) => {
    console.log("error", e.detail.error);
  });
}, []);
tsx
const playerRef = useRef<PlayerRef>(null);
 
useEffect(() => {
  if (!playerRef.current) {
    return;
  }
  playerRef.current.addEventListener("play", () => {
    console.log("playing");
  });
  playerRef.current.addEventListener("ratechange", () => {
    console.log("ratechange");
  });
  playerRef.current.addEventListener("pause", () => {
    console.log("pausing");
  });
 
  // See below for difference between `seeked` and `timeupdate`
  playerRef.current.addEventListener("seeked", (e) => {
    console.log("seeked to " + e.detail.frame);
  });
  playerRef.current.addEventListener("timeupdate", (e) => {
    console.log("time has updated to " + e.detail.frame);
  });
  playerRef.current.addEventListener("ended", (e) => {
    console.log("ended");
  });
  playerRef.current.addEventListener("error", (e) => {
    console.log("error", e.detail.error);
  });
}, []);

seeked​

Fired when the time position changes. You may get the current frame by reading it from e.detail.frame.

tsx
playerRef.current.addEventListener("seeked", (e) => {
  console.log("seeked to " + e.detail.frame); // seeked to 120
});
tsx
playerRef.current.addEventListener("seeked", (e) => {
  console.log("seeked to " + e.detail.frame); // seeked to 120
});

This event fires on every single frame update. Don't update your UI based on this event as it will cause a lot of rerenders. Use the timeupdate event instead.

ended​

Fires when the video has ended and looping is disabled.

play​

Fires when the video has started playing or has resumed from a pause.

ratechange​

Fires when the playbackRate has changed.

pause​

Fires when the video has paused or ended.

timeupdate​

Fires periodically when the video is playing. Unlike the seeked event, frames are skipped, and the event is throttled to only fire a few times a second.

tsx
playerRef.current.addEventListener("timeupdate", (e) => {
  console.log("current frame is " + e.detail.frame); // current frame is 120
});
tsx
playerRef.current.addEventListener("timeupdate", (e) => {
  console.log("current frame is " + e.detail.frame); // current frame is 120
});

error​

Fires when an error or uncaught exception has happened in the video.

You may get the error by reading the e.detail.error value:

tsx
ref.current?.addEventListener("error", (e) => {
  console.log("error ", e.detail.error); // error [Error: undefined is not a function]
});
tsx
ref.current?.addEventListener("error", (e) => {
  console.log("error ", e.detail.error); // error [Error: undefined is not a function]
});

Handling errors​

Since videos are written in React, they are prone to crashing. When a video throws an exception, you may handle the error using the error event. The video will unmount and show an error UI, but the host application (The React app which is embedding the player) will not crash. It is up to you to handle the error and to re-mount the video (for example by changing the key prop in React).

This feature is implemented using an error boundary, so only errors in the render function will be caught. Errors in event handlers and asynchronous code will not be reported and will not cause the video to unmount.

You can customize the error message that is shown if a video crashes:

tsx
const MyApp: React.FC = () => {
  // `ErrorFallback` type can be imported from "@remotion/player"
  const errorFallback: ErrorFallback = useCallback(({ error }) => {
    return (
      <AbsoluteFill
        style={{
          backgroundColor: "yellow",
          justifyContent: "center",
          alignItems: "center",
        }}
      >
        Sorry about this! An error occurred: {error.message}
      </AbsoluteFill>
    );
  }, []);
 
  return (
    <Player
      fps={30}
      component={Component}
      durationInFrames={100}
      compositionWidth={1080}
      compositionHeight={1080}
      errorFallback={errorFallback}
    />
  );
};
tsx
const MyApp: React.FC = () => {
  // `ErrorFallback` type can be imported from "@remotion/player"
  const errorFallback: ErrorFallback = useCallback(({ error }) => {
    return (
      <AbsoluteFill
        style={{
          backgroundColor: "yellow",
          justifyContent: "center",
          alignItems: "center",
        }}
      >
        Sorry about this! An error occurred: {error.message}
      </AbsoluteFill>
    );
  }, []);
 
  return (
    <Player
      fps={30}
      component={Component}
      durationInFrames={100}
      compositionWidth={1080}
      compositionHeight={1080}
      errorFallback={errorFallback}
    />
  );
};