Added: maxNBest, serviceURI, setCustomParameter and SpeechParameterList
authorGlen Shires <gshires@google.com>
Wed, 09 May 2012 22:48:01 -0700
changeset 2067f706eef96
parent 1 a26b7e79f58b
child 3 8617a5da02b5
Added: maxNBest, serviceURI, setCustomParameter and SpeechParameterList
speechapi.html
     1.1 --- a/speechapi.html	Thu Apr 12 15:44:59 2012 +0100
     1.2 +++ b/speechapi.html	Wed May 09 22:48:01 2012 -0700
     1.3 @@ -389,7 +389,12 @@
     1.4        <li><a href="#speechreco-event"><span class=secno>5.1.8 </span>Speech Recognition Event</a></li>
     1.5        <li><a href="#speechreco-speechgrammar"><span class=secno>5.1.9 </span>Speech Grammar</a></li>
     1.6        <li><a href="#speechreco-speechgrammarlist"><span class=secno>5.1.10 </span>Speech Grammar List</a></li>
     1.7 +      <li><a href="#speechreco-speechparameter"><span class=secno>5.1.11 </span>Speech Parameter</a></li>
     1.8 +      <li><a href="#speechreco-speechparameterlist"><span class=secno>5.1.12 </span>Speech Parameter List</a></li>
     1.9        <li><a href="#tts-section"><span class=secno>5.2 </span>The TTS Interface</a></li>
    1.10 +      <li><a href="#tts-attributes"><span class=secno>5.1.1 </span>TTS Attributes</a></li>
    1.11 +      <li><a href="#tts-methods"><span class=secno>5.1.2 </span>TTS Methods</a></li>
    1.12 +      <li><a href="#tts-events"><span class=secno>5.1.3 </span>TTS Events</a></li>
    1.13        <li><a href="#examples"><span class=secno>6 </span>Examples</a></li>
    1.14        <li class=no-num><a href="#acknowledgments">Acknowledgments</a></li>
    1.15        <li class=no-num><a href="#references">References</a></li>
    1.16 @@ -526,6 +531,8 @@
    1.17          attribute <a href="#dfn-speechgrammarlist">SpeechGrammarList</a> <a href="#dfn-grammars">grammars</a>;
    1.18          attribute DOMString <a href="#dfn-lang">lang</a>;
    1.19          attribute boolean <a href="#dfn-continuous">continuous</a>;
    1.20 +        attribute integer <a href="#dfn-maxnbest">maxNBest</a>;
    1.21 +        attribute DOMString <a href="#dfn-serviceuri">serviceURI</a>;
    1.22  
    1.23          <span class="comment">// methods to drive the speech interaction</span>
    1.24          void <a href="#dfn-start">start</a>();
    1.25 @@ -545,6 +552,10 @@
    1.26          attribute Function <a href="#dfn-onerror">onerror</a>;
    1.27          attribute Function <a href="#dfn-onstart">onstart</a>;
    1.28          attribute Function <a href="#dfn-onend">onend</a>;
    1.29 +
    1.30 +        <span class="comment">// the generic set of parameters</span>
    1.31 +        void <a href="#dfn-setcustomparameter">setCustomParameter</a>(in DOMString <a href="#dfn-name">name</a>, in DOMString <a href="#dfn-value">value</a>);
    1.32 +        attribute <a href="#dfn-speechparameterlist">SpeechParameterList</a> <a href="#dfn-parameters">parameters</a>;
    1.33      };
    1.34  
    1.35      interface <dfn id="speechrecognitionerror">SpeechRecognitionError</dfn> {
    1.36 @@ -607,6 +618,20 @@
    1.37          void <a href="#dfn-addGrammarstring">addFromString</a>(in DOMString <a href="#dfn-grammarString">string</a>,
    1.38                          optional float <a href="#dfn-grammarWeight">weight</a>);
    1.39      };
    1.40 +
    1.41 +    <span class="comment">// The object representing a speech parameter</span>
    1.42 +    [Constructor]
    1.43 +    interface <dfn id="dfn-speechparameter">SpeechParameter</dfn> {
    1.44 +        attribute DOMString <a href="#dfn-name">name</a>;
    1.45 +        attribute DOMString <a href="#dfn-value">value</a>;
    1.46 +    };
    1.47 +
    1.48 +    <span class="comment">// The object representing a speech parameter collection</span>
    1.49 +    [Constructor]
    1.50 +    interface <dfn id="dfn-speechparameterlist">SpeechParameterList</dfn> {
    1.51 +        readonly attribute unsigned long <a href="#dfn-speechparameterlistlength">length</a>;
    1.52 +        getter <a href="#dfn-speechparameter">SpeechParameter</a> <a href="#dfn-speechparameterlistitem">item</a>(in unsigned long index);
    1.53 +    };
    1.54            </code>
    1.55          </pre>
    1.56        </div>
    1.57 @@ -628,6 +653,19 @@
    1.58        This represents a request/response single turn pattern of interaction.
    1.59        When the continuous attribute is set to true the service <em class="rfc2119" title="must">must</em> return a set of recognitions representing more a dictation of multiple recognitions in response to a single starting of recognition.
    1.60        The user agent default value <em class="rfc2119" title="should">should</em> be false.</dd>
    1.61 +
    1.62 +      <dt><dfn id="dfn-maxnbest">maxNBest</dfn> attribute</dt>
    1.63 +      <dd>This attribute will set the maximum number of recognition results that should be returned. The default value is 1.</dd>
    1.64 +
    1.65 +      <dt><dfn id="dfn-serviceuri">serviceURI</dfn> attribute</dt>
    1.66 +      <dd>The serviceURI attribute specifies the location of the speech recognition service that the web application wishes to use.
    1.67 +      If this attribute is unset at the time of the start method call, then the user agent <em class="rfc2119" title="should">must</em> use the user agent default speech service.
    1.68 +      Note that the serviceURI is a generic URI and can thus point to local services either through use of a URN with meaning to the User Agent or by specifying a URL that the User Agent recognizes as a local service.
    1.69 +      Additionally, the User Agent default can be local or remote and can incorporate end user choices via interfaces provided by the User Agent such as browser configuration parameters.</dd>
    1.70 +
    1.71 +      <dt><dfn id="dfn-parameters">parameters</dfn> attribute</dt>
    1.72 +      <dd>This attribute holds an array of arbitrary extension parameters.
    1.73 +      These parameters could set user specific information (such as profile, gender, or age information) or could be used to set recognition parameters specific to the recognition service in use.</dd>
    1.74      </dl>
    1.75  
    1.76      <h4 id="speechreco-methods"><span class=secno>5.1.2 </span>Speech Recognition Methods</h4>
    1.77 @@ -650,6 +688,11 @@
    1.78        <dd>The abort method is a request to immediately stop listening and stop recognizing and do not return any information but that the system is done.
    1.79        When the stop method is called the speech service <em class="rfc2119" title="must">must</em> stop recognizing.
    1.80        The user agent <em class="rfc2119" title="must">must</em> raise a end event once the speech service is no longer connected.</dd>
    1.81 +
    1.82 +      <dt>The <dfn id="dfn-setcustomparameter">setCustomParameter</dfn> method</dt>
    1.83 +      <dd>This method appends an arbitrary recognition service parameter to the parameters array.
    1.84 +      The name of the parameter is given by the <a href="#dfn-name">name</a> parameter and the value by the <a href="#dfn-value">value</a> parameter.
    1.85 +      This arbitrary parameter mechanism allows services that want to have extensions or to set user specific information (such as profile, gender, or age information) to accomplish the task.</dd>
    1.86      </dl>
    1.87  
    1.88      <h4 id="speechreco-events"><span class=secno>5.1.3 </span>Speech Recognition Events</h4>
    1.89 @@ -873,6 +916,34 @@
    1.90        If the weight parameter is not present, the default value of 1.0 is used.</dd>
    1.91      </dl>
    1.92  
    1.93 +    <h4 id="speechreco-speechparameter"><span class=secno>5.1.11 </span>Speech Parameter</h4>
    1.94 +
    1.95 +    <p>The SpeechParameter object represents the container for arbitrary name/value parameters.
    1.96 +    This extensible mechanism allows developers to take advantage of extensions that recognition services may allow.
    1.97 +    This structure has the following attributes:</p>
    1.98 +
    1.99 +    <dl>
   1.100 +      <dt><dfn id="dfn-name">name</dfn> attribute</dt>
   1.101 +      <dd>The required name attribute is the name of the custom parameter.</dd>
   1.102 +
   1.103 +      <dt><dfn id="dfn-value">value</dfn> attribute</dt>
   1.104 +      <dd>The required value attribute is the value of the custom parameter.</dd>
   1.105 +    </dl>
   1.106 +
   1.107 +    <h4 id="speechreco-speechparameterlist"><span class=secno>5.1.12 </span>Speech Parameter List</h4>
   1.108 +
   1.109 +    <p>The SpeechParameterList object represents a collection of SpeechParameter objects.
   1.110 +    This structure has the following attributes:</p>
   1.111 +
   1.112 +    <dl>
   1.113 +      <dt><dfn id="dfn-speechparameterlistlength">length</dfn></dt>
   1.114 +      <dd>The length attribute represents how many parameters are currently in the array.</dd>
   1.115 +
   1.116 +      <dt><dfn id="dfn-speechparameterlistitem">item</dfn></dt>
   1.117 +      <dd>The item getter returns a SpeechParameter from the index into an array of parameters.
   1.118 +      The user agent <em class="rfc2119" title="must">must</em> ensure that the length attribute is set to the number of elements in the array.</dd>
   1.119 +    </dl>
   1.120 +
   1.121      <h3 id="tts-section"><span class=secno>5.2 </span>The TTS Interface</h3>
   1.122  
   1.123      <p>The TTS interface is the scripted web <acronym title="Application Programming Interface">API</acronym> for controlling a text-to-speech output.</p>
   1.124 @@ -887,7 +958,8 @@
   1.125      [Constructor]
   1.126        interface TTS {
   1.127            attribute DOMString text;
   1.128 -          attribute DOMString lang;
   1.129 +          attribute DOMString <a href="#dfn-ttslang">lang</a>;
   1.130 +          attribute DOMString <a href="#dfn-ttsserviceuri">serviceURI</a>;
   1.131            readonly attribute boolean paused;
   1.132            readonly attribute boolean ended;
   1.133  
   1.134 @@ -904,6 +976,25 @@
   1.135        </div>
   1.136      </div>
   1.137  
   1.138 +    <h4 id="tts-attributes"><span class=secno>5.2.1 </span>TTS Attributes</h4>
   1.139 +
   1.140 +    <dl>
   1.141 +      <dt><dfn id="dfn-ttslang">lang</dfn> attribute</dt>
   1.142 +      <dd>This attribute will set the language of the speech synthesis for the request, using a valid <a href="http://www.ietf.org/rfc/bcp/bcp47.txt">BCP 47</a> language tag.
   1.143 +      If unset it remains unset for getting in script, but will default to use the <a href="http://www.w3.org/TR/html5/elements.html#the-lang-and-xml:lang-attributes">lang</a> of the html document root element and associated hierachy.
   1.144 +      This default value is computed and used when the input request opens a connection to the recognition service.</dd>
   1.145 +
   1.146 +      <dt><dfn id="dfn-ttsserviceuri">serviceURI</dfn> attribute</dt>
   1.147 +      <dd>The serviceURI attribute specifies the location of the speech synthesis service that the web application wishes to use.
   1.148 +      If this attribute is unset at the time of the play method call, then the user agent <em class="rfc2119" title="should">must</em> use the user agent default speech service.
   1.149 +      Note that the serviceURI is a generic URI and can thus point to local services either through use of a URN with meaning to the User Agent or by specifying a URL that the User Agent recognizes as a local service.
   1.150 +      Additionally, the User Agent default can be local or remote and can incorporate end user choices via interfaces provided by the User Agent such as browser configuration parameters.</dd>
   1.151 +    </dl>
   1.152 +
   1.153 +    <h4 id="tts-methods"><span class=secno>5.2.2 </span>TTS Methods</h4>
   1.154 +
   1.155 +    <h4 id="tts-events"><span class=secno>5.2.3 </span>TTS Events</h4>
   1.156 +
   1.157      <h2 id="examples"><span class=secno>6 </span>Examples</h2>
   1.158  
   1.159      <p><em>This section is non-normative.</em></p>
   1.160 @@ -970,14 +1061,14 @@
   1.161      Specifically, the following are supported from <a href="http://www.w3.org/2005/Incubator/htmlspeech/XGR-htmlspeech-20111206/#api_examples">Section 7.1.7</a>.</p>
   1.162  
   1.163      <ul>
   1.164 -      <li>Speech Web Search JS API Only (except for non-essential aspects: serviceURI and speedVsAccuracy)</li>
   1.165 +      <li>Speech Web Search JS API Only (except for the non-essential aspect speedVsAccuracy)</li>
   1.166        <li>Web search by voice, with auto-submit</li>
   1.167        <li>Web search by voice, with "Did you say..."</li>
   1.168        <li>Speech translator</li>
   1.169        <li>Speech shell</li>
   1.170        <li>Turn-by-turn navigation</li>
   1.171        <li>Domain Specific Grammars Contingent on Earlier Inputs</li>
   1.172 -      <li>Speech Enabled Email Client (except for non-essential aspects: serviceURI and speedVsAccuracy)</li>
   1.173 +      <li>Speech Enabled Email Client (except for the non-essential aspect speedVsAccuracy)</li>
   1.174        <li>Simple Multimodal Example JS API Only</li>
   1.175        <li>Speech XG Translating Example</li>
   1.176      </ul>