open-standards/wai/extensions/capability-constraints.md

WAI Extension: Capability Constraints

Status: Draft. Makes capability dispatch (WAI SPEC.md §4) a precondition check rather than a binary claim, by ingesting the constraint-set grammar and register pattern the broadcast-IP world already ratified. No transport, no registry service, no negotiation protocol — it evaluates values WAI already carries. A sink also declares what its display presents — resolution, refresh rate, bit depth, dynamic range and physical size — and no rendition above that is sent to it (§4); the receipt of each segment records how its rendition matched. Keywords MUST, MUST NOT, SHOULD, MAY are RFC 2119/8174.

1. The problem: support is not binary

WAI dispatch treats a capability as present or absent: a sink either claims cap or does not. Real sinks are not like that. A decoder supports a codec to a level — up to a resolution, a frame rate, a bit depth, a profile. "This capability, but only to 4K60 10-bit, this profile" is the normal case and is currently unexpressible.

The consequence is that partial support fails at decode time rather than at selection time. A sink advertises the capability, receives an object it cannot actually handle, and fails after committing to the bytes. Worse, WAI's rendition selection has nothing to evaluate, so it defers to a deployer policy the specification never states.

2. Constraint sets

A constraint set is an ORed set of constraints over named parameters, each constraint being an enumeration, a minimum, a maximum, or a combination. A sink satisfies a capability when it advertises cap and the object's declared parameters satisfy at least one of the registered constraint sets for cap.

This grammar is deliberately not invented here. It is the shape AMWA's Receiver and Sender Capabilities specifications (BCP-004-01 and BCP-004-02, both v1.0.0) use, with parameters drawn from a public register rather than a bespoke schema per implementation. WAI ingests the grammar and the register pattern, not the transport or the discovery model those specifications sit in.

• A capability registration MAY publish one or more constraint sets. A capability with none is unconstrained, which is the current behaviour and remains valid.
• A sink MUST evaluate constraint sets before dispatch, not during it. The point is to move the failure earlier; a check performed at decode has bought nothing.
• A sink MUST NOT advertise a capability whose constraint sets it cannot evaluate. Advertising a capability while ignoring its constraints is the binary behaviour this extension exists to replace.
• Where an object's declared parameters satisfy no set, the sink MUST treat the capability as unsupported for that object — not as a decode error, and not as a reason to attempt it anyway.

3. Parameters and the register

Parameters are named in a register, so two implementations constrain the same property under the same name. WAI adopts the pattern; it does not adopt the existing register wholesale, for a reason worth stating plainly:

The ratified registers are broadcast-essence-shaped. They cover media type, frame rate, colour sampling, bit depth, codec profile — which serves WAI's conventional media capabilities and nothing else. There are no entries for the neural, quantum, world or haptic families. Those register entries WAI must author itself, and until it does, those capabilities remain unconstrained under §2, which is the honest state rather than a pretended one.

• A parameter name MUST resolve in a register. An implementation-local name is not a constraint anyone else can evaluate.
• WAI-authored parameters MUST be namespaced so they cannot collide with entries authored elsewhere.

3.1 The register this revision holds

WAI's parameters are named under the prefix wai:. Each value is an integer or a string, so every evaluation is exact; a rate that would be a rational elsewhere is an integer in a stated unit here.

parameter	value	what it is
wai:codec	string	the codec string a decoder is configured with
wai:frame_width	integer	the coded width, in samples
wai:frame_height	integer	the coded height, in samples
wai:frame_rate_milli	integer	frames per 1000 seconds
wai:bit_depth	integer	bits per sample
wai:chroma	string	the chroma sampling: 4:2:0, 4:2:2, 4:4:4 or 4:0:0
wai:sample_rate	integer	audio samples per second, per channel
wai:channel_count	integer	audio channels
wai:bitrate	integer	bits per second
wai:transfer	integer	the video's transfer characteristics, as a TransferCharacteristics code point of the coding-independent code points (ISO/IEC 23001-8, as draft-pantos-hls-rfc8216bis-22 §4.4.6.2 cites it): 1, 6, 13, 14 and 15 are standard dynamic range, 16 is PQ and 18 is HLG

The families §3 names (neural, quantum, world, haptic) have no entries yet, and stay unconstrained until they do. The form a page evaluates constraint sets in, and their evaluation, are browser-sink §5; its reference implementation is the browser_sink module of wai-rs.

4. Display capability

Bits a panel cannot present are spent and never seen: pixels above its resolution, pictures above its refresh rate, bits per sample above its depth, a dynamic range above its own. A sink states what its panel presents in a display declaration, and a rendition above it is not sent. The declaration is a statement the sink makes once to whatever chooses its renditions, and makes again when its panel changes; nothing is exchanged beyond it.

