Authentication

All of these REST requests require a valid JWT, presented in the Authorization header as a bearer token. See Auth Service doc.

Create Mixer Event

On the best available Mixer Node, create a new Mixer Event. This is similar to Get Server for Publish, but for Mixers.

Note that here, the word “event” is used in the sense of a music concert or sporting event, rather than the EventListener sense.

Mixer output is always forwarded to another clustered server. AS-Streams chooses that server by internally calling Get Server for Publish. Effectively, the mixer acts like a publisher to the PUBLISH server.

Note that if a matching Provision is found (a Provision containing a matching streamGuid), this request forwards the provision to the chosen server(s). This is primarily to support transcoding an ABR ladder from the mixer output stream.

Create Mixer Event Request

POST https://<host>/as/v1/streams/mixer/<nodeGroupName>?subgroup=us-east&strict=false&transcode=false

nodeGroupName: Required. The name of the NodeGroup. If running a system with only one NodeGroup, you may use default as an alias (the name default matches any NodeGroup’s name as long as there is only one NodeGroup defined).

eventId: Required. Min 1 char, max 16 chars. Alphanumeric, plus -, _, and .. Must be unique within the NodeGroup.

subgroup: Optional, default null meaning “all”. The name of the subgroup (the immediate parent) of candidate nodes. May be a comma-separated list, in order of preference.

strict: Optional, default false. Return only servers from the specified subgroup (or fail). If not strict, other regions may be returned.

transcode: Optional, default false If true, there must be a valid provision (previously created with a Create Provision request), such that the Provision.streamGuid matches this mixer’s output streamGuid. If false, there must be no such Provision.

Body:

{
    "eventId": "event1",
    "streamGuid": "live/mix1",
    "originIp": "192.168.1.222",
    "width": 1920,
    "height": 1080,
    "frameRate": 30,
    "bitRate": 4000000,
    "maxBitRate": 7000000,
    "qpMin": 28,
    "qpMax": 48,
    "audioSampleRate": 48000,
    "audioChannels": 2,
    "subMixes": 2
}

eventId: String, alphanumeric, up to 256 characters. Name of this mixer or set of mixers.

streamGuid: String.

originIp: Optional. String, up to 45 characters. Origin node to forward to. Must be a routable address. Usually an Origin node within a cluster. If this field is null or missing, the Streams Service will internally perform a Get Server for Publish call passing any parameters subgroup, strict, and transcode.

width: Integer, between 2 and 7680. Video frame width in pixels.

height: Integer, between 2 and 4320. Video frame height in pixels.

bitRate: Integer, between 100 and 1048576. Video data rate in bits per second.

maxBitRate: Integer, between 100 and 1048576. Maximum video data rate in bits per second.

qpMin: Integer, between 0 and 63. Must be less than or equal to qpMax. Minimum h264 quantizer.

qpMax: Integer, between 0 and 63. Must be greater than or equal to qpMin. Maximum h264 quantizer.

audioSampleRate: Integer, between 8000 and 96000. Audio data rate in samples per second.

audioChannels: Integer, either 1 and 2 (mono or stereo).

subMixes: (Optional) Integer, between 1 and 10. The number of simultaneous mixers to create for this event. Default is 1.

Create Mixer Event Response

The response is a list of one or more stream locations.

The first location will always be the mixer. The second location will be the node where the mixer will publish (an PUBLISH-capable node, or maybe TRANSCODE-capable). In the case that an ABR Provision has previously been created, and transcoding requested, the response will also include the Transcoder’s destination Origin.

On success:

HTTP 201: CREATED

Body:

[
   {
      "nodeRole" : "mixer",
      "nodeState" : "INSERVICE",
      "serverAddress" : "129.213.150.214",
      "streamGuid" : "live/mix1",
      "subGroup" : "ashburn"
   },
   {
      "nodeRole" : "origin",
      "nodeState" : "INSERVICE",
      "serverAddress" : "129.213.93.116",
      "streamGuid" : "live/mix1",
      "subGroup" : "ashburn",
      "subscribers" : 0
   }
]

On error:

HTTP 400: Bad Request | Validation failure (see response body for details).

HTTP 401: Unauthorized | Missing or invalid JWT Authorization header

HTTP 404: Not Found | No NodeGroup found with nodeGroupName, or no provision found for streamGuid while transcode=true.

HTTP 409: Conflict | A mixer event with this eventId already exists in this NodeGroup.

HTTP 409: Conflict | A stream with this streamGuid already exists in this NodeGroup.

Get All Mixer Events

Get all mixer events in a given NodeGroup.

Get All Mixer Events Request

GET https://<host>/as/v1/streams/mixer/<nodeGroupName>

No body.

Get All Mixer Events Response

On success:

HTTP 200: OKAY

{
   "event1" : {
      "durationMs" : 0,
      "nodeRole" : "mixer",
      "nodeState" : "INSERVICE",
      "serverAddress" : "129.213.150.214",
      "streamGuid" : "live/mix1",
      "subscribers" : 0
   }
}

On error:

HTTP 401: Unauthorized | Missing or invalid JWT Authorization header

HTTP 404: Not Found | No NodeGroup found with nodeGroupName.

Get RenderTrees for Mixer Event

Get a list of Rendtrees for a given mixer event.

Get RenderTrees for Mixer Event Request

GET https://<host>/as/v1/streams/mixer/<nodeGroupName>/<eventId>

No body.

Get RenderTrees for Mixer Event Response

On success:

HTTP 200: OKAY

[
  {
    "rootVideoNode": {
      "nodes": [
        {
          "streamGuid": "live/stream1",
          "sourceX": 0,
          "sourceY": 0,
          "sourceWidth": 1920,
          "sourceHeight": 1080,
          "destX": 0,
          "destY": 0,
          "destWidth": 1920,
          "destHeight": 1080,
          "node": "VideoSourceNode"
        }
      ],
      "node": "CompositorNode"
    },
    "rootAudioNode": {
      "nodes": [
        {
          "streamGuid": "live/stream1",
          "pan": 0.0,
          "gain": 0.0,
          "node": "AudioSourceNode"
        }
      ],
      "node": "SumNode"
    }
  }
]

The response is an array of RenderTrees, one for each of the event’s submixes.

On error:

HTTP 401: Unauthorized | Missing or invalid JWT Authorization header

HTTP 404: Not Found | No NodeGroup found with nodeGroupName, or no mixer event found for eventId (see error response for details)

Update RenderTrees

Update the RenderTree for each submix in a given Mixer Event.

Update RenderTrees Request

PUT https://<host>/as/v1/streams/mixer/<nodeGroupName>/<eventId>

Body:

[
    {
        "rootVideoNode": {
            "red": 0,
            "green": 0,
            "blue": 1,
            "alpha": 1,
            "node": "SolidColorNode"
        },
        "rootAudioNode": {
            "nodes": [
                {
                    "streamGuid": "live/stream1",
                    "pan": 0,
                    "gain": 0,
                    "node": "AudioSourceNode"
                }
            ],
            "node": "SumNode"
        }
    }
]

Note that if the request contains fewer RenderTrees than the mixer event has submixes, only the first submixes will receive updates and remaining submixes will be ignored. However if additional (too many) RenderTrees are supplied, this is an error (400).

Update RenderTrees Response

On success:

HTTP 200: OKAY

Body:

{
    "result": "UPDATED"
}

On error:

HTTP 400: Bad Request | Validation failure (see response body for details).

HTTP 401: Unauthorized | Missing or invalid JWT Authorization header

HTTP 404: Not Found | No NodeGroup found with nodeGroupName, or no mixer event found for eventId (see error response for details)

Delete Mixer Event

Delete the given mixer event, stopping all submixes.

Delete Mixer Event Request

DELETE https://<host>/as/v1/streams/mixer/<nodeGroupName>/<eventId>

No body.

Delete Mixer Event Response

On success:

HTTP 200: OKAY

{
    "result": "UPDATED"
}

On error:

HTTP 401: Unauthorized | Missing or invalid JWT Authorization header

HTTP 404: Not Found | No NodeGroup found with nodeGroupName, or no mixer event found for eventId (see error response for details)