M2A Live Encoder Configuration (v1)

Download OpenAPI specification:Download

License: MIT

For managing the configuration used for M2A Live encoders by url: "https://www.m2amedia.tv" allowing existing AWS MediaLive configurations to be imported, analysed and broken down into reusable fragments.

New reusable configuration is added by submitting a prototype. When submitting a new prototype, a full AWS MediaLive channel definition must be provided. This definition is the JSON representation of an existing channel's configuration; e.g. that would be used by the CreateChannel MediaLive API endpoint.

The MediaLive management console allows a channel's configuration to be exported to this form as a "channel template".

When a prototype is first created, it enters a submitted state. Upon retrieval -- including immediately after creation, its template is analysed to detect potential reusable fragments. Note that this list of potential fragments may contain duplicates or otherwise unwanted configuration. For example, when importing a template that contains redundant outputs for the same content that only varies by their destination.

To complete the addition of a new, reusable configuration, fragments must be imported from the prototype. When importing fragments, the caller must select -- by inclusion of fragment identifiers, which candidate fragments they wish to permanently store and make available for reuse. Due to the possibility of duplicates or otherwise unwanted configuration, it is expected that the list of candidate fragments is reviewed manually before completing the import process.

Once the import is complete, the prototype moves to the imported state and the selected fragments are stored permanently and will be available for use when later reconstructing a full MediaLive channel configuration. Note that, once a prototype has been imported, it will not be possible to import additional fragments at a later date. Instead, a new prototype must be submitted.

Note that this API's interpretation of a given template may vary slightly over time. As such, users are strongly encouraged to conduct rigorous testing of any imported fragments before committing to their usage in a mission critical context or production environment.

Fragments

Fragments are small, reusable pieces of AWS MediaLive channel configuration. They are created by the prototype submission and import process described above. Each fragment has a type which identifies which aspect of a channel's configuration it encapsulates.

