APIs: Common Keys
←APIs · Index↑ · APIs - Client Side Implementation Notes→
A number of common keys are used within NMOS APIs. Their definitions, required practices for interpretation and permitted values are described below.
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’ should be modified to reflect the wall clock instant at which this change occurred.
The version is a nanosecond TAI timestamp represented as a string of the format: <seconds>:<nanoseconds>. Note the ‘:’ as opposed to a ‘.’, indicating that the value ‘1439299836:10’ should be 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.
Label
Freeform human readable string to be used within user interfaces.
Description
Freeform human readable string to be used within user interfaces.
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 |
API clients interpreting these URNs MUST correctly recognise subclassifications of these formats which may be added in the future. For example, if filtering by the type ‘urn:x-nmos:format:video’, the filter must include subclassifications such as ‘urn:x-nmos:format:video.raw’).
Query API clients MUST be tolerant to the presence of formats not yet defined here which may be added in later API versions.
Transport
A URN describing the protocol used to send data (video, audio, data etc.) over a network.
| 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 should use the transport ‘urn:x-nmos:transport:rtp.mcast’, but a receiver supporting both unicast and multicast should present the transport ‘urn:x-nmos:transport:rtp’ to indicate its less restrictive state.
Manufacturers MAY use their own namespaces to indicate transports which are not defined within the NMOS namespace at a particular API version, but should support be added in a future version the NMOS variant MUST be used when upgrading to that API version.
As with formats (described above), subclassifications of these URNs must be recognised correctly as members of these top level categories.
Tags
A set of keys and values providing a means to filter resources based on particular categorisations. Each tag has a single key, but MAY have multiple values. Each tags SHOULD be interpreted using the comparison of a single key value pair, with the comparison being case-insensitive following the Unicode Simple Case Folding specification.
Example: Tags Format
{
"tags": {
"location": ["Salford", "Media City"],
"studio": ["HQ1"],
"recording": ["The Voice UK"]
}
}
Type (Devices)
A URN describing the role which a Device has within the production environment (such as camera, mixer, tally light etc.).
| Permitted Value | Valid From API Version |
|---|---|
| urn:x-nmos:device:generic | v1.0 |
| urn:x-nmos:device:pipeline | v1.0 |
As with formats (described above), subclassifications of these URNs must be recognised correctly as members of these top level categories.
Manufacturers MAY use their own namespaces to indicate device types which are not defined within the NMOS namespace at a particular API version, but should support be added in a future version the NMOS variant MUST be used when upgrading to that API version.