Listening to events

There are two ways to receive Player and Source events:

  • Player.on and Source.on (since v1.31.0): subscribe to events in code, independent of any PlayerView. Use this to react to events of a player that is not shown (yet), or to receive the events of a specific Source.
  • PlayerView event props: pass callbacks such as onReady to the PlayerView. The view forwards them to Player.on of its player. Events that are specific to the PlayerView, such as onFullscreenEnter, are only available as props.

For a complete list of the available events, check PlayerEventMap and SourceEventMap and events.ts.

Player events via Player.on

Player.on registers a listener for an event name, and Player.off removes it again:

import { useEffect } from 'react';
import {
  PlayerErrorEvent,
  ReadyEvent,
  usePlayer,
} from 'bitmovin-player-react-native';

export default function PlayerScreen() {
  const player = usePlayer();

  useEffect(() => {
    const onReady = (event: ReadyEvent) => {
      console.log('Ready', event.timestamp);
    };
    const onPlayerError = (event: PlayerErrorEvent) => {
      console.error('Player error', event.message);
    };
    player.on('ready', onReady);
    player.on('playerError', onPlayerError);
    return () => {
      player.off('ready', onReady);
      player.off('playerError', onPlayerError);
    };
  }, [player]);

  // ...
}
  • The player emits its own events, and the source events of the active source, e.g. sourceLoaded.
  • Listeners can be registered before the player is initialized or before a source is loaded. They also receive the events of that load, such as playerActive.
  • All listeners are removed when the player is destroyed.
  • Registering the same listener twice for an event has no effect.

Source events via Source.on

Source.on receives all events of one specific source, including while it is not the active source of a player. This is useful with playlists, e.g. to know when a preloaded source has been loaded:

import {
  Source,
  SourceLoadedEvent,
  SourceType,
} from 'bitmovin-player-react-native';

const source = new Source({
  url: 'https://cdn.bitmovin.com/content/assets/streams-sample-video/sintel/m3u8/index.m3u8',
  type: SourceType.HLS,
  title: 'Sintel',
});

const onSourceLoaded = (event: SourceLoadedEvent) => {
  console.log(`${source.config?.title} is loaded`, event.source.duration);
};
source.on('sourceLoaded', onSourceLoaded);

player.loadSource(source);

// Later, once the listener is no longer needed:
source.off('sourceLoaded', onSourceLoaded);
  • Listeners can be registered before the source is loaded.
  • All listeners are removed when the source is destroyed.
📘

Player.on or Source.on for Sources?

Player.on only receives the source events of the source that is currently active. The only exception is sourceError, which the player also emits for inactive sources, without identifying the source. Use Source.on for the events of a specific source.

PlayerView event props

To register an event callback on the PlayerView, use the event name prefixed with on as a property:

const onReady = useCallback((event: ReadyEvent) => {
  console.log('Ready event');
}, []);
...

return (
  <PlayerView
    player={player}
    onReady={onReady}
    onMuted={onMuted}
    onPaused={onPaused}
    onPlayerActive={onPlayerActive}
    onSourceLoaded={onSourceLoaded}
    onPlayerError={onPlayerError}
    onSourceError={onSourceError}
    onPlaybackFinished={onPlaybackFinished}
    ...
  />
);

The PlayerView registers these props via Player.on of its player while it is mounted, and removes them via Player.off when it unmounts. They therefore receive the same events as Player.on, but only while the view is mounted. Fullscreen and picture-in-picture events, such as onFullscreenEnter, come from the view itself and are only available as props.

Known limitations

  • On Android, SourceUnloadedEvent.source is not set for events received via Player.on or the PlayerView props, as the native event does not carry the source. Use Source.on to receive it with the source.
  • Source.on listeners do not receive the final sourceUnloaded of a source that is destroyed together with its player. Player.on listeners and the onSourceUnloaded prop receive it for the active source.

Did this page help you?