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, or to register as a speech provider for other extensions and packaged apps that want to speak.

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 synthesis providers.

Generating speech

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

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

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': 0.8});

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

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

Not all speech engines will support all options.

You can also pass a callback function that will be called when the speech has finished. For example, suppose we have an image on our page displaying a picture of a face with a closed mouth. We could open the mouth while speaking, and close it when done.

faceImage.src = 'open_mouth.png';
chrome.experimental.tts.speak(
    'Hello, world.', null, function() {
      faceImage.src = 'closed_mouth.png';
    });

To stop speaking immediately, just call stop(). Call isSpeaking() to find out if a TTS engine is currently speaking.

You can check to see if an error occurred by checking chrome.extension.lastError inside the callback function.

SSML markup

Utterances used in this API may include markup using the Speech Synthesis Markup Language (SSML). For example: 

chrome.experimental.tts.speak('The <emphasis>second</emphasis> word of this sentence was emphasized.');

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

Implementing a speech provider

An extension can register itself as a speech provider. By doing so, it can intercept some or all calls to functions such as speak() and stop() and provide an alternate implementation. Extensions are free to use any available web technology to provide speech, including streaming audio from a server, HTML5 audio, Native Client, or Flash. An extension could even do something different with the utterances, like display closed captions in a pop-up window or send them as log messages to a remote server.

To provide TTS, an extension must first declare all voices it provides in the extension manifest, like this:

{
  "name": "My TTS Provider",
  "version": "1.0",
  "permissions": ["experimental"]
  "tts": {
    "voices": [
      {
        "voiceName": "Alice",
        "locale": "en-US",
        "gender": "female"
      },
      {
        "voiceName": "Pat",
        "locale": "en-US"
      }
    ]
  },
  "background_page": "background.html",
}

An extension can specify any number of voices. The three parameters—voiceName, locale, and gender—are all optional. If they are all unspecified, the extension will handle all speech from all clients. If any of them are specified, they can be used to filter speech requests. For example, if a voice only supports French, it should set the locale to 'fr' (or something more specific like 'fr-FR') so that only utterances in that locale are routed to that extension.

To handle speech calls, the extension should register listeners for onSpeak and onStop, like this:

var speakListener = function(utterance, options, callback) {
  ...
  callback();
};
var stopListener = function() {
  ...
};
chrome.experimental.tts.onSpeak.addListener(speakListener);
chrome.experimental.tts.onStop.addListener(stopListener);

Important: Don't forget to call the callback function from your speak listener!

If an extension does not register listeners for both onSpeak and onStop, it will not intercept any speech calls, regardless of what is in the manifest.

The decision of whether or not to send a given speech request to an extension is based solely on whether the extension supports the given voice parameters in its manifest and has registered listeners for onSpeak and onStop. In other words, there's no way for an extension to receive a speech request and dynamically decide whether to handle it or not.

API reference: chrome.experimental.tts

Methods

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. May include SSML markup.
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.
locale
( optional Type array of string )
The language and optional region code that specify the language and dialect 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 speed between 0 and 1 inclusive, with 0 being slowest and 1 being fastest, with a default of 0.5.
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 1 inclusive, with 0 being lowest and 1 being highest, with a default of 0.5.
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.
callback
( optional Type array of function )
This function is called when speaking is finished.
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.

Events

onSpeak

chrome.experimental.tts.onSpeak.addListener(function(string utterance, object options, function callback) {...});

Called when the user makes a call to tts.speak and the options matches one of the tts_voices from this extension's manifest.

Parameters

utterance
( Type array of string )
The text to speak. This may include SSML, so if your engine does not support SSML, you should strip out all XML markup and synthesize only the underlying text content.
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
( Type array of object )
The speak 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.
voiceName
( optional Type array of string )
The name of the voice to use for 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.
locale
( optional Type array of string )
The language and region code that specify the language and dialect to be used for synthesis, in the form -, e.g. en-US, en-GB, fr-CA, 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 speed between 0 and 1 inclusive, with 0 being slowest and 1 being fastest.
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 1 inclusive, with 0 being lowest and 1 being highest.
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.
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
( Type array of function )
You must call this function when speaking is finished.
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.

onStop

chrome.experimental.tts.onStop.addListener(function() {...});

Fired when a call is made to tts.stop and this extension may be in the middle of speaking. If an extension receives a call to onStop and speech is already stopped, it should do nothing (not raise an error).

Parameters