chrome.tts

Descripción

Usa la API de chrome.tts para reproducir texto a voz (TTS) sintetizado. Consulta también la API de ttsEngine relacionada, que permite que una extensión implemente un motor de voz.

Chrome ofrece esta capacidad en Windows (con SAPI 5), Mac OS X y ChromeOS, mediante las capacidades de síntesis de voz que proporciona el sistema operativo. En todas las plataformas, el usuario puede instalar extensiones que se registran como motores de voz alternativos.

Permisos

tts

Conceptos y uso

Generar voz

Llama a speak() desde tu extensión para hablar. Por ejemplo:

chrome.tts.speak('Hello, world.');

Para dejar de hablar de inmediato, llama a stop():

chrome.tts.stop();

Puedes proporcionar opciones que controlen varias propiedades de la voz, como la velocidad, el tono y mucho más. Por ejemplo:

chrome.tts.speak('Hello, world.', {'rate': 2.0});

También es una buena idea especificar el idioma de modo que se elija un sintetizador que admita ese idioma (y dialecto regional, si corresponde).

chrome.tts.speak('Hello, world.', {'lang': 'en-US', 'rate': 2.0});

De forma predeterminada, cada llamada a speak() interrumpe las voces en curso y habla de inmediato. Para determinar si una llamada interrumpiría algo, puedes llamar a isSpeaking(). Además, puedes usar la opción enqueue para hacer que esta frase se agregue a una cola de expresiones que se dirán cuando finalice la expresión actual.

chrome.tts.speak('Speak this first.');
chrome.tts.speak(
    'Speak this next, when the first sentence is done.', {'enqueue': true});

Encontrarás una descripción completa de todas las opciones en tts.speak(). No todos los motores de voz serán compatibles con todas las opciones.

Para detectar errores y asegurarte de que llamas correctamente a speak(), pasa una función de devolución de llamada que no reciba argumentos. Dentro de la devolución de llamada, revisa runtime.lastError para ver si hubo algún error.

chrome.tts.speak(
  utterance,
  options,
  function() {
    if (chrome.runtime.lastError) {
      console.log('Error: ' + chrome.runtime.lastError.message);
    }
  }
);

La devolución de llamada se muestra de inmediato, antes de que el motor empiece a generar voz. El objetivo de la devolución de llamada es alertarte sobre los errores de sintaxis en el uso de la API de TTS para no detectar todos los errores posibles que puedan ocurrir en el proceso de sintetización y salida de voz. Para detectar estos errores, debes usar un objeto de escucha de eventos, como se describe en la siguiente sección.

Escucha eventos

Para obtener más información en tiempo real sobre el estado de la voz sintetizada, pasa un objeto de escucha de eventos de las opciones a speak(), como se muestra a continuación:

chrome.tts.speak(
  utterance,
  {
    onEvent: function(event) {
      console.log('Event ' + event.type + ' at position ' + event.charIndex);
      if (event.type == 'error') {
        console.log('Error: ' + event.errorMessage);
      }
    }
  },
  callback
);

Cada evento incluye un tipo de evento, el índice de caracteres de la voz actual en relación con la declaración y, para los eventos de error, un mensaje de error opcional. Los tipos de eventos son los siguientes:

• 'start': El motor comenzó a decir el enunciado.
• 'word': Se alcanzó el límite de una palabra. Usa event.charIndex para determinar la posición de voz actual.
• 'sentence': Se alcanzó el límite de una oración. Usa event.charIndex para determinar la posición de voz actual.
• 'marker': Se alcanzó un marcador de SSML. Usa event.charIndex para determinar la posición de voz actual.
• 'end': El motor terminó de decir el enunciado.
• 'interrupted': Otra llamada a speak() o stop() interrumpió este enunciado, y este no se completó.
• 'cancelled': Este enunciado se puso en cola, pero luego se canceló por otra llamada a speak() o stop(), y nunca comenzó a hablar.
• 'error': Se produjo un error específico del motor y no se puede pronunciar este enunciado. Consulta event.errorMessage para obtener más información.

Cuatro de los tipos de eventos ('end', 'interrupted', 'cancelled' y 'error') son finales. Una vez que se recibe uno de esos eventos, este enunciado ya no hablará y no se recibirán nuevos eventos de este enunciado.

Es posible que algunas voces no admitan todos los tipos de eventos y que algunas no envíen eventos en absoluto. Si no quieres usar una voz, a menos que envíe ciertos eventos, pasa los eventos que necesitas en el miembro requiredEventTypes del objeto de opciones o usa getVoices() para elegir una voz que cumpla con tus requisitos. Ambas se describen a continuación.

Lenguaje de marcado de SSML

Las declaraciones usadas en esta API pueden incluir lenguaje de marcado que use el Lenguaje de marcación de síntesis de voz (SSML). Si usas el SSML, el primer argumento para speak() debe ser un documento de SSML completo con un encabezado XML y una etiqueta <speak> de nivel superior, no un fragmento de documento.

