Mixer APIs
Mixer Provisioning API
The Mixer node exposes an API for the Stream Manager to provision it. The Stream Manager creates the provision object using the data included in the create-composition API. The mixer starts its composition when a provision is posted and publishes its composite stream.
Post Provision
Description
Post a mixing provision to start a composition.
REQUEST
- URI:
http://{host}:5080/mixer/publish?
action=start
&event=<event-name>
&sessionId=<session-name>
&digest=<password>
&streamName=<composite-stream-name>
&path=<composite-stream-scope>
&doForward=<true|false>
&originIP=<IP-server-to-forward-composite-stream-to>
&width=<width-composite-stream>
&height=<height-composite-stream>
&framerate=<framerate-composite-stream>
&bitrate=<bitrate-composite-stream>
&splashUrl=Base64(<URL-mixing-page>)
- Method: POST
RESPONSE
- Success: HTTP CODE
200
- DATA: (none)
- Failure: HTTP CODE 400 or 404
- Data:
{
"status": "error",
"meesage": <error-message>
}
Example
- URI:
http://{host}:5080/mixer/publish?
action=start
&event=event1
&sessionId=session1
&digest=password
&streamName=out
&path=live
&doForward=true
&originIP=129.168.0.152
&width=1280
&height=720
&framerate=30
&bitrate=1500
&splashUrl=aHR0cHM6Ly93d3cueW91dHViZS5jb20v
- Method: POST
RESPONSE
- Success: HTTP CODE
200
- DATA: (none)
Delete Provision
Description
When a user calls the Delete Composition API, the Stream Manager will call the following Mixer API on all mixers of a composition to delete the composition:
REQUEST
- URI:
http://{host}:5080/mixer/publish?
action=stop
&event=<event-name>
&sessionId=<session-name>
&digest=<password>
&streamName=<composite-stream-name>
- Method: POST
RESPONSE
- Success: HTTP CODE
200
- DATA: (none)
- Failure: HTTP CODE 400 or 404
- Data:
{
"status": "error",
"meesage": <error-message>
}
Example
- URI:
http://{host}:5080/mixer/publish?
action=stop
&event=event1&
&sessionId=session1&
&digest=password&
&streamName=out
- Method: POST
RESPONSE
- Success: HTTP CODE
200
- DATA: (none)
Mixer Composition API
Create Composition
Description
Create a mixer composition.
REQUEST
- URI:
http://{host}:{port}/streammanager/api/4.0/composition?accessToken=<accessToken>
- Method: POST
- DATA:
{
"event": "<event-name>",
"transcodeComposition": <true|false>,
"digest": "<round-trip-authentication-password>",
"mixers": [
{
"mixerName":"<mixer-name>",
"mixingPage":"<URL-mixing-page>",
"streamName": "<composite-stream-name>",
"path":"<composite-stream-scope>",
"width":<width-composite-stream>,
"height":<height-composite-stream>,
"framerate":<framerate-composite-stream>,
"bitrate":<bitrate-kbps-composite-stream>,
"doForward": true,
"destinationMixerName":"<destination-mixer-name>"
},
{
"mixerName":"<mixer-name>",
"mixingPage":"<URL-mixing-page>",
"streamName": "<composite-stream-name>",
"path":"<composite-stream-scope>",
"width":<width-composite-stream>,
"height":<height-composite-stream>,
"framerate":<framerate-composite-stream>,
"bitrate":<bitrate-kbps-composite-stream>,
"doForward": true,
"destinationMixerName":"<destination-mixer-name>"
},
],
"location":[
"<mixer-region>"
]
}
Note 1: When provisioning the Mixer, the Stream Manager appends
&type=cef&cef-id=<sm-generated-id>
to the end of themixingPage
URL. In this way, the page can process thecef-id
URL parameter to determine on what mixer instance it was loaded. This is useful for remotely controlling the compositions in multiple mixer nodes.
Note 2: The existing implementation does not support creating new mixer instances on the fly. Therefore, if a composition requires n mixers, then there must be a node group with at least n mixers that are
inservice
before making the create composition call. If there are less mixers than requested unpredictable behaviour may be observed.
RESPONSE
- Success: HTTP CODE
200
- DATA:
{
"event": "<event-name>",
"transcodeComposition": <true|false>,
"digest": "<round-trip-authentication-password>",
"location": [
"<mixer-region>"
],
"mixers": [
{
"id": "<sm-generated-id>",
"mixerName": "<mixer-name>",
"location": "<mixer-region>",
"mixingPage": "<URL-mixing-page>",
"streamName": "<composite-stream-name>",
"path":"<composite-stream-scope>",
"width":<width-composite-stream>,
"height":<height-composite-stream>,
"framerate":<framerate-composite-stream>,
"bitrate":<bitrate-kbps-composite-stream>,
"destinationMixerName": "<destination-mixer-name>",
"serverAddress": "<mixer-IP>",
"destination": "<destination-node-IP>",
"doForward": true,
"state": "INSERVICE"
},
{
"id": "<sm-generated-id>",
"mixerName": "<mixer-name>",
"location": "<mixer-region>",
"mixingPage": "<URL-mixing-page>",
"streamName": "<composite-stream-name>",
"path":"<composite-stream-scope>",
"width":<width-composite-stream>,
"height":<height-composite-stream>,
"framerate":<framerate-composite-stream>,
"bitrate":<bitrate-kbps-composite-stream>,
"destinationMixerName": "<destination-mixer-name>",
"serverAddress": "<mixer-IP>",
"destination": "<destination-node-IP>",
"doForward": true,
"state": "INSERVICE"
}
]
}
- Failure: HTTP CODE 400 or 404
- Data:
{
"errorMessage": "<error-message-string>",
"timestamp": <error-timestamp>
}
Example
REQUEST URI: https://streammanagerurl.red5pro.com/streammanager/api/4.0/composition?accessToken=xyz123
- Method: POST
- Data: JSON
{
"event": "test1",
"transcodeComposition": false,
"digest": "password",
"mixers": [
{
"mixerName":"mixer1",
"mixingPage":"https://test.red5pro.com/mixerpage1.html",
"streamName": "stream01",
"path":"live",
"width": 1280,
"height": 720,
"framerate": 30,
"bitrate": 1500,
"doForward": true,
"destinationMixerName":"mixer2"
},
{
"mixerName":"mixer2",
"mixingPage":"https://test.red5pro.com/mixerpage2.html",
"streamName": "stream02",
"path":"live",
"width": 1280,
"height": 720,
"framerate": 30,
"bitrate": 1500,
"doForward": true,
"destinationMixerName":""
}
],
"location":[
"nyc3"
]
}
RESPONSE
- Success: HTTP CODE 201
- Data:
{
"event": "test1",
"transcodeComposition": false,
"digest": "password",
"location": [
"nyc3"
],
"mixers": [
{
"id": "nex83node-nyc3-1615320241113",
"mixerName": "mixer1",
"location": "nyc3",
"mixingPage": "https://test.red5pro.com/mixerpage1.html",
"streamName": "stream01",
"path": "live",
"destinationMixerName": "mixer2",
"serverAddress": "{mixer1 IP address}",
"destination": "{mixer2 IP address}",
"width": 1280,
"height": 720,
"framerate": 30,
"bitrate": 1500,
"doForward": true,
"state": "INSERVICE"
},
{
"id": "nex83node-nyc3-1615320241115",
"mixerName": "mixer2",
"location": "nyc3",
"mixingPage": "https://test.red5pro.com/mixerpage2.html",
"streamName": "stream02",
"path": "live",
"destinationMixerName": "",
"serverAddress": "{mixer2 IP address}",
"destination": "{origin1 IP address}",
"width": 1280,
"height": 720,
"framerate": 30,
"bitrate": 1500,
"doForward": true,
"state": "INSERVICE"
}
]
}
List Compositions
DESCRIPTION:
Lists compositions that are provisioned through the Stream Manager.
- URI:
http://{host}:{port}/streammanager/api/4.0/composition?accessToken=<accessToken>
METHOD: GET
RESPONSE
- Failure: HTTP CODE 400 or 404
- Data:
{
"errorMessage": "<error-message-string>",
"timestamp": <error-timestamp>
}
- SUCCESS: HTTP CODE 200
- Data:
[
"<composition1>",
"<composition2>",
"<composition3>"
]
Example: Lists the provisioned compositions.
REQUEST URI: https://streammanager.url.com/streammanager/api/4.0/composition?accessToken=xyz123
Method: GET
RESPONSE
- Success: HTTP CODE 201
- Data:
[
"test9",
"test8",
"test1"
]
Read Composition
DESCRIPTION:
Reads and returns details of a composition.
- URI:
http://{host}:{port}/streammanager/api/4.0/composition/{composition-name}?accessToken=<accessToken>
METHOD: GET
RESPONSE
- Failure: HTTP CODE 400 or 404
- Data:
{
"errorMessage": "<error-message-string>",
"timestamp": <error-timestamp>
}
- SUCCESS: HTTP CODE
-
DATA::
{ "event": "<event-name>", "transcodeComposition": <true|false>, "digest": "<round-trip-authentication-password>", "location": [ "<mixer-region>" ], "mixers": [ { "id": "<sm-generated-id>", "mixerName": "<mixer-name>", "location": "<mixer-region>", "mixingPage": "<URL-mixing-page>", "streamName": "<composite-stream-name>", "path":"<composite-stream-scope>", "width":<width-composite-stream>, "height":<height-composite-stream>, "framerate":<framerate-composite-stream>, "bitrate":<bitrate-kbps-composite-stream>, "destinationMixerName": "<destination-mixer-name>", "serverAddress": "<mixer-IP>", "destination": "<destination-node-IP>", "doForward": true, "state": "INSERVICE" }, { "id": "<sm-generated-id>", "mixerName": "<mixer-name>", "location": "<mixer-region>", "mixingPage": "<URL-mixing-page>", "streamName": "<composite-stream-name>", "path":"<composite-stream-scope>", "width":<width-composite-stream>, "height":<height-composite-stream>, "framerate":<framerate-composite-stream>, "bitrate":<bitrate-kbps-composite-stream>, "destinationMixerName": "<destination-mixer-name>", "serverAddress": "<mixer-IP>", "destination": "<destination-node-IP>", "doForward": true, "state": "INSERVICE" } ] }
Example: Reads mixer composition details.
REQUEST URI: https://streammanager.url.com/streammanager/api/4.0/composition/test1?accessToken=xyz123
Method: GET
RESPONSE
- Success: HTTP CODE 200
- Data:
{
"event": "test1",
"transcodeComposition": false,
"digest": "password",
"location": [
"nyc3"
],
"mixers": [
{
"id": "nex83node-nyc3-1615320241113",
"mixerName": "mixer1",
"location": "nyc3",
"mixingPage": "https://test.red5pro.com/mixerpage1.html",
"streamName": "stream01",
"path": "live",
"destinationMixerName": "mixer2",
"serverAddress": "209.97.159.55",
"destination": "159.203.113.122",
"width": 1280,
"height": 720,
"framerate": 30,
"bitrate": 1500,
"doForward": true,
"state": "INSERVICE"
},
{
"id": "nex83node-nyc3-1615320241115",
"mixerName": "mixer2",
"location": "nyc3",
"mixingPage": "https://test.red5pro.com/mixerpage2.html",
"streamName": "stream02",
"path": "live",
"destinationMixerName": "",
"serverAddress": "159.203.113.122",
"destination": "167.172.235.187",
"width": 1280,
"height": 720,
"framerate": 30,
"bitrate": 1500,
"doForward": true,
"state": "INSERVICE"
}
]
}
Delete Composition
DESCRIPTION
Deletes a mixer composition from Stream Manager data store by a given event name. It does not delete the mixer instances.
- URI:
http://{host}:{port}/streammanager/api/4.0/composition{composition-name}?accessToken=<accessToken>
- METHOD: DELETE
RESPONSE
- Failure: HTTP CODE 400 or 404
- Data:
{
"errorMessage": "<error-message-string>",
"timestamp": <error-timestamp>
}
SUCCESS
- CODE: 200
- DATA: (none)
Example: Deletes the composition created earlier
- URI:
https://streammanager.url.com/streammanager/composition/test1?accessToken=xyz123
- Method: DELETE
RESPONSE
- Success: HTTP CODE 200
- DATA: (none)
Mixer Conference API
- Create Conference
- List Conferences
- Read Conference Provision
- Join Conference
- Delete Conference Provision
Use the Mixer Conference API
to create a WebRTC video conference, where participants are provided with a program feed and mix-minus audio of the conference. The Conference API
is used with the Mixer Composition API to create video conferences where participants watch a composite stream that includes all participants while listening to a mix minus audio feed.
Note: The Conference API is currently limited to WebRTC publishers and subscribers.
Create Conference
Description
Create a conference.
REQUEST
- URI:
http://{host}:{port}/streammanager/api/4.0/admin/event/meta/{scope}/{room-name}/{room-name}?accessToken=<accessToken>
- Method: POST
-
DATA:
{ "guid": "<scope>/<room-name>", "context": "<scope>/<room-name>", "name": "<room-name>", "level": 0, "isRestricted": false, "parameters": { "group": "webrtc", "audiotracks": <audio-tracks-returned-to-participant>, "videotracks": <video-tracks-returned-to-participant> }, "restrictions": [], "primaries": [], "secondaries": [] }
When a conference provision for {scope}/{room-name}/{room-name}
is created, every WebRTC live stream published using the new HTML5 SDK RTCConferenceParticipant
in {scope}/{room-name}/{stream-name}
will be part of the conference. As a result of that, the audio packets of that stream will be processed to generate the mix minus tracks for the participants. Additionally, the RTCConferenceParticipant
will receive back the video feed {scope}/{room-name}/{room-name}
that could include a composition of the conference or a program feed and the mix minus audio tracks with the audio of the other participants.
RESPONSE
- Success: HTTP CODE
200
- DATA:
{
"name":"<room-name>",
"scope":"<scope>",
"data": {
"guid": "<scope>/<room-name>",
"context": "<scope>/<room-name>",
"name": "<room-name>",
"level": 0,
"isRestricted": false,
"parameters": {
"group": "webrtc",
"audiotracks": <audio-tracks-returned-to-participant>,
"videotracks": <video-tracks-returned-to-participant>
},
"restrictions": [],
"primaries": [],
"secondaries": []
},
"updated":<timestamp>
}
- Failure: HTTP CODE 400 or 404
- Data:
{
"errorMessage": "<error-message-string>",
"timestamp": <error-timestamp>
}
Example
REQUEST URI: http://streammanagerurl.red5pro.com/streammanager/api/4.0/admin/event/meta/live/room1/room1?accessToken=xyz123
- Method: POST
- Data: JSON
{
"guid": "live/room1",
"context": "live/room1",
"name": "room1",
"level": 0,
"isRestricted": false,
"parameters": {
"group": "webrtc",
"audiotracks": 3,
"videotracks": 1
},
"restrictions": [],
"primaries": [],
"secondaries": []
}
RESPONSE
- Success: HTTP CODE 200
- Data:
{
"name":"room1",
"scope":"live",
"data": {
"guid": "live/room1",
"context": "live/room1",
"name": "room1",
"level": 0,
"isRestricted": false,
"parameters": {
"group": "webrtc",
"audiotracks": 3,
"videotracks": 1
},
"restrictions": [],
"primaries": [],
"secondaries": []
},
"updated": 1615402189012
}
List Conferences
DESCRIPTION:
Lists conferences that are provisioned through the Stream Manager.
- URI:
http://{host}:{port}/streammanager/api/4.0/admin/event/meta?accessToken=<accessToken>
METHOD: GET
RESPONSE
- Failure: HTTP CODE 400 or 404
- Data:
{
"errorMessage": "<error-message-string>",
"timestamp": <error-timestamp>
}
- SUCCESS: HTTP CODE 200
- Data:
[
"guid: <scope>/<room-name>/<room-name>",
"guid: <scope>/<room-name>/<room-name>",
"guid: <scope>/<room-name>/<room-name>"
]
Example: Lists the provisioned conferences.
REQUEST URI: https://streammanager.url.com/streammanager/api/4.0/admin/event/meta?accessToken=xyz123
Method: GET
RESPONSE
- Success: HTTP CODE 201
- Data:
[
"guid: live/room1/room1",
"guid: live/room2/room2",
"guid: live/room3/room3",
]
Read Conference Provision
DESCRIPTION:
Reads and returns details of a conference provision.
- URI:
http://{host}:{port}/streammanager/api/4.0/admin/event/meta/{scope}/{room-name}/{room-name}?accessToken=xyz123
METHOD: GET
RESPONSE
- Failure: HTTP CODE 400 or 404
- Data:
{
"errorMessage": "<error-message-string>",
"timestamp": <error-timestamp>
}
- SUCCESS: HTTP CODE
-
DATA::
{ "name":"<room-name>", "scope":"<scope>", "data": { "guid": "<scope>/<room-name>", "context": "<scope>/<room-name>", "name": "<room-name>", "level": 0, "isRestricted": false, "parameters": { "group": "webrtc", "audiotracks": <audio-tracks-returned-to-participant>, "videotracks": <video-tracks-returned-to-participant> }, "restrictions": [], "primaries": [], "secondaries": [] }, "updated":<timestamp> }
Example: Reads conference provision details.
REQUEST URI: https://streammanager.url.com/streammanager/api/4.0/admin/event/meta/live/room1/room1?accessToken=xyz123
Method: GET
RESPONSE
- Success: HTTP CODE 200
-
Data:
{ "name":"room1", "scope":"live", "data": { "guid": "live/room1", "context": "live/room1", "name": "room1", "level": 0, "isRestricted": false, "parameters": { "group": "webrtc", "audiotracks": 3, "videotracks": 1 }, "restrictions": [], "primaries": [], "secondaries": [] }, "updated": 1615402189012 }
Join Conference
DESCRIPTION
Returns the server to use for joining a conference.
- URI:
http://{host}:{port}/streammanager/api/4.0/event/{scope}/{room-name}/join
- METHOD: GET
RESPONSE
- Failure: HTTP CODE 400 or 404
- Data: (NONE)
NOTE: The call will return 400 if the Stream Manager cannot find an existing composition with
event
equal to{room-name}
and a mixer publishing the stream{scope}/{room-name}/{room-name}
. That is because the conference streams need to be published to the server that mixer is forwarding its composite stream to.
SUCCESS
- CODE: 200
-
DATA:
{ "name": "<scope>/<room-name>", "scope": "<room-name>", "serverAddress": "<origin-host-address>", "region": "<region-code>" }
Example: Get the server for joining the conference created earlier
- URI:
https://streammanager.url.com/streammanager/api/4.0/event/live/room1/join
- Method: GET
RESPONSE
- Success: HTTP CODE 200
-
DATA:
{ "scope": "live/room1", "name": "room1", "serverAddress": "167.172.235.187", "region": "nyc3" }
Delete Conference Provision
DESCRIPTION
Deletes a conference provision from Stream Manager data store.
- URI:
http://{host}:{port}/streammanager/api/4.0/admin/event/meta/{scope}/{room-name}/{room-name}?accessToken=xyz123
- METHOD: DELETE
RESPONSE
- Failure: HTTP CODE 400 or 404
- Data:
{
"errorMessage": "<error-message-string>",
"timestamp": <error-timestamp>
}
SUCCESS
- CODE: 200
-
DATA:
{ "name":"<room-name>", "scope":"<scope>", "data": { "guid": "<scope>/<room-name>", "context": "<scope>/<room-name>", "name": "<room-name>", "level": 0, "isRestricted": false, "parameters": { "group": "webrtc", "audiotracks": <audio-tracks-returned-to-participant>, "videotracks": <video-tracks-returned-to-participant> }, "restrictions": [], "primaries": [], "secondaries": [] }, "updated":<timestamp> }
Example: Deletes the conference provision created earlier
- URI:
https://streammanager.url.com/streammanager/api/4.0/admin/event/meta/live/room1/room1?accessToken=xyz123
- Method: DELETE
RESPONSE
- Success: HTTP CODE 200
-
DATA:
{ "name":"room1", "scope":"live", "data": { "guid": "live/room1", "context": "live/room1", "name": "room1", "level": 0, "isRestricted": false, "parameters": { "group": "webrtc", "audiotracks": 3, "videotracks": 1 }, "restrictions": [], "primaries": [], "secondaries": [] }, "updated": 1615402189012 }