Adding static documentation to the speech input extension API.

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

Index: chrome/common/extensions/docs/static/experimental.speechInput.html
diff --git a/chrome/common/extensions/docs/static/experimental.speechInput.html b/chrome/common/extensions/docs/static/experimental.speechInput.html
new file mode 100644
index 0000000000000000000000000000000000000000..11811a7b64794c899aeb6ad7097dc7d7b2d02f87
--- /dev/null
+++ b/chrome/common/extensions/docs/static/experimental.speechInput.html
@@ -0,0 +1,118 @@
+<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. It provides exclusive

[Satish, 2011/11/11 22:17:54]

The 'It provides exclusive' statement is duplicated below as well. Perhaps
remove it here?

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

Done.

+access to the default recording device to the first extension requesting it.
+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
+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> method.
+This will asynchronously request to start a new session for speech recognition.

[Satish, 2011/11/11 22:17:54]

This line seems unnecessary since you talk about the callback below

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

Done.

+If provided, <code>callback</code> will be called once the actual recording has

[Satish, 2011/11/11 22:17:54]

remove 'the actual'

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

Done.

+successfully started. A microphone tray icon will appear on the task bar during

[Satish, 2011/11/11 22:17:54]

We probably shouldn't talk about the UI here, just how to use the API?

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

Done.

+all the recognition session. In case of error during the start the call will

[Satish, 2011/11/11 22:17:54]

remove 'during the start the call will fail and '

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

Done.

+fail and <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 start when the device is

[Satish, 2011/11/11 22:17:54]

start -> "<code>start</code>"

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

Done.

+being used by anything else than the current extension will fail and set

[Satish, 2011/11/11 22:17:54]

'anything else than the current extension' -> 'another extension or web page'

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

Done.

+<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,
+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 in use call the <code>isRecording</code>

[Satish, 2011/11/11 22:17:54]

'in use' -> 'active'

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

Done.

+method. Please note that its result is limited to audio recording within Chrome.</p>

[Satish, 2011/11/11 22:17:54]

'its result is limited to' -> 'it only checks for'

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

Done.

+
+<p>Repeated calls for the same session from the extension currently accessing the

[Satish, 2011/11/11 22:17:54]

this paragraph seems unnecessary as these are obvious from the above
descriptions

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

Done.

+device will also fail and set the error code to <code>requestInProgress</code>
+or <code>invalidOperation</code> depending on the state of the first request.</p>
+
+
+<h2 id="howToGetResults">How to get speech recognition results</h2>
+<p>To listen for speech recognition results the API provides the function

[Satish, 2011/11/11 22:17:54]

Simplify as 'Listen to the <code>onResult<code> event to receive speech
recognition results.'. If you prefer to use 'chrome.experimental.speechInput.'
prefix suggest doing the same throughout this doc.

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

Done.

+<code>chrome.experimental.speechInput.onResult.addListener()</code> with the
+following signature.</p>
+
+<pre>
+var callback = function(result) { ... };
+
+chrome.experimental.speechInput.onResult.addListener(callback);
+</pre>
+
+<p>The <code>result</code> object contains an array of recognition hypotheses
+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>If there is an error during the recognition process or nothing could be

[Satish, 2011/11/11 22:17:54]

could simplify as 'To handle errors during speech recognition listen for the
<code>onError</code> event.' - and give a short code sample similar to above.
The callback's parameter would be different I presume

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

Done.

+recognized the <code>onError</code> event will be generated. To listen for
+recognition-time errors use the
+<code>chrome.experimental.speechInput.onError.addListener()</code> function
+in the same way as with <code>onResult</code>. Recording will automatically
+stop in case on error. It is safe to call <code>start</code> again
+from the error callback.</p>
+
+
+<h2 id="howToStop">How to stop recording</h2>
+<p>If an extension is currently recording for speech input it can request to stop

[Satish, 2011/11/11 22:17:54]

could simplify as 'To stop speech recognition call the <code>stop</code> method.
If provided, <code>callback</code>' ...

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

Done.

+anytime by calling the <code>stop</code> method. This will asynchronously
+request to finish the current speech recognition session ignoring any results.
+If provided, <code>callback</code> will be called once recording has
+successfully stopped.</p>
+
+<p>Any errors during the stop process will set
+<code>chrome.extension.lastError</code>. Repeated calls for the same session

[Satish, 2011/11/11 22:17:54]

could simplify similar to suggested above for start

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

Done.

+from the extension currently accessing the device will also fail and set the
+error code to <code>requestInProgress</code> or <code>invalidOperation</code>
+depending on the state of the first request.</p>
+
+
+<h2 id="otherFeatures">Other features</h2>
+<p>This API also generates events when sound is detected to start and stop

[Satish, 2011/11/11 22:17:54]

Perhaps simplify this as just a listing of these two events.
"
<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>
"

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

Done.

+during a recording session. To listen to them use the functions
+<code>chrome.experimental.speechInput.onSoundStart()</code> and
+<code>chrome.experimental.speechInput.onSoundEnd()</code>.</p>
+
+
+<h2 id="examples">Examples</h2>
+<p>The following example illustrates how to show a javascript alert with the
+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(result.hypotheses[0].utterance);
+}
+
+chrome.experimental.speechInput.onError.addListener(recognitionFailed);
+chrome.experimental.speechInput.onResult.addListener(recognitionSucceded);
+chrome.experimental.speechInput.start({ "language": "en" }, checkStart);
+</pre>