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 ¶ms, 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 ¶ms = 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.
| Constante | Valor | Descripción |
|---|---|---|
QTextToSpeech::BoundaryHint::Default | 0 | Utiliza el comportamiento predeterminado específico del motor. |
QTextToSpeech::BoundaryHint::Immediate | 1 | El motor debe detener la reproducción inmediatamente. |
QTextToSpeech::BoundaryHint::Word | 2 | Detener la lectura cuando termine la palabra actual. |
QTextToSpeech::BoundaryHint::Sentence | 3 | Detener la reproducción de voz al finalizar la frase actual. |
QTextToSpeech::BoundaryHint::Utterance (since Qt 6.6) | 4 | Detener 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.
| Constante | Valor | Descripción |
|---|---|---|
QTextToSpeech::Capability::None | 0 | El motor no implementa ninguna de las capacidades. |
QTextToSpeech::Capability::Speak | 1 << 0 | El motor puede reproducir audio a partir de texto. |
QTextToSpeech::Capability::PauseResume | 1 << 1 | El motor puede pausar y reanudar la reproducción de audio. |
QTextToSpeech::Capability::WordByWordProgress | 1 << 2 | El motor emite la señal sayingWord() por cada palabra que se pronuncia. |
QTextToSpeech::Capability::Synthesize | 1 << 3 | El 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 ».
| Constante | Valor | Descripción |
|---|---|---|
QTextToSpeech::ErrorReason::NoError | 0 | No se ha producido ningún error. |
QTextToSpeech::ErrorReason::Initialization | 1 | No se ha podido inicializar el backend, por ejemplo, debido a la falta de un controlador o a un requisito del sistema operativo. |
QTextToSpeech::ErrorReason::Configuration | 2 | La configuración del backend proporcionada es incoherente, por ejemplo, debido a un nombre de voz o a parámetros incorrectos. |
QTextToSpeech::ErrorReason::Input | 3 | No se ha podido sintetizar el texto proporcionado, por ejemplo, debido a un tamaño o caracteres no válidos. |
QTextToSpeech::ErrorReason::Playback | 4 | Ha 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.
| Constante | Valor | Descripción |
|---|---|---|
QTextToSpeech::Ready | 0 | El sintetizador está listo para comenzar con un nuevo texto. Este es también el estado tras finalizar un texto. |
QTextToSpeech::Speaking | 1 | Se está reproduciendo el texto. |
QTextToSpeech::Synthesizing | 4 | El texto se está sintetizando en datos PCM. La señal synthesized() se emitirá con bloques de datos. |
QTextToSpeech::Paused | 2 | La síntesis se ha pausado y puede reanudarse con ` resume()`. |
QTextToSpeech::Error | 3 | Se 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 ¶ms = 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 ¶ms, 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 ¶ms = 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.
© 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.