/

Creating a composition


Compositions are created via the Stream Manager API.

To create a new composition, you need the following information:

  • event: unique event name or UUID.
  • transcodeComposition: boolean that determines whether the final composite stream will be published to a Transcoder or an Origin node.
  • digest: string with the password configured in the mixer web application on the Mixer node. It is recommended to configure a password that matches the Stream Manager Access Token.
  • mixers: array with the following data to provide to each mixer

    • mixerName: unique identifier for a mixer:
    • mixingPage: URL of the HTML5 page to load in the Mixer (e.g. https://streammanager-url/client/mixer/presenter-flow-viewer.html)
    • streamName: stream name of the composite stream that will be published by the mixer
    • path: scope of the composite stream that will be published by the mixer
    • width: width of the composite stream that will be published by the mixer
    • height: height of the composite stream that will be published by the mixer
    • framerate: framerate of the composite stream that will be published by the mixer
    • bitrate: bitrate (in kbps) of the composite stream that will be published by the mixer
    • doForward: ALWAYS TRUE (will either be forwarded to another Mixer or an origin or transcoder).
    • destinationMixerName: mixerName of the destination mixer to forward to, if any. If this parameter is blank then the stream will be forwarded to a transcoder or origin depending on the value of transcodeComposition.
  • location: array with the region name where the Mixers are deployed.

Creating compositions of compositions

Large compositions require using multiple mixers where the composite stream of some mixers is fed into another mixer. The mixerName and destinationMixerName properties in the create composition API allow the specification of how mixers forward their composite stream between one another.

mixer01

Using the figure above as an example, where the composite stream of Mixer 1 and 2 is forwarded to Mixer 3, the mixerName and destinationMixerName properties in the create composition call can be assigned as follows:

Mixer 1:
   mixerName: "1"
   destinationMixerName: "3"
Mixer 2:
   mixerName: "2"
   destinationMixerName: "3"
Mixer 3:
   mixerName: "3"
   destinationMixerName: ""

When the Stream Manager receives the call it assigns each of the mixerNames above (1, 2 and 3) to one of the available mixers and replaces the destinationMixerName with the IP of the Mixer that is associated with that destinationMixerName when sending the provision to each mixer node. For example, if there are three mixers available with IPs 89.12.12.1, 89.12.12.2 and 89.12.12.3, the Stream Manager could assign them as follows to the mixerNames:

1 -> 89.12.12.1
2 -> 89.12.12.2
3 -> 89.12.12.3

Therefore, Mixer 1 and Mixer 2 are provisioned to forward to Mixer 3 -> 89.12.12.3, while Mixer 3 has an empty destinationMixerName and is provisioned to forward to an existing Origin or Transcoder node depending on the value of transcodeComposition.

A high level diagram of the architecture with two Mixers is shown in Figure 1 below.

mixer01

Figure 1 shows how the streams of two sets of three viewers are mixed together into a single stream for the final composite. Each Mixer in the top layer loads a page that subscribes to the viewers’ streams to pre-mix into a single stream generating the streams M(1,2,3) and M(4,5,6). The pre-mixed streams are published to another Mixer which mixes them into the final mixed stream M(M(1,2,3), M(4,5,6)). Once the final mixed stream is generated it is published to a Red5 Pro Cluster - either to an origin or a transcoder (where it can be transcoded to multiple variants).

The HTML5 page loaded into each Mixer determines the created composition. This page can interface with a back-end service, such as a WebSocket server, to receive commands to dynamically update its layout in real-time as driven by an Editor. For a simple use-case with a single Mixer, the HTML5 page could include a grid that automatically grows and shrinks as streams are added or removed. Additionally, an Editor could send commands to this page through a back-end service. These commands can control things such as muting the audio of a participant. In this way, when part of the stream is muted, their audio will not be part of the final composite stream which will include a mix of only the unmuted streams.