1.0-AF-edits

docs/Overview.md

@@ -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.
 
@@ -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
 
@@ -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
 
@@ -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`.
 
@@ -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`.
 
@@ -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:transport:ndi:group`. The NDI group tag can 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`.
@@ -194,27 +206,26 @@ 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_address" : "10.10.10.123:5906"
   }
 ]
 ```
+#### machine_name
+The name of the sender node in the NDI domain. A node MUST report the machine name being utilized by the NDI SDK. A controller SHOULD NOT specify a new `machine_name` but SHOULD use `null` or the current `machine_name`. 
 
-**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.
-
-**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.
+#### source_name
+The name of the NDI stream created by the Native NDI Sender in the NDI domain. This parameter MUST NOT be concatenated with `machine_name` in the format `machine_name(source_name)`.
 
-**source_name**:
-The name of the NDI stream as declared by the NDI Sender.
+| Informative note: In the NDI domain, the `source_name` and `machine_name` are concatenatedin the format `machine_name(source_name)` when streams are discovered and connected, however in the `transport_params`, these properties are kept independent.
 
-**group_name**: 
-The NDI group of the source. `null` indicates the default group.
+#### source_url 
+The URL of the sender as utilized by the NDI SDK. Sender MUST report this upon activation. The contents are proprietary to the NDI SDK and SHOULD NOT be interpreted. A controller SHOULD specify `auto` or the current value when setting this property. 
 
-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_address
+The IP address and port that the sender is utilizing for the stream. It MUST be in the format `ip_address:port_number`.
 
 ### Receiver Parameters
 
@@ -223,32 +234,39 @@ 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_address" : "10.10.10.123:5906"
   }
 ]
 ```
 
-**interface_ip**: 
-IP address of the network interface the receiver MUST use. If set to `auto` the receiver MUST determine which interface to use.
+machine name / source name SHOULD always be specified. Others MAY be specified.
+
+#### machine_name
+This indicates the device name of the Native NDI Sender that is to be connected, as utilized by the NDI SDK.
 
-**server_host**: 
-Hostname or IP hosting the NDI server. A `null` value indicates that the Receiver has not yet been configured.
+#### source_name
+The name of the Native NDI Sender stream in the NDI domain that is to be connected. This property MUST NOT be concatenatedwith `machine_name` in the format `machine_name(source_name)`.
 
-**server_port**: 
-Port for the NDI server. If set to `auto` the receiver MUST determine which port to use.
+> Informative notes: In the NDI domain, the `source_name` and `machine_name` are concatenatedin 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 sender as utilized by the NDI SDK. The contents are proprietary to the NDI SDK and SHOULD NOT be interpreted. A controller SHOULD specify this parameter with values provided by a sender's `transport_params` or the NDI SDK discovery methods. If this parameter is set to `null`, the receiver MUST determine for itself the value of `source_url`.
 
-**group_name**: 
-The NDI group of the source, `null` indicates the default group.
+#### source_address
+The IP address and port that the sender is utilizing for the stream. If specified, it MUST be in the format `ip_address:port_number`, other wise it MUST be set to `null` if not known.
 
-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.
+## IS-05 Connection Bahavior 
+ Connections in the NDI domain can be specified in several different ways. In each case the Native NDI Receiver identifies the stream to be connected through at least one of:
+ - `machine_name` and `source_name`
+ - `source_url`
+ - `source_address` and `source_name`
+ - `source_address`
 
+ Native NDI Devices will not necessarily support all these methods, so Controllers and Devices SHOULD specify as much information as is known in `transport_params`. If the NDI Receiver is not provided with one or more of the above parameters, but is able to determine the additional parameters, it MUST report these updated `transport_params` upon activation.
+
 ## Controllers
 
 A controller MUST be able to discover NDI Senders and NDI Receivers by using the query API.