[e] (0) Reword the muted/volume logic. This shouldn't have a normativ…

…e effect, but should be easier to read, and should make potential future changes easier to make. Fixing https://www.w3.org/Bugs/Public/show_bug.cgi?id=25019 Affected topics: DOM APIs, Video Text Tracks, Video and Audio git-svn-id: http://svn.whatwg.org/webapps@8596 340c8d12-0b0e-0410-8428-c7bf67bfef74
whatwg · May 1, 2014 · 1bb2b8c · 1bb2b8c
1 parent a7f52cc
commit 1bb2b8c
Show file tree

Hide file tree

Showing 3 changed files with 111 additions and 70 deletions.
diff --git a/complete.html b/complete.html
@@ -7632,6 +7632,7 @@ <h5 id=htmlallcollection-0><span class=secno>2.7.2.1 </span>HTMLAllCollection</h
    <code><a href=#the-textarea-element>textarea</a></code> <!-- in some browsers -->
   </p>
 
+<!--CLEANUP-->
   <p>The <a href=#supported-property-names>supported property names</a> consist of the non-empty values of all the <code title=attr-id><a href=#the-id-attribute>id</a></code> attributes of all the elements <a href=#represented-by-the-collection>represented by the
   collection</a>, and the non-empty values of all the <code title="">name</code> attributes of all the
   <a href=#all-named-elements>"all"-named elements</a> <a href=#represented-by-the-collection>represented by the collection</a>, in <a href=#tree-order>tree
@@ -27576,9 +27577,10 @@ <h5 id=playing-the-media-resource><span class=secno>4.7.10.8 </span>Playing the
   the <a href=#official-playback-position>official playback position</a> must be set to the <a href=#current-playback-position>current playback
   position</a>.</p> <!-- cross-ref is intentionally to the other term, to help find this -->
 
-  <p>When the <a href=#direction-of-playback>direction of playback</a> is backwards, any corresponding audio must be
-  muted. When the <a href=#effective-playback-rate>effective playback rate</a> is so low or so high that the user agent
-  cannot play audio usefully, the corresponding audio must also be muted. If the <a href=#effective-playback-rate>effective
+  <!--CLEANUP-->
+  <p>While the <a href=#direction-of-playback>direction of playback</a> is backwards, any corresponding audio must be
+  <a href=#concept-media-muted title=concept-media-muted>muted</a>. While the <a href=#effective-playback-rate>effective playback rate</a> is so low or so high that the user agent
+  cannot play audio usefully, the corresponding audio must also be <a href=#concept-media-muted title=concept-media-muted>muted</a>. If the <a href=#effective-playback-rate>effective
   playback rate</a> is not 1.0, the user agent may apply pitch adjustments to the audio as
   necessary to render it faithfully.</p>
 
@@ -30847,22 +30849,32 @@ <h5 id=user-interface><span class=secno>4.7.10.13 </span>User interface</h5>
 
   </dl><div class=impl>
 
-  <p>The <dfn id=dom-media-volume title=dom-media-volume><code>volume</code></dfn> attribute must return the playback
-  volume of any audio portions of the <a href=#media-element>media element</a>, in the range 0.0 (silent) to 1.0
-  (loudest). Initially, the volume should be 1.0, but user agents may remember the last set value
-  across sessions, on a per-site basis or otherwise, so the volume may start at other values. On
-  setting, if the new value is in the range 0.0 to 1.0 inclusive, the playback volume of any audio
-  portions of the <a href=#media-element>media element</a> must be set to the new value. If the new value is
+  <p>A <a href=#media-element>media element</a> has a <dfn id=concept-media-volume title=concept-media-volume>playback volume</dfn>, which is a fraction in the range 0.0 (silent) to 1.0 (loudest).
+  Initially, the volume should be 1.0, but user agents may remember the last set value across
+  sessions, on a per-site basis or otherwise, so the volume may start at other values.</p>
+
+  <!--CLEANUP-->
+  <p>The <dfn id=dom-media-volume title=dom-media-volume><code>volume</code></dfn> IDL attribute must return the <a href=#concept-media-volume title=concept-media-volume>playback
+  volume</a> of any audio portions of the <a href=#media-element>media element</a>. On
+  setting, if the new value is in the range 0.0 to 1.0 inclusive, the <a href=#media-element>media element</a>'s <a href=#concept-media-volume title=concept-media-volume>playback
+  volume</a> must be set to the new value. If the new value is
   outside the range 0.0 to 1.0 inclusive, then, on setting, an <code><a href=#indexsizeerror>IndexSizeError</a></code> exception
   must be thrown instead.</p>
 
