The Streamroot Developer Hub

Welcome to the Streamroot developer hub. You'll find comprehensive guides and documentation to help you start working with Streamroot as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    
Suggest Edits

PeerAgent Class Reference

 

Overview

This API allows you to retrieve some information about the PeerAgent and interact with it.

PeerAgent instances are exposed on the window: window.Streamroot.peerAgents[<id>], where id is the identifier of the target PeerAgent instance.

You can obtain the list of <id> with the following Object.keys(window.Streamroot.peerAgent). So in the general case when you have only one PeerAgent instance on your page, you can access the data using window.Streamroot.peerAgents[Object.keys(window.Streamroot.peerAgents)[0]]

Declarations

Getting the PeerAgent version

(get) version

(get) version: string

Returns the version of the PeerAgent instance.

Stats

(get) stats

(get) stats: Object

Object containing the current PeerAgent instance statistics.

Content

cdn: number, data downloaded from CDN since the beginning of the session (in bytes).
p2p: number, data downloaded from P2P since the beginning of the session (in bytes).
upload: number, data uploaded since the beginning of the session (in bytes).
peers: number, realtime connected peers count.

Guidelines

The values of all listed properties are equal to 0 if P2P is deactivated.

(get) isP2PEnabled

(get) isP2PEnabled: boolean

true if P2P is available and activated. false otherwise.

(get, set) p2pDownloadOn

(get, set) p2pDownloadOn: boolean

Retrieves and sets a value determining whether the P2P download is enabled or not.

(get, set) p2pUploadOn

(get, set) p2pUploadOn: boolean

Retrieves and sets a value determining whether the P2P upload is enabled or not.

P2P state

Suggest Edits

Integration API

 

In addition to our plug-and-play integrations for popular players, we offer an API to allow you to integrate Streamroot's PeerAgent into a custom JavaScript media engine.

General concept

The PeerAgent module has been specifically designed for adaptive bitrate video streaming, maximizing p2p efficiency while ensuring the effectiveness of the adaptive bitrate mechanisms. It pre-fetches the video segments from the p2p network to offload the CDN as much as possible.

For that end, the PeerAgent module must have some interaction with the Player as described in this document.

General view of a Media Engine Architecture

The diagram below illustrates a general HTML5 media engine architecture.

Media Engine Architecture

Media Engine Architecture

The diagram below illustrates how Streamroot PeerAgent interacts with the Media player architecture.

Media Engine Architecture with Streamroot

Media Engine Architecture with Streamroot

Integration process

This custom integration is a three-step process, we suggest the following order:

  1. Implement the following interfaces to let your media engine share information with the PeerAgent module:
    • TrackView, exposing properties of media tracks.
    • SegmentView, exposing properties of media segments.
    • MediaMap, exposing manifest (or playlist) information.
  2. Implement the following interface:
  3. Use the peerAgent.getSegment method in place of the usual http requests.

Reference implementations

We have developed open-source wrappers based on this integration interface for the following popular media engines. You can refer to these implementations for reference.

Support

Please contact Streamroot if you encounter any issues during the integration. We are happy to see our PeerAgent module integrated into an increasing number of players.

If you prefer that we complete the integration into you custom player, please contact our Customer Service at contact@streamroot.io for more information.

And remember, if you need a quick solution, we provide plug and play integration for popular players as well!

Suggest Edits

PeerAgent

 

Overview

PeerAgent is the global object you will use to instantiate the different interfaces, and benefit from Streamroot's peer-accelerated delivery.

There are two ways to fetch PeerAgent: either through a CDN distribution or using npm.

CDN distribution

We have two releases channels on which you can fetch PeerAgent:

Name Description url
stable Stable release https://cdn.streamroot.io/peer-agent/stable/p2p.js
latest Latest release (including bug fixes and new features) https://cdn.streamroot.io/peer-agent/latest/p2p.js

In this case, the constructor is: window.Streamroot.Downloader.

Guidelines

We recommend using the stable release channel for the production environment and the latest release channel for the testing and pre-production environment.

npm distribution

The package name is: streamroot-p2p.

In this case, you can include PeerAgent with: import StreamrootPeerAgentModule from 'streamroot-p2p';

Declarations

PeerAgent lifecycle

constructor

