You are viewing extension docs in chrome via the 'file:' scheme: are you expecting to see local changes when you refresh? You'll need run chrome with --allow-file-access-from-files.
paramName
( optional enumerated Type array of paramType )
Undocumented.
Description of this parameter from the json schema.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
Parameters

Google Chrome Extensions (Labs)

chrome.experimental.tts

For information on how to use experimental APIs, see the chrome.experimental.* APIs page.

Use the chrome.experimental.tts module to play synthesized text-to-speech (TTS) from your extension or packaged app. See also the related experimental.ttsEngine module which allows an extension to implement a speech engine.

Give us feedback: If you have suggestions, especially changes that should be made before stabilizing the first version of this API, please send your ideas to the chromium-extensions group.

Overview

To enable this experimental API, visit chrome://flags and enable Experimental Extension APIs.

Chrome provides native support for speech on Windows (using SAPI 5), Mac OS X, and Chrome OS, using speech synthesis capabilities provided by the operating system. On all platforms, the user can install extensions that register themselves as alternative speech engines.

Generating speech

Call speak() from your extension or packaged app to speak. For example:

chrome.experimental.tts.speak('Hello, world.');

To stop speaking immediately, just call stop(): 

chrome.experimental.tts.stop();

You can provide options that control various properties of the speech, such as its rate, pitch, and more. For example:

chrome.experimental.tts.speak('Hello, world.', {'rate': 2.0});

It's also a good idea to specify the language so that a synthesizer supporting that language (and regional dialect, if applicable) is chosen.

chrome.experimental.tts.speak(
    'Hello, world.', {'lang': 'en-US', 'rate': 2.0});

By default, each call to speak() will interrupt any ongoing speech and speak immediately. To determine if a call would be interrupting anything, you can call isSpeaking(), or you can use the enqueue option to cause this utterance to be added to a queue of utterances that will be spoken when the current utterance has finished. 

chrome.experimental.tts.speak(
    'Speak this first.');
chrome.experimental.tts.speak(
    'Speak this next, when the first sentence is done.', {'enqueue': true});

A complete description of all options can be found in the speak() method documentation below. Not all speech engines will support all options.

To catch errors and make sure you're calling speak() correctly, pass a callback function that takes no arguments. Inside the callback, check chrome.extension.lastError to see if there were any errors.

chrome.experimental.tts.speak(
    utterance,
    options,
    function() {
      if (chrome.extension.lastError) {
        console.log('Error: ' + chrome.extension.lastError.message);
      }
    });

The callback returns right away, before the speech engine has started generating speech. The purpose of the callback is to alert you to syntax errors in your use of the TTS API, not all possible errors that might occur in the process of synthesizing and outputting speech. To catch these errors too, you need to use an event listener, described below.

Listening to events

To get more real-time information about the status of synthesized speech, pass an event listener in the options to speak(), like this:

chrome.experimental.tts.speak(
    utterance,
    {
      'onevent': function(event) {
        console.log('Event ' + event.type ' at position ' + event.charIndex);
        if (event.type == 'error') {
          console.log('Error: ' + event.errorMessage);
        }
      }
    },
    callback);

Each event includes an event type, the character index of the current speech relative to the utterance, and for error events, an optional error message. The event types are:

  • 'start': the engine has started speaking the utterance.
  • 'word': a word boundary was reached. Use event.charIndex to determine the current speech position.
  • 'sentence': a sentence boundary was reached. Use event.charIndex to determine the current speech position.
  • 'marker': an SSML marker was reached. Use event.charIndex to determine the current speech position.
  • 'end': the engine has finished speaking the utterance.
  • 'interrupted': this utterance was interrupted by another call to speak() or stop() and did not finish.
  • 'cancelled': this utterance was queued, but then cancelled by another call to speak() or stop() and never began to speak at all.
  • 'error': An engine-specific error occurred and this utterance cannot be spoken. Check event.errorMessage for details.

Four of the event types, 'end', 'interrupted', 'cancelled', and 'error', are final. After one of those events is received, this utterance will no longer speak and no new events from this utterance will be received.

Some TTS engines may not support all event types, and some may not even support any events at all. To require that the speech engine used sends the events you're interested in, you can pass a list of event types in the requiredEventTypes member of the options object, or use getVoices to choose a voice that has the events you need. Both are documented below.

SSML markup

Utterances used in this API may include markup using the Speech Synthesis Markup Language (SSML). If you use SSML, the first argument to speak() should be a complete SSML document with an XML header and a top-level <speak> tag, not a document fragment. For example: 

chrome.experimental.tts.speak(
    '<?xml version="1.0"?>' +
    '<speak>' +
    '  The <emphasis>second</emphasis> ' +
    '  word of this sentence was emphasized.' +
    '</speak>');

Not all speech engines will support all SSML tags, and some may not support SSML at all, but all engines are required to ignore any SSML they don't support and still speak the underlying text.

Choosing a voice

By default, Chrome will choose the most appropriate voice for each utterance you want to speak, based on the language and gender. On most Windows, Mac OS X, and Chrome OS systems, speech synthesis provided by the operating system should be able to speak any text in at least one language. Some users may have a variety of voices available, though, from their operating system and from speech engines implemented by other Chrome extensions. In those cases, you can implement custom code to choose the appropriate voice, or present the user with a list of choices.

To get a list of all voices, call getVoices() and pass it a function that receives an array of TtsVoice objects as its argument:

chrome.experimental.tts.getVoices(
    function(voices) {
      for (var i = 0; i < voices.length; i++) {
        console.log('Voice ' + i + ':');
        console.log('  name: ' + voices[i].voiceName);
        console.log('  lang: ' + voices[i].lang);
        console.log('  gender: ' + voices[i].gender);
        console.log('  extension id: ' + voices[i].extensionId);
        console.log('  event types: ' + voices[i].eventTypes);
      }
    });

