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

Para possibilitar mais personalização da resposta de áudio, é possível enviar Linguagem de Marcação de Síntese de Fala (SSML, na sigla em inglês) na solicitação da Cloud Text-to-Speech com o fornecimento de detalhes sobre pausas, formatação de áudio para acrônimos, datas, horas, abreviaturas ou texto que deva ser censurado. Consulte o tutorial de SSML da Cloud TTS para mais informações e exemplos de código.

Em seguida, mostramos um exemplo de marcação SSML e a sintetização do texto pela Cloud TTS:

<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>

Aqui está 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 Cloud TTS aceita um subconjunto de tags SSML disponíveis, que estão descritas aqui.

Para mais informações sobre como criar dados de áudio com a Cloud TTS usando entradas SSML, consulte Como criar arquivos de áudio de voz.

Dicas para usar a SSML

Dependendo da sua implementação, talvez seja necessário escapar aspas no payload SSML enviado para a Cloud TTS. O exemplo a seguir mostra como formatar uma entrada SSML incluída em um 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'
    }
  }"

Reservar caracteres

Evite usar caracteres de reserva SSML no texto que será convertido em áudio. Quando você precisar fazer isso, use o código de escape para impedir que o caractere seja lido como código. A tabela a seguir mostra caracteres SSML reservados e os códigos de escape associados a eles.

Selecionar uma voz

Você pode definir a voz no objeto VoiceSelectionParams. Consulte o tutorial de SSML da Text-to-Speech para acessar um exemplo de código que demonstra o uso do objeto VoiceSelectionParams.

É possível usar a tag <voice> para ler SSML em várias vozes, mas você precisa definir o nome do VoiceSelectionParams para uma voz compatível:

Compatibilidade com elementos SSML

As seções a seguir 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 sobre o elemento speak, consulte a especificação do W3.

Exemplo

<speak>
  my SSML content
</speak>

<break>

Elemento vazio que controla a pausa ou outros limites prosódicos entre as palavras. Usar <break> entre qualquer par de tokens é opcional. Se esse elemento não estiver presente entre as palavras, a quebra será determinada automaticamente com base no contexto linguístico.

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

Atributos

Exemplo

O exemplo a seguir mostra como usar o elemento <break> para pausar entre as etapas:

<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>

Esse elemento permite indicar informações sobre o tipo de construção de texto contido no elemento. Também ajuda a especificar o nível de detalhes para renderizar o texto contido.

O elemento <say‑as> tem o atributo obrigatório, interpret-as, que determina como o valor é falado. Atributos opcionais format e detail são usados dependendo do valor interpret-as específico.

Exemplos

O atributo interpret-as aceita os seguintes valores:

• currency

  O exemplo a seguir é falado, em inglês, como "quarenta e dois dólares e um centavo". Se o atributo de idioma for omitido, a localidade atual será usada.

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

• telephone

  Veja a descrição de interpret-as='telephone' na observação do WG do W3C sobre a SSML 1.0, valores de atributo say-as.

  O exemplo a seguir é falado, em inglês, como "one eight zero zero two zero two one two one two". Se o atributo "google:style" for omitido, ele vai falar zero como a letra O.

  No momento, o atributo "google:style='zero-as-zero'" funciona apenas em localidades em EN.

        <speak>
          <say-as interpret-as='telephone' google:style='zero-as-zero'>1800-202-1212</say-as>
        </speak>
      

• verbatim ou spell-out

  O exemplo a seguir é soletrado letra por letra:

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

• date

  O atributo format é uma sequência de códigos de caracteres de campo de data. Os códigos de caracteres de campo aceitos em format são {y, m, d} para ano, mês e dia (do mês), respectivamente. Se o código de campo aparecer uma vez para ano, mês ou dia, o número de dígitos esperados será 4, 2 e 2, respectivamente. Se o código de campo for repetido, o número de dígitos esperados será o número de vezes que o código for repetido. É possível separar os campos no texto da data por pontuação e/ou espaços.

  O atributo detail controla a forma falada da data. Para detail='1', apenas os campos "dia" e um dos campos "mês ou "ano" são obrigatórios, embora seja possível fornecer ambos. Esse é o padrão quando nem todos os três campos são fornecidos. A forma falada, em inglês, é "The {dia ordinal} of {mês}, {ano}".

  O exemplo a seguir é falado, em inglês, como "The tenth of September, nineteen sixty":

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

  O exemplo a seguir é falado, em inglês, como "The tenth of September":

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

  Para detail='2', os campos "dia", "mês" e "ano" são obrigatórios e esse é o padrão quando todos os três campos são fornecidos. A forma falada, em inglês, é "{mês} {dia ordinal}, {ano}".

  O exemplo a seguir é falado, em inglês, como "September tenth, nineteen sixty":

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

