AMWA BCP-007-03: NMOS With MXL

Introduction

MXL provides an open and non-proprietary exchange layer within Dynamic Media Facilities.

This document outlines how MXL enabled media functions can be managed through AMWA IS-04 and IS-05.

Use of Normative Language

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.

Definitions

The NMOS terms ‘Controller’, ‘Node’, ‘Source’, ‘Flow’, ‘Sender’, ‘Receiver’ are used as defined in the NMOS Glossary.

MXL IS-04 Sources, Flows and Senders

Nodes that encapsulate media functions containing MXL writers MUST expose Source, Flow and Sender resources for each MXL writer in their IS-04 Node API.

Nodes compliant with this specification MUST implement IS-04 v1.3 or higher.

Sources

An MXL Source resource MUST set the format attribute to a value specified in the NMOS formats parameter register.

Examples of Source resources are provided in Examples.

Flows

An MXL Flow resource MUST set the format attribute to a value specified in the NMOS formats parameter register.

An MXL Flow resource MUST set the media_type attribute to a value specified in the NMOS media types parameter register.

Typical values used by MXL Flow resources for the media_type attribute include but are not limited to:

video/v210
video/v210a
audio/float32
video/smpte291

Examples of Flow resources are provided in Examples.

Senders

An MXL Sender resource MUST set the transport attribute to urn:x-nmos:transport:mxl.

An MXL Sender resource MUST expose an empty interface_bindings array.

An example Sender resource is provided in Examples.

Transport file usage

MXL does not require a transport file.

The manifest_href attribute of an MXL Sender MUST always be set to null.

The response for requests against the /transportfile endpoint of an MXL IS-05 Sender MUST always return a 404.

MXL IS-04 Receivers

Nodes that encapsulate media functions containing MXL readers MUST expose a Receiver resource for each MXL reader in their IS-04 Node API.

An MXL Receiver resource MUST set the transport attribute to urn:x-nmos:transport:mxl.

An MXL Receiver resource MUST expose an empty interface_bindings array.

An MXL Receiver resource MUST set the format attribute to a value specified in the NMOS formats parameter register.

An MXL Receiver resource MUST set the media_types attribute to at least one value. The values used MUST be specified in the NMOS media types parameter register.

Typical values used by MXL Receiver resources for the media_types attribute include but are not limited to:

video/v210
video/v210a
audio/float32
video/smpte291

The Receiver MUST express its limitations or preferences regarding the flows that it supports consuming by declaring constraints in accordance with the BCP-004-01 specification. The Receiver SHOULD express its constraints as precisely as possible, to enable a Controller to determine, with high confidence, the Receiver’s compatibility with available MXL flows. It is not always practical for the constraints to enumerate every type of flow a Receiver can or cannot consume; however, they SHOULD describe as many commonly used operating points as practical, along with any preferences.

The Receiver MUST use the constraint_sets parameter within the caps object to describe supported combinations of parameters, using the parameter constraints defined in the Capabilities Register of the NMOS Parameter Registers. The full details are described in BCP-004-01 NMOS Receiver Capabilities.

An example Receiver resource is provided in Examples.

MXL IS-05 Senders and Receivers

Nodes compliant with this specification MUST implement IS-05 v1.2 or higher.

Connection Management using IS-05 proceeds in the same manner as for any other transport, using MXL-specific transport parameters defined in MXL Sender transport parameters and MXL Receiver transport parameters.

The mxl_domain_id and mxl_flow_id transport parameters MUST be present in the IS-05 active, staged, and constraints endpoints of an MXL Sender and Receiver.

MXL Senders and Receivers MUST always use a single set of transport parameters in the transport parameters arrays in both the staged and active endpoints.

MXL Senders and Receivers MUST always use a single set of constraints in the constraints endpoint array.

Transport Parameters

Name	Description
`mxl_domain_id`	Specifies the MXL domain id where the MXL flow will be located. The Sender and Receiver list allowed values in the `constraints` endpoint.
`mxl_flow_id`	Specifies the MXL flow id which will be used for the write or read operation. The Sender and Receiver list allowed values in the `constraints` endpoint.

MXL Senders and Receivers MUST NOT allow the special value auto for mxl_domain_id or mxl_flow_id.

Note that the mxl_flow_id need not be the same as the ID of the associated IS-04 Flow resource.

Receivers

A PATCH request on the /staged endpoint of an MXL IS-05 Receiver is not expected to contain a transport file in the transport_file attribute.

A successful activation resulting in master_enable becoming true MUST start the MXL read operation.

A successful activation resulting in master_enable becoming false MUST stop the MXL read operation.