-  <p>The <dfn id=dom-media-muted title=dom-media-muted><code>muted</code></dfn> attribute must return true if the
-  audio output is muted and false otherwise. Initially, the audio output should not be muted
-  (false), but user agents may remember the last set value across sessions, on a per-site basis or
-  otherwise, so the muted state may start as muted (true). On setting, if the new value is true then
-  the audio output should be muted and if the new value is false it should be unmuted.</p>
+  <p>A <a href=#media-element>media element</a> can also be <dfn id=concept-media-muted title=concept-media-muted>muted</dfn>. If
+  anything is muting the element, then it is muted. (For example, when the <a href=#direction-of-playback>direction of
+  playback</a> is backwards, the element is muted.)</p>
+
+  <!--CLEANUP-->
 
-  <p>Whenever either of the values that would be returned by the <code title=dom-media-volume><a href=#dom-media-volume>volume</a></code> and <code title=dom-media-muted><a href=#dom-media-muted>muted</a></code> attributes
+  <p>The <dfn id=dom-media-muted title=dom-media-muted><code>muted</code></dfn> IDL attribute must return the value
+  to which it was last set. When a <a href=#media-element>media element</a> is created, if the element has a <code title=attr-media-muted><a href=#attr-media-muted>muted</a></code> content attribute specified, then the <code title=dom-media-muted><a href=#dom-media-muted>muted</a></code> IDL attribute should be set to true; otherwise, the user
+  agents may set the value to the user's preferred value (e.g. remembering the last set value across
+  sessions, on a per-site basis or otherwise). While the <code title=dom-media-muted><a href=#dom-media-muted>muted</a></code>
+  IDL attribute is set to true, the <a href=#media-element>media element</a> must be <a href=#concept-media-muted title=concept-media-muted>muted</a>.</p>
+
+  <!--CLEANUP-->
+  <p>Whenever either of the values that would be returned by the <code title=dom-media-volume><a href=#dom-media-volume>volume</a></code> and <code title=dom-media-muted><a href=#dom-media-muted>muted</a></code> IDL attributes
   change, the user agent must <a href=#queue-a-task>queue a task</a> to <a href=#fire-a-simple-event>fire a simple event</a> named
   <code title=event-media-volumechange><a href=#event-media-volumechange>volumechange</a></code> at the <a href=#media-element>media element</a>.</p>
 
@@ -30872,18 +30884,21 @@ <h5 id=user-interface><span class=secno>4.7.10.13 </span>User interface</h5>
    then the element's <a href=#effective-media-volume>effective media volume</a> is the volume desired by the user. Abort
    these steps.</li>
 
-   <li><p>If the element's audio output is muted, the element's <a href=#effective-media-volume>effective media volume</a>
+   <!--CLEANUP-->
+   <li><p>If the element's audio output is <a href=#concept-media-muted title=concept-media-muted>muted</a>, the element's <a href=#effective-media-volume>effective media volume</a>
    is zero. Abort these steps.</li>
 
    <li><p>If the element has a <a href=#current-media-controller>current media controller</a> and that
    <code><a href=#mediacontroller>MediaController</a></code> object's <a href=#media-controller-mute-override>media controller mute override</a> is true, the
    element's <a href=#effective-media-volume>effective media volume</a> is zero. Abort these steps.</li>
 
