QTextToSpeech Class

The QTextToSpeech class provides a convenient access to text-to-speech engines. More...

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

Public Types

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 }

Properties

Public Functions

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, const QObject *context, Functor &&functor)
(since 6.6) void synthesize(const QString &text, Functor &&functor)
QVoice voice() const
double volume() const

Public Slots

(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)

Signals

(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)

Static Public Members

QStringList availableEngines()

Detailed Description

Use say() to start reading text to the default audio device, and stop(), pause(), and resume() to control the reading of the text.

     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);

To synthesize text into PCM data for further processing, use synthesize().

Use findVoices() to get a list of matching voices, or use availableVoices() to get the list of voices that support the current locale. Change the locale property, using one of the availableLocales() that is a good match for the language that the input text is in, and for the accent of the desired voice output. This will change the list of available voices on most platforms. Then use one of the available voices in a call to setVoice().

Not every engine supports all features. Use the engineCapabilities() function to test which features are available, and adjust the usage of the class accordingly.

Note: Which locales and voices the engine supports depends usually on the Operating System configuration. E.g. on macOS, end users can install voices through the Accessibility panel in System Preferences.

Member Type Documentation

enum class QTextToSpeech::BoundaryHint

describes when speech should be stopped and paused.

ConstantValueDescription
QTextToSpeech::BoundaryHint::Default0Uses the engine specific default behavior.
QTextToSpeech::BoundaryHint::Immediate1The engine should stop playback immediately.
QTextToSpeech::BoundaryHint::Word2Stop speech when the current word is finished.
QTextToSpeech::BoundaryHint::Sentence3Stop speech when the current sentence is finished.
QTextToSpeech::BoundaryHint::Utterance (since Qt 6.6)4Stop speech when the current utterance is finished. An utterance is the block of text used in a call to say() or enqueue().

Note: These are hints to the engine. The current engine might not support all options.

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

This enum describes the capabilities of a text-to-speech engine.

ConstantValueDescription
QTextToSpeech::Capability::None0The engine implements none of the capabilities.
QTextToSpeech::Capability::Speak1 << 0The engine can play audio output from text.
QTextToSpeech::Capability::PauseResume1 << 1The engine can pause and then resume the audo output.
QTextToSpeech::Capability::WordByWordProgress1 << 2The engine emits the sayingWord() signal for each word that gets spoken.
QTextToSpeech::Capability::Synthesize1 << 3The engine can synthesize PCM audio data from text.

This enum was introduced in Qt 6.6.

The Capabilities type is a typedef for QFlags<Capability>. It stores an OR combination of Capability values.

See also engineCapabilities().

enum class QTextToSpeech::ErrorReason

This enum describes the current error, if any, of the QTextToSpeech engine.

ConstantValueDescription
QTextToSpeech::ErrorReason::NoError0No error has occurred.
QTextToSpeech::ErrorReason::Initialization1The backend could not be initialized, e.g. due to a missing driver or operating system requirement.
QTextToSpeech::ErrorReason::Configuration2The given backend configuration is inconsistent, e.g. due to wrong voice name or parameters.
QTextToSpeech::ErrorReason::Input3The given text could not be synthesized, e.g. due to invalid size or characters.
QTextToSpeech::ErrorReason::Playback4Audio playback failed e.g. due to missing audio device, wrong format or audio streaming interruption.

Use errorReason() to obtain the current error and errorString() to get the related error message.

See also errorOccurred().

enum QTextToSpeech::State

This enum describes the current state of the text-to-speech engine.

ConstantValueDescription
QTextToSpeech::Ready0The synthesizer is ready to start a new text. This is also the state after a text was finished.
QTextToSpeech::Speaking1Text is being spoken.
QTextToSpeech::Synthesizing4Text is being synthesized into PCM data. The synthesized() signal will be emitted with chunks of data.
QTextToSpeech::Paused2The synthesis was paused and can be resumed with resume().
QTextToSpeech::Error3An error has occurred. Details are given by errorReason().

See also QTextToSpeech::ErrorReason, errorReason(), and errorString().

Property Documentation

[since 6.4] engine : QString

This property holds the engine used to synthesize text to speech.

Changing the engine stops any ongoing speech.

