Se usó la API de Cloud Translation para traducir esta página.
Switch to English

Lenguaje de marcación de síntesis de voz (SSML)

Puedes proporcionar detalles sobre las pausas y el formato de audio para las siglas, fechas, horas, abreviaturas, o el texto que se debe censurar, en tu solicitud a Text-to-Speech mediante el lenguaje de marcación de síntesis de voz (SSML) con el fin de que tu respuesta de audio sea más personalizada. Consulta el instructivo de SSML de Speech-to-Text para obtener más información y muestras de código. Consulta la página sobre características de SSML (Beta) para obtener etiquetas SSML adicionales de texto actualmente compatibles en versión Beta.

A continuación, se muestra un ejemplo de lenguaje de marcación SSML y cómo Text-to-Speech sintetiza el 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>

Este es el texto sintetizado correspondiente al documento de ejemplo de SSML:

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.

Text-to-Speech admite un subconjunto de las etiquetas SSML disponibles que se describen en este tema.

Para obtener más información sobre cómo crear datos de audio desde la entrada de SSML con Text-to-Speech, consulta Cómo crear archivos de audio de voz.

Sugerencias para usar SSML

Según la implementación, es posible que debas usar caracteres de escape con las comillas simples o dobles en la carga útil de SSML que envías a Text-to-Speech. En el siguiente ejemplo, se muestra cómo dar formato a la entrada de SSML incluida en un 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'
    }
  }"

También debes evitar los caracteres de control XML, como “<”, “>”, “&”, y las comillas dobles y simples en el texto que se va a convertir en audio. Por supuesto, puedes usar estos caracteres cuando des formato a los elementos y las entidades XML en tu SSML de entrada.

Cuando usas SSML, solo una voz puede leer toda la entrada de SSML. Puedes configurar la voz en el objeto VoiceSelectionParams. Consulta el instructivo de SSML de Text-to-Speech para ver un ejemplo de código que demuestra el uso del objeto VoiceSelectionParams.

Compatibilidad con los elementos de SSML

En las siguientes secciones, se describen los elementos y las opciones de SSML que se pueden usar en tus Acciones.

<speak>

El elemento raíz de la respuesta de SSML.

Para obtener más información sobre el elemento speak, consulta la especificación de W3.

Ejemplo

<speak>
  my SSML content
</speak>

<break>

Un elemento vacío que controla las pausas, o bien otros límites prosódicos entre las palabras. Usar <break> entre cualquier par de tokens es opcional. Si este elemento no está presente entre las palabras, la pausa se determina automáticamente según el contexto lingüístico.

Para obtener más información sobre el elemento break, consulta la especificación de W3.

Atributos

Atributo Descripción
time

Establece la duración de la pausa en segundos o milisegundos (p. ej., “3 s” o “250 ms”).

strength

Establece la intensidad de la pausa prosódica del resultado según términos relativos. Los valores válidos son “x-weak”, “weak”, “medium”, “strong” y “x-strong”. El valor “none” (ninguna) indica que no se debe incluir ningún límite de pausa prosódica en el resultado; se puede usar para evitar una pausa prosódica que, de lo contrario, el procesador produciría. Los demás valores indican una intensidad de pausa no descendente y monótona (conceptualmente ascendente) entre los tokens. Los límites más intensos generalmente están acompañados de una pausa.

Ejemplo

En el siguiente ejemplo, se muestra cómo usar el elemento <break> para hacer pausas entre pasos:

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

Con este elemento, puedes indicar información sobre el tipo de construcción de texto que contiene el elemento. También te ayuda a especificar el nivel de detalle para el procesamiento del texto contenido.

El elemento <say‑as> tiene el atributo obligatorio interpret-as, que determina cómo se pronuncia el valor. Se pueden usar los atributos opcionales format y detail según el valor interpret-as determinado.

Ejemplos

