Streamrooter API

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';

// Before actually loading the first manifest
const sdk = new Streamrooter(streamrootKey, playerInterface, dnaConfig, yourIntegrationVersion);
sdk.attachMediaElement(html5video);

... 

// Use this instead of performing your media manifest/segment request over XHR/fetch
const fetchRequest = sdk.fetch({
    url: 'url-of-request-to-be-done',
    contentType: Streamrooter.ContentTypes.MEDIA_SEGMENT,
    responseType: Streamrooter.ResponseTypes.ARRAY_BUFFER,
    ...
}, {
    onError: (...) => {...},
    onSuccess: (...) => {...},
    onProgress: (...) => {...}
});

...

// Before changing content/stopping playback session
sdk.detachMediaElement();
sdk.stop();

...

// When the player itself is destroyed
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. 

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 supports GET requests)

Arguments

• config
  An object describing 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.
  • timeout: (optional) Number
    HTTP request timeout in milliseconds, 0 for no timeout (default value if parameter is omitted).

• 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 successfully with a 20x response.
    • config
      The fetch config object used for this request. (NOTE: responseURL is added to the FetchConfig carrying the actual HTTP-requested URL, that may be changed by a server-side redirect. Also responseHeaders is also added carrying the headers included in the server's HTTP response)
      
    • 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
  • 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. (NOTE: responseHeaders is added carrying the headers included in the server's HTTP response)
    • 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. 
  • 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 onSuccess)

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)