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 } |
enum class | ErrorReason { NoError, Initialization, Configuration, Input, Playback } |
enum | State { Ready, Speaking, Paused, Error } |
Properties
Public Functions
QTextToSpeech(QObject *parent = nullptr) | |
QTextToSpeech(const QString &engine, QObject *parent = nullptr) | |
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::ErrorReason | errorReason() const |
QString | errorString() const |
QLocale | locale() const |
double | pitch() const |
double | rate() const |
bool | setEngine(const QString &engine, const QVariantMap ¶ms = QVariantMap()) |
QTextToSpeech::State | state() const |
QVoice | voice() const |
double | volume() const |
Public Slots
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
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) |
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().
The list of voices the engine supports for the current language is returned by availableVoices(). Change the language using setLocale(), 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().
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.
Constant | Value | Description |
---|---|---|
QTextToSpeech::BoundaryHint::Default | 0 | Uses the engine specific default behavior. |
QTextToSpeech::BoundaryHint::Immediate | 1 | The engine should stop playback immediately. |
QTextToSpeech::BoundaryHint::Word | 2 | Stop speech when the current word is finished. |
QTextToSpeech::BoundaryHint::Sentence | 3 | Stop speech when the current sentence is finished. |
Note: These are hints to the engine. The current engine might not support all options.
enum class QTextToSpeech::ErrorReason
This enum describes the current error, if any, of the QTextToSpeech engine.
Constant | Value | Description |
---|---|---|
QTextToSpeech::ErrorReason::NoError | 0 | No error has occurred. |
QTextToSpeech::ErrorReason::Initialization | 1 | The backend could not be initialized, e.g. due to a missing driver or operating system requirement. |
QTextToSpeech::ErrorReason::Configuration | 2 | The given backend configuration is inconsistent, e.g. due to wrong voice name or parameters. |
QTextToSpeech::ErrorReason::Input | 3 | The given text could not be synthesized, e.g. due to invalid size or characters. |
QTextToSpeech::ErrorReason::Playback | 4 | Audio 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.
Constant | Value | Description |
---|---|---|
QTextToSpeech::Ready | 0 | The synthesizer is ready to start a new text. This is also the state after a text was finished. |
QTextToSpeech::Speaking | 1 | Text is being spoken. |
QTextToSpeech::Paused | 2 | The synthesis was paused and can be resumed with resume(). |
QTextToSpeech::Error | 3 | An 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 ¶ms = 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) |
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.
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) |
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
[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 ¶ms, 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]
QTextToSpeech::~QTextToSpeech()
Destroys this QTextToSpeech object, stopping any speech.
[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.
[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.
[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().
[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().
[slot]
void QTextToSpeech::resume()
Resume speaking after pause() has been called.
See also pause().
[slot]
void QTextToSpeech::say(const QString &text)
Starts synthesizing 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 stop(), pause(), and resume().
[invokable, since 6.4]
bool QTextToSpeech::setEngine(const QString &engine, const QVariantMap ¶ms = 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.
The reading cannot be resumed. Whether the boundaryHint is respected depends on the engine.
© 2024 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.