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