Chrome TTS API Complete Reference

chrome.tts API Reference

The chrome.tts API enables extensions to synthesize speech using the operating system’s text-to-speech engine. This API is particularly useful for accessibility features, read-aloud functionality, language learning applications, and audio notifications.

Overview

The Text-to-Speech (TTS) API allows Chrome extensions to convert text into spoken words. The API provides fine-grained control over voice selection, speech rate, pitch, volume, and event handling for synchronized visual highlighting.

Permission Required: Add "tts" to the permissions array in your manifest.json:

{
  "permissions": ["tts"]
}

The API uses the system’s available TTS voices, which vary by operating system and installed language packs.

API Methods

chrome.tts.speak()

Speaks text using the TTS engine.

chrome.tts.speak(utterance, options?, callback?)

Parameters:

• utterance (string): The text to speak.
• options (optional object): Speech options including:
  • voiceName (string): The name of the voice to use.
  • lang (string): The language code (e.g., “en-US”, “es-ES”).
  • rate (number): Speech rate from 0.1 to 10 (default: 1).
  • pitch (number): Pitch from 0 to 2 (default: 1).
  • volume (number): Volume from 0 to 1 (default: 1).
  • enqueue (boolean): If true, appends to the queue instead of interrupting.
  • onEvent (function): Callback for speech events.
• callback (optional function): Called when speaking begins.

Example:

chrome.tts.speak('Hello, world!', {
  voiceName: 'Google US English',
  rate: 1.0,
  pitch: 1.0,
  volume: 1.0
}, () => {
  if (chrome.runtime.lastError) {
    console.error('TTS Error:', chrome.runtime.lastError);
  }
});

chrome.tts.stop()

Immediately stops any ongoing speech and clears the queue.

chrome.tts.stop()

Example:

// Stop speaking after 3 seconds
setTimeout(() => {
  chrome.tts.stop();
}, 3000);

chrome.tts.pause()

Pauses speech synthesis. Note: Not all TTS engines support pausing.

chrome.tts.pause()

chrome.tts.resume()

Resumes paused speech.

chrome.tts.resume()

chrome.tts.isSpeaking()

Checks whether the TTS engine is currently speaking.

chrome.tts.isSpeaking(callback)

Parameters:

• callback (function): Called with a boolean indicating if speaking.

Example:

chrome.tts.isSpeaking((speaking) => {
  console.log('Currently speaking:', speaking);
});

chrome.tts.getVoices()

Retrieves the list of available TTS voices.

chrome.tts.getVoices(callback)

Parameters:

• callback (function): Called with an array of TtsVoice objects.

Example:

chrome.tts.getVoices((voices) => {
  voices.forEach(voice => {
    console.log(`${voice.voiceName} (${voice.lang})`);
  });
});

TtsVoice Object

Represents a single available voice for speech synthesis.

Properties:

• voiceName (string): The name of the voice.
• lang (string): The language code (e.g., “en-US”).
• remote (boolean): Whether the voice is a remote network voice.
• extensionId (string): ID of the extension providing this voice (if applicable).
• eventTypes (array): Supported event types for this voice.

Example Voice Object:

{
  voiceName: 'Google US English',
  lang: 'en-US',
  remote: true,
  extensionId: 'none',
  eventTypes: ['start', 'end', 'word', 'sentence', 'marker']
}

Speech Events

The TTS API dispatches events during speech synthesis. Use the onEvent callback in chrome.tts.speak() to handle these events.

Event Types

Example with Event Handling:

chrome.tts.speak('Hello world, this is a test.', {
  onEvent: (event) => {
    if (event.type === 'word') {
      console.log(`Word: "${event.charIndex}"`);
    } else if (event.type === 'end') {
      console.log('Speech finished');
    } else if (event.type === 'error') {
      console.error('TTS Error:', event.errorMessage);
    }
  }
});

Use Cases

Accessibility

• Screen reader support for visually impaired users
• Audio feedback for keyboard navigation
• Voice prompts for complex interfaces

Read-Aloud Features

• Reading articles or documents aloud
• Email and message readers
• E-book narration

Language Learning

• Pronunciation practice
• Listening comprehension exercises
• Vocabulary audio playback

Audio Notifications

• Silent push notification alternatives
• Background task completion alerts
• Time-based announcements

Code Examples

Basic TTS Usage

Basic chrome.tts.speak Usage

function speakText(text) {
  chrome.tts.speak(text, () => {
    if (chrome.runtime.lastError) {
      console.error('TTS Error:', chrome.runtime.lastError.message);
    }
  });
}

speakText('Welcome to our extension!');

Voice Selection

function speakWithVoice(text, voiceName) {
  chrome.tts.getVoices((voices) => {
    const selectedVoice = voices.find(v => v.voiceName === voiceName);
    if (selectedVoice) {
      chrome.tts.speak(text, { voiceName: voiceName });
    } else {
      console.warn('Voice not found, using default');
      chrome.tts.speak(text);
    }
  });
}

speakWithVoice('Hello!', 'Google UK English Male');

Queue Multiple Utterances

function speakQueue(messages) {
  messages.forEach((msg, index) => {
    chrome.tts.speak(msg, {
      enqueue: true,
      onEvent: (event) => {
        if (event.type === 'end' && index === messages.length - 1) {
          console.log('All messages spoken');
        }
      }
    });
  });
}

speakQueue(['First message', 'Second message', 'Third message']);

Word Highlighting with Events

function speakWithHighlighting(text) {
  const utterance = new SpeechSynthesisUtterance(text);
  
  chrome.tts.speak(text, {
    onEvent: (event) => {
      if (event.type === 'word') {
        const word = text.substring(event.charIndex, event.charIndex + event.charLength);
        highlightWord(word); // Custom function to highlight word in UI
        console.log('Current word:', word);
      }
    }
  });
}

function highlightWord(word) {
  // Implementation depends on your UI
  console.log('Highlighting:', word);
}

Cross-References

• TTS Permission - Configuration and permission details
• TTS Engine Permission - Custom TTS engine development
• Accessibility Guide - Building accessible extensions
• chrome.ttsEngine API - Custom TTS engine implementation

  Frequently Asked Questions

How do I make Chrome speak text?

Use chrome.tts.speak() with the text to speak. You can customize rate, pitch, and voice selection.

Can I pause and resume speech?

Yes, use chrome.tts.pause() and chrome.tts.resume() to control ongoing speech.

Part of the Chrome Extension Guide by theluckystrike. Built at zovo.one.