OLD | NEW |
| (Empty) |
1 <p id="classSummary"> | |
2 Use the <code>chrome.ttsEngine</code> module to | |
3 implement a text-to-speech (TTS) engine using an extension. If your | |
4 extension registers using this API, it will receive events containing | |
5 an utterance to be spoken and other parameters when any extension or packaged | |
6 app uses the | |
7 <a href="tts.html">tts</a> | |
8 module to generate speech. Your extension can then use any available | |
9 web technology to synthesize and output the speech, and send events back | |
10 to the calling function to report the status. | |
11 </p> | |
12 <h2 id="overview">Overview</h2> | |
13 <p>An extension can register itself as a speech engine. By doing so, it | |
14 can intercept some or all calls to functions such as | |
15 <a href="tts.html#method-speak"><code>speak()</code></a> and | |
16 <a href="tts.html#method-stop"><code>stop()</code></a> | |
17 and provide an alternate implementation. | |
18 Extensions are free to use any available web technology | |
19 to provide speech, including streaming audio from a server, HTML5 audio, | |
20 Native Client, or Flash. An extension could even do something different | |
21 with the utterances, like display closed captions in a pop-up window or | |
22 send them as log messages to a remote server.</p> | |
23 <h2 id="manifest">Manifest</h2> | |
24 <p>To implement a TTS engine, an extension must | |
25 declare the "ttsEngine" permission and then declare all voices | |
26 it provides in the extension manifest, like this:</p> | |
27 <pre>{ | |
28 "name": "My TTS Engine", | |
29 "version": "1.0", | |
30 <b>"permissions": ["ttsEngine"], | |
31 "tts_engine": { | |
32 "voices": [ | |
33 { | |
34 "voice_name": "Alice", | |
35 "lang": "en-US", | |
36 "gender": "female", | |
37 "event_types": ["start", "marker", "end"] | |
38 }, | |
39 { | |
40 "voice_name": "Pat", | |
41 "lang": "en-US", | |
42 "event_types": ["end"] | |
43 } | |
44 ] | |
45 },</b> | |
46 "background_page": "background.html", | |
47 }</pre> | |
48 <p>An extension can specify any number of voices.</p> | |
49 <p>The <code>voice_name</code> parameter is required. The name should be | |
50 descriptive enough that it identifies the name of the voice and the | |
51 engine used. In the unlikely event that two extensions register voices | |
52 with the same name, a client can specify the ID of the extension that | |
53 should do the synthesis.</p> | |
54 <p>The <code>gender</code> parameter is optional. If your voice corresponds | |
55 to a male or female voice, you can use this parameter to help clients | |
56 choose the most appropriate voice for their application.</p> | |
57 <p>The <code>lang</code> parameter is optional, but highly recommended. | |
58 Almost always, a voice can synthesize speech in just a single language. | |
59 When an engine supports more than one language, it can easily register a | |
60 separate voice for each language. Under rare circumstances where a single | |
61 voice can handle more than one language, it's easiest to just list two | |
62 separate voices and handle them using the same logic internally. However, | |
63 if you want to create a voice that will handle utterances in any language, | |
64 leave out the <code>lang</code> parameter from your extension's manifest.</p> | |
65 <p>Finally, the <code>event_types</code> parameter is required if the engine can | |
66 send events to update the client on the progress of speech synthesis. | |
67 At a minimum, supporting the <code>'end'</code> event type to indicate | |
68 when speech is finished is highly recommended, otherwise Chrome cannot | |
69 schedule queued utterances.</p> | |
70 <p class="note"> | |
71 <strong>Note:</strong> If your TTS engine does not support | |
72 the <code>'end'</code> event type, Chrome cannot queue utterances | |
73 because it has no way of knowing when your utterance has finished. To | |
74 help mitigate this, Chrome passes an additional boolean <code>enqueue</code> | |
75 option to your engine's onSpeak handler, giving you the option of | |
76 implementing your own queueing. This is discouraged because then | |
77 clients are unable to queue utterances that should get spoken by different | |
78 speech engines.</p> | |
79 <p>The possible event types that you can send correspond to the event types | |
80 that the <code>speak()</code> method receives:</p> | |
81 <ul> | |
82 <li><code>'start'</code>: The engine has started speaking the utterance. | |
83 <li><code>'word'</code>: A word boundary was reached. Use | |
84 <code>event.charIndex</code> to determine the current speech | |
85 position. | |
86 <li><code>'sentence'</code>: A sentence boundary was reached. Use | |
87 <code>event.charIndex</code> to determine the current speech | |
88 position. | |
89 <li><code>'marker'</code>: An SSML marker was reached. Use | |
90 <code>event.charIndex</code> to determine the current speech | |
91 position. | |
92 <li><code>'end'</code>: The engine has finished speaking the utterance. | |
93 <li><code>'error'</code>: An engine-specific error occurred and | |
94 this utterance cannot be spoken. | |
95 Pass more information in <code>event.errorMessage</code>. | |
96 </ul> | |
97 <p>The <code>'interrupted'</code> and <code>'cancelled'</code> events are | |
98 not sent by the speech engine; they are generated automatically by Chrome.</p> | |
99 <p>Text-to-speech clients can get the voice information from your | |
100 extension's manifest by calling | |
101 <a href="tts.html#method-getVoices">getVoices()</a>, | |
102 assuming you've registered speech event listeners as described below.</p> | |
103 <h2 id="handling_speech_events">Handling speech events</h2> | |
104 <p>To generate speech at the request of clients, your extension must | |
105 register listeners for both <code>onSpeak</code> and <code>onStop</code>, | |
106 like this:</p> | |
107 <pre>var speakListener = function(utterance, options, sendTtsEvent) { | |
108 sendTtsEvent({'event_type': 'start', 'charIndex': 0}) | |
109 // (start speaking) | |
110 sendTtsEvent({'event_type': 'end', 'charIndex': utterance.length}) | |
111 }; | |
112 var stopListener = function() { | |
113 // (stop all speech) | |
114 }; | |
115 chrome.ttsEngine.onSpeak.addListener(speakListener); | |
116 chrome.ttsEngine.onStop.addListener(stopListener);</pre> | |
117 <p class="warning"> | |
118 <b>Important:</b> | |
119 If your extension does not register listeners for both | |
120 <code>onSpeak</code> and <code>onStop</code>, it will not intercept any | |
121 speech calls, regardless of what is in the manifest.</p> | |
122 <p>The decision of whether or not to send a given speech request to an | |
123 extension is based solely on whether the extension supports the given voice | |
124 parameters in its manifest and has registered listeners | |
125 for <code>onSpeak</code> and <code>onStop</code>. In other words, | |
126 there's no way for an extension to receive a speech request and | |
127 dynamically decide whether to handle it.</p> | |
OLD | NEW |