From 48e2f7b75912f7939e868ea57518b2aeb3ff3cc8 Mon Sep 17 00:00:00 2001 From: cristian-recoseanu Date: Tue, 24 Oct 2023 09:10:03 +0100 Subject: [PATCH] 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> --- APIs/schemas/constraint_set.json | 7 ++++ APIs/schemas/substream_constraints.json | 39 +++++++++++++++++ docs/Examples.md | 56 +++++++++++++++++++++++++ docs/Receiver Capabilities.md | 18 ++++++++ 4 files changed, 120 insertions(+) create mode 100644 APIs/schemas/substream_constraints.json 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..d9f8e9a 100644 --- 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 index 4b980ab..f879e1c 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,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.