Use Player to start playing a WebRTC stream. You can use a controllable version using a WSController as connector, or change it to use a HTTPConnector (HTTP WHEP). By default it uses a WSController excepting if on Player.start you use a Connect.Params.endPoint prefixed with a http:// protocol. With a controllable connector you can change track during the playback, what is not possible with a HTTP(WHEP) connector.

In addition then a player with a controllable connector uses a MultiBitrate algorithm to switch track automatically regarding network congestion. You can disable it and fix manually a track by selecting it after a start call. At last it's possible to indicate which are tracks to play in first by setting audio and video tracks before start call. In this case it can be usefull to get metadata information about the stream before to play it, see Player.start to achieve it.

Example

const player = new Player();
// const player = new Player(isWHEP ? HTTPConnector : WSController);
player.onStart = stream => {
videoElement.srcObject = stream;
console.log('start playing');
}
player.onStop = _ => {
console.log('stop playing');
}
// optionnaly set initial video track to play before start() call
player.videoTrack = 1;
// start playback
player.start({
endPoint: address, // if address is prefixed by `http://` it uses a HTTPConnector (HTTP-WHEP) if Player is build without contructor argument
streamName: 'as+bc3f535f-37f3-458b-8171-b4c5e77a6137'
});
// Tracks are in a MBR mode: video track 1 can change regarding network congestion
...
// Fix video track to 2, disable MBR mode
player.videoTrack = 2;
...
player.stop();

Hierarchy

Constructors

  • Constructs a new Player instance, optionally with a custom connector This doesn't start the playback, you must call Player.start method By default if no connector is indicated it uses a WSController (WebSocket IController) excepting if Connect.Params.endPoint is prefixed with a http:// protocol in such case it uses instead a HTTPConnector (HTTP IConnector). To force a HTTPConnector build explicitly with HTTPConnector as Connector argument.

    Parameters

    • Optional Connector: (new (connectParams) => IConnector)

      Connector class to use for signaling, or nothing to let's Player.start method determines it automatically.

    Returns Player

    Example

    // Default build
    const player = new Player();
    player.start({
    endPoint: address, // if address is prefixed by `http://` it uses a HTTPConnector (HTTP-WHIP), otherwise it uses a WSController (WebSocket)
    streamName: 'as+bc3f535f-37f3-458b-8171-b4c5e77a6137'
    });
    // Force connector selection whatever the address used in endPoint
    const player = new Player(isWHIP ? HTTPConnector : WSController);
    player.start({
    endPoint: address, // optional protocol prefix has no incidence on connector selection
    streamName: 'as+bc3f535f-37f3-458b-8171-b4c5e77a6137'
    })

Properties

Connector?: (new (connectParams) => IConnector)

Type declaration

    • new (connectParams): IConnector
    • Connector class to use for signaling, or nothing to let's Player.start method determines it automatically.

      Parameters

      • connectParams: Params

      Returns IConnector

_audioTrack?: number
_audioTrackFixed?: boolean
_connector?: IConnector
_controller?: IController
_dataTracks: number[]
_metadata?: Metadata
_playingInfos?: PlayingInfos
_streamData?: IStreamData
_streamMetadata?: StreamMetadata
_videoTrack?: number
_videoTrackFixed?: boolean
log: ILog

Start a log

Param

Returns

a Log object with the levels of log to call

Accessors

  • get audioTrack(): undefined | number
  • Index of the audio track, can be undefined if player is not playing

    Returns undefined | number

  • set audioTrack(idx): void
  • Sets the current audio track to the index provided, it can be set before calling Player.start to select the initial audio track, or set after Player.start to fix track and disable MBR While playing you can set it to undefined to activate MBR when session is controllable

    Parameters

    • idx: undefined | number

    Returns void

  • get controller(): undefined | IController
  • Returns the IController instance when starting with a connector with controllable ability, or undefined if stream is not starting or stream is not controllable.

    Returns undefined | IController

  • get dataTracks(): number[]
  • The list of tracks currently receiving

    Returns number[]

  • set dataTracks(tracks): void
  • Set the data track ids to receive

    Parameters

    • tracks: number[]

    Returns void

  • get stream(): undefined | MediaStream
  • Playable media stream as specified by MediaStream

    Returns undefined | MediaStream

  • get streamName(): string
  • Stream name, for example as+bc3f535f-37f3-458b-8171-b4c5e77a6137

    Returns string

  • get videoTrack(): undefined | number
  • Index of the video track, can be undefined if player is not playing

    Returns undefined | number

  • set videoTrack(idx): void
  • Sets the current video track to the index provided, it can be set before calling Player.start to select the initial video track, or set after Player.start to fix track and disable MBR While playing you can set it to undefined to activate MBR when session is controllable

    Parameters

    • idx: undefined | number

    Returns void

