chrome.ttsEngine

refresh date: 2026-09-25 robots: noindex

Descrição

Use a API chrome.ttsEngine para implementar um mecanismo de conversão de texto em voz(TTS, na sigla em inglês) usando uma extensão. Se a extensão se registrar usando essa API, ela vai receber eventos com uma frase a ser falada e outros parâmetros quando qualquer extensão ou app do Chrome usar a API tts para gerar fala. A extensão pode usar qualquer tecnologia da Web disponível para sintetizar e gerar a fala, além de enviar eventos de volta à função de chamada para informar o status.

Permissões

ttsEngine

Visão geral

Uma extensão pode se registrar como um mecanismo de fala. Ao fazer isso, ele pode interceptar algumas ou todas as chamadas para funções como tts.speak e tts.stop e fornecer uma implementação alternativa. As extensões podem usar qualquer tecnologia da Web disponível para fornecer fala, incluindo streaming de áudio de um servidor, áudio HTML5. Uma extensão pode até fazer algo diferente com as falas, como mostrar legendas descritivas em uma janela pop-up ou enviá-las como mensagens de registro para um servidor remoto.

Manifesto

Para implementar um mecanismo de TTS, uma extensão precisa declarar a permissão "ttsEngine" e, em seguida, declarar todas as vozes que ela fornece no manifesto da extensão, desta forma:

{
  "name": "My TTS Engine",
  "version": "1.0",
  "permissions": ["ttsEngine"],
  "tts_engine": {
    "voices": [
      {
        "voice_name": "Alice",
        "lang": "en-US",
        "event_types": ["start", "marker", "end"]
      },
      {
        "voice_name": "Pat",
        "lang": "en-US",
        "event_types": ["end"]
      }
    ]
  },
  "background": {
    "page": "background.html",
    "persistent": false
  }
}

Uma extensão pode especificar qualquer número de vozes.

O parâmetro voice_name é obrigatório. O nome precisa ser descritivo o suficiente para identificar o nome da voz e o mecanismo usado. No caso improvável de duas extensões registrarem vozes com o mesmo nome, um cliente pode especificar o ID da extensão que deve fazer a síntese.

O parâmetro lang é opcional, mas altamente recomendado. Quase sempre, uma voz pode sintetizar a fala em apenas um idioma. Quando um mecanismo oferece suporte a mais de um idioma, ele pode registrar facilmente uma voz separada para cada um. Em raras circunstâncias em que uma única voz pode lidar com mais de um idioma, é mais fácil listar duas vozes separadas e lidar com elas usando a mesma lógica internamente. No entanto, se você quiser criar uma voz que lide com enunciados em qualquer idioma, omita o parâmetro lang do manifesto da extensão.

Por fim, o parâmetro event_types é obrigatório se o mecanismo puder enviar eventos para atualizar o cliente sobre o progresso da síntese de voz. No mínimo, é altamente recomendável oferecer suporte ao tipo de evento 'end' para indicar quando a fala é concluída. Caso contrário, o Chrome não poderá programar as falas em fila.

Depois de carregada, uma extensão pode substituir a lista de vozes declaradas chamando chrome.ttsEngine.updateVoices. Os parâmetros usados na chamada programática para updateVoices estão em letras concatenadas, por exemplo, voiceName, ao contrário do arquivo de manifesto, que usa voice_name.

Os tipos de evento que você pode enviar correspondem aos tipos de evento que o método speak() recebe:

  • '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.
  • 'error': ocorreu um erro específico do mecanismo, e não é possível falar essa frase. Transmita mais informações em event.errorMessage.

Os eventos 'interrupted' e 'cancelled' não são enviados pelo mecanismo de fala, mas gerados automaticamente pelo Chrome.

Os clientes de conversão de texto em voz podem receber as informações de voz do manifesto da sua extensão chamando tts.getVoices, supondo que você tenha registrado listeners de eventos de fala, conforme descrito abaixo.

Como lidar com eventos de fala

Para gerar fala a pedido dos clientes, sua extensão precisa registrar listeners para onSpeak e onStop, desta forma:

const speakListener = (utterance, options, sendTtsEvent) => {
  sendTtsEvent({type: 'start', charIndex: 0})

  // (start speaking)

  sendTtsEvent({type: 'end', charIndex: utterance.length})
};

const stopListener = () => {
  // (stop all speech)
};

