Initial changes to support substreams (#29)

* Create substream_constraints.json * Update constraint_set.json - to include the new substreams property * Update Examples.md - to add MUX example using substreams * Update APIs/schemas/substream_constraints.json to an "open enum" Co-authored-by: Gareth Sylvester-Bradley <31761158+garethsb@users.noreply.github.com> * Update Examples.md in line with the latest schema update for "format" * Update Receiver Capabilities.md To add substreams section * Change "MUX" to "mux" --------- Co-authored-by: Gareth Sylvester-Bradley <31761158+garethsb@users.noreply.github.com>
AMWA-TV · Oct 24, 2023 · 48e2f7b · 48e2f7b
1 parent 4bf057c
commit 48e2f7b
Show file tree

Hide file tree

Showing 4 changed files with 120 additions and 0 deletions.
diff --git a/APIs/schemas/constraint_set.json b/APIs/schemas/constraint_set.json
@@ -20,6 +20,13 @@
       "description": "This value indicates whether a Constraint Set is available to use immediately (true) or whether this is an offline capability which can be activated via some unspecified configuration mechanism (false). When the attribute is omitted its value is assumed to be true.",
       "type": "boolean",
       "default": true
+    },
+    "urn:x-nmos:substreams": {
+      "description": "This exposes any substream constraints.",
+      "type": "array",
+      "items": {
+        "$ref": "substream_constraints.json"
+      }
     }
   },
   "patternProperties": {

diff --git a/APIs/schemas/substream_constraints.json b/APIs/schemas/substream_constraints.json
@@ -0,0 +1,39 @@
+{
+  "$schema": "http://json-schema.org/draft-04/schema#",
+  "description": "Describes substream constraints",
+  "title": "Constraint Set",
+  "type": "object",
+  "minProperties": 1,
+  "properties": {
+    "description": {
+      "description": "Substream group description",
+      "type": "string"
+    },
+    "format": {
+      "description": "Substream format",
+      "type": "string",
+      "anyOf": [
+        {
+          "enum": [
+            "urn:x-nmos:format:video",
+            "urn:x-nmos:format:audio",
+            "urn:x-nmos:format:data"
+          ]
+        },
+        {
+          "pattern": "^urn:x-nmos:format:(?!mux$)"
+        }
+      ]
+    },
+    "count": {
+      "$ref": "param_constraint_number.json"
+    },
+    "constraint_sets": {
+      "description": "Substream constraint sets",
+      "type": "array",
+      "items": {
+        "$ref": "constraint_set.json"
+      }
+    }
+  }
+}
diff --git a/docs/Examples.md b/docs/Examples.md
@@ -236,3 +236,59 @@ For example, Type N receivers can be expected to correctly receive a stream orig
 
 [TR-05]: https://www.videoservicesforum.org/download/technical_recommendations/VSF_TR-05_2018-06-23.pdf
 "VSF TR-05: Essential Formats and Descriptions for Interoperability of SMPTE ST 2110-20 Video Signals"
+
+### Substreams
+
+The following example shows a mux MPEG 2 transport stream Receiver exposing substream constraints.
+
+```json
+{
+  "id": "9dd002e2-76a0-4edc-88ef-7d4aff4b2d26",
+  "transport": "rtp",
+  "format": "mux",
+  "caps": {
+    "media_types": [
+      "video/MP2T"
+    ],
+    "constraint_sets": [
+      {
+        "urn:x-nmos:substreams": [
+          {
+            "description": "hi-res",
+            "format": "urn:x-nmos:format:video",
+            "count": {
+              "enum": [
+                1
+              ]
+            },
+            "constraint_sets": [...]
+          },
+          {
+            "description": "proxy",
+            "format": "urn:x-nmos:format:video",
+            "count": {
+              "minimum": 0,
+              "maximum": 1
+            },
+            "constraint_sets": [...]
+          },
+          {
+            "format": "urn:x-nmos:format:audio",
+            "count": {
+              "enum": [
+                0,
+                2,
+                4
+              ]
+            },
+            "constraint_sets": [...]
+          }
+        ]
+      },
+      {
+        "urn:x-nmos:substreams": [...]
+      }
+    ]
+  }
+}
+```
diff --git a/docs/Receiver Capabilities.md b/docs/Receiver Capabilities.md
@@ -46,6 +46,7 @@ Manufacturers MAY use their own namespaces to indicate Parameter Constraints whi
 ### Parameter Constraint Types
 
 The specification defines the JSON value type to which the constraint relates, which MUST be one of:
+
 * `string`
 * `integer`
 * `number`
@@ -87,6 +88,7 @@ It could therefore be better to explicitly constrain the target parameter to all
 ### Common Constraint Keywords
 
 The following attributes are allowed for all constraint types:
+
 * `enum` as an array value with one or more elements of the specified type
 
 ### String Constraint Keywords
@@ -162,6 +164,22 @@ A Controller MUST NOT take into consideration a Constraint Set that has this att
 
 If a Constraint Set is enabled or the Receiver does not support offline capabilities then this attribute MAY be omitted.
 
+### Substreams
+
+The `urn:x-nmos:substreams` attribute allows mux Receivers to indicate per substream constraints.
+
+The substreams are represented as a JSON array containing substream JSON objects.
+
+Each substream object includes the following attributes:
+
+* a description
+* the format of the substream
+* a count which specifies how many instances of this substream are required (both min, max or enum attributes can be used for this)
+* constraint_sets for this particular substream. These constraint sets are defined in the same way as constraints defined for single essence flows [see Constraint Sets](#constraint-sets).
+
+A Constraint Set using the `substreams` attribute is satisfied if **all of** its Substream Parameter Constraints are satisfied in the quantities specified by each `count` attribute.
+This implies that if **any of** the Substream Parameter Constraints are _not_ satisfied in the quantities specified by each `count` attribute, the Constraint Set as a whole is not satisfied.
+
 ### Listing Constraint Sets
 
 The Receiver advertises a list of Constraint Sets as a JSON array of these objects, using the key `constraint_sets` in the `caps` object.