Move the tts and ttsEngine APIs out of experimental, and give

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

Index: chrome/common/extensions/docs/static/experimental.tts.html
===================================================================
--- chrome/common/extensions/docs/static/experimental.tts.html	(revision 93167)
+++ chrome/common/extensions/docs/static/experimental.tts.html	(working copy)
@@ -1,190 +0,0 @@
-<p id="classSummary">
-Use the <code>chrome.experimental.tts</code> module to play synthesized
-text-to-speech (TTS) from your extension or packaged app.
-See also the related
-<a href="experimental.ttsEngine.html">experimental.ttsEngine</a>
-module, which allows an extension to implement a speech engine.
-</p>
-
-<p class="note"><b>Give us feedback:</b> If you have suggestions,
-especially changes that should be made before stabilizing the first
-version of this API, please send your ideas to the
-<a href="http://groups.google.com/a/chromium.org/group/chromium-extensions">chromium-extensions</a>
-group.</p>
-
-<h2 id="overview">Overview</h2>
-
-<p>To enable this experimental API, visit
-<b>chrome://flags</b> and enable <b>Experimental Extension APIs</b>.
-
-<p>Chrome provides native support for speech on Windows (using SAPI
-5), Mac OS X, and Chrome OS, using speech synthesis capabilities
-provided by the operating system. On all platforms, the user can
-install extensions that register themselves as alternative speech
-engines.</p>
-
-<h2 id="generating_speech">Generating speech</h2>
-
-<p>Call <code>speak()</code> from your extension or
-packaged app to speak. For example:</p>
-
-<pre>chrome.experimental.tts.speak('Hello, world.');</pre>
-
-<p>To stop speaking immediately, just call <code>stop()</code>:
-
-<pre>chrome.experimental.tts.stop();</pre>
-
-<p>You can provide options that control various properties of the speech,
-such as its rate, pitch, and more. For example:</p>
-
-<pre>chrome.experimental.tts.speak('Hello, world.', {'rate': 2.0});</pre>
-
-<p>It's also a good idea to specify the language so that a synthesizer
-supporting that language (and regional dialect, if applicable) is chosen.</p>
-
-<pre>chrome.experimental.tts.speak(
-    'Hello, world.', {'lang': 'en-US', 'rate': 2.0});</pre>
-
-<p>By default, each call to <code>speak()</code> interrupts any
-ongoing speech and speaks immediately. To determine if a call would be
-interrupting anything, you can call <code>isSpeaking()</code>.  In
-addition, you can use the <code>enqueue</code> option to cause this
-utterance to be added to a queue of utterances that will be spoken
-when the current utterance has finished.</p>
-
-<pre>chrome.experimental.tts.speak(
-    'Speak this first.');
-chrome.experimental.tts.speak(
-    'Speak this next, when the first sentence is done.', {'enqueue': true});
-</pre>
-
-<p>A complete description of all options can be found in the
-<a href="#method-speak">speak() method documentation</a> below.
-Not all speech engines will support all options.</p>
-
-<p>To catch errors and make sure you're calling <code>speak()</code>
-correctly, pass a callback function that takes no arguments. Inside
-the callback, check
-<a href="extension.html#property-lastError">chrome.extension.lastError</a>
-to see if there were any errors.</p>
-
-<pre>chrome.experimental.tts.speak(
-    utterance,
-    options,
-    function() {
-      if (chrome.extension.lastError) {
-        console.log('Error: ' + chrome.extension.lastError.message);
-      }
-    });</pre>
-
-<p>The callback returns right away, before the engine has started
-generating speech. The purpose of the callback is to alert you to
-syntax errors in your use of the TTS API, not to catch all possible
-errors that might occur in the process of synthesizing and outputting
-speech. To catch these errors too, you need to use an event listener,
-described below.</p>
-
-<h2 id="events">Listening to events</h2>
-
-<p>To get more real-time information about the status of synthesized speech,
-pass an event listener in the options to <code>speak()</code>, like this:</p>
-
-<pre>chrome.experimental.tts.speak(
-    utterance,
-    {
-      onEvent: function(event) {
-        console.log('Event ' + event.type ' at position ' + event.charIndex);
-        if (event.type == 'error') {
-          console.log('Error: ' + event.errorMessage);
-        }
-      }
-    },
-    callback);</pre>
-
-<p>Each event includes an event type, the character index of the current
-speech relative to the utterance, and for error events, an optional
-error message. The event types are:</p>
-
-<ul>
-  <li><code>'start'</code>: The engine has started speaking the utterance.
-  <li><code>'word'</code>: A word boundary was reached. Use
-          <code>event.charIndex</code> to determine the current speech
-          position.
-  <li><code>'sentence'</code>: A sentence boundary was reached. Use
-          <code>event.charIndex</code> to determine the current speech
-          position.
-  <li><code>'marker'</code>: An SSML marker was reached. Use
-          <code>event.charIndex</code> to determine the current speech
-          position.
-  <li><code>'end'</code>: The engine has finished speaking the utterance.
-  <li><code>'interrupted'</code>: This utterance was interrupted by another
-          call to <code>speak()</code> or <code>stop()</code> and did not
-          finish.
-  <li><code>'cancelled'</code>: This utterance was queued, but then
-          cancelled by another call to <code>speak()</code> or
-          <code>stop()</code> and never began to speak at all.
-  <li><code>'error'</code>: An engine-specific error occurred and
-          this utterance cannot be spoken.
-          Check <code>event.errorMessage</code> for details.
-</ul>
-
-<p>Four of the event types&mdash;<code>'end'</code>, <code>'interrupted'</code>,
-<code>'cancelled'</code>, and <code>'error'</code>&mdash;are <i>final</i>.
-After one of those events is received, this utterance will no longer
-speak and no new events from this utterance will be received.</p>
-
-<p>Some voices may not support all event types, and some voices may not
-send any events at all. If you do not want to use a voice unless it sends
-certain events, pass the events you require in the
-<code>requiredEventTypes</code> member of the options object, or use
-<code>getVoices()</code> to choose a voice that meets your requirements.
-Both are documented below.</p>
-
-<h2 id="ssml">SSML markup</h2>
-
-<p>Utterances used in this API may include markup using the
-<a href="http://www.w3.org/TR/speech-synthesis">Speech Synthesis Markup
-Language (SSML)</a>. If you use SSML, the first argument to
-<code>speak()</code> should be a complete SSML document with an XML
-header and a top-level <code>&lt;speak&gt;</code> tag, not a document
-fragment.</p>
-
-<p>For example:</p>
-
-<pre>chrome.experimental.tts.speak(
-    '&lt;?xml version="1.0"?&gt;' +
-    '&lt;speak&gt;' +
-    '  The &lt;emphasis&gt;second&lt;/emphasis&gt; ' +
-    '  word of this sentence was emphasized.' +
-    '&lt;/speak&gt;');</pre>
-
-<p>Not all speech engines will support all SSML tags, and some may not support
-SSML at all, but all engines are required to ignore any SSML they don't
-support and to still speak the underlying text.</p>
-
-<h2 id="choosing_voice">Choosing a voice</h2>
-
-<p>By default, Chrome chooses the most appropriate voice for each
-utterance you want to speak, based on the language and gender. On most
-Windows, Mac OS X, and Chrome OS systems, speech synthesis provided by
-the operating system should be able to speak any text in at least one
-language. Some users may have a variety of voices available, though,
-from their operating system and from speech engines implemented by other
-Chrome extensions. In those cases, you can implement custom code to choose
-the appropriate voice, or to present the user with a list of choices.</p>
-
-<p>To get a list of all voices, call <code>getVoices()</code> and pass it
-a function that receives an array of <code>TtsVoice</code> objects as its
-argument:</p>
-
-<pre>chrome.experimental.tts.getVoices(
-    function(voices) {
-      for (var i = 0; i < voices.length; i++) {
-        console.log('Voice ' + i + ':');
-        console.log('  name: ' + voices[i].voiceName);
-        console.log('  lang: ' + voices[i].lang);
-        console.log('  gender: ' + voices[i].gender);
-        console.log('  extension id: ' + voices[i].extensionId);
-        console.log('  event types: ' + voices[i].eventTypes);
-      }
-    });</pre>