Add preservesPitch to HTMLMediaElement

Also extends the playbackRate definition.

Co-authored-by: Attila Haraszti <[email protected]>

source

@@ -32601,6 +32601,7 @@ interface <dfn>HTMLMediaElement</dfn> : <span>HTMLElement</span> {
   readonly attribute boolean <span data-x="dom-media-paused">paused</span>;
   attribute double <span data-x="dom-media-defaultPlaybackRate">defaultPlaybackRate</span>;
   attribute double <span data-x="dom-media-playbackRate">playbackRate</span>;
+  attribute boolean <span data-x="dom-media-preservesPitch">preservesPitch</span>;
   readonly attribute <span>TimeRanges</span> <span data-x="dom-media-played">played</span>;
   readonly attribute <span>TimeRanges</span> <span data-x="dom-media-seekable">seekable</span>;
   readonly attribute boolean <span data-x="dom-media-ended">ended</span>;
@@ -32659,10 +32660,6 @@ interface <dfn>HTMLMediaElement</dfn> : <span>HTMLElement</span> {
       so that the author's controls can get away of the UA's
   -->
 
-  <!-- v2 features that already have experimental implementations:
-    * webkitPreservesPitch (for when playbackRate != 1.0)
-  -->
-
   <p><span data-x="media element">Media elements</span> are used to present audio data, or video and
   audio data, to the user. This is referred to as <dfn>media data</dfn> in this section, since this
   section applies equally to <span data-x="media element">media elements</span> for audio or for
@@ -34738,6 +34735,17 @@ interface <dfn>MediaError</dfn> {
     <p>Can be set, to change the rate of playback.</p>
    </dd>
 
+   <dt><var>media</var> . <code subdfn data-x="dom-media-preservesPitch">preservesPitch</code></dt>
+
+   <dd>
+    <p>Returns true if pitch-preserving algorithms are used when the <code
+    data-x="dom-media-playbackRate">playbackRate</code> is not 1.0. The default value is true.</p>
+
+    <p>Can be set to false to have the <span>media resource</span>'s audio pitch change up or down
+    depending on the <code data-x="dom-media-playbackRate">playbackRate</code>. This is useful for
+    aesthetic and performance reasons.</p>
+   </dd>
+
    <dt><var>media</var> . <code subdfn data-x="dom-media-played">played</code></dt>
 
    <dd>
@@ -34977,7 +34985,15 @@ interface <dfn>MediaError</dfn> {
   by script or by being changed directly by the user agent, e.g. in response to user control) the
   user agent must <span>queue a media element task</span> given the <span>media element</span> to
   <span data-x="concept-event-fire">fire an event</span> named <code
-  data-x="event-media-ratechange">ratechange</code> at the <span>media element</span>.</p>
+  data-x="event-media-ratechange">ratechange</code> at the <span>media element</span>. The user
+  agent must process attribute changes smoothly and must not introduce any perceivable gaps or
+  muting of playback in response.</p>
+
+  <p>The <dfn><code data-x="dom-media-preservesPitch">preservesPitch</code></dfn> getter steps are
+  to return true if a pitch-preserving algorithm is in effect during playback. The setter steps are
+  to correspondingly switch the pitch-preserving algorithm on or off, without any perceivable gaps
+  or muting of playback. By default, such a pitch-preserving algorithm must be in effect (i.e., the
+  getter will initially return true).</p>
 
   <hr>
 
@@ -35215,8 +35231,10 @@ interface <dfn>MediaError</dfn> {
   data-x="dom-media-playbackRate">playbackRate</code> is so low or so high that the user agent
   cannot play audio usefully, the corresponding audio must also be <span
   data-x="concept-media-muted">muted</span>. If the element's <code
-  data-x="dom-media-playbackRate">playbackRate</code> is not 1.0, the user agent may apply pitch
-  adjustments to the audio as necessary to render it faithfully.</p>
+  data-x="dom-media-playbackRate">playbackRate</code> is not 1.0 and <code
+  data-x="dom-media-preservesPitch">preservesPitch</code> is true, the user agent must apply pitch
+  adjustment to preserve the original pitch of the audio. Otherwise, the user agent must speed up
+  or slow down the audio without any pitch adjustment.</p>
 
   <p>When a <span>media element</span> is <span>potentially playing</span>, its audio data played
   must be synchronized with the <span>current playback position</span>, at the element's
@@ -122403,6 +122421,7 @@ INSERT INTERFACES HERE
   Ashley Gullen,
   Ashley Sheridan,
   Atsushi Takayama,
+  Attila Haraszti,
   Aurelien Levy,
   Ave Wrigley,
   Avi Drissman,