Player

The Player class is a player controller that is decoupled from the player view. Create a Player instance using the PlayerProvider, and attach the video surface using the PlayerView when needed. The player instance can be accessed with the usePlayer hook to control playback. Other player hooks, such as usePosition and useDuration, allow responding to player events and creating custom controls.

PlayerProvider

The PlayerProvider component initializes the player and makes it accessible through the PlayerContext. It takes a player configuration to initialize a player instance:

<PlayerProvider playerConfig={{
  autoPlay: true,
  source: {
    url: 'https://demo.cf.castlabs.com/media/prestohls/master.m3u8',
    type: ContentType.Hls,
  },
}}>
  {/* component tree */}
</PlayerProvider>

PlayerProvider can be placed anywhere in the component tree. It supports multiple instances, with each PlayerProvider managing its own player. Additionally, it is possible to nest multiple PlayerProvider components.

PlayerView

The PlayerView component creates a video surface and attaches it to the player. It must be used within the scope of a PlayerProvider. However, the PlayerView doesn't need to be a direct child of the PlayerProvider; it just needs to be within its scope. For example:

<PlayerProvider playerConfig={playerConfig}>
  <PlayerView />
</PlayerProvider>

usePlayer

The usePlayer hook provides a programmatic way to interact with the player in functional components. Similar to the PlayerView component, the hook must be used within the scope of a PlayerProvider. Sample usage:

const player = usePlayer();
player.pause();

Other player hooks can be used to build custom player controls. For example, the usePosition and useDuration hooks can be used to build a time label:

export default function TimeLabel() {
  const position = usePosition(); // in milliseconds
  const duration = useDuration(); // in milliseconds
  return (<>{position} / {duration}</>);
}

For the full list of hooks, refer to the API documentation.