chrome.ttsEngine.onSpeak.addListener(speakListener);
chrome.ttsEngine.onStop.addListener(stopListener);

A decisão de enviar ou não uma determinada solicitação de fala para uma extensão é baseada apenas no fato de a extensão oferecer suporte aos parâmetros de voz fornecidos no manifesto e ter listeners registrados para onSpeak e onStop. Em outras palavras, não há como uma extensão receber uma solicitação de fala e decidir dinamicamente se vai processá-la.

Tipos

AudioBuffer

Chrome 92+

Parâmetros que contêm um buffer de áudio e dados associados.

Propriedades

  • audioBuffer

    ArrayBuffer

    O buffer de áudio do mecanismo de conversão de texto em voz. Ele precisa ter exatamente o comprimento audioStreamOptions.bufferSize e ser codificado como mono, em audioStreamOptions.sampleRate, e como PCM linear, float assinado de 32 bits, ou seja, o tipo Float32Array em JavaScript.

  • charIndex

    número optional

    O índice de caracteres associado a esse buffer de áudio.

  • isLastBuffer

    booleano opcional

    Verdadeiro se esse buffer de áudio for o último do texto que está sendo falado.

AudioStreamOptions

Chrome 92+

Contém o formato do stream de áudio que deve ser produzido por um mecanismo.

Propriedades

  • bufferSize

    número

    O número de amostras em um buffer de áudio.

  • sampleRate

    número

    A taxa de amostragem esperada em um buffer de áudio.

LanguageInstallStatus

Chrome 132+

O status de instalação de uma voz.

Enumeração

"notInstalled"

"installing"

"installed"

"failed"

LanguageStatus

Chrome 132+

Status de instalação de um idioma.

Propriedades

  • erro

    string opcional

    Detalhes sobre falhas de instalação. Preenchido opcionalmente se houver falha na instalação do idioma.

  • installStatus

    LanguageInstallStatus

    Status da instalação.

  • lang

    string

    String de idioma na forma de código de idioma-código de região, em que a região pode ser omitida. Exemplos: en, en-AU, zh-CH.

LanguageUninstallOptions

Chrome 132+

Opções para desinstalar um determinado idioma.

Propriedades

  • uninstallImmediately

    booleano

    Verdadeiro se o cliente de TTS quiser que o idioma seja desinstalado imediatamente. O mecanismo pode escolher se ou quando desinstalar o idioma, com base nesse parâmetro e nas informações do solicitante. Se for falso, ele poderá usar outros critérios, como o uso recente, para determinar quando desinstalar.

SpeakOptions

Chrome 92+

Opções especificadas para o método tts.speak().

Propriedades

  • gênero

    VoiceGender opcional

    Descontinuado desde o Chrome 92

    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 da 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. Esse valor precisa estar entre 0,1 e 10,0, inclusive. Quando uma voz não for compatível com toda essa faixa de taxas, não retorne um erro. Em vez disso, limite a taxa ao intervalo aceito pela voz.

  • voiceName

    string opcional

    O nome da voz a ser usada na síntese.

  • 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.

TtsClient

Chrome 131+

Identificador do cliente que está solicitando o status.

Propriedades

  • ID

    string

    Cliente que faz uma solicitação de gerenciamento de idioma. Para uma extensão, esse é o ID exclusivo dela. Para recursos do Chrome, esse é o nome legível por humanos do recurso.

  • Tipo de solicitante.

TtsClientSource

Chrome 131+

Tipo de solicitante.

Enumeração

"chromefeature"

"extension"

VoiceGender

Chrome 54+ Descontinuado desde o Chrome 70

O gênero foi descontinuado e será ignorado.

Enumeração

"male"

"female"

Métodos

updateLanguage()

Chrome 132+ 
chrome.ttsEngine.updateLanguage(
  status: LanguageStatus,
): void

Chamado por um mecanismo quando uma instalação de idioma é tentada e quando um idioma é desinstalado. Também é chamado em resposta a uma solicitação de status de um cliente. Quando uma voz é instalada ou desinstalada, o mecanismo também precisa chamar ttsEngine.updateVoices para registrar a voz.

Parâmetros

updateVoices()

Chrome 66 ou mais recente 
chrome.ttsEngine.updateVoices(
  voices: TtsVoice[],
): void

Chamado por um mecanismo para atualizar a lista de vozes. Essa lista substitui todas as vozes declaradas no manifesto da extensão.

Parâmetros

  • vozes

    TtsVoice[]

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

