chrome.tts

refresh date: 2026-09-25 robots: noindex

Descrição

Use a API chrome.tts para reproduzir a conversão de texto em voz (TTS, na sigla em inglês) sintetizada. Consulte também a API ttsEngine relacionada, que permite que uma extensão implemente um mecanismo de fala.

Permissões

tts

Visão geral

O Chrome oferece suporte nativo para fala no Windows (usando SAPI 5), Mac OS X e ChromeOS, usando recursos de síntese de fala fornecidos pelo sistema operacional. Em todas as plataformas, o usuário pode instalar extensões que se registram como mecanismos de fala alternativos.

Gerando fala

Chame speak() da sua extensão para falar. Exemplo:

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

Para interromper a fala imediatamente, basta chamar stop():

chrome.tts.stop();

É possível fornecer opções que controlam várias propriedades da fala, como taxa, tom e muito mais. Exemplo:

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

Também é recomendável especificar o idioma para que um sintetizador compatível com esse idioma (e dialeto regional, se aplicável) seja escolhido.

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

Por padrão, cada chamada para speak() interrompe qualquer fala em andamento e fala imediatamente. Para determinar se uma chamada interromperia algo, chame isSpeaking(). Além disso, é possível usar a opção enqueue para que esse enunciado seja adicionado a uma fila de enunciados que serão falados quando o enunciado atual for concluído.

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

Uma descrição completa de todas as opções pode ser encontrada na tts.speak abaixo. Nem todos os mecanismos de fala oferecem suporte a todas as opções.

Para detectar erros e garantir que você está chamando speak() corretamente, transmita uma função de callback que não use argumentos. No callback, verifique runtime.lastError para ver se houve algum erro.

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

O callback retorna imediatamente, antes que o mecanismo comece a gerar a fala. O objetivo do callback é alertar sobre erros de sintaxe no uso da API TTS, não detectar todos os possíveis erros que podem ocorrer no processo de sintetização e saída de fala. Para detectar esses erros também, use um listener de eventos, descrito abaixo.

Detectar eventos

Para receber mais informações em tempo real sobre o status da fala sintetizada, transmita um listener de eventos nas opções para speak(), desta forma:

chrome.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
);

Cada evento inclui um tipo de evento, o índice de caracteres da fala atual em relação à frase e, para eventos de erro, uma mensagem de erro opcional. Os tipos de evento são:

  • 'start': o mecanismo começou a falar o enunciado.
  • 'word': um limite de palavra foi atingido. Use event.charIndex para determinar a posição atual da fala.
  • 'sentence': um limite de frase foi atingido. Use event.charIndex para determinar a posição atual da fala.
  • 'marker': um marcador SSML foi alcançado. Use event.charIndex para determinar a posição atual da fala.
  • 'end': o mecanismo terminou de falar o enunciado.
  • 'interrupted': essa fala foi interrompida por outra chamada para speak() ou stop() e não foi concluída.
  • 'cancelled': essa fala foi colocada na fila, mas foi cancelada por outra chamada para speak() ou stop() e nunca começou a ser dita.
  • 'error': ocorreu um erro específico do mecanismo, e não é possível falar essa frase. Confira a event.errorMessage para saber mais.

Quatro dos tipos de evento ('end', 'interrupted', 'cancelled' e 'error') são finais. Depois que um desses eventos for recebido, essa fala não será mais dita e nenhum novo evento dela será recebido.

Algumas vozes podem não ser compatíveis com todos os tipos de evento, e outras podem não enviar nenhum evento. Se você não quiser usar uma voz, a menos que ela envie determinados eventos, transmita os eventos necessários no membro requiredEventTypes do objeto de opções ou use getVoices() para escolher uma voz que atenda aos seus requisitos. Ambos estão documentados abaixo.

Marcação SSML

As falas usadas nessa API podem incluir marcações usando a Linguagem de marcação de síntese de fala (SSML, na sigla em inglês). Se você usar SSML, o primeiro argumento para speak() precisa ser um documento SSML completo com um cabeçalho XML e uma tag <speak> de nível superior, não um fragmento de documento.

Exemplo:

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

Nem todos os mecanismos de fala são compatíveis com todas as tags SSML, e alguns podem não ser compatíveis com SSML, mas todos os mecanismos precisam ignorar qualquer SSML que não seja compatível e ainda falar o texto subjacente.

