Linguagem de marcação de síntese de voz (SSML)

Pode enviar Linguagem de marcação de síntese de voz (SSML) no seu pedido de conversão de texto em voz para permitir uma maior personalização na sua resposta de áudio, fornecendo detalhes sobre pausas e formatação de áudio para acrónimos, datas, horas, abreviaturas ou texto que deve ser censurado. Consulte o tutorial de SSML de conversão de texto em voz para ver mais informações e exemplos de código.

O exemplo seguinte mostra uma marcação SSML e a conversão de texto em voz sintetiza o texto:

<speak>
  Here are <say-as interpret-as="characters">SSML</say-as> samples.
  I can pause <break time="3s"/>.
  I can play a sound
  <audio src="https://www.example.com/MY_MP3_FILE.mp3">didn't get your MP3 audio file</audio>.
  I can speak in cardinals. Your number is <say-as interpret-as="cardinal">10</say-as>.
  Or I can speak in ordinals. You are <say-as interpret-as="ordinal">10</say-as> in line.
  Or I can even speak in digits. The digits for ten are <say-as interpret-as="characters">10</say-as>.
  I can also substitute phrases, like the <sub alias="World Wide Web Consortium">W3C</sub>.
  Finally, I can speak a paragraph with two sentences.
  <p><s>This is sentence one.</s><s>This is sentence two.</s></p>
</speak>

Segue-se o texto sintetizado para o documento SSML de exemplo:

Here are S S M L samples. I can pause [3 second pause]. I can play a sound [audio file plays].
I can speak in cardinals. Your number is ten.
Or I can speak in ordinals. You are tenth in line.
Or I can even speak in digits. The digits for ten are one oh.
I can also substitute phrases, like the World Wide Web Consortium.
Finally, I can speak a paragraph with two sentences. This is sentence one. This is sentence two.

A conversão de texto em voz suporta um subconjunto das etiquetas SSML disponíveis, que são descritas neste tópico.

Para mais informações sobre como criar dados de áudio a partir de entrada SSML com a API Text-to-Speech, consulte o artigo Criar ficheiros de áudio de voz.

Sugestões para usar SSML

Consoante a sua implementação, pode ter de usar carateres de escape em aspas ou citações na carga útil SSML que envia para a funcionalidade de conversão de texto em voz. O exemplo seguinte mostra como formatar a entrada SSML incluída num objeto JSON.

"{
    'input':{
     'ssml':'<speak>The <say-as interpret-as=\"characters\">SSML</say-as>
          standard <break time=\"1s\"/>is defined by the
          <sub alias=\"World Wide Web Consortium\">W3C</sub>.</speak>'
    },
    'voice':{
      'languageCode':'en-us',
      'name':'en-US-Standard-B',
      'ssmlGender':'MALE'
    },
    'audioConfig':{
      'audioEncoding':'MP3'
    }
  }"

Reserve carateres

Evite usar carateres reservados SSML no texto a converter em áudio. Quando precisar de usar um caráter reservado de SSML, impeça que o caráter seja lido como código usando o respetivo código de escape. A tabela seguinte mostra os carateres SSML reservados e os respetivos códigos de escape associados.

Personagem Código de escape
" &quot;
& &amp;
. &apos;
< &lt;
> &gt;

Selecione uma voz

Pode definir a voz no objeto VoiceSelectionParams. Consulte o tutorial de SSML de conversão de texto em voz para ver um exemplo de código que demonstra a utilização do objeto VoiceSelectionParams.

Pode usar a etiqueta <voice> para ler SSML em várias vozes, mas tem de definir o nome VoiceSelectionParams para uma voz compatível:

Tipo de voz pedido Tipo de voz suportado na etiqueta <voice>
Neural2 Studio Wavenet Notícias Standard
Neural2 ✔ ✔ ✔
Studio ✔ ✔ ✔
Wavenet ✔ ✔ ✔
Standard ✔ ✔ ✔
Notícias ✔ ✔ ✔

Suporte para elementos SSML

As secções seguintes descrevem os elementos e as opções de SSML que podem ser usados nas suas ações.

<speak>

O elemento raiz da resposta SSML.

Para saber mais acerca do elemento speak, consulte a especificação da W3.

Exemplo

<speak>
  my SSML content
</speak>

<break>