On most platforms, changing the engine will update the list of available locales and available voices.

This property was introduced in Qt 6.4.

Access functions:

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

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

Notifier signal:

void engineChanged(const QString &engine)

[read-only, since 6.6] engineCapabilities : const Capabilities

This property holds the capabilities implemented by the current engine

This property was introduced in Qt 6.6.

Access functions:

QTextToSpeech::Capabilities engineCapabilities() const

Notifier signal:

void engineChanged(const QString &engine)

See also engine.

locale : QLocale

This property holds the current locale in use.

By default, the system locale is used.

On some platforms, changing the locale will update the list of available voices, and if the current voice is not available with the new locale, a new voice will be set.

Access functions:

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

Notifier signal:

void localeChanged(const QLocale &locale)

See also voice and findVoices().

pitch : double

This property holds the voice pitch, ranging from -1.0 to 1.0.

The default of 0.0 is the normal speech pitch.

Access functions:

double pitch() const
void setPitch(double pitch)

Notifier signal:

void pitchChanged(double pitch)

rate : double

This property holds the current voice rate, ranging from -1.0 to 1.0.

The default value of 0.0 is normal speech flow.

Access functions:

double rate() const
void setRate(double rate)

Notifier signal:

void rateChanged(double rate)

[read-only] state : const State

This property holds the current state of the speech synthesizer.

 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);
 }

Use say() to start synthesizing text with the current voice and locale.

Access functions:

QTextToSpeech::State state() const

Notifier signal:

void stateChanged(QTextToSpeech::State state)

voice : QVoice

This property holds the voice that will be used for the speech.

The voice needs to be one of the voices available for the engine.

On some platforms, setting the voice changes other voice attributes such as locale, pitch, and so on. These changes trigger the emission of signals.

Access functions:

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

Notifier signal:

void voiceChanged(const QVoice &voice)

See also findVoices().

volume : double

This property holds the current volume, ranging from 0.0 to 1.0.

The default value is the platform's default volume.

Access functions:

double volume() const
void setVolume(double volume)

Notifier signal:

void volumeChanged(double volume)

Member Function Documentation

[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)

Synthesizes the text into raw audio data.

This function synthesizes the speech asynchronously into raw audio data. When data is available, the functor will be called as functor(QAudioFormat format, QByteArray bytes), with format describing the format of the data in bytes; or as functor(QAudioBuffer &buffer).

The state property is set to Synthesizing when the synthesis starts, and to Ready once the synthesis is finished. While synthesizing, the functor might be called multiple times, possibly with changing values for format.

The functor can be a callable, like a lambda or free function, with an optional context object:

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

or a member function of the context object:

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

If context is destroyed, then the functor will no longer get called.

Note: This API requires that the engine has the Synthesize capability.

This function was introduced in Qt 6.6.

See also say() and stop().

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

Loads a text-to-speech engine from a plug-in that uses the default engine plug-in and constructs a QTextToSpeech object as the child of parent.

The default engine is platform-specific.

If the engine initializes correctly, then the state of the engine will change to QTextToSpeech::Ready; note that this might happen asynchronously. If the plugin fails to load, then state will be set to QTextToSpeech::Error.

See also availableEngines().

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

Loads a text-to-speech engine from a plug-in that matches parameter engine and constructs a QTextToSpeech object as the child of parent.

If engine is empty, the default engine plug-in is used. The default engine is platform-specific.

If the engine initializes correctly, the state of the engine will be set to QTextToSpeech::Ready. If the plugin fails to load, or if the engine fails to initialize, the engine's state will be set to QTextToSpeech::Error.

See also availableEngines().

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

Loads a text-to-speech engine from a plug-in that matches parameter engine and constructs a QTextToSpeech object as the child of parent, passing params through to the engine.

If engine is empty, the default engine plug-in is used. The default engine is platform-specific. Which key/value pairs in params are supported depends on the engine. See the engine documentation for details. Unsupported entries will be ignored.

If the engine initializes correctly, the state of the engine will be set to QTextToSpeech::Ready. If the plugin fails to load, or if the engine fails to initialize, the engine's state will be set to QTextToSpeech::Error.

This function was introduced in Qt 6.4.

See also availableEngines().

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

Destroys this QTextToSpeech object, stopping any speech.

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

