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

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)

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.
• 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
  • 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. 
  • 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)

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)