Um elemento vazio que controla a pausa ou outros limites prosódicos entre palavras. A utilização de <break> entre qualquer par de tokens é opcional. Se este elemento não estiver presente entre palavras, a pausa é determinada automaticamente com base no contexto linguístico.

Para saber mais acerca do elemento break, consulte a especificação da W3.

Atributos

Atributo Descrição
time

Define a duração da pausa em segundos ou milissegundos (por exemplo, "3s" ou "250ms").
strength

Define a intensidade da pausa prosódica da saída por termos relativos. Os valores válidos são: "x-weak", "weak", "medium", "strong" e "x-strong". O valor "none" indica que não deve ser emitida nenhuma fronteira de pausa prosódica, o que pode ser usado para evitar uma pausa prosódica que o processador produziria de outra forma. Os outros valores indicam uma força de quebra monotonicamente não decrescente (conceitualmente crescente) entre os tokens. Normalmente, os limites mais fortes são acompanhados de pausas.

Exemplo

O exemplo seguinte mostra como usar o elemento <break> para pausar entre passos:

<speak>
  Step 1, take a deep breath. <break time="200ms"/>
  Step 2, exhale.
  Step 3, take a deep breath again. <break strength="weak"/>
  Step 4, exhale.
</speak>

<say‑as>

Este elemento permite-lhe indicar informações sobre o tipo de construção de texto contido no elemento. Também ajuda a especificar o nível de detalhe para a renderização do texto contido.

O elemento <say‑as> tem o atributo obrigatório interpret-as, que determina como o valor é falado. Os atributos opcionais format e detail podem ser usados consoante o valor interpret-as específico.

Exemplos

O atributo interpret-as suporta os seguintes valores:

  • currency

    O exemplo seguinte é dito como "quarenta e dois dólares e um cêntimo". Se o atributo de idioma for omitido, usa o local atual.

    <speak>
  <say-as interpret-as='currency' language='en-US'>$42.01</say-as>
</speak>
  • telephone

    Consulte a interpret-as='telephone'descrição nas notas do WG sobre os valores do atributo say-as da SSML 1.0 da W3C.

    O exemplo seguinte é dito como "um oito zero zero dois zero dois um dois um dois". Se o atributo "google:style" for omitido, o número zero é pronunciado como a letra O.

    Atualmente, o atributo "google:style='zero-as-zero'" só funciona em localizações EN.

          <speak>
        <say-as interpret-as='telephone' google:style='zero-as-zero'>1800-202-1212</say-as>
      </speak>
  • verbatim ou spell-out

    O exemplo seguinte é escrito letra a letra:

    <speak>
  <say-as interpret-as="verbatim">abcdefg</say-as>
</speak>
  • date

    O atributo format é uma sequência de códigos de carateres de campo de data. Os códigos de carateres de campos suportados em format são {y, m, d} para o ano, o mês e o dia (do mês), respetivamente. Se o código do campo aparecer uma vez para o ano, o mês ou o dia, o número de dígitos esperado é 4, 2 e 2, respetivamente. Se o código de campo for repetido, o número de dígitos esperado é o número de vezes que o código é repetido. Os campos no texto de data podem ser separados por pontuação e/ou espaços.

    O atributo detail controla a forma falada da data. Para detail='1', apenas os campos de dia e um dos campos de mês ou ano são obrigatórios, embora ambos possam ser fornecidos. Esta é a predefinição quando são fornecidos menos de três campos. A forma falada é "{ordinal day} de {month} de {year}".

    O exemplo seguinte é dito como "Dez de setembro de mil novecentos e sessenta":

    <speak>
  <say-as interpret-as="date" format="yyyymmdd" detail="1">
    1960-09-10
  </say-as>
</speak>

    O exemplo seguinte é dito como "The tenth of September" (O décimo de setembro):

    <speak>
  <say-as interpret-as="date" format="dm">10-9</say-as>
</speak>

    Para detail='2' os campos de dia, mês e ano são obrigatórios e esta é a predefinição quando todos os três campos são fornecidos. A forma falada é "{month} {ordinal day}, {year}".

    O exemplo seguinte é dito como "dez de setembro de mil novecentos e sessenta":

    <speak>
  <say-as interpret-as="date" format="dmy" detail="2">
    10-9-1960
  </say-as>
</speak>
  • characters

    O exemplo seguinte é dito como "C A N":

    <speak>
  <say-as interpret-as="characters">can</say-as>