El atributo interpret-as admite los siguientes valores:

  • cardinal

    La forma hablada del número del siguiente ejemplo es “twelve thousand three hundred forty five”, en el caso del inglés estadounidense, o “twelve thousand three hundred and forty five”, en el caso del inglés británico:

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

    En el siguiente ejemplo, la forma hablada es "First" (primero):

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

    En el siguiente ejemplo, la forma hablada se expresa como "C A N":

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

    En el siguiente ejemplo, la forma hablada se expresa como "five and a half" (cinco y medio):

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

    En el siguiente ejemplo, se escucha un “pip”, como si la palabra estuviera censurada:

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

    Convierte las unidades en singular o plural según el número. En el siguiente ejemplo, la forma hablada se expresa como "10 feet" (10 pies):

    <speak>
      <say-as interpret-as="unit">10 foot</say-as>
    </speak>
        
  • verbatim o spell-out

    En el siguiente ejemplo, se deletrea letra por letra:

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

    El atributo format es una secuencia de códigos de caracteres del campo de fecha. Los códigos de caracteres de campo admitidos en format son {y, m, d} para el año, el mes y el día (del mes), respectivamente. Si el código del campo aparece una vez para el año, mes o día, entonces la cantidad de dígitos que se espera es 4, 2 y 2, respectivamente. Si el código del campo se repite, entonces la cantidad de dígitos que se espera es la cantidad de veces que se repite el código. Los campos en el texto de la fecha pueden separarse con puntuación o espacios.

    El atributo detail controla el formato con el que se expresa la forma hablada de la fecha. Para detail='1', solo son obligatorios los campos de día y uno de los campos de mes o año, aunque se pueden ingresar ambos. Esta es la configuración predeterminada cuando no se proporcionan los tres campos. Se expresa como "El {número ordinal del día} de {mes}, {año}".

    El siguiente ejemplo se expresa como "The tenth of September, nineteen sixty" (el diez de septiembre, mil novecientos sesenta):

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

    En el siguiente ejemplo, la forma hablada se expresa como "The tenth of September" (el diez de septiembre):

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

    Para detail='2', son obligatorios los campos de día, mes y año, y esta es la configuración predeterminada cuando se proporcionan los tres campos. Se expresa como “{mes} {número ordinal del día}, {año}”.

    En el siguiente ejemplo, se expresa como "September tenth, nineteen sixty" (septiembre diez, mil novecientos sesenta):

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

    En el siguiente ejemplo, se expresa como "Two thirty P.M." (dos treinta p.m.):

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

    El atributo format es una secuencia de códigos de caracteres de campo de hora. Los códigos de caracteres de campo admitidos en format son {h, m, s, Z, 12, 24} para la hora, los minutos (de la hora), los segundos (del minuto), la zona horaria, el formato de 12 horas y de 24 horas, respectivamente. Si el código del campo aparece una vez para la hora, los minutos o los segundos, la cantidad de dígitos que se espera es 1, 2 y 2, respectivamente. Si el código del campo se repite, entonces la cantidad de dígitos que se espera es la cantidad de veces que se repite el código. Los campos en el texto de la hora pueden separarse con puntuación o espacios. Si no se especifican la hora, los minutos o los segundos en el formato o si los dígitos no coinciden, el campo se trata como si tuviera valor cero. El valor predeterminado para format es “hms12”.

    El atributo detail controla si se usa el formato de 12 o 24 horas para la forma hablada de la hora. El formato hablado será de 24 horas si se usa detail='1' o si se omite detail y el formato de la hora es de 24 horas. El formato hablado será de 12 horas si se usa detail='2' o si se omite detail y el formato de la hora es de 12 horas.

  • telephone

    Consulta la descripción de interpret-as='telephone' en la nota de WG sobre los valores del atributo say-as de SSML 1.0 de W3C.

Para obtener más información sobre el elemento say-as, consulta la especificación de W3.

<audio>

Admite la inserción de archivos de audio grabado y la inserción de otros formatos de audio junto con el resultado de voz sintetizada.

Atributos

