Mixer APIs
Mixer Composition API
The Stream Manager creates a provision object using the data included in the create-composition API request. When a provision is posted, the mixer starts its composition and publishes the composite stream. When provisioning the composition, the Stream Manager appends &type=cef&cef-id=<sm-generated-id>
to the end of the mixingPage
URL. In this way, the page can process the cef-id
URL parameter to determine on what mixer instance it was loaded. This is useful for remotely controlling the compositions in multiple mixer nodes. A mixer composition can use any HTTP/S page as the mixingPage
URL.
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 fewer mixers than requested, unpredictable behavior may be observed.
Create Composition
Description
Create a mixer composition. The simple example creates a mixed stream that is then published to a transcoder (if transcodeComposition
is true
) or origin node (if transcodeComposition
is false
). The URL-mixing-page
can be any HTTP/S page.
REQUEST
- URI:
http://{host}:{port}/streammanager/api/4.0/composition?accessToken=<accessToken>
- Method: POST
- DATA:
{
"event": "<event-name>",
"transcodeComposition": <true|false>,
"digest": "<stream-manager-access-token>",
"mixers": [
{
"mixerName":"<mixer-name>",
"mixingPage":"<URL-mixing-page>?sm=true",
"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":""
}
],
"location":[
"<mixer-region>"
]
}
Where:
event
– the “event name” is used to track your specific compositiontranscodeComposition
– set totrue
if you want to transcode your mixed composition, orfalse
if you are not using ABR.digest
– this must match the stream manager access token value.mixingPage
– in theory, you can use any HTTP/S URL for this page. We’ve provided some sample mix pages with the webrtcexamples that are accessible athttps://{streammanager-URL}/webrtcexamples/sample-mixer-pages/
(/2x2
,/3x3
,/7x7/
, and/nxn/
). IMPORTANT: You must include the?sm=true
at the end of the URL path since the composition is being generated via a stream manager request.streamName
– the name of the outgoing stream. This is the stream name that your subscribers will connect to in order to view the composite stream.path
– the scope of the outgoing stream. Unless you have a custom webapp, use thelive
webapp that is included with the server distributionwidth
,height
,framerate
, andbitrate
– the attributes of your mixed stream.doForward
– this value should always be set to true; as you will either be forwarding to another mixer node, origin node, or transcoder node (iftranscodeComposition
is set totrue
)destinationMixerName
– if you are forwarding the mixer output to another mixer, then use a dummy mixer name here (e.g.mixer
); otherwise, leave this value blank.
RESPONSE
- Success: HTTP CODE
200
- DATA:
{
"event": "<event-name>",
"transcodeComposition": <true|false>,
"digest": "<stream-manager-access-token>",
"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"
}
]
}
- 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?sm=true",
"streamName": "stream01",
"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?sm=true",
"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"
}
]
}
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 the 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": "<stream-manager-access-token>", "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" } ] }
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"
}
]
}
Delete Composition
DESCRIPTION
Deletes a mixer composition from the 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 to which the mixer is forwarding its composite stream.
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 the 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 }