The Streamrooter is the Streamroot interface to the outside world on browser environments.
Install
You can install the module to your repo with this command (or any NPM-equivalent):
npm install @streamroot/streamrooter
Usage
Here is a concise example describing Streamrooter interface.
import Streamrooter from '@streamrooot/streamrooter';
const sdk = new Streamrooter(streamrootKey, playerInterface, dnaConfig, yourIntegrationVersion);
sdk.load('your-manifest-url', Streamrooter.StreamTypes.HLS);
sdk.attachMediaElement(html5video);
...
const fetchRequest = sdk.fetch({
url: 'url-of-request-to-be-done',
contentType: Streamrooter.ContentTypes.MEDIA_SEGMENT,
responseType: Streamrooter.ResponseTypes.ARRAY_BUFFER,
...
}, {
onError: (...) => {...},
onSuccess: (...) => {...},
onProgress: (...) => {...}
});
...
sdk.detachMediaElement();
sdk.stop();
sdk.destroy();
API
Methods
constructor
new Streamrooter(
streamrootKey: String,
playerInterface: Object,
dnaConfig: Object,
integrationVersion: String) -> Streamrooter
Creates a new Streamrooter.
Arguments
- streamrootKey
This parameter is the customer unique key to allow Streamroot's tech to identify clients. - playerInterface
An object implementing the PlayerInterface described in this documentation, this object facilitate advanced interaction between the player and the Streamrooter. - dnaConfig
Streamroot's DNA config object described in this documentation. - integrationVersion
A short String describing the version of the integration glue code for identification/stats purpose.
load
streamrooter.load(contentURL: String, streamType: Streamrooter.StreamTypes)
Starts a DNA session. (To use when you start a new media content on your player)
DEPRECATED: From version 2.20 fetch-ing a MANIFEST will auto detect and initialize the session with correct manifest URL and manifest Type.
Arguments
- contentURL
The stream main URL. Must be compliant with the RFC 3986 - streamType
Accepted values are from the Streamrooter.StreamTypes Enum:- StreamTypes.HLS for HLS streams.
- StreamTypes.DASH for DASH streams.
- StreamTypes.SMOOTH for HSS streams.
fetch
streamrooter.fetch(config: FetchConfig, callbacks) -> FetchRequest
Fetch a given URL with CDN Mesh Delivery. Could be a manifest or a media segment. (NOTE: this API only support GET requests)
Arguments
- config
An object decribing the request to be made, it consists of the following fields:- url: String
The URL of your request. - contentType: ContentTypes
The type of request you are going to make, acceptable values:- Streamrooter.ContentTypes.MANIFEST
- Streamrooter.ContentTypes.MEDIA_SEGMENT
- responseType: ResponseTypes
The expecting response type of the request, acceptable values:- Streamrooter.ResponseTypes.TEXT (NOTE: Must be response type for ContentTypes.MANIFEST)
- Streamrooter.ResponseTypes.ARRAY_BUFFER (NOTE: Must be response type for ContentTypes.MEDIA_SEGMENT)
- headers: (optional) Object
A key-value object describing the headers of the request. - withCredentials: (optional) Boolean
Set to true to send cookies along with your request.
- url: String
- callbacks
An object containing callbacks to handle the different states (progress, success and error) of a request. The object structure contains:- onSuccess: Function (config: FetchConfig, data: String | ArrayBuffer, progress: FetchProgress)
Called when the request finished sucessfully with a 20x response.- config
The fetch config object used for this request. (NOTE: in this callback there could be an added responseURL if your request is re-directed on the server) - data
The response data depending on the declared ResponseType. - progress
An object describing the operational statistics of the requests following the XHR progress event spec.- timeElapsed
- latency
- lengthComputable
- loaded
- total
- config
- onError: Function (config: FetchConfig, error: FetchError)
Called when there is a problem when executing the request (CORS/blocked/etc.) or a non-20x response is received.- config
The fetch config used for this request. - error
An object describing the error encountered:- status: Number - non-20x error code or 0 for non HTTP errors.
- message: String - error details from the server.
- config
- onProgress: Function (config: FetchConfig, progress: FetchProgress)
- config
The fetch config used for this request - progress
An object describing the operational statistics of the requests following the XHR progress event spec. (Described in onSucess)
- config
- onSuccess: Function (config: FetchConfig, data: String | ArrayBuffer, progress: FetchProgress)
Returns
A FetchRequest object allowing to perform actions on this specific request. The object structure is:
- abort: Function ()
Function to call when you want to abort the fetch request. (NOTE: this will also trigger onError in FetchCallbacks)
attachMediaElement
attachMediaElement(mediaElement: HTMLMediaElement)
Attach a HTML5VideoElement to the Streamrooter.
Arguments
- mediaElement: HTML5VideoElement
The HTML5 Video Element for Streamrooter to monitor for QoS purposes.
detachMediaElement
detachMediaElement()
Let the Streamrooter know the previously attached media element is not relevant at the time being (mid-rolls for instance). You can reattach your media by calling attach
again.
stop
streamrooter.stop()
Stop the current DNA session, you can start a new one by calling load again. (To use when you change the media content of your player)
destroy
streamrooter.destroy()
Completely cleans up the Streamrooter. (NOTE: Any further call to the destroyed Streamrooter will fail)