简介本资源是面向Qt开发者尤其C/QML中级以上的语音交互功能实战代码包聚焦Qt 5.10版本下qtspeech模块的跨平台文本转语音TTS与语音识别能力实现。资源完整包含Qt Speech子系统核心源码及多平台适配实现如Windows下的SAPI、Linux的Speech Dispatcher、Android原生接口及Flite轻量级处理器等覆盖QTextToSpeech API封装、信号槽驱动的语音播放控制、语言/语速/音调参数配置等关键实践路径。压缩包共101个文件含26个.pro工程配置、24个.h头文件与23个.cpp实现文件辅以JSON配置、QML集成示例及平台特异性实现如qtexttospeech_winrt.cpp、qtexttospeech_android.cpp总大小仅155KB结构清晰、可直接编译调试。目前已有1656人学习下载读者可获得一套开箱即用的Qt语音功能参考实现深入理解跨平台TTS抽象层设计逻辑并快速复用于无障碍应用、导航播报或教学软件等实际场景。1. QtSpeech 5.10 不是独立库而是 Qt 5.10 中 QTextToSpeech 模块的典型工程命名习惯你在 GitHub、Gitee 或企业内部代码仓库里搜到qtspeech-5.10这个名称大概率不是某个第三方语音 SDK 的发行版而是开发者基于 Qt 官方QTextToSpeech类封装的最小可运行示例项目——它用-5.10显式标注所依赖的 Qt 版本目的是规避 Qt 5.12 引入的插件路径变更、TTS 后端抽象层重构如QTextToSpeechPrivate重设计带来的兼容性断裂。这类项目通常只含 3 个核心文件main.cpp初始化语音引擎、mainwindow.cpp绑定 UI 控件如 QLineEdit 输入文本 QPushButton 触发朗读、qtspeech.pro声明QT texttospeech模块依赖。它解决的实际问题是在嵌入式 Linux如 AM57xx Qt 5.10.1 eglfs或 Windows DesktopMSVC2015环境下绕过系统级语音服务如 Windows SAPI、macOS NSSpeechSynthesizer的权限/注册限制直接调用 Qt 封装的跨平台语音合成接口。适合 Qt 5.9–5.12 跨版本维护的老项目迁移工程师、工业 HMI 开发者以及需要离线语音播报但又不想引入 Python/pyttsx3 或 C 语音引擎如 eSpeak-ng编译依赖的嵌入式团队。2. QTextToSpeech 在 Qt 5.10 中的底层机制与后端选型逻辑2.1 Qt 5.10 的 TTS 架构分层从 API 到平台插件Qt 5.10 的QTextToSpeech类位于QtTextToSpeech模块其设计遵循典型的「抽象接口 平台插件」模式。应用层调用QTextToSpeech::say(Hello)时实际执行链为QTextToSpeech → QTextToSpeechPrivate → QPlatformTextToSpeechPlugin → 具体平台插件如 qtexttospeech_win.dll / libqtexttospeech_pulse.so。关键点在于Qt 5.10不自带语音合成引擎它仅提供统一 API 和插件加载框架具体发音能力完全依赖操作系统原生后端或第三方插件。Windows 下默认使用 SAPI 5.4需系统已安装语音包Linux 下依赖 PulseAudio speech-dispatcher需speech-dispatcher服务运行macOS 则桥接到 NSSpeechSynthesizer。这意味着若你的目标设备是无桌面环境的嵌入式 Linux如 Yocto 构建的 Qt 5.10 镜像QTextToSpeech默认会因找不到libqtexttospeech_pulse.so插件而静默失败——此时必须手动编译并部署适配的插件或切换至qtexttospeech_espeak这类社区插件。提示Qt 5.10 的QTextToSpeech不支持语音识别Speech-to-Text标题中出现的qt语音识别属于常见误标。真正实现语音识别需集成QAudioRecorder 外部 ASR 引擎如 Vosk、Whisper.cpp或使用 Qt 6.5 新增的QVoiceAssistant但该类在 Qt 5.10 中不存在。2.2 Qt 5.10 中 QTextToSpeech 的初始化与状态验证在 Qt 5.10 项目中启用语音功能必须显式链接模块并验证插件加载。以下是最小验证代码#include QApplication #include QTextToSpeech #include QDebug int main(int argc, char *argv[]) { QApplication app(argc, argv); QTextToSpeech *tts new QTextToSpeech; // 关键检查可用引擎数量Qt 5.10 下若返回 0说明插件未就位 qDebug() Available engines: tts-availableEngines(); // 检查当前引擎是否有效Qt 5.10 不自动 fallback需手动 setEngine if (!tts-engine().isEmpty()) { qDebug() Current engine: tts-engine(); } else { qDebug() No default engine set — will use first available; if (!tts-availableEngines().isEmpty()) { tts-setEngine(tts-availableEngines().first()); } } // 测试朗读Qt 5.10 下若无声音优先检查插件路径而非代码 tts-say(Qt 5.10 speech test); return app.exec(); }参数说明与调试要点tts-availableEngines()返回QStringListQt 5.10 Windows 下常见值为[sapi]Linux 下为[pulse, espeak]若为空说明QPLATFORM_PLUGIN_PATH未指向含qtexttospeech_*.so/.dll的目录。tts-setEngine(espeak)可强制指定后端但需确保对应插件已编译并置于插件搜索路径如./plugins/texttospeech/。tts-state()在say()后应短暂变为QTextToSpeech::Speaking若始终为QTextToSpeech::Ready表明引擎未启动成功——此时需检查系统日志Linux 用journalctl -u speech-dispatcherWindows 查事件查看器。2.3 Qt 5.10 的插件路径配置与部署陷阱Qt 5.10 对插件路径的解析严格依赖QCoreApplication::addLibraryPath()和环境变量。常见部署失败场景及修复命令如下场景现象修复命令Linux 示例说明插件目录未被识别availableEngines()返回空列表export QT_PLUGIN_PATH/opt/Qt5.10/pluginsexport QML2_IMPORT_PATH/opt/Qt5.10/qmlQt 5.10 不读取QT_QPA_PLATFORM_PLUGIN_PATH该变量用于 GUI 平台插件非 TTSspeech-dispatcher 服务未运行Linux 下pulse引擎存在但无声sudo systemctl start speech-dispatchersudo systemctl enable speech-dispatcherQt 5.10 的qtexttospeech_pulse.so依赖speech-dispatcher的 D-Bus 接口非直连 PulseAudioWindows 语音包缺失sapi引擎存在但报错SAPI_E_INVALIDARG控制面板 → 语言 → 添加语言 → 中文简体→ 选项 → 下载语音Qt 5.10 调用 SAPI 时需对应语言的 TTS 引擎已安装否则say()无响应注意Qt 5.10 的QTextToSpeech不支持动态加载插件如QLibrary::load()所有插件必须通过标准路径机制发现。若需自定义插件如适配嵌入式 ALSA必须继承QPlatformTextToSpeechPlugin并在plugins/texttospeech/下部署.so文件。3. 在 Qt Creator 中构建 qtspeech-5.10 工程的完整操作链3.1 创建最小可运行工程从 .pro 文件到 UI 绑定新建 Qt Widgets Application 项目后需修改三处核心配置。首先编辑qtspeech.proQT core widgets texttospeech CONFIG c11 # Qt 5.10 必须显式声明 texttospeech 模块否则链接失败 TARGET qtspeech TEMPLATE app SOURCES \ main.cpp \ mainwindow.cpp HEADERS \ mainwindow.h FORMS \ mainwindow.ui # 关键指定插件搜索路径Qt 5.10 默认不包含 texttospeech 目录 PLUGIN_PATH $${OUT_PWD}/plugins QMAKE_POST_LINK $$escape_expand(\\n) mkdir -p $$PLUGIN_PATH/texttospeech然后在mainwindow.ui中拖入QLineEdit对象名lineEditText和QPushButton对象名btnSpeak并在mainwindow.cpp中绑定槽函数#include mainwindow.h #include ui_mainwindow.h #include QTextToSpeech #include QMessageBox MainWindow::MainWindow(QWidget *parent) : QMainWindow(parent) , ui(new Ui::MainWindow) { ui-setupUi(this); // Qt 5.10 下必须在 UI 初始化后创建 tts 实例 m_tts new QTextToSpeech(this); // 连接按钮点击信号到朗读槽 connect(ui-btnSpeak, QPushButton::clicked, this, MainWindow::onSpeakClicked); } void MainWindow::onSpeakClicked() { QString text ui-lineEditText-text().trimmed(); if (text.isEmpty()) { QMessageBox::warning(this, Empty Input, Please enter text to speak); return; } // Qt 5.10 的 say() 是异步调用无需额外线程 m_tts-say(text); // 可选监听状态变化Qt 5.10 支持 stateChanged 信号 connect(m_tts, QTextToSpeech::stateChanged, this, [](QTextToSpeech::State state) { if (state QTextToSpeech::Speaking) { qDebug() Speech started; } else if (state QTextToSpeech::Ready) { qDebug() Speech finished; } }); }3.2 Qt Creator 构建套件配置与 Kit 选择Qt 5.10 项目必须匹配精确的构建套件Kit否则texttospeech模块头文件无法找到。在 Qt Creator 中执行以下步骤确认 Qt 版本安装进入Tools → Options → Devices → Qt Versions点击Add选择qmake路径如/opt/Qt5.10/5.10.1/gcc_64/bin/qmake确保版本号显示为5.10.1非5.10.0或5.10.2。创建专用 Kit进入Kits标签页点击Add设置Name:Desktop Qt 5.10.1 GCC 64bitDevice type:DesktopDevice:Local desktopCompiler:GCC (x86_64 linux gnu)需提前在Compilers中添加Qt version: 刚刚添加的Qt 5.10.1Debugger:System GDB激活 Kit 并构建在项目侧边栏Projects→Build Run→Build选择该 Kit点击Run qmakeQt Creator 会自动执行qmake -spec linux-g再点击Build。提示若构建时报错fatal error: QTextToSpeech: No such file or directory说明 Kit 中的 Qt version 未正确关联texttospeech模块——需检查/opt/Qt5.10/5.10.1/gcc_64/lib/cmake/Qt5TextToSpeech/目录是否存在Qt5TextToSpeechConfig.cmake文件。缺失则需重新安装 Qt 5.10 并勾选Text To Speech组件。3.3 插件部署与运行时路径调试构建成功后生成的可执行文件需配套插件才能发声。Qt 5.10 的插件部署必须满足路径约定# 假设构建输出目录为 build-qtspeech-Desktop_Qt_5_10_1_GCC_64bit-Debug/ cd build-qtspeech-Desktop_Qt_5_10_1_GCC_64bit-Debug/ # 创建标准插件目录结构Qt 5.10 严格按此路径查找 mkdir -p plugins/texttospeech/ # 复制插件以 Ubuntu 为例插件位于 Qt 安装目录 cp /opt/Qt5.10/5.10.1/gcc_64/plugins/texttospeech/libqtexttospeech_pulse.so plugins/texttospeech/ cp /opt/Qt5.10/5.10.1/gcc_64/plugins/texttospeech/libqtexttospeech_espeak.so plugins/texttospeech/ # 设置运行时插件路径Qt 5.10 不读取 LD_LIBRARY_PATH 加载插件 export QT_PLUGIN_PATH$PWD/plugins ./qtspeech验证插件加载的终极命令# 运行时打印 Qt 插件搜索路径 ./qtspeech --plugin-path-debug # 检查插件是否被识别Qt 5.10 输出格式固定 QFactoryLoader::QFactoryLoader() checking directory path /path/to/build/plugins/texttospeech ...若输出中未出现texttospeech目录则QT_PLUGIN_PATH设置错误或目录结构不符合plugins/texttospeech/约定。4. Qt 5.10 QTextToSpeech 的语音质量调优与多语言支持实战4.1 语速、音调、音量的 Qt 5.10 原生控制参数Qt 5.10 的QTextToSpeech提供三个可调属性但各平台后端支持度不同。以下为实测有效的参数组合以 Windows SAPI 和 Linux espeak 为例属性Windows SAPIQt 5.10Linux espeakQt 5.10设置方式效果说明rate-10 ~ 10默认 0-100 ~ 100默认 0tts-setRate(5)SAPI 下每单位约 ±5% 语速espeak 下每单位 ±1%pitch-10 ~ 10默认 00 ~ 99默认 50tts-setPitch(7)SAPI 影响音高espeak 影响基频0最低99最高volume0.0 ~ 1.0默认 1.00.0 ~ 1.0默认 1.0tts-setVolume(0.8)全平台通用线性衰减幅度关键限制Qt 5.10 不支持voice属性的实时切换如tts-setVoice(voiceId)必须在say()前调用setVoice()且仅对后续朗读生效。获取可用 voice 列表需// Qt 5.10 下 voice 列表依赖后端SAPI 返回 COM 对象 IDespeak 返回语言代码 for (const QVoice voice : tts-availableVoices()) { qDebug() Voice: voice.name() Language: voice.language() Gender: voice.gender(); // Male/Female/Unknown } // 常见输出(Microsoft David Desktop en-US Male)提示Qt 5.10 的QVoice::name()在 Linux espeak 下返回espeak无法区分具体发音人若需多音色必须编译多个 espeak 插件如libqtexttospeech_espeak_en.so,libqtexttospeech_espeak_zh.so并分别调用setEngine()。4.2 中文语音支持的 Qt 5.10 专项配置Qt 5.10 默认对中文支持薄弱原因在于Windows SAPI 的中文语音包需单独下载如Microsoft Zira Desktop不支持中文需Microsoft LiliLinux espeak 的中文发音质量差默认zh语言使用拼音转写无声调。实测有效的中文方案Windows 下启用 SAPI 中文引擎// 在 say() 前强制设置中文 voice for (const QVoice v : tts-availableVoices()) { if (v.language() zh-CN v.name().contains(Lili)) { tts-setVoice(v); break; } } tts-say(你好Qt 5.10); // 此时将使用 Lili 引擎Linux 下提升 espeak 中文质量编译 espeak 插件时启用--with-phoneme选项并在代码中注入声调标记// Qt 5.10 不支持 SSML需手动转换为 espeak 格式 QString zhText ni3 hao3; // 使用数字声调 tts-say(zhText); // espeak 插件自动识别数字声调跨平台兜底方案预生成音频文件当QTextToSpeech无法满足中文质量要求时Qt 5.10 可无缝集成QSound播放预录制 WAV// 将文本哈希为文件名避免重复生成 QString audioFile QString(cache/%1.wav).arg(qHash(你好)); if (!QFile::exists(audioFile)) { // 调用外部工具生成如 espeak -w cache/xxx.wav 你好 QProcess::execute(espeak -w audioFile \你好\); } QSound::play(audioFile); // Qt 5.10 原生支持 WAV 播放4.3 Qt 5.10 下语音任务队列与错误恢复机制QTextToSpeech在 Qt 5.10 中不提供内置队列连续调用say()会导致前一个任务被中断。实现可靠队列需手动管理class SpeechQueue : public QObject { Q_OBJECT public: explicit SpeechQueue(QTextToSpeech *tts, QObject *parent nullptr) : QObject(parent), m_tts(tts) { connect(m_tts, QTextToSpeech::stateChanged, this, SpeechQueue::onStateChanged); } public slots: void enqueue(const QString text) { m_queue.enqueue(text); if (m_tts-state() QTextToSpeech::Ready !m_queue.isEmpty()) { m_tts-say(m_queue.dequeue()); } } private slots: void onStateChanged(QTextToSpeech::State state) { if (state QTextToSpeech::Ready !m_queue.isEmpty()) { m_tts-say(m_queue.dequeue()); // 自动触发下一个 } } private: QTextToSpeech *m_tts; QQueueQString m_queue; }; // 使用示例 SpeechQueue *queue new SpeechQueue(tts, this); queue-enqueue(第一句); queue-enqueue(第二句); queue-enqueue(第三句);错误恢复关键点Qt 5.10 的QTextToSpeech::errorOccurred信号不可靠常不触发应以stateChanged为主判断若state卡在QTextToSpeech::Paused或QTextToSpeech::Error需调用m_tts-stop()重置状态在嵌入式设备上建议每次say()前检查tts-state() QTextToSpeech::Ready否则stop()say()组合调用。5. Qt 5.10 语音工程的发布打包与跨平台验证清单5.1 Windows 发布DLL 依赖与语音包捆绑策略Qt 5.10 Windows 应用发布需处理三层依赖Qt 运行时 DLL使用windeployqt工具必须匹配 Qt 5.10 版本# 在构建目录执行Qt 5.10 的 windeployqt 位于 bin/ 目录 /opt/Qt5.10/5.10.1/msvc2015_64/bin/windeployqt.exe --no-compiler-runtime --no-opengl-sw ./qtspeech.exeSAPI 语音包无法打包进 EXE需在安装文档中明确要求用户安装Microsoft Speech Platform - Runtime和Chinese (Simplified) Language Pack插件 DLLqtexttospeech_sapi.dll必须置于./plugins/texttospeech/目录且QT_PLUGIN_PATH设为.。验证清单[ ] 运行Dependency Walker检查qtspeech.exe是否缺失Qt5TextToSpeech.dll[ ] 在无 Qt 环境的纯净 Win10 虚拟机中测试确认availableEngines()返回[sapi][ ] 输入中文文本验证是否触发Microsoft Lili引擎任务管理器中观察speechsynth.exe进程。5.2 Linux 嵌入式发布Yocto 构建与插件裁剪在 Yocto如dunfell分支中集成 Qt 5.10 语音支持需修改local.conf# 启用 texttospeech 模块 IMAGE_INSTALL_append qtbase qtdeclarative qttexttospeech # 指定插件espeak 更轻量适合嵌入式 PACKAGECONFIG_append_pn-qtbase texttospeech PACKAGECONFIG_append_pn-qttexttospeech espeak # 避免打包无用插件减少镜像体积 EXCLUDE_FROM_SHLIBS libqtexttospeech_pulse.so构建后在目标设备上验证# 检查插件是否被安装 ls /usr/lib/qt/plugins/texttospeech/ # 应存在 libqtexttospeech_espeak.so # 手动测试插件加载 LD_LIBRARY_PATH/usr/lib/qt/plugins/texttospeech:/usr/lib/qt/lib \ QT_PLUGIN_PATH/usr/lib/qt/plugins \ ./qtspeech --plugin-path-debug关键裁剪技巧删除libqtexttospeech_pulse.so节省 200KB仅保留libqtexttospeech_espeak.so编译 espeak 时禁用 X11 支持./configure --without-x使插件体积降至 150KB 以下在qtspeech.pro中添加QMAKE_LFLAGS -Wl,-z,defs强制符号解析避免运行时undefined symbol错误。5.3 macOS 发布签名与权限适配Qt 5.10 macOS 应用需通过codesign签名才能调用 NSSpeechSynthesizer# 签名主程序 codesign -s Developer ID Application: Your Name --deep --force ./qtspeech.app # 签名插件Qt 5.10 要求每个 .so 文件单独签名 codesign -s Developer ID Application: Your Name ./qtspeech.app/Contents/Plugins/texttospeech/libqtexttospeech_mac.dylib # 启用辅助功能权限首次运行时弹窗 tccutil reset Accessibility权限验证命令# 检查 Accessibility 权限是否授予 tccutil list Accessibility | grep qtspeech # 若未授权需在「系统偏好设置 → 安全性与隐私 → 辅助功能」中手动勾选提示Qt 5.10 的 macOS 插件libqtexttospeech_mac.dylib依赖AppKit.framework若签名后报错Library not loaded: rpath/AppKit.framework/Versions/C/AppKit需在qtspeech.pro中添加QMAKE_LFLAGS -Wl,-rpath,executable_path/../Frameworks并使用macdeployqt工具复制 Framework。本文还有配套的精品资源点击获取
Qt 5.10 QTextToSpeech 跨平台语音合成实战指南
简介本资源是面向Qt开发者尤其C/QML中级以上的语音交互功能实战代码包聚焦Qt 5.10版本下qtspeech模块的跨平台文本转语音TTS与语音识别能力实现。资源完整包含Qt Speech子系统核心源码及多平台适配实现如Windows下的SAPI、Linux的Speech Dispatcher、Android原生接口及Flite轻量级处理器等覆盖QTextToSpeech API封装、信号槽驱动的语音播放控制、语言/语速/音调参数配置等关键实践路径。压缩包共101个文件含26个.pro工程配置、24个.h头文件与23个.cpp实现文件辅以JSON配置、QML集成示例及平台特异性实现如qtexttospeech_winrt.cpp、qtexttospeech_android.cpp总大小仅155KB结构清晰、可直接编译调试。目前已有1656人学习下载读者可获得一套开箱即用的Qt语音功能参考实现深入理解跨平台TTS抽象层设计逻辑并快速复用于无障碍应用、导航播报或教学软件等实际场景。1. QtSpeech 5.10 不是独立库而是 Qt 5.10 中 QTextToSpeech 模块的典型工程命名习惯你在 GitHub、Gitee 或企业内部代码仓库里搜到qtspeech-5.10这个名称大概率不是某个第三方语音 SDK 的发行版而是开发者基于 Qt 官方QTextToSpeech类封装的最小可运行示例项目——它用-5.10显式标注所依赖的 Qt 版本目的是规避 Qt 5.12 引入的插件路径变更、TTS 后端抽象层重构如QTextToSpeechPrivate重设计带来的兼容性断裂。这类项目通常只含 3 个核心文件main.cpp初始化语音引擎、mainwindow.cpp绑定 UI 控件如 QLineEdit 输入文本 QPushButton 触发朗读、qtspeech.pro声明QT texttospeech模块依赖。它解决的实际问题是在嵌入式 Linux如 AM57xx Qt 5.10.1 eglfs或 Windows DesktopMSVC2015环境下绕过系统级语音服务如 Windows SAPI、macOS NSSpeechSynthesizer的权限/注册限制直接调用 Qt 封装的跨平台语音合成接口。适合 Qt 5.9–5.12 跨版本维护的老项目迁移工程师、工业 HMI 开发者以及需要离线语音播报但又不想引入 Python/pyttsx3 或 C 语音引擎如 eSpeak-ng编译依赖的嵌入式团队。2. QTextToSpeech 在 Qt 5.10 中的底层机制与后端选型逻辑2.1 Qt 5.10 的 TTS 架构分层从 API 到平台插件Qt 5.10 的QTextToSpeech类位于QtTextToSpeech模块其设计遵循典型的「抽象接口 平台插件」模式。应用层调用QTextToSpeech::say(Hello)时实际执行链为QTextToSpeech → QTextToSpeechPrivate → QPlatformTextToSpeechPlugin → 具体平台插件如 qtexttospeech_win.dll / libqtexttospeech_pulse.so。关键点在于Qt 5.10不自带语音合成引擎它仅提供统一 API 和插件加载框架具体发音能力完全依赖操作系统原生后端或第三方插件。Windows 下默认使用 SAPI 5.4需系统已安装语音包Linux 下依赖 PulseAudio speech-dispatcher需speech-dispatcher服务运行macOS 则桥接到 NSSpeechSynthesizer。这意味着若你的目标设备是无桌面环境的嵌入式 Linux如 Yocto 构建的 Qt 5.10 镜像QTextToSpeech默认会因找不到libqtexttospeech_pulse.so插件而静默失败——此时必须手动编译并部署适配的插件或切换至qtexttospeech_espeak这类社区插件。提示Qt 5.10 的QTextToSpeech不支持语音识别Speech-to-Text标题中出现的qt语音识别属于常见误标。真正实现语音识别需集成QAudioRecorder 外部 ASR 引擎如 Vosk、Whisper.cpp或使用 Qt 6.5 新增的QVoiceAssistant但该类在 Qt 5.10 中不存在。2.2 Qt 5.10 中 QTextToSpeech 的初始化与状态验证在 Qt 5.10 项目中启用语音功能必须显式链接模块并验证插件加载。以下是最小验证代码#include QApplication #include QTextToSpeech #include QDebug int main(int argc, char *argv[]) { QApplication app(argc, argv); QTextToSpeech *tts new QTextToSpeech; // 关键检查可用引擎数量Qt 5.10 下若返回 0说明插件未就位 qDebug() Available engines: tts-availableEngines(); // 检查当前引擎是否有效Qt 5.10 不自动 fallback需手动 setEngine if (!tts-engine().isEmpty()) { qDebug() Current engine: tts-engine(); } else { qDebug() No default engine set — will use first available; if (!tts-availableEngines().isEmpty()) { tts-setEngine(tts-availableEngines().first()); } } // 测试朗读Qt 5.10 下若无声音优先检查插件路径而非代码 tts-say(Qt 5.10 speech test); return app.exec(); }参数说明与调试要点tts-availableEngines()返回QStringListQt 5.10 Windows 下常见值为[sapi]Linux 下为[pulse, espeak]若为空说明QPLATFORM_PLUGIN_PATH未指向含qtexttospeech_*.so/.dll的目录。tts-setEngine(espeak)可强制指定后端但需确保对应插件已编译并置于插件搜索路径如./plugins/texttospeech/。tts-state()在say()后应短暂变为QTextToSpeech::Speaking若始终为QTextToSpeech::Ready表明引擎未启动成功——此时需检查系统日志Linux 用journalctl -u speech-dispatcherWindows 查事件查看器。2.3 Qt 5.10 的插件路径配置与部署陷阱Qt 5.10 对插件路径的解析严格依赖QCoreApplication::addLibraryPath()和环境变量。常见部署失败场景及修复命令如下场景现象修复命令Linux 示例说明插件目录未被识别availableEngines()返回空列表export QT_PLUGIN_PATH/opt/Qt5.10/pluginsexport QML2_IMPORT_PATH/opt/Qt5.10/qmlQt 5.10 不读取QT_QPA_PLATFORM_PLUGIN_PATH该变量用于 GUI 平台插件非 TTSspeech-dispatcher 服务未运行Linux 下pulse引擎存在但无声sudo systemctl start speech-dispatchersudo systemctl enable speech-dispatcherQt 5.10 的qtexttospeech_pulse.so依赖speech-dispatcher的 D-Bus 接口非直连 PulseAudioWindows 语音包缺失sapi引擎存在但报错SAPI_E_INVALIDARG控制面板 → 语言 → 添加语言 → 中文简体→ 选项 → 下载语音Qt 5.10 调用 SAPI 时需对应语言的 TTS 引擎已安装否则say()无响应注意Qt 5.10 的QTextToSpeech不支持动态加载插件如QLibrary::load()所有插件必须通过标准路径机制发现。若需自定义插件如适配嵌入式 ALSA必须继承QPlatformTextToSpeechPlugin并在plugins/texttospeech/下部署.so文件。3. 在 Qt Creator 中构建 qtspeech-5.10 工程的完整操作链3.1 创建最小可运行工程从 .pro 文件到 UI 绑定新建 Qt Widgets Application 项目后需修改三处核心配置。首先编辑qtspeech.proQT core widgets texttospeech CONFIG c11 # Qt 5.10 必须显式声明 texttospeech 模块否则链接失败 TARGET qtspeech TEMPLATE app SOURCES \ main.cpp \ mainwindow.cpp HEADERS \ mainwindow.h FORMS \ mainwindow.ui # 关键指定插件搜索路径Qt 5.10 默认不包含 texttospeech 目录 PLUGIN_PATH $${OUT_PWD}/plugins QMAKE_POST_LINK $$escape_expand(\\n) mkdir -p $$PLUGIN_PATH/texttospeech然后在mainwindow.ui中拖入QLineEdit对象名lineEditText和QPushButton对象名btnSpeak并在mainwindow.cpp中绑定槽函数#include mainwindow.h #include ui_mainwindow.h #include QTextToSpeech #include QMessageBox MainWindow::MainWindow(QWidget *parent) : QMainWindow(parent) , ui(new Ui::MainWindow) { ui-setupUi(this); // Qt 5.10 下必须在 UI 初始化后创建 tts 实例 m_tts new QTextToSpeech(this); // 连接按钮点击信号到朗读槽 connect(ui-btnSpeak, QPushButton::clicked, this, MainWindow::onSpeakClicked); } void MainWindow::onSpeakClicked() { QString text ui-lineEditText-text().trimmed(); if (text.isEmpty()) { QMessageBox::warning(this, Empty Input, Please enter text to speak); return; } // Qt 5.10 的 say() 是异步调用无需额外线程 m_tts-say(text); // 可选监听状态变化Qt 5.10 支持 stateChanged 信号 connect(m_tts, QTextToSpeech::stateChanged, this, [](QTextToSpeech::State state) { if (state QTextToSpeech::Speaking) { qDebug() Speech started; } else if (state QTextToSpeech::Ready) { qDebug() Speech finished; } }); }3.2 Qt Creator 构建套件配置与 Kit 选择Qt 5.10 项目必须匹配精确的构建套件Kit否则texttospeech模块头文件无法找到。在 Qt Creator 中执行以下步骤确认 Qt 版本安装进入Tools → Options → Devices → Qt Versions点击Add选择qmake路径如/opt/Qt5.10/5.10.1/gcc_64/bin/qmake确保版本号显示为5.10.1非5.10.0或5.10.2。创建专用 Kit进入Kits标签页点击Add设置Name:Desktop Qt 5.10.1 GCC 64bitDevice type:DesktopDevice:Local desktopCompiler:GCC (x86_64 linux gnu)需提前在Compilers中添加Qt version: 刚刚添加的Qt 5.10.1Debugger:System GDB激活 Kit 并构建在项目侧边栏Projects→Build Run→Build选择该 Kit点击Run qmakeQt Creator 会自动执行qmake -spec linux-g再点击Build。提示若构建时报错fatal error: QTextToSpeech: No such file or directory说明 Kit 中的 Qt version 未正确关联texttospeech模块——需检查/opt/Qt5.10/5.10.1/gcc_64/lib/cmake/Qt5TextToSpeech/目录是否存在Qt5TextToSpeechConfig.cmake文件。缺失则需重新安装 Qt 5.10 并勾选Text To Speech组件。3.3 插件部署与运行时路径调试构建成功后生成的可执行文件需配套插件才能发声。Qt 5.10 的插件部署必须满足路径约定# 假设构建输出目录为 build-qtspeech-Desktop_Qt_5_10_1_GCC_64bit-Debug/ cd build-qtspeech-Desktop_Qt_5_10_1_GCC_64bit-Debug/ # 创建标准插件目录结构Qt 5.10 严格按此路径查找 mkdir -p plugins/texttospeech/ # 复制插件以 Ubuntu 为例插件位于 Qt 安装目录 cp /opt/Qt5.10/5.10.1/gcc_64/plugins/texttospeech/libqtexttospeech_pulse.so plugins/texttospeech/ cp /opt/Qt5.10/5.10.1/gcc_64/plugins/texttospeech/libqtexttospeech_espeak.so plugins/texttospeech/ # 设置运行时插件路径Qt 5.10 不读取 LD_LIBRARY_PATH 加载插件 export QT_PLUGIN_PATH$PWD/plugins ./qtspeech验证插件加载的终极命令# 运行时打印 Qt 插件搜索路径 ./qtspeech --plugin-path-debug # 检查插件是否被识别Qt 5.10 输出格式固定 QFactoryLoader::QFactoryLoader() checking directory path /path/to/build/plugins/texttospeech ...若输出中未出现texttospeech目录则QT_PLUGIN_PATH设置错误或目录结构不符合plugins/texttospeech/约定。4. Qt 5.10 QTextToSpeech 的语音质量调优与多语言支持实战4.1 语速、音调、音量的 Qt 5.10 原生控制参数Qt 5.10 的QTextToSpeech提供三个可调属性但各平台后端支持度不同。以下为实测有效的参数组合以 Windows SAPI 和 Linux espeak 为例属性Windows SAPIQt 5.10Linux espeakQt 5.10设置方式效果说明rate-10 ~ 10默认 0-100 ~ 100默认 0tts-setRate(5)SAPI 下每单位约 ±5% 语速espeak 下每单位 ±1%pitch-10 ~ 10默认 00 ~ 99默认 50tts-setPitch(7)SAPI 影响音高espeak 影响基频0最低99最高volume0.0 ~ 1.0默认 1.00.0 ~ 1.0默认 1.0tts-setVolume(0.8)全平台通用线性衰减幅度关键限制Qt 5.10 不支持voice属性的实时切换如tts-setVoice(voiceId)必须在say()前调用setVoice()且仅对后续朗读生效。获取可用 voice 列表需// Qt 5.10 下 voice 列表依赖后端SAPI 返回 COM 对象 IDespeak 返回语言代码 for (const QVoice voice : tts-availableVoices()) { qDebug() Voice: voice.name() Language: voice.language() Gender: voice.gender(); // Male/Female/Unknown } // 常见输出(Microsoft David Desktop en-US Male)提示Qt 5.10 的QVoice::name()在 Linux espeak 下返回espeak无法区分具体发音人若需多音色必须编译多个 espeak 插件如libqtexttospeech_espeak_en.so,libqtexttospeech_espeak_zh.so并分别调用setEngine()。4.2 中文语音支持的 Qt 5.10 专项配置Qt 5.10 默认对中文支持薄弱原因在于Windows SAPI 的中文语音包需单独下载如Microsoft Zira Desktop不支持中文需Microsoft LiliLinux espeak 的中文发音质量差默认zh语言使用拼音转写无声调。实测有效的中文方案Windows 下启用 SAPI 中文引擎// 在 say() 前强制设置中文 voice for (const QVoice v : tts-availableVoices()) { if (v.language() zh-CN v.name().contains(Lili)) { tts-setVoice(v); break; } } tts-say(你好Qt 5.10); // 此时将使用 Lili 引擎Linux 下提升 espeak 中文质量编译 espeak 插件时启用--with-phoneme选项并在代码中注入声调标记// Qt 5.10 不支持 SSML需手动转换为 espeak 格式 QString zhText ni3 hao3; // 使用数字声调 tts-say(zhText); // espeak 插件自动识别数字声调跨平台兜底方案预生成音频文件当QTextToSpeech无法满足中文质量要求时Qt 5.10 可无缝集成QSound播放预录制 WAV// 将文本哈希为文件名避免重复生成 QString audioFile QString(cache/%1.wav).arg(qHash(你好)); if (!QFile::exists(audioFile)) { // 调用外部工具生成如 espeak -w cache/xxx.wav 你好 QProcess::execute(espeak -w audioFile \你好\); } QSound::play(audioFile); // Qt 5.10 原生支持 WAV 播放4.3 Qt 5.10 下语音任务队列与错误恢复机制QTextToSpeech在 Qt 5.10 中不提供内置队列连续调用say()会导致前一个任务被中断。实现可靠队列需手动管理class SpeechQueue : public QObject { Q_OBJECT public: explicit SpeechQueue(QTextToSpeech *tts, QObject *parent nullptr) : QObject(parent), m_tts(tts) { connect(m_tts, QTextToSpeech::stateChanged, this, SpeechQueue::onStateChanged); } public slots: void enqueue(const QString text) { m_queue.enqueue(text); if (m_tts-state() QTextToSpeech::Ready !m_queue.isEmpty()) { m_tts-say(m_queue.dequeue()); } } private slots: void onStateChanged(QTextToSpeech::State state) { if (state QTextToSpeech::Ready !m_queue.isEmpty()) { m_tts-say(m_queue.dequeue()); // 自动触发下一个 } } private: QTextToSpeech *m_tts; QQueueQString m_queue; }; // 使用示例 SpeechQueue *queue new SpeechQueue(tts, this); queue-enqueue(第一句); queue-enqueue(第二句); queue-enqueue(第三句);错误恢复关键点Qt 5.10 的QTextToSpeech::errorOccurred信号不可靠常不触发应以stateChanged为主判断若state卡在QTextToSpeech::Paused或QTextToSpeech::Error需调用m_tts-stop()重置状态在嵌入式设备上建议每次say()前检查tts-state() QTextToSpeech::Ready否则stop()say()组合调用。5. Qt 5.10 语音工程的发布打包与跨平台验证清单5.1 Windows 发布DLL 依赖与语音包捆绑策略Qt 5.10 Windows 应用发布需处理三层依赖Qt 运行时 DLL使用windeployqt工具必须匹配 Qt 5.10 版本# 在构建目录执行Qt 5.10 的 windeployqt 位于 bin/ 目录 /opt/Qt5.10/5.10.1/msvc2015_64/bin/windeployqt.exe --no-compiler-runtime --no-opengl-sw ./qtspeech.exeSAPI 语音包无法打包进 EXE需在安装文档中明确要求用户安装Microsoft Speech Platform - Runtime和Chinese (Simplified) Language Pack插件 DLLqtexttospeech_sapi.dll必须置于./plugins/texttospeech/目录且QT_PLUGIN_PATH设为.。验证清单[ ] 运行Dependency Walker检查qtspeech.exe是否缺失Qt5TextToSpeech.dll[ ] 在无 Qt 环境的纯净 Win10 虚拟机中测试确认availableEngines()返回[sapi][ ] 输入中文文本验证是否触发Microsoft Lili引擎任务管理器中观察speechsynth.exe进程。5.2 Linux 嵌入式发布Yocto 构建与插件裁剪在 Yocto如dunfell分支中集成 Qt 5.10 语音支持需修改local.conf# 启用 texttospeech 模块 IMAGE_INSTALL_append qtbase qtdeclarative qttexttospeech # 指定插件espeak 更轻量适合嵌入式 PACKAGECONFIG_append_pn-qtbase texttospeech PACKAGECONFIG_append_pn-qttexttospeech espeak # 避免打包无用插件减少镜像体积 EXCLUDE_FROM_SHLIBS libqtexttospeech_pulse.so构建后在目标设备上验证# 检查插件是否被安装 ls /usr/lib/qt/plugins/texttospeech/ # 应存在 libqtexttospeech_espeak.so # 手动测试插件加载 LD_LIBRARY_PATH/usr/lib/qt/plugins/texttospeech:/usr/lib/qt/lib \ QT_PLUGIN_PATH/usr/lib/qt/plugins \ ./qtspeech --plugin-path-debug关键裁剪技巧删除libqtexttospeech_pulse.so节省 200KB仅保留libqtexttospeech_espeak.so编译 espeak 时禁用 X11 支持./configure --without-x使插件体积降至 150KB 以下在qtspeech.pro中添加QMAKE_LFLAGS -Wl,-z,defs强制符号解析避免运行时undefined symbol错误。5.3 macOS 发布签名与权限适配Qt 5.10 macOS 应用需通过codesign签名才能调用 NSSpeechSynthesizer# 签名主程序 codesign -s Developer ID Application: Your Name --deep --force ./qtspeech.app # 签名插件Qt 5.10 要求每个 .so 文件单独签名 codesign -s Developer ID Application: Your Name ./qtspeech.app/Contents/Plugins/texttospeech/libqtexttospeech_mac.dylib # 启用辅助功能权限首次运行时弹窗 tccutil reset Accessibility权限验证命令# 检查 Accessibility 权限是否授予 tccutil list Accessibility | grep qtspeech # 若未授权需在「系统偏好设置 → 安全性与隐私 → 辅助功能」中手动勾选提示Qt 5.10 的 macOS 插件libqtexttospeech_mac.dylib依赖AppKit.framework若签名后报错Library not loaded: rpath/AppKit.framework/Versions/C/AppKit需在qtspeech.pro中添加QMAKE_LFLAGS -Wl,-rpath,executable_path/../Frameworks并使用macdeployqt工具复制 Framework。本文还有配套的精品资源点击获取
