QTextToSpeech Class

成员函数文档

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

从使用默认引擎插件的插件中加载一个文本转语音引擎，并构建一个 QTextToSpeech 对象作为parent 的子对象。

默认引擎因平台而异。

如果引擎初始化成功，则该引擎的state 将变为QTextToSpeech::Ready ；请注意，此过程可能异步发生。如果插件加载失败，则state 将被设置为QTextToSpeech::Error 。

另请参阅 availableEngines()。

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

从与参数engine 匹配的插件中加载一个文本转语音引擎，并构建一个QTextToSpeech对象作为parent 的子对象。

如果engine 为空，则使用默认引擎插件。默认引擎因平台而异。

如果引擎初始化成功，该引擎的state 将设置为QTextToSpeech::Ready 。如果插件加载失败，或者引擎初始化失败，该引擎的state 将设置为QTextToSpeech::Error 。

另请参阅 availableEngines()。

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

从与参数engine 匹配的插件中加载一个文本转语音引擎，并构建一个QTextToSpeech对象作为parent 的子对象，同时将params 传递给该引擎。

如果engine 为空，则使用默认引擎插件。默认引擎因平台而异。params 中哪些键值对受支持取决于引擎。详情请参阅引擎文档。不受支持的条目将被忽略。

如果引擎初始化成功，该引擎的state 将被设置为QTextToSpeech::Ready 。如果插件加载失败，或者引擎初始化失败，该引擎的state 将被设置为QTextToSpeech::Error 。

该函数在 Qt 6.4 中引入。

另请参阅 availableEngines()。

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

销毁此QTextToSpeech 对象，并停止所有语音播放。

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

该信号在引擎开始为id 合成语音音频之前触发。id 是调用enqueue()返回的值。应用程序可以利用此信号对voice 的属性进行最后一刻的修改，或跟踪通过enqueue()入队文本的处理过程。

该函数在 Qt 6.6 中引入。

另请参阅 enqueue()、synthesize() 以及voice 。

[static invokable] QStringList QTextToSpeech::availableEngines()

获取支持的文本转语音引擎插件列表。

另请参阅 engine 。

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

返回当前活动engine 所支持的语言环境列表。

另请参阅 availableVoices() 和findVoices()。

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

返回当前locale 可用的语音列表。

另请参阅 availableLocales() 和findVoices()。

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

将utterance 添加到待朗读文本的队列中，并开始朗读。返回该文本在队列中的索引；若发生错误，则返回 -1。

如果引擎当前的state 为Ready ，则会立即朗读utterance 。否则，引擎将在完成当前文本的朗读后，开始朗读utterance 。

每次引擎处理队列中的下一个文本条目时，都会触发aboutToSynthesize() 信号。这使应用程序能够跟踪进度，并对语音属性进行最后一刻的调整。

调用stop() 将清空队列。若要在文本结尾处暂停引擎，请使用Utterance 边界提示。

该函数在 Qt 6.6 中引入。

另请参阅 say()、stop()、aboutToSynthesize() 和synthesize()。

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

当发生错误且state 已设置为QTextToSpeech::Error 时，将发出此信号。reason 参数指定错误类型，而errorString 提供可供人类阅读的错误描述。

QTextToSpeech::ErrorReason 并非已注册的元类型，因此对于队列连接，您必须通过Q_DECLARE_METATYPE() 和qRegisterMetaType() 对其进行注册。

另请参阅 errorReason()、errorString() 以及《创建自定义 Qt 类型》。

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

返回引擎报告错误的原因。

另请参阅 state 和errorOccurred()。

[invokable] QString QTextToSpeech::errorString() const

返回当前引擎的错误消息。

另请参阅 errorOccurred()。

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

返回符合args 中条件的所有语音列表。

args 中的参数将按顺序处理，以组装出满足所有条件的语音列表。类型为QString 的参数将与语音的name 进行匹配，类型为QLocale 的参数将与语音的locale 进行匹配，以此类推。可以仅指定所需语音的Language 或Territory ，且名称可与regular expression 进行匹配。

如果条件列表为空，该函数将返回所有语音。无法使用多个同类型的条件，否则将导致编译时错误。

该函数于 Qt 6.6 中引入。

另请参阅 availableVoices()。

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

暂停当前在boundaryHint 处的语音播放。

boundaryHint 是否被遵守取决于engine 。

另请参阅 resume() 和PauseResume 。

[slot] void QTextToSpeech::resume()

在调用pause() 之后继续播放语音。

另请参阅 pause()。

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

开始播放text 。

此函数将异步开始合成语音，并将文本读入默认音频输出设备。

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

可通过state 属性获取当前状态，一旦开始朗读，该属性将设置为Speaking 。朗读完成后，state 将被设置为Ready 。

另请参阅 enqueue()、stop()、pause()、resume() 以及synthesize()。

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

当word （即语句id 中由start 和length 所指代的文本片段）被播放到音频设备时，会触发此信号。

该函数在 Qt 6.6 中引入。

另请参阅 Capability 和say()。

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

将此QTextToSpeech 对象所使用的引擎设置为engine ，并将params 作为参数传递给引擎构造函数。

返回engine 是否设置成功。

params 中哪些键值对受支持取决于引擎。详情请参阅引擎文档。不受支持的条目将被忽略。

该函数在 Qt 6.4 中引入。

另请参阅 engine()。

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

在boundaryHint 处停止当前读取，并清空待处理文本队列。

无法恢复当前的读取操作。是否遵守boundaryHint 取决于引擎。

另请参阅 say()、enqueue() 和pause()。

将text 合成到原始音频数据中。

该函数以异步方式将语音合成到原始音频数据中。当数据可用时，functor 将被调用为functor(QAudioFormat format, QByteArray bytes) ，其中format 描述了bytes 中数据的format ；或者被调用为functor(QAudioBuffer &buffer) 。

state 属性在合成开始时被设置为Synthesizing ，合成完成后则被设置为Ready 。在合成过程中，functor 可能会被调用多次，且format 的值可能会发生变化。

functor 可以是一个可调用对象（如 lambda 或自由函数），并可选地包含一个context 对象：

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

或者作为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);

如果 `context ` 被销毁，则 `functor ` 将不再被调用。

这些函数于 Qt 6.6 中引入。

另请参阅 say() 和stop()。