chrome.tts

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() usando sua extensão para falar. Exemplo:

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

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

chrome.tts.stop();

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

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

Também é uma boa ideia especificar o idioma de modo que um sintetizador que ofereça suporte a ele (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 estaria interrompendo alguma coisa, você pode chamar isSpeaking(). Além disso, você pode usar a opção enqueue para fazer com que esse enunciado seja adicionado a uma fila de enunciados que ser falado quando o enunciado 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 no tts.speak abaixo. Nem toda fala mecanismos 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 aceita argumentos. Dentro do callback, confira se há algum em runtime.lastError. erros.

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 voz. O objetivo callback é alertar sobre erros de sintaxe ao usar a API TTS, não para capturar todas as informações erros que podem ocorrer no processo de síntese e produção de voz. Para detectar esses erros também, você precisa usar um listener de eventos, descrito abaixo.

Como detectar eventos

Para obter mais informações em tempo real sobre o status da fala sintetizada, transmita um listener de evento as opções para speak(), da seguinte 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 falar o enunciado.
  • 'word': um limite de palavras foi atingido. Usar event.charIndex para determinar a fala atual posição
  • 'sentence': um limite de frases foi atingido. Use event.charIndex para determinar o na posição da fala.
  • 'marker': um marcador SSML foi atingido. Usar event.charIndex para determinar a fala atual posição
  • 'end': o mecanismo terminou de falar o enunciado.
  • 'interrupted': este enunciado foi interrompido por outra chamada para speak() ou stop() e não terminar.
  • 'cancelled': este enunciado foi colocado na fila e cancelado por outra chamada para speak() ou stop() e nunca começou a falar.
  • 'error': ocorreu um erro específico do mecanismo, e este enunciado não pode ser falado. Marca de seleção event.errorMessage para mais detalhes.

Quatro dos tipos de evento ('end', 'interrupted', 'cancelled' e 'error') são finais. Depois um desses eventos for recebido, esse enunciado não falará mais nem novos eventos deste falada será recebida.

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 certos eventos, passe os eventos que você precisa na requiredEventTypes membro do objeto de opções ou use getVoices() para escolher uma voz que atenda de acordo com seus requisitos. Ambas estão documentadas abaixo.

Marcação SSML

Os enunciados usados nesta API podem incluir marcação usando a Linguagem de marcação de síntese de fala (SSML). Se você usar SSML, o primeiro argumento para speak() deverá 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 oferecem suporte a todas as tags SSML, e alguns podem não oferecer suporte a SSML, mas todas os mecanismos precisam ignorar qualquer SSML que não sejam compatíveis e ainda assim comunicar o texto subjacente.

Como escolher uma voz

Por padrão, o Chrome escolhe a voz mais apropriada para cada expressão que você quer falar, com base nos do idioma. Na maioria dos sistemas Windows, Mac OS X e ChromeOS, a síntese de fala é fornecida pelo sistema operacional deve ser capaz de falar qualquer texto em pelo menos um idioma. Alguns usuários podem ter de vozes disponíveis, no entanto, a partir do sistema operacional e dos mecanismos de fala implementados por outras extensões do Chrome. Nesses casos, você pode implementar código personalizado para escolher os voz, 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 superior

Enumeração

"início"

"final"

"palavra"

"sentence"

"marcador"

"interrompido"

"cancelado"

"erro"

"pausar"

"retomar"

TtsEvent

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

Propriedades

  • charIndex

    número opcional

    O índice do caractere atual no enunciado. 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 início da palavra seguinte no texto.

  • errorMessage

    string opcional

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

  • comprimento

    número opcional

    Chrome 74 ou superior

    O tamanho da próxima parte do enunciado. 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çar, word quando um limite de palavras for atingido, sentence quando um limite de frases for atingido, marker quando um elemento de marca SSML for atingido, end quando o final da fala for atingido, interrupted quando o enunciado for interrompido ou interrompido antes de chegar ao fim, cancelled quando ele for removido da fila antes de ser sintetizado ou error quando qualquer outro erro ocorrer. Ao pausar a fala, um evento pause é acionado quando um enunciado específico é pausado no meio e resume quando ele retoma a fala. Os eventos de pausa e retomada poderão não ser acionados se a fala for pausada entre as falas.

TtsOptions

Chrome 77 ou superior

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

Propriedades

  • desiredEventTypes

    string[] opcional

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

  • colocar na fila

    booleano opcional

    Se verdadeiro, enfileira essa expressão 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 esse novo enunciado.

  • extensionId

    string opcional

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

  • gênero

    VoiceGender opcional

    Descontinuado desde o Chrome 77

    O uso do 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 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 menor e 2 o mais alto. 1,0 corresponde ao tom padrão de uma voz.

  • taxa

    número opcional

    Velocidade da fala em relação à taxa padrão para esta 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 não são permitidos, 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.

  • requiredEventTypes

    string[] opcional

    Os tipos de evento de TTS a que a voz precisa oferecer suporte.

  • voiceName

    string opcional

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

  • volume

    número opcional

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

  • onEvent

    void opcional

    Essa função é chamada com eventos que ocorrem no processo de fala do enunciado.

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

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

    • evento

      TtsEvent

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

TtsVoice

A 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 pode enviar.

  • extensionId

    string opcional

    O ID do ramal que fornece essa voz.

  • gênero

    VoiceGender opcional

    Descontinuado desde o Chrome 70

    O uso do gênero foi descontinuado e será ignorado.

    O gênero desta 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 verdadeiro, o mecanismo de síntese é um recurso de rede remota. Pode ser maior latência e incorrer em custos de largura de banda.

  • voiceName

    string opcional

    Nome da voz.

VoiceGender

Chrome 54 ou superior Descontinuado desde o Chrome 70

O uso do gênero foi descontinuado e ignorado.

Enumeração

"masculino"

"feminino"

Métodos

getVoices()

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

Recebe uma matriz de todas as vozes disponíveis.

Parâmetros

  • callback

    função opcional

    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&lt;TtsVoice[]&gt;

    Chrome 101 ou versões mais recentes

    As promessas só têm suporte no Manifesto V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

isSpeaking()

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

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

Parâmetros

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    (speaking: boolean) => void

    • falar

      booleano

      Verdadeiro em caso de fala; caso contrário, é falso.

Retorna

  • Promise&lt;boolean&gt;

    Chrome 101 ou versões mais recentes

    As promessas só têm suporte no Manifesto V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

pause()

chrome.tts.pause()

Pausa a síntese de fala, possivelmente no meio de um enunciado. Uma chamada para retomar ou parar retomar a fala.

resume()

chrome.tts.resume()

Se a fala tiver sido pausada, retoma a fala 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, seja em texto simples ou um documento SSML completo e bem formado. Os mecanismos de fala que não são compatíveis com SSML removerão as tags e falarão o texto. O tamanho máximo do texto é de 32.768 caracteres.

  • opções

    TtsOptions opcional

    Opções de fala.

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    () => void

Retorna

  • Promessa<void>

    Chrome 101 ou versões mais recentes

    As promessas só têm suporte no Manifesto V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

stop()

chrome.tts.stop()

Interrompe qualquer fala atual e limpa a fila de enunciados pendentes. Além disso, se a fala tiver sido pausada, ela será retomada para a próxima ligação.

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