</speak>
  • cardinal

    O exemplo seguinte é falado como "Twelve thousand three hundred forty five" (para inglês dos EUA) ou "Twelve thousand three hundred and forty five (para inglês do Reino Unido)":

    <speak>
  <say-as interpret-as="cardinal">12345</say-as>
</speak>
  • ordinal

    O exemplo seguinte é dito como "Primeiro":

    <speak>
  <say-as interpret-as="ordinal">1</say-as>
</speak>
  • fraction

    O exemplo seguinte é dito como "cinco e meio":

    <speak>
  <say-as interpret-as="fraction">5+1/2</say-as>
</speak>
  • expletive ou bleep

    O exemplo seguinte é apresentado como um sinal sonoro, como se tivesse sido censurado:

    <speak>
  <say-as interpret-as="expletive">censor this</say-as>
</speak>
  • unit

    Converte unidades para singular ou plural, consoante o número. O exemplo seguinte é dito como "10 pés":

    <speak>
  <say-as interpret-as="unit">10 foot</say-as>
</speak>
  • time

    O exemplo seguinte é dito como "Duas e trinta da tarde":

    <speak>
  <say-as interpret-as="time" format="hms12">2:30pm</say-as>
</speak>

    O atributo format é uma sequência de códigos de carateres de campo de tempo. Os códigos de carateres de campo suportados em format são {h,m, s, Z, 12, 24} para hora, minuto (da hora), segundo (do minuto), fuso horário, hora de 12 horas e hora de 24 horas, respetivamente. Se o código do campo aparecer uma vez para a hora, o minuto ou o segundo, o número de dígitos esperado é 1, 2 e 2, respetivamente. Se o código de campo for repetido, o número de dígitos esperado é o número de vezes que o código é repetido. Os campos no texto de tempo podem ser separados por pontuação e/ou espaços. Se a hora, os minutos ou os segundos não forem especificados no formato ou não existirem dígitos correspondentes, o campo é tratado como um valor zero. O valor predefinido format é "hms12".

    O atributo detail controla se a forma falada da hora é de 12 ou 24 horas. A forma falada é a hora no formato de 24 horas se detail='1' ou se detail for omitido e o formato da hora for de 24 horas. A forma falada é a hora no formato de 12 horas se detail='2' ou se detail for omitido e o formato da hora for de 12 horas.

Para saber mais acerca do elemento say-as, consulte a especificação da W3.

<audio>

Suporta a inserção de ficheiros de áudio gravados e a inserção de outros formatos de áudio em conjunto com a saída de voz sintetizada.

Atributos

Atributo Obrigatória Predefinição Valores
src sim N/A Um URI que faz referência à origem de multimédia de áudio. O protocolo suportado é https.
clipBegin não 0 Um TimeDesignation que é o desvio do início da fonte de áudio a partir do qual se inicia a reprodução. Se este valor for igual ou superior à duração real da fonte de áudio, não é inserido áudio.
clipEnd não infinito Uma TimeDesignation que é o desvio do início da fonte de áudio para terminar a reprodução. Se a duração real da fonte de áudio for inferior a este valor, a reprodução termina nesse momento. Se clipBegin for superior ou igual a clipEnd, não é inserido áudio.
speed não 100% A taxa de reprodução de saída relativa à taxa de entrada normal expressa como uma percentagem. O formato é um número real positivo seguido de %. O intervalo atualmente suportado é [50% (lento – metade da velocidade), 200% (rápido – o dobro da velocidade)]. Os valores fora desse intervalo podem (ou não) ser ajustados para estarem dentro do mesmo.
repeatCount não 1 ou 10 se repeatDur estiver definido Um número real que especifica quantas vezes inserir o áudio (após o corte, se existir, por clipBegin e/ou clipEnd). As repetições fracionárias não são suportadas, pelo que o valor é arredondado para o número inteiro mais próximo. Zero não é um valor válido e, por isso, é tratado como não especificado e tem o valor predefinido nesse caso.
repeatDur não infinito Um TimeDesignation que é um limite na duração do áudio inserido após o processamento da origem para os atributos clipBegin, clipEnd, repeatCount e speed (em vez da duração de reprodução normal). Se a duração do áudio processado for inferior a este valor, a reprodução termina nesse momento.
soundLevel não +0dB Ajuste o nível de som do áudio em soundLevel decibéis. O intervalo máximo é de +/-40 dB, mas o intervalo real pode ser efetivamente inferior e a qualidade da saída pode não produzir bons resultados em todo o intervalo.