Eventos

onInstallLanguageRequest

Chrome 131+ 
chrome.ttsEngine.onInstallLanguageRequest.addListener(
  callback: function,
)

Acionado quando um cliente de TTS solicita a instalação de um novo idioma. O mecanismo deve tentar baixar e instalar o idioma e chamar ttsEngine.updateLanguage com o resultado. Se for bem-sucedido, o mecanismo também vai chamar ttsEngine.updateVoices para registrar as novas vozes disponíveis.

Parâmetros

  • callback

    função

    O parâmetro callback é semelhante a: 

    (requestor: TtsClient, lang: string) => void

onLanguageStatusRequest

Chrome 132+ 
chrome.ttsEngine.onLanguageStatusRequest.addListener(
  callback: function,
)

Acionado quando um cliente de TTS solicita o status de instalação de um idioma.

Parâmetros

  • callback

    função

    O parâmetro callback é semelhante a: 

    (requestor: TtsClient, lang: string) => void

onPause

chrome.ttsEngine.onPause.addListener(
  callback: function,
)

Opcional: se um mecanismo for compatível com o evento de pausa, ele vai pausar a frase atual que está sendo falada, se houver, até receber um evento de retomada ou de parada. Um evento de parada também precisa limpar o estado pausado.

Parâmetros

  • callback

    função

    O parâmetro callback é semelhante a: 

    () => void

onResume

chrome.ttsEngine.onResume.addListener(
  callback: function,
)

Opcional: se um mecanismo for compatível com o evento de pausa, ele também precisa ser compatível com o evento de retomada para continuar falando a frase atual, se houver. Um evento de parada também precisa limpar o estado pausado.

Parâmetros

  • callback

    função

    O parâmetro callback é semelhante a: 

    () => void

onSpeak

chrome.ttsEngine.onSpeak.addListener(
  callback: function,
)

Chamado quando o usuário faz uma chamada para tts.speak() e uma das vozes do manifesto dessa extensão é a primeira a corresponder ao objeto de opções.

Parâmetros

  • callback

    função

    O parâmetro callback é semelhante a: 

    (utterance: string, options: SpeakOptions, sendTtsEvent: function) => void

    • enunciado

      string

    • opções

      SpeakOptions

    • sendTtsEvent

      função

      O parâmetro sendTtsEvent é semelhante a: 

      (event: tts.TtsEvent) => void

      • evento

        tts.TtsEvent

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

onSpeakWithAudioStream

Chrome 92+ 
chrome.ttsEngine.onSpeakWithAudioStream.addListener(
  callback: function,
)

Chamado quando o usuário faz uma chamada para tts.speak() e uma das vozes do manifesto dessa extensão é a primeira a corresponder ao objeto de opções. Difere de ttsEngine.onSpeak porque o Chrome fornece serviços de reprodução de áudio e processa o envio de eventos de TTS.

Parâmetros

  • callback

    função

    O parâmetro callback é semelhante a: 

    (utterance: string, options: SpeakOptions, audioStreamOptions: AudioStreamOptions, sendTtsAudio: function, sendError: function) => void

    • enunciado

      string

    • opções

      SpeakOptions

    • audioStreamOptions

      AudioStreamOptions

    • sendTtsAudio

      função

      O parâmetro sendTtsAudio é semelhante a: 

      (audioBufferParams: AudioBuffer) => void

      • audioBufferParams

        AudioBuffer

        Parâmetros que contêm um buffer de áudio e dados associados.

    • sendError

      função

      Chrome 94 ou mais recente

      O parâmetro sendError é semelhante a: 

      (errorMessage?: string) => void

      • errorMessage

        string opcional

        Uma string que descreve o erro.

onStop

chrome.ttsEngine.onStop.addListener(
  callback: function,
)

Disparado quando uma chamada é feita para tts.stop e esta extensão pode estar no meio da fala. Se uma extensão receber uma chamada para onStop e a fala já estiver interrompida, ela não deve fazer nada (não gerar um erro). Se a fala estiver no estado pausado, isso vai cancelar o estado pausado.

Parâmetros

  • callback

    função

    O parâmetro callback é semelhante a: 

    () => void

onUninstallLanguageRequest

Chrome 132+ 
chrome.ttsEngine.onUninstallLanguageRequest.addListener(
  callback: function,
)

Acionado quando um cliente de TTS indica que um idioma não é mais necessário.

Parâmetros