/

Provisioning


Provisioning

The first step to set up an Adaptive Bitrate video streaming is to provide a provision of stream variants to the Stream Manager. This is achieved by making a POST request with a JSON object as payload:

Method:POST

URL: https://yourstreammanager.com/streammanager/api/3.1/admin/event/meta/live/mystream?accessToken=myaccessToken

Where:

  • yourstreammanager.com: is the url of your Stream Manager
  • mystream: is the top-level name (guid) of the stream to be published
  • accessToken: is the access token defined in the Stream Manager configuration.

The JSON object needs to have the following structure:

{
  "meta": {
      "authentication": {
      "username": "<username>",
      "password": "<password>"
     },
      "stream": [
        {
          "name": "<variant1_name>",
          "bandwidth": "<value>",
          "level": "1",
          "properties": {
          "videoHeight": <value>,
          "videoWidth": <value>,
          "videoFPS": <value>4
          }
         },
                 {
          "name": "<variant2_name>",
          "bandwidth": "<value>",
          "level": "2",
          "properties": {
          "videoHeight": <value>,
          "videoWidth": <value>,
          "videoFPS": <value>

          }
         },
                 {
          "name": "<variant3_name>",
          "bandwidth": "<value>",
          "level": "3",
          "properties": {
          "videoHeight": <value>,
          "videoWidth": <value>,
          "videoFPS": <value>

          }
         }
],
      "georules": {
      "regions": [
        "<location_names>"
      ],
      "restricted": "<restriction_status>"
    },
    "qos": "3"
  }
}

Where:

  • Stream: an array that defines, for each version of the same stream, an object with the stream’s level, name, bitrate, height and width, and frames per second (optional).
  • Authentication (optional): specifies the username and password that have been configured for the video stream if required.
  • Qos (optional): is an integer that indicates the quality of service that needs to be provided (currently 3 is the only valid level).
  • Georules (optional): based on the restricted boolean value, this specifies which regions should be allowed or restricted to subscribe to a video stream.

As an example, using mystream as the top-level name and defining three variants for the stream, the POST and JSON object would look like the following:

https://yourstreammanager.com/streammanager/api/3.1/admin/event/meta/live/mystream?accessToken=myaccessToken

{
  "meta": {
      "authentication": {
      "username": "",
      "password": ""
     },
      "stream": [
        {
          "name": "mystream_1",
          "bandwidth": "1000000",
          "level": "1",
          "properties": {
          "videoHeight": 1280,
          "videoWidth": 720,
          "videoFPS": 24
          }
         },
                 {
          "name": "mystream_2",
          "bandwidth": "750000",
          "level": "2",
          "properties": {
          "videoHeight": 640,
          "videoWidth": 360,
          "videoFPS": 24

          }
         },
                 {
          "name": "mystream_3",
          "bandwidth": "300000",
          "level": "3",
          "properties": {
          "videoHeight": 320,
          "videoWidth": 180,
          "videoFPS": 15

          }
         }
],
      "georules": {
      "regions": [
        "US"
      ],
      "restricted": "false"
    },
    "qos": "3"
  }
}

NOTE: It is critical to use the same aspect ratio for all variants, for an optimal subscriber ABR experience. See this list of 16:9 resolutions for some
NOTE #2: If the bitrates of consecutive variants are too far apart, ABR may not work.

A successful response will return an object with the top-level stream name and the meta field populated with the JSON object sent in the POST call:

{
    "name": "mystream",
    "scope": "live",
    "data": {
        "meta": {
            "authentication": {
                "username": "",
                "password": ""
            },
            "stream": [
                {
                    "name": "mystream_1",
                    "bandwidth": "10000000",
                    "level": "1",
                    "properties": {
                        "videoWidth": 1280,
                        "videoHeight": 720,
                        "videoFPS": 24
                    }
                },
                {
                    "name": "mystream_2",
                    "bandwidth": "800000",
                    "level": "2",
                    "properties": {
                        "videoWidth": 640,
                        "videoHeight": 360,
                        "videoFPS": 24
                    }
                },
                {
                    "name": "mystream_3",
                    "bandwidth": "350000",
                    "level": "3",
                    "properties": {
                        "videoWidth": 320,
                        "videoHeight": 180,
                        "videoFPS": 24
                    }
                }
            ],
            "georules": {
                "regions": [
                    "US"
                ],
                "restricted": "false"
            },
            "qos": "3"
        }
    },
    "updated": 1539880127208
}

It is possible to access the provision at any time through the Stream Manager API as follows:

Method:GET

URL: https://yourstreammanager.com/streammanager/api/3.1/admin/event/meta/live/mystream?accessToken=myaccessToken

Where:

  • yourstreammanager.com: is the host of your Stream Manager
  • mystream: is the GUID of the stream
  • accessToken: is the token defined in the Stream Manager configuration.