constructor(playerInterface: PlayerInterface, contentUrl: string, mediaMap: MediaMap, p2pConfig: Object, segmentViewClass: class, streamType: string, integrationVersion: string)

Returns an initialized PeerAgent object.

Parameters

Name Type Description
playerInterface PlayerInterface a PlayerInterface instance
contentUrl string Url of the stream
mediaMap MediaMap a MediaMap instance
p2pConfig Object P2P configuration options. See p2pConfig
segmentViewClass class the constructor of your implementation of SegmentView
streamType string represents the stream type. See Stream types
integrationVersion string integration version to avoid incompatible peers to exchange data

Examples

Here is an example implementation with hls.js.
Here is an example implementation with dash.js.

dispose

dispose()

Clean up and remove the PeerAgent.

Examples

Here is an example implementation with hls.js.
Here is an example implementation with dash.js.

Guidelines

This is useful for playing a new video without refreshing the entire page. In this case, you simply need to call the method to delete the module, and then create a new one with your new url.

Stream types

StreamTypes

static StreamTypes: string

Object containing supported stream types.

Packaging Format
Key
Value

HLS

HLS

"hls"

MPEG-DASH

DASH

"dash"

Microsoft Smooth Streaming

SMOOTH

"smooth"

Fetching a segment

getSegment

getSegment(request: Object, callbacks: Object, segmentView: SegmentView): Object

Fetches the requested segment from the local P2P cache or from the CDN.

When calling this method, the requested segment is retrieved from the P2P cache. If the segment is absent or incomplete, the remaining part (or the entire segment if applicable) is downloaded from the CDN. Thus, in the worst case scenario (segment not downloaded from the P2P network at all), this method is equivalent to your usual http call to the CDN.

Parameters

Name Type Description
request Object contains the parameters for the http request
callbacks Object contains the callbacks for the http request
segmentView SegmentView instance of the SegmentView corresponding to the segment to fetch

request

  • url: string, containing the url to download the segment.
  • withCredentials: boolean, whether the http request should use credentials or not. Optional, default: false. See the XHR use case
  • headers: Object, containing any additional http headers for the http request (in key:value format). See http headers for reference.

callbacks

Success

Called when the segment has been fully downloaded.

key: onSuccess
value: function(segmentData: ArrayBuffer, stats: Object, request: Object)

Arguments:

Name Type Description
segmentData ArrayBuffer contains the data downloaded from the P2P network and/or the CDN
stats Object contains the request's stats. See Success and progress stats
request Object object passed to the getSegment method

Progress

key: onProgress
value: function(stats: Object, request: Object)

Arguments:

Name Type Description
stats Object contains the request's stats. See Success and progress stats
request Object object passed to the getSegment method

Error

Called when the request failed.

key: onError
value: function(httpError: Object, request: Object)

Arguments:

Name Type Description
httpError Object contains the http error
request Object object passed to the getSegment method

httpError:

  • status: number, status code returned by the server (or 0 in case of abort, timeout, or network error)
  • message: string, message describing the error

Return value

A segmentRequest object.

segmentRequest

  • abort(): Aborts the segment request.

Examples

Here is an example implementation with hls.js.
Here is an example implementation with dash.js.

Guidelines

  • Adapt your ABR algorithms if they are based on bandwidth estimations, taking into account P2P and http traffic separately. See the examples implementation with hls.js and dash.js for guidance.
  • change the abort() method of your downloader to use it way the segmentRequest does.

Success and progress stats

  • cdnDownloaded: number of bytes downloaded from the CDN.
  • cdnDuration: duration of the CDN download in milliseconds
  • p2pDownloaded: number of bytes downloaded from the P2P network.
  • p2pDuration: duration of the P2P download in milliseconds

Media element

setMediaElement

setMediaElement(mediaElement: Object)

Gives peerAgent access to the media element.

Parameters

Name Type Description
mediaElement Object provides media playback properties

mediaElement

  • duration: double, content duration in seconds.
  • currentTime: double, current position of the playhead, in seconds.
  • paused: boolean, true if the playback is currently paused. false if playing or buffering.
  • seeking: boolean, true if currently seeking, false if not.
  • buffered: TimeRanges, time ranges for which the mediaElement has media data readily available.

Guidelines

The HTML5 <video> tag can be used as a mediaElement.

Examples

