En esta página

QTextToSpeech Class

La clase QTextToSpeech ofrece un acceso sencillo a los motores de conversión de texto a voz. Más información...

Encabezado: #include <QTextToSpeech>
CMake: find_package(Qt6 REQUIRED COMPONENTS TextToSpeech)
target_link_libraries(mytarget PRIVATE Qt6::TextToSpeech)
qmake: QT += texttospeech
Heredado de: QObject

Tipos públicos

enum class BoundaryHint { Default, Immediate, Word, Sentence, Utterance }
flags Capabilities
(since 6.6) enum class Capability { None, Speak, PauseResume, WordByWordProgress, Synthesize }
enum class ErrorReason { NoError, Initialization, Configuration, Input, Playback }
enum State { Ready, Speaking, Synthesizing, Paused, Error }

Propiedades

Funciones públicas

QTextToSpeech(QObject *parent = nullptr)
QTextToSpeech(const QString &engine, QObject *parent = nullptr)
(since 6.4) QTextToSpeech(const QString &engine, const QVariantMap &params, QObject *parent = nullptr)
virtual ~QTextToSpeech() override
QList<QLocale> availableLocales() const
QList<QVoice> availableVoices() const
QString engine() const
QTextToSpeech::Capabilities engineCapabilities() const
QTextToSpeech::ErrorReason errorReason() const
QString errorString() const
(since 6.6) QList<QVoice> findVoices(Args &&... args) const
QLocale locale() const
double pitch() const
double rate() const
(since 6.4) bool setEngine(const QString &engine, const QVariantMap &params = QVariantMap())
QTextToSpeech::State state() const
(since 6.6) void synthesize(const QString &text, Functor &&functor)
(since 6.6) void synthesize(const QString &text, const QObject *context, Functor &&functor)
QVoice voice() const
double volume() const

Ranuras públicas

(since 6.6) qsizetype enqueue(const QString &utterance)
void pause(QTextToSpeech::BoundaryHint boundaryHint = QTextToSpeech::BoundaryHint::Default)
void resume()
void say(const QString &text)
void setLocale(const QLocale &locale)
void setPitch(double pitch)
void setRate(double rate)
void setVoice(const QVoice &voice)
void setVolume(double volume)
void stop(QTextToSpeech::BoundaryHint boundaryHint = QTextToSpeech::BoundaryHint::Default)

Señales

(since 6.6) void aboutToSynthesize(qsizetype id)
void engineChanged(const QString &engine)
void errorOccurred(QTextToSpeech::ErrorReason reason, const QString &errorString)
void localeChanged(const QLocale &locale)
void pitchChanged(double pitch)
void rateChanged(double rate)
(since 6.6) void sayingWord(const QString &word, qsizetype id, qsizetype start, qsizetype length)
void stateChanged(QTextToSpeech::State state)
void voiceChanged(const QVoice &voice)
void volumeChanged(double volume)

Miembros públicos estáticos

QStringList availableEngines()

Descripción detallada

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

    connect(ui.speakButton, &QPushButton::clicked, m_speech, [this]{
        m_speech->say(ui.plainTextEdit->toPlainText());
    });
    connect(ui.stopButton, &QPushButton::clicked, m_speech, [this]{
        m_speech->stop();
    });
    connect(ui.pauseButton, &QPushButton::clicked, m_speech, [this]{
        m_speech->pause();
    });
    connect(ui.resumeButton, &QPushButton::clicked, m_speech, &QTextToSpeech::resume);

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

Utilice findVoices() para obtener una lista de voces compatibles, o utilice availableVoices() para obtener la lista de voces que admiten la configuración regional actual. Modifique la propiedad locale utilizando una de las funciones availableLocales() que mejor se adapte al idioma del texto de entrada y al acento de la voz de salida 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 una llamada a setVoice().

No todos los motores admiten todas las funciones. Utiliza la función engineCapabilities() para comprobar qué funciones están disponibles y adapta el uso de la clase 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 sobre los tipos de miembro

enum class QTextToSpeech::BoundaryHint

describe cuándo se debe interrumpir y hacer una pausa en el discurso.