Atributo Obligatorio Valor predeterminado Valores
src No corresponde Un URI que hace referencia a la fuente de audio multimedia. El protocolo admitido es https.
clipBegin No 0 Una designación de tiempo que es el desplazamiento desde el inicio del audio de origen en el cual se debe iniciar la reproducción. Si este valor es mayor o igual que la duración real del audio de origen, entonces no se inserta ningún audio.
clipEnd No infinito Una designación de tiempo que es el desplazamiento desde el inicio del audio de origen en el cual se debe finalizar la reproducción. Si la duración real del audio de origen es menor que este valor, entonces la reproducción finalizará en ese momento. Si clipBegin es mayor o igual que clipEnd, entonces no se inserta ningún audio.
speed No 100% La tasa proporcional de velocidad de reproducción del resultado en relación con la velocidad de entrada normal expresada como un porcentaje. El formato es un número real positivo seguido de %. El rango admitido actualmente es [50% (lento - velocidad media), 200% (rápido - doble de velocidad)]. Los valores que se encuentren fuera de este intervalo se podrán ajustar (o no) para que se incluyan en él.
repeatCount No 1 o 10 si se configura repeatDur Un número real que especifica cuántas veces se debe insertar el audio (después del recorte, si corresponde, con clipBegin o clipEnd). Las repeticiones fraccionarias no son compatibles, por lo que el valor se redondeará al número entero más cercano. Cero no es un valor válido y, por consiguiente, se trata como sin especificar y se usa el valor predeterminado en ese caso.
repeatDur No infinito Una designación de tiempo que es un límite de la duración del audio insertado después de procesar la fuente para los atributos clipBegin, clipEnd, repeatCount y speed (en lugar de la duración normal de la reproducción). Si la duración del audio procesado es menor que este valor, entonces la reproducción finalizará en ese momento.
soundLevel No +0dB Ajusta el nivel de sonido del audio en decibeles de soundLevel. El intervalo máximo es de +/-40dB, pero el real puede ser, en efecto, menor, y la calidad del resultado puede no ser buena en el intervalo total.

A continuación, se definen las opciones de configuración que se admiten para el audio en la actualidad:

  • Formato: MP3 (MPEG v2)
    • 24,000 muestras por segundo
    • Entre 24,000 y 96,000 bits por segundo, tasa fija
  • Formato: Opus en Ogg
    • 24,000 muestras por segundo (súper banda ancha)
    • De 24,000 a 96,000 bits por segundo, tasa fija
  • Formato (obsoleto): WAV (RIFF)
    • PCM de 16 bits con signo y de tipo "little endian"
    • 24,000 muestras por segundo
  • Para todos los formatos:
    • Se prefiere el uso de un solo canal, pero se acepta el formato estéreo.
    • La duración máxima es de 240 segundos. Si deseas reproducir audio con una duración más prolongada, evalúa implementar una respuesta multimedia.
    • El límite de tamaño de los archivos es de 5 megabytes.
    • La URL de origen debe usar el protocolo HTTPS.
    • Nuestro UserAgent cuando se obtiene el audio es "Google-Speech-Actions".

El contenido del elemento <audio> es opcional y se usa si el archivo de audio no se puede reproducir o si el dispositivo de salida no admite audio. Puede incluir un elemento <desc>, en cuyo caso el contenido de texto de ese elemento se utiliza para mostrarse. Consulta la sección de audio grabado de la lista de tareas para las respuestas a fin de obtener más información.

La URL src también debe ser una URL HTTPS (Google Cloud Storage puede alojar tus archivos de audio en una URL HTTPS).

Para obtener más información acerca de las respuestas multimedia, consulta la sección correspondiente de la guía de respuestas.

Para obtener más información sobre el elemento audio, consulta la especificación de W3.

Ejemplo

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

<p>,<s>

Elementos de la oración y el párrafo.

Para obtener más información sobre los elementos p y s, consulta la especificación W3.

Ejemplo

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