Seguem-se as definições atualmente suportadas para áudio:

  • Formato: MP3 (MPEG v2)
    • 24 mil amostras por segundo
    • 24 K ~ 96 K bits por segundo, taxa fixa
  • Formato: Opus em Ogg
    • 24 mil amostras por segundo (banda ultralarga)
    • 24 K a 96 K bits por segundo, taxa fixa
  • Formato (descontinuado): WAV (RIFF)
    • PCM de 16 bits assinado, little endian
    • 24 mil amostras por segundo
  • Para todos os formatos:
    • É preferível um único canal, mas o estéreo é aceitável.
    • Duração máxima de 240 segundos. Se quiser reproduzir áudio com uma duração mais longa, considere implementar uma resposta multimédia.
    • Limite de tamanho do ficheiro de 5 megabytes.
    • O URL de origem tem de usar o protocolo HTTPS.
    • O nosso UserAgent quando obtém o áudio é "Google-Speech-Actions".

O conteúdo do elemento <audio> é opcional e é usado se o ficheiro de áudio não puder ser reproduzido ou se o dispositivo de saída não suportar áudio. Os conteúdos podem incluir um elemento <desc>, caso em que os conteúdos de texto desse elemento são usados para apresentação. Para mais informações, consulte a secção Áudio gravado na Lista de verificação de respostas.

O URL src também tem de ser um URL HTTPS (o Google Cloud Storage pode alojar os seus ficheiros de áudio num URL HTTPS).

Para saber mais sobre as respostas de multimédia, consulte a secção Resposta de multimédia no guia de respostas.

Para saber mais acerca do elemento audio, consulte a especificação da W3.

Exemplo