ConstanteValorDescripción
QTextToSpeech::BoundaryHint::Default0Utiliza el comportamiento predeterminado específico del motor.
QTextToSpeech::BoundaryHint::Immediate1El motor debe detener la reproducción inmediatamente.
QTextToSpeech::BoundaryHint::Word2Detener la lectura cuando termine la palabra actual.
QTextToSpeech::BoundaryHint::Sentence3Detener la reproducción de voz al finalizar la frase actual.
QTextToSpeech::BoundaryHint::Utterance (since Qt 6.6)4Detener la reproducción cuando finalice la expresión actual. Una expresión es el bloque de texto utilizado en una llamada a say() o enqueue().

Nota: Se trata de sugerencias para el motor. Es posible que el motor actual no admita todas las opciones.

[since 6.6] enum class QTextToSpeech::Capability
flags QTextToSpeech::Capabilities

Esta enumeración describe las capacidades de un motor de conversión de texto a voz.

ConstanteValorDescripción
QTextToSpeech::Capability::None0El motor no implementa ninguna de las capacidades.
QTextToSpeech::Capability::Speak1 << 0El motor puede reproducir audio a partir de texto.
QTextToSpeech::Capability::PauseResume1 << 1El motor puede pausar y reanudar la reproducción de audio.
QTextToSpeech::Capability::WordByWordProgress1 << 2El motor emite la señal sayingWord() por cada palabra que se pronuncia.
QTextToSpeech::Capability::Synthesize1 << 3El motor puede « synthesize » datos de audio PCM a partir de texto.

Esta enumeración se introdujo en Qt 6.6.

El tipo «Capabilities» es una definición de tipo (typedef) para QFlags<Capability>. Almacena una combinación OR de valores de Capability.

Véase también engineCapabilities().

enum class QTextToSpeech::ErrorReason

Esta enumeración describe el error actual, si lo hay, del motor « QTextToSpeech ».

ConstanteValorDescripción
QTextToSpeech::ErrorReason::NoError0No se ha producido ningún error.
QTextToSpeech::ErrorReason::Initialization1No se ha podido inicializar el backend, por ejemplo, debido a la falta de un controlador o a un requisito del sistema operativo.
QTextToSpeech::ErrorReason::Configuration2La configuración del backend proporcionada es incoherente, por ejemplo, debido a un nombre de voz o a parámetros incorrectos.
QTextToSpeech::ErrorReason::Input3No se ha podido sintetizar el texto proporcionado, por ejemplo, debido a un tamaño o caracteres no válidos.
QTextToSpeech::ErrorReason::Playback4Ha fallado la reproducción de audio, por ejemplo, debido a la falta de un dispositivo de audio, a un formato incorrecto o a una interrupción en la transmisión de audio.

Utiliza errorReason() para obtener el error actual y errorString() para obtener el mensaje de error correspondiente.

Véase también errorOccurred().

enum QTextToSpeech::State

Esta enumeración describe el estado actual del motor de conversión de texto a voz.

ConstanteValorDescripción
QTextToSpeech::Ready0El sintetizador está listo para comenzar con un nuevo texto. Este es también el estado tras finalizar un texto.
QTextToSpeech::Speaking1Se está reproduciendo el texto.
QTextToSpeech::Synthesizing4El texto se está sintetizando en datos PCM. La señal synthesized() se emitirá con bloques de datos.
QTextToSpeech::Paused2La síntesis se ha pausado y puede reanudarse con ` resume()`.
QTextToSpeech::Error3Se ha producido un error. Los detalles se obtienen mediante errorReason().

Véase también « QTextToSpeech::ErrorReason» , « errorReason()» y « errorString()».

Documentación de propiedades

[since 6.4] engine : QString

Esta propiedad contiene el motor utilizado para sintetizar texto a voz.

Al cambiar el motor, se interrumpe 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.

Esta enumeración se introdujo en Qt 6.4.

Funciones de acceso:

QString engine() const
bool setEngine(const QString &engine, const QVariantMap &params = QVariantMap())[see note below]

Nota: Esta función se puede invocar a través del sistema de metobjetos y desde QML. Véase Q_INVOKABLE.

Señal de notificador:

void engineChanged(const QString &engine)

[read-only, since 6.6] engineCapabilities : Capabilities

Esta propiedad contiene las capacidades implementadas por el motor actual

