• Mixer Composition API
• Mixer Conference API

---

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
• List Compositions
• Read Composition
• Delete Composition

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 composition
• transcodeComposition – set to true if you want to transcode your mixed composition, or false 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 at https://{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 the live webapp that is included with the server distribution
• width, height, framerate, and bitrate – 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 (if transcodeComposition is set to true)
• 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
  }