-   <li><p>Let <var title="">volume</var> be the playback volume of the audio portions of the
+   <!--CLEANUP-->
+   <li><p>Let <var title="">volume</var> be the <a href=#concept-media-volume title=concept-media-volume>playback volume</a> of the audio portions of the
    <a href=#media-element>media element</a>, in range 0.0 (silent) to 1.0 (loudest).</li>
 
-   <li><p>If the element has a <a href=#current-media-controller>current media controller</a>, multiply <var title="">volume</var> by that <code><a href=#mediacontroller>MediaController</a></code> object's <a href=#media-controller-volume-multiplier>media controller volume
-   multiplier</a>.</li>
+   <li><p>If the element has a <a href=#current-media-controller>current media controller</a>, multiply <var title="">volume</var> by that <code><a href=#mediacontroller>MediaController</a></code> object's <a href=#media-controller-volume-multiplier>media controller
+   volume multiplier</a>. (The <a href=#media-controller-volume-multiplier>media controller volume multiplier</a> is in the range
+   0.0 to 1.0, so this can only reduce the value.)</li>
 
    <li><p>The element's <a href=#effective-media-volume>effective media volume</a> is <var title="">volume</var>,
    interpreted relative to the range 0.0 to 1.0, with 0.0 being silent, and 1.0 being the loudest
@@ -30893,16 +30908,14 @@ <h5 id=user-interface><span class=secno>4.7.10.13 </span>User interface</h5>
 
   </ol></div>
 
-  <p>The <dfn id=attr-media-muted title=attr-media-muted><code>muted</code></dfn> attribute on <a href=#media-element title="media
+  <!--CLEANUP-->
+  <p>The <dfn id=attr-media-muted title=attr-media-muted><code>muted</code></dfn> content attribute on <a href=#media-element title="media
   element">media elements</a> is a <a href=#boolean-attribute>boolean attribute</a> that controls the default state
   of the audio output of the <a href=#media-resource>media resource</a>, potentially overriding user
   preferences.</p>
 
   <div class=impl>
 
-  <p>When a <a href=#media-element>media element</a> is created, if it has a <code title=attr-media-muted><a href=#attr-media-muted>muted</a></code> attribute specified, the user agent must mute the
-  <a href=#media-element>media element</a>'s audio output, overriding any user preference.</p>
-
   <p>The <dfn id=dom-media-defaultmuted title=dom-media-defaultMuted><code>defaultMuted</code></dfn> IDL attribute must
   <a href=#reflect>reflect</a> the <code title=attr-media-muted><a href=#attr-media-muted>muted</a></code> content attribute.</p>
 

diff --git a/index b/index
@@ -7632,6 +7632,7 @@ a.setAttribute('href', 'http://example.com/'); // change the content attribute d
    <code><a href=#the-textarea-element>textarea</a></code> <!-- in some browsers -->
   </p>
 
+<!--CLEANUP-->
   <p>The <a href=#supported-property-names>supported property names</a> consist of the non-empty values of all the <code title=attr-id><a href=#the-id-attribute>id</a></code> attributes of all the elements <a href=#represented-by-the-collection>represented by the
   collection</a>, and the non-empty values of all the <code title="">name</code> attributes of all the
   <a href=#all-named-elements>"all"-named elements</a> <a href=#represented-by-the-collection>represented by the collection</a>, in <a href=#tree-order>tree
@@ -27576,9 +27577,10 @@ interface <dfn id=htmlmediaelement>HTMLMediaElement</dfn> : <a href=#htmlelement
   the <a href=#official-playback-position>official playback position</a> must be set to the <a href=#current-playback-position>current playback
   position</a>.</p> <!-- cross-ref is intentionally to the other term, to help find this -->
 