Esta enumeración se introdujo en Qt 6.6.

Funciones de acceso:

QTextToSpeech::Capabilities engineCapabilities() const

Señal de notificador:

void engineChanged(const QString &engine)

Véase también engine.

locale : QLocale

Esta propiedad contiene la configuración regional actualmente en uso.

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

En algunas plataformas, al cambiar la configuración regional se actualizará la lista de available voices, y si la voz actual no está disponible con la nueva configuración regional, se establecerá una nueva voz.

Funciones de acceso:

QLocale locale() const
void setLocale(const QLocale &locale)

Señal de notificación:

void localeChanged(const QLocale &locale)

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

pitch : double

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

El valor por defecto, 0,0, corresponde al tono de voz normal.

Funciones de acceso:

double pitch() const
void setPitch(double pitch)

Señal de notificación:

void pitchChanged(double pitch)

rate : double

Esta propiedad contiene la velocidad de voz actual, con un rango que va de -1,0 a 1,0.

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

Funciones de acceso:

double rate() const
void setRate(double rate)

Señal de notificación:

void rateChanged(double rate)

[read-only] state : State

Esta propiedad contiene el estado actual del sintetizador de voz.

void MainWindow::stateChanged(QTextToSpeech::State state)
{
    switch (state) {
    case QTextToSpeech::Speaking:
        ui.statusbar->showMessage(tr("Speech started..."));
        break;
    case QTextToSpeech::Ready:
        ui.statusbar->showMessage(tr("Speech stopped..."), 2000);
        break;
    case QTextToSpeech::Paused:
        ui.statusbar->showMessage(tr("Speech paused..."));
        break;
    default:
        ui.statusbar->showMessage(tr("Speech error!"));
        break;
    }

    ui.pauseButton->setEnabled(state == QTextToSpeech::Speaking);
    ui.resumeButton->setEnabled(state == QTextToSpeech::Paused);
    ui.stopButton->setEnabled(state == QTextToSpeech::Speaking || state == QTextToSpeech::Paused);
}

Utiliza ` say()` para comenzar a sintetizar texto con el ` voice ` y el ` locale` actuales.

Funciones de acceso:

QTextToSpeech::State state() const

Señal de notificación:

void stateChanged(QTextToSpeech::State state)

voice : QVoice

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

La voz debe ser una de las voices available compatibles con 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.

Funciones de acceso:

QVoice voice() const
void setVoice(const QVoice &voice)

Señal de notificador:

void voiceChanged(const QVoice &voice)

Véase también findVoices().

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.

Funciones de acceso:

double volume() const
void setVolume(double volume)

Señal de notificador:

void volumeChanged(double volume)

Documentación de funciones de miembro

[explicit] QTextToSpeech::QTextToSpeech(QObject *parent = nullptr)

Carga un motor de conversión de texto a voz desde un complemento que utiliza el complemento del motor predeterminado y crea un objeto `QTextToSpeech` como elemento secundario de ` parent`.

El motor predeterminado depende de la plataforma.

Si el motor se inicializa correctamente, el ` state ` del motor cambiará a ` QTextToSpeech::Ready`; ten en cuenta que esto puede ocurrir de forma asíncrona. Si el complemento no se carga, se establecerá ` state ` en ` QTextToSpeech::Error`.

Véase también availableEngines().

[explicit] QTextToSpeech::QTextToSpeech(const QString &engine, QObject *parent = nullptr)

Carga un motor de conversión de texto a voz desde un complemento que se ajusta al parámetro « engine » y crea un objeto `QTextToSpeech` como elemento secundario de ` parent`.

Si engine está vacío, se utiliza el complemento del motor por defecto. El motor por defecto depende de la plataforma.

Si el motor se inicializa correctamente, el parámetro « state » del motor se establecerá en « QTextToSpeech::Ready ». Si el complemento no se carga o si el motor no se inicializa, el parámetro « state » del motor se establecerá en « QTextToSpeech::Error ».

Véase también availableEngines().

[explicit, since 6.4] QTextToSpeech::QTextToSpeech(const QString &engine, const QVariantMap &params, QObject *parent = nullptr)