Por ejemplo:

chrome.tts.speak(
  '<?xml version="1.0"?>' +
  '<speak>' +
  '  The <emphasis>second</emphasis> ' +
  '  word of this sentence was emphasized.' +
  '</speak>'
);

No todos los motores de voz serán compatibles con todas las etiquetas de SSML, y es posible que algunos no lo admitan en absoluto, pero todos los motores deben ignorar cualquier SSML que no admitan y que sigan hablando el texto subyacente.

Elige una voz

De forma predeterminada, Chrome elige la voz más adecuada para cada frase que deseas pronunciar, según el idioma. En la mayoría de los sistemas Windows, Mac OS X y ChromeOS, la síntesis de voz que proporciona el sistema operativo debe poder reproducir texto en al menos un idioma. Sin embargo, es posible que algunos usuarios tengan una variedad de voces disponibles de sus sistemas operativos y de motores de voz implementados por otras extensiones de Chrome. En esos casos, puedes implementar un código personalizado para elegir la voz adecuada o presentar al usuario una lista de opciones.

Para obtener una lista de todas las voces, llama a getVoices() y pásale una función que reciba un array de objetos TtsVoice como su argumento:

chrome.tts.getVoices(
  function(voices) {
    for (var i = 0; i < voices.length; i++) {
      console.log('Voice ' + i + ':');
      console.log('  name: ' + voices[i].voiceName);
      console.log('  lang: ' + voices[i].lang);
      console.log('  extension id: ' + voices[i].extensionId);
      console.log('  event types: ' + voices[i].eventTypes);
    }
  }
);

Tipos

EventType

Chrome 54 y versiones posteriores

Enum

TtsEvent

Es un evento del motor de TTS para comunicar el estado de una declaración.

Propiedades

• charIndex

  número opcional

  Es el índice del carácter actual en el enunciado. En el caso de los eventos de palabras, el evento se activa al final de una palabra y antes del comienzo de la siguiente. El símbolo charIndex representa un punto en el texto al comienzo de la siguiente palabra que se dirá.

• errorMessage

  cadena opcional

  La descripción del error, si el tipo de evento es error.

• length

  número opcional

  Chrome 74 y versiones posteriores

  La longitud de la siguiente parte del enunciado. Por ejemplo, en un evento word, esta es la longitud de la palabra que se dirá a continuación. Se establecerá en -1 si el motor de voz no lo establece.

• Tipo

  EventType

  El tipo puede ser start apenas comienza la voz, word cuando se alcanza el límite de una palabra, sentence cuando se alcanza el límite de una oración, marker cuando se alcanza un elemento de marca de SSML, end cuando se alcanza el final de la frase, interrupted cuando la frase se detiene o se interrumpe antes de llegar al final, cancelled cuando se quita de la cola antes de sintetizarse o error cuando se produce cualquier otro error. Cuando se pausa la voz, se activa un evento pause si se pausa un enunciado específico en el medio y resume si se reanuda un enunciado. Ten en cuenta que es posible que los eventos de pausa y reanudación no se activen si el discurso se pausa entre los enunciados.

TtsOptions

Chrome 77 y versiones posteriores

Las opciones de voz del motor de TTS.

Propiedades

• desiredEventTypes

  string[] opcional

  Los tipos de eventos de TTS que te interesa escuchar. Si faltan, es posible que se envíen todos los tipos de eventos.

• poner en cola

  booleano opcional

  Si es verdadero, pone en cola esta declaración si TTS ya está en curso. Si es falso (el valor predeterminado), interrumpe cualquier voz actual y limpia la cola de voz antes de decir esta frase nueva.

• extensionId

  cadena opcional

  El ID de la extensión del motor de voz que se usará, si se conoce.

• género

  VoiceGender opcional

  Obsoleta a partir de Chrome 77

  El género dejó de estar disponible y se ignorará.

  Género de voz para la voz sintetizada.

• lang

  cadena opcional

  El idioma que se usará para la síntesis, en el formato language-region. Ejemplos: “en”, “en-US”, “en-GB”, “zh-CN”.

• lanzamiento

  número opcional

  El tono del habla debe ser de entre 0 y 2 inclusive, donde 0 es el más bajo y 2 es el más alto. 1.0 corresponde al tono predeterminado de una voz.

• de conversiones

  número opcional

  Velocidad de habla en relación con la velocidad predeterminada para esta voz. La velocidad predeterminada es de 1.0, que suele ser entre 180 y 220 palabras por minuto. 2.0 es el doble de rápido y 0.5 es la mitad. Los valores inferiores a 0.1 o superiores a 10.0 no están permitidos, pero muchas voces restringirán aún más las velocidades mínima y máxima. Por ejemplo, es posible que una voz en particular no hable más de 3 veces lo normal, incluso si especificas un valor superior a 3.0.

