Revision control
++ // Copyright (C) 2015 The Qt Company Ltd.
++ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only
++ // Qt-Security score:significant reason:default
++
++ #include "qtexttospeech.h"
++ #include "qtexttospeech_p.h"
++
++ #include <QtCore/qcborarray.h>
++ #include <QtCore/qdebug.h>
++ #include <QtCore/private/qfactoryloader_p.h>
++
++ #include <QtMultimedia/qaudiobuffer.h>
++
++ QT_BEGIN_NAMESPACE
++
++ using namespace Qt::StringLiterals;
++
++ Q_GLOBAL_STATIC_WITH_ARGS(QFactoryLoader, loader,
++ ("org.qt-project.qt.speech.tts.plugin/6.0",
++ QLatin1String("/texttospeech")))
++
++ QMutex QTextToSpeechPrivate::m_mutex;
++
++ QTextToSpeechPrivate::QTextToSpeechPrivate(QTextToSpeech *speech)
++ : q_ptr(speech)
++ {
++ qRegisterMetaType<QTextToSpeech::State>();
++ qRegisterMetaType<QTextToSpeech::ErrorReason>();
++ }
++
++ QTextToSpeechPrivate::~QTextToSpeechPrivate()
++ {
++ }
++
++ void QTextToSpeechPrivate::setEngineProvider(const QString &engine, const QVariantMap ¶ms)
++ {
++ Q_Q(QTextToSpeech);
++
++ q->stop(QTextToSpeech::BoundaryHint::Immediate);
++ m_engine.reset();
++
++ m_providerName = engine;
++ if (m_providerName.isEmpty()) {
++ const auto plugins = QTextToSpeechPrivate::plugins();
++ int priority = -1;
++ for (const auto &&[provider, metadata] : plugins.asKeyValueRange()) {
++ const int pluginPriority = metadata.value(QStringLiteral("Priority")).toInteger();
++ if (pluginPriority > priority) {
++ priority = pluginPriority;
++ m_providerName = provider;
++ }
++ }
++ if (m_providerName.isEmpty()) {
++ qCritical() << "No text-to-speech plug-ins were found.";
++ return;
++ }
++ }
++ if (!loadMeta()) {
++ qCritical() << "Text-to-speech plug-in" << m_providerName << "is not supported.";
++ return;
++ }
++ loadPlugin();
++ if (m_plugin) {
++ QString errorString;
++ m_engine.reset(m_plugin->createTextToSpeechEngine(params, nullptr, &errorString));
++ if (!m_engine) {
++ qCritical() << "Error creating text-to-speech engine" << m_providerName
++ << (errorString.isEmpty() ? QStringLiteral("") : (QStringLiteral(": ") + errorString));
++ }
++ } else {
++ qCritical() << "Error loading text-to-speech plug-in" << m_providerName;
++ }
++
++ if (m_engine) {
++ // We have to maintain the public state separately from the engine's actual
++ // state, as we use it to manage queued texts
++ updateState(m_engine->state());
++ QObjectPrivate::connect(m_engine.get(), &QTextToSpeechEngine::stateChanged,
++ this, &QTextToSpeechPrivate::updateState);
++ // The other engine signals are directly forwarded to public API signals
++ QObject::connect(m_engine.get(), &QTextToSpeechEngine::errorOccurred,
++ q, &QTextToSpeech::errorOccurred);
++ QObject::connect(m_engine.get(), &QTextToSpeechEngine::sayingWord,
++ q, [this, q](const QString &word, qsizetype start, qsizetype length){
++ emit q->sayingWord(word, m_currentUtterance, start, length);
++ });
++ } else {
++ m_providerName.clear();
++ }
++ }
++
++ bool QTextToSpeechPrivate::loadMeta()
++ {
++ m_plugin = nullptr;
++ m_metaData = QCborMap();
++
++ QList<QCborMap> candidates = QTextToSpeechPrivate::plugins().values(m_providerName);
++
++ int versionFound = -1;
++
++ // figure out which version of the plugin we want
++ for (int i = 0; i < candidates.size(); ++i) {
++ QCborMap meta = candidates[i];
++ if (int ver = meta.value(QLatin1String("Version")).toInteger(); ver > versionFound) {
++ versionFound = ver;
++ m_metaData = std::move(meta);
++ }
++ }
++
++ if (m_metaData.isEmpty()) {
++ m_metaData.insert(QLatin1String("index"), -1); // not found
++ return false;
++ }
++
++ return true;
++ }
++
++ void QTextToSpeechPrivate::loadPlugin()
++ {
++ int idx = m_metaData.value(QLatin1String("index")).toInteger();
++ if (idx < 0) {
++ m_plugin = nullptr;
++ return;
++ }
++ m_plugin = qobject_cast<QTextToSpeechPlugin *>(loader()->instance(idx));
++ }
++
++ QMultiHash<QString, QCborMap> QTextToSpeechPrivate::plugins(bool reload)
++ {
++ static QMultiHash<QString, QCborMap> plugins;
++ static bool alreadyDiscovered = false;
++ QMutexLocker lock(&m_mutex);
++
++ if (reload == true)
++ alreadyDiscovered = false;
++
++ if (!alreadyDiscovered) {
++ loadPluginMetadata(plugins);
++ alreadyDiscovered = true;
++ }
++ return plugins;
++ }
++
++ void QTextToSpeechPrivate::loadPluginMetadata(QMultiHash<QString, QCborMap> &list)
++ {
++ QFactoryLoader *l = loader();
++ QList<QPluginParsedMetaData> meta = l->metaData();
++ for (int i = 0; i < meta.size(); ++i) {
++ QCborMap obj = meta.at(i).value(QtPluginMetaDataKeys::MetaData).toMap();
++ obj.insert(QLatin1String("index"), i);
++ list.insert(obj.value(QLatin1String("Provider")).toString(), obj);
++ }
++ }
++
++ void QTextToSpeechPrivate::updateState(QTextToSpeech::State newState)
++ {
++ Q_Q(QTextToSpeech);
++ if (m_state == newState)
++ return;
++
++ if (newState == QTextToSpeech::Ready) {
++ // If we have more text to process, start the next request immediately,
++ // and ignore the transition to Ready (don't emit the signals).
++ if (!m_pendingUtterances.isEmpty()) {
++ const QString nextText = m_pendingUtterances.first();
++ // QTextToSpeech::pause prepends an empty entry to request a pause
++ if (nextText.isEmpty()) {
++ m_state = QTextToSpeech::Paused;
++ m_pendingUtterances.dequeue();
++ } else {
++ const auto nextFunction = [this]{
++ switch (m_state) {
++ case QTextToSpeech::Synthesizing:
++ return &QTextToSpeechEngine::synthesize;
++ case QTextToSpeech::Speaking:
++ case QTextToSpeech::Paused:
++ return &QTextToSpeechEngine::say;
++ default:
++ break;
++ }
++ return decltype(&QTextToSpeechEngine::synthesize)(nullptr);
++ }();
++ if (nextFunction) {
++ const auto oldState = m_state;
++ emit q->aboutToSynthesize(m_currentUtterance);
++ // connected slot could have called pause or stop, in which
++ // case the state changed or the pendingTexts got reset.
++ if (m_state == oldState && !m_pendingUtterances.isEmpty()) {
++ m_pendingUtterances.dequeue();
++ ++m_currentUtterance;
++ (m_engine.get()->*nextFunction)(nextText);
++ return;
++ } else if (m_state == QTextToSpeech::Paused) {
++ // In case of pause(), empty strings got inserted.
++ // We are already idle, so remove them again.
++ while (!m_pendingUtterances.isEmpty() && m_pendingUtterances.first().isEmpty())
++ m_pendingUtterances.dequeue();
++ return;
++ }
++ // in case of stop(), disconnect and update the state
++ disconnectSynthesizeFunctor();
++ }
++ }
++ } else {
++ // If we are done synthesizing and the functor-overload was used,
++ // clear the temporary connection.
++ disconnectSynthesizeFunctor();
++ }
++ }
++ m_state = newState;
++ emit q->stateChanged(newState);
++ }
++
++ void QTextToSpeechPrivate::disconnectSynthesizeFunctor()
++ {
++ if (m_slotObject) {
++ m_slotObject->destroyIfLastRef();
++ m_slotObject = nullptr;
++ m_engine->disconnect(m_synthesizeConnection);
++ }
++ }
++
++ /*!
++ \class QTextToSpeech
++ \brief The QTextToSpeech class provides a convenient access to text-to-speech engines.
++ \inmodule QtTextToSpeech
++
++ Use \l say() to start reading text to the default audio device, and
++ \l stop(), \l pause(), and \l resume() to control the reading of the text.
++
++ \snippet hello_speak/mainwindow.cpp say
++ \snippet hello_speak/mainwindow.cpp stop
++ \snippet hello_speak/mainwindow.cpp pause
++ \snippet hello_speak/mainwindow.cpp resume
++
++ To synthesize text into PCM data for further processing, use synthesize().
++
++ Use \l findVoices() to get a list of matching voices, or use \l
++ availableVoices() to get the list of voices that support the current
++ locale. Change the \l locale property, using one of the \l 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 \l 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
++ \e Accessibility panel in \e{System Preferences}.
++ */
++
++ /*!
++ \qmltype TextToSpeech
++ \inqmlmodule QtTextToSpeech
++ \brief The TextToSpeech type provides access to text-to-speech engines.
++
++ Use \l say() to start reading text to the default audio device, and
++ \l stop(), \l pause(), and \l resume() to control the reading of the text.
++
++ \snippet quickspeech/Main.qml initialize
++ \codeline
++ \dots
++ \codeline
++ \snippet quickspeech/Main.qml say0
++ \snippet quickspeech/Main.qml pause
++ \snippet quickspeech/Main.qml resume
++ \dots
++
++ To synthesize text into PCM data for further processing, use synthesize().
++
++ To set a voice, use the VoiceSelector attached property like this:
++
++ \code
++ TextToSpeech {
++ VoiceSelector.locale: Qt.locale("en_UK")
++ VoiceSelector.gender: Voice.Male
++ }
++ \endcode
++
++ The first voice that matches all specified criteria will be used. If no voice
++ matches all criteria, then the voice will not change.
++
++ Alternatively, use \l findVoices() to get a list of matching voices, or use
++ \l availableVoices() to get the list of voices that support the current
++ locale. Change the \l locale property, using one of the \l 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
++ the \l voice property.
++
++ Not every engine supports all features. Use the engineCapabilities()
++ function to test which features are available, and adjust the usage of the
++ type 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
++ \e Accessibility panel in \e{System Preferences}.
++ */
++
++ /*!
++ \enum QTextToSpeech::State
++
++ \brief This enum describes the current state of the text-to-speech engine.
++
++ \value Ready The synthesizer is ready to start a new text. This is
++ also the state after a text was finished.
++ \value Speaking Text is being spoken.
++ \value Synthesizing Text is being synthesized into PCM data. The synthesized()
++ signal will be emitted with chunks of data.
++ \value Paused The synthesis was paused and can be resumed with \l resume().
++ \value Error An error has occurred. Details are given by \l errorReason().
++
++ \sa QTextToSpeech::ErrorReason errorReason() errorString()
++ */
++
++ /*!
++ \enum QTextToSpeech::ErrorReason
++
++ \brief This enum describes the current error, if any, of the QTextToSpeech engine.
++
++ \value NoError No error has occurred.
++ \value Initialization The backend could not be initialized, e.g. due to
++ a missing driver or operating system requirement.
++ \value Configuration The given backend configuration is inconsistent, e.g.
++ due to wrong voice name or parameters.
++ \value Input The given text could not be synthesized, e.g. due to
++ invalid size or characters.
++ \value Playback Audio playback failed e.g. due to missing audio device,
++ wrong format or audio streaming interruption.
++
++ Use \l errorReason() to obtain the current error and \l errorString() to get the
++ related error message.
++
++ \sa errorOccurred()
++ */
++
++ /*!
++ \enum QTextToSpeech::BoundaryHint
++
++ \brief describes when speech should be stopped and paused.
++
++ \value Default Uses the engine specific default behavior.
++ \value Immediate The engine should stop playback immediately.
++ \value Word Stop speech when the current word is finished.
++ \value Sentence Stop speech when the current sentence is finished.
++ \value [since 6.6] Utterance
++ Stop 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.
++ */
++
++ /*!
++ 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 \a parent.
++
++ The default engine is platform-specific.
++
++ If the engine initializes correctly, then the \l state of the engine will
++ change to QTextToSpeech::Ready; note that this might happen asynchronously.
++ If the plugin fails to load, then \l state will be set to QTextToSpeech::Error.
++
++ \sa availableEngines()
++ */
++ QTextToSpeech::QTextToSpeech(QObject *parent)
++ : QTextToSpeech(QString(), QVariantMap(), parent)
++ {
++ }
++
++ /*!
++ Loads a text-to-speech engine from a plug-in that matches parameter \a engine and
++ constructs a QTextToSpeech object as the child of \a parent.
++
++ If \a engine is empty, the default engine plug-in is used. The default
++ engine is platform-specific.
++
++ If the engine initializes correctly, the \l 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 \l state will be set to QTextToSpeech::Error.
++
++ \sa availableEngines()
++ */
++ QTextToSpeech::QTextToSpeech(const QString &engine, QObject *parent)
++ : QTextToSpeech(engine, QVariantMap(), parent)
++ {
++ }
++
++ /*!
++ \since 6.4
++
++ Loads a text-to-speech engine from a plug-in that matches parameter \a engine and
++ constructs a QTextToSpeech object as the child of \a parent, passing \a params
++ through to the engine.
++
++ If \a engine is empty, the default engine plug-in is used. The default
++ engine is platform-specific. Which key/value pairs in \a params are supported
++ depends on the engine. See \l{Qt TextToSpeech Engines}{the engine documentation}
++ for details. Unsupported entries will be ignored.
++
++ If the engine initializes correctly, the \l 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 \l state will be set to QTextToSpeech::Error.
++
++ \sa availableEngines()
++ */
++ QTextToSpeech::QTextToSpeech(const QString &engine, const QVariantMap ¶ms, QObject *parent)
++ : QObject(*new QTextToSpeechPrivate(this), parent)
++ {
++ Q_D(QTextToSpeech);
++ // allow QDeclarativeTextToSpeech to skip initialization until the component
++ // is complete
++ if (engine != u"none"_s)
++ d->setEngineProvider(engine, params);
++ else
++ d->m_providerName = engine;
++ }
++
++ /*!
++ Destroys this QTextToSpeech object, stopping any speech.
++ */
++ QTextToSpeech::~QTextToSpeech()
++ {
++ stop(QTextToSpeech::BoundaryHint::Immediate);
++ }
++
++ /*!
++ \qmlproperty string TextToSpeech::engine
++
++ 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
++ \l{availableLocales()}{available locales} and \l{availableVoices()}{available voices}.
++ */
++
++ /*!
++ \property QTextToSpeech::engine
++ \brief the engine used to synthesize text to speech.
++ \since 6.4
++
++ Changing the engine stops any ongoing speech.
++
++ On most platforms, changing the engine will update the list of
++ \l{availableLocales()}{available locales} and \l{availableVoices()}{available voices}.
++ */
++
++ /*!
++ \since 6.4
++ Sets the engine used by this QTextToSpeech object to \a engine, passing
++ \a params through to the engine constructor.
++
++ \return whether \a engine could be set successfully.
++
++ Which key/value pairs in \a params are supported depends on the engine.
++ See \l{Qt TextToSpeech Engines}{the engine documentation} for details.
++ Unsupported entries will be ignored.
++ */
++ bool QTextToSpeech::setEngine(const QString &engine, const QVariantMap ¶ms)
++ {
++ Q_D(QTextToSpeech);
++ if (d->m_providerName == engine && params.isEmpty())
++ return true;
++
++ // read values from the old engine
++ if (d->m_engine) {
++ d->m_storedPitch = d->m_engine->pitch();
++ d->m_storedRate = d->m_engine->rate();
++ d->m_storedVolume = d->m_engine->volume();
++ }
++
++ d->setEngineProvider(engine, params);
++
++ emit engineChanged(d->m_providerName);
++ d->updateState(d->m_engine ? d->m_engine->state()
++ : QTextToSpeech::Error);
++
++ // Restore values from the previous engine, or from
++ // property setters before the engine was initialized.
++ if (d->m_engine) {
++ if (!qIsNaN(d->m_storedPitch))
++ d->m_engine->setPitch(d->m_storedPitch);
++ if (!qIsNaN(d->m_storedRate))
++ d->m_engine->setRate(d->m_storedRate);
++ if (!qIsNaN(d->m_storedVolume))
++ d->m_engine->setVolume(d->m_storedVolume);
++
++ // setting the engine might have changed these values
++ if (double realPitch = pitch(); d->m_storedPitch != realPitch)
++ emit pitchChanged(realPitch);
++ if (double realRate = rate(); d->m_storedRate != realRate)
++ emit rateChanged(realRate);
++ if (double realVolume = volume(); d->m_storedVolume != realVolume)
++ emit volumeChanged(realVolume);
++
++ emit localeChanged(locale());
++ emit voiceChanged(voice());
++ }
++ return d->m_engine.get();
++ }
++
++ QString QTextToSpeech::engine() const
++ {
++ Q_D(const QTextToSpeech);
++ return d->m_providerName;
++ }
++
++ /*!
++ \enum QTextToSpeech::Capability
++ \since 6.6
++ \brief This enum describes the capabilities of a text-to-speech engine.
++
++ \value None The engine implements none of the capabilities.
++ \value Speak The engine can play audio output from text.
++ \value PauseResume The engine can pause and then resume the audo output.
++ \value WordByWordProgress The engine emits the sayingWord() signal for
++ each word that gets spoken.
++ \value Synthesize The engine can \l{synthesize()}{synthesize} PCM
++ audio data from text.
++
++ \sa engineCapabilities()
++ */
++
++ /*!
++ \qmlproperty enumeration TextToSpeech::engineCapabilities
++ \brief This property holds the capabilities implemented by the current engine.
++ \since 6.6
++
++ \sa engine, QTextToSpeech::Capability
++ */
++
++ /*!
++ \property QTextToSpeech::engineCapabilities
++ \brief the capabilities implemented by the current engine
++ \since 6.6
++
++ \sa engine
++ */
++ QTextToSpeech::Capabilities QTextToSpeech::engineCapabilities() const
++ {
++ Q_D(const QTextToSpeech);
++
++ QTextToSpeech::Capabilities caps = d->m_engine
++ ? d->m_engine->capabilities()
++ : QTextToSpeech::Capability::None;
++ if (caps != QTextToSpeech::Capability::None)
++ return caps;
++ if (d->m_providerName.isEmpty()) {
++ qCritical() << "No engine set.";
++ return caps;
++ }
++
++ const QMetaEnum capEnum = QMetaEnum::fromType<QTextToSpeech::Capabilities>();
++ const auto plugin = QTextToSpeechPrivate::plugins().value(d->m_providerName);
++ const auto capNames = plugin.value(QStringLiteral("Capabilities")).toArray();
++
++ // compatibility: plugins that don't set Features can only speak
++ if (capNames.isEmpty())
++ caps |= QTextToSpeech::Capability::Speak;
++
++ for (const auto capName : capNames) {
++ const auto capString = capName.toString().toUtf8();
++ bool ok = false;
++ const QTextToSpeech::Capability capFlag = QTextToSpeech::Capability(capEnum.keyToValue(capString.data(), &ok));
++ if (!ok) {
++ qWarning("Unknown capability: '%s' doesn't map to any QTextToSpeech::Capability value",
++ capString.constData());
++ } else {
++ caps |= capFlag;
++ }
++ }
++ return caps;
++ }
++
++ /*!
++ \qmlmethod list<string> TextToSpeech::availableEngines()
++
++ Holds the list of supported text-to-speech engine plug-ins.
++ */
++
++ /*!
++ Gets the list of supported text-to-speech engine plug-ins.
++
++ \sa engine
++ */
++ QStringList QTextToSpeech::availableEngines()
++ {
++ return QTextToSpeechPrivate::plugins().keys();
++ }
++
++ /*!
++ \qmlproperty enumeration TextToSpeech::state
++ \brief This property holds the current state of the speech synthesizer.
++
++ \sa QTextToSpeech::State say() stop() pause()
++
++ \snippet quickspeech/Main.qml stateChanged
++ */
++
++ /*!
++ \property QTextToSpeech::state
++ \brief the current state of the speech synthesizer.
++
++ \snippet hello_speak/mainwindow.cpp stateChanged
++
++ Use \l say() to start synthesizing text with the current \l voice and \l locale.
++ */
++ QTextToSpeech::State QTextToSpeech::state() const
++ {
++ Q_D(const QTextToSpeech);
++ return d->m_state;
++ }
++
++ /*!
++ \qmlsignal TextToSpeech::aboutToSynthesize(number id)
++
++ \since 6.6
++
++ This signal gets emitted just before the engine starts to synthesize the
++ speech audio for \a id. Applications can use this signal to make last-minute
++ changes to \l voice attributes, or to track the process of text enqueued
++ via enqueue().
++
++ \sa enqueue(), voice
++ */
++
++ /*!
++ \fn void QTextToSpeech::aboutToSynthesize(qsizetype id)
++ \since 6.6
++
++ This signal gets emitted just before the engine starts to synthesize the
++ speech audio for \a id. The \a id is the value returned by a call to enqueue(),
++ Applications can use this signal to make last-minute changes to \l voice
++ attributes, or to track the process of text enqueued via enqueue().
++
++ \sa enqueue(), synthesize(), voice
++ */
++
++ /*!
++ \qmlsignal TextToSpeech::sayingWord(string word, int id, int start, int length)
++ \since 6.6
++
++ This signal is emitted when the \a word, which is the slice of text indicated
++ by \a start and \a length in the utterance \a id, gets played to the audio device.
++
++ \note This signal requires that the engine has the
++ \l {QTextToSpeech::Capability::}{WordByWordProgress} capability.
++
++ The following code highlights the word that is spoken in a TextArea \c input:
++ \snippet quickspeech/Main.qml sayingWord
++
++ \sa QTextToSpeech::Capability, say()
++ */
++
++ /*!
++ \fn void QTextToSpeech::sayingWord(const QString &word, qsizetype id, qsizetype start, qsizetype length)
++ \since 6.6
++
++ This signal is emitted when the \a word, which is the slice of text indicated
++ by \a start and \a length in the utterance \a id, gets played to the audio device.
++
++ \note This signal requires that the engine has the
++ \l {QTextToSpeech::Capability::}{WordByWordProgress} capability.
++
++ \sa Capability, say()
++ */
++
++ /*!
++ \qmlsignal void TextToSpeech::errorOccurred(enumeration reason, string errorString)
++
++ This signal is emitted after an error occurred and the \l state has been set to
++ \c TextToSpeech.Error. The \a reason parameter specifies the type of error,
++ and the \a errorString provides a human-readable error description.
++
++ \sa state errorReason(), errorString()
++ */
++
++ /*!
++ \fn void QTextToSpeech::errorOccurred(QTextToSpeech::ErrorReason reason, const QString &errorString)
++
++ This signal is emitted after an error occurred and the \l state has been set to
++ QTextToSpeech::Error. The \a reason parameter specifies the type of error,
++ and the \a 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().
++
++ \sa errorReason(), errorString(), {Creating Custom Qt Types}
++ */
++
++ /*!
++ \qmlmethod enumeration TextToSpeech::errorReason()
++ \return the reason why the engine has reported an error.
++
++ \sa QTextToSpeech::ErrorReason
++ */
++
++ /*!
++ \return the reason why the engine has reported an error.
++
++ \sa state errorOccurred()
++ */
++ QTextToSpeech::ErrorReason QTextToSpeech::errorReason() const
++ {
++ Q_D(const QTextToSpeech);
++ if (d->m_engine)
++ return d->m_engine->errorReason();
++ return QTextToSpeech::ErrorReason::Initialization;
++ }
++
++ /*!
++ \qmlmethod string TextToSpeech::errorString()
++ \return the current engine error message.
++ */
++
++ /*!
++ \return the current engine error message.
++
++ \sa errorOccurred()
++ */
++ QString QTextToSpeech::errorString() const
++ {
++ Q_D(const QTextToSpeech);
++ if (d->m_engine)
++ return d->m_engine->errorString();
++ return tr("Text to speech engine not initialized");
++ }
++
++ /*!
++ \qmlmethod void TextToSpeech::say(string text)
++
++ Starts synthesizing the \a text.
++
++ This function starts sythesizing the speech asynchronously, and reads the text to the
++ default audio output device.
++
++ \snippet quickspeech/Main.qml say0
++
++ \note All in-progress readings are stopped before beginning to read the recently
++ synthesized text.
++
++ The current state is available using the \l state property, and is
++ set to \l {QTextToSpeech::Speaking} once the reading starts. When the reading is done,
++ \l state will be set to \l {QTextToSpeech::Ready}.
++
++ \sa stop(), pause(), resume()
++ */
++
++ /*!
++ Starts speaking the \a text.
++
++ This function starts sythesizing the speech asynchronously, and reads the text to the
++ default audio output device.
++
++ \snippet hello_speak/mainwindow.cpp say
++
++ \note All in-progress readings are stopped before beginning to read the recently
++ synthesized text.
++
++ The current state is available using the \l state property, and is
++ set to \l Speaking once the reading starts. When the reading is done,
++ \l state will be set to \l Ready.
++
++ \sa enqueue(), stop(), pause(), resume(), synthesize()
++ */
++ void QTextToSpeech::say(const QString &text)
++ {
++ Q_D(QTextToSpeech);
++ d->m_pendingUtterances = {};
++ d->m_utteranceCounter = 1;
++ if (d->m_engine) {
++ emit aboutToSynthesize(0);
++ d->m_engine->say(text);
++ }
++ }
++
++ /*!
++ \qmlmethod int TextToSpeech::enqueue(string utterance)
++ \since 6.6
++
++ Adds \a utterance to the queue of text to be spoken, and starts speaking.
++
++ If the engine's \l state is currently \c Ready, \a utterance will be spoken
++ immediately. Otherwise, the engine will start to speak \a 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.
++
++ \sa say(), stop(), aboutToSynthesize()
++ */
++
++ /*!
++ \since 6.6
++
++ Adds \a 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 \l state is currently \c Ready, \a utterance will be spoken
++ immediately. Otherwise, the engine will start to speak \a 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 \l {QTextToSpeech::BoundaryHint::}{Utterance} boundary hint.
++
++ \sa say(), stop(), aboutToSynthesize(), synthesize()
++ */
++ qsizetype QTextToSpeech::enqueue(const QString &utterance)
++ {
++ Q_D(QTextToSpeech);
++ if (!d->m_engine || utterance.isEmpty())
++ return -1;
++
++ switch (d->m_engine->state()) {
++ case QTextToSpeech::Error:
++ return -1;
++ case QTextToSpeech::Ready:
++ emit aboutToSynthesize(0);
++ d->m_engine->say(utterance);
++ break;
++ case QTextToSpeech::Speaking:
++ case QTextToSpeech::Synthesizing:
++ case QTextToSpeech::Paused:
++ d->m_pendingUtterances.enqueue(utterance);
++ break;
++ }
++
++ return d->m_utteranceCounter++;
++ }
++
++ /*!
++ \fn template<typename Functor> void QTextToSpeech::synthesize(
++ const QString &text, Functor &&functor)
++ \fn template<typename Functor> void QTextToSpeech::synthesize(
++ const QString &text, const QObject *context, Functor &&functor)
++ \since 6.6
++
++ Synthesizes the \a text into raw audio data.
++
++ This function synthesizes the speech asynchronously into raw audio data.
++ When data is available, the \a functor will be called as
++ \c {functor(QAudioFormat format, QByteArray bytes)}, with \c format
++ describing the \l {QAudioFormat}{format} of the data in \c bytes;
++ or as \c {functor(QAudioBuffer &buffer)}.
++
++ The \l state property is set to \l Synthesizing when the synthesis starts,
++ and to \l Ready once the synthesis is finished. While synthesizing, the
++ \a functor might be called multiple times, possibly with changing values
++ for \c format.
++
++ The \a functor can be a callable, like a lambda or free function, with an
++ optional \a context object:
++
++ \code
++ tts.synthesize("Hello world", [](const QAudioFormat &format, const QByteArray &bytes){
++ // process data according to format
++ });
++ \endcode
++
++ or a member function of the \a context object:
++
++ \code
++ struct PCMProcessor : QObject
++ {
++ void processData(const QAudioFormat &format, const QByteArray &bytes)
++ {
++ // process data according to format
++ }
++ } processor;
++ tts.synthesize("Hello world", &processor, &PCMProcessor::processData);
++ \endcode
++
++ If \a context is destroyed, then the \a functor will no longer get called.
++
++ \note This API requires that the engine has the
++ \l {QTextToSpeech::Capability::}{Synthesize} capability.
++
++ \sa say(), stop()
++ */
++
++ /*!
++ \internal
++
++ Handles the engine's synthesized() signal to call \a slotObj on the \a context
++ object. The slot object and the temporary connection are stored and released
++ in updateState() when the state of the engine transitions back to Ready.
++ */
++ void QTextToSpeech::synthesizeImpl(const QString &text,
++ QtPrivate::QSlotObjectBase *slotObj, const QObject *context,
++ SynthesizeOverload overload)
++ {
++ Q_D(QTextToSpeech);
++ Q_ASSERT(slotObj);
++ if (d->m_slotObject)
++ d->m_slotObject->destroyIfLastRef();
++ d->m_slotObject = slotObj;
++ const auto receive = [d, context, overload](const QAudioFormat &format, const QByteArray &bytes){
++ Q_ASSERT(d->m_slotObject);
++ if (overload == SynthesizeOverload::AudioBuffer) {
++ const QAudioBuffer buffer(bytes, format);
++ void *args[] = {nullptr, const_cast<QAudioBuffer *>(&buffer)};
++ d->m_slotObject->call(const_cast<QObject *>(context), args);
++ } else {
++ void *args[] = {nullptr,
++ const_cast<QAudioFormat *>(&format),
++ const_cast<QByteArray *>(&bytes)};
++ d->m_slotObject->call(const_cast<QObject *>(context), args);
++ }
++ };
++ d->m_synthesizeConnection = connect(d->m_engine.get(), &QTextToSpeechEngine::synthesized,
++ context ? context : this, receive);
++
++ if (!d->m_engine)
++ return;
++
++ if (d->m_engine->state() == QTextToSpeech::Synthesizing)
++ d->m_pendingUtterances.enqueue(text);
++ else
++ d->m_engine->synthesize(text);
++ }
++
++ /*!
++ \qmlmethod void TextToSpeech::stop(BoundaryHint boundaryHint)
++
++ Stops the current reading at \a boundaryHint, and clears the
++ queue of pending texts.
++
++ The reading cannot be resumed. Whether the \a boundaryHint is
++ respected depends on the engine.
++
++ \sa say(), enqueue(), pause(), QTextToSpeech::BoundaryHint
++ */
++
++ /*!
++ Stops the current reading at \a boundaryHint, and clears the
++ queue of pending texts.
++
++ The reading cannot be resumed. Whether the \a boundaryHint is
++ respected depends on the engine.
++
++ \sa say(), enqueue(), pause()
++ */
++ void QTextToSpeech::stop(BoundaryHint boundaryHint)
++ {
++ Q_D(QTextToSpeech);
++ d->m_pendingUtterances = {};
++ d->m_utteranceCounter = 0;
++ if (d->m_engine) {
++ if (boundaryHint == QTextToSpeech::BoundaryHint::Immediate)
++ d->disconnectSynthesizeFunctor();
++ d->m_engine->stop(boundaryHint);
++ }
++ }
++
++ /*!
++ \qmlmethod void TextToSpeech::pause(BoundaryHint boundaryHint)
++
++ Pauses the current speech at \a boundaryHint.
++
++ Whether the \a boundaryHint is respected depends on the \l engine.
++
++ \sa resume(), QTextToSpeech::BoundaryHint,
++ {QTextToSpeech::Capabilities}{PauseResume}
++ */
++
++ /*!
++ Pauses the current speech at \a boundaryHint.
++
++ Whether the \a boundaryHint is respected depends on the \l engine.
++
++ \sa resume(), {QTextToSpeech::Capabilities}{PauseResume}
++ */
++ void QTextToSpeech::pause(BoundaryHint boundaryHint)
++ {
++ Q_D(QTextToSpeech);
++ if (!d->m_engine || d->m_state != QTextToSpeech::Speaking)
++ return;
++
++ if (boundaryHint == BoundaryHint::Utterance) {
++ if (d->m_pendingUtterances.isEmpty() || !d->m_pendingUtterances.first().isEmpty())
++ d->m_pendingUtterances.prepend(QString());
++ }
++ // pause called in response to aboutToSynthesize
++ if (d->m_engine->state() == QTextToSpeech::Ready) {
++ d->updateState(QTextToSpeech::Paused);
++ } else {
++ d->m_engine->pause(boundaryHint);
++ }
++ }
++
++ /*!
++ \qmlmethod void TextToSpeech::resume()
++
++ Resume speaking after \l pause() has been called.
++
++ \sa pause()
++ */
++
++ /*!
++ Resume speaking after \l 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.
++
++ \sa pause()
++ */
++ void QTextToSpeech::resume()
++ {
++ Q_D(QTextToSpeech);
++ if (d->m_state != QTextToSpeech::Paused)
++ return;
++
++ if (d->m_engine) {
++ // If we are pausing before proceeding with the next utterance,
++ // then continue with the next pending text.
++ if (d->m_engine->state() == QTextToSpeech::Ready)
++ d->updateState(QTextToSpeech::Ready);
++ else
++ d->m_engine->resume();
++ }
++ }
++
++ /*!
++ \qmlproperty double TextToSpeech::pitch
++
++ This property hold the voice pitch, ranging from -1.0 to 1.0.
++
++ The default of 0.0 is the normal speech pitch.
++ */
++
++ /*!
++ \property QTextToSpeech::pitch
++ \brief the voice pitch, ranging from -1.0 to 1.0.
++
++ The default of 0.0 is the normal speech pitch.
++ */
++
++ void QTextToSpeech::setPitch(double pitch)
++ {
++ Q_D(QTextToSpeech);
++ pitch = qBound(-1.0, pitch, 1.0);
++
++ if (!d->m_engine) {
++ if (d->m_storedPitch != pitch) {
++ d->m_storedPitch = pitch;
++ emit pitchChanged(pitch);
++ }
++ return;
++ }
++ if (d->m_engine->pitch() == pitch)
++ return;
++ if (d->m_engine && d->m_engine->setPitch(pitch))
++ emit pitchChanged(pitch);
++ }
++
++ double QTextToSpeech::pitch() const
++ {
++ Q_D(const QTextToSpeech);
++ if (d->m_engine)
++ return d->m_engine->pitch();
++ return qIsNaN(d->m_storedPitch) ? 0.0 : d->m_storedPitch;
++ }
++
++ /*!
++ \qmlproperty double TextToSpeech::rate
++
++ \brief This property holds the current voice rate, ranging from -1.0 to 1.0.
++
++ The default of 0.0 is the normal speech flow.
++ */
++
++ /*!
++ \property QTextToSpeech::rate
++ \brief the current voice rate, ranging from -1.0 to 1.0.
++
++ The default value of 0.0 is normal speech flow.
++ */
++ void QTextToSpeech::setRate(double rate)
++ {
++ Q_D(QTextToSpeech);
++ rate = qBound(-1.0, rate, 1.0);
++
++ if (!d->m_engine) {
++ if (d->m_storedRate != rate) {
++ d->m_storedRate = rate;
++ emit rateChanged(rate);
++ }
++ return;
++ }
++ if (d->m_engine->rate() == rate)
++ return;
++ if (d->m_engine && d->m_engine->setRate(rate))
++ emit rateChanged(rate);
++ }
++
++ double QTextToSpeech::rate() const
++ {
++ Q_D(const QTextToSpeech);
++ if (d->m_engine)
++ return d->m_engine->rate();
++ return qIsNaN(d->m_storedRate) ? 0.0 : d->m_storedRate;
++ }
++
++ /*!
++ \qmlproperty double TextToSpeech::volume
++
++ \brief This property holds the current volume, ranging from 0.0 to 1.0.
++
++ The default value is the platform's default volume.
++ */
++
++ /*!
++ \property QTextToSpeech::volume
++ \brief the current volume, ranging from 0.0 to 1.0.
++
++ The default value is the platform's default volume.
++ */
++ void QTextToSpeech::setVolume(double volume)
++ {
++ Q_D(QTextToSpeech);
++ volume = qBound(0.0, volume, 1.0);
++
++ if (!d->m_engine) {
++ if (d->m_storedVolume != volume) {
++ d->m_storedVolume = volume;
++ emit volumeChanged(volume);
++ }
++ return;
++ }
++ if (d->m_engine->volume() == volume)
++ return;
++ if (d->m_engine->setVolume(volume))
++ emit volumeChanged(volume);
++ }
++
++ double QTextToSpeech::volume() const
++ {
++ Q_D(const QTextToSpeech);
++ if (d->m_engine)
++ return d->m_engine->volume();
++ return qIsNaN(d->m_storedVolume) ? 0.0 : d->m_storedVolume;
++ }
++
++ /*!
++ \qmlproperty locale TextToSpeech::locale
++
++ \brief This property holds the current locale in use.
++
++ By default, the system locale is used.
++
++ \sa voice
++ */
++
++ /*!
++ \property QTextToSpeech::locale
++ \brief the current locale in use.
++
++ By default, the system locale is used.
++
++ On some platforms, changing the locale will update the list of
++ \l{availableVoices()}{available voices}, and if the current voice is not
++ available with the new locale, a new voice will be set.
++
++ \sa voice, findVoices()
++ */
++ void QTextToSpeech::setLocale(const QLocale &locale)
++ {
++ Q_D(QTextToSpeech);
++ if (!d->m_engine)
++ return;
++
++ if (d->m_engine->locale() == locale)
++ return;
++
++ const QVoice oldVoice = voice();
++ if (d->m_engine->setLocale(locale)) {
++ emit localeChanged(locale);
++ if (const QVoice newVoice = d->m_engine->voice(); oldVoice != newVoice)
++ emit voiceChanged(newVoice);
++ }
++ }
++
++ QLocale QTextToSpeech::locale() const
++ {
++ Q_D(const QTextToSpeech);
++ if (d->m_engine)
++ return d->m_engine->locale();
++ return QLocale();
++ }
++
++ /*!
++ \qmlmethod list<voice> TextToSpeech::availableLocales()
++
++ Holds the list of locales that are supported by the active \l engine.
++ */
++
++ /*!
++ \return the list of locales that are supported by the active \l engine.
++
++ \sa availableVoices(), findVoices()
++ */
++ QList<QLocale> QTextToSpeech::availableLocales() const
++ {
++ Q_D(const QTextToSpeech);
++ if (d->m_engine)
++ return d->m_engine->availableLocales();
++ return QList<QLocale>();
++ }
++
++ /*!
++ \qmlproperty voice TextToSpeech::voice
++
++ \brief This property holds the voice that will be used for the speech.
++
++ The voice needs to be one of the \l{availableVoices()}{voices available} for
++ the engine.
++
++ On some platforms, setting the voice changes other voice attributes such
++ as \l locale, \l pitch, and so on. These changes trigger the emission of
++ signals.
++ */
++
++ /*!
++ \property QTextToSpeech::voice
++ \brief the voice that will be used for the speech.
++
++ The voice needs to be one of the \l{availableVoices()}{voices available} for
++ the engine.
++
++ On some platforms, setting the voice changes other voice attributes such
++ as \l locale, \l pitch, and so on. These changes trigger the emission of
++ signals.
++
++ \sa findVoices()
++ */
++ void QTextToSpeech::setVoice(const QVoice &voice)
++ {
++ Q_D(QTextToSpeech);
++ if (!d->m_engine)
++ return;
++
++ if (d->m_engine->voice() == voice)
++ return;
++
++ const QLocale oldLocale = locale();
++ if (d->m_engine->setVoice(voice)) {
++ emit voiceChanged(voice);
++ if (const QLocale newLocale = d->m_engine->locale(); newLocale != oldLocale)
++ emit localeChanged(newLocale);
++ }
++ }
++
++ QVoice QTextToSpeech::voice() const
++ {
++ Q_D(const QTextToSpeech);
++ if (d->m_engine)
++ return d->m_engine->voice();
++ return QVoice();
++ }
++
++ /*!
++ \qmlmethod list<voice> TextToSpeech::availableVoices()
++
++ Holds the list of voices available for the current \l locale.
++ */
++
++ /*!
++ \return the list of voices available for the current \l locale.
++
++ \note If no locale has been set, the system locale is used.
++
++ \sa availableLocales(), findVoices()
++ */
++ QList<QVoice> QTextToSpeech::availableVoices() const
++ {
++ Q_D(const QTextToSpeech);
++ if (d->m_engine)
++ return d->m_engine->availableVoices();
++ return QList<QVoice>();
++ }
++
++ /*!
++ \fn template<typename ...Args> QList<QVoice> QTextToSpeech::findVoices(Args &&...args) const
++ \since 6.6
++
++ \return the list of voices that match the criteria in \a args.
++
++ The arguments in \a 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 \l{QVoice::}{name},
++ of the voice, an argument of type QLocale is matched agains the voice's
++ \l {QVoice::}{locale}, etc. It is possible to specify only the \l {QLocale::}{Language} or
++ \l {QLocale::}{Territory} of the desired voices, and the name can be matched against a
++ \l {QRegularExpression}{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 \a args includes the current \l {QTextToSpeech::}{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 \l {QTextToSpeech::}{state} is
++ \l {QTextToSpeech::State}{Ready}.
++
++ \sa availableVoices()
++ */
++
++ /*!
++ \qmlmethod list<voice> TextToSpeech::findVoices(map criteria)
++ \since 6.6
++
++ Returns the list of voices that match all the specified \a criteria.
++
++ \a criteria is a map from voice property name to property value, supporting
++ combinations of search criteria such as:
++
++ \code
++ let daniel = tts.findVoices({
++ "name": "Daniel"
++ })
++ let maleEnglish = tts.findVoices({
++ "gender": Voice.Male,
++ "language": Qt.locale('en')
++ })
++ \endcode
++
++ \sa VoiceSelector
++ */
++
++ /*!
++ \internal
++
++ Returns the list of all voices. This requires iterating through all locales,
++ unless \a locale is set, in which case we can just go through the voices for
++ that locale.
++ */
++ QList<QVoice> QTextToSpeech::allVoices(const QLocale *locale) const
++ {
++ Q_D(const QTextToSpeech);
++ if (!d->m_engine)
++ return {};
++
++ const QVoice oldVoice = d->m_engine->voice();
++
++ QList<QVoice> voices;
++ QSignalBlocker blockSignals(const_cast<QTextToSpeech *>(this));
++ const QList<QLocale> allLocales = locale ? QList<QLocale>{*locale} : availableLocales();
++ for (const auto &l : allLocales) {
++ if (d->m_engine->locale() != l)
++ d->m_engine->setLocale(l);
++ voices << d->m_engine->availableVoices();
++ }
++
++ // reset back to old voice, which will have changed when we changed the
++ // engine's locale.
++ if (d->m_engine->voice() != oldVoice)
++ d->m_engine->setVoice(oldVoice);
++
++ return voices;
++ }
++
++ QT_END_NAMESPACE