En esta página

TextToSpeech QML Type

El tipo TextToSpeech permite acceder a motores de conversión de texto a voz. Más información...

Import Statement: import QtTextToSpeech

Propiedades

Señales

Métodos

Descripción detallada

Utiliza say() para iniciar la lectura del texto en el dispositivo de audio predeterminado, y stop(), pause() y resume() para controlar la lectura del texto.

    TextToSpeech {
        id: tts
        volume: volumeSlider.value
        pitch: pitchSlider.value
        rate: rateSlider.value
    ...

        RowLayout {
            Button {
                text: qsTr("Speak")
                enabled: [TextToSpeech.Paused, TextToSpeech.Ready].includes(tts.state)
                onClicked: {
                    let voices = tts.availableVoices()
                    tts.voice = voices[voicesComboBox.currentIndex]
                    tts.say(input.text)
                }
            }
            Button {
                text: qsTr("Pause")
                enabled: tts.state == TextToSpeech.Speaking
                onClicked: tts.pause()
                visible: tts.engineCapabilities & TextToSpeech.Capabilities.PauseResume
            }
            Button {
                text: qsTr("Resume")
                enabled: tts.state == TextToSpeech.Paused
                onClicked: tts.resume()
                visible: tts.engineCapabilities & TextToSpeech.Capabilities.PauseResume
            }
    ...

Para sintetizar texto en datos PCM para su posterior procesamiento, utiliza synthesize().

Para establecer una voz, utiliza la propiedad asociada « VoiceSelector » de la siguiente manera:

TextToSpeech {
    VoiceSelector.locale: Qt.locale("en_UK")
    VoiceSelector.gender: Voice.Male
}

Se utilizará la primera voz que cumpla todos los criterios especificados. Si ninguna voz cumple todos los criterios, la voz no cambiará.

Como alternativa, utiliza findVoices() para obtener una lista de voces que coincidan, o utiliza availableVoices() para obtener la lista de voces compatibles con la configuración regional actual. Modifica la propiedad « locale » utilizando una de las funciones « availableLocales()» que mejor se adapte al idioma del texto de entrada y al acento de la salida de voz deseada. Esto modificará la lista de voces disponibles en la mayoría de las plataformas. A continuación, utiliza una de las voces disponibles en la propiedad « voice ».

No todos los motores admiten todas las funciones. Utiliza la función engineCapabilities() para comprobar qué funciones están disponibles y adapta el uso del tipo en consecuencia.

Nota: Las configuraciones regionales y las vocesque admite el motor suelen depender de la configuración del sistema operativo. Por ejemplo, en macOS, los usuarios finales pueden instalar voces a través del panel de Accesibilidad en Preferencias del Sistema.

Documentación de las propiedades

engine : string

El motor utilizado para sintetizar texto a voz.

Al cambiar de motor, se detiene cualquier reproducción de voz en curso.

En la mayoría de las plataformas, al cambiar el motor se actualizará la lista de available locales y available voices.

engineCapabilities : enumeration [since 6.6]

Esta propiedad contiene las capacidades implementadas por el motor actual.

Esta propiedad se introdujo en Qt 6.6.

Véase también engine y QTextToSpeech::Capability.

engineParameters : map

Esta propiedad contiene parámetros específicos del motor.

Véase también engine.

locale : locale

Esta propiedad contiene la configuración regional que se está utilizando actualmente.

Por defecto, se utiliza la configuración regional del sistema.

Véase también voice.

pitch : double

Esta propiedad determina el tono de la voz, con un rango que va de -1,0 a 1,0.

El valor predeterminado, 0,0, corresponde al tono de voz normal.

rate : double

Esta propiedad contiene la velocidad actual de la voz, que oscila entre -1,0 y 1,0.

El valor por defecto, 0,0, corresponde al flujo normal del habla.

state : enumeration

Esta propiedad contiene el estado actual del sintetizador de voz.

        onStateChanged: updateStateLabel(state)

        function updateStateLabel(state)
        {
            switch (state) {
                case TextToSpeech.Ready:
                    statusLabel.text = qsTr("Ready")
                    break
                case TextToSpeech.Speaking:
                    statusLabel.text = qsTr("Speaking")
                    break
                case TextToSpeech.Paused:
                    statusLabel.text = qsTr("Paused...")
                    break
                case TextToSpeech.Error:
                    statusLabel.text = qsTr("Error!")
                    break
            }
        }

Véase también QTextToSpeech::State, say(), stop() y pause().

voice : voice

Esta propiedad contiene la voz que se utilizará para el discurso.

La voz debe ser una de las que figuran en voices available para el motor.

En algunas plataformas, al configurar la voz se modifican otros atributos de voz, como « locale », « pitch », etc. Estos cambios activan la emisión de señales.

volume : double

Esta propiedad contiene el volumen actual, que oscila entre 0,0 y 1,0.

El valor por defecto es el volumen predeterminado de la plataforma.

Documentación de Signal

[since 6.6] aboutToSynthesize(number id)

Esta señal se emite justo antes de que el motor comience a sintetizar el audio de voz para id. Las aplicaciones pueden utilizar esta señal para realizar cambios de última hora en los atributos de voice, o para realizar un seguimiento del proceso del texto puesto en cola mediante enqueue().

Nota: El controlador correspondiente es onAboutToSynthesize.

Esta señal se introdujo en Qt 6.6.

Véase también enqueue() y voice.

void errorOccurred(enumeration reason, string errorString)

Esta señal se emite después de que se haya producido un error y se haya establecido el parámetro « state » en « TextToSpeech.Error ». El parámetro « reason » especifica el tipo de error, y el parámetro « errorString » proporciona una descripción del error comprensible para el usuario.

Nota: El controlador correspondiente es onErrorOccurred.

Véase también state, errorReason() y errorString().

[since 6.6] sayingWord(string word, int id, int start, int length)

Esta señal se emite cuando el « word » —que es el fragmento de texto indicado por start y length en la expresión id — se reproduce en el dispositivo de audio.

Nota: Esta señal requiere que el motor cuente con la capacidad « WordByWordProgress ».

El siguiente código resalta la palabra que se pronuncia en un TextArea input :

        onSayingWord: (word, id, start, length)=> {
            input.select(start, start + length)
        }

Nota: El controlador correspondiente es onSayingWord.

Esta señal se introdujo en Qt 6.6.

Véase también QTextToSpeech::Capability y say().

Documentación del método

list<string> availableEngines()

Contiene la lista de complementos de motores de conversión de texto a voz compatibles.

list<voice> availableLocales()

Contiene la lista de configuraciones regionales compatibles con el archivo « engine » activo.

list<voice> availableVoices()

Contiene la lista de voces disponibles para el locale actual.

[since 6.6] int enqueue(string utterance)

Añade utterance a la cola de texto que se va a leer en voz alta y comienza a leerlo.

Si el estado « state » del motor es actualmente « Ready », se leerá en voz alta « utterance » de inmediato. De lo contrario, el motor comenzará a leer « utterance » una vez que haya terminado de leer el texto actual.

Cada vez que el motor pasa a la siguiente entrada de texto de la cola, se emite la señal aboutToSynthesize(). Esto permite a las aplicaciones realizar un seguimiento del progreso y realizar cambios de última hora en los atributos de voz.

Al llamar a stop() se borra la cola.

Este método se introdujo en Qt 6.6.

Véase también say(), stop() y aboutToSynthesize().

enumeration errorReason()

Devuelve el motivo por el que el motor ha notificado un error.

Véase también QTextToSpeech::ErrorReason.

string errorString()

Devuelve el mensaje de error actual del motor.

[since 6.6] list<voice> findVoices(map criteria)

Devuelve la lista de voces que coinciden con todos los criterios especificados en criteria.

criteria Es un mapa que relaciona el nombre de la propiedad de la voz con el valor de la propiedad, y admite combinaciones de criterios de búsqueda como, por ejemplo:

let daniel = tts.findVoices({
    "name": "Daniel"
})
let maleEnglish = tts.findVoices({
    "gender": Voice.Male,
    "language": Qt.locale('en')
})

Este método se introdujo en Qt 6.6.

Véase también VoiceSelector.

void pause(BoundaryHint boundaryHint)

Pausa la reproducción actual en boundaryHint.

Que se respete la dirección boundaryHint depende de engine.

Véase también resume(), QTextToSpeech::BoundaryHint y PauseResume.

void resume()

Reanuda la ejecución tras la llamada a pause().

Véase también pause().

void say(string text)

Comienza a sintetizar el text.

Esta función inicia la síntesis de voz de forma asíncrona y lee el texto en el dispositivo de salida de audio predeterminado.

        RowLayout {
            Button {
                text: qsTr("Speak")
                enabled: [TextToSpeech.Paused, TextToSpeech.Ready].includes(tts.state)
                onClicked: {
                    let voices = tts.availableVoices()
                    tts.voice = voices[voicesComboBox.currentIndex]
                    tts.say(input.text)
                }
            }

Nota: Todas las lecturas en curso se detienen antes de comenzar a leer el texto recién sintetizado.

El estado actual se puede consultar mediante la propiedad ` state ` y se establece en ` QTextToSpeech::Speaking ` una vez que comienza la lectura. Cuando finaliza la lectura, ` state ` se establecerá en ` QTextToSpeech::Ready`.

Véanse también stop(), pause() y resume().

void stop(BoundaryHint boundaryHint)

Detiene la lectura actual en boundaryHint y borra la cola de mensajes pendientes.

La lectura no se puede reanudar. El cumplimiento de ` boundaryHint ` depende del motor.

Véase también say(), enqueue(), pause() y QTextToSpeech::BoundaryHint.

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.