Here is an example implementation with hls.js.
Here is an example implementation with dash.js.

Suggest Edits

PlayerInterface

 

Overview

The purpose of the PlayerInterface is to enable PeerAgent to interact with the player's ABR track switching decisions.

Declarations

Getting the stream properties

isLive

isLive(): boolean

Returns a boolean value that indicates whether the stream is live or VoD.

Return value

true if the stream is live, false otherwise.

Exceptions

This method must throw if called before the player knows if the stream is live or VoD.

Examples

Here is an example implementation with hls.js.
Here is an example implementation with dash.js.

Managing event listeners

addEventListener

addEventListener(eventName: string, callback: Function)

Registers an callback to a given player event name.

Parameters

Name Type Description
eventName string The name of the event for which to register the callback. See the Event name list.
callback Function Callback to be triggered when the event corresponding to the given eventName is fired.

Examples

Here is an example implementation with hls.js.
Here is an example implementation with dash.js.

Warning

Unless you implemented the optional TrackView#type, this event must be triggered at least once before the player attempts to load the first media segment.

removeEventListener

removeEventListener(eventName: string, callback: Function)

Unregisters an callback for a given player event name.

Parameters

Name Type Description
eventName string The name of the event for which to remove the callback. See the Event name list.
callback Function Callback to be unregister from the given eventName.

Examples

Here is an example implementation with hls.js.
Here is an example implementation with dash.js.

Event name list

Track change

This event must be fired when tracks are initialized, switched, or the Period (for MPEG-DASH) changed. It happens when the adaptive bitrate module decides to change the quality/track, before the first segment from the new track is downloaded.

Event name

"onTrackChange"

Arguments

Name Type Description
tracks Object An object containing the tracks being changed

tracks
It must contain at least one TrackView, of type either video or audio.

Examples

Here is an example implementation with hls.js.

Working with buffer levels (live streams only)

setBufferMarginLive

setBufferMarginLive(bufferLevel: number)

Sets the buffer level. (See Buffer Levels).

Parameters

Name Type Description
bufferLevel number Integer value (greater than or equal to 0)

Examples

Here is an example implementation with hls.js.
Here is an example implementation with dash.js.

Guidelines

This value can either represent a number of seconds or a number of video segments.
See Buffer Levels.

The upper and lower limits of this value are defined by a configuration parameter of PeerAgent.

Buffer levels in details

A buffer level is assigned to each peer and takes a dynamic value between limits defined in the PeerAgent configuration. The buffer level determines how many seconds a peer can buffer from your CDN. Limiting the number of seconds that can be buffered through your CDN guarantees that a peer will attempt to download the most recent segments from the peer-to-peer network first.

Peer A with a higher buffer level will download more segments from the CDN than Peer B with a lower buffer level. This way, Peer B can potentially download the most recent segments from Peer A instead of downloading these segments from the CDN.

PeerAgent will assign dynamically a value of Bufferlevel using setBufferMarginLive(), depending on the amount of data in the media buffer.

Suggest Edits

SegmentView

 

Overview

A SegmentView identifies a media segment, which is the atomic part of a HTTP video stream. It describes a media segment with its metadata.

Guidelines

This class is instantiated inside PeerAgent and you must never instantiate it yourself.

Declarations

Initializing SegmentViews

constructor

constructor(serializedSegmentView: Object)

Returns an initialized SegmentView object with properties set according to the serializedSegmentView parameter.

Parameters

Name Type Description
serializedSegmentView Object a serialized SegmentView using JSON.stringify(object)

Examples

Here is an example implementation with hls.js.
Here is an example implementation with dash.js.

Identifying and comparing SegmentViews

getId

getId(): number

Unique time based identifier.

Return value

The id associated to the segmentView.

Examples

Here is an example implementation with hls.js.
Here is an example implementation with dash.js.

Guidelines

The same segments on different viewers' devices must have the same id.

viewToString

viewToString(): string

Unique serialization of the segmentView.

Return value

The serialization associated to the current SegmentView instance.

Examples

Here is an example implementation with hls.js.
Here is an example implementation with dash.js.

Guidelines

The same segments on different viewers' devices must have the same string representation.

isEqual

isEqual(segmentView: SegmentView): boolean

Determines whether another SegmentView instance is exactly equal to the current SegmentView instance.

Parameters

