Copyright 2023, Matrox Graphics Inc.
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
In IS-04, a Sender resource expresses the capabilities of a Sender through attributes that identify constraints on streams and sub-Streams that are compatible with the Sender. Such Sender can be constrained to operate at an operating point within the Sender Capabilities using the IS-11 API.
The Sender caps object is provided as an extensible mechanism to define fine-grained capabilities.
This specification defines a new constraint_sets attribute for the Sender caps object, its value is an array of alternatives; this constraint is satisfied when any of its enumerated Constraint Sets are satisfied.
When evaluating constraints for sub-Flows/sub-Streams, only the Constraint Sets alternatives of matching format and urn:x-matrox:layer are to be considered. The remaining Constraints Sets of the constraint_sets are ignored.
This specification defines a generic JSON syntax to express Constraint Sets made up of individual Parameter Constraints. The Constraint Set is satisfied if all of its Parameter Constraints are satisfied.
The representation of individual Parameter Constraints resembles the mechanism defined by IS-05 to constrain Sender and Receiver transport parameters at the /constraints endpoints, which Nodes and Controllers may also support.
This specification also defines a new version attribute to indicate when changes to the caps object took place.
The constraints_set and version attributes are listed in the Capabilities parameter register in the NMOS Parameter Registers.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.
A specification for each Parameter Constraint is strongly RECOMMENDED to be listed in the Capabilities register in the NMOS Parameter Registers and Matrox Capabilities. Each specification defines a unique identifier, the constraint type, and the target parameter, as follows.
Each Parameter Constraint is given a unique identifier - a URN. Parameter Constraints defined by the AMWA have the form:
urn:x-nmos:cap:<category>:<constraint>
Two <category> names are initially defined, format for media-related constraints, and transport for transport-related constraints.
For example, urn:x-nmos:cap:format:grain_rate is a Parameter Constraint relating to the Grain rate of the stream, for example by targeting the grain_rate attribute of an IS-04 Flow. (The concept of Grains is defined in the JT-NM Reference Architecture.)
The <category> name meta is reserved for metadata related to Constraint Sets. These attributes are not constraints themselves.
Manufacturers MAY use their own namespaces to indicate Parameter Constraints which are not currently defined within the NMOS namespace (urn:x-nmos:cap:).
The specification defines the JSON value type to which the constraint relates, which MUST be one of:
stringintegernumberbooleanrational- as per IS-04, a JSON object with an integer
numeratorand optional integerdenominator(default: 1)
- as per IS-04, a JSON object with an integer
The type of the constraint defines which Constraint Keywords are allowed when the Parameter Constraint is instantiated.
The specification defines the target parameter against which the constraint is to be evaluated, for example, the specific IS-04 Flow attribute or SDP format-specific parameter.
Especially in the case of parameters carried in non-JSON formats, such as a transport file, the specification MUST also describe how to map the parameter value to one of the supported JSON types.
The Sender expresses its capabilities with respect to a particular Parameter Constraint by including the constraint's unique identifier as an attribute in a Constraint Set with an object value, the attributes of which depend on the specified type.
For example:
"urn:x-nmos:cap:format:sample_depth": {
"enum": [ 24, 20, 16 ]
}Each Parameter Constraint is instantiated as an object with attributes that are type-specific Constraint Keywords defining how the parameter is constrained.
The Parameter Constraint is satisfied if all of the constraints expressed by the Constraint Keywords are satisfied. This implies that if any of the constraints expressed by the Constraint Keywords are not satisfied, the Parameter Constraint is not satisfied. Equally, when there are no Constraint Keywords, the Parameter Constraint thus explicitly indicates that the target parameter is unconstrained.
Note that in some cases, the target parameter will allow future addition of new values, for example by inclusion in the Flow Attributes register in the NMOS Parameter Registers. It could therefore be better to explicitly constrain the target parameter to all supported values, if new values could cause an issue.
The following attributes are allowed for all constraint types:
enumas an array value with one or more elements of the specified type
Nothing additional
The following attributes are additionally allowed for integer and number constraints:
minimum, inclusive minimum, an integer or number as appropriatemaximum, inclusive maximum, an integer or number as appropriate
minimum MUST be less than or equal to maximum. Empty ranges are not permitted, consistent with the rule that enumerations cannot be empty."
Nothing additional
The following attributes are additionally allowed for rational constraints:
minimum, inclusive minimum, arationalvaluemaximum, inclusive maximum, arationalvalue
minimum MUST be less than or equal to maximum. Empty ranges are not permitted, consistent with the rule that enumerations cannot be empty."
Note that comparison between two rational values, n1 / d1 and n2 / d2, SHOULD be performed by cross-multiplication and comparison of the products, n1 * d2 and n2 * d1, taking account of negative denominators.
Constraint Sets MUST be instantiated with one or more Parameter Constraints. The Constraint Set is satisfied if all of its Parameter Constraints are satisfied. This implies that if any of the Parameter Constraints are not satisfied, the Constraint Set as a whole is not satisfied.
The Constraint Set is represented as a JSON object with attributes that are the Parameter Constraints.
Additional metadata about each Constraint Set MAY be included, using the metadata attributes listed in the Capabilities register in the NMOS Parameter Registers and Matrox Capabilities with the following unique identifiers:
urn:x-nmos:cap:meta:<attribute>
The metadata attribute urn:x-nmos:cap:meta:label MAY be used to provide a human-readable name for the Constraint Set as a simple string value.
If a Sender uses this attribute, it SHOULD do so for all Constraint Sets.
A Controller MAY use this label to indicate to a user which Constraint Sets of a Sender are satisfied by a Sender.
The metadata attribute urn:x-nmos:cap:meta:preference enables the Sender to indicate its preference between the listed Constraint Sets.
A Controller MAY use Sender preference, for example, to assist the user in choosing between multiple Sender's operating point.
The preference is indicated as an integer value in the range from -100 to 100 inclusive.
If the Sender has no preference, it MAY omit the attribute from all Constraint Sets.
When a Sender wants to indicate preference, it adds the attribute either to all Constraint Sets or only to some, in which case the other Constraint Sets have an effective value of 0. The Sender indicates its strongest preference for one or more Constraint Sets by assigning them its highest value. It indicates preference against, or weaker preference for, Constraint Sets by assigning them lower values.
For example:
- When a Sender supports a few options natively, and many that require some transformation, it MAY explicitly associate a positive value just with the native options (since the many will have a lower effective value of 0).
- When a Sender supports many options well, but a few low-quality options are provided, perhaps for wider compatibility, it MAY explicitly associate a negative value just with those options (since the many will have a higher effective value of 0).
The metadata attribute urn:x-nmos:cap:meta:enabled MAY be used to indicate Constraint Sets which do not apply to the current operating configuration of a Sender, but which can be enabled via some unspecified configuration mechanism.
A Controller MUST NOT take into consideration a Constraint Set that has this attribute set to false, unless the Controller is capable of making the required configuration changes. Controllers MAY use this attribute as a hint to users that a Sender's operating point could become available subject to a reconfiguration.
If a Constraint Set is enabled or the Sender does not support offline capabilities then this attribute MAY be omitted.
A sub-Flow is defined as a member of a multiplexed flow produced by a Flow of format urn:x-nmos:format:mux. A sub-Flow MUST be a member of the parents attribute of a mux Flow.
A sub-Stream is defined as a member of a multiplexed stream consumed by a Receiver of format urn:x-nmos:format:mux.
The metadata attribute urn:x-matrox:cap:meta:format MUST be used to indicate that a Constraint Set, associated with a sub-Flow/sub-Stream, applies to a specific format. The format MAY be one of urn:x-nmos:format:video, urn:x-nmos:format:audio or urn:x-nmos:format:data.
The metadata attribute urn:x-matrox:cap:meta:layer MUST be used to indicate that a Constraint Set, associated with a sub-Flow/sub-Stream, applies to a specific layer of a given format. The layer must be an unsigned integer in the range 0 to N-1 where N the total number of layers of a given format.
The metadata urn:x-matrox:cap:meta:format and urn:x-matrox:cap:meta:layer attributes MUST be used to filter the Constraint Sets for a target sub-Flow/sub-Stream or a target mux Flow/Stream.
A sub-Flow MUST have a urn:x-matrox:layer attribute matching the associated Sender Constraint Set urn:x-matrox:cap:meta:layer meta attribute. The sub-Flow format attribute MUST match the associated Sender Constraint Set urn:x-matrox:cap:meta:format meta attribute.
A Source associated with a Receiver sub-Stream MUST have a urn:x-matrox:layer attribute matching the associated Receiver Constraint Set urn:x-matrox:cap:meta:layer meta attribute. The Source format attribute MUST match the associated Receiver Constraint Set urn:x-matrox:cap:meta:format meta attribute.
The metadata attribute urn:x-matrox:cap:meta:layer_compatibility_groups MAY be used on a mux Flow/Stream or sub-Flow/sub-Stream to indicate that a Constraint Set applies to a number of layer compatibility groups. The layer compatibility groups must be an array of unsigned integer in the range 0 to 63. A Constraint Set MAY apply to multiple compatibility groups. A Constraint Set without a urn:x-matrox:cap:meta:layer_compatibility_groups attribute MUST be assumed as being part of all groups. Only Constraint Sets that are members of a common group are compatibles. A Controller SHOULD process Constraint Sets according to their compatibility group.
A mux Flow SHOULD have a urn:x-matrox:layer_compatibility_groups attribute matching or subsetting the associated Sender Constraint Set urn:x-matrox:cap:meta:layer_compatibility_groups meta attribute. A mux Flow or sub-Flow without a urn:x-matrox:layer_compatibility_groups attribute MUST be assumed as being part of all groups. The intersection of the urn:x-matrox:layer_compatibility_groups attribute of a mux Flow and all the sub-Flows associated with the mux Flow MUST not be empty.
A sub-Flow SHOULD have a urn:x-matrox:layer_compatibility_groups attribute matching or subsetting the associated Sender Constraint Set urn:x-matrox:cap:meta:layer_compatibility_groups meta attribute. A mux Flow or sub-Flow without a urn:x-matrox:layer_compatibility_groups attribute MUST be assumed as being part of all groups. The intersection of the urn:x-matrox:layer_compatibility_groups attribute of a mux Flow and all the sub-Flows associated with the mux Flow MUST not be empty.
Informative Note: The value of an urn:x-matrox:layer_compatibility_groups attribute of a mux Flow or sub-Flow result from the application of IS-11 active constraints or dynamic mux Flow or sub-Flow reconfiguration.
A sub-Stream/sub-Flow Constraint Set MUST NOT use transport Receiver/Sender Capabilities. Such Capabilities use the urn:x-nmos:cap:transport: or urn:x-matrox:cap:transport: prefix and apply only to a Stream/Flow.
The Sender advertises a list of Constraint Sets as a JSON array of these objects, using the key constraint_sets in the caps object.
The constraint_sets as a whole are satisfied if any of the listed Constraint Sets of matching format and urn:x-matrox:layer are satisfied. For the purpose of filtering the list of Constraint Sets, the absence of the urn:x-matrox:cap:meta:format and urn:x-matrox:cap:meta:layer meta attributes provides the list of Constraint Sets that are not associated with sub-Flows/sub-Streams. The evaluation of the constraint_sets targets a Flow/Stream of one of the formats urn:x-nmos:format:audio, urn:x-nmos:format:video, urn:x-nmos:format:data, urn:x-nmos:format:mux in which the Constraint Sets do not have the urn:x-matrox:cap:meta:format and urn:x-matrox:cap:meta:layer meta attributes, or the evaluation of the constraint_sets targets a sub-Flow/sub-Stream of one of the formats urn:x-nmos:format:audio, urn:x-nmos:format:video, urn:x-nmos:format:data in which the Constraint Sets have the urn:x-matrox:cap:meta:format and urn:x-matrox:cap:meta:layer meta attributes.
When the list is empty, or none of the Constraint Sets are satisfied, the constraint_sets as a whole is thus not satisfied.
Several worked examples are provided in the Examples section.
This specification includes a JSON Schema for each Parameter Constraint Type and for Constraint Sets and the constraint_sets attribute as a whole, in the APIs/schemas directory.
The Capabilities register in the NMOS Parameter Registers and Matrox Capabilities include a supplementary schema that validates the specific requirements for every Parameter Constraint listed in the register.
IS-04 requires that the core resource version is updated when any attributes of the caps object or resource as a whole are changed.
Other attributes of the Sender resource are likely to be updated more often than caps, for example the subscription attribute is updated to reflect a new connection.
However, the capabilities of a Sender could change over its lifetime, for example, as a result of reconfiguration by some other means.
This specification therefore defines a version attribute for the caps object itself, which reflects only when that object last changed.
In order to use the finer-grained constraints mechanism defined by this specification, Senders MUST include both the constraint_sets and version attributes in the caps object.
Senders SHOULD express their capabilities as precisely as possible, using the relevant Parameter Constraints listed in the Capabilities register in the NMOS Parameter Registers and Matrox Capabilities. However, this specification may not be sufficiently expressive to indicate every type of stream or sub-Stream that a Sender can or cannot produce successfully. It is entirely possible that a Sender may fail to produce a stream or sub-Stream even if the Sender's advertised Constraint Sets indicate that it can.
A Sender MUST not produce a stream or sub-Stream that is incompatible with the advertised Sender Capabilities.
The value of the constraint_sets attribute MUST be valid according to this specification. The value of all the Constraint Set attributes MUST be valid according to the relevant specification in the Capabilities register in the NMOS Parameter Registers and Matrox Capabilities.
The Sender MUST reflect any change in its capabilities by updating the caps object as appropriate and modifying the version attribute of that object as well as the core resource version.
Controllers are strongly RECOMMENDED to support all Parameter Constraints listed in the Capabilities register in the NMOS Parameter Registers and Matrox Capabilities that are applicable for the kinds of Sender 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 it SHOULD distinguish this case to a user.
Controllers SHOULD provide an indication to a user whether a Receiver satisfies a Constraint Set of a Sender, for example in a cross-point matrix view. Controllers MAY allow a user to attempt to make a connection to a Sender or to constrain a Sender whether the Sender's constraint_sets are satisfied or not.
Controllers MAY use the version attribute of the caps object to avoid unnecessary re-evaluation of Sender capabilities.
This document modifies the original document BCP-004-01 from AMWA.
Copyright 2021 AMWA
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.