Qt 文本转语言（QTextToSpeech类）详解 - 实践

Qt 文本转语言（QTextToSpeech类）详解

• 一、QTextToSpeech类详解
• • 1、核心功能
  • 2、重要信号
  • 3、 基本使用示例
  • 4、进阶控制示例 (带暂停/恢复)
  • 5、注意事项
  • 6、总结
• 二、示例
• • 1、效果展示
  • 2、源码分享

一、QTextToSpeech类详解

QTextToSpeech 是 Qt6 中引入的一个核心类，属于 Qt TextToSpeech 模块。它提供了一种将文本转换为语音（语音合成）的接口。开发者可以利用这个类为应用程序添加语音输出功能，例如用于无障碍支持、语音助手、教育应用、导航提示等场景。

1、核心功能

1. 文本转语音： 核心功能是将提供的字符串文本朗读出来。
2. 控制播放：
   • speak(): 开始朗读文本。
   • stop(): 立即停止当前朗读。
   • pause(): 暂停当前朗读。
   • resume(): 从暂停处恢复朗读。
3. 状态查询： 通过 state() 方法获取当前状态（Ready、Speaking、Paused、BackendError）。
4. 语音属性设置：
   • 音量 (volume): 范围通常在 0.0 (静音) 到 1.0 (最大音量) 之间。
   • 语速 (rate): 范围通常在 -1.0 (最慢) 到 1.0 (最快) 之间，0.0 表示正常语速。
   • 音高 (pitch): 范围通常在 -1.0 (最低音高) 到 1.0 (最高音高) 之间，0.0 表示默认音高。
5. 语音选择：
   • 可以获取系统可用的语音引擎 (availableEngines())。
   • 可以获取特定引擎支持的语言 (availableLocales())。
   • 可以获取特定引擎和语言下可用的声音 (availableVoices())。
   • 可以设置当前使用的 locale (语言和区域组合，如 en_US) 或具体的 voice (特定的发音人)。
6. 引擎管理：
   • 可以设置当前使用的语音引擎 (setEngine())，引擎名称通常与平台相关（如 "sapi" 在 Windows, "speechd" 在 Linux）。
   • 可以获取当前引擎名称 (engine())。

2、重要信号

• stateChanged(QTextToSpeech::State state): 当语音状态改变时触发。
• volumeChanged(double volume): 当音量改变时触发。
• rateChanged(double rate): 当语速改变时触发。
• pitchChanged(double pitch): 当音高改变时触发。
• voiceChanged(const QVoice &voice): 当语音（发音人）改变时触发。
• localeChanged(const QLocale &locale): 当语言区域改变时触发。
• engineChanged(const QString &engine): 当语音引擎改变时触发。
• errorOccurred(QTextToSpeech::ErrorReason reason, const QString &errorString): 当发生错误时触发。

3、 基本使用示例

#include <QTextToSpeech>#include <QDebug>int main(int argc, char *argv[]) {QCoreApplication app(argc, argv);// 1. 创建 QTextToSpeech 对象QTextToSpeech *speech = new QTextToSpeech(&app);// 2. (可选) 设置语音属性 - 这里设置正常音量、语速和音高speech->setVolume(1.0);speech->setRate(0.0);speech->setPitch(0.0);// 3. (可选) 设置语言或发音人// 例如，设置中文：QLocale chineseLocale(QLocale::Chinese, QLocale::China);if (speech->availableLocales().contains(chineseLocale)) {speech->setLocale(chineseLocale);} else {qWarning() << "Chinese voice not available.";}// 4. 朗读文本QString textToSpeak = "你好，世界！欢迎使用Qt语音合成功能。";speech->say(textToSpeak);// 5. (可选) 连接信号，例如监听状态变化QObject::connect(speech, &QTextToSpeech::stateChanged, [](QTextToSpeech::State state) {qDebug() << "Speech state changed to:" << state;});return app.exec();}

4、进阶控制示例 (带暂停/恢复)

// ... 创建 speech 对象后 ...
// 连接按钮信号 (假设有 pauseButton 和 resumeButton)
QObject::connect(pauseButton, &QPushButton::clicked, [speech]() {
if (speech->state() == QTextToSpeech::Speaking) {
speech->pause();
}
});
QObject::connect(resumeButton, &QPushButton::clicked, [speech]() {
if (speech->state() == QTextToSpeech::Paused) {
speech->resume();
}
});
// 连接停止按钮
QObject::connect(stopButton, &QPushButton::clicked, [speech]() {
speech->stop();
});

5、注意事项

1. 平台依赖：QTextToSpeech 的功能和质量高度依赖于底层操作系统提供的语音合成引擎。不同平台（Windows, Linux, macOS, Android, iOS）可用的引擎、声音和支持的语言可能差异很大。
2. 引擎初始化： 在某些平台上，引擎的初始化可能是异步的。在调用 say() 之前，最好确认 state() 是否为 Ready，或者监听 stateChanged 信号。
3. 语音队列： 如果在当前语音尚未完成时调用 say() 朗读新文本，新文本会加入队列，并在当前语音结束后自动播放。调用 stop() 会清空队列。
4. 资源管理： 创建 QTextToSpeech 对象可能消耗较多资源。如果应用中只在特定时刻需要语音，可以考虑在需要时创建，用完即删。
5. 错误处理： 务必监听 errorOccurred 信号，以便处理可能发生的错误（如引擎加载失败、文本过长、网络问题等）。

6、总结

QTextToSpeech 为 Qt 应用程序提供了便捷的文本转语音功能接口。开发者可以通过它设置音量、语速、音高，选择不同的语言和发音人，并控制语音的播放、暂停、恢复和停止。了解其平台依赖性、状态管理和错误处理对于开发健壮的语音功能至关重要。

二、示例

1、效果展示

2、源码分享

#include "mainwindow.h"
#include "ui_mainwindow.h"
MainWindow::MainWindow(QWidget *parent)
: QMainWindow(parent)
, ui(new Ui::MainWindow)
{
ui->setupUi(this);
}
MainWindow::~MainWindow()
{
delete ui;
}
void MainWindow::on_pushButton_clicked()
{
// 1. 创建 QTextToSpeech 对象
QTextToSpeech *speech = new QTextToSpeech(this);
// 2. (可选) 设置语音属性 - 这里设置正常音量、语速和音高
speech->setVolume(1.0);
speech->setRate(0.0);
speech->setPitch(0.0);
// 3. (可选) 设置语言或发音人
// 例如，设置中文：
QLocale chineseLocale(QLocale::Chinese, QLocale::China);
if (speech->availableLocales().contains(chineseLocale)) {
speech->setLocale(chineseLocale);
} else {
qWarning() << "Chinese voice not available.";
}
// 4. 朗读文本
QString textToSpeak = this->ui->lineEdit->text();
speech->say(textToSpeak);
// 5. (可选) 连接信号，例如监听状态变化
QObject::connect(speech, &QTextToSpeech::stateChanged, [=](QTextToSpeech::State state) {
qDebug() << "Speech state changed to:" << state;
this->ui->textBrowser->append(QString("Speech state changed to:").append(QString::number(state)));
});
}