Currently there are seven principal fragment types. For most, there exists sub-types to distinguish between their usage with video, audio or caption media.

  • base: Base fragments are the largest and most wide-ranging in what they encompass. These fragments carry the "global" configuration of the channel, including the channel's input specification (e.g. anticipated input bitrate), VPC configuration (optionally) and motion graphics configuration. In effect, anything not listed for one of the other fragment types below is likely to end up in the base fragment.

    It is base fragments that form the backbone of any channel configuration generated by this API.

  • selector:audio, selector:video and selector:caption: Selectors describe how to identify individual media streams coming from a single source. For example, this may be the PID of a single audio stream in a transport stream input or the video track's ID for a file input. These fragments are extracted from the input attachments of a submitted prototype.

  • rendition:audio, rendition:video and rendition:caption: Renditions describe how MediaLive is to encode a media stream. Mapping effectively one-to-one with the prototype's audio, video and caption description configuration blocks, these fragments carry both the broad, quality-dictating settings such as bitrate, resolution and framerate, as well as the finer settings for a particular media encoding.

    Audio encodes can have specific stream names defined which would be displayed by the player. During analysis of a prototype, multiple prospective rendition:audio fragments are generated, one with the stream name included and one without. Stream names are included in the list of fragment features and details to inform the manual import selection.

  • filter:video: Optional deblocking and denoising filters to apply to a given inputs' video. Note that there is no comparative filtering available for audio as yet currently supported by MediaLive.

  • output: Describes how to send an encoded media stream to a destination. Note that output fragments do not themselves contain a destination. Instead, destinations are to be provided by the caller when generating a configuration and it is only at this point that the output is bound to the given destination.

    Some output protocols have support for name modifiers which influence the name of media fragments as they appear at the destination. Depending on the intended usage of an output, these modifiers may or may not be significant. During analysis of a prototype, multiple prospective output fragments are generated, one with the modifier included and one without. Modifiers are included in the list of fragment features and details to inform the manual import selection.

  • failover, failover:audio: Fragment failover represents optional automatic input failover settings for defining what the conditions are for declaring the input unhealthy and failing over to a different input. This fragment is extracted from the input attachments of a submitted prototype. Fragment failover:audio represents optional failover condition as part of input failover settings to perform a failover if the specified audio selector is silent for the specified period. This fragment failover:audio should be used alongside failover fragment only as it forms part of it.

  • destination:settings: Settings extracted from output destination for a standard output; one destination for each redundant encoder. These settings may contain url specifying a destination, stream name for RTMP destinations (URLs of type rtmp://), as also username for destination and key used to extract the password from EC2 Parameter store. If extracted fragment has username specified, it is reflected in fragment's name.

For the most part, fragments are stored as they appeared in the original prototype, with only small adjustments made to enable later recomposition. As such, it can generally be trusted that a fragment will preserve the finer configuration details as-is.

Generating Configuration

Once a set of fragments have been imported, they can be used to reconstruct a full AWS MediaLive channel configuration. Generating a configuration starts with a base fragment which provides the skeleton to which other fragments are attached. ARN of the role to assume when running the Channel must be provided as well.

When requesting a configuration, the caller must specify, by ARN, which inputs the channel will be attached to. As MediaLive manages inputs separately to channels, this API assumes that the inputs have already been fully created and configured by a separate process.

Each input must specify the ARN of at least one MediaLive input. Optionally a secondary MediaLive input can be specified to form a failover pair. If a secondary is specified, the generated channel configuration will include two input attachments -- one for each input. Configuration can be specified for secondary input which references failover fragment, this will apply automatic failover settings to the primary input attachment.

As with inputs, the caller must additional specify one or more destinations for the encoded media. Destinations take the form of a URI which suitable for use with the intended output protocol. For example, a https: URL may be used for Smooth Streaming whereas ARN would be used for AWS MediaPackage outputs. For URLs where authentication is required, a destination:settings fragment which refers to location at which MediaLive should load credentials from.

Both inputs and destinations must be named. These names are used to refer back to the input or destination when assembling the encoding configuration. Other than for the purpose of later referencing, names have no semantic meaning to this API. Names must be unique for a given configuration request.

With inputs and destinations specified, a caller must provide at least one filter-input-selector-failover-rendition-output-destination sequence. These sequences, assemblies, describe what media to encode, how to encode it and where to send it afterwards.

In an assembly, the input and destination are named references to the previously defined inputs and destinations. The selector, rendition and output are references to previously imported configuration fragments of a corresponding type. That is to say, a rendition may be a rendition:video or rendition:audio fragment, but it must not be an output fragment. Fragment super types must match in one assembly, e.g. selector:video must go with rendition:video and filter:video in one assembly. Similarly, selector:audio must go with rendition:audio and failover:audio in one assembly.

Optionally, filter can be specified for video assembly (with video selector and video rendition) which references filter:video fragment and failover can be specified for audio assembly (with audio selector and audio rendition) which references failover:audio fragment.

Only one selector for selector:video fragment and only one filter for filter:video fragment can be specified per assembly plan (among all assemblies).

Output fragments referenced in assembly plan must have unique name modifiers if those are specified.

One assembly must be specified for each unique path through the encoder pipeline. Meaning that, if there's a single, selected audio track that is to be transcoded into multiple renditions of differing quality, the same selector fragment must be specified by the two assemblies:

{
  "assemblies": [{
    "input": "source-name",
    "destination": "destination-name",
    "selector": "8fcc550c-d272-414c-8cee-8b45acd5f787",
    "rendition": "3721341c-e725-4e30-aee8-dc76b79e09e7",
    "output": "24512e2f-7567-4d2a-a560-7aae20c3ca8a",
    "failover: "daa93191-52e6-470c-afbf-4e62bb994cb3",
  }, {
    "input": "source-name",
    "destination": "destination-name",
    "selector": "8fcc550c-d272-414c-8cee-8b45acd5f787",
    "rendition": "2c5feab2-8b86-49e5-9a41-0c578ec8b94f",
    "output": "24512e2f-7567-4d2a-a560-7aae20c3ca8a",
    "failover: "daa93191-52e6-470c-afbf-4e62bb994cb3",
  }]
}

Note the repeated selector and output fragment IDs.

Although the same fragment may be referenced multiple times across multiple assemblies, the fragment will only be included in the generated configuration as many times as strictly required -- typically once.

Often the same configuration is desired for multiple encoders, perhaps with only small task-by-task variations. Assemblies that are frequently used together can be grouped into an assembly set. Sets, like configuration requests, contain selector-rendition-output sequences. However, these sequences are not bound to a given input or destination so that they can be reused even if the input or destination varies.

When requesting a channel configuration, references to sets can be given instead of, or in addition to individual fragment assemblies. When a set is referenced, they must also be bound to an input and destination which, in turn, binds the given input and destination to each assembly within the set; effectively expanding the set's assemblies in-place.

Consider the set 4a5476c3:

{
  "metadata": { ... },
  "assemblies": [{
    "selector": "8fcc550c-d272-414c-8cee-8b45acd5f787",
    "rendition": "3721341c-e725-4e30-aee8-dc76b79e09e7",
    "output": "24512e2f-7567-4d2a-a560-7aae20c3ca8a",
    "failover: "daa93191-52e6-470c-afbf-4e62bb994cb3"
  }, {
    "selector": "8fcc550c-d272-414c-8cee-8b45acd5f787",
    "rendition": "2c5feab2-8b86-49e5-9a41-0c578ec8b94f",
    "output": "24512e2f-7567-4d2a-a560-7aae20c3ca8a",
    "failover: "daa93191-52e6-470c-afbf-4e62bb994cb3"
  }]
}

Which can be used to generate a channel configuration equivalent to the earlier example:

{
  "inputs": { ... },
  "destinations" : { ... },
  "assemblies": [{
    "input": "source-name",
    "destination": "destination-name",
    "set": "4a5476c3-54b9-481e-89a4-2eb4be109bba"
  }]
}

configurations

Endpoints for configurations

Generate an AWS MediaLive configuration.

Creates a complete AWS MediaLive channel configuration from the given re-usable components.

Base references base fragment which provides the skeleton to which other fragments are attached. ARN of the role to assume when running the Channel must be provided as well.

Each input and destination must be given a non-zero length identifier which can be cross-referenced when binding an input or destination to an assembly. These identifiers must be unique across a given configuration request.

Each input must specify the ARN of at least one MediaLive input to which channel will be attached. Secondary MediaLive input and failover configuration for input is optional.

At least one destionation must be specified for the encoded media. Either of URI form (e.g. https: URL for Smooth Streaming) or of channel ARN form (for AWS MediaPackage outputs). For URLs where authentication is required, settings should be specified to reference destination:settings fragment which refers to location at which MediaLive should load credentials from.

Fragments are arranged into a list of filter-selector-failover-rendition-output assemblies. Alternatively, pre-created arrangement of assembly sets can be referenced for inclusion.

When specifying assemblies, either individually or from an assembly set, they must be bound to an input and destination. Inputs and destinations are separately defined as part of the configuration request. For assembly sets, the given input and destination is bound to each assembly in the set.

Fragment super types must match in one assembly, e.g. selector:video must go with rendition:video and filter:video in one assembly. Similarly, selector:audio must go with rendition:audio and failover:audio in one assembly.

Only one selector for selector:video fragment and only one filter for filter:video fragment can be specified per assembly plan (among all assemblies).

Output fragments referenced in assembly plan must have unique name modifiers if those are specified.

One assembly must be specified for each unique path through the encoder pipeline. Meaning that, if there's a single, selected audio track that is to be transcoded into multiple renditions of differing quality, the same selector fragment must be specified by the two assemblies.

Request Body schema: application/json
base
required
string <uuid> (Resource identifier)

Unique identifier used for identification of individual resources in M2A Medialive Configuration Manager APIs.

required
Array of objects non-empty
required
Array of DestinationURI (object) or DestinationChannelId (object) (ConfigurationDestination) non-empty
required
Array of objects or objects non-empty
role-arn
required
string (ARN) ^arn:([^:\n]*):([^:\n]*):([^:\n]*):([^:\n]*):...

Responses

Request samples

Content type
application/json
{
  • "base": "46106fd4-f16f-4f0f-a8a0-9c34e78b9ada",
  • "inputs": [
    ],
  • "destinations": [
    ],
  • "assemblies": [
    ],
  • "role-arn": "string"
}

Response samples

Content type
application/json
{ }

fragments

Endpoints for fragments

List all re-usable configuration components.

Retrieve pages listing all previously imported re-usable fragments.

query Parameters
organisation-id
required
string <uuid> (Resource identifier)
Example: organisation-id=46106fd4-f16f-4f0f-a8a0-9c34e78b9ada

ID of an owning organisation.

Responses

Response samples

Content type
application/json
{
  • "page": {
    },
  • "items": [
    ]
}

Retrieve an imported re-usable configuration component.

Retrieve specified previously specified imported re-usable fragment.

path Parameters
fragment-id
required
string <uuid> (Resource identifier)
Example: 46106fd4-f16f-4f0f-a8a0-9c34e78b9ada

ID of a re-usable configuration component.

Responses

Response samples

Content type
application/json
Example
{
  • "id": "1114c6ba-3975-4840-bed1-88183ca4d9c6",
  • "metadata": {
    },
  • "prototype": "46106fd4-f16f-4f0f-a8a0-9c34e78b9ada",
  • "json": {
    },
  • "type": "base",
  • "details": {
    },
  • "features": [ ]
}

prototypes

Endpoints for prototypes

Submit an AWS MediaLive configuration template for fragmentation into reusable components.

Creates a new configuration prototype from an AWS MediaLive configuration template. A template is the JSON encoded string which describes the full configuration of a MediaLive channel. The given template will be analysed to find candidate re-usable components. These candidates are included in the response body and can be imported via the corresponding .../import/ endpoint.

If no name label is specified in the given labels, then a suitable name will be derived from the template itself.

Request Body schema: application/json
required
object (Metadata)
template
required
object

Responses

Request samples

Content type
application/json
{
  • "metadata": {
    },
  • "template": { }
}

Response samples

Content type
application/json
{
  • "id": "46106fd4-f16f-4f0f-a8a0-9c34e78b9ada",
  • "metadata": {
    },
  • "status": "submitted",
  • "fragments": [
    ]
}

Retrieve a previously submitted configuration prototype.

Retrieves specified configuration prototype.

path Parameters
prototype-id
required
string <uuid> (Resource identifier)
Example: 46106fd4-f16f-4f0f-a8a0-9c34e78b9ada

ID of a prototype.

Responses

Response samples

Content type
application/json
{
  • "id": "46106fd4-f16f-4f0f-a8a0-9c34e78b9ada",
  • "metadata": {
    },
  • "status": "submitted",
  • "fragments": [
    ]
}

Import re-usable components from a prototype.

Creates a re-usable fragment for each one listed in the request body. In doing so, the prototype moves to the imported state and no further fragments may be imported from it.

Each fragment listed in the request must refer back to a previously analysed fragment by its ID. If any requested fragments are not recognised, then the request will be rejected with a 409. Rarely, this may occur transiently and the client may wish to restart the import process. If doing so, a client must refresh the prototype analysis.

Each fragment may be given a name. These names needn't match the suggested names from the prototype analysis. However, if no name is specified, then the suggested name will be used as a default.

path Parameters
prototype-id
required
string <uuid> (Resource identifier)
Example: 46106fd4-f16f-4f0f-a8a0-9c34e78b9ada

ID of a prototype.

Request Body schema: application/json
required
Array of objects

Responses

Request samples

Content type
application/json
{
  • "fragments": [
    ]
}

Response samples

Content type
application/json
Example
{
  • "error": {
    }
}

sets

Endpoints for sets

Group commonly assembled configuration components.

Creates a group of pre-assembled fragments that can be used in later requests to generate full AWS MediaLive configurations. A set is made up of a non-empty list of filter-selector-failover-rendition-output assemblies much like those submitted during the generation of configuration. However, these assemblies are not bound to a specific input or destination.

Composition of a set is fixed. Once created, it cannot be modified.

Request Body schema: application/json
required
object (Metadata)
required
Array of objects (Assembly) non-empty

Responses

Request samples

Content type
application/json
{
  • "metadata": {
    },
  • "assemblies": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "metadata": {
    },
  • "assemblies": [
    ]
}

List all pre-arranged commonly assembled configuration components.

Retrieve paged list of previously created sets.

query Parameters
organisation-id
required
string <uuid> (Resource identifier)
Example: organisation-id=46106fd4-f16f-4f0f-a8a0-9c34e78b9ada

ID of an owning organisation.

Responses

Response samples

Content type
application/json
{
  • "page": {
    },
  • "items": [
    ]
}

Retrieve a pre-arranged configuration assembly.

Retrieve specified set.

path Parameters
set-id
required
string <uuid> (Resource identifier)
Example: 46106fd4-f16f-4f0f-a8a0-9c34e78b9ada

ID of a group of pre-assembled fragments.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "metadata": {
    },
  • "assemblies": [
    ]
}