Senders

A successful activation resulting in master_enable becoming true MUST start the MXL write operation.

A successful activation resulting in master_enable becoming false MUST stop the MXL write operation.

MXL Domain volume and identity mapping

The base folder where MXL flows are stored is called an MXL domain. Multiple MXL domains can co-exist on the same host.
MXL domains are mapped to media functions at deployment time through volume mapping. This means that the path where a domain folder is located inside a container could be different from the path where the domain folder is located on the host.

Consider the following simple deployment example where we have two mxl-writer media functions and an mxl-reader media function.

services:
  writer-media-function-1:
    image: mxl-writer:latest
    volumes:
      - type: bind
        source: /Volumes/mxl/domain_1
        target: /domain_1
  writer-media-function-2:
    image: mxl-writer:latest
    volumes:
      - type: bind
        source: /Volumes/mxl/domain_2
        target: /domain_2
  reader-media-function:
    image: mxl-reader:latest
    volumes:
      - type: bind
        source: /Volumes/mxl/domain_1
        target: /domain_a
        read_only: true
      - type: bind
        source: /Volumes/mxl/domain_2
        target: /domain_b
        read_only: true

Without applying any strong identity to the MXL domains the reader media function cannot resolve domain_a and domain_b as being the same as domain_1 and domain_2.

All MXL domains MUST hold a definition json file domain_def.json in their folder on the host. The domain definition json object MUST respect the MXL Domain definition schema where the following attributes are defined as:

id - the unique identity of the domain as a UUID
label - the label of the domain as a string
description - optional description of the domain as a string

An example MXL domain definition is provided in Examples.

It is assumed media functions will be configured by an orchestrator with the MXL domain’s location on the local filesystem, allowing them to discover available mapped domains, and their identity, by checking the contents of each MXL domain for the domain_def.json file. The identity of each domain travels with each domain mapping inside each media function, meaning media functions can resolve domains to the same identity even when they have been mapped to different local paths inside the media function.

Given the above deployment example, this is the local path structure inside each of the media functions:

writer-media-function-1:

mxl-holder/
├── domain-01/
│   ├── domain_def.json
│   └── 4c02e7c0-ffeb-4595-8673-a265d103123a.mxl-flow/
│       └── flow_def.json

mxl-holder/domain-01/domain_def.json

{
    "id": "1ac254d9-a5eb-475f-a2b6-3d02a5cfbc82",
    "label": "Red Studio",
    "description": "MXL Red Studio domain"
}

writer-media-function-2:

my-mxl-holder/
├── domain-02/
│   ├── domain_def.json
│   └── 3494dc19-22c2-4f00-865b-cdbeee7909f0.mxl-flow/
│       └── flow_def.json

my-mxl-holder/domain-02/domain_def.json

{
    "id": "3310f209-9351-47c0-b9a2-14c59b6a4c23",
    "label": "Blue Studio",
    "description": "MXL Blue Studio domain"
}

reader-media-function:

base-mxl-holder/
├── domain-a/
│   ├── domain_def.json
│   └── 4c02e7c0-ffeb-4595-8673-a265d103123a.mxl-flow/
│       └── flow_def.json
├── domain-b/
│   ├── domain_def.json
│   └── 3494dc19-22c2-4f00-865b-cdbeee7909f0.mxl-flow/
│       └── flow_def.json

base-mxl-holder/domain-a/domain_def.json

{
    "id": "1ac254d9-a5eb-475f-a2b6-3d02a5cfbc82",
    "label": "Red Studio",
    "description": "MXL Red Studio domain"
}

base-mxl-holder/domain-b/domain_def.json

{
    "id": "3310f209-9351-47c0-b9a2-14c59b6a4c23",
    "label": "Blue Studio",
    "description": "MXL Blue Studio domain"
}

where domain-a and domain-b inside the reader-media-function resolve to the same identity as domain-01 and domain-02 mapped in the writer media functions.

Controllers

A controller MUST be able to discover MXL Senders and MXL Receivers by using the IS-04 Query API.

A controller MUST be able to connect an MXL Receiver to an MXL Sender by using the IS-05 Connection API.

When a controller makes a PATCH request on the /staged endpoint of an MXL IS-05 Receiver it MUST NOT provide the transport_file attribute.

Controllers MUST support the BCP-004-01 Receiver Capabilities mechanism in order to evaluate the flow compatibility between MXL Senders and MXL Receivers.

Index↑

Documentation built at 04:15:58 CDT on 2026-04-30.
(c) AMWA 2026. RAML/JSON licensed under Apache 2.0. Documentation licensed under CC BY-ND 4.0.