Prácticas recomendadas

  • Usa etiquetas <s>...</s> para unir oraciones completas, especialmente si contienen elementos de SSML que cambian la prosodia (es decir, <audio>, <break>, <emphasis>, <par>, <prosody>, <say-as>, <seq> y <sub>).
  • Si se pretende que una pausa en el discurso sea lo suficientemente larga para percibirla, usa las etiquetas <s>...</s> y coloca esa pausa entre oraciones.

<sub>

Indica que el texto en el valor de atributo alias reemplaza al texto contenido para la pronunciación.

También puedes usar el elemento sub para proporcionar una pronunciación simplificada de una palabra difícil de leer. Con el último ejemplo que aparece a continuación, se demuestra este caso práctico en japonés.

Para obtener más información sobre el elemento sub, consulta la especificación de W3.

Ejemplos

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

<mark>

Un elemento vacío que coloca un marcador en la secuencia de texto o etiquetas. Se puede usar para hacer referencia a una ubicación específica en la secuencia o para insertar un marcador en una transmisión de salida para notificaciones asíncronas.

Para obtener más información sobre el elemento mark, consulta la especificación de W3.

Ejemplo


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

<prosody>

Se usa para personalizar el tono de la voz, la velocidad del habla y el volumen del texto que contiene el elemento. Actualmente, se admiten los atributos rate, pitch y volume.

Los atributos rate y volume se pueden configurar de acuerdo con las especificaciones de W3. Existen tres opciones para configurar el valor del atributo pitch, que se indican a continuación:

Atributo Descripción
name

El ID de la string de cada marca.

Opción Descripción
Relativo Especifica un valor relativo (p. ej., “bajo”, “medio”, “alto”, etc.), en el que “medio” es el tono predeterminado.
Semitonos Aumenta o disminuye la afinación en “N” semitonos con “+Nst” o “-Nst”, respectivamente. Ten en cuenta que “+/-” y “st” son obligatorios.
Porcentaje Aumenta o disminuye el tono en porcentaje de “N” con “+N%” o “-N%”, respectivamente. Ten en cuenta que el signo “%” es obligatorio, pero “+/-” es opcional.

Para obtener más información sobre el elemento prosody, consulta la especificación de W3.

Ejemplo

En el siguiente ejemplo, se usa el elemento <prosody> para hablar lentamente a 2 semitonos por debajo de lo normal:

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

<emphasis>

Se usa para agregar o quitar énfasis al texto que contiene el elemento. El elemento <emphasis> modifica el discurso de manera similar a <prosody>, pero sin la necesidad de establecer atributos de voz individuales.

Este elemento acepta un atributo de “nivel” opcional con los siguientes valores válidos:

  • strong
  • moderate
  • none
  • reduced

Para obtener más información sobre el elemento emphasis, consulta la especificación de W3.

Ejemplo

En el siguiente ejemplo, se usa el elemento <emphasis> para hacer un anuncio:

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

<par>

Un contenedor multimedia paralelo que te permite reproducir varios elementos multimedia a la vez. El único contenido permitido es un conjunto de uno o más elementos <par>, <seq> y <media>. El orden de los elementos <media> no es importante.

A menos que un elemento secundario especifique un tiempo de inicio diferente, el tiempo de inicio implícito del elemento es el mismo que el del contenedor <par>. Si un elemento secundario tiene un valor de desplazamiento configurado para su atributo begin o end, el desplazamiento del elemento estará relacionado con el tiempo de inicio del contenedor <par>. Para el elemento raíz <par>, el atributo begin se ignora y el tiempo de inicio será cuando el proceso de síntesis de voz SSML comience a generar resultados para el elemento raíz <par> (es decir, en efecto, tiempo “cero”).

Ejemplo

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

Un contenedor multimedia secuencial con el que puedes reproducir elementos multimedia uno detrás de otro. El único contenido permitido es un conjunto de uno o más elementos <seq>, <par> y <media>. El orden de los elementos multimedia será el orden en el que se procesen.