Methods

  • Parameters

    • params: Params

    Returns void

  • Returns connection info, such as round trip time, requests sent and received, bytes sent and received, and bitrates NOTE: This call is resource-intensive for the CPU.

    Returns Promise<ConnectionInfos>

    A promise for a ConnectionInfos

  • Event unsubscription

    Parameters

    • name: "data" | "stop" | "state" | "start" | "metadata" | "playing" | "Data" | "Playing" | "Start" | "Stop" | "State" | "Metadata"

      Name of event without the 'on' prefix (ex: 'log' to 'onLog' event declared)

    • event: Function

      Unsubscriber Function, must be the one passed to on or once subscription methods

    Returns boolean

  • Event subscription

    Parameters

    • name: "data" | "stop" | "state" | "start" | "metadata" | "playing" | "Data" | "Playing" | "Start" | "Stop" | "State" | "Metadata"

      Name of event without the on prefix (ex: log to onLog event declared)

    • event: Function

      Subscriber Function

    • Optional options: {
          signal?: AbortSignal;
      }
      • Optional signal?: AbortSignal

        Optional AbortSignal to stop this or multiple subscriptions in same time

    Returns void

  • Event subscription only one time, once time fired it's automatically unsubscribe

    Parameters

    • name: "data" | "stop" | "state" | "start" | "metadata" | "playing" | "Data" | "Playing" | "Start" | "Stop" | "State" | "Metadata"

      Name of event without the on prefix (ex: log to onLog event declared)

    • event: Function

      Subscriber Function

    • Optional options: {
          signal?: AbortSignal;
      }
      • Optional signal?: AbortSignal

    Returns void

  • Starts playing the stream The connector is determined automatically from Connect.Params.endPoint if not forced in the constructor.

    Instead to use a Connect.Params you can prefer use a already built StreamMetadata instance to the same end-point, it allows to discover tracks in amount and initialize track selection to start playback.

    The multiBitrate option can take three different types of value:

    • A MBRParams object to configured the default MBRLinear implementation, default value {}
    • undefined to disable MBR management
    • Use a custom MBRAbstract implementation instance

    In addition you can disable MBR while playing by set audio or video track to an explicit value (Player.videoTrack and Player.audioTrack).

    Parameters

    • params: Params | StreamMetadata

      Connection parameters or a StreamMetadata object already connected to the same end-point Note that if you pass a StreamMetadata object its life-time management is fully delegated to the Player

    • multiBitrate: undefined | MBRParams | MBRAbstract = {}

      Multi-bitrate implementation or MBRParams to configure the default implementation

    Returns void

    Example

    // Default start with MBR activated
    player.start({
    endPoint: address,
    streamName: 'as+bc3f535f-37f3-458b-8171-b4c5e77a6137'
    });
    // Start with selected initial track, in using a StreamMetadata object preinitialized
    const streamMetadata = new StreamMetadata({
    endPoint: address,
    streamName: 'as+bc3f535f-37f3-458b-8171-b4c5e77a6137'
    });
    streamMetadata.onMetadata = metadata => {
    // start to play with higher bitrate selection (audios and videos are sorted by descending BPS)
    player.audioTrack = metadata.audios[0].idx;
    player.videoTrack = metadata.videos[0].idx;
    // give the streamMetadata channel to reuse instead of opening a new again
    player.start(streamMetadata);
    // Now MBR select automatically the best tracks regarding network congestion
    ...
    // Fix audioTrack to the high rendition (disable MBR for audio track)
    player.audioTrack = 1;
    ...
    // Reactivate MBR for audio
    player.audioTrack = undefined;
    }
  • Stops playing the stream

    Parameters

    • Optional error: PlayerError

      error description on an improper stop

    Returns void

Events

  • Event fired when data is received in the stream

    Parameters

    • time: number
    • track: number
    • data: any

    Returns void

  • Event fired when metadata is present in the stream

    Parameters

    Returns void

  • Event fired every second to report information while content plays

    Parameters

    Returns void

  • Event fired when streaming starts

    Parameters

    • stream: MediaStream

    Returns void

  • Event fired when streaming stops

    Parameters

    • Optional error: PlayerError

      error description on an improper stop

    Returns void

Generated using TypeDoc