Como escolher uma voz

Por padrão, o Chrome escolhe a voz mais adequada para cada frase que você quer falar, com base no idioma. Na maioria dos sistemas Windows, Mac OS X e ChromeOS, a síntese de voz fornecida pelo sistema operacional deve ser capaz de ler qualquer texto em pelo menos um idioma. No entanto, alguns usuários podem ter uma variedade de vozes disponíveis no sistema operacional e nos mecanismos de fala implementados por outras extensões do Chrome. Nesses casos, é possível implementar um código personalizado para escolher a voz adequada ou apresentar ao usuário uma lista de opções.

Para ver uma lista de todas as vozes, chame getVoices() e transmita uma função que receba uma matriz de objetos TtsVoice como argumento:

chrome.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('  extension id: ' + voices[i].extensionId);
      console.log('  event types: ' + voices[i].eventTypes);
    }
  }
);

Tipos

EventType

Chrome 54 ou mais recente

Enumeração

"start"

"end"

"word"

"sentence"

"marker"

"interrupted"

"cancelled"

"error"

"pausar"

"resume"

TtsEvent

Um evento do mecanismo de TTS para comunicar o status de uma fala.

Propriedades

  • charIndex

    número optional

    O índice do caractere atual na fala. Para eventos de palavras, o evento é acionado no final de uma palavra e antes do início da próxima. O charIndex representa um ponto no texto no início da próxima palavra a ser falada.

  • errorMessage

    string opcional

    A descrição do erro, se o tipo de evento for error.

  • comprimento

    número optional

    Chrome 74+

    A duração da próxima parte da fala. Por exemplo, em um evento word, esse é o tamanho da palavra que será falada em seguida. Ele será definido como -1 se não for definido pelo mecanismo de fala.

  • tipo

    EventType

    O tipo pode ser start assim que a fala começa, word quando um limite de palavra é atingido, sentence quando um limite de frase é atingido, marker quando um elemento de marca SSML é atingido, end quando o fim da fala é atingido, interrupted quando a fala é interrompida antes de chegar ao fim, cancelled quando é removida da fila antes de ser sintetizada ou error quando ocorre qualquer outro erro. Ao pausar a fala, um evento pause será acionado se uma determinada frase for pausada no meio, e resume se uma frase retomar a fala. Os eventos de pausa e retomada podem não ser acionados se a fala for pausada entre as frases.

TtsOptions

Chrome 77 ou mais recente

As opções de fala para o mecanismo de TTS.

Propriedades

  • desiredEventTypes

    string[] opcional

    Os tipos de evento de TTS que você quer detectar. Se estiver ausente, todos os tipos de evento poderão ser enviados.

  • enqueue

    booleano opcional

    Se verdadeiro, coloca essa fala na fila se a TTS já estiver em andamento. Se for falso (o padrão), interrompe qualquer fala atual e limpa a fila de fala antes de falar essa nova frase.

  • extensionId

    string opcional

    O ID da extensão do mecanismo de fala a ser usado, se conhecido.

  • gênero

    VoiceGender opcional

    Descontinuado desde o Chrome 77

    O gênero foi descontinuado e será ignorado.

    Gênero da voz para fala sintetizada.

  • lang

    string opcional

    O idioma a ser usado para síntese, no formato idioma-região. Exemplos: "en", "en-US", "en-GB", "zh-CN".

  • pitch

    número optional

    Tom de fala entre 0 e 2, inclusive, em que 0 é o mais baixo e 2 é o mais alto. 1.0 corresponde ao tom padrão de uma voz.

  • taxa

    número optional

    Velocidade de fala em relação à velocidade padrão para essa voz. 1.0 é a taxa padrão, normalmente em torno de 180 a 220 palavras por minuto. 2,0 é duas vezes mais rápido e 0,5 é metade da velocidade nativa. Valores abaixo de 0,1 ou acima de 10,0 são estritamente proibidos, mas muitas vozes restringem ainda mais as taxas mínima e máxima. Por exemplo, uma voz específica pode não falar mais rápido do que três vezes o normal, mesmo que você especifique um valor maior que 3,0.

  • requiredEventTypes

    string[] opcional

    Os tipos de evento de TTS que a voz precisa aceitar.

  • voiceName

    string opcional

    O nome da voz a ser usada na síntese. Se estiver vazio, usa qualquer voz disponível.

  • volume

    número optional

    Volume de fala entre 0 e 1, inclusive, em que 0 é o mais baixo e 1 é o mais alto, com um padrão de 1,0.

  • onEvent

    void optional

    Essa função é chamada com eventos que ocorrem no processo de falar a frase.

    A função onEvent é semelhante a: 

    (event: TtsEvent) => {...}

    • evento

      TtsEvent

      O evento de atualização do mecanismo de conversão de texto em voz que indica o status dessa fala.

