renamed voice-pitch-range to voice-range

fixed clamping for out-of-range (actual user agent) values

Author: danielweck

css3-speech/Overview.html

@@ -308,8 +308,8 @@ <h2 class="no-num no-toc" id=contents>Table of contents</h2>
       </span>The &lsquo;<code class=property>voice-pitch</code>&rsquo;
       property</a>
 
-     <li><a href="#voice-props-voice-pitch-range"><span class=secno>10.4.
-      </span>The &lsquo;<code class=property>voice-pitch-range</code>&rsquo;
+     <li><a href="#voice-props-voice-range"><span class=secno>10.4.
+      </span>The &lsquo;<code class=property>voice-range</code>&rsquo;
       property</a>
     </ul>
 
@@ -2162,6 +2162,13 @@ <h3 id=voice-props-voice-pitch><span class=secno>10.3. </span>The &lsquo;<a
    pitch of the output). For example, the common pitch for a male voice is
    around 120Hz, whereas it is around 210Hz for a female voice.
 
+  <p> Speech-capable user agents are likely to support a specific range of
+   values rather than the full range of possible computed numerical values
+   for frequencies. The actual values in user agents may therefore be clamped
+   to implementation-dependent minimum and maximum boundaries. For example:
+   although the 0Hz frequency can be legitimately computed, it may be clamped
+   to a more meaningful value in the context of the speech synthesizer.
+
   <p class=note> Note that the functionality provided by this property is
    related to the <a
    href="http://www.w3.org/TR/speech-synthesis11/#edef_prosody"><code>pitch</code>
@@ -2175,43 +2182,47 @@ <h3 id=voice-props-voice-pitch><span class=secno>10.3. </span>The &lsquo;<a
     <p> A value in <a href="#frequency-def">frequency</a> units (Hertz or
      kiloHertz, e.g. "100Hz", "+2kHz"). Values are restricted to positive
      numbers when the &lsquo;<code class=property>absolute</code>&rsquo;
-     keyword is used. Otherwise, a negative value represents an decrement,
-     and a positive value represents an increment (relative to the inherited
-     frequency value). For example, "2kHz" is a positive offset (strictly
-     equivalent to "+2kHz"), unlike "+2kHz absolute" which is an absolute
-     frequency value (strictly equivalent to "2kHz absolute"). Computed
-     frequency values that are negative numbers result in the property being
-     ignored.</p>
+     keyword is used. Otherwise (when the &lsquo;<code
+     class=property>absolute</code>&rsquo; keyword is not used), a negative
+     value represents an decrement, and a positive value represents an
+     increment (relative to the inherited value). For example, "2kHz" is a
+     positive offset (strictly equivalent to "+2kHz"), and "+2kHz absolute"
+     is an absolute frequency (strictly equivalent to "2kHz absolute").
+     Computed absolute frequency values that are negative are clamped to zero
+     Hertz.</p>
 
    <dt> <strong>absolute</strong>
 
    <dd>
-    <p> This keyword specifies that the provided frequency value is expressed
-     as a positive absolute value.</p>
+    <p> This keyword specifies that the provided frequency is expressed as an
+     absolute, positive value. When a negative value is provided, it is
+     clamped to zero.</p>
 
    <dt> <strong>&lt;semitones&gt;</strong>
 
    <dd>
     <p> Specifies a relative change (decrement or increment) to the inherited
-     frequency value. The syntax of allowed values is a &lt;<a
+     value. The syntax of allowed values is a &lt;<a
      href="#number-def">number</a>&gt; followed immediately by "st"
      (semitones). A semitone is half of a tone (a half step) on the standard
      diatonic scale. As such, a semitone doesn't correspond to a fixed
      frequency: the ratio between two consecutive frequencies separated by
      exactly one semitone is the twelfth root of two (approximately 1.05946).
-     </p>
+     Computed absolute frequency values that are negative are clamped to zero
+     Hertz.</p>
 
    <dt> <strong>&lt;percentage&gt;</strong>
 
    <dd>
     <p> Positive and negative <a href="#percentage-def">percentage</a> values
      are allowed, to represent an increment or decrement (respectively)
-     relative to the inherited frequency value. Computed values are
-     calculated by adding (or subtracting) the specified fraction of the
-     inherited frequency value, to (from) the inherited frequency value. For
-     example, 50% (which is equivalent to +50%) with a inherited value of
-     200Hz results in <code>200 + (200*0.5)</code> = 300Hz. Conversely, -50%
-     results in <code>200-(200*0.5)</code> = 100Hz.</p>
+     relative to the inherited value. Computed values are calculated by
+     adding (or subtracting) the specified fraction of the inherited value,
+     to (from) the inherited value. For example, 50% (which is equivalent to
+     +50%) with a inherited value of 200Hz results in <code>200 +
+     (200*0.5)</code> = 300Hz. Conversely, -50% results in
+     <code>200-(200*0.5)</code> = 100Hz. Computed absolute frequency values
+     that are negative are clamped to zero Hertz.</p>
 
    <dt><strong>x-low</strong>, <strong>low</strong>, <strong>medium</strong>,
     <strong>high</strong>, <strong>x-high</strong>
