Networked Media Open Specifications

APIs: Common Keys

←APIs · Index↑ · APIs - Client Side Implementation Notes→

A number of common keys are used within NMOS APIs. Their definitions, semantics and permitted values are described below.

Note: From v1.1 onwards, the core id, version, label, description and tags properties are available for all resource types.

ID

Core resources such as Sources, Flows, Nodes etc. include an id attribute. Resource identity is explained in the Data Model and Identifier Persistence & Generation sections of this specification.

The id attribute is a UUID, formatted as a string of 32 lowercase hex digits in groups of 8, 4, 4, 4, 12 separated by -, for example: f81d4fae-7dec-11d0-a765-00a0c91e6bf6.

Version

Core resources such as Sources, Flows, Nodes etc. include a version attribute. As properties of a given Flow or similar will change over its lifetime, the version identifies the instant at which this change took place. For example, if a vision mix transition occurred which resulted in a change to the parents which make up a particular Flow, the version is modified to reflect the wall clock instant at which this change occurred.

version is a TAI timestamp. In NMOS APIS, a TAI timestamp is represented as a string of the format: <seconds>:<nanoseconds>. Note the : as opposed to a ., indicating that the value 1439299836:10 is interpreted as 1439299836 seconds and 10 nanoseconds.

Combining the version with the resource’s ID attribute creates a hash which can be used to uniquely identify a particular variant of a Source, Flow or similar.

In registered operation, whenever a Node’s resources are updated, the change is registered with the Registration API, as specified in Behaviour: Registration. In peer-to-peer operation, the change is advertised using the ver_ TXT records, as specified in Discovery: Peer-to-Peer Operation.

Label

Freeform human readable string to be used within user interfaces.

Description

Freeform human readable string to be used within user interfaces.

Tags

A set of names and values providing a means to filter resources based on particular categorisations.

Filtering resources based on a name-value pair compares the value with each of the values for that name found in the resource tags. The comparison SHOULD be case-insensitive following the Unicode Simple Case Folding specification.

Example: Tags Format

{
  "tags": {
    "location": ["Salford", "Media City"],
    "studio": ["HQ1"],
    "recording": ["The Voice UK"]
  }
}

Format

A URN describing the data format of a video, audio or data flow.

Permitted Value Valid From API Version
urn:x-nmos:format:video v1.0
urn:x-nmos:format:audio v1.0
urn:x-nmos:format:data v1.0
urn:x-nmos:format:mux v1.1

See Use of URNs below for additional requirements regarding their handling.

Transport

A URN describing the protocol used to send data (video, audio, data etc.) over a network.

Note: From v1.3 onwards, permitted transport types are not versioned and are instead defined in the Transports register of the NMOS Parameter Registers. Prior to v1.3, the following table applies.

Permitted Value Valid From API Version
urn:x-nmos:transport:rtp v1.0
urn:x-nmos:transport:rtp.mcast v1.0
urn:x-nmos:transport:rtp.ucast v1.0
urn:x-nmos:transport:dash v1.0

For example, an RTP Transmitter sending to a multicast group uses the transport urn:x-nmos:transport:rtp.mcast, but a receiver supporting both unicast and multicast presents the transport urn:x-nmos:transport:rtp to indicate its less restrictive state.

See Use of URNs below for additional requirements regarding their handling.

Type (Devices)

A URN describing the role which a Device has within the production environment (such as camera, mixer, tally light etc.).

Note: From v1.3 onwards, permitted device types are not versioned and are instead defined in the Device Types register of the NMOS Parameter Registers. Prior to v1.3, the following table applies.

Permitted Value Valid From API Version
urn:x-nmos:device:generic v1.0
urn:x-nmos:device:pipeline v1.0

See Use of URNs below for additional requirements regarding their handling.

Use of URNs

All Uniform Resource Names (URNs) specified within the scope of the NMOS specifications MUST use the namespace urn:x-nmos:. Manufacturers MAY use their own namespaces to indicate values of URN which are not currently defined within the NMOS namespace.

NMOS specification URNs use the following construction:

<URN-base>[.<subclassification>][/<version>]

where:

A subclassification is more constrained than its URN base. For example, the URN base urn:x-nmos:transport:rtp above has two subclassifications of ucast and mcast.

Further subclassifications might be defined for a URN base in the future.

Versioned URNs will be used to indicate specification versions.

For example, the URN urn:x-nmos:control:sr-ctrl/v1.0 can be separated into a base urn:x-nmos:control:sr-ctrl and version v1.0.

API clients MUST be tolerant to URNs which have not yet been defined, but which might be added in later API versions.

←APIs · Index↑ · APIs - Client Side Implementation Notes→