TtsVoice

Uma descrição de uma voz disponível para síntese de voz.

Propriedades

  • eventTypes

    EventType[] opcional

    Todos os tipos de evento de callback que essa voz pode enviar.

  • extensionId

    string opcional

    O ID da extensão que fornece essa voz.

  • gênero

    VoiceGender opcional

    Descontinuado desde o Chrome 70

    O gênero foi descontinuado e será ignorado.

    O gênero da voz.

  • lang

    string opcional

    O idioma compatível com essa voz, no formato idioma-região. Exemplos: "en", "en-US", "en-GB", "zh-CN".

  • controle remoto

    booleano opcional

    Se for verdadeiro, o mecanismo de síntese é um recurso de rede remoto. Ela pode ter uma latência maior e gerar custos de largura de banda.

  • voiceName

    string opcional

    Nome da voz.

VoiceGender

Chrome 54+ Descontinuado desde o Chrome 70

O gênero foi descontinuado e é ignorado.

Enumeração

"male"

"female"

Métodos

getVoices()

Promessa 
chrome.tts.getVoices(
  callback?: function,
): Promise<TtsVoice[]>

Recebe uma matriz de todas as vozes disponíveis.

Parâmetros

  • callback

    função optional

    O parâmetro callback é semelhante a: 

    (voices: TtsVoice[]) => void

    • vozes

      TtsVoice[]

      Matriz de objetos tts.TtsVoice que representam as vozes disponíveis para síntese de voz.

Retorna

  • Promise<TtsVoice[]>

    Chrome 101+

    As promessas só são compatíveis com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

isSpeaking()

Promessa 
chrome.tts.isSpeaking(
  callback?: function,
): Promise<boolean>

Verifica se o mecanismo está falando no momento. No Mac OS X, o resultado é verdadeiro sempre que o mecanismo de fala do sistema está falando, mesmo que a fala não tenha sido iniciada pelo Chrome.

Parâmetros

  • callback

    função optional

    O parâmetro callback é semelhante a: 

    (speaking: boolean) => void

    • falar

      booleano

      Verdadeiro se estiver falando. Caso contrário, falso.

Retorna

  • Promise<boolean>

    Chrome 101+

    As promessas só são compatíveis com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

pause()

chrome.tts.pause(): void

Pausa a síntese de voz, possivelmente no meio de uma fala. Uma chamada para retomar ou parar vai retomar a fala.

resume()

chrome.tts.resume(): void

Se a fala foi pausada, retoma de onde parou.

speak()

Promessa 
chrome.tts.speak(
  utterance: string,
  options?: TtsOptions,
  callback?: function,
): Promise<void>

Lê o texto usando um mecanismo de conversão de texto em voz.

Parâmetros

  • enunciado

    string

    O texto a ser falado, seja texto simples ou um documento SSML completo e bem formado. Os mecanismos de fala que não são compatíveis com SSML vão remover as tags e falar o texto. O tamanho máximo do texto é de 32.768 caracteres.

  • opções

    TtsOptions opcional

    As opções de fala.

  • callback

    função optional

    O parâmetro callback é semelhante a: 

    () => void

Retorna

  • Promessa<void>

    Chrome 101+

    Resolve imediatamente, antes que a fala termine. Se ocorrer um erro, a promessa será rejeitada. Use options.onEvent para receber feedback mais detalhado.

    As promessas só são compatíveis com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

stop()

chrome.tts.stop(): void

Interrompe qualquer fala atual e limpa a fila de enunciados pendentes. Além disso, se a fala foi pausada, ela será retomada na próxima chamada para falar.

Eventos

onVoicesChanged

Chrome 124+ 
chrome.tts.onVoicesChanged.addListener(
  callback: function,
)

Chamado quando a lista de tts.TtsVoice que seria retornada por getVoices é alterada.

Parâmetros

  • callback

    função

    O parâmetro callback é semelhante a: 

    () => void