AMWA NMOS Device Audio Channel Mapping Specification: Overview
The documents included in this directory provide additional details and recommendations for implementations of the defined API, and its consumers.
The purpose of this document is to explain how an NMOS compatible system can re-map audio channels. This can take place on a sending device, where the resulting re-mapped audio may be sent out over the network, or a receiving device, where audio received from the network may be re-mapped prior to consumption.
The terms ‘Node’, ‘Device’, ‘Sender’ and ‘Receiver’ will be used extensively throughout this document. Please refer to the core NMOS Technical Overview for definitions of these.
This API is intended to be used in conjunction with an NMOS IS-04 Discovery & Registration deployment, however it has been written in such a way to provide useful functionality even in the absence of such a system.
This API may also be used on a Device with an NMOS IS-05 Device Connection Management interface, but still provides useful functionality when used on Devices where connections are established by other means.
Use of Normative Language
The documents included in this Directory form a normative part of the specification, along with the API definitions and schemas included in the APIs directory.
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.
The API may be used to define a mapping between one or more audio “Inputs” and one or more audio “Outputs”. Inputs and Outputs are resources local to the device, and as such are not published to the registry. An Input can be assigned audio from an NMOS Receiver, or can represent audio sources from elsewhere (e.g a microphone or physical input). Similarly audio routed to an Output can be assigned to an NMOS Source, or can be consumed elsewhere (e.g be routed to a loudspeaker or a physical output). A Device may also wish to direct audio from an Output back into a Device’s Input, as a way of expressing complex Device routing limitations.
A Device may not be able to arbitrarily route audio from any Input to any Output. As such the API allows the Device it is running on to express these limitations.
Inputs and Outputs both have a number of Channels available for use. An Input represents each of the audio tracks assigned to it as a Channel. The number of channels an Input or Output has can be restricted by the Device, and cannot be altered by the client.
The relationship between Input channels and Output channels is defined by the “Map”. Where a given Input is routable to a given Output, it MUST be possible to route any of the Input’s channels to any channel of the Output. Output channels that do not have any Input channels routed to them are said to be “parked”.
The API has two representations of the Map. The “Active” Map describes the current channel mapping state of the Device. The “Staged” Map represents the intended state of the Device at some future point. An “Activation” is the process whereby the Staged Map transitions to being the Active map. At the time of activation the underlying audio channel mapping behaviour of the Device transitions to reflect the new state of the Active map.
An Activation may either be “immediate”, “relatively scheduled” or “absolutely scheduled”. Immediate activations are carried out as soon as possible after the request to carry them out has been received. A relatively scheduled activation is carried out after a period of time specified by the client has elapsed. An absolute activation is carried out at a specific time specified by the client.
The API is divided into the following parts:
This contains the two states of the Map, staged and active. The Staged Map is modifiable by the client through use of the HTTP PATCH method. The Active Map is not directly modifiable by the client - changes must be made by modifying the Staged Map and requesting an activation.
This resource enumerates all of the Inputs, their channels and routing constraints. It also exposes the
parent resource, which is used to indicate the origin of the audio associated with that Input.
This resource is equivalent to the
inputs resource but for Outputs - contains information about Output channels, restrictions on which Inputs may be routed to an Output, and an optional Source ID, which represents the new NMOS Source created by re-mapping the audio.
This is simply a view onto data available elsewhere in the API, in order to allow clients to gather the information they need about inputs and outputs in a single request.
The following sequence diagrams show the expected interactions with the IS-04 registry, a device’s IS-05 Connection Management API and its Audio Channel Mapping API in order to route a channel mapped audio stream to a receiver.
The mapping can either take place on the receiving Device itself, or on the sending Device, depending on the capabilities and requirements of the system.
Receiver Side Sequence Diagram
Sender Side Sequence Diagram