diff --git a/APIs/schemas/constraint_set.json b/APIs/schemas/constraint_set.json index ab439d3..3a8797a 100644 --- 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 new file mode 100644 index 0000000..2d8919f --- /dev/null +++ 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 index e646e5a..87f2bd8 100644 --- a/docs/Examples.md +++ b/docs/Examples.md @@ -236,3 +236,60 @@ 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 video profile", + "format": "urn:x-nmos:format:video", + "count": { + "enum": [ + 1 + ] + }, + "constraint_sets": [...] + }, + { + "description": "proxy video profile", + "format": "urn:x-nmos:format:video", + "count": { + "minimum": 0, + "maximum": 1 + }, + "constraint_sets": [...] + }, + { + "description": "audio profile", + "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 index 4b980ab..cd0be09 100644 --- 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,28 @@ 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. + +Substream Parameter Constraints are matched against parent Flow and source attributes. Each parent Flow can only be used to satisfy one Substream Parameter Constraints. The following diagram shows this matching workflow. + +| ![Substreams](images/substreams.png) | +|:--:| +| _**Substreams**_ | + ### 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. @@ -198,7 +222,7 @@ The Receiver MUST reflect any change in its capabilities by updating the `caps` ## Behaviour: Controllers -Controllers are strongly RECOMMENDED to support all Parameter Constraints listed in the Capabilities register in the [NMOS Parameter Registers][] that are applicable for the kinds of Receiver with which they interact. +Controllers are strongly RECOMMENDED to support all Parameter Constraints, including [per-substream](#substreams) Parameter Contraints, listed in the Capabilities register in the [NMOS Parameter Registers][] that are applicable for the kinds of Receiver with which they interact. However, Controllers MAY ignore individual Parameter Constraints whose unique identifiers they do not recognize. Some Parameter Constraints are only relevant to specific `transport` and `format` values or to particular IANA media types. When a Controller cannot evaluate any of the Parameter Constraints in a Constraint Set, that Constraint Set SHOULD be considered to be satisfied, but the Controller MAY distinguish this case for a user. diff --git a/docs/images/substreams.png b/docs/images/substreams.png new file mode 100644 index 0000000..52d9cb8 Binary files /dev/null and b/docs/images/substreams.png differ