Adding static documentation to the speech input extension API.

chrome/common/extensions/docs/static/experimental.speechInput.html

+<div id="pageData-name" class="pageData">Speech Input API</div>
+
+<!-- BEGIN AUTHORED CONTENT -->
+<p id="classSummary">
+The <code>chrome.experimental.speechInput</code> module provides
+one-shot speech recognition to Chrome extensions.
+This module is still experimental. For information on how to use experimental
+APIs, see the <a href="experimental.html">chrome.experimental.* APIs</a> page.
+</p>
+
+<h2 id="manifest">Manifest</h2>
+<p>You must declare the "experimental" permission in the <a
+  href="manifest.html">extension manifest</a> to use the speechInput

[kathyw, 2011/11/15 00:04:10]

speechInput -> speech input

(since we're not listing the complete name of the API, just use the English
equivalent to talk about it)

[Leandro Graciá Gil, 2011/11/15 12:10:12]

Done.

+API.
+For example:</p>
+<pre>{
+  "name": "My extension",
+  ...
+  <b>"permissions": [
+    "experimental"
+  ]</b>,
+  ...
+}</pre>
+
+<h2 id="howToStart">How to start speech recognition</h2>
+<p>To start recognizing speech an extension must call the <code>start</code>

[kathyw, 2011/11/15 00:04:10]

Add () after method names:

<code>start()</code>

[Leandro Graciá Gil, 2011/11/15 12:10:12]

Done.

+method. If provided, <code>callback</code> will be called once recording has

[kathyw, 2011/11/15 00:04:10]

<code>callback</code>
->
your callback

(or something similar; callback isn't a required name, so we don't <code> font
it)

[Leandro Graciá Gil, 2011/11/15 12:10:12]

Done.

+successfully started. In case of error <code>chrome.extension.lastError</code>
+will be set.</p>
+
+<p>This API provides exclusive access to the default recording device to the
+first extension requesting it. Consequently, any calls to <code>start</code>
+when the device is being used by another extension or web page will fail and set
+<code>chrome.extension.lastError</code>. The message <code>requestDenied</code>
+will be set if another extension in the same profile is making use of the API,

[kathyw, 2011/11/15 00:04:10]

API, otherwise -> API. Otherwise

[Leandro Graciá Gil, 2011/11/15 12:10:12]

Done.

+otherwise <code>noRecordingDeviceFound</code>, <code>recordingDeviceInUse</code>
+or <code>unableToStart</code> will be set depending on the situation.</p>
+
+<p>To check if recording is currently active call the <code>isRecording</code>

[kathyw, 2011/11/15 00:04:10]

Slight tweaks (if -> whether, add comma, add ()):

To check whether recording is currently active, call the
<code>isRecording()</code> method.

[Leandro Graciá Gil, 2011/11/15 12:10:12]

Done.

+method. Please note that it only checks for audio recording within Chrome.</p>
+
+
+<h2 id="howToGetResults">How to get speech recognition results</h2>
+<p>Listen to the <code>onResult</code> event to receive speech recognition
+results.</p>
+
+<pre>
+var callback = function(result) { ... };
+
+chrome.experimental.speechInput.onResult.addListener(callback);
+</pre>
+
+<p>The <code>result</code> object contains an array of
+<a href="#type-SpeechInputResultHypothesis">SpeechInputResultHypothesis</a>
+sorted by decreasing likelihood.</p>
+
+<p>Recording automatically stops when results are received. It is safe to call
+<code>start</code> again from the results callback.</p>
+
+<p>To handle errors during speech recognition listen for the
+<code>onError</code> event.</p>
+
+<pre>
+var callback = function(error) { ... };
+
+chrome.experimental.speechInput.onError.addListener(callback);
+</pre>
+
+</p>Recording will automatically stop in case on error.

[kathyw, 2011/11/15 00:04:10]

on error -> of error
(or "of an error")

[Leandro Graciá Gil, 2011/11/15 12:10:12]

Done.

+It is safe to call <code>start</code> again from the error callback.</p>

[kathyw, 2011/11/15 00:04:10]

start -> start()

[Leandro Graciá Gil, 2011/11/15 12:10:12]

Done.

+
+
+<h2 id="howToStop">How to stop recording</h2>
+<p>To stop speech recognition call the <code>stop</code> method. If provided,

[kathyw, 2011/11/15 00:04:10]

stop -> stop()

[Leandro Graciá Gil, 2011/11/15 12:10:12]

Done.

+<code>callback</code> will be called once recording has successfully

[kathyw, 2011/11/15 00:04:10]

<code>callback</code>
->
the callback function

[Leandro Graciá Gil, 2011/11/15 12:10:12]

Done.

+stopped. In case of error <code>chrome.extension.lastError</code> will be set.
+</p>
+
+
+<h2 id="otherFeatures">Other features</h2>
+<ul><li>
+<code>onSoundStart</code> - Event generated when start of sound is detected
+(from previously being silent).
+</li><li>
+<code>onSoundEnd</code> - Event generated when end of sound is detected (a
+continued period of silence).
+</li></ul>
+
+
+<h2 id="examples">Examples</h2>
+<p>The following example illustrates how to show a javascript alert with the

[kathyw, 2011/11/15 00:04:10]

javascript -> JavaScript

[Leandro Graciá Gil, 2011/11/15 12:10:12]

Done.

+most likely recognition result.</p>
+<pre>
+function checkStart() {
+  if (chrome.extension.lastError) {
+    alert("Couldn't start speech input: " + chrome.extension.lastError.message);
+  }
+}
+
+function recognitionFailed(error) {
+  alert("Speech input failed: " + error.code);
+}
+
+function recognitionSucceeded(result) {
+  alert("Recognized '" + result.hypotheses[0].utterance + "' with confidence " + result.hypotheses[0].confidence);
+}
+
+chrome.experimental.speechInput.onError.addListener(recognitionFailed);
+chrome.experimental.speechInput.onResult.addListener(recognitionSucceded);
+chrome.experimental.speechInput.start({ "language": "en" }, checkStart);
+</pre>

[kathyw, 2011/11/15 00:04:10]

We should add examples under docs/examples/<something> and link to them here.
But that can wait, unless you have an example handy.

[Leandro Graciá Gil, 2011/11/15 12:10:12]

The example I have is basically the same simple case I'm already showing here. I
guess something more elaborate should go to the examples folder.

On 2011/11/15 00:04:10, kathyw wrote: