browser.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 proporciona esta capacidad en Windows (con SAPI 5), macOS y ChromeOS, con las capacidades de síntesis de voz que proporciona el sistema operativo. En todas las plataformas, el usuario puede instalar extensiones que se registren como motores de voz alternativos.

Permisos

tts

Conceptos y uso

Genera voz

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

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

Para detener la lectura de inmediato, llama a stop():

browser.tts.stop();

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

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

También es recomendable especificar el idioma para que se elija un sintetizador que lo admita (y el dialecto regional, si corresponde).

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

De forma predeterminada, cada llamada a speak() interrumpe cualquier voz 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 que esta expresión se agregue a una cola de expresiones que se pronunciarán cuando finalice la expresión actual.

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

Puedes encontrar una descripción completa de todas las opciones en tts.speak(). No todos los motores de voz admitirán todas las opciones.

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

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

La devolución de llamada se muestra de inmediato, antes de que el motor comience a generar voz. El propósito de la devolución de llamada es alertarte sobre errores de sintaxis en el uso de la API de TTS, no detectar todos los errores posibles que podrían ocurrir en el proceso de sintetizar y generar voz. Para detectar estos errores, también debes usar un objeto de escucha de eventos, que 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 en las opciones a speak(), de la siguiente manera:

browser.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 expresión y, para los eventos de error, un mensaje de error opcional. Los tipos de eventos son los siguientes:

  • 'start': El motor comenzó a pronunciar la expresión.
  • 'word': Se alcanzó un límite de palabra. Usa event.charIndex para determinar la posición actual de la voz.
  • 'sentence': Se alcanzó el límite de una oración. Usa event.charIndex para determinar la posición actual de la voz.
  • 'marker': Se alcanzó un marcador de SSML. Usa event.charIndex para determinar la posición actual de la voz.
  • 'end': El motor terminó de pronunciar el enunciado.
  • 'interrupted': Otra llamada a speak() o stop() interrumpió este enunciado, por lo que no finalizó.
  • 'cancelled': Esta expresión se puso en cola, pero luego se canceló con 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 detalles.

Cuatro de los tipos de eventos ('end', 'interrupted', 'cancelled' y 'error') son finales. Después de que se reciba uno de esos eventos, esta expresión ya no hablará y no se recibirán eventos nuevos de esta expresión.

Es posible que algunas voces no admitan todos los tipos de eventos y que otras no envíen ningún evento. 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. Ambos se describen a continuación.

Lenguaje de marcado SSML

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

Por ejemplo:

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

No todos los motores de voz admitirán todas las etiquetas de SSML, y es posible que algunos no admitan SSML en absoluto, pero todos los motores deben ignorar cualquier SSML que no admitan y, aun así, pronunciar el texto subyacente.

Elige una voz

De forma predeterminada, Chrome elige la voz más adecuada para cada enunciado que quieras decir, según el idioma. En la mayoría de los sistemas Windows, macOS y ChromeOS, la síntesis de voz que proporciona el sistema operativo debería poder leer cualquier texto en, al menos, un idioma. Sin embargo, es posible que algunos usuarios tengan una variedad de voces disponibles, tanto de su sistema operativo como de los motores de voz implementados por otras extensiones de Chrome. En esos casos, puedes implementar código personalizado para elegir la voz adecuada o presentarle 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 argumento:

browser.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 browser.* desde Chrome 148

Enum

"start"

"end"

"word"

"sentence"

"marker"

"interrupted"

"cancelled"

"error"

"pause"

"resume"

TtsEvent

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

Propiedades

  • charIndex

    number 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 charIndex representa un punto en el texto al comienzo de la siguiente palabra que se pronunciará.

  • errorMessage

    string opcional

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

  • longitud

    number opcional

    Chrome 74 y versiones posteriores browser.* desde Chrome 148

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

  • tipo

    EventType

    El tipo puede ser start en cuanto se inicia la voz, word cuando se alcanza un límite de palabra, sentence cuando se alcanza un límite de oración, marker cuando se alcanza un elemento de marca SSML, end cuando se alcanza el final de la expresión, interrupted cuando se detiene o interrumpe la expresión 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 una expresión en particular en el medio, y resume si se reanuda la voz. Ten en cuenta que es posible que los eventos de pausa y reanudación no se activen si la voz se pausa entre las expresiones.

TtsOptions

Chrome 77 y versiones posteriores browser.* desde Chrome 148

Son las opciones de voz para el motor de TTS.

Propiedades

  • desiredEventTypes

    string[] opcional

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

  • enqueue

    booleano opcional

    Si es verdadero, pone en cola esta expresión si la TTS ya está en curso. Si es falso (el valor predeterminado), interrumpe cualquier voz actual y vacía la cola de voz antes de pronunciar esta nueva expresión.

  • extensionId

    string opcional

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

  • género

    VoiceGender opcional

    Obsoleto desde Chrome 77

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

    Es el género de la voz para la voz sintetizada.

  • lang

    string opcional

    Es el idioma que se usará para la síntesis, en el formato idioma-región. Ejemplos: "en", "en-US", "en-GB", "zh-CN".

  • pitch

    number opcional

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

  • de conversiones

    number opcional

    Es la velocidad de habla en relación con la velocidad predeterminada para esta voz. 1.0 es la velocidad predeterminada, que suele ser de 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 están estrictamente prohibidos, pero muchas voces restringirán aún más las tasas mínimas y máximas; por ejemplo, una voz en particular puede no hablar más rápido que 3 veces lo normal, incluso si especificas un valor superior a 3.0.

  • requiredEventTypes

    string[] opcional

    Son los tipos de eventos de TTS que debe admitir la voz.

  • voiceName

    string opcional

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

  • Volumen

    number opcional

    Volumen de voz entre 0 y 1 inclusive, donde 0 es el más bajo y 1 es el más alto, con un valor predeterminado de 1.0.

  • onEvent

    void optional

    Se llama a esta función con eventos que ocurren en el proceso de pronunciar la expresión.

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

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

    • evento

      TtsEvent

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

TtsVoice

Es 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

    string opcional

    Es el ID de la extensión que proporciona esta voz.

  • género

    VoiceGender opcional

    Obsoleto desde Chrome 70

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

    Es el género de esta voz.

  • lang

    string opcional

    Es el idioma que admite esta voz, en el formato idioma-región. Ejemplos: "en", "en-US", "en-GB", "zh-CN".

  • Control remoto

    booleano opcional

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

  • voiceName

    string opcional

    El nombre de la voz.

VoiceGender

Chrome 54 y versiones posteriores browser.* desde Chrome 148 Obsoleto desde Chrome 70

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

Enum

"male"

"female"

Métodos

getVoices()

browser.tts.getVoices(): Promise<TtsVoice[]>

Obtiene un array de todas las voces disponibles.

Muestra

  • Promise<TtsVoice[]>

    Chrome 101 y versiones posteriores browser.* desde Chrome 148

isSpeaking()

browser.tts.isSpeaking(): Promise<boolean>

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

Muestra

  • Promise<boolean>

    Chrome 101 y versiones posteriores browser.* desde Chrome 148

pause()

browser.tts.pause(): void

Pausa la síntesis de voz, posiblemente en medio de una expresión. Una llamada para reanudar o detener la voz quitará la pausa.

resume()

browser.tts.resume(): void

Si se pausó la voz, se reanuda desde donde se detuvo.

speak()

browser.tts.speak(
  utterance: string,
  options?: TtsOptions,
): Promise<void>

Habla con un motor de texto a voz.

Parámetros

  • enunciado

    string

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

  • opciones

    TtsOptions opcional

    Son las opciones de voz.

Muestra

  • Promise<void>

    Chrome 101 y versiones posteriores browser.* desde Chrome 148

    Se resuelve de inmediato, antes de que termine de hablar. Si se produce un error, se rechazará la promesa. Usa options.onEvent para obtener comentarios más detallados.

stop()

browser.tts.stop(): void

Detiene cualquier voz actual y vacía la cola de cualquier enunciado pendiente. Además, si se pausó la voz, ahora se reanudará para la próxima llamada a speak.

Eventos

onVoicesChanged

Chrome 124 y versiones posteriores browser.* desde Chrome 148 
browser.tts.onVoicesChanged.addListener(
  callback: function,
)

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

Parámetros

  • callback

    función

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

    () => void