chrome.ttsEngine

Descrição

Use a API chrome.ttsEngine para implementar um mecanismo de conversão de texto em voz(TTS) usando uma extensão. Se a extensão se registrar usando essa API, ela vai receber eventos com uma frase a ser dita e outros parâmetros quando qualquer extensão ou app do Chrome usar a API tts para gerar fala. Sua extensão pode usar qualquer tecnologia da Web disponível para sintetizar e gerar a fala e 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 frases, como mostrar legendas 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 fornecidas no manifesto da extensão, como este:

{
  "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 a voz e o mecanismo usados. No caso improvável de duas extensões registrarem vozes com o mesmo nome, um cliente pode especificar o ID da extensão que fará 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 idioma. Em circunstâncias raras em que uma única voz pode processar mais de um idioma, é mais fácil listar duas vozes separadas e processá-las usando a mesma lógica internamente. No entanto, se você quiser criar uma voz que processe enunciados em qualquer idioma, deixe de fora o parâmetro lang do manifesto da extensão.

Por fim, o parâmetro event_types é necessário se o mecanismo puder enviar eventos para atualizar o cliente sobre o progresso da síntese de fala. 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 na 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 maiúsculas: 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 a frase.
  • 'word': um limite de palavras 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 a frase.
  • 'error': ocorreu um erro específico do mecanismo e essa frase não pode ser dita. Transmita mais informações em event.errorMessage.

Os eventos 'interrupted' e 'cancelled' não são enviados pelo mecanismo de fala. Eles são 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, desde que você tenha registrado listeners de eventos de fala, conforme descrito abaixo.

Como processar eventos de fala

Para gerar falas a pedido dos clientes, sua extensão precisa registrar listeners para onSpeak e onStop, assim:

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 na compatibilidade da extensão com os parâmetros de voz fornecidos no manifesto e se ela registrou listeners para onSpeak e onStop. Em outras palavras, não há como uma extensão receber um pedido de fala e decidir dinamicamente se vai processá-lo.

Tipos

AudioBuffer

Chrome 92 e versões mais recentes

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. O comprimento precisa ser exatamente audioStreamOptions.bufferSize e codificado como mono, em audioStreamOptions.sampleRate, e como PCM linear, float de 32 bits assinado, ou seja, o tipo Float32Array em JavaScript.

  • charIndex

    número opcional

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

  • isLastBuffer

    booleano opcional

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

AudioStreamOptions

Chrome 92 e versões mais recentes

Contém o formato de stream de áudio esperado para ser produzido por um mecanismo.

Propriedades

  • bufferSize

    number

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

  • sampleRate

    number

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

LanguageInstallStatus

Pendente

O status de instalação de uma voz.

Enumeração

"notInstalled"

"installing"

"installed"

"falha"

LanguageStatus

Pendente

Status de instalação de um idioma.

Propriedades

  • erro

    string opcional

    Detalhes sobre falhas de instalação. Pode ser preenchido se a instalação do idioma falhar.

  • installStatus

    LanguageInstallStatus

    Status da instalação.

  • lang

    string

    String de idioma no formato 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

Pendente

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 vai ou quando vai desinstalar o idioma com base nesse parâmetro e nas informações do solicitante. Se for falso, outros critérios, como o uso recente, podem ser usados para determinar quando desinstalar.

SpeakOptions

Chrome 92 e versões mais recentes

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

Propriedades

  • gênero

    VoiceGender opcional

    Suspensa 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 opcional

    Tom de fala entre 0 e 2, sendo 0 o mais baixo e 2 o mais alto. 1,0 corresponde ao tom padrão dessa voz.

  • taxa

    número opcional

    Taxa de fala em relação à taxa padrão dessa voz. 1,0 é a taxa padrão, normalmente entre 180 e 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. Quando uma voz não oferece suporte a toda a faixa de taxas, não retorne um erro. Em vez disso, corte a taxa para o intervalo aceito pela voz.

  • voiceName

    string opcional

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

  • volume

    número opcional

    Volume de fala entre 0 e 1, sendo 0 o menor e 1 o maior, com um padrão de 1,0.

TtsClient

Chrome 131 e versões mais recentes

Identificador do cliente que solicita o status.

Propriedades

  • id

    string

    Cliente fazendo 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 do recurso.

  • Tipo de solicitante.

TtsClientSource

Chrome 131 e versões mais recentes

Tipo de solicitante.

Enumeração

"chromefeature"

"extension"

VoiceGender

Chrome 54 e versões mais recentes Descontinuado no Chrome 70

O gênero foi descontinuado e será ignorado.

Enumeração

"male"

"female"

Métodos

updateLanguage()

Pendente
chrome.ttsEngine.updateLanguage(
  status: LanguageStatus,
)

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[],
)

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

Eventos

onInstallLanguageRequest

Chrome 131 e versões mais recentes 
chrome.ttsEngine.onInstallLanguageRequest.addListener(
  callback: function,
)

É acionado quando um cliente de TTS solicita a instalação de um novo idioma. O mecanismo precisa tentar fazer o download e a instalação do idioma e chamar ttsEngine.updateLanguage com o resultado. Se for bem-sucedido, o mecanismo também precisará chamar ttsEngine.updateVoices para registrar as vozes recém-disponíveis.

Parâmetros

  • callback

    função

    O parâmetro callback tem este formato: 

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

onLanguageStatusRequest

Pendente
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 tem este formato: 

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

onPause

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

Opcional: se um mecanismo oferecer suporte ao 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 tem este formato: 

    () => void

onResume

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

Opcional: se um mecanismo oferecer suporte ao evento de pausa, ele também precisará oferecer suporte ao evento de retomada para continuar a falar 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 tem este formato: 

    () => 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 tem este formato: 

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

    • enunciado

      string

    • opções

      SpeakOptions

    • sendTtsEvent

      função

      O parâmetro sendTtsEvent tem este formato: 

      (event: tts.TtsEvent) => void

      • evento

        tts.TtsEvent

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

onSpeakWithAudioStream

Chrome 92 e versões mais recentes 
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 tem este formato: 

    (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 tem este formato: 

      (audioBufferParams: AudioBuffer) => void

      • audioBufferParams

        AudioBuffer

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

    • sendError

      função

      Chrome 94 e versões mais recentes

      O parâmetro sendError tem este formato: 

      (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 essa 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 fará nada (não gerará um erro). Se a fala estiver pausada, isso vai cancelar o estado de pausa.

Parâmetros

  • callback

    função

    O parâmetro callback tem este formato: 

    () => void

onUninstallLanguageRequest

Pendente
chrome.ttsEngine.onUninstallLanguageRequest.addListener(
  callback: function,
)

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

Parâmetros