From 9f26feabc286abde2a497b7a275b9cc4f5c5de07 Mon Sep 17 00:00:00 2001 From: Paul Adenot Date: Fri, 13 Aug 2021 10:34:14 +0200 Subject: [PATCH 1/7] Activate lint for accidental rfc2119 in non-normative section of the spec --- index.src.html | 1 + 1 file changed, 1 insertion(+) diff --git a/index.src.html b/index.src.html index 01bb50f3..db170c91 100644 --- a/index.src.html +++ b/index.src.html @@ -20,6 +20,7 @@ technology developed elsewhere. Implementers may support any combination of codecs or none at all. +Complain About:accidental-2119 yes Markup Shorthands:css no, markdown yes, dfn yes !Participate: Git Repository. !Participate: File an issue. From fdb7ccbd5544fb9ee3f985403fd5d5253d41d81c Mon Sep 17 00:00:00 2001 From: Paul Adenot Date: Fri, 13 Aug 2021 10:34:48 +0200 Subject: [PATCH 2/7] Rephrase occurences of rfc2119 words in non-normative sections --- index.src.html | 116 ++++++++++++++++++++++++------------------------- 1 file changed, 58 insertions(+), 58 deletions(-) diff --git a/index.src.html b/index.src.html index db170c91..b939956b 100644 --- a/index.src.html +++ b/index.src.html @@ -343,9 +343,9 @@ chunks as described by |config|. NOTE: This method will trigger a {{NotSupportedError}} if the User Agent - does not support |config|. Authors should first check support by calling - {{AudioDecoder/isConfigSupported()}} with |config|. User Agents are not - required to support any particular codec type or configuration. + does not support |config|. Authors are encouraged to first check support + by calling {{AudioDecoder/isConfigSupported()}} with |config|. User + Agents don't have to support any particular codec type or configuration. When invoked, run these steps: 1. If |config| is not a [=valid AudioDecoderConfig=], throw a @@ -455,7 +455,7 @@ NOTE: The returned {{AudioDecoderSupport}} {{AudioDecoderSupport/config}} will contain only the dictionary members that User Agent recognized. - Unrecognized dictionary members will be ignored. Authors may detect + Unrecognized dictionary members will be ignored. Authors can detect unrecognized dictionary members by comparing {{AudioDecoderSupport/config}} to their provided |config|. @@ -612,9 +612,9 @@ chunks as described by |config|. NOTE: This method will trigger a {{NotSupportedError}} if the User Agent - does not support |config|. Authors should first check support by calling - {{VideoDecoder/isConfigSupported()}} with |config|. User Agents are not - required to support any particular codec type or configuration. + does not support |config|. Authors are encouraged to first check support by + calling {{VideoDecoder/isConfigSupported()}} with |config|. User Agents + don't have to support any particular codec type or configuration. When invoked, run these steps: 1. If |config| is not a [=valid VideoDecoderConfig=], throw a @@ -640,15 +640,15 @@
[=Enqueues a control message=] to decode the given |chunk|. - NOTE: Authors should call {{VideoFrame/close()}} on output + NOTE: Authors are encouraged to call {{VideoFrame/close()}} on output {{VideoFrame}}s immediately when frames are no longer needed. The underlying [=media resource=]s are owned by the {{VideoDecoder}} and - failing to release them (or waiting for garbage collection) may cause + failing to release them (or waiting for garbage collection) can cause decoding to stall. NOTE: {{VideoDecoder}} requires that frames are output in the order they - expect to be presented, commonly known as presentation order. Some - {{VideoDecoder/[[codec implementation]]}}s may require the User Agent + expect to be presented, commonly known as presentation order. When using + some {{VideoDecoder/[[codec implementation]]}}s the User Agent will have to to reorder outputs into presentation order. When invoked, run these steps: @@ -735,7 +735,7 @@ NOTE: The returned {{VideoDecoderSupport}} {{VideoDecoderSupport/config}} will contain only the dictionary members that User Agent recognized. - Unrecognized dictionary members will be ignored. Authors may detect + Unrecognized dictionary members will be ignored. Authors can detect unrecognized dictionary members by comparing {{VideoDecoderSupport/config}} to their provided |config|. @@ -777,10 +777,10 @@ let |colorSpace| be `undefined`. NOTE: The codec implementation can detect a {{VideoColorSpace}} by - analyzing the bitstream. Detection is not required and may not - always be feasible. The exact method of detection is implementer - defined and codec-specific. Authors may override the - detected {{VideoColorSpace}} by providing a + analyzing the bitstream. Detection is made on a best-effort + basis. The exact method of detection is implementer defined and + codec-specific. Authors can override the detected + {{VideoColorSpace}} by providing a {{VideoDecoderConfig/colorSpace}} in the {{VideoDecoderConfig}}. 5. If {{VideoDecoderConfig/colorSpace}} [=map/exists=] in the @@ -916,9 +916,9 @@ decoding chunks as described by |config|. NOTE: This method will trigger a {{NotSupportedError}} if the User Agent - does not support |config|. Authors should first check support by calling - {{AudioEncoder/isConfigSupported()}} with |config|. User Agents are not - required to support any particular codec type or configuration. + does not support |config|. Authors are encouraged to first check support + by calling {{AudioEncoder/isConfigSupported()}} with |config|. User + Agents don't have to support any particular codec type or configuration. When invoked, run these steps: 1. If |config| is not a [=valid AudioEncoderConfig=], throw a @@ -1020,7 +1020,7 @@ NOTE: The returned {{AudioEncoderSupport}} {{AudioEncoderSupport/config}} will contain only the dictionary members that User Agent recognized. - Unrecognized dictionary members will be ignored. Authors may detect + Unrecognized dictionary members will be ignored. Authors can detect unrecognized dictionary members by comparing {{AudioEncoderSupport/config}} to their provided |config|. @@ -1235,9 +1235,10 @@ decoding chunks as described by |config|. NOTE: This method will trigger a {{NotSupportedError}} if the User Agent - does not support |config|. Authors should first check support by calling - {{VideoEncoder/isConfigSupported()}} with |config|. User Agents are not - required to support any particular codec type or configuration. + does not support |config|. Authors are encouraged to first check support + by calling {{VideoEncoder/isConfigSupported()}} with |config|. User + Agents don't have to support any particular codec type or + configuration. When invoked, run these steps: 1. If |config| is not a [=valid VideoEncoderConfig=], throw a @@ -1340,7 +1341,7 @@ NOTE: The returned {{VideoEncoderSupport}} {{VideoEncoderSupport/config}} will contain only the dictionary members that User Agent recognized. - Unrecognized dictionary members will be ignored. Authors may detect + Unrecognized dictionary members will be ignored. Authors can detect unrecognized dictionary members by comparing {{VideoEncoderSupport/config}} to their provided |config|. @@ -1520,9 +1521,9 @@ {{AudioEncoderConfig}}, and {{VideoEncoderConfig}} each define their respective configuration entries and defaults. - NOTE: Support for a given configuration may change dynamically if the - hardware is altered (e.g. external GPU unplugged) or if required - hardware resources are exhausted. User Agents should describe support on + NOTE: Support for a given configuration can change dynamically if the + hardware is altered (e.g. external GPU unplugged) or if an essential + hardware resources are exhausted. User Agents describe support on a best-effort basis given the resources that are available at the time of the query. @@ -1734,8 +1735,8 @@
A sequence of codec specific bytes, commonly known as extradata. - NOTE: The registrations in the [[WEBCODECS-CODEC-REGISTRY]] may describe whether/how - to populate this sequence, corresponding to the provided + NOTE: The registrations in the [[WEBCODECS-CODEC-REGISTRY]] describes + whether/how to populate this sequence, corresponding to the provided {{VideoDecoderConfig/codec}}.
@@ -1765,10 +1766,9 @@ NOTE: {{VideoFrame/displayWidth}} and {{VideoFrame/displayHeight}} can both be - different from {{VideoDecoderConfig/displayAspectWidth}} and - {{VideoDecoderConfig/displayAspectHeight}}, but they should have identical - ratios, after scaling is applied when - [=create a videoframe|creating the video frame=]. + different from {{VideoDecoderConfig/displayAspectWidth}} and + {{VideoDecoderConfig/displayAspectHeight}}, but have identical ratios, after scaling is applied when [=create a videoframe|creating the + video frame=].
colorSpace
@@ -1791,8 +1791,8 @@ is output. NOTE: In addition to User Agent and hardware limitations, some codec - bitstreams may require a minimum number of inputs before any output can be - produced. + bitstreams require a minimum number of inputs before any output can be + produced.
@@ -1808,8 +1808,8 @@ }; -NOTE: Codec-specific extensions to {{AudioEncoderConfig}} may be defined by the - registrations in the [[WEBCODECS-CODEC-REGISTRY]]. +NOTE: Codec-specific extensions to {{AudioEncoderConfig}} are described in + their registrations in the [[WEBCODECS-CODEC-REGISTRY]]. To check if an {{AudioEncoderConfig}} is a valid AudioEncoderConfig, run these steps: @@ -1853,7 +1853,7 @@ }; -NOTE: Codec-specific extensions to {{VideoEncoderConfig}} may be defined by the +NOTE: Codec-specific extensions to {{VideoEncoderConfig}} are described in their registrations in the [[WEBCODECS-CODEC-REGISTRY]]. To check if a {{VideoEncoderConfig}} is a valid VideoEncoderConfig, @@ -1907,11 +1907,11 @@ NOTE: Providing a {{VideoEncoderConfig/displayWidth}} or {{VideoEncoderConfig/displayHeight}} that differs from {{VideoEncoderConfig/width}} and {{VideoEncoderConfig/height}} signals - that chunks should be scaled after decoding to arrive at the final + that chunks are to be scaled after decoding to arrive at the final display aspect ratio. For many codecs this is merely pass-through information, but some codecs - may optionally include display sizing in the bitstream. + can /ometimes include display sizing in the bitstream.
@@ -2001,9 +2001,9 @@ strategy will be to prioritize hardware acceleration at higher resolutions with a fallback to software codecs if hardware acceleration fails. - Authors should carefully weigh the tradeoffs when setting a hardware - acceleration preference. The precise tradeoffs will be device-specific, but - authors should generally expect the following: + Authors are encouraged to carefully weigh the tradeoffs when setting a + hardware acceleration preference. The precise tradeoffs will be + device-specific, but authors can generally expect the following: * Setting a value of {{HardwareAcceleration/prefer-hardware}} or {{HardwareAcceleration/prefer-software}} may significantly restrict what @@ -2019,7 +2019,7 @@ * Hardware acceleration will often be more power efficient than purely software based codecs. * For lower resolution content, the overhead added by hardware acceleration - may yield decreased performance and power efficiency compared to purely + can yield decreased performance and power efficiency compared to purely software based codecs. Given these tradeoffs, a good example of using "prefer-hardware" would be if @@ -2332,7 +2332,7 @@ need for expensive copies, this specification defines a scheme for reference counting (`clone()` and `close()`). -NOTE: Authors should take care to invoke `close()` immediately when frames are +NOTE: Authors are encourage to call `close()` immediately when frames are no longer needed. ### Reference Counting ### {#raw-media-memory-model-reference-counting} @@ -2357,7 +2357,7 @@ referenced by a `[[resource reference]]`. NOTE: When a [=media resource=] is no longer referenced by a - `[[resource reference]]`, the resource may be destroyed. User Agents are + `[[resource reference]]`, the resource can be destroyed. User Agents are encouraged to destroy such resources quickly to reduce memory pressure and facilitate resource reuse. @@ -2865,7 +2865,7 @@ VideoFrame Interface {#videoframe-interface} -------------------------------------------- -NOTE: {{VideoFrame}} is a {{CanvasImageSource}}. A {{VideoFrame}} may be +NOTE: {{VideoFrame}} is a {{CanvasImageSource}}. A {{VideoFrame}} can be passed to any method accepting a {{CanvasImageSource}}, including {{CanvasDrawImage}}'s {{CanvasDrawImage/drawImage()}}. @@ -3023,8 +3023,8 @@ 2. Let |resource| be a new [=media resource=] containing a copy of |image|'s [=bitmap data=]. - NOTE: Implementers should avoid a deep copy by using reference - counting where feasible. + NOTE: Implementers are encouraged to avoid a deep copy by using + reference counting where feasible. 3. Let |width| be `image.width` and |height| be `image.height`. 4. Run the [=VideoFrame/Initialize Frame With Resource and Size=] @@ -3572,7 +3572,7 @@ |minAllocationSize|. NOTE: The above step uses a maximum to allow for the - possibility that user specified plane offsets may reorder + possibility that user specified plane offsets reorder planes. 18. Let |earlierPlaneIndex| be `0`. @@ -3661,10 +3661,10 @@
NOTE: The steps of {{VideoFrame/copyTo()}} or {{VideoFrame/allocationSize()}} will enforce the following requirements: - * The coordinates of {{VideoFrameCopyToOptions/rect}} must be + * The coordinates of {{VideoFrameCopyToOptions/rect}} are sample-aligned as determiend by {{VideoFrame/[[format]]}}. * If {{VideoFrameCopyToOptions/layout}} [=map/exists=], a {{PlaneLayout}} - must be provided for all planes. + is provided for all planes.
: rect @@ -4234,9 +4234,9 @@ :: NOTE: Calling {{ImageDecoder/decode()}} on the constructed {{ImageDecoder}} will trigger a {{NotSupportedError}} if the User Agent does not support - |type|. Authors should first check support by calling - {{ImageDecoder/isTypeSupported()}} with |type|. User Agents are not - required to support any particular type. + |type|. Authors are encouraged to first check support by calling + {{ImageDecoder/isTypeSupported()}} with |type|. User Agents don't have to + support any particular type. When invoked, run these steps: 1. If |init| is not [=valid ImageDecoderInit=], throw a {{TypeError}}. @@ -4428,7 +4428,7 @@ NOTE: If [=this=] was constructed with {{ImageDecoderInit/data}} as a {{ReadableStream}}, the - {{ImageTrack/frameCount}} may change as additional bytes are + {{ImageTrack/frameCount}} can change as additional bytes are appended to {{ImageDecoder/[[encoded data]]}}. See the [=Update Tracks=] algorithm. @@ -4763,7 +4763,7 @@
NOTE: For [=Progressive Images=], setting - {{ImageDecodeOptions/completeFramesOnly}} to `false` may be used to + {{ImageDecodeOptions/completeFramesOnly}} to `false` can be used to offer users a preview an image that is still being buffered from the network (via the {{ImageDecoderInit/data}} {{ReadableStream}}). @@ -4815,7 +4815,7 @@ :: The promise used to signal when the {{ImageTrackList}} has been populated with {{ImageTrack}}s. - NOTE: {{ImageTrack}} {{ImageTrack/frameCount}} may receive subsequent + NOTE: {{ImageTrack}} {{ImageTrack/frameCount}} can receive subsequent updates until {{ImageDecoder/complete}} is `true`. : [[track list]] From fec2acbbed465f41c2aea15b307248e69a741859 Mon Sep 17 00:00:00 2001 From: Paul Adenot Date: Fri, 13 Aug 2021 10:35:42 +0200 Subject: [PATCH 3/7] Make one occurence normative, keep the rfc2119 word --- index.src.html | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/index.src.html b/index.src.html index b939956b..7a6cdded 100644 --- a/index.src.html +++ b/index.src.html @@ -3356,9 +3356,9 @@ :: 1. If |overrideColorSpace| is provided, return a new {{VideoColorSpace}} constructed with |overrideColorSpace|. - NOTE: User Agents may replace `null` members of the provided - |overrideColorSpace| with guessed values as determined by - implementer defined heuristics. + User Agents MAY replace `null` members of the provided + |overrideColorSpace| with guessed values as determined by implementer + defined heuristics. 2. Otherwise, if {{VideoFrame/[[format]]}} is an [=RGB format=] return a new instance of the [=sRGB Color Space=] From 587c6ae279767f2649e717ddc10c3125e2eabbfa Mon Sep 17 00:00:00 2001 From: Paul Adenot Date: Fri, 13 Aug 2021 10:54:30 +0200 Subject: [PATCH 4/7] Mark three sections as non-normative. Fix rfc2119 word usage in those sections. --- index.src.html | 80 +++++++++++++++++++++++++++----------------------- 1 file changed, 44 insertions(+), 36 deletions(-) diff --git a/index.src.html b/index.src.html index 7a6cdded..a33310e3 100644 --- a/index.src.html +++ b/index.src.html @@ -202,18 +202,20 @@ Background {#processing-model-background} ----------------------------------------- -This section is non-normative. - -The codec interfaces defined by the specification are designed such that new -codec tasks may be scheduled while previous tasks are still pending. For -example, web authors may call `decode()` without waiting for a previous -`decode()` to complete. This is achieved by offloading underlying codec tasks to -a separate thread for parallel execution. - -This section describes threading behaviors as they are visible from the -perspective of web authors. Implementers may choose to use more or less threads -as long as the exernally visible behaviors of blocking and sequencing are -maintained as follows. +
+ This section is non-normative. + + The codec interfaces defined by the specification are designed such that new + codec tasks can be scheduled while previous tasks are still pending. For + example, web authors can call `decode()` without waiting for a previous + `decode()` to complete. This is achieved by offloading underlying codec tasks + to a separate thread for parallel execution. + + This section describes threading behaviors as they are visible from the + perspective of web authors. Implementers can choose to use more or less + threads as long as the exernally visible behaviors of blocking and sequencing + are maintained as follows. +
Control Thread and Codec Thread {#control-thread-and-codec-thread} ------------------------------------------------------------------ @@ -4147,17 +4149,19 @@ Background {#image-decoding-background} ------------------------------------- -This section is non-normative. +
+ This section is non-normative. -Image codec definitions are typically accompanied by a definition for a -corresponding file format. Hence image decoders often perform both duties of -unpacking (demuxing) as well as decoding the encoded image data. The WebCodecs -{{ImageDecoder}} follows this pattern, which motivates an interface design that -is notably different from that of {{VideoDecoder}} and {{AudioDecoder}}. + Image codec definitions are typically accompanied by a definition for a + corresponding file format. Hence image decoders often perform both duties of + unpacking (demuxing) as well as decoding the encoded image data. The WebCodecs + {{ImageDecoder}} follows this pattern, which motivates an interface design that + is notably different from that of {{VideoDecoder}} and {{AudioDecoder}}. -In spite of these differences, {{ImageDecoder}} uses the same -[=codec processing model=] as the other codec interfaces. Additionally, -{{ImageDecoder}} uses the {{VideoFrame}} interface to describe decoded outputs. + In spite of these differences, {{ImageDecoder}} uses the same + [=codec processing model=] as the other codec interfaces. Additionally, + {{ImageDecoder}} uses the {{VideoFrame}} interface to describe decoded outputs. +
ImageDecoder Interface {#imagedecoder-interface} ------------------------------------------------ @@ -5079,18 +5083,22 @@ Best Practices for Authors Using WebCodecs{#best-practices-developers} ====================================================================== -While WebCodecs internally operates on background threads, authors working with -realtime media or in contended main thread environments should ensure their -media pipelines operate in worker contexts entirely independent of the main -thread where possible. For example, realtime media processing of {{VideoFrame}}s -should generally be done in a worker context. - -The main thread has significant potential for high contention and jank that may -go unnoticed in development, yet degrade inconsistently across devices and User -Agents in the field -- potentially dramatically impacting the end user -experience. Ensuring the media pipeline is decoupled from the main thread helps -provide a smooth experience for end users. - -Authors using the main thread for their media pipeline should be sure of their -target frame rates, main thread workload, how their application will be -embedded, and the class of devices their users will be using. +
+ This section is non-normative. + + While WebCodecs internally operates on background threads, authors working with + realtime media or in contended main thread environments are encouraged to ensure their + media pipelines operate in worker contexts entirely independent of the main + thread where possible. For example, realtime media processing of {{VideoFrame}}s + are generally be done in a worker context. + + The main thread has significant potential for high contention and jank that can + go unnoticed in development, yet degrade inconsistently across devices and User + Agents in the field -- potentially dramatically impacting the end user + experience. Ensuring the media pipeline is decoupled from the main thread helps + provide a smooth experience for end users. + + Authors using the main thread for their media pipeline ought to be sure of + their target frame rates, main thread workload, how their application will be + embedded, and the class of devices their users will be using. +
From 56080e7d5b32067c2dc2b433aa2a935c76dca511 Mon Sep 17 00:00:00 2001 From: Paul Adenot Date: Fri, 20 Aug 2021 15:23:52 +0200 Subject: [PATCH 5/7] Put the RFC2119 words in tags and rewrap the paragraphs This was done mostly via this scripts: > #!/usr/bin/env python > > # no optional and required because they are webidl keywords and don't > # appear otherwise in the spec > RFC_2119_LIST_LOWER=("must", "must not", "shall", "shall not", "should", "should not", "recommended", "may") > RFC_2119_LIST_UPPER=("MUST", "MUST NOT", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY") > > fin = open("index.src.html", "rt") > fout = open("index-replaced.src.html", "wt") > for line in fin: > replaced = line > for i, word in enumerate(RFC_2119_LIST_LOWER): > replaced = replaced.replace(RFC_2119_LIST_LOWER[i], > "" + RFC_2119_LIST_UPPER[i] + "") > fout.write(replaced) > fin.close() > fout.close() and then rewrapped in vim. --- index.src.html | 304 ++++++++++++++++++++++++++----------------------- 1 file changed, 161 insertions(+), 143 deletions(-) diff --git a/index.src.html b/index.src.html index a33310e3..22b91dbe 100644 --- a/index.src.html +++ b/index.src.html @@ -17,8 +17,8 @@ This specification does not specify or require any particular codec or method of encoding or decoding. The purpose of this specification is to provide JavaScript interfaces to implementations of existing codec - technology developed elsewhere. Implementers may support any combination of - codecs or none at all. + technology developed elsewhere. Implementers are free to + support any combination of codecs or none at all. Complain About:accidental-2119 yes Markup Shorthands:css no, markdown yes, dfn yes @@ -149,16 +149,17 @@ : Internal Pending Output :: Codec outputs such as {{VideoFrame}}s that currently reside in the internal pipeline of the underlying codec implementation. The underlying codec - implementation may emit new outputs only when new inputs are provided. The - underlying codec implementation must emit all outputs in response to a - flush. + implementation MAY emit new outputs only when new + inputs are provided. The underlying codec implementation MUST emit all outputs in response to a flush. : Codec System Resources :: Resources including CPU memory, GPU memory, and exclusive handles to specific - decoding/encoding hardware that may be allocated by the User Agent as part - of codec configuration or generation of {{AudioData}} and {{VideoFrame}} - objects. Such resources may be quickly exhausted and should be released - immediately when no longer in use. + decoding/encoding hardware that MAY be allocated by + the User Agent as part of codec configuration or generation of {{AudioData}} + and {{VideoFrame}} objects. Such resources MAY be + quickly exhausted and SHOULD be released immediately + when no longer in use. : Temporal Layer :: A grouping of {{EncodedVideoChunk}}s whose timestamp cadence produces a @@ -255,7 +256,7 @@ message means performing a sequence of steps specified by the method that enqueued the message. -The codec processing loop must run these steps: +The codec processing loop MUST run these steps: 1. While true: 1. If the [=control message queue=] is empty, [=continue=]. 2. Dequeue |front message| from the [=control message queue=]. @@ -299,7 +300,7 @@ :: Callback given at construction for decode errors. : [[key chunk required]] :: A boolean indicating that the next chunk passed to {{AudioDecoder/decode()}} - must describe a [=key chunk=] as indicated by + MUST describe a [=key chunk=] as indicated by {{EncodedAudioChunk/[[type]]}}. : \[[state]] :: The current {{CodecState}} of this {{AudioDecoder}}. @@ -378,7 +379,7 @@ 2. If {{AudioDecoder/[[key chunk required]]}} is `true`: 1. If |chunk|.{{EncodedAudioChunk/[[type]]}} is not {{EncodedAudioChunkType/key}}, throw a {{DataError}}. - 2. Implementers should inspect the |chunk|'s + 2. Implementers SHOULD inspect the |chunk|'s {{EncodedAudioChunk/[[internal data]]}} to verify that it is truly a [=key chunk=]. If a mismatch is detected, throw a {{DataError}}. @@ -567,11 +568,14 @@ : [[active decoder config]] :: The {{VideoDecoderConfig}} that is actively applied. : [[key chunk required]] -:: A boolean indicating that the next chunk passed to {{VideoDecoder/decode()}} must describe a [=key chunk=] as indicated by {{EncodedVideoChunk/type}}. +:: A boolean indicating that the next chunk passed to {{VideoDecoder/decode()}} + MUST describe a [=key chunk=] as indicated by + {{EncodedVideoChunk/type}}. : \[[state]] :: The current {{CodecState}} of this {{VideoDecoder}}. : \[[decodeQueueSize]] -:: The number of pending decode requests. This number will decrease as the underlying codec is ready to accept new input. +:: The number of pending decode requests. This number will decrease as the + underlying codec is ready to accept new input. : [[pending flush promises]] :: A list of unresolved promises returned by calls to {{VideoDecoder/flush()}}. @@ -659,7 +663,7 @@ 2. If {{VideoDecoder/[[key chunk required]]}} is `true`: 1. If |chunk|.{{EncodedVideoChunk/type}} is not {{EncodedVideoChunkType/key}}, throw a {{DataError}}. - 2. Implementers should inspect the |chunk|'s + 2. Implementers SHOULD inspect the |chunk|'s {{EncodedVideoChunk/[[internal data]]}} to verify that it is truly a [=key chunk=]. If a mismatch is detected, throw a {{DataError}}. @@ -1079,9 +1083,9 @@ |outputConfig|.{{AudioDecoderConfig/numberOfChannels}}. 4. Assign |outputConfig|.{{AudioDecoderConfig/description}} with a sequence of codec specific bytes as determined by the - {{AudioEncoder/[[codec implementation]]}}. The User Agent must - ensure that the provided description could be used to - correctly decode output. + {{AudioEncoder/[[codec implementation]]}}. The User Agent MUST ensure that the provided description + could be used to correctly decode output. NOTE: The codec specific requirements for populating the {{AudioDecoderConfig/description}} are described in the @@ -1137,8 +1141,8 @@ : decoderConfig -:: A {{AudioDecoderConfig}} that authors may use to decode the associated - {{EncodedAudioChunk}}. +:: A {{AudioDecoderConfig}} that authors MAY use to + decode the associated {{EncodedAudioChunk}}. VideoEncoder Interface {#videoencoder-interface} @@ -1402,9 +1406,9 @@ `outputConfig.displayHeight`. 6. Assign the remaining keys of `outputConfig` as determined by {{VideoEncoder/[[codec implementation]]}}. The User Agent - must ensure that the configuration is completely described - such that |outputConfig| could be used to correctly decode - |output|. + MUST ensure that the configuration is + completely described such that |outputConfig| could be used to + correctly decode |output|. NOTE: The codec specific requirements for populating the {{VideoDecoderConfig/description}} are described in the @@ -1478,8 +1482,8 @@ : decoderConfig -:: A {{VideoDecoderConfig}} that authors may use to decode the associated - {{EncodedVideoChunk}}. +:: A {{VideoDecoderConfig}} that authors MAY use to + decode the associated {{EncodedVideoChunk}}. : svc :: A collection of metadata describing this {{EncodedVideoChunk}} with respect @@ -1524,7 +1528,7 @@ respective configuration entries and defaults. NOTE: Support for a given configuration can change dynamically if the - hardware is altered (e.g. external GPU unplugged) or if an essential + hardware is altered (e.g. external GPU unplugged) or if essential hardware resources are exhausted. User Agents describe support on a best-effort basis given the resources that are available at the time of the query. @@ -1640,7 +1644,8 @@ A codec string describes a given codec format to be used for encoding or decoding. -A valid codec string must meet the following conditions. +A valid codec string MUST meet the following +conditions. 1. Is valid per the relevant codec specification (see examples below). 2. It describes a single codec. 3. It is unambiguous about codec profile, level, and constraint bits for codecs @@ -1657,8 +1662,9 @@ level or are less constrained than requested. The format and semantics for codec strings are defined by codec registrations -listed in the [[WEBCODECS-CODEC-REGISTRY]]. A compliant implementation may support any -combination of codec registrations or none at all. +listed in the [[WEBCODECS-CODEC-REGISTRY]]. A compliant implementation MAY support any combination of codec registrations or +none at all. AudioDecoderConfig{#audio-decoder-config} ----------------------------------------- @@ -1877,7 +1883,7 @@ The encoded width of output {{EncodedVideoChunk}}s in pixels, prior to any display aspect ratio adjustments. - The encoder must scale any {{VideoFrame}} whose + The encoder MUST scale any {{VideoFrame}} whose {{VideoFrame/[[visible width]]}} differs from this value. @@ -1886,7 +1892,7 @@ The encoded height of output {{EncodedVideoChunk}}s in pixels, prior to any display aspect ratio adjustments. - The encoder must scale any {{VideoFrame}} whose + The encoder MUST scale any {{VideoFrame}} whose {{VideoFrame/[[visible height]]}} differs from this value.
@@ -1913,7 +1919,7 @@ display aspect ratio. For many codecs this is merely pass-through information, but some codecs - can /ometimes include display sizing in the bitstream. + can sometimes include display sizing in the bitstream.
@@ -1925,11 +1931,11 @@
framerate
The expected frame rate in frames per second, if known. This value, along - with the frame {{VideoFrame/timestamp}}, should be used by the video encoder - to calculate the optimal byte length for each encoded frame. Additionally, - the value should be considered a target deadline for outputting encoding - chunks when {{VideoEncoderConfig/latencyMode}} is set to - {{LatencyMode/realtime}}. + with the frame {{VideoFrame/timestamp}}, SHOULD be + used by the video encoder to calculate the optimal byte length for each + encoded frame. Additionally, the value SHOULD be + considered a target deadline for outputting encoding chunks when + {{VideoEncoderConfig/latencyMode}} is set to {{LatencyMode/realtime}}.
hardwareAcceleration
@@ -1940,10 +1946,11 @@
alpha
- Whether the alpha component of the {{VideoFrame}} inputs should be kept - or discarded prior to encoding. If {{VideoEncoderConfig/alpha}} is - equal to {{AlphaOption/discard}}, alpha data is always discarded, regardless - of a {{VideoFrame}}'s {{VideoFrame/[[format]]}}. + Whether the alpha component of the {{VideoFrame}} inputs SHOULD be kept or discarded prior to encoding. If + {{VideoEncoderConfig/alpha}} is equal to {{AlphaOption/discard}}, alpha data + is always discarded, regardless of a {{VideoFrame}}'s + {{VideoFrame/[[format]]}}.
scalabilityMode
@@ -2036,13 +2043,15 @@
no-preference
- Indicates that the User Agent may use hardware acceleration if it is - available and compatible with other aspects of the codec configuration. + Indicates that the User Agent MAY use hardware + acceleration if it is available and compatible with other aspects of the + codec configuration.
prefer-software
- Indicates that the User Agent SHOULD prefer a software codec implementation. - User Agents may ignore this value for any reason. + Indicates that the User Agent SHOULD prefer a + software codec implementation. User Agents may ignore this value for any + reason. NOTE: This may cause the configuration to be unsupported on platforms where an unaccelerated codec is unavailable or is incompatible with other aspects @@ -2050,8 +2059,8 @@
prefer-hardware
- Indicates that the User Agent SHOULD prefer hardware acceleration. User - Agents may ignore this value for any reason. + Indicates that the User Agent SHOULD prefer + hardware acceleration. User Agents may ignore this value for any reason. NOTE: This may cause the configuration to be unsupported on platforms where an accelerated codec is unavailable or is incompatible with other aspects of @@ -2068,19 +2077,19 @@ }; -Describes how the user agent should behave when dealing with alpha channels, for -a variety of different operations. +Describes how the user agent SHOULD behave when dealing +with alpha channels, for a variety of different operations.
keep
- Indicates that the user agent should preserve alpha channel data for - {{VideoFrame}}s, if it is present. + Indicates that the user agent SHOULD preserve alpha + channel data for {{VideoFrame}}s, if it is present.
discard
- Indicates that the user agent should ignore or remove {{VideoFrame}}'s alpha - channel data. + Indicates that the user agent SHOULD ignore or + remove {{VideoFrame}}'s alpha channel data.
@@ -2094,22 +2103,26 @@ : quality -:: Indicates that the User Agent should optimize for encoding quality. In - this mode: - * User Agents may increase encoding latency to improve quality. - * User Agents must not drop frames to achieve the target - {{VideoEncoderConfig/bitrate}} and/or {{VideoEncoderConfig/framerate}}. - * {{VideoEncoderConfig/framerate}} should not be used as a target deadline - for emitting encoded chunks. +:: Indicates that the User Agent SHOULD optimize for + encoding quality. In this mode: + * User Agents MAY increase encoding latency to + improve quality. + * User Agents MUST not drop frames to achieve the + target {{VideoEncoderConfig/bitrate}} and/or + {{VideoEncoderConfig/framerate}}. + * {{VideoEncoderConfig/framerate}} SHOULD not be + used as a target deadline for emitting encoded chunks. : realtime -:: Indicates that the User Agent should optimize for low latency. In this +:: Indicates that the User Agent SHOULD optimize for + low latency. In this mode: - * User Agents may sacrifice quality to improve latency. - * User Agents may drop frames to achieve the target + * User Agents MAY sacrifice quality to improve + latency. + * User Agents MAY drop frames to achieve the target {{VideoEncoderConfig/bitrate}} and/or {{VideoEncoderConfig/framerate}}. - * {{VideoEncoderConfig/framerate}} should be used as a target deadline for - emitting encoded chunks. + * {{VideoEncoderConfig/framerate}} SHOULD be used + as a target deadline for emitting encoded chunks. Configuration Equivalence{#config-equivalence} ---------------------------------------------- @@ -2330,9 +2343,9 @@ This section is non-normative. -Decoded media data may occupy a large amount of system memory. To minimize the -need for expensive copies, this specification defines a scheme for reference -counting (`clone()` and `close()`). +Decoded media data MAY occupy a large amount of system +memory. To minimize the need for expensive copies, this specification defines a +scheme for reference counting (`clone()` and `close()`). NOTE: Authors are encourage to call `close()` immediately when frames are no longer needed. @@ -2355,8 +2368,8 @@ will clear their [[resource reference]] slot, releasing the reference their [=media resource=]. -A [=media resource=] must remain alive at least as long as it continues to be -referenced by a `[[resource reference]]`. +A [=media resource=] MUST remain alive at least as long +as it continues to be referenced by a `[[resource reference]]`. NOTE: When a [=media resource=] is no longer referenced by a `[[resource reference]]`, the resource can be destroyed. User Agents are @@ -2374,15 +2387,15 @@ Transferring an {{AudioData}} or {{VideoFrame}} moves its `[[resource reference]]` to the destination object and closes (as in {{AudioData/close()}}) -the source object. Authors may use this facility +the source object. Authors MAY use this facility to move an {{AudioData}} or {{VideoFrame}} between realms without copying the underlying [=media resource=]. Serializing an {{AudioData}} or {{VideoFrame}} effectively clones (as in {{VideoFrame/clone()}}) the source object, resulting in two objects that -reference the same [=media resource=]. Authors may use this facility to clone -an {{AudioData}} or {{VideoFrame}} to another realm without copying the -underlying [=media resource=]. +reference the same [=media resource=]. Authors MAY use +this facility to clone an {{AudioData}} or {{VideoFrame}} to another realm +without copying the underlying [=media resource=]. AudioData Interface {#audiodata-interface} --------------------------------------------- @@ -2843,7 +2856,7 @@ {{f32}}. When samples are stored in {{s32}}, each sample MUST be left-shifted by `8` bits. By virtue of this process, samples outside of the valid 24-bit range ([-8388608, +8388607]) will be clipped. To avoid clipping and ensure lossless -transport, samples may be converted to {{f32}}. +transport, samples MAY be converted to {{f32}}. NOTE: While clipping is unavoidable in {{u8}}, {{s16}}, and {{s32}} samples due to their storage types, implementations SHOULD take care not to clip internally @@ -2999,10 +3012,10 @@ throw an {{InvalidStateError}} {{DOMException}}. 3. Let |resource| be a new [=media resource=] containing a copy of |image|'s media data. If this is an animated image, |image|'s - [=bitmap data=] must only be taken from the default image of the - animation (the one that the format defines is to be used when - animation is not supported or is disabled), or, if there is no - such image, the first frame of the animation. + [=bitmap data=] MUST only be taken from the + default image of the animation (the one that the format defines is + to be used when animation is not supported or is disabled), or, if + there is no such image, the first frame of the animation. 4. Let |width| and |height| be the [=natural width=] and [=natural height=] of |image|. 5. Run the [=VideoFrame/Initialize Frame With Resource and Size=] @@ -3068,13 +3081,14 @@ {{VideoFrameBufferInit/visibleRect}} and {{VideoFrameBufferInit/layout}} to determine where in |data| the pixels for each plane reside. - The User Agent may choose to allocate |resource| with a larger coded - size and plane strides to improve memory alignment. Increases will be - reflected by {{VideoFrame/codedWidth}} and {{VideoFrame/codedHeight}}. - Additionally, the User Agent may use - {{VideoFrameBufferInit/visibleRect}} to copy only the visible rectangle. - It may also reposition the visible rectangle within |resource|. The - final position will be reflected by {{VideoFrame/visibleRect}}. + The User Agent MAY choose to allocate + |resource| with a larger coded size and plane strides to improve memory + alignment. Increases will be reflected by {{VideoFrame/codedWidth}} and + {{VideoFrame/codedHeight}}. Additionally, the User Agent MAY use {{VideoFrameBufferInit/visibleRect}} to + copy only the visible rectangle. It MAY also + reposition the visible rectangle within |resource|. The final position + will be reflected by {{VideoFrame/visibleRect}}. 12. Let |resourceCodedWidth| be the coded width of |resource|. 13. Let |resourceCodedHeight| be the coded height of |resource|. @@ -3083,9 +3097,9 @@ 15. Let |resourceVisibleTop| be the top offset for the visible rectangle of |resource|. - ISSUE: The spec should provide definitions (and possibly diagrams) for - coded size, visible rectangle, and display size. See - [#166](https://github.com/w3c/webcodecs/issues/166). + ISSUE: The spec SHOULD provide definitions (and + possibly diagrams) for coded size, visible rectangle, and display size. + See [#166](https://github.com/w3c/webcodecs/issues/166). 16. Let |frame| be a new {{VideoFrame}} object initialized as follows: 1. Assign |resourceCodedWidth|, |resourceCodedHeight|, @@ -3640,9 +3654,9 @@ ### Rendering ### {#videoframe-rendering} When rendered, for example by {{CanvasDrawImage}} -{{CanvasDrawImage/drawImage()}}, a {{VideoFrame}} must be converted to a -color space compatible with the rendering target, unless color conversion is -explicitly disabled. +{{CanvasDrawImage/drawImage()}}, a {{VideoFrame}} MUST +be converted to a color space compatible with the rendering target, unless color +conversion is explicitly disabled. Color space conversion during {{ImageBitmap}} construction is controlled by {{ImageBitmapOptions}} {{ImageBitmapOptions/colorSpaceConversion}}. Setting this @@ -3698,11 +3712,11 @@ --------------------------- A {{PlaneLayout}} is a dictionary specifying the offset and stride of a {{VideoFrame}} plane once copied to a {{BufferSource}}. A sequence of -{{PlaneLayout}}s may be provided to {{VideoFrame}}'s {{VideoFrame/copyTo()}} to -specify how the plane is laid out in the destination {{BufferSource}}}. -Alternatively, callers can inspect {{VideoFrame/copyTo()}}'s returned sequence -of {{PlaneLayout}}s to learn the the offset and stride for planes as decided by -the User Agent. +{{PlaneLayout}}s MAY be provided to {{VideoFrame}}'s +{{VideoFrame/copyTo()}} to specify how the plane is laid out in the destination +{{BufferSource}}}. Alternatively, callers can inspect {{VideoFrame/copyTo()}}'s +returned sequence of {{PlaneLayout}}s to learn the the offset and stride for +planes as decided by the User Agent. dictionary PlaneLayout { @@ -4723,17 +4737,18 @@ : <dfn dict-member for=ImageDecoderInit>desiredWidth</dfn> :: Indicates a desired width for decoded outputs. Implementation is best - effort; decoding to a desired width may not be supported by all formats/ - decoders. + effort; decoding to a desired width <em class="rfc2119">MAY</em> not be + supported by all formats/ decoders. : <dfn dict-member for=ImageDecoderInit>desiredHeight</dfn> :: Indicates a desired height for decoded outputs. Implementation is best - effort; decoding to a desired height may not be supported by all - formats/decoders. + effort; decoding to a desired height <em class="rfc2119">MAY</em> not be + supported by all formats/decoders. : <dfn dict-member for=ImageDecoderInit>preferAnimation</dfn> :: For images with multiple tracks, this indicates whether the - initial track selection should prefer an animated track. + initial track selection <em class="rfc2119">SHOULD</em> prefer an animated + track. NOTE: See the [=ImageDecoder/Get Default Selected Track Index=] algorithm. @@ -4753,10 +4768,10 @@ : <dfn dict-member for=ImageDecodeOptions>completeFramesOnly</dfn> :: For [=Progressive Images=], a value of `false` indicates that the decoder - may output an {{ImageDecodeResult/image}} with reduced detail. Each - subsequent call to {{ImageDecoder/decode()}} for the same - {{ImageDecodeOptions/frameIndex}} will resolve to produce an image with a - higher [=Progressive Image Frame Generation=] (more image detail) than the + <em class="rfc2119">MAY</em> output an {{ImageDecodeResult/image}} with + reduced detail. Each subsequent call to {{ImageDecoder/decode()}} for the + same {{ImageDecodeOptions/frameIndex}} will resolve to produce an image with + a higher [=Progressive Image Frame Generation=] (more image detail) than the previous call, until finally the full-detail image is produced. If {{ImageDecodeOptions/completeFramesOnly}} is assigned `true`, or if the @@ -5006,9 +5021,9 @@ The primary security impact is that features of this API make it easier for an attacker to exploit vulnerabilities in the underlying platform codecs. -Additionally, new abilities to configure and control the codecs may allow for -new exploits that rely on a specific configuration and/or sequence of control -operations. +Additionally, new abilities to configure and control the codecs <em +class="rfc2119">MAY</em> allow for new exploits that rely on a specific +configuration and/or sequence of control operations. Platform codecs are historically an internal detail of APIs like {{HTMLMediaElement}}, [[WEBAUDIO]], and [[WebRTC]]. In this way, it has always @@ -5025,17 +5040,17 @@ affords attackers the ability to invoke sequences of control methods that were not previously possible via the higher level APIs. -User Agents should mitigate this risk by extensively fuzzing their -implementation with random inputs and control method invocations. Additionally, -User Agents are encouraged to isolate their underlying codecs in processes with -restricted privileges (sandbox) as a barrier against successful exploits being -able to read user data. +User Agents <em class="rfc2119">SHOULD</em> mitigate this risk by extensively +fuzzing their implementation with random inputs and control method invocations. +Additionally, User Agents are encouraged to isolate their underlying codecs in +processes with restricted privileges (sandbox) as a barrier against successful +exploits being able to read user data. An additional concern is exposing the underlying codecs to input mutation race -conditions. Specifically, it should not be possible for a site to mutate a codec -input or output while the underlying codec may still be operating on that data. -This concern is mitigated by ensuring that input and output interfaces are -immutable. +conditions. Specifically, it <em class="rfc2119">SHOULD</em> not be possible for +a site to mutate a codec input or output while the underlying codec <em +class="rfc2119">MAY</em> still be operating on that data. This concern is +mitigated by ensuring that input and output interfaces are immutable. Privacy Considerations{#privacy-considerations} =============================================== @@ -5043,23 +5058,25 @@ The primary privacy impact is an increased ability to fingerprint users by querying for different codec capabilities to establish a codec feature profile. Much of this profile is already exposed by existing APIs. Such profiles are very -unlikely to be uniquely identifying, but may be used with other metrics to -create a fingerprint. - -An attacker may accumulate a codec feature profile by calling -`IsConfigSupported()` methods with a number of different configuration -dictionaries. Similarly, an attacker may attempt to `configure()` a codec with -different configuration dictionaries and observe which configurations are -accepted. - -Attackers may also use existing APIs to establish much of the codec feature -profile. For example, the [[media-capabilities]] {{decodingInfo()}} API -describes what types of decoders are supported and its {{powerEfficient}} -attribute may signal when a decoder uses hardware acceleration. Similarly, the -[[WebRTC]] {{RTCRtpSender/getCapabilities()}} API may be used to determine what -types of encoders are supported and the {{RTCPeerConnection/getStats()}} API may -be used to determine when an encoder uses hardware acceleration. WebCodecs will -expose some additional information in the form of low level codec features. +unlikely to be uniquely identifying, but <em class="rfc2119">MAY</em> be used +with other metrics to create a fingerprint. + +An attacker <em class="rfc2119">MAY</em> accumulate a codec feature profile by +calling `IsConfigSupported()` methods with a number of different configuration +dictionaries. Similarly, an attacker <em class="rfc2119">MAY</em> attempt to +`configure()` a codec with different configuration dictionaries and observe +which configurations are accepted. + +Attackers <em class="rfc2119">MAY</em> also use existing APIs to establish much +of the codec feature profile. For example, the [[media-capabilities]] +{{decodingInfo()}} API describes what types of decoders are supported and its +{{powerEfficient}} attribute <em class="rfc2119">MAY</em> signal when a decoder +uses hardware acceleration. Similarly, the [[WebRTC]] +{{RTCRtpSender/getCapabilities()}} API <em class="rfc2119">MAY</em> be used to +determine what types of encoders are supported and the +{{RTCPeerConnection/getStats()}} API <em class="rfc2119">MAY</em> be used to +determine when an encoder uses hardware acceleration. WebCodecs will expose some +additional information in the form of low level codec features. A codec feature profile alone is unlikely to be uniquely identifying. Underlying codecs are often implemented entirely in software (be it part of the User Agent @@ -5068,17 +5085,18 @@ are often implemented with hardware acceleration, but such hardware is mass produced and devices of a particular class and manufacture date (e.g. flagship phones manufactured in 2020) will often have common capabilities. There will be -outliers (some users may run outdated versions of software codecs or use a rare -mix of custom assembled hardware), but most of the time a given codec feature -profile is shared by a large group of users. +outliers (some users <em class="rfc2119">MAY</em> run outdated versions of +software codecs or use a rare mix of custom assembled hardware), but most of the +time a given codec feature profile is shared by a large group of users. Segmenting groups of users by codec feature profile still amounts to a bit of entropy that can be combined with other metrics to uniquely identify a user. -User Agents may partially mitigate this by returning an error whenever a site -attempts to exhaustively probe for codec capabilities. Additionally, User Agents -may implement a "privacy budget", which depletes as authors use WebCodecs and -other identifying APIs. Upon exhaustion of the privacy budget, codec -capabilities could be reduced to a common baseline or prompt for user approval. +User Agents <em class="rfc2119">MAY</em> partially mitigate this by returning an +error whenever a site attempts to exhaustively probe for codec capabilities. +Additionally, User Agents <em class="rfc2119">MAY</em> implement a "privacy +budget", which depletes as authors use WebCodecs and other identifying APIs. +Upon exhaustion of the privacy budget, codec capabilities could be reduced to a +common baseline or prompt for user approval. Best Practices for Authors Using WebCodecs{#best-practices-developers} ====================================================================== From cde0f2a2ac90c7ae402e8f9231d18a3f06fa697f Mon Sep 17 00:00:00 2001 From: Paul Adenot <paul@paul.cx> Date: Fri, 20 Aug 2021 15:26:59 +0200 Subject: [PATCH 6/7] Add a bit of CSS to highlight RFC2119 words --- index.src.html | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/index.src.html b/index.src.html index 22b91dbe..f65376e5 100644 --- a/index.src.html +++ b/index.src.html @@ -131,6 +131,11 @@ background-color: lightgrey; } +.rfc2119 { + text-transform: lowercase; + font-variant: small-caps; + font-style: normal; +} </style> From 3d41cca72b3b9e2ab8356a18c561c13f8a5479b3 Mon Sep 17 00:00:00 2001 From: Paul Adenot <paul@paul.cx> Date: Fri, 20 Aug 2021 15:33:52 +0200 Subject: [PATCH 7/7] Replace remaining instances of rfc2119 words with english equivalent after rebase --- index.src.html | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/index.src.html b/index.src.html index f65376e5..bbb3f746 100644 --- a/index.src.html +++ b/index.src.html @@ -2003,7 +2003,7 @@ fingerprinting, they SHOULD ignore the {{HardwareAcceleration}} preference. <div class='note'> - NOTE: Good examples of when a User Agent may ignore + NOTE: Good examples of when a User Agent can ignore {{HardwareAcceleration/prefer-hardware}} or {{HardwareAcceleration/prefer-software}} are for reasons of user privacy or circumstances where the User Agent determines an alternative setting would @@ -2020,10 +2020,10 @@ device-specific, but authors can generally expect the following: * Setting a value of {{HardwareAcceleration/prefer-hardware}} or - {{HardwareAcceleration/prefer-software}} may significantly restrict what - configurations are supported. It may occur that the user's device does not + {{HardwareAcceleration/prefer-software}} can significantly restrict what + configurations are supported. It can occur that the user's device does not offer acceleration for any codec, or only for the most common profiles of - older codecs. It may also occur that a given User Agent lacks a software + older codecs. It can also occur that a given User Agent lacks a software based codec implementation. * Hardware acceleration does not simply imply faster encoding / decoding. Hardware acceleration often has higher startup latency but more consistent @@ -2058,7 +2058,7 @@ software codec implementation. User Agents may ignore this value for any reason. - NOTE: This may cause the configuration to be unsupported on platforms where + NOTE: This can cause the configuration to be unsupported on platforms where an unaccelerated codec is unavailable or is incompatible with other aspects of the codec configuration. </dd> @@ -2067,7 +2067,7 @@ Indicates that the User Agent <em class="rfc2119">SHOULD</em> prefer hardware acceleration. User Agents may ignore this value for any reason. - NOTE: This may cause the configuration to be unsupported on platforms where + NOTE: This can cause the configuration to be unsupported on platforms where an accelerated codec is unavailable or is incompatible with other aspects of the codec configuration. </dd>