Carga un motor de conversión de texto a voz desde un complemento que se ajusta al parámetro ` engine ` y crea un objeto `QTextToSpeech` como elemento secundario de ` parent`, pasando ` params ` al motor.

Si engine está vacío, se utiliza el complemento del motor por defecto. El motor por defecto depende de la plataforma. Los pares clave/valor de params que se admiten dependen del motor. Consulta la documentación del motor para obtener más detalles. Las entradas no admitidas se ignorarán.

Si el motor se inicializa correctamente, el ` state ` del motor se establecerá en ` QTextToSpeech::Ready`. Si el complemento no se carga o si el motor no se inicializa, el ` state ` del motor se establecerá en ` QTextToSpeech::Error`.

Esta función se introdujo en Qt 6.4.

Véase también availableEngines().

[override virtual noexcept] QTextToSpeech::~QTextToSpeech()

Destruye este objeto « QTextToSpeech », deteniendo cualquier discurso.

[signal, since 6.6] void QTextToSpeech::aboutToSynthesize(qsizetype id)

Esta señal se emite justo antes de que el motor comience a sintetizar el audio de voz para id. El id es el valor devuelto por una llamada a enqueue(). 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().

Esta función se introdujo en Qt 6.6.

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

[static invokable] QStringList QTextToSpeech::availableEngines()

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

Nota: Esta función se puede invocar a través del sistema de metaobjetos y desde QML. Véase Q_INVOKABLE.

Véase también engine.

[invokable] QList<QLocale> QTextToSpeech::availableLocales() const

Devuelve la lista de configuraciones regionales compatibles con el objeto engine activo.

Nota: Esta función se puede invocar a través del sistema de metaobjetos y desde QML. Véase Q_INVOKABLE.

Véase también availableVoices() y findVoices().

[invokable] QList<QVoice> QTextToSpeech::availableVoices() const

Devuelve la lista de voces disponibles para el locale actual.

Nota: Si no se ha establecido ninguna configuración regional, se utiliza la configuración regional del sistema.

Nota: Esta función se puede invocar a través del sistema de metaobjetos y desde QML. Véase Q_INVOKABLE.

Véase también ` availableLocales()` y ` findVoices()`.

[slot, since 6.6] qsizetype QTextToSpeech::enqueue(const QString &utterance)

Añade utterance a la cola de textos que se van a leer en voz alta e inicia la lectura. Devuelve el índice del texto en la cola o -1 en caso de error.

Si el « state » del motor es actualmente « Ready », se leerá « utterance » inmediatamente. 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. Para pausar el motor al final de un texto, utiliza la indicación de límite Utterance.

Esta función se introdujo en Qt 6.6.

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

[signal] void QTextToSpeech::errorOccurred(QTextToSpeech::ErrorReason reason, const QString &errorString)

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

QTextToSpeech::ErrorReason no es un metatipo registrado, por lo que, para las conexiones en cola, tendrás que registrarlo con Q_DECLARE_METATYPE() y qRegisterMetaType().

Véase también errorReason(), errorString() y Creación de tipos Qt personalizados.

[invokable] QTextToSpeech::ErrorReason QTextToSpeech::errorReason() const

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

Nota: Esta función se puede invocar a través del sistema de metaobjetos y desde QML. Véase Q_INVOKABLE.

Véase también state y errorOccurred().

[invokable] QString QTextToSpeech::errorString() const

Devuelve el mensaje de error actual del motor.

Nota: Esta función se puede invocar a través del sistema de metaobjetos y desde QML. Véase Q_INVOKABLE.

Véase también errorOccurred().

[since 6.6] template <typename... Args> QList<QVoice> QTextToSpeech::findVoices(Args &&... args) const

Devuelve la lista de voces que cumplen los criterios especificados en args.

Los argumentos de args se procesan para elaborar la lista de voces que cumplen todos ellos. Un argumento de tipo QString se compara con el name de la voz; un argumento de tipo QLocale se compara con el locale de la voz, etc. Es posible especificar únicamente el Language o el Territory de las voces deseadas, y el nombre se puede comparar con un regular expression.

Esta función devuelve todas las voces si la lista de criterios está vacía. No es posible utilizar varios criterios del mismo tipo, ya que provocaría un error en tiempo de compilación.

