chrome/common/extensions/docs/templates/intros/ttsEngine.html

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