Name Type Description
segmentView SegmentView another segmentView

Return value

true if the segments are the same, false otherwise.

Examples

Here is an example implementation with hls.js.
Here is an example implementation with dash.js.

Working with TrackViews

(get) trackView

(get) trackView: TrackView

The TrackView to which the segment belongs.

isInTrack

isInTrack(trackView: TrackView): boolean

Determines whether the current SegmentView instance belongs to the given trackView.

Parameters

Name Type Description
trackView TrackView another trackView

Return value

true if the segment belongs to the track, false otherwise.

Examples

Here is an example implementation with hls.js.
Here is an example implementation with dash.js.

Binary representation

toArrayBuffer

toArrayBuffer(): ArrayBuffer

Serializes the current SegmentView instance into binary so it can be sent from one peer to another through a peer connection.

Return value

An ArrayBuffer containing the binary representation of the current SegmentView instance.

Examples

Here is an example implementation with hls.js.
Here is an example implementation with dash.js.

Guidelines

The binary export of a segment will be transferred from one peer to another in every message sent. We highly recommend the use of a lightweight serialization to reduce the overhead.

fromArrayBuffer

static fromArrayBuffer(arrayBuffer: ArrayBuffer): SegmentView

Creates a SegmentView from its binary representation.

Parameters

Name Type Description
arrayBuffer ArrayBuffer the binary representation of a SegmentView

Return value

An initialized SegmentView object with properties set according to the arrayBuffer parameter.

Examples

Here is an example implementation with hls.js.
Here is an example implementation with dash.js.

Suggest Edits

TrackView

 

Overview

A TrackView represents a video or audio track for a given quality (and a given AdaptationSet for MPEG-DASH content).

Guidelines

PeerAgent only manipulates instances of TrackView and will never instantiate one itself, so there are no requirements on the constructor of this object.

Declarations

Identifying and comparing TrackViews

Properties

bitrate

Informative value of the track's bitrate. This property is optional and is used on our side for debug purposes.

Methods

viewToString

viewToString(): string

Unique serialization of the trackView.

Return value

The serialization associated to the current TrackView instance.

Examples

Here is an example implementation with hls.js.
Here is an example implementation with dash.js.

Guidelines

The same segments on different viewers' devices must have the same string representation.

isEqual

isEqual(trackView: TrackView): boolean

Determines whether another TrackView instance is exactly equal to the current TrackView instance.

Parameters

Name Type Description
trackView TrackView another trackView

Return value

true if the tracks are the same, false otherwise.

Examples

Here is an example implementation with hls.js.
Here is an example implementation with dash.js.

(get) type

(get) type: string (optional)

Represents the type of the track. Possible values are "audio" and "video".

Guidelines

This property is optional with the current version of PeerAgent (v4), but will become mandatory in the next version.

 

Overview

The MediaMap object offers an abstraction of the content of the manifest/playlist that PeerAgent uses to know what segment it should pre-fetch from the p2p network.

Guidelines

You must keep a single instance of MediaMap per instance of the PeerAgent that you may update on a regular basis (for live streaming). You should never get rid of this map object unless you already called the .dispose() method of the PeerAgent.

Declarations

Retrieving SegmentView and TrackView information

getSegmentTime

getSegmentTime(segmentView: SegmentView): number

Returns the starting timestamp of a given SegmentView.

Parameters

Name Type Description
segmentView SegmentView the segment whose starting time is asked

Return value

The starting timestamp of the given segmentView.

Examples

Here is an example implementation with hls.js.
Here is an example implementation with dash.js.

getSegmentList

getSegmentList(trackView: TrackView, beginTime: number, duration: number): [SegmentView]

Returns a list of segments in a given track and in a certain time range

Parameters

Name Type Description
trackView TrackView the track
beginTime number timestamp in seconds of the beginning of the timeframe we want to capture in the list
duration number duration in seconds of the timeframe we want to capture in the list

Return value

The list of SegmentView where every segment's starting time is between beginTime and beginTime + duration.

Examples

Here is an example implementation with hls.js.
Here is an example implementation with dash.js.

getTrackList

getTrackList(): [TrackView]

Returns a list of the available tracks in the current media stream.

Return value

The list of TrackView available in the current MediaMap.

Examples

Here is an example implementation with hls.js.
Here is an example implementation with dash.js.