• Mixer Provisioning API
• Mixer Composition API
• Mixer Conference API

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
• Delete Provision

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

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 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.

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::

  Copy

  {
  "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:

  Copy

  {
  "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::

  Copy

  {
  "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:

  Copy

  {
  "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:

  Copy

  {
  "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:

  Copy

  {
  "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:

  Copy

  {
  "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:

  Copy

  {
  "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
  }