Los atributos begin y end de los elementos secundarios se pueden configurar como valores de desplazamiento (consulta la sección de Especificación de tiempos, a continuación). Los valores de desplazamiento de esos elementos secundarios estarán relacionados con el final del elemento anterior en la secuencia o, en el caso del primer elemento de la secuencia, con el comienzo de su contenedor <seq>.

Ejemplo

<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 una capa multimedia en un elemento <par> o <seq>. El contenido permitido de un elemento <media> es un elemento de SSML <speak> o <audio>. La siguiente tabla describe los atributos válidos de un elemento <media>.

Atributos

Atributo Obligatorio Valor predeterminado Valores
xml:id No ningún valor Un identificador XML único para este elemento. Las entidades codificadas no son compatibles. Los valores de identificador permitidos coinciden con la expresión regular "([-_#]|\p{L}|\p{D})+". Consulta XML-ID para obtener más información.
begin No 0 El tiempo de inicio de este contenedor multimedia. Se ignora si es un elemento de contenedor multimedia raíz (y se trata igual que el valor predeterminado “0”). Consulta la sección de Especificación de tiempos que se encuentra a continuación para ver los valores de string válidos.
end No ningún valor Una especificación para el tiempo de finalización de este contenedor multimedia. Consulta la sección de Especificación de tiempos que se encuentra a continuación para ver los valores de string válidos.
repeatCount No 1 Un número real que especifica cuántas veces se debe insertar el elemento multimedia. No se admiten fracciones en las repeticiones, de manera que el valor se redondeará al número entero más cercano. Cero no es un valor válido y, por consiguiente, se trata como sin especificar y se usa el valor predeterminado en ese caso.
repeatDur No ningún valor Una designación de tiempo que es el límite de duración del elemento multimedia insertado. Si la duración del elemento multimedia es menor que este valor, entonces la reproducción finalizará en ese momento.
soundLevel No +0dB Ajusta el nivel de sonido del audio en decibeles de soundLevel. El intervalo máximo es de +/-40dB, pero el real puede ser, en efecto, menor, y la calidad del resultado puede no ser buena en el intervalo total.
fadeInDur No 0s Una designación de tiempo durante la cual el elemento multimedia aparecerá gradualmente desde el silencio hasta el soundLevel especificado de forma opcional. Si la duración del elemento multimedia es menor que este valor, entonces el elemento aparecerá de forma parcial al final de la reproducción.
fadeOutDur No 0s Una designación de tiempo durante la cual el elemento multimedia desaparecerá gradualmente del soundLevel especificado de forma opcional, hasta el silencio. Si la duración del elemento multimedia es menor que este valor, entonces el elemento desaparecerá de forma parcial al inicio de la reproducción.

Especificación de tiempo

Una especificación de tiempo, que se usa para el valor de los atributos “begin” y “end” de elementos <media> y contenedores multimedia (elementos <par> y <seq>), es un valor de desplazamiento (por ejemplo, +2.5s) o un valor syncbase (por ejemplo, foo_id.end-250ms).

  • Valor de desplazamiento: El valor de desplazamiento de tiempo (offset) es un “Timecount-value” de SMIL (lenguaje de integración multimedia sincronizada) que acepta valores que coinciden con la expresión regular: "\s\*(+|-)?\s\*(\d+)(\.\d+)?(h|min|s|ms)?\s\*"

    La primera string de dígitos es la parte entera del número decimal y la segunda string de dígitos es la fracción del decimal. El signo predeterminado (es decir, “(+|-)?”) es “+”. Los valores unitarios corresponden a horas, minutos, segundos y milisegundos, respectivamente. La configuración predeterminada para las unidades es "s" (segundos).

  • Valor syncbase: Un valor syncbase es un valor de syncbase de SMIL que permite valores que coinciden con la expresión regular: "([-_#]|\p{L}|\p{D})+\.(begin|end)\s\*(+|-)\s\*(\d+)(\.\d+)?(h|min|s|ms)?\s\*"

    Los dígitos y las unidades se interpretan de la misma manera que con un valor de desplazamiento.