Player Interface API

To be able to create an instance of Streamrooter you need to pass it an object implementing a PlayerInterface API, the role of this object is to:

• Handle triggers from the Streamrooter for player-manipulating features, some of them includes:
  • Setting buffer target for live stream to improve QoS.
  • Monitoring buffer target of player to optimize Mesh Delivery.
  • Gather statistics and/or information on the player to optimize internals of CDN Mesh Delivery.

EventEmitter-like methods (required)

First and foremost, the object must provide an EventEmitter-like interface which will then be hooked to Streamrooter's internal events.

on(eventName: Streamrooter.Events, handler: Function (...params))

Allows the Streamrooter to add an event listener to the PlayerInterface, which is expected to trigger some events:

// Inside the Streamrooter
const streamrootErrorHandler = (errorDetails) => {
    // The error is then trigger some Streamrooter's internal mechanisms
};
playerInterfaceObj.on(Streamrooter.Events.PLAYBACK_ERROR, streamrootErrorHandler);

removeListener(eventName: Streamrooter.Events, handler: Function (...params))

Allows the Streamrooter to unregister an event listener from the PlayerInterface when it is stopped or destroyed.

// Inside the Streamrooter
playerInterfaceObj.removeListener(Streamrooter.Events.PLAYBACK_ERROR, streamrootErrorHandler );

Events to be raised by the PlayerInterface

Streamrooter.Events.PLAYBACK_ERROR

• Raised when there is a fatal error from player.
• Handler parameters:
  • errorDetails: String
    Textual description of the error from player.

Streamrooter.Events.TRACK_SWITCH

• Raised when the player change the ABR video quality
• Handler parameters:
  • None

Player buffer target interactions (required for Live)

To improve the offload for live streaming, we need to be able to manipulate the player's buffer target on runtime.

getBufferTarget() -> Number | null

This method allows the Streamrooter to retrieve the current buffer target from the player.

• Returns

  • The player current buffer target in seconds or null if it is not possible to get the info.

// Inside the Streamrooter
playerInterface.getBufferTarget();
// -> Number or null if it is not possible to getBufferTarget

setBufferTarget(bufferTarget: Number)

This method allows the Streamrooter to set the buffer target in the player.

Arguments

• bufferTarget: Number
  The buffer target in seconds the player should be set to (NOTE: May be called with the same values multiple times)

// Inside the Streamrooter
playerInterface.setBufferTarget(30);

Player Information and Statistics

getPlayerInfo() -> Object

This method returns various information from the player. The return value should be an object with the following properties:

• bufferBasedABR: Boolean
  Informs us whether the player uses some flavor of buffer occupancy logic in its ABR algorithm (for example BOLA)
• playerInfo: Object (optional)
  Information about the outer player integrated with the SDK, for stats and monitoring purpose.
  • name: String
    Concise name if the integrated player. (Example: video.js, clappr, flowplayer etc.)
  • version: String
    Version of the integrated player.

// Inside the Streamrooter
playerInterface.getPlayerInfo()
// ->
{
    bufferBasedABR: true,
    playerInfo: {
        name: 'awesome-player',
        version: '6.66'
    }
}

getLatency() -> Number | null

Returns

• Player's current target Live latency in second or null if it is playing VoD or if it is not possible to obtain the value.

getMediaEngineName() -> String

Returns

• Name of the currently active internal media engine playing the current content. (Example: Dash.js, Hls.js, Shaka Player)

getMediaEngineVersion() -> String

Returns

• Version of the currently active internal media engine playing the current content.