chrome.tts

Descrição

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

O Chrome oferece esse recurso 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.

Permissões

tts

Conceitos e uso

Gerar voz

Para falar, ligue para speak() usando sua extensão. Exemplo:

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

Para parar de falar imediatamente, basta chamar stop():

chrome.tts.stop();

Você pode fornecer opções que controlam várias propriedades da fala, como velocidade, tom, entre outras. Exemplo:

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

Também é uma boa ideia especificar o idioma para que um sintetizador que ofereça suporte a ele seja escolhido (e um dialeto regional, se aplicável).

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 alguma coisa, chame isSpeaking(). Além disso, é possível usar a opção enqueue para fazer com que essa fala seja adicionada a uma fila de falas que serão faladas quando a fala atual terminar.

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 em tts.speak(). Nem todos os mecanismos de fala aceitam 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. Dentro do callback, verifique runtime.lastError para ver se há 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 fala. O objetivo do callback é alertar você sobre erros de sintaxe no uso da API TTS, não para capturar todos os erros possíveis que podem ocorrer no processo de síntese e saída de fala. Para detectar esses erros também, você precisa usar um listener de eventos, descrito na próxima seção.

Ouvir 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 ao enunciado e, para eventos de erro, uma mensagem de erro opcional. Os tipos de evento são:

  • 'start': o mecanismo começou a gerar a fala.
  • 'word': um limite de palavras foi atingido. Use event.charIndex para determinar a posição da fala atual.
  • 'sentence': o limite de uma frase foi atingido. Use event.charIndex para determinar a posição da fala atual.
  • 'marker': um marcador SSML foi atingido. Use event.charIndex para determinar a posição da fala atual.
  • 'end': o mecanismo terminou de falar a fala.
  • '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 cancelada por outra chamada para speak() ou stop(), e nunca começou a ser falada.
  • 'error': ocorreu um erro específico do mecanismo, e essa expressão não pode ser falada. Confira event.errorMessage para mais detalhes.

Quatro dos tipos de evento ('end', 'interrupted', 'cancelled' e 'error') são final. Depois que um desses eventos for recebido, esse enunciado não será mais falado, e nenhum evento novo dele será recebido.

Algumas vozes podem não ser compatíveis com todos os tipos de evento e outras podem não enviar eventos. 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 são descritos a seguir.

Marcação SSML

As enunciados usados nessa API podem incluir marcação 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() precisará 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. No entanto, todos os mecanismos são obrigados a ignorar qualquer SSML não compatível e continuar falando o texto subjacente.

Escolher uma voz

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

Para conferir uma lista de todas as vozes, chame getVoices() e transmita uma função que recebe 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

Tipo enumerado

TtsEvent

Um evento do mecanismo TTS para comunicar o status de um enunciado.

Propriedades

  • charIndex

    número opcional

    O índice do caractere atual na fala. Para eventos de palavras, o evento é disparado 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.

  • length

    número opcional

    Chrome 74 ou mais recente

    O comprimento 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 poderá ser start assim que a fala for iniciada, word quando o limite de palavras for atingido, sentence quando o limite de uma frase é atingido, marker quando um elemento de marca SSML é alcançado, end quando o fim da fala é alcançado, interrupted quando a fala é interrompida ou interrompida antes de chegar ao fim, cancelled quando ela é removida da fila antes de ser sintetizada ou error quando ocorre qualquer outro erro. Ao pausar a fala, um evento pause será disparado se uma fala específica for pausada no meio, e resume se uma fala retomar a fala. Os eventos de pausa e retomada podem não ser acionados se a fala for pausada entre os enunciados.

TtsOptions

Chrome 77 ou mais recente

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