@@ -2237,16 +2248,16 @@ <h3 id=voice-props-voice-pitch><span class=secno>10.3. </span>The &lsquo;<a
       </pre>
   </div>
 
-  <h3 id=voice-props-voice-pitch-range><span class=secno>10.4. </span>The
-   &lsquo;<a href="#voice-pitch-range"><code
-   class=property>voice-pitch-range</code></a>&rsquo; property</h3>
+  <h3 id=voice-props-voice-range><span class=secno>10.4. </span>The &lsquo;<a
+   href="#voice-range"><code class=property>voice-range</code></a>&rsquo;
+   property</h3>
 
   <table class=propdef summary="name: syntax">
    <tbody>
     <tr>
      <td>Name:
 
-     <td> <dfn id=voice-pitch-range>voice-pitch-range</dfn>
+     <td> <dfn id=voice-range>voice-range</dfn>
 
     <tr>
      <td> <em>Value:</em>
@@ -2285,15 +2296,22 @@ <h3 id=voice-props-voice-pitch-range><span class=secno>10.4. </span>The
      <td>specified value
   </table>
 
-  <p> The &lsquo;<a href="#voice-pitch-range"><code
-   class=property>voice-pitch-range</code></a>&rsquo; property specifies the
+  <p> The &lsquo;<a href="#voice-range"><code
+   class=property>voice-range</code></a>&rsquo; property specifies the
    variability in the "baseline" pitch, i.e. how much the fundamental
    frequency may deviate from the average pitch of the speech output. The
    dynamic pitch range of the generated speech generally increases for a
    highly animated voice, for example when variations in inflection are used
    to convey meaning and emphasis in speech. Typically, a low range produces
    a flat, monotonic voice, whereas a high range produces an animated voice.
 
+  <p> Speech-capable user agents are likely to support a specific range of
+   values rather than the full range of possible computed numerical values
+   for frequencies. The actual values in user agents may therefore be clamped
+   to implementation-dependent minimum and maximum boundaries. For example:
+   although the 0Hz frequency can be legitimately computed, it may be clamped
+   to a more meaningful value in the context of the speech synthesizer.
+
   <p class=note> Note that the functionality provided by this property is
    related to the <a
    href="http://www.w3.org/TR/speech-synthesis11/#edef_prosody"><code>range</code>
@@ -2307,42 +2325,47 @@ <h3 id=voice-props-voice-pitch-range><span class=secno>10.4. </span>The
     <p> A value in <a href="#frequency-def">frequency</a> units (Hertz or
      kiloHertz, e.g. "100Hz", "+2kHz"). Values are restricted to positive
      numbers when the &lsquo;<code class=property>absolute</code>&rsquo;
-     keyword is used. Otherwise, a negative value represents an decrement,
-     and a positive value represents an increment (relative to the inherited
-     frequency value). For example, "2kHz" is a positive offset (strictly
-     equivalent to "+2kHz"), unlike "+2kHz absolute" which is an absolute
-     frequency value (strictly equivalent to "2kHz absolute"). Computed
-     frequency values that are negative numbers result in the property being
-     ignored.</p>
+     keyword is used. Otherwise (when the &lsquo;<code
+     class=property>absolute</code>&rsquo; keyword is not used), a negative
+     value represents an decrement, and a positive value represents an
+     increment (relative to the inherited value). For example, "2kHz" is a
+     positive offset (strictly equivalent to "+2kHz"), and "+2kHz absolute"
+     is an absolute frequency (strictly equivalent to "2kHz absolute").
+     Computed absolute frequency values that are negative are clamped to zero
+     Hertz.</p>
 
    <dt> <strong>absolute</strong>
 
    <dd>
-    <p> This keyword specifies that the provided frequency value is expressed
-     as a positive absolute value.</p>
+    <p> This keyword specifies that the provided frequency is expressed as an
+     absolute, positive value. When a negative value is provided, it is
+     clamped to zero.</p>
 
    <dt> <strong>&lt;semitones&gt;</strong>
 
    <dd>
     <p> Specifies a relative change (decrement or increment) to the inherited
-     frequency value. The syntax of allowed values is a &lt;<a
+     value. The syntax of allowed values is a &lt;<a
      href="#number-def">number</a>&gt; followed immediately by "st"
      (semitones). A semitone is half of a tone (a half step) on the standard
      diatonic scale. As such, a semitone doesn't correspond to a fixed
      frequency: the ratio between two consecutive frequencies separated by
