The M2A Live service provides an API for creating and managing the resources required to deliver a live streaming video workflow on top of the AWS media services suite, including AWS MediaLive. In this version, the following resources are supported:

• Encoders An encoder resource represents the encoding of a single logical input stream into one or more output renditions that may be distributed to one or more destinations of the same type. Encoders must be created within an M2A Cloud Target Account which has been set up for your Organisation. Each encoder is associated with a specific AWS region. If multi-region resiliency is required multiple encoders are defined in different AWS regions.
• Standalone Inputs A standalone input is a long-lived MediaLive input resource that persists independently of any encoder. Standalone inputs are used when static IP addresses are required for push-type inputs (RTP, RTMP). They can be attached to and detached from channels as needed, but must be managed separately from the encoders that reference them.

New in version v4 An encoder is defined by three core components: a template, a list of inputs, and a list of destinations. Together these describe the full AWS MediaLive channel configuration.

Templates

Each encoder references a named Jinja2 channel template stored in the M2A template service. The template defines the encoding profile — output groups, video/audio codec settings, input attachment structure, and timecode configuration. It is rendered at channel creation time to produce the final AWS MediaLive channel JSON. Use template-configuration to supply per-encoder overrides for any Jinja2 variables (macros) declared in the template. For example, audio PIDs, language codes, or stream-specific bitrate values that differ between encoders that share the same template. Keys must match variable names defined in the template; unrecognised keys are ignored.

Inputs

The template defines a fixed number of InputAttachments. Each input you provide in the inputs array is mapped positionally into the corresponding attachment slot in the rendered template — the first input maps to the first attachment, the second to the second, and so on. The number of inputs provided must not exceed the number of attachment slots in the template. Most single-pipeline templates expect one input. Templates designed for automatic input failover expect two: the primary input first, followed by the secondary. The secondary input is automatically wired into the failover settings on the primary attachment.

Destinations

Destinations define where encoded media is sent. Each destination in the destinations array is matched independently to an output group in the rendered template by its output-group-type and, optionally, its name. Destination properties fall into two logical categories, which may be mixed freely within the same destinations array:

Explicit properties supply the raw target directly:

• url — the ingest endpoint for HLS, MS Smooth, RTMP, Archive, UDP, CMAF Ingest, and Multiplex output groups.
• channel-id — a raw AWS MediaPackage channel ID.

M2A resource properties supply an M2A platform identifier that is resolved to the underlying AWS resource or network endpoint at channel creation time:

• packager-id — an M2A-managed MediaPackage packager. The platform resolves this to the associated MediaPackage channel ID. Mutually exclusive with channel-id; if both are supplied, packager-id takes precedence and channel-id is ignored.
• connect-source-id — an M2A Connect source, resolved to a UDP endpoint.

If name is specified on a destination, the system looks for an output group with that exact name in the template. If name is omitted, the first output group of the matching type is used.

By default (auto-fix-destinations: true) the system silently drops any template output groups that have no matching destination. Set auto-fix-destinations: false to enforce a strict count match — channel creation will fail if the number of destinations does not exactly match the number of output groups in the rendered template.

API Structure:

The API is modelled on JSONAPI (https://jsonapi.org/format/). Where possible related resources are modelled as Relationships. ie: - a specific account owner (one to one relationship) - mediainputs (one to many relationship) - enrolments (one to many relationship) Owner can be only of type target-account.

HTTP Headers:

The following headers are required for all requests - json { 'Accept': 'application/vnd.api+json', 'Content-Type': 'application/vnd.api+json' }

Encoder CRUD API

Standalone MediaLive Input CRUD API

Submit and manage control actions for encoders. The action-type field determines the behaviour and which schema applies.

Scheduled actions (SCHEDULED) allow dynamic, real-time changes to a live encoder without stopping the stream — graphics and static-image overlays.

The encoder must be in IDLE or RUNNING state. The settings.type field identifies the action; settings.timing controls when it fires.

Timing types (settings.timing.type):

• immediate — as soon as possible after submission.
• fixed — at a specific wall-clock time. Requires settings.timing.time.

follow timing is defined in the schemas but is not accepted on any endpoint; submitting it returns 400.

Status for scheduled actions uses ScheduleActionStatus: PENDING → ACTIVE / FIRED → INACTIVE / FAILED.

Implemented: motion-graphics-activate, motion-graphics-deactivate, static-image-activate, static-image-deactivate. All other scheduled action types have schemas defined but are not accepted — submitting one fails schema validation and returns 400.

Startup scheduled actions: Encoders can be configured with schedule-actions (in the encoder settings). These are submitted automatically on the start that follows creation, once the encoder reaches RUNNING, and are not re-submitted on any later start — a stop or restart moves them to INACTIVE. The resulting action records are returned in the encoder response under schedule-actions.

To cancel a scheduled action before it fires, use DELETE /encoders/{encoder-id}/actions/{action-id}. Only PENDING actions can be deleted.

Slate actions replace the encoder's live output with a pre-configured slate (fallback) clip. Use slating to fill airtime during source failures, ad breaks, or planned pauses without stopping the encoder.

All slate actions require the encoder to be RUNNING. The sequence for managing a slate is:

Use slate-action-type: FIXED with slate-datetime on START_SLATE or SWITCH_SLATE to schedule the transition at a specific wall-clock time rather than immediately.

Lifecycle actions transition the encoder between states (START, STOP, RESTART, PAUSE, RESUME, etc.). Each action is processed asynchronously. The response status field (ACTIVE, COMPLETE, FAILED) reflects the outcome.