-  <p>When the <a href=#direction-of-playback>direction of playback</a> is backwards, any corresponding audio must be
-  muted. When the <a href=#effective-playback-rate>effective playback rate</a> is so low or so high that the user agent
-  cannot play audio usefully, the corresponding audio must also be muted. If the <a href=#effective-playback-rate>effective
+  <!--CLEANUP-->
+  <p>While the <a href=#direction-of-playback>direction of playback</a> is backwards, any corresponding audio must be
+  <a href=#concept-media-muted title=concept-media-muted>muted</a>. While the <a href=#effective-playback-rate>effective playback rate</a> is so low or so high that the user agent
+  cannot play audio usefully, the corresponding audio must also be <a href=#concept-media-muted title=concept-media-muted>muted</a>. If the <a href=#effective-playback-rate>effective
   playback rate</a> is not 1.0, the user agent may apply pitch adjustments to the audio as
   necessary to render it faithfully.</p>
 
@@ -30847,22 +30849,32 @@ red:89
 
   </dl><div class=impl>
 
-  <p>The <dfn id=dom-media-volume title=dom-media-volume><code>volume</code></dfn> attribute must return the playback
-  volume of any audio portions of the <a href=#media-element>media element</a>, in the range 0.0 (silent) to 1.0
-  (loudest). Initially, the volume should be 1.0, but user agents may remember the last set value
-  across sessions, on a per-site basis or otherwise, so the volume may start at other values. On
-  setting, if the new value is in the range 0.0 to 1.0 inclusive, the playback volume of any audio
-  portions of the <a href=#media-element>media element</a> must be set to the new value. If the new value is
+  <p>A <a href=#media-element>media element</a> has a <dfn id=concept-media-volume title=concept-media-volume>playback volume</dfn>, which is a fraction in the range 0.0 (silent) to 1.0 (loudest).
+  Initially, the volume should be 1.0, but user agents may remember the last set value across
+  sessions, on a per-site basis or otherwise, so the volume may start at other values.</p>
+
+  <!--CLEANUP-->
+  <p>The <dfn id=dom-media-volume title=dom-media-volume><code>volume</code></dfn> IDL attribute must return the <a href=#concept-media-volume title=concept-media-volume>playback
+  volume</a> of any audio portions of the <a href=#media-element>media element</a>. On
+  setting, if the new value is in the range 0.0 to 1.0 inclusive, the <a href=#media-element>media element</a>'s <a href=#concept-media-volume title=concept-media-volume>playback
+  volume</a> must be set to the new value. If the new value is
   outside the range 0.0 to 1.0 inclusive, then, on setting, an <code><a href=#indexsizeerror>IndexSizeError</a></code> exception
   must be thrown instead.</p>
 
-  <p>The <dfn id=dom-media-muted title=dom-media-muted><code>muted</code></dfn> attribute must return true if the
-  audio output is muted and false otherwise. Initially, the audio output should not be muted
-  (false), but user agents may remember the last set value across sessions, on a per-site basis or
-  otherwise, so the muted state may start as muted (true). On setting, if the new value is true then
-  the audio output should be muted and if the new value is false it should be unmuted.</p>
+  <p>A <a href=#media-element>media element</a> can also be <dfn id=concept-media-muted title=concept-media-muted>muted</dfn>. If
+  anything is muting the element, then it is muted. (For example, when the <a href=#direction-of-playback>direction of
+  playback</a> is backwards, the element is muted.)</p>
+
+  <!--CLEANUP-->
 
-  <p>Whenever either of the values that would be returned by the <code title=dom-media-volume><a href=#dom-media-volume>volume</a></code> and <code title=dom-media-muted><a href=#dom-media-muted>muted</a></code> attributes
+  <p>The <dfn id=dom-media-muted title=dom-media-muted><code>muted</code></dfn> IDL attribute must return the value
+  to which it was last set. When a <a href=#media-element>media element</a> is created, if the element has a <code title=attr-media-muted><a href=#attr-media-muted>muted</a></code> content attribute specified, then the <code title=dom-media-muted><a href=#dom-media-muted>muted</a></code> IDL attribute should be set to true; otherwise, the user
+  agents may set the value to the user's preferred value (e.g. remembering the last set value across
+  sessions, on a per-site basis or otherwise). While the <code title=dom-media-muted><a href=#dom-media-muted>muted</a></code>
+  IDL attribute is set to true, the <a href=#media-element>media element</a> must be <a href=#concept-media-muted title=concept-media-muted>muted</a>.</p>
+
+  <!--CLEANUP-->
+  <p>Whenever either of the values that would be returned by the <code title=dom-media-volume><a href=#dom-media-volume>volume</a></code> and <code title=dom-media-muted><a href=#dom-media-muted>muted</a></code> IDL attributes
   change, the user agent must <a href=#queue-a-task>queue a task</a> to <a href=#fire-a-simple-event>fire a simple event</a> named
   <code title=event-media-volumechange><a href=#event-media-volumechange>volumechange</a></code> at the <a href=#media-element>media element</a>.</p>
 
