SSML

Ao retornar uma resposta ao Google Assistente, você pode usar um subconjunto dos Linguagem de marcação de síntese de fala (SSML, na sigla em inglês) nas suas respostas. De usando SSML, é possível fazer com que as respostas da sua conversa pareçam mais naturais fala. O exemplo a seguir mostra a marcação SSML e o áudio correspondente de Google Assistente:

Node.js

function saySSML(conv) {
  const ssml = '<speak>' +
    'Here are <say-as interpret-as="characters">SSML</say-as> samples. ' +
    'I can pause <break time="3" />. ' +
    'I can play a sound <audio src="https://www.example.com/MY_WAVE_FILE.wav">your wave file</audio>. ' +
    'I can speak in cardinals. Your position is <say-as interpret-as="cardinal">10</say-as> in line. ' +
    '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. Your position in line is <say-as interpret-as="digits">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>';
  conv.add(ssml);
}

JSON

{
  "expectUserResponse": true,
  "expectedInputs": [
    {
      "possibleIntents": [
        {
          "intent": "actions.intent.TEXT"
        }
      ],
      "inputPrompt": {
        "richInitialPrompt": {
          "items": [
            {
              "simpleResponse": {
                "textToSpeech": "<speak>Here are <say-as interpret-as=\"characters\">SSML</say-as> samples. I can pause <break time=\"3\" />. I can play a sound <audio src=\"https://www.example.com/MY_WAVE_FILE.wav\">your wave file</audio>. I can speak in cardinals. Your position is <say-as interpret-as=\"cardinal\">10</say-as> in line. 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. Your position in line is <say-as interpret-as=\"digits\">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>"
              }
            }
          ]
        }
      }
    }
  ]
}

Áudio

URLs em SSML

Ao definir uma resposta SSML que inclui apenas um URL, o "e" comercial nesse URL pode causar problemas devido à formatação XML. Para garantir que o URL seja devidamente referenciadas, substitua as instâncias de & por &amp;.

Mesmo que sua resposta SSML inclua apenas um URL, o Actions on Google exige o texto de exibição para a resposta. Como o texto na tag <audio> não será falado pelo Google Assistente, você pode inserir o texto de preenchimento ou uma breve descrição no <audio> para atender a esse requisito. O texto na tag <audio> não será falado pelo Google Assistente após o áudio tocar e se conecta ao Action no Google para uma versão de exibição de texto da SSML.

Veja um exemplo de resposta SSML problemática:

<speak>
  <audio src="https://firebasestorage.googleapis.com/v0/b/project-name.appspot.com/o/audio-file-name.ogg?alt=media&token=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX">
  </audio>
</speak>

O exemplo acima não faz o escape do & para a formatação XML adequada.

Uma versão fixa da mesma resposta SSML tem a seguinte aparência:

<speak>
  <audio src="https://firebasestorage.googleapis.com/v0/b/project-name.appspot.com/o/audio-file-name.ogg?alt=media&amp;token=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX">
  text
  </audio>
</speak>

Compatibilidade com elementos SSML

As seções a seguir descrevem os elementos e as opções de SSML que podem ser usados em 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

Atributo Descrição
time

Define o tamanho da quebra em segundos ou milissegundos (por exemplo, "3 s" ou "250 ms").
strength

Define a força da quebra prosódica de saída por termos relativos. Os valores válidos são: "x-weak", "weak", "medium", "strong" e "x-strong". O valor "none" indica que nenhum limite de quebra prosódico será gerado, o que pode ser usado para evitar uma quebra prosódica que o processador poderia produzir. Os outros valores indicam uma força de quebra monotonicamente não decrescente (que aumenta de modo conceitual) entre os tokens. Os limites mais fortes normalmente são acompanhados por pausas.

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 "tempo". 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

Atributo Obrigatório Padrão Valores
src sim n/a Um URI que se refere à fonte de mídia de áudio. O protocolo aceito é https.
clipBegin não 0 Uma TimeDesignation que especifica o ponto em que o áudio começará a tocar a partir do momento que for iniciado. Se esse valor for maior ou igual à duração real da fonte de áudio, nenhum áudio será inserido.
clipEnd não infinito Uma TimeDesignation que especifica o ponto em que o áudio parará de tocar a partir do momento que for iniciado. Se a duração real da fonte de áudio for menor que esse valor, a reprodução será finalizada nesse momento. Se clipBegin for maior ou igual a clipEnd, nenhum áudio será inserido.
speed não 100% A proporção da taxa de reprodução de saída em relação à taxa de entrada normal expressa em porcentagem. O formato é um número real positivo seguido por %. O intervalo atualmente aceito é de [50% (lento - meia velocidade), 200% (rápido - velocidade dupla)]. Valores fora desse intervalo podem (ou não) ser ajustados para ficar dentro dele.
repeatCount não 1 ou 10, se repeatDur for definido Um número real especificando quantas vezes é preciso inserir o áudio (após o recorte, se houver, até clipBegin e/ou clipEnd). Não são aceitas repetições fracionárias. Portanto, o valor será arredondado para o número inteiro mais próximo. Zero não é um valor válido e, portanto, é tratado como não especificado e tem o valor padrão nesse caso.
repeatDur não infinito Uma TimeDesignation que é um limite da duração do áudio inserido após o processamento da origem para os atributos clipBegin, clipEnd, repeatCount e speed (em vez da duração normal de reprodução). Se a duração do áudio processado for menor que esse valor, a reprodução será finalizada nesse momento.
soundLevel não +0 dB Ajusta o nível de som do áudio em soundLevel decibéis. O intervalo máximo é de +/- 40 dB, mas o real talvez seja efetivamente menor, e a qualidade de saída pode não produzir bons resultados em todo o intervalo.

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 abrir o arquivo de áudio ou se o dispositivo de saída não for compatível com á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 de 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.

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

