QTextToSpeech Class

Member Function Documentation

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.

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.

See also engine.

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

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

See also availableVoices() and findVoices().

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

Returns the list of voices available for the current locale.

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.

See also state and errorOccurred().

[invokable] QString QTextToSpeech::errorString() const

Returns the current engine error message.

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.

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.

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

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.

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.

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