• characters

  O exemplo a seguir é falado, em inglês, como "C A N":

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

• cardinal

  O exemplo a seguir é falado, em inglês, 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 a seguir é falado, em inglês, como "First":

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

• fraction

  O exemplo a seguir é falado, em inglês, como "five and a half":

  <speak>
    <say-as interpret-as="fraction">5+1/2</say-as>
  </speak>
      

• expletive ou bleep

  O exemplo a seguir é emitido como um sinal sonoro de censura:

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

• unit

  Converte unidades para singular ou plural, dependendo do número. O exemplo a seguir é falado, em inglês, como "10 feet":

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

• time

  O exemplo a seguir é falado, em inglês, como "Two thirty P.M.":

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

  O atributo format é uma sequência de códigos de caracteres do campo de hora. Os códigos de caracteres de campo aceitos em format são {h, m, s, Z, 12, 24} para "hora", "minuto" (da hora), "segundo" (do minuto), "fuso horário", "12 horas" e "24 horas", respectivamente. Se o código de campo aparecer uma vez por hora, minuto ou segundo, o número de dígitos esperados é 1, 2 e 2, respectivamente. Se o código de campo for repetido, o número de dígitos esperados será o número de vezes que o código for repetido. É possível separar os campos no texto da hora podem por pontuação e/ou espaços. Se "hora", "minuto" ou "segundo" não forem especificados no formato ou não houver dígitos correspondentes, o campo será tratado como um valor zero. O format padrão é "hms12".

  O atributo detail controla se a forma falada da hora é de 12 ou 24 horas. O formato falado será 24 horas se detail='1' ou se detail forem omitidos e o formato da hora for 24 horas. O formato falado será de 12 horas se detail='2' ou se detail forem omitidos e o formato da hora for 12 horas.

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

<audio>

Aceita a inserção de arquivos de áudio gravados e de outros formatos de áudio em conjunto com a saída de fala sintetizada.

Atributos

Veja a seguir as configurações aceitas atualmente para áudio:

• Formato: MP3 (MPEG v2)
  • 24.000 amostras por segundo
  • 24K - 96K bits por segundo, taxa fixa
• Formato: Opus em Ogg
  • 24.000 amostras por segundo (super banda larga)
  • 24K - 96K bits por segundo, taxa fixa
• Formato (obsoleto): WAV (RIFF)
  • PCM assinado de 16 bits, little endian
  • 24.000 amostras por segundo
• Válido para todos os formatos:
  • É preferível ter um canal único, mas estéreo é aceitável.
  • Duração máxima de 240 segundos. Se você quiser tocar áudio com uma duração maior, implemente uma resposta de mídia.
  • Limite de tamanho de arquivo de 5 megabytes.
  • O URL de origem precisa usar o protocolo HTTPS.
  • O UserAgent ao buscar o áudio é o "Google-Speech-Actions".

O conteúdo do elemento <audio> é opcional e será usado se não for possível reproduzir o arquivo de áudio ou se o dispositivo de saída não aceitar o áudio. O conteúdo inclui um elemento <desc>. Nesse caso, o conteúdo de texto desse elemento é usado para exibição. Para mais informações, consulte a seção "Áudio gravado" na Lista de verificação de respostas.

O URL src também precisa ser um URL HTTPS. O Google Cloud Storage hospeda seus arquivos de áudio em um URL HTTPS.

Para saber mais sobre respostas de mídia, consulte a seção de resposta de mídia no guia de respostas.

Para saber mais sobre o elemento audio, consulte a especificação do 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 frase e parágrafo.

Para saber mais sobre os elementos p e s, consulte a especificação do W3.

Exemplo

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

Práticas recomendadas

• Use as tags <s>...</s> para agrupar frases completas, principalmente se elas 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 for longa o suficiente para ser audível, use as tags <s>...</s> e coloque essa quebra entre as sentenças.

<sub>

Indica que o texto no valor do atributo de alias substitui o texto contido para a pronúncia.

Também é possível usar o elemento sub para fornecer uma pronúncia simplificada de uma palavra de difícil leitura. O último exemplo abaixo demonstra este caso de uso em japonês.

Para saber mais sobre o elemento sub, consulte a especificação do 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 tags. É possível usá-lo para referir-se a um local específico na sequência ou para inserir um marcador em um fluxo de saída para notificação assíncrona.