• requiredEventTypes

  string[] opcional

  Los tipos de eventos de TTS que la voz debe admitir.

• voiceName

  cadena opcional

  El nombre de la voz que se usará para la síntesis. Si está vacío, usa cualquier voz disponible.

• Volumen

  número opcional

  El volumen del habla debe ser de entre 0 y 1 inclusive, donde 0 es el más bajo y 1 el más alto, con un valor predeterminado de 1.0.

• onEvent

  void opcional

  Esta función se llama con eventos que tienen lugar en el proceso de decir la declaración.

  La función onEvent se ve de la siguiente manera:

  (event: TtsEvent)=> {...}

  • event

    TtsEvent

    El evento de actualización del motor de texto a voz que indica el estado de este enunciado.

TtsVoice

Una descripción de una voz disponible para la síntesis de voz.

Propiedades

• eventTypes

  EventType[] opcional

  Todos los tipos de eventos de devolución de llamada que esta voz puede enviar.

• extensionId

  cadena opcional

  El ID de la extensión que proporciona esta voz.

• género

  VoiceGender opcional

  Obsoleta a partir de Chrome 70

  El género dejó de estar disponible y se ignorará.

  Género de esta voz.

• lang

  cadena opcional

  El idioma que admite esta voz, en el formato language-region. Ejemplos: “en”, “en-US”, “en-GB”, “zh-CN”.

• remoto

  booleano opcional

  Si es verdadero, el motor de síntesis es un recurso de red remoto. Puede ser una latencia más alta y generar costos de ancho de banda.

• voiceName

  cadena opcional

  El nombre de la voz.

VoiceGender

Chrome 54 y versiones posteriores Obsoleta a partir de Chrome 70

El género dejó de estar disponible y se ignorará.

Enum

Métodos

getVoices()

Promesa

chrome.tts.getVoices(
  callback?: function,
)

Obtiene un array de todas las voces disponibles.

Parámetros

• callback

  Función opcional

  El parámetro callback se ve de la siguiente manera:

  (voices: TtsVoice[])=>void

  • voces

    TtsVoice

    Array de objetos tts.TtsVoice que representan las voces disponibles para la síntesis de voz.

Devuelve

• Promise<TtsVoice[]>

  Chrome 101 y versiones posteriores

  Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para brindar retrocompatibilidad. No puedes usar ambos en la misma llamada a función. La promesa se resuelve con el mismo tipo que se pasa a la devolución de llamada.

isSpeaking()

Promesa

chrome.tts.isSpeaking(
  callback?: function,
)

Comprueba si el motor está hablando en ese momento. En Mac OS X, el resultado es verdadero cada vez que el motor de voz del sistema está hablando, incluso si Chrome no inició la voz.

Parámetros

• callback

  Función opcional

  El parámetro callback se ve de la siguiente manera:

  (speaking: boolean)=>void

  • hablando

    boolean

    Verdadero si se habla, de lo contrario, falso.

Devuelve

• Promise<boolean>

  Chrome 101 y versiones posteriores

  Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para brindar retrocompatibilidad. No puedes usar ambos en la misma llamada a función. La promesa se resuelve con el mismo tipo que se pasa a la devolución de llamada.

pause()

chrome.tts.pause()

Pausa la síntesis de voz, potencialmente en medio de un discurso. Si se reanuda o detiene la llamada, se reanudará el audio.

resume()

chrome.tts.resume()

Si se pausó la voz, se reanuda la conversación desde donde la dejaste.

speak()

Promesa

chrome.tts.speak(
  utterance: string,
  options?: TtsOptions,
  callback?: function,
)

Reproduce texto con un motor de texto a voz.

Parámetros

• expresión

  cadena

  El texto que se va a hablar, ya sea texto sin formato o un documento de SSML completo y bien formado. Los motores de voz que no admiten SSML quitarán las etiquetas y dirán el texto. La longitud máxima del texto es de 32,768 caracteres.

• Opciones

  TtsOptions opcionales

  Las opciones de voz.

• callback

  Función opcional

  El parámetro callback se ve de la siguiente manera:

  ()=>void

Devuelve

• Promise<void>

  Chrome 101 y versiones posteriores

  Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para brindar retrocompatibilidad. No puedes usar ambos en la misma llamada a función. La promesa se resuelve con el mismo tipo que se pasa a la devolución de llamada.

stop()

chrome.tts.stop()

Detiene las voces actuales y limpia la cola de las declaraciones pendientes. Además, si se pausó la voz, se reanudará para que la próxima llamada hable.

Eventos

onVoicesChanged

Chrome 124 y versiones posteriores

chrome.tts.onVoicesChanged.addListener(
  callback: function,
)

Se llama cuando cambia la lista de tts.TtsVoice que mostrará getVoices.

Parámetros

• callback

  la función

  El parámetro callback se ve de la siguiente manera:

  ()=>void