4.1 The declaration

member	value	what it is
long	integer, at least 1	the panel's longer side, in its own pixels
short	integer, from 1 to long	its shorter side
refresh_milli	integer, at least 1	the most pictures it presents per 1000 seconds; for a panel whose rate varies, its highest
bit_depth	integer, 1 to 16	the bits per colour component it presents
hdr	boolean	whether it presents the range of the high-dynamic-range transfers, PQ and HLG, above standard dynamic range's
long_mm, short_mm	integer, 0 or more	its physical size along its longer and shorter sides, in millimetres; 0 where the sink does not know it

The sides are stated without orientation, so a sink that turns its panel declares nothing new. A native host reads every member from its platform's description of the display the stream is presented on. A page reads them through the interfaces it has:

• long and short: CSSOM View's screen.width and screen.height, which are in CSS pixels, each times devicePixelRatio, rounded to the nearest integer;
• bit_depth: ⌊screen.colorDepth / 3⌋, which is 8 where the user agent does not say (CSSOM View has colorDepth return 24 when it does not know the depth or withholds it);
• hdr: true when the media query (video-dynamic-range: high) or (dynamic-range: high) matches (Media Queries Level 5 §6.5, §8.2);
• refresh_milli: no interface states it, so a page measures it: 1000 times the whole number of pictures per second nearest to 10⁶ divided by the median of at least 60 intervals, in microseconds, between consecutive animation frames (of an even count, the upper of the two middle ones);
• long_mm and short_mm: 0, since a page has no interface for them.

Texts read for this section: CSSOM View Module, W3C Working Draft 16 September 2025, §2.1 and §4.3 (Screen, devicePixelRatio); Media Queries Level 5, W3C Working Draft 19 February 2026, §6.5 and §8.2; draft-pantos-hls-rfc8216bis-22 §4.4.6.2 (RESOLUTION, FRAME-RATE, VIDEO-RANGE).

4.2 The match

A rendition is read through the parameters of §3.1: w = wai:frame_width, h = wai:frame_height, r = wai:frame_rate_milli, d = wai:bit_depth and x = wai:transfer, with x = 1 where the rendition declares none (an HLS variant stream without VIDEO-RANGE is standard dynamic range, rfc8216bis-22 §4.4.6.2). Its exceedances against a declaration are the bits:

bit	name	set when
0	resolution	max(w, h) > long, or min(w, h) > short
1	refresh	r > refresh_milli
2	bit_depth	d > bit_depth
3	dynamic_range	x is 16 or 18, and hdr is false

A rendition is within the declaration when its exceedances are 0. Of the renditions a sender offers a sink (its ladder), the admissible ones are those within the declaration; where none is, the least rendition alone is admissible. The least is the first in the order of (w × h, r, d, 1 where x is 16 or 18 and 0 otherwise), ascending, and of two equal there, the one the ladder lists first. A panel smaller than every rendition is still served, by the least of them.

The match of a rendition is its exceedances, with bit 4, none_within, set when no rendition of the ladder is within the declaration. It is what a receipt records (stream-termination §3.4).

• A sender that holds a sink's declaration MUST NOT send it a rendition that is not admissible. A sink that chooses its own renditions — an HLS or DASH player's selection, a MoQ subscriber's choice of track — MUST NOT request one that is not admissible.
• A sink SHOULD declare its panel to whatever chooses its renditions, before the first is chosen, by a means this revision does not fix, and MUST declare it again when the panel changes (a window moved to another display, its dynamic range switched).
• The physical size bounds nothing in this revision: how much of a resolution a viewer resolves depends on how far away the viewer is, which a sink does not know. It is declared and recorded.
• A receipt of a segment records the match of its rendition against the declaration in effect when it was received, and a verifier refuses a segment of a rendition that was not admissible (stream-termination §6.1, rendition_above_panel).

The check is made before dispatch, as §2's is, and like §2's an unmet declaration is not a decode error: the rendition is not chosen.

5. What this is not

• It is not a negotiation protocol. There is no pre-flight exchange, no controller, and no registry service. The display declaration of §4 is a statement the sink makes, which a sender evaluates; nothing answers it. Capability-plus-budget binding before execution is already owned by JCP, and duplicating it here would put two mechanisms in the tree for one job.
• It is not a transport concern. Constraint evaluation reads values the object already declares.
• It is not an energy mechanism. A constraint set says what a sink can decode, and a display declaration what it can present; neither says what it should spend. What a rendition above the panel would have cost is not claimed as saved by this text.

6. Framing

The grammar is thin — close to a JSON-Schema subset — and that is fine. The value is not expressiveness; it is that a ratified, register-backed way of saying "supported, to here" already exists, and WAI's dispatch, which has only "supported", gains a range by adopting it.