Skip to main content

API - @remotion/player

EXPERIMENTAL
This component may change in minor version updates. Monitor the documentation page to see breaking changes when upgrading.

Using the Remotion Player you can embed Remotion videos in any React app and customize the video content at runtime.

Demo#

Play the video, then tweak the parameters below the video.

Hi there!Your favorite color is
0:00 / 0:11

Enter your name:

Select your favorite color:

Installation#

To install the player, run the following command in a React project:

bash
npm i remotion @remotion/player
bash
npm i remotion @remotion/player

<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.

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.

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.

toggle()#

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

getCurrentFrame()#

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

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('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('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.

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.

Known issues#

Before we mark the player as stable, we are looking to improve in the following areas:

  • Better loading state than the current "Loading..." text.
  • Implement keyboard controls.
  • Customize error UI