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.
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 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 tts.speak
abaixo. 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 abaixo.
Detectar 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. Useevent.charIndex
para determinar a posição da fala atual.'sentence'
: o limite de uma frase foi atingido. Useevent.charIndex
para determinar a posição da fala atual.'marker'
: um marcador SSML foi atingido. Useevent.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 paraspeak()
oustop()
e não foi concluída.'cancelled'
: essa fala foi colocada na fila, mas cancelada por outra chamada paraspeak()
oustop()
, e nunca começou a ser falada.'error'
: ocorreu um erro específico do mecanismo, e essa expressão não pode ser falada. Confiraevent.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. Ambas estão documentadas abaixo.
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.
Como 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
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 recenteO 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
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 ouerror
quando ocorre qualquer outro erro. Ao pausar a fala, um eventopause
será disparado se uma fala específica for pausada no meio, eresume
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
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 77O 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
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 70O 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
O gênero foi descontinuado e ignorado.
Tipo enumerado
Métodos
getVoices()
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 recentesPromessas são compatíveis apenas com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.
isSpeaking()
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 recentesPromessas são compatíveis apenas com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.
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()
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 recentesPromessas são compatíveis apenas com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.
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.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