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.