Exemplo

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

<prosody>

Usado para personalizar o tom, a taxa de fala e o volume de texto contido no elemento. Atualmente, os atributos rate, pitch e volume são compatíveis.

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

Atributo Descrição
name

A ID da string de cada marca.
Opção Descrição
Relativo Especifique um valor relativo (por exemplo, "low", "medium", "high" etc.), em que" "medium" é o tom padrão.
Semitons Aumente ou diminua o tom em "N" semitons usando "+N st" ou "-N st", respectivamente. Observe que "+/-" e "st" são obrigatórios.
Porcentagem Aumente ou diminua o tom em "N%" usando "+ N%" ou "-N%", respectivamente. Observe que "%" é obrigatório, mas "+/-" é opcional.

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

Exemplo

O exemplo a seguir usa o elemento <prosody> para falar lentamente a dois 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 fala de forma semelhante a <prosody>, mas sem a necessidade de definir atributos de fala individuais.

Esse elemento aceita um atributo "level" opcional com os seguintes valores válidos:

  • strong
  • moderate
  • none
  • reduced

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

Exemplo

O exemplo a seguir usa o elemento <emphasis> para fazer um comunicado:

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

<par>

Um contêiner de mídia paralela que permite abrir vários elementos de mídia de uma só vez. O único conteúdo permitido é um conjunto de um ou mais elementos <par>, <seq> e <media>. A ordem dos elementos <media> não é importante.

A menos que um elemento filho especifique um horário de início diferente, o horário de início implícito para o elemento é o mesmo que o do contêiner <par>. Se um elemento filho tiver um valor de ajuste definido para seu atributo begin ou end, o ajuste do elemento será relativo ao horário de início do contêiner <par>. Para o elemento raiz <par>, o atributo "begin" é ignorado e o horário de início ocorre quando o processo de síntese de voz SSML começa a gerar a saída para o elemento raiz <par> (ou seja, efetivamente tempo "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 contêiner de mídia sequencial que permite abrir elementos de mí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 de mídia é a ordem em que eles são renderizados.

Os atributos begin e end de elementos filhos são definidos como valores de ajuste. Consulte Especificação de tempo abaixo. Os valores de ajuste desses elementos filhos serão relativos ao final do elemento anterior na sequência ou, no caso do primeiro elemento na sequência, em relação ao início do contêiner <seq> dele.

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 mídia em um elemento <par> ou <seq>. O conteúdo permitido de um elemento <media> é um elemento SSML <speak> ou <audio>. A tabela a seguir descreve os atributos válidos para um elemento <media>.

Atributos

Atributo Obrigatório Padrão Valores
xml:id não nenhum valor Um identificador XML exclusivo para esse elemento. Entidades codificadas não são aceitas. Os valores permitidos para o identificador 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 contêiner de mídia. Ignorado se este for o elemento de contêiner de mídia raiz (tratado da mesma forma que o padrão de "0"). Consulte a seção Especificação de tempo abaixo para valores de string válidos.
end não nenhum valor Uma especificação para a hora de término deste contêiner de mídia. Consulte a seção Especificação de tempo abaixo para valores de string válidos.
repeatCount não 1 Um número real que especifica quantas vezes é preciso inserir a mídia. Repetições fracionárias não são aceitas. Portanto, o valor será arredondado para o número inteiro mais próximo. Zero não é um valor válido e, portanto, é tratado como não especificado e tem o valor padrão nesse caso.
repeatDur não nenhum valor Uma TimeDesignation que é um limite na duração da mídia inserida. Se a duração da mídia for menor que esse valor, a reprodução será finalizada nesse momento.
soundLevel não +0 dB Ajusta o nível de som do áudio em soundLevel decibéis. O intervalo máximo é de +/- 40 dB, mas o real talvez seja efetivamente menor, e a qualidade de saída pode não produzir bons resultados em todo o intervalo.
fadeInDur não 0s Uma TimeDesignation em que o som da mídia aparecerá gradualmente, do modo silencioso para o modo soundLevel especificado. Se a duração da mídia for menor que esse valor, a exibição gradual será interrompida ao final da reprodução, e o nível de som não atingirá o nível especificado.
fadeOutDur não 0s Uma TimeDesignation em que o som da mídia será reduzido gradualmente, do modo soundLevel especificado até desaparecer por completo. Se a duração da mídia for menor que esse valor, o nível de som será definido como um valor mais baixo para garantir que o silêncio seja atingido ao final da reprodução.

Especificação de tempo

Uma especificação de tempo, usada para o valor dos atributos "begin" e "end" de elementos <media> e contêineres de mídia (elementos <par> e <seq>), é um valor de ajuste (por exemplo, +2.5s) ou um valor de syncbase (por exemplo, foo_id.end-250ms).

  • Valor de ajuste: o valor de ajuste de tempo é um valor de contagem de tempo SMIL que permite valores correspondentes à 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 é a parte fracionária. O sinal padrão (ou seja, "(+|-)?") é "+". Os valores unitários correspondem a horas, minutos, segundos e milissegundos, respectivamente. O padrão para as unidades é "s" (segundos).

  • Valor da syncbase: é um valor de syncbase SMIL que permite valores correspondentes à 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 ajuste.

Simulador de TTS

O Console do Actions inclui um simulador de TTS que pode ser usado para testar a SSML por qualquer um dos elementos acima. Encontre o simulador de TTS no console em Simulador > Áudio. Digite seu texto e SSML no simulador e clique em Atualizar e ouvir para ouvir a saída de TTS.

Você também pode clicar no botão de download para salvar um arquivo .mp3 da sua TTS. saída.