@@ -30872,18 +30884,21 @@ red:89
    then the element's <a href=#effective-media-volume>effective media volume</a> is the volume desired by the user. Abort
    these steps.</li>
 
-   <li><p>If the element's audio output is muted, the element's <a href=#effective-media-volume>effective media volume</a>
+   <!--CLEANUP-->
+   <li><p>If the element's audio output is <a href=#concept-media-muted title=concept-media-muted>muted</a>, the element's <a href=#effective-media-volume>effective media volume</a>
    is zero. Abort these steps.</li>
 
    <li><p>If the element has a <a href=#current-media-controller>current media controller</a> and that
    <code><a href=#mediacontroller>MediaController</a></code> object's <a href=#media-controller-mute-override>media controller mute override</a> is true, the
    element's <a href=#effective-media-volume>effective media volume</a> is zero. Abort these steps.</li>
 
-   <li><p>Let <var title="">volume</var> be the playback volume of the audio portions of the
+   <!--CLEANUP-->
+   <li><p>Let <var title="">volume</var> be the <a href=#concept-media-volume title=concept-media-volume>playback volume</a> of the audio portions of the
    <a href=#media-element>media element</a>, in range 0.0 (silent) to 1.0 (loudest).</li>
 
-   <li><p>If the element has a <a href=#current-media-controller>current media controller</a>, multiply <var title="">volume</var> by that <code><a href=#mediacontroller>MediaController</a></code> object's <a href=#media-controller-volume-multiplier>media controller volume
-   multiplier</a>.</li>
+   <li><p>If the element has a <a href=#current-media-controller>current media controller</a>, multiply <var title="">volume</var> by that <code><a href=#mediacontroller>MediaController</a></code> object's <a href=#media-controller-volume-multiplier>media controller
+   volume multiplier</a>. (The <a href=#media-controller-volume-multiplier>media controller volume multiplier</a> is in the range
+   0.0 to 1.0, so this can only reduce the value.)</li>
 
    <li><p>The element's <a href=#effective-media-volume>effective media volume</a> is <var title="">volume</var>,
    interpreted relative to the range 0.0 to 1.0, with 0.0 being silent, and 1.0 being the loudest
@@ -30893,16 +30908,14 @@ red:89
 
   </ol></div>
 
-  <p>The <dfn id=attr-media-muted title=attr-media-muted><code>muted</code></dfn> attribute on <a href=#media-element title="media
+  <!--CLEANUP-->
+  <p>The <dfn id=attr-media-muted title=attr-media-muted><code>muted</code></dfn> content attribute on <a href=#media-element title="media
   element">media elements</a> is a <a href=#boolean-attribute>boolean attribute</a> that controls the default state
   of the audio output of the <a href=#media-resource>media resource</a>, potentially overriding user
   preferences.</p>
 
   <div class=impl>
 
-  <p>When a <a href=#media-element>media element</a> is created, if it has a <code title=attr-media-muted><a href=#attr-media-muted>muted</a></code> attribute specified, the user agent must mute the
-  <a href=#media-element>media element</a>'s audio output, overriding any user preference.</p>
-
   <p>The <dfn id=dom-media-defaultmuted title=dom-media-defaultMuted><code>defaultMuted</code></dfn> IDL attribute must
   <a href=#reflect>reflect</a> the <code title=attr-media-muted><a href=#attr-media-muted>muted</a></code> content attribute.</p>