Propriedades

  • desiredEventTypes

    string[] opcional

    Os tipos de eventos de TTS que você quer ouvir. Se não definido, todos os tipos de evento podem ser enviados.

  • enfileirar

    booleano opcional

    Se verdadeiro, enfileira essa fala se o 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 fala.

  • extensionId

    string opcional

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

  • gender

    VoiceGender opcional

    Descontinuado desde o Chrome 77

    O gênero foi descontinuado e será ignorado.

    Gênero de voz para fala sintetizada.

  • lang

    string opcional

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

  • pitch

    número opcional

    Abordagem falado entre 0 e 2, incluindo 0, o mais baixo e 2, o mais alto. 1,0 corresponde ao tom padrão de uma voz.

  • taxa

    número opcional

    Taxa de fala em relação à taxa padrão desta 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 com suporte ao recurso de voz.

  • voiceName

    string opcional

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

  • volume

    número opcional

    O volume da fala varia entre 0 e 1, sendo 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 fala do enunciado.

    A função onEvent tem esta aparência: 

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

    • event

      TtsEvent

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

TtsVoice

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

Propriedades

  • eventTypes

    EventType[] opcional

    Todos os tipos de evento de callback que essa voz é capaz de enviar.

  • extensionId

    string opcional

    O ID da extensão que fornece essa voz.

  • gender

    VoiceGender opcional

    Descontinuado desde o Chrome 70

    O gênero foi descontinuado e será ignorado.

    O gênero desta voz.

  • lang

    string opcional

    O idioma aceito por essa voz, no formato idioma-região. Exemplos: "en", "en-US", "en-GB", "zh-CN".

  • controle remoto

    booleano opcional

    Se 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 ou mais recente Descontinuado desde o Chrome 70

O gênero foi descontinuado e ignorado.

Tipo enumerado

Métodos

getVoices()

Promessa 
chrome.tts.getVoices(
  callback?: function,
)

Recebe uma matriz de todas as vozes disponíveis.

Parâmetros

  • callback

    função optional

    O parâmetro callback tem esta aparência: 

    (voices: TtsVoice[])=>void

    • vozes

      TtsVoice[]

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

Retorna

  • Promise<TtsVoice[]>

    Chrome 101 e mais recentes

    Promessas são compatíveis com o Manifest V3 e versões mais recentes, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo que é passado para o callback.

isSpeaking()

Promessa 
chrome.tts.isSpeaking(
  callback?: function,
)

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

    (speaking: boolean)=>void

    • falando

      boolean

      Verdadeiro se falar. Caso contrário, será falso.

Retorna

  • Promise<boolean>

    Chrome 101 e mais recentes

    Promessas são compatíveis com o Manifest V3 e versões mais recentes, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo que é passado para o callback.

pause()

chrome.tts.pause()

Pausa a síntese de fala, potencialmente no meio de um enunciado. Ao retomar ou interromper uma chamada, a fala será retomada.

resume()

chrome.tts.resume()

Se a fala foi pausada, continua falando de onde parou.

speak()

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

Fala o texto usando um mecanismo de conversão de texto em voz.

Parâmetros

  • enunciado

    string

    O texto a ser falado, em texto simples ou um documento SSML completo e bem formado. Mecanismos de fala que não são compatíveis com SSML removem as tags e falam o texto. O tamanho máximo do texto é de 32.768 caracteres.

  • do modelo.

    TtsOptions opcional

    Opções de fala.

  • callback

    função optional

    O parâmetro callback tem esta aparência: 

    ()=>void

Retorna

  • Promise<void>

    Chrome 101 e mais recentes

    Promessas são compatíveis com o Manifest V3 e versões mais recentes, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo que é passado para o callback.

stop()

chrome.tts.stop()

Interrompe todas as falas atuais e limpa a fila de falas pendentes. Além disso, se a fala tiver sido pausada, ela será retomada para a próxima chamada.

Eventos

onVoicesChanged

Chrome 124 ou mais recente 
chrome.tts.onVoicesChanged.addListener(
  callback: function,
)

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

Parâmetros

  • callback

    função

    O parâmetro callback tem esta aparência: 

    ()=>void