Nota: A menos que args incluya el locale actual, es posible que esta función tenga que cambiar la configuración regional del motor para obtener la lista de todas las voces. Esto depende del motor, pero podría afectar a la síntesis de voz en curso. Por lo tanto, se recomienda no llamar a esta función a menos que el state sea Ready.

Esta función se introdujo en Qt 6.6.

Véase también availableVoices().

[slot] void QTextToSpeech::pause(QTextToSpeech::BoundaryHint boundaryHint = QTextToSpeech::BoundaryHint::Default)

Pausa la reproducción actual en boundaryHint.

Que se respete el valor de « boundaryHint » depende de « engine ».

Véase también resume() y PauseResume.

[slot] void QTextToSpeech::resume()

Reanudar la lectura en voz alta después de que se haya llamado a pause().

Nota: En Android, al reanudar la reproducción de voz pausada, esta se reiniciará desde el principio. Se trata de una limitación del motor de conversión de texto a voz subyacente.

Véase también pause().

[slot] void QTextToSpeech::say(const QString &text)

Comienza a reproducir el archivo « text ».

Esta función comienza a sintetizar el discurso de forma asíncrona y lee el texto en el dispositivo de salida de audio predeterminado.

    connect(ui.speakButton, &QPushButton::clicked, m_speech, [this]{
        m_speech->say(ui.plainTextEdit->toPlainText());
    });

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

El estado actual está disponible mediante la propiedad « state » y se establece en « Speaking » una vez que comienza la lectura. Cuando finaliza la lectura, « state » se establecerá en « Ready ».

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

[signal, since 6.6] void QTextToSpeech::sayingWord(const QString &word, qsizetype id, qsizetype start, qsizetype 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 disponga de la capacidad « WordByWordProgress ».

Esta función se introdujo en Qt 6.6.

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

[invokable, since 6.4] bool QTextToSpeech::setEngine(const QString &engine, const QVariantMap &params = QVariantMap())

Establece el motor utilizado por este objeto ` QTextToSpeech ` en ` engine`, pasando ` params ` al constructor del motor.

Devuelve si se ha podido establecer correctamente engine.

Los pares clave/valor de params que se admiten dependen del motor. Consulte la documentación del motor para obtener más detalles. Las entradas no admitidas se ignorarán.

Nota: Esta función se puede invocar a través del sistema de metaobjetos y desde QML. Véase Q_INVOKABLE.

Nota: Funciónde asignación para la propiedad engine.

Esta función se introdujo en Qt 6.4.

Véase también engine().

[slot] void QTextToSpeech::stop(QTextToSpeech::BoundaryHint boundaryHint = QTextToSpeech::BoundaryHint::Default)

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()` y ` pause()`.

[since 6.6] template <typename Functor> void QTextToSpeech::synthesize(const QString &text, Functor &&functor)

[since 6.6] template <typename Functor> void QTextToSpeech::synthesize(const QString &text, const QObject *context, Functor &&functor)

Sintetiza el archivo « text » en datos de audio sin procesar.

Esta función sintetiza el discurso de forma asíncrona en datos de audio sin procesar. Cuando haya datos disponibles, se llamará a la función « functor » como « functor(QAudioFormat format, QByteArray bytes) », donde « format » describe el « format » de los datos en « bytes »; o como « functor(QAudioBuffer &buffer) ».

La propiedad state se establece en Synthesizing al inicio de la síntesis, y en Ready una vez finalizada la síntesis. Durante la síntesis, la functor puede llamarse varias veces, posiblemente con valores cambiantes para format.

La función functor puede ser una función invocable, como una lambda o una función libre, con un objeto context opcional:

tts.synthesize("Hello world", [](const QAudioFormat &format, const QByteArray &bytes){
    // process data according to format
});

o una función miembro del objeto ` context `:

struct PCMProcessor : QObject
{
    void processData(const QAudioFormat &format, const QByteArray &bytes)
    {
        // process data according to format
    }
} processor;
tts.synthesize("Hello world", &processor, &PCMProcessor::processData);

Si se destruye ` context `, el ` functor ` dejará de ser invocado.

Nota: Esta API requiere que el motor disponga de la capacidad « Synthesize ».

Estas funciones se introdujeron en Qt 6.6.

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

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