Skip to content

Commit

Permalink
Merge pull request #11 from AMWA-TV/1.0-AF-edits
Browse files Browse the repository at this point in the history
1.0 af edits
  • Loading branch information
afryer-ross authored Apr 23, 2024
2 parents 5534268 + ed37bf0 commit 47fba2b
Show file tree
Hide file tree
Showing 5 changed files with 303 additions and 35 deletions.
112 changes: 77 additions & 35 deletions docs/Overview.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ _(c) AMWA 2023, CC Attribution-NoDerivatives 4.0 International (CC BY-ND 4.0)_

## Introduction

NDI (Network Display Interface) is an IP transport and control technology created by Newtek, a division of Vizrt Group. It includes definitions of encoding, transport and provides a full SDK to implement IP media transport. This document outlines how NDI devices can be managed through NMOS IS-04 and IS-05.
NDI (Network Display Interface) is an IP transport and control technology created by Newtek. NDI® is a registered trademark of Vizrt NDI AB. It includes definitions of encoding, transport and provides a full SDK to implement IP media transport. This document outlines how NDI devices can be managed through NMOS IS-04 and IS-05.

Familiarity with the [JT-NM Reference Architecture](https://jt-nm.org/reference-architecture/) and the [NDI® SDK](https://ndi.video/sdk/) are assumed.

Expand Down Expand Up @@ -73,9 +73,9 @@ An NMOS Sender which implements the NDI transport.

An NMOS Receiver which implements the NDI transport.

### NDI Full Bandwidth
### NDI High Bandwidth

An NDI stream which utilizes proprietary codecs for audio and video. NDI Full Bandwidth is supported by both the NDI Standard SDK and NDI Advanced SDK.
An NDI stream which utilizes proprietary codecs for audio and video. NDI High Bandwidth is supported by both the NDI Standard SDK and NDI Advanced SDK.

### NDI HX, NDI HX2, NDI HX3

Expand All @@ -89,7 +89,7 @@ NDI High Efficiency profiles, named **NDI HX**, **NDI HX2**, and **NDI HX3**, ut

### NDI

This document uses the term "NDI" when referring to all NDI variants, and specify "NDI Full Bandwidth", "NDI HX", "NDI HX2", or "NDI HX3" where the text applies to specific NDI variants.
This document uses the term "NDI" when referring to all NDI variants, and specify "NDI High Bandwidth", "NDI HX", "NDI HX2", or "NDI HX3" where the text applies to specific NDI variants.

## Native NDI Model

Expand Down Expand Up @@ -133,7 +133,7 @@ The mux Flow MUST have parent video and/or audio sub-Flows identifying the sub-F

#### Video sub-Flows

For NDI Full Bandwidth the video sub-Flows `media_type` attribute MUST be `video/raw`.
For NDI High Bandwidth the video sub-Flows `media_type` attribute MUST be `video/raw`.

For NDI HX, HX2 and HX3 the video sub-Flows `media_type` attribute MUST be `video/H264` or `video/H265`.

Expand All @@ -143,7 +143,7 @@ NDI video+alpha video flows MUST be modeled as a single video sub-Flow, includin

#### Audio sub-Flows

For NDI Full Bandwidth the audio sub-Flows `media_type` SHOULD be a supported PCM type such as `audio/L16`, `audio/L20`, or `audio/L24`.
For NDI High Bandwidth the audio sub-Flows `media_type` SHOULD be a supported PCM type such as `audio/L16`, `audio/L20`, or `audio/L24`.

For NDI HX, HX2 and HX3 the audio sub-Flows `media_type` attribute MUST be `audio/mpeg4-generic` or `audio/opus`.

Expand All @@ -159,6 +159,18 @@ NDI Senders MUST have their `transport` attribute set to `urn:x-nmos:transport:n

NDI Senders MUST be associated with a mux Flow.

#### NDI Group Tags

NDI Senders MUST specify the NDI groups, through use of tags. NDI group tag MUST use the URN `urn:x-nmos:tag:transport:ndi:group`. The NDI group tag could have multiple values to represent multiple NDI groups, for example:
```json
"tags": {
"urn:x-nmos:tag:transport:ndi:group": [
"Cameras",
"Studio-A"
]
}
```

### Receivers

The NDI Receiver MUST have its `format` attribute set to `urn:x-nmos:format:mux`.
Expand All @@ -175,8 +187,6 @@ An NDI Receiver MUST specify as a minimum the following capabilities:
}
```

Additional capabilities MAY be expressed in the `constraint_sets` array attribute of the Receiver for the stream of media type `application/ndi` and for the associated sub-streams.

## NDI IS-05 Resources

### Transport Type
Expand All @@ -194,27 +204,43 @@ The IS-05 schemas `sender_transport_params_ndi.json` and `constraints_schema_sen
```json
[
{
"server_ip": "10.10.10.10",
"server_port": 5960,
"machine_name": "ndi-machine-name",
"source_name": "ndi-sender-unique-name",
"group_name": "camera1"
"source_url" : "...",
"source_ip" : "10.10.10.123",
"source_port" : "5906"
}
]
```

**server_ip**:
IP address hosting the NDI server (IP address of interface bound to the server). If the parameter is set to auto the Sender MUST establish for itself which interface it can use, based on its own internal configuration. A `null` value indicates that the Sender has not yet been configured.
NDI Senders MUST specify `machine_name` and `source_name` in the Sender `transport_params`. Senders MAY also specify `source_url`, `source_ip` and `source_port`.

#### machine_name
The device name of the Native NDI Sender as utilized by the NDI SDK. The Sender MUST specify the `machine_name`. Senders MUST constrain this parameter with appropriate values. Controllers updating this parameter MUST specify a `machine_name` which is in the Sender contraints or `auto` to allow the Sender to determine the `machine_name`.

> Informative note: If a Sender does not wish a controller to change the `machine_name`, the constraint set would contain the current NDI device name and `auto` only.
#### source_name
The name of the Native NDI Sender stream in the NDI domain. This property MUST NOT be concatenated with `machine_name` in the format `machine_name (source_name)`. The Sender MUST specify the `source_name`.

A controller MAY modify this parameter within the supported constraints of the Sender.

**server_port**:
Port for the NDI server. If the parameter is set to `auto` the Sender MUST establish for itself which port it can use, based on its own internal configuration.
> Informative note: In the NDI domain, the `source_name` and `machine_name` are concatenated in the format `machine_name (source_name)` when streams are discovered and connected, however in the `transport_params`, these properties are kept independent.
**source_name**:
The name of the NDI stream as declared by the NDI Sender.
#### source_url
The URL of the Native NDI Sender as utilized by the NDI SDK. The contents are proprietary to the NDI SDK and SHOULD NOT be interpreted. If unspecified, it MUST be set to `null`. Senders MUST constrain this parameter with appropriate values.

**group_name**:
The NDI group of the source. `null` indicates the default group.
Controllers updating this parameter MUST specify a `source_url` which is in the Sender contraints or `auto` to allow the Sender to determine the `source_url`.

Although the NDI Advanced SDK does allow NDI Native Devices to specify additional Sender transport parameters, these parameters and properties SHOULD NOT be exposed in NMOS.
#### source_ip
The IP address that the sender is utilizing for the stream. If a sender or controller specifies the `source_ip` it MUST also specify `source_port`.

Controllers updating this parameter MUST specify a `source_ip` which is in the Sender contraints or `auto` to allow the Sender to determine the `source_ip`.

### source_port
The port number that the sender is utilizing for the stream. If a sender or controller specifies the `source_port` it MUST also specify `source_ip`.

Controllers updating this parameter MUST specify a `source_port` which is in the Sender contraints or `auto` to allow the Sender to determine the `source_port`.

### Receiver Parameters

Expand All @@ -223,31 +249,47 @@ The IS-05 schemas `receiver_transport_params_ndi.json` and `constraints_schema_r
```json
[
{
"interface_ip": "10.10.10.20",
"server_host": "10.10.10.10",
"server_port": 5960,
"machine_name": "ndi-machine-name",
"source_name": "ndi-sender-unique-name",
"group_name": "camera1"
"source_url" : "...",
"source_ip" : "10.10.10.123",
"source_port" : "5906",
"interface_ip" : "10.10.10.2"
}
]
```
NDI Receivers MUST support `machine_name` and `source_name` in the Receiver `transport_params`. Receivers MAY also support `source_url`, `source_ip` , `source_port` and `interface_ip`.

#### machine_name
The device name of the Native NDI Sender that is to be connected, as utilized by the NDI SDK.

A controller MUST specify `machine_name` when making a connection.

#### source_name
The name of the Native NDI Sender stream in the NDI domain that is to be connected. This property MUST NOT be concatenated with `machine_name` in the format `machine_name (source_name)`.

A controller MUST specify `source_name` when making a connection.

> Informative notes: In the NDI domain, the `source_name` and `machine_name` are concatenated in the format `machine_name (source_name)` when streams are discovered and connected, however in the `transport_params`, these properties are kept independent.
#### source_url
The URL of the NDI Native Sender as utilized by the NDI SDK. The contents are proprietary to the NDI SDK and SHOULD NOT be interpreted.

If supported by the Receiver, a controller MAY specify `source_url` when making a connection if it is known, otherwise the controller MUST set it to `null`.

**interface_ip**:
IP address of the network interface the receiver MUST use. If set to `auto` the receiver MUST determine which interface to use.
#### source_ip
The IP address that the sender is utilizing for the stream. If a receiver or controller specifies the `source_ip` it MUST also specify `source_port`.

**server_host**:
Hostname or IP hosting the NDI server. A `null` value indicates that the Receiver has not yet been configured.
If supported by the Receiver, a controller SHOULD specify `source_ip` when making a connection if it is known, otherwise the controller MUST set it to `null`.

**server_port**:
Port for the NDI server. If set to `auto` the receiver MUST determine which port to use.
### source_port
The port number that the sender is utilizing for the stream. If a receiver or controller specifies the `source_port` it MUST also specify `source_ip`.

**source_name**:
The name of the NDI stream as declared by the NDI sender.
If supported by the Receiver, a controller SHOULD specify `source_port` when making a connection if it is known, otherwise the controller MUST set it to `null`.

**group_name**:
The NDI group of the source, `null` indicates the default group.
### interface_ip
IP address of the network interface the receiver SHOULD use. The receiver SHOULD provide an enum in the constraints endpoint, which contain the available interface addresses. If set to `auto` the receiver MUST determine which interface to use for itself.

Although the NDI Advanced SDK does allow NDI Native Devices to specify additional Receiver transport parameters, these parameters and properties SHOULD NOT be exposed in NMOS.

## Controllers

Expand Down
30 changes: 30 additions & 0 deletions schema/receiver_transport_constraints_ndi.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"description": "Used to express the dynamic constraints on NDI receiver transport parameters. These constraints may be set and changed at runtime. Every transport parameter supported must have an entry, even if it is only an empty object.",
"patternProperties": {
"^ext_[a-zA-Z0-9_]+$":{
"$ref": "constraint-schema.json#/definitions/constraint"
}
},
"properties": {
"machine_name": {
"$ref": "constraint-schema.json#/definitions/constraint"
},
"source_name": {
"$ref": "constraint-schema.json#/definitions/constraint"
},
"source_url": {
"$ref": "constraint-schema.json#/definitions/constraint"
},
"source_ip": {
"$ref": "constraint-schema.json#/definitions/constraint"
},
"source_port": {
"$ref": "constraint-schema.json#/definitions/constraint"
},
"interface_ip": {
"$ref": "constraint-schema.json#/definitions/constraint"
}
}
}
98 changes: 98 additions & 0 deletions schema/receiver_transport_params_ndi_json.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,98 @@
{
"$schema": "http://json-schema.org/draft-04/schema#",
"description": "Describes the transport parameters associated with the NDI transport. The constraints in this schema are minimum constraints, but may be further constrained at the constraints endpoint. NDI Receivers MUST support machine_name and source_name in the Receiver transport_params. Receivers MAY also support source_url, source_address and source_port.",
"title": "NDI Receiver Transport Parameters",
"type": "object",
"properties": {
"machine_name": {
"type": [
"string",
"null"
],
"description": "The device name of the Native NDI Sender that is to be connected, as utilized by the NDI SDK. A controller MUST specify machine_name when making a connection. A null value indicates that the Receiver has not yet been configured.",
"anyOf": [
{
"format": "string"
}, {
"type": "null"
}
]
},
"source_name": {
"type": [
"string",
"null"
],
"description": "The name of the Native NDI Sender stream in the NDI domain that is to be connected. This property MUST NOT be concatenated with machine_name in the format machine_name (source_name). A controller MUST specify source_name when making a connection. A null value indicates that the Receiver has not yet been configured.",
"anyOf": [
{
"format": "string"
}, {
"type": "null"
}
]
},
"source_url": {
"type": [
"string",
"null"
],
"description": "The URL of the NDI Native Sender as utilized by the NDI SDK. The contents are proprietary to the NDI SDK and SHOULD NOT be interpreted.If supported by the Receiver, a controller MAY specify source_url when making a connection if it is known, otherwise the controller MUST set it to null.",
"anyOf": [
{
"format": "string"
}, {
"type": "null"
}
]
},
"source_ip": {
"type": [
"string",
"null"
],
"description": "The IP address that the sender is utilizing for the stream. If a receiver or controller specifies the source_address it MUST also specify source_port. If supported by the Receiver, a controller SHOULD specify source_address when making a connection if it is known, otherwise the controller MUST set it to null",
"anyOf": [
{
"format": "ipv4"
}, {
"format": "ipv6"
}, {
"type": "null"
}
]
},
"source_port": {
"type": [
"integer",
"null"
],
"description": "The port number that the sender is utilizing for the stream. If a receiver or controller specifies the source_port it MUST also specify source_address. If supported by the Receiver, a controller SHOULD specify source_port when making a connection if it is known, otherwise the controller MUST set it to null.",
"anyOf": [{
"minimum": 0,
"maximum": 65535
}, {
"type": "null"
}
]
},
"interface_ip": {
"type": "string",
"description": "IP address of the network interface the receiver should use. The receiver should provide an enum in the constraints endpoint, which contain the available interface addresses. If set to auto the receiver must determine which interface to use for itself.",
"anyOf": [{
"format": "ipv4"
}, {
"format": "ipv6"
}, {
"pattern": "^auto$"
}
]
}
},
"patternProperties": {
"^ext_[a-zA-Z0-9_]+$": {
"$ref": "receiver_transport_params_ext.json"
}
},
"additionalProperties": false
}
27 changes: 27 additions & 0 deletions schema/sender_transport_constraints_ndi.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"description": "Used to express the dynamic constraints on NDI sender transport parameters. These constraints may be set and changed at run time. Every transport parameter supported must have an entry, even if it is only an empty object.",
"patternProperties": {
"^ext_[a-zA-Z0-9_]+$":{
"$ref": "constraint-schema.json#/definitions/constraint"
}
},
"properties": {
"machine_name": {
"$ref": "constraint-schema.json#/definitions/constraint"
},
"source_name": {
"$ref": "constraint-schema.json#/definitions/constraint"
},
"source_url": {
"$ref": "constraint-schema.json#/definitions/constraint"
},
"source_ip": {
"$ref": "constraint-schema.json#/definitions/constraint"
},
"source_port": {
"$ref": "constraint-schema.json#/definitions/constraint"
}
}
}
Loading

0 comments on commit 47fba2b

Please sign in to comment.