Add contentHint section to codec-registries

codec_registry.src.html

@@ -63,8 +63,11 @@
     4. Expectations for {{EncodedAudioChunk}} or {{EncodedVideoChunk}}
         {{EncodedVideoChunk/[[type]]}}
 4. Where applicable, a registration specification may include a section
-    describing extensions to {{VideoEncoderConfig}} or {{AudioEncoderConfig}}
-    dictionaries.
+    describing:
+    1. Extensions to {{VideoEncoderConfig}} or {{AudioEncoderConfig}}
+        dictionaries
+    2. Guidelines for mapping {{VideoEncoderConfig/contentHint}} or
+        {{AudioEncoderConfig/contentHint}} values to codec-specific concepts.
 5. Candidate entries must be announced by filing an issue in the
     [WebCodecs GitHub issue tracker](https://github.com/w3c/webcodecs/issues/)
     so they can be discussed and evaluated for compliance before being added to

index.src.html

@@ -52,6 +52,7 @@
 
 spec: mst-content-hint; urlPrefix: https://www.w3.org/TR/mst-content-hint/
     type: dfn; text: video content hints; url:#video-content-hints
+    type: dfn; text: audio content hints; url:#audio-content-hints
 
 spec: ECMASCRIPT; urlPrefix: https://tc39.es/ecma262/
     type: dfn; text: the current Realm; url: #current-realm
@@ -2051,6 +2052,7 @@
   [EnforceRange] unsigned long numberOfChannels;
   [EnforceRange] unsigned long long bitrate;
   BitrateMode bitrateMode = "variable";
+  DOMString contentHint;
 };
 </xmp>
 
@@ -2090,6 +2092,22 @@
     encouraged to check by calling {{AudioEncoder/isConfigSupported()}} with
     |config|.
   </dd>
+  <dt><dfn dict-member for=AudioEncoderConfig>contentHint</dfn></dt>
+  <dd>
+    An encoding [=audio content hint=] as defined by [[mst-content-hint]].
+
+    If the [[WEBCODECS-CODEC-REGISTRY]] entry matching
+    {{AudioEncoderConfig/codec}} contains codec-specific guidelines for how to
+    interpret {{AudioEncoderConfig/contentHint}}, the User Agent
+    <em class="rfc2119">MUST</em> follow the guidelines in the codec registry.
+
+    Otherwise, the User Agent <em class="rfc2119">MAY</em> use this hint to set
+    expectations about incoming {{AudioData}} and to improve encoding quality.
+
+    The User Agent <em class="rfc2119">MUST NOT</em> refuse the configuration
+    if it doesn't support this content hint.
+    See {{AudioEncoder/isConfigSupported()}}.
+  </dd>
 </dl>
 
 
@@ -2231,15 +2249,17 @@
   <dd>
     An encoding [=video content hint=] as defined by [[mst-content-hint]].
 
-    The User Agent <em class="rfc2119">MAY</em> use this hint to set
+    If the [[WEBCODECS-CODEC-REGISTRY]] entry matching
+    {{VideoEncoderConfig/codec}} contains codec-specific guidelines for how to
+    interpret {{VideoEncoderConfig/contentHint}}, the User Agent
+    <em class="rfc2119">MUST</em> follow the guidelines in the codec registry.
+
+    Otherwise, the User Agent <em class="rfc2119">MAY</em> use this hint to set
     expectations about incoming {{VideoFrame}}s and to improve encoding quality.
 
     The User Agent <em class="rfc2119">MUST NOT</em> refuse the configuration
     if it doesn't support this content hint.
     See {{VideoEncoder/isConfigSupported()}}.
-
-    NOTE: Any codec-specific encoding options take precedence over
-      {{contentHint}}.
   </dd>
 
 </dl>

opus_codec_registration.src.html

@@ -16,7 +16,8 @@
     codec-specific {{EncodedAudioChunk}} {{EncodedAudioChunk/[[internal data]]}}
     bytes, (3) the {{AudioDecoderConfig/description|AudioDecoderConfig.description}}
     bytes, (4) the values of {{EncodedAudioChunk}} {{EncodedAudioChunk/[[type]]}},
-    and (5) the codec-specific extensions to {{AudioEncoderConfig}}
+    (5) the {{AudioEncoderConfig/contentHint|AudioEncoderConfig.contentHint}}
+    mappings and (6) the codec-specific extensions to {{AudioEncoderConfig}}
 
     The registration is not intended to include any information on whether a
     codec format is encumbered by intellectual property claims. Implementers and
@@ -33,6 +34,12 @@
 </pre>
 
 
+<pre class='anchors'>
+spec: mst-content-hint; urlPrefix: https://www.w3.org/TR/mst-content-hint/
+    type: dfn; text: speech; url:#idl-def-AudioContentHint.speech
+    type: dfn; text: music; url:#idl-def-AudioContentHint.music
+</pre>
+
 <pre class='biblio'>
 {
   "OPUS": {
@@ -46,7 +53,7 @@
     "title": "RFC 7845: Ogg Encapsulation for the Opus Audio Codec",
     "publisher": "IETF",
     "date": "April 2016"
-  }
+  },
 }
 </pre>
 
@@ -89,6 +96,26 @@
 NOTE: Once the initialization has succeeded, any packet can be decoded at any
 time without error, but this might not result in the expected audio output.
 
+AudioEncoderConfig.contentHint guidelines {#contenthint-guidelines}
+================================================
+
+The User Agent <em class="rfc2119">MUST</em> take into consideration the value
+of {{AudioEncoderConfig/contentHint}} when configuring an Opus encoder.
+
+If {{AudioEncoderConfig/contentHint}} is <code>"[=speech=]"</code>, the User Agent
+<em class="rfc2119">MUST</em> use encoder settings that are best for most
+VoIP/videoconference applications where listening quality and intelligibility
+matter most.
+
+If {{AudioEncoderConfig/contentHint}} is <code>"[=music=]"</code>, the User Agent
+<em class="rfc2119">MUST</em> use encoder settings that are best for
+broadcast/high-fidelity applications where the decoded audio should be as close
+as possible to the input.
+
+For all other values of {{AudioEncoderConfig/contentHint}}, the User Agent
+<em class="rfc2119">MAY</em> ignore the flag or choose encoder settings based on
+any additional signals and context.
+
 AudioEncoderConfig extensions {#audioencoderconfig-extensions}
 =============================================================