This signal gets emitted just before the engine starts to synthesize the speech audio for id. The id is the value returned by a call to enqueue(), Applications can use this signal to make last-minute changes to voice attributes, or to track the process of text enqueued via enqueue().

This function was introduced in Qt 6.6.

See also enqueue(), synthesize(), and voice.

[static invokable] QStringList QTextToSpeech::availableEngines()

Gets the list of supported text-to-speech engine plug-ins.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

See also engine.

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

Returns the list of locales that are supported by the active engine.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

See also availableVoices() and findVoices().

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

Returns the list of voices available for the current locale.

Note: If no locale has been set, the system locale is used.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

See also availableLocales() and findVoices().

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

Adds utterance to the queue of texts to be spoken, and starts speaking. Returns the index of the text in the queue, or -1 in case of an error.

If the engine's state is currently Ready, utterance will be spoken immediately. Otherwise, the engine will start to speak utterance once it has finished speaking the current text.

Each time the engine proceeds to the next text entry in the queue, the aboutToSynthesize() signal gets emitted. This allows applications to keep track of the progress, and to make last-minute changes to voice attributes.

Calling stop() clears the queue. To pause the engine at the end of a text, use the Utterance boundary hint.

This function was introduced in Qt 6.6.

See also say(), stop(), aboutToSynthesize(), and synthesize().

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

This signal is emitted after an error occurred and the state has been set to QTextToSpeech::Error. The reason parameter specifies the type of error, and the errorString provides a human-readable error description.

QTextToSpeech::ErrorReason is not a registered metatype, so for queued connections, you will have to register it with Q_DECLARE_METATYPE() and qRegisterMetaType().

See also errorReason(), errorString(), and Creating Custom Qt Types.

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

Returns the reason why the engine has reported an error.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

See also state and errorOccurred().

[invokable] QString QTextToSpeech::errorString() const

Returns the current engine error message.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

See also errorOccurred().

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

Returns the list of voices that match the criteria in args.

The arguments in args are processed in order to assemble the list of voices that match all of them. An argument of type QString is matched against the name, of the voice, an argument of type QLocale is matched agains the voice's locale, etc. It is possible to specify only the Language or Territory of the desired voices, and the name can be matched against a regular expression.

This function returns all voices if the list of criteria is empty. Multiple criteria of the same type are not possible and will result in a compile-time error.

Note: Unless args includes the current locale, this function might need to change the locale of the engine to get the list of all voices. This is engine specific, but might impact ongoing speech synthesis. It is therefore advisable to not call this function unless the state is Ready.

This function was introduced in Qt 6.6.

See also availableVoices().

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

Pauses the current speech at boundaryHint.

Whether the boundaryHint is respected depends on the engine.

See also resume() and PauseResume.

[slot] void QTextToSpeech::resume()

Resume speaking after pause() has been called.

Note: On Android, resuming paused speech will restart from the beginning. This is a limitation of the underlying text-to-speech engine.

See also pause().

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

Starts speaking the text.

This function starts sythesizing the speech asynchronously, and reads the text to the default audio output device.

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

Note: All in-progress readings are stopped before beginning to read the recently synthesized text.

The current state is available using the state property, and is set to Speaking once the reading starts. When the reading is done, state will be set to Ready.

See also enqueue(), stop(), pause(), resume(), and synthesize().

[signal, since 6.6] void QTextToSpeech::sayingWord(const QString &word, qsizetype id, qsizetype start, qsizetype length)

This signal is emitted when the word, which is the slice of text indicated by start and length in the utterance id, gets played to the audio device.

Note: This signal requires that the engine has the WordByWordProgress capability.

This function was introduced in Qt 6.6.

See also Capability and say().

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

Sets the engine used by this QTextToSpeech object to engine, passing params through to the engine constructor.

Returns whether engine could be set successfully.

Which key/value pairs in params are supported depends on the engine. See the engine documentation for details. Unsupported entries will be ignored.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

Note: Setter function for property engine.

This function was introduced in Qt 6.4.

See also engine().

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

Stops the current reading at boundaryHint, and clears the queue of pending texts.

The reading cannot be resumed. Whether the boundaryHint is respected depends on the engine.

See also say(), enqueue(), and pause().