Red5 Documentation

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

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
    }