<speak>
  <audio src="cat_purr_close.ogg">
    <desc>a cat purring</desc>
    PURR (sound didn't load)
  </audio>
</speak>

<p>,<s>

Elementos de frases e parágrafos.

Para saber mais acerca dos elementos p e s, consulte a especificação da W3.

Exemplo

<p><s>This is sentence one.</s><s>This is sentence two.</s></p>

Práticas recomendadas

  • Use etiquetas <s>...</s> para envolver frases completas, especialmente se contiverem elementos SSML que alterem a prosódia (ou seja, <audio>, <break>, <emphasis>, <par>, <prosody>, <say-as>, <seq> e <sub>).
  • Se uma pausa na fala se destinar a ser suficientemente longa para que a possa ouvir, use etiquetas <s>...</s> e coloque essa pausa entre frases.

<sub>

Indicar que o texto no valor do atributo alias substitui o texto contido para pronúncia.

Também pode usar o elemento sub para fornecer uma pronúncia simplificada de uma palavra difícil de ler. O último exemplo abaixo demonstra este exemplo de utilização em japonês.

Para saber mais acerca do elemento sub, consulte a especificação da W3.

Exemplos

<sub alias="World Wide Web Consortium">W3C</sub>
 
<sub alias="にっぽんばし">日本橋</sub>

<mark>

Um elemento vazio que coloca um marcador na sequência de texto ou de etiquetas. Pode ser usado para fazer referência a uma localização específica na sequência ou para inserir um marcador num fluxo de saída para notificação assíncrona.

Para saber mais acerca do elemento mark, consulte a especificação da W3.

Exemplo

<speak>
Go from <mark name="here"/> here, to <mark name="there"/> there!
</speak>

<prosody>

Usado para personalizar o tom, a velocidade de voz e o volume do texto contido no elemento. Atualmente, os atributos rate, pitch e volume são suportados.

Os atributos rate e volume podem ser definidos de acordo com as especificações da W3. Existem três opções para definir o valor do atributo pitch:

Atributo Descrição
name

O ID de string de cada marca.
Opção Descrição
Família Especifique um valor relativo (por exemplo, "baixo", "médio", "alto", etc.) em que "médio" é o tom predefinido.
Semitons Aumente ou diminua o tom em "N" semitons usando "+Nst" ou "-Nst", respetivamente. Tenha em atenção que "+/-" e "st" são obrigatórios.
Percentagem Aumente ou diminua o tom em "N" por cento usando "+N%" ou "-N%", respetivamente. Tenha em atenção que "%" é obrigatório, mas "+/-" é opcional.

Para saber mais acerca do elemento prosody, consulte a especificação da W3.

Exemplo

O exemplo seguinte usa o elemento <prosody> para falar lentamente a 2 semitons abaixo do normal:

<prosody rate="slow" pitch="-2st">Can you hear me now?</prosody>

<emphasis>

Usado para adicionar ou remover ênfase do texto contido no elemento. O elemento <emphasis> modifica a voz de forma semelhante a <prosody>, mas sem a necessidade de definir atributos de voz individuais.

Este elemento suporta um atributo "level" opcional com os seguintes valores válidos:

  • strong
  • moderate
  • none
  • reduced

Para saber mais acerca do elemento emphasis, consulte a especificação da W3.

Exemplo

O exemplo seguinte usa o elemento <emphasis> para fazer um anúncio:

<emphasis level="moderate">This is an important announcement</emphasis>

<par>

Um contentor de multimédia paralelo que lhe permite reproduzir vários elementos multimédia em simultâneo. O único conteúdo permitido é um conjunto de um ou mais elementos <par>, <seq> e <media>. A ordem dos elementos <media> não é significativa.

A menos que um elemento secundário especifique uma hora de início diferente, a hora de início implícita do elemento é a mesma que a do contentor <par>. Se um elemento secundário tiver um valor de deslocamento definido para o respetivo atributo begin ou end, o deslocamento do elemento é relativo à hora de início do contentor <par>. Para o elemento <par> raiz, o atributo begin é ignorado e a hora de início é quando o processo de síntese de voz SSML começa a gerar resultados para o elemento <par> raiz (ou seja, efetivamente, a hora "zero").

Exemplo

<speak>
  <par>
    <media xml:id="question" begin="0.5s">
      <speak>Who invented the Internet?</speak>
    </media>
    <media xml:id="answer" begin="question.end+2.0s">
      <speak>The Internet was invented by cats.</speak>
    </media>
    <media begin="answer.end-0.2s" soundLevel="-6dB">
      <audio
        src="https://actions.google.com/.../cartoon_boing.ogg"/>
    </media>
    <media repeatCount="3" soundLevel="+2.28dB"
      fadeInDur="2s" fadeOutDur="0.2s">
      <audio
        src="https://actions.google.com/.../cat_purr_close.ogg"/>
    </media>
  </par>
</speak>

<seq>

Um contentor de multimédia sequencial que lhe permite reproduzir elementos multimédia um após o outro. O único conteúdo permitido é um conjunto de um ou mais elementos <seq>, <par> e <media>. A ordem dos elementos multimédia é a ordem pela qual são renderizados.

Os atributos begin e end dos elementos secundários podem ser definidos para valores de desvio (consulte a especificação de tempo abaixo). Os valores de deslocamento desses elementos secundários são relativos ao fim do elemento anterior na sequência ou, no caso do primeiro elemento na sequência, relativos ao início do respetivo contentor <seq>.

Exemplo

<speak>
  <seq>
    <media begin="0.5s">
      <speak>Who invented the Internet?</speak>
    </media>
    <media begin="2.0s">
      <speak>The Internet was invented by cats.</speak>
    </media>
    <media soundLevel="-6dB">
      <audio
        src="https://actions.google.com/.../cartoon_boing.ogg"/>
    </media>
    <media repeatCount="3" soundLevel="+2.28dB"
      fadeInDur="2s" fadeOutDur="0.2s">
      <audio
        src="https://actions.google.com/.../cat_purr_close.ogg"/>
    </media>
  </seq>
</speak>

<media>

Representa uma camada de multimédia num elemento <par> ou <seq>. O conteúdo permitido de um elemento <media> é um elemento SSML <speak> ou <audio>. A tabela seguinte descreve os atributos válidos para um elemento <media>.

Atributos

Atributo Obrigatória Predefinição Valores
xml:id não nenhum valor Um identificador XML exclusivo deste elemento. As entidades codificadas não são suportadas. Os valores dos identificadores permitidos correspondem à expressão regular "([-_#]|\p{L}|\p{D})+". Consulte XML-ID para mais informações.
begin não 0 A hora de início deste contentor multimédia. É ignorado se for o elemento do contentor de multimédia raiz (tratado da mesma forma que o valor predefinido de "0"). Consulte a secção Especificação de tempo abaixo para ver os valores de string válidos.
end não nenhum valor Uma especificação da hora de fim deste contentor de multimédia. Consulte a secção Especificação de tempo abaixo para ver os valores de string válidos.
repeatCount não 1 Um número real que especifica quantas vezes inserir o conteúdo multimédia. As repetições fracionárias não são suportadas, pelo que o valor é arredondado para o número inteiro mais próximo. Zero não é um valor válido e, por isso, é tratado como não especificado e tem o valor predefinido nesse caso.
repeatDur não nenhum valor Um TimeDesignation que é um limite na duração do conteúdo multimédia inserido. Se a duração do conteúdo multimédia for inferior a este valor, a reprodução termina nesse momento.
soundLevel não +0dB Ajustar o nível de som do áudio em soundLevel decibéis. O intervalo máximo é de +/-40 dB, mas o intervalo real pode ser efetivamente inferior e a qualidade da saída pode não produzir bons resultados em todo o intervalo.
fadeInDur não 0s Uma TimeDesignation durante a qual o volume do conteúdo multimédia aumenta gradualmente do silêncio para o volume soundLevel especificado opcionalmente. Se a duração do conteúdo multimédia for inferior a este valor, o aumento gradual termina no final da reprodução e o nível de som não atinge o nível de som especificado.
fadeOutDur não 0s Uma TimeDesignation durante a qual o volume do conteúdo multimédia vai diminuindo gradualmente a partir do soundLevel opcionalmente especificado até ficar em silêncio. Se a duração do conteúdo multimédia for inferior a este valor, o nível de som é definido para um valor mais baixo para garantir que o silêncio é atingido no final da reprodução.

Especificação de tempo

Uma especificação de tempo, usada para o valor dos atributos `begin` e `end` dos elementos <media> e dos contentores de multimédia (elementos <par> e <seq>), é um valor de desvio (por exemplo, +2.5s) ou um valor de base de sincronização (por exemplo, foo_id.end-250ms).

  • Valor de deslocamento: o valor de deslocamento de tempo é um valor de contagem de tempo SMIL que permite valores que correspondem à expressão regular: "\s\*(+|-)?\s\*(\d+)(\.\d+)?(h|min|s|ms)?\s\*"

    A primeira string de dígitos é a parte inteira do número decimal e a segunda string de dígitos é a parte fracionária decimal. O sinal predefinido (ou seja, "(+|-)?") é "+". Os valores das unidades correspondem a horas, minutos, segundos e milissegundos, respetivamente. A predefinição das unidades é "s" (segundos).

  • Valor de syncbase: um valor de syncbase é um valor de syncbase SMIL que permite valores que correspondem à expressão regular: "([-_#]|\p{L}|\p{D})+\.(begin|end)\s\*(+|-)\s\*(\d+)(\.\d+)?(h|min|s|ms)?\s\*"

    Os dígitos e as unidades são interpretados da mesma forma que um valor de desvio.

<phoneme>

Pode usar a etiqueta <phoneme> para produzir pronúncias personalizadas de palavras em linha. A conversão de texto em voz aceita os alfabetos fonéticos IPA e X-SAMPA. Consulte a página de fonemas para ver uma lista dos idiomas e fonemas suportados.

Cada aplicação da etiqueta <phoneme> direciona a pronúncia de uma única palavra:

  <phoneme alphabet="ipa" ph="ˌmænɪˈtoʊbə">manitoba</phoneme>
  <phoneme alphabet="x-sampa" ph='m@"hA:g@%ni:'>mahogany</phoneme>

Marcadores de stress

Existem até três níveis de ênfase que podem ser colocados numa transcrição:

  1. Stress primário: indicado com /ˈ/ no AFI e /"/ no X-SAMPA.
  2. Stress secundário: indicado com /ˌ/ no AFI e /%/ no X-SAMPA.
  3. Não acentuada: não é denotada com um símbolo (em nenhuma das notações).

Alguns idiomas podem ter menos de três níveis ou não indicar a colocação do acento tónico. Consulte a página de fonemas para ver os níveis de stress disponíveis para o seu idioma. Os marcadores de acentuação são colocados no início de cada sílaba acentuada. Por exemplo, em inglês dos EUA:

Exemplo de palavra IPA X-SAMPA
água ˈwɑːtɚ "wA:t@`
subaquático ˌʌndɚˈwɑːtɚ %Vnd@"wA:t@

Transcrições amplas vs. restritas

Regra geral, mantenha as transcrições mais abrangentes e fonéticas. Por exemplo, em inglês dos EUA, transcreva /t/ intervocálico (em vez de usar um toque):

Exemplo de palavra IPA X-SAMPA
manteiga ˈbʌtɚ em vez de ˈbʌɾɚ "bVt@` em vez de "bV4@`

Existem alguns casos em que a utilização da representação fonémica faz com que os resultados da conversão de texto em voz soem pouco naturais (por exemplo, se a sequência de fonemas for anatomicamente difícil de pronunciar).

Um exemplo disto é a assimilação de sonoridade para /s/ em inglês. Neste caso, a assimilação deve refletir-se na transcrição:

Exemplo de palavra IPA X-SAMPA
gatos ˈkæts "k{ts
cães ˈdɑːgz em vez de ˈdɑːgs "dA:gz" em vez de "dA:gs"

Redução

Cada sílaba tem de conter uma (e apenas uma) vogal. Isto significa que deve evitar consoantes silábicas e, em vez disso, transcrevê-las com uma vogal reduzida. Por exemplo:

Exemplo de palavra IPA X-SAMPA
gatinho ˈkɪtən em vez de ˈkɪtn "kIt@n" em vez de "kitn"
chaleira ˈkɛtəl em vez de ˈkɛtl "kEt@l" em vez de "kEtl"

Silabação

Opcionalmente, pode especificar limites de sílabas através de /./. Cada sílaba tem de conter uma (e apenas uma) vogal. Por exemplo:

Exemplo de palavra IPA X-SAMPA
legibilidade ˌɹiː.də.ˈbɪ.lə.tiː %r\i:.d@."bI.l@.ti:

Dicionário de pronúncia personalizado

Em alternativa ao fornecimento de pronúncias incorporadas com a etiqueta phoneme, forneça um dicionário de pronúncias personalizadas na RPC de síntese de voz. Quando o dicionário de pronúncia personalizado está no pedido, o texto de entrada é automaticamente transformado com a etiqueta phoneme SSML.

Por exemplo, o seguinte pedido com entrada de texto e pronúncia personalizada é transformado e é equivalente ao SSML abaixo.

Entrada original:

input: {
  text: 'Hello world! It is indeed a beautiful world!',
  custom_pronunciations: {
    pronunciations: {
      phrase: 'world'
      phonetic_encoding: PHONETIC_ENCODING_IPA
      pronunciation: 'wɜːld'
    }
  }
}

Entrada transformada:

input: {
  ssml: '<speak>Hello <phoneme alphabet="ipa" ph="wɜːld">world</phoneme>! It is indeed a beautiful <phoneme alphabet="ipa" ph="wɜːld">world</phoneme>!</speak>'
}

Durações

A conversão de texto em voz suporta <say-as interpret-as="duration"> para ler corretamente as durações. Por exemplo, o seguinte exemplo seria verbalizado como "cinco horas e trinta minutos":

<say-as interpret-as="duration" format="h:m">5:30</say-as>

A string de formato suporta os seguintes valores:

Sigla Valor
h horas
m minutos
s segundos
ms milissegundos

<voice>

A etiqueta <voice> permite-lhe usar mais do que uma voz num único pedido SSML. No exemplo seguinte, a voz predefinida é uma voz masculina em inglês. Todas as palavras são sintetizadas nesta voz, exceto "qu'est-ce qui t'amène ici", que é verbalizada em francês com uma voz feminina em vez do idioma (inglês) e género (masculino) predefinidos. 

<speak>And then she asked, <voice language="fr-FR" gender="female">qu'est-ce qui
t'amène ici</voice><break time="250ms"/> in her sweet and gentle voice.</speak>

Em alternativa, pode usar uma etiqueta <voice> para especificar uma voz individual (o nome da voz na página de vozes suportadas) em vez de especificar um language e/ou gender:

<speak>The dog is friendly<voice name="fr-CA-Wavenet-B">mais la chat est
mignon</voice><break time="250ms"/> said a pet shop
owner</speak>

Quando usa a etiqueta <voice>, a conversão de texto em voz espera receber name (o nome da voz que quer usar) ou uma combinação dos seguintes atributos. Todos os três atributos são opcionais, mas tem de fornecer, pelo menos, um se não fornecer um name.

  • gender: um de "masculino", "feminino" ou "neutro".
  • variant: Usado como desempate nos casos em que existem várias possibilidades de voz a usar com base na sua configuração.
  • language: o idioma pretendido. Só é possível especificar um idioma numa etiqueta <voice> específica. Especifique o seu idioma no formato BCP-47. Pode encontrar o código BCP-47 do seu idioma na coluna código de idioma na página de idiomas e vozes suportados.

Também pode controlar a prioridade relativa de cada um dos atributos gender, variant e language através de duas etiquetas adicionais: required e ordering.

  • required: se um atributo for designado como required e não for configurado corretamente, o pedido falha.
  • ordering: todos os atributos indicados após uma etiqueta ordering são considerados atributos preferenciais e não obrigatórios. A API Text-to-Speech considera os atributos preferenciais com base no melhor esforço na ordem em que são apresentados após a etiqueta ordering. Se algum atributo preferencial estiver configurado incorretamente, a funcionalidade de conversão de texto em voz pode continuar a devolver uma voz válida, mas com a configuração incorreta ignorada.

Exemplos de configurações que usam as etiquetas required e ordering:

<speak>And there it was <voice language="en-GB" gender="male" required="gender"
ordering="gender language">a flying bird </voice>roaring in the skies for the
first time.</speak>
 
<speak>Today is supposed to be <voice language="en-GB" gender="female"
ordering="language gender">Sunday Funday.</voice></speak>

<lang>

Pode usar o elemento <lang> para incluir texto em vários idiomas no mesmo pedido SSML. Todos os idiomas são sintetizados na mesma voz, a menos que use a etiqueta <voice> para alterar explicitamente a voz. A string xml:lang tem de conter o idioma de destino no formato BCP-47 (este valor é apresentado como "código de idioma" na tabela de vozes suportadas). No exemplo seguinte, "chat" é verbalizado em francês em vez do idioma predefinido (inglês):

<speak>The french word for cat is <lang xml:lang="fr-FR">chat</lang></speak>

A conversão de texto em voz suporta a etiqueta <lang> com base no melhor esforço. Nem todas as combinações de idiomas produzem resultados da mesma qualidade se forem especificadas no mesmo pedido SSML. Em alguns casos, uma combinação de idiomas pode produzir um efeito que é detetável, mas subtil ou percebido como negativo. Problemas conhecidos:

  • O japonês com carateres Kanji não é suportado pela etiqueta <lang>. A entrada é transliterada e lida como carateres chineses.
  • Os idiomas semíticos, como o árabe, o hebraico e o persa, não são suportados pela etiqueta <lang> e resultam em silêncio. Se quiser usar qualquer um destes idiomas, recomendamos que use a etiqueta <voice> para mudar para uma voz que fale o idioma pretendido (se disponível).

Pontos temporais SSML

A API Text-to-Speech suporta a utilização de pontos de tempo nos dados de áudio criados. Um ponto de tempo é uma indicação de tempo (em segundos, medida a partir do início do áudio gerado) que corresponde a um ponto designado no guião. Pode definir um ponto temporal no script através da etiqueta <mark>. Quando o áudio é gerado, a API devolve o desvio de tempo entre o início do áudio e o ponto temporal.

Existem dois passos para definir um ponto temporal:

  1. Adicione uma etiqueta SSML <mark> ao ponto no guião para o qual quer uma indicação de tempo.
  2. Defina TimepointType como SSML_MARK. Se este campo não for definido, os pontos temporais não são devolvidos por predefinição.

O exemplo seguinte devolve dois pontos no tempo:

  • timepoint_1: indica a hora (em segundos) em que a palavra "Mark" aparece no áudio gerado.
  • timepoint_2: indica o tempo (em segundos) em que a palavra "ver" aparece no áudio gerado.
<speak>Hello <mark name="timepoint_1"/> Mark. Good to <mark
name="timepoint_2"/> see you.</speak>

Estilos

As seguintes vozes podem falar em vários estilos:

  1. en-US-Neural2-F
  2. en-US-Neural2-J

Use a etiqueta <google:style> para controlar o estilo a usar. Use a etiqueta apenas em frases completas.

Exemplo:

<speak><google:style name="lively">Hello I'm so happy today!</google:style></speak>

O campo name suporta os seguintes valores:

  1. apologetic
  2. calm
  3. empathetic
  4. firm
  5. lively