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 expressão a ser falada 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, além de enviar eventos de volta para a função de chamada e informar o status.

Permissões

ttsEngine

Conceitos e uso

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 áudio de streaming de um servidor, áudio HTML5. Uma extensão pode até fazer algo diferente com as frases, como mostrar legendas descritivas em um pop-up ou enviá-las como mensagens de registro para um servidor remoto.

Para implementar um mecanismo de TTS, uma extensão precisa declarar a permissão "ttsEngine" e todas as vozes que ela oferece no manifesto da extensão, assim:

{
  "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 consegue sintetizar a fala em apenas um idioma. Quando um mecanismo é compatível com mais de um idioma, ele pode registrar uma voz separada para cada um deles. 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 frases em qualquer idioma, deixe de fora 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. É altamente recomendável oferecer suporte ao tipo de evento 'end' para indicar quando a fala termina. Caso contrário, o Chrome não poderá programar as frases enfileiradas.

Depois de carregada, uma extensão pode substituir a lista de vozes declaradas chamando chrome.ttsEngine.updateVoices. Observe que 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 que o método speak() recebe:

  • 'start': o mecanismo começou a falar a expressão.
  • '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 a frase.
  • 'error': ocorreu um erro específico do mecanismo, e a expressão não pode ser falada. 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, supondo que você tenha registrado listeners de eventos de fala conforme descrito abaixo.

Processar eventos de fala

Para gerar fala 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 se baseia apenas em se a extensão oferece suporte aos parâmetros de voz especificados no manifesto e se registrou listeners 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 ou mais recente

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 o comprimento exato audioStreamOptions.bufferSize e ser codificado como mono, em audioStreamOptions.sampleRate e como pcm linear, ponto flutuante de 32 bits com sinal, 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 este buffer de áudio for o último do texto que está sendo falado.

AudioStreamOptions

Chrome 92 ou mais recente

Contém o formato de stream de áudio esperado para 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 ou mais recente

O status de instalação de uma voz.

Enumeração

"notInstalled"

"instalando"

"instalado"

"falhou"

LanguageStatus

Chrome 132 ou mais recente

Status de instalação de um idioma.

Propriedades

  • erro

    string opcional

    Detalhes sobre falhas de instalação. Preenchido opcionalmente se a instalação do idioma falhar.

  • installStatus

    LanguageInstallStatus

    Status da instalação.

  • lang

    string

    String de idioma no formato código de idioma-código de região, em que a região pode ser omitida. Por exemplo: en, en-AU, zh-CH.

LanguageUninstallOptions

Chrome 132 ou mais recente

Opções para desinstalar um idioma específico.

Propriedades

  • uninstallImmediately

    booleano

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

SpeakOptions

Chrome 92 ou mais recente

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

Propriedades

  • gênero

    VoiceGender opcional

    Suspensas 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 voz entre 0 e 2, sendo 0 o mais baixo e 2 o mais alto. 1,0 corresponde à entonação padrão dessa voz.

  • taxa

    número optional

    Taxa de fala relativa à 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 fica entre 0,1 e 10,0, inclusive. Quando uma voz não for compatível com toda essa variedade de taxas, não retorne um erro. Em vez disso, corte a taxa para o intervalo compatível com a voz.

  • voiceName

    string opcional

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

  • volume

    número optional

    Volume da fala entre 0 e 1, sendo 0 o mais baixo e 1 o mais alto, com um padrão de 1,0.

TtsClient

Chrome 131 ou mais recente

Identificador do cliente que está solicitando o status.

Propriedades

  • ID

    string

    Cliente fazendo uma solicitação de gerenciamento de idiomas. 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 ou mais recente

Tipo de solicitante.

Enumeração

"chromefeature"

"extension"

VoiceGender

Chrome 54 ou mais recente Suspensas desde o Chrome 70

O gênero foi descontinuado e será ignorado.

Enumeração

"male"

"female"

Métodos

updateLanguage()

Chrome 132 ou mais recente 
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 ou mais recente 
chrome.ttsEngine.onInstallLanguageRequest.addListener(
  callback: function,
)

Disparado quando um cliente de TTS solicita a instalação de um novo idioma. O mecanismo precisa tentar baixar e instalar o idioma e chamar ttsEngine.updateLanguage com o resultado. Se a operação for bem-sucedida, o mecanismo também vai chamar ttsEngine.updateVoices para registrar as vozes recém-disponibilizadas.

Parâmetros

  • callback

    função

    O parâmetro callback tem esta aparência: 

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

onLanguageStatusRequest

Chrome 132 ou mais recente 
chrome.ttsEngine.onLanguageStatusRequest.addListener(
  callback: function,
)

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

Parâmetros

  • callback

    função

    O parâmetro callback tem esta aparência: 

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

onPause

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

Opcional: se um mecanismo oferecer suporte ao evento de pausa, ele deverá pausar a declaração atual que está sendo falada, se houver, até receber um evento de retomada ou de interrupção. Um evento de parada também deve limpar o estado pausado.

Parâmetros

  • callback

    função

    O parâmetro callback tem esta aparência: 

    () => void

onResume

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

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

Parâmetros

  • callback

    função

    O parâmetro callback tem esta aparência: 

    () => 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 esta aparência: 

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

    • enunciado

      string

    • opções

      SpeakOptions

    • sendTtsEvent

      função

      O parâmetro sendTtsEvent tem esta aparência: 

      (event: tts.TtsEvent) => void

      • evento

        tts.TtsEvent

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

onSpeakWithAudioStream

Chrome 92 ou mais recente 
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. Diferente de ttsEngine.onSpeak, em que o Chrome oferece 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 esta aparência: 

    (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 esta aparência: 

      (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 tem esta aparência: 

      (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 deve fazer 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 esta aparência: 

    () => void

onUninstallLanguageRequest

Chrome 132 ou mais recente 
chrome.ttsEngine.onUninstallLanguageRequest.addListener(
  callback: function,
)

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

Parâmetros