-     exactly one semitone is the twelfth root of two (approximately 1.05946).</p>
+     exactly one semitone is the twelfth root of two (approximately 1.05946).
+     Computed absolute frequency values that are negative are clamped to zero
+     Hertz.</p>
 
    <dt> <strong>&lt;percentage&gt;</strong>
 
    <dd>
     <p> Positive and negative <a href="#percentage-def">percentage</a> values
      are allowed, to represent an increment or decrement (respectively)
-     relative to the inherited frequency value. Computed values are
-     calculated by adding (or subtracting) the specified fraction of the
-     inherited frequency value, to (from) the inherited frequency value. For
-     example, 50% (which is equivalent to +50%) with a inherited value of
-     200Hz results in <code>200 + (200*0.5)</code> = 300Hz. Conversely, -50%
-     results in <code>200-(200*0.5)</code> = 100Hz.</p>
+     relative to the inherited value. Computed values are calculated by
+     adding (or subtracting) the specified fraction of the inherited value,
+     to (from) the inherited frequency value. For example, 50% (which is
+     equivalent to +50%) with a inherited value of 200Hz results in <code>200
+     + (200*0.5)</code> = 300Hz. Conversely, -50% results in
+     <code>200-(200*0.5)</code> = 100Hz. Computed absolute frequency values
+     that are negative are clamped to zero Hertz.</p>
 
    <dt><strong>x-low</strong>, <strong>low</strong>, <strong>medium</strong>,
     <strong>high</strong> and <strong>x-high</strong>
@@ -2992,7 +3015,7 @@ <h2 class=no-num id=property-index>Appendix A &mdash; Property index</h2>
      <td>speech
 
     <tr>
-     <td><a class=property href="#voice-pitch-range">voice-pitch-range</a>
+     <td><a class=property href="#voice-range">voice-range</a>
 
      <td>&lt;frequency&gt; &amp;&amp; absolute? | &lt;semitones&gt; |
       &lt;percentage&gt; | x-low | low | medium | high | x-high
@@ -3263,8 +3286,8 @@ <h2 class=no-num id=index>Appendix B &mdash; Index</h2>
    <li>voice-pitch, <a href="#voice-pitch"
     title=voice-pitch><strong>10.3.</strong></a>
 
-   <li>voice-pitch-range, <a href="#voice-pitch-range"
-    title=voice-pitch-range><strong>10.4.</strong></a>
+   <li>voice-range, <a href="#voice-range"
+    title=voice-range><strong>10.4.</strong></a>
 
    <li>voice-rate, <a href="#voice-rate"
     title=voice-rate><strong>10.2.</strong></a>
@@ -3481,6 +3504,13 @@ <h2 class=no-num id=changes>Appendix D &mdash; Changes from previous draft</h2>
    list of changes</a>, which - for succinctness - is not repeated here.
 
   <ul>
+   <li>Renamed &lsquo;<code class=property>voice-pitch-range</code>&rsquo; to
+    &lsquo;<a href="#voice-range"><code
+    class=property>voice-range</code></a>&rsquo;, which is compatible with
+    SSML's notation, and removes the possibility to interpret this property
+    as being a subset of &lsquo;<a href="#voice-pitch"><code
+    class=property>voice-pitch</code></a>&rsquo;.
+
    <li>Removed the "phonemes" property (and its associated "@alphabet"
     at-rule).
 
@@ -3507,9 +3537,8 @@ <h2 class=no-num id=changes>Appendix D &mdash; Changes from previous draft</h2>
     class=property>rest</code></a>&rsquo;, which should be zero (were
     "implementation-dependent").
 
-   <li>Corrected the [initial] values for &lsquo;<a
-    href="#voice-pitch-range"><code
-    class=property>voice-pitch-range</code></a>&rsquo; and &lsquo;<a
+   <li>Corrected the [initial] values for &lsquo;<a href="#voice-range"><code
+    class=property>voice-range</code></a>&rsquo; and &lsquo;<a
     href="#voice-pitch"><code class=property>voice-pitch</code></a>&rsquo; to
     "medium".
 
@@ -3571,8 +3600,8 @@ <h2 class=no-num id=changes>Appendix D &mdash; Changes from previous draft</h2>
 
    <li>Separated the &lsquo;<code class=property>absolute</code>&rsquo;
     keyword for &lsquo;<a href="#voice-pitch"><code
-    class=property>voice-pitch</code></a>&rsquo; and &lsquo;<code
-    class=property>voice-range</code>&rsquo;.
+    class=property>voice-pitch</code></a>&rsquo; and &lsquo;<a
+    href="#voice-range"><code class=property>voice-range</code></a>&rsquo;.
 
    <li>Improved document structure by adding sub-sections.