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 |