| OLD | NEW |
|---|
| (Empty) |
| 1 <p id="classSummary"> | |
| 2 Use the <code>chrome.experimental.tts</code> module to play synthesized | |
| 3 text-to-speech (TTS) from your extension or packaged app. | |
| 4 See also the related | |
| 5 <a href="experimental.ttsEngine.html">experimental.ttsEngine</a> | |
| 6 module, which allows an extension to implement a speech engine. | |
| 7 </p> | |
| 8 | |
| 9 <p class="note"><b>Give us feedback:</b> If you have suggestions, | |
| 10 especially changes that should be made before stabilizing the first | |
| 11 version of this API, please send your ideas to the | |
| 12 <a href="http://groups.google.com/a/chromium.org/group/chromium-extensions">chro
mium-extensions</a> | |
| 13 group.</p> | |
| 14 | |
| 15 <h2 id="overview">Overview</h2> | |
| 16 | |
| 17 <p>To enable this experimental API, visit | |
| 18 <b>chrome://flags</b> and enable <b>Experimental Extension APIs</b>. | |
| 19 | |
| 20 <p>Chrome provides native support for speech on Windows (using SAPI | |
| 21 5), Mac OS X, and Chrome OS, using speech synthesis capabilities | |
| 22 provided by the operating system. On all platforms, the user can | |
| 23 install extensions that register themselves as alternative speech | |
| 24 engines.</p> | |
| 25 | |
| 26 <h2 id="generating_speech">Generating speech</h2> | |
| 27 | |
| 28 <p>Call <code>speak()</code> from your extension or | |
| 29 packaged app to speak. For example:</p> | |
| 30 | |
| 31 <pre>chrome.experimental.tts.speak('Hello, world.');</pre> | |
| 32 | |
| 33 <p>To stop speaking immediately, just call <code>stop()</code>: | |
| 34 | |
| 35 <pre>chrome.experimental.tts.stop();</pre> | |
| 36 | |
| 37 <p>You can provide options that control various properties of the speech, | |
| 38 such as its rate, pitch, and more. For example:</p> | |
| 39 | |
| 40 <pre>chrome.experimental.tts.speak('Hello, world.', {'rate': 2.0});</pre> | |
| 41 | |
| 42 <p>It's also a good idea to specify the language so that a synthesizer | |
| 43 supporting that language (and regional dialect, if applicable) is chosen.</p> | |
| 44 | |
| 45 <pre>chrome.experimental.tts.speak( | |
| 46 'Hello, world.', {'lang': 'en-US', 'rate': 2.0});</pre> | |
| 47 | |
| 48 <p>By default, each call to <code>speak()</code> interrupts any | |
| 49 ongoing speech and speaks immediately. To determine if a call would be | |
| 50 interrupting anything, you can call <code>isSpeaking()</code>. In | |
| 51 addition, you can use the <code>enqueue</code> option to cause this | |
| 52 utterance to be added to a queue of utterances that will be spoken | |
| 53 when the current utterance has finished.</p> | |
| 54 | |
| 55 <pre>chrome.experimental.tts.speak( | |
| 56 'Speak this first.'); | |
| 57 chrome.experimental.tts.speak( | |
| 58 'Speak this next, when the first sentence is done.', {'enqueue': true}); | |
| 59 </pre> | |
| 60 | |
| 61 <p>A complete description of all options can be found in the | |
| 62 <a href="#method-speak">speak() method documentation</a> below. | |
| 63 Not all speech engines will support all options.</p> | |
| 64 | |
| 65 <p>To catch errors and make sure you're calling <code>speak()</code> | |
| 66 correctly, pass a callback function that takes no arguments. Inside | |
| 67 the callback, check | |
| 68 <a href="extension.html#property-lastError">chrome.extension.lastError</a> | |
| 69 to see if there were any errors.</p> | |
| 70 | |
| 71 <pre>chrome.experimental.tts.speak( | |
| 72 utterance, | |
| 73 options, | |
| 74 function() { | |
| 75 if (chrome.extension.lastError) { | |
| 76 console.log('Error: ' + chrome.extension.lastError.message); | |
| 77 } | |
| 78 });</pre> | |
| 79 | |
| 80 <p>The callback returns right away, before the engine has started | |
| 81 generating speech. The purpose of the callback is to alert you to | |
| 82 syntax errors in your use of the TTS API, not to catch all possible | |
| 83 errors that might occur in the process of synthesizing and outputting | |
| 84 speech. To catch these errors too, you need to use an event listener, | |
| 85 described below.</p> | |
| 86 | |
| 87 <h2 id="events">Listening to events</h2> | |
| 88 | |
| 89 <p>To get more real-time information about the status of synthesized speech, | |
| 90 pass an event listener in the options to <code>speak()</code>, like this:</p> | |
| 91 | |
| 92 <pre>chrome.experimental.tts.speak( | |
| 93 utterance, | |
| 94 { | |
| 95 onEvent: function(event) { | |
| 96 console.log('Event ' + event.type ' at position ' + event.charIndex); | |
| 97 if (event.type == 'error') { | |
| 98 console.log('Error: ' + event.errorMessage); | |
| 99 } | |
| 100 } | |
| 101 }, | |
| 102 callback);</pre> | |
| 103 | |
| 104 <p>Each event includes an event type, the character index of the current | |
| 105 speech relative to the utterance, and for error events, an optional | |
| 106 error message. The event types are:</p> | |
| 107 | |
| 108 <ul> | |
| 109 <li><code>'start'</code>: The engine has started speaking the utterance. | |
| 110 <li><code>'word'</code>: A word boundary was reached. Use | |
| 111 <code>event.charIndex</code> to determine the current speech | |
| 112 position. | |
| 113 <li><code>'sentence'</code>: A sentence boundary was reached. Use | |
| 114 <code>event.charIndex</code> to determine the current speech | |
| 115 position. | |
| 116 <li><code>'marker'</code>: An SSML marker was reached. Use | |
| 117 <code>event.charIndex</code> to determine the current speech | |
| 118 position. | |
| 119 <li><code>'end'</code>: The engine has finished speaking the utterance. | |
| 120 <li><code>'interrupted'</code>: This utterance was interrupted by another | |
| 121 call to <code>speak()</code> or <code>stop()</code> and did not | |
| 122 finish. | |
| 123 <li><code>'cancelled'</code>: This utterance was queued, but then | |
| 124 cancelled by another call to <code>speak()</code> or | |
| 125 <code>stop()</code> and never began to speak at all. | |
| 126 <li><code>'error'</code>: An engine-specific error occurred and | |
| 127 this utterance cannot be spoken. | |
| 128 Check <code>event.errorMessage</code> for details. | |
| 129 </ul> | |
| 130 | |
| 131 <p>Four of the event types—<code>'end'</code>, <code>'interrupted'</code>, | |
| 132 <code>'cancelled'</code>, and <code>'error'</code>—are <i>final</i>. | |
| 133 After one of those events is received, this utterance will no longer | |
| 134 speak and no new events from this utterance will be received.</p> | |
| 135 | |
| 136 <p>Some voices may not support all event types, and some voices may not | |
| 137 send any events at all. If you do not want to use a voice unless it sends | |
| 138 certain events, pass the events you require in the | |
| 139 <code>requiredEventTypes</code> member of the options object, or use | |
| 140 <code>getVoices()</code> to choose a voice that meets your requirements. | |
| 141 Both are documented below.</p> | |
| 142 | |
| 143 <h2 id="ssml">SSML markup</h2> | |
| 144 | |
| 145 <p>Utterances used in this API may include markup using the | |
| 146 <a href="http://www.w3.org/TR/speech-synthesis">Speech Synthesis Markup | |
| 147 Language (SSML)</a>. If you use SSML, the first argument to | |
| 148 <code>speak()</code> should be a complete SSML document with an XML | |
| 149 header and a top-level <code><speak></code> tag, not a document | |
| 150 fragment.</p> | |
| 151 | |
| 152 <p>For example:</p> | |
| 153 | |
| 154 <pre>chrome.experimental.tts.speak( | |
| 155 '<?xml version="1.0"?>' + | |
| 156 '<speak>' + | |
| 157 ' The <emphasis>second</emphasis> ' + | |
| 158 ' word of this sentence was emphasized.' + | |
| 159 '</speak>');</pre> | |
| 160 | |
| 161 <p>Not all speech engines will support all SSML tags, and some may not support | |
| 162 SSML at all, but all engines are required to ignore any SSML they don't | |
| 163 support and to still speak the underlying text.</p> | |
| 164 | |
| 165 <h2 id="choosing_voice">Choosing a voice</h2> | |
| 166 | |
| 167 <p>By default, Chrome chooses the most appropriate voice for each | |
| 168 utterance you want to speak, based on the language and gender. On most | |
| 169 Windows, Mac OS X, and Chrome OS systems, speech synthesis provided by | |
| 170 the operating system should be able to speak any text in at least one | |
| 171 language. Some users may have a variety of voices available, though, | |
| 172 from their operating system and from speech engines implemented by other | |
| 173 Chrome extensions. In those cases, you can implement custom code to choose | |
| 174 the appropriate voice, or to present the user with a list of choices.</p> | |
| 175 | |
| 176 <p>To get a list of all voices, call <code>getVoices()</code> and pass it | |
| 177 a function that receives an array of <code>TtsVoice</code> objects as its | |
| 178 argument:</p> | |
| 179 | |
| 180 <pre>chrome.experimental.tts.getVoices( | |
| 181 function(voices) { | |
| 182 for (var i = 0; i < voices.length; i++) { | |
| 183 console.log('Voice ' + i + ':'); | |
| 184 console.log(' name: ' + voices[i].voiceName); | |
| 185 console.log(' lang: ' + voices[i].lang); | |
| 186 console.log(' gender: ' + voices[i].gender); | |
| 187 console.log(' extension id: ' + voices[i].extensionId); | |
| 188 console.log(' event types: ' + voices[i].eventTypes); | |
| 189 } | |
| 190 });</pre> | |
| OLD | NEW |
|---|
Chromium Code Reviews
Issue 7258007:
Move the tts and ttsEngine APIs out of experimental, and give (Closed)
Base URL: svn://chrome-svn/chrome/trunk/src/