API reference: chrome.experimental.tts

Methods

getVoices

void chrome.experimental.tts.getVoices(, function callback)

Get an array of all available voices.

Parameters

callback
( optional Type array of function )
Undocumented.
Description of this parameter from the json schema.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

Returns

Callback function

The callback parameter should specify a function that looks like this:

If you specify the callback parameter, it should specify a function that looks like this: 

function(array of TtsVoice voices) {...};
voices
( Type array of TtsVoice array of paramType paramType )
Array of TtsVoice objects representing the available voices for speech synthesis.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

This function was added in version . If you require this function, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

isSpeaking

void chrome.experimental.tts.isSpeaking(, function callback)

Check if the engine is currently speaking.

Parameters

callback
( optional Type array of function )
Undocumented.
Description of this parameter from the json schema.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

Returns

Callback function

The callback parameter should specify a function that looks like this:

If you specify the callback parameter, it should specify a function that looks like this: 

function(boolean speaking) {...};
speaking
( Type array of boolean )
True if speaking, false otherwise.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

This function was added in version . If you require this function, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

speak

void chrome.experimental.tts.speak(, string utterance, object options, function callback)

Speak text using a text-to-speech engine.

Parameters

utterance
( Type array of string )
The text to speak, either plaintext or a complete well-formed SSML document. Speech engines that do not support SSML will strip away the tags and speak the text. The maximum length of the text is 32,768 characters.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
options
( optional Type array of object )
The speech options.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
enqueue
( optional Type array of boolean )
If true, enqueues this utterance if TTS is already in progress. If false (the default), interrupts any current speech and flushes the speech queue before speaking this new utterance.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
voiceName
( optional Type array of string )
The name of the voice to use for synthesis. If empty, uses any available voice.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
extensionId
( optional Type array of string )
The specific extension ID of the speech engine to use, if known.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
lang
( optional Type array of string )
The language to be used for synthesis, in the form <language>-<region>. Examples: 'en', 'en-US', 'en-GB', 'zh-CN', etc.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
gender
( optional enumerated Type array of string ["male", "female"] )
Gender of voice for synthesized speech.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
rate
( optional Type array of number )
Speaking rate relative to the default rate for this voice. 1.0 is the default rate, normally around 180 to 220 words per minute, 2.0 would be twice as fast, and 0.5 would be half as fast. Values below 0.1 or above 10.0 are strictly disallowed, but many voices will constrain the minimum and maximum rates further - i.e. a particular voice may not actually speak faster than 3 times normal even if you specify a value larger than 3.0.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
pitch
( optional Type array of number )
Speaking pitch between 0 and 2 inclusive, with 0 being lowest and 1 being highest, with 1.0 being the default pitch of this particular voice.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
volume
( optional Type array of number )
Speaking volume between 0 and 1 inclusive, with 0 being lowest and 1 being highest, with a default of 1.0.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
requiredEventTypes
( optional Type array of Type array of string paramType )
The TTS event types the voice must support. If missing, this criteria will not be used to filter voices.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
desiredEventTypes
( optional Type array of Type array of string paramType )
The TTS event types that should be sent. If missing, all event types will be sent.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
onevent
( optional Type array of function )
This function is called with events that occur in the process of speaking the utterance.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
Parameters
event
( TtsEvent array of paramType )
The update event from the text-to-speech engine indicating the status of this utterance.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
callback
( optional Type array of function )
Called right away, before speech finishes. Check chrome.extension.lastError to make sure there were no errors. Use options.onevent to get more detailed feedback.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

Returns

Callback function

The callback parameter should specify a function that looks like this:

If you specify the callback parameter, it should specify a function that looks like this: 

function() {...};

This function was added in version . If you require this function, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

stop

void chrome.experimental.tts.stop(, )

Stop any current speech.

Parameters

Returns

Callback function

The callback parameter should specify a function that looks like this:

If you specify the callback parameter, it should specify a function that looks like this: 

function(Type param1, Type param2) {...};

This function was added in version . If you require this function, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

Types

TtsEvent

paramName
( Type array of object )
An event from the TTS engine to communicate the status of an utterance.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
type
( enumerated Type array of string ["start", "end", "word", "sentence", "marker", "interrupted", "cancelled", "error"] )
The message can be 'start' when this utterance is begun to be spoken, 'word' when a word boundary is reached, 'sentence' when a sentence boundary is reached, 'marker' when an SSML mark element is reached, 'end' when the end of the utterance is reached, 'interrupted' when the utterance is stopped or interrupted before reaching the end, 'cancelled' when it's removed from the queue before ever being synthesized, and 'error' when any other error occurs. Clients will always receive 'end', 'cancelled', 'interrupted', or 'error', and other events will depend on the engine.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
charIndex
( optional Type array of number )
The index of the current character in the utterance.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
errorMessage
( optional Type array of string )
The error message, if the message is 'error'.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

TtsVoice

paramName
( Type array of object )
A description of a voice available for speech synthesis.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
voiceName
( optional Type array of string )
The name of the voice.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
lang
( optional Type array of string )
The language that this voice supports, in the form <language>-<region>. Examples: 'en', 'en-US', 'en-GB', 'zh-CN', etc.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
gender
( optional enumerated Type array of string ["male", "female"] )
This voice's gender.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
extensionId
( optional Type array of string )
The ID of the extension providing this voice.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
eventTypes
( optional Type array of Type array of string paramType )
All of the callback event types that this voice is capable of sending.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.