简介：这份资源聚焦微软SAPI（语音应用程序接口）在文本阅读场景中的应用，面向希望在Windows平台快速实现语音合成功能的开发者，也适合作为学习TTS接口的入门示例。压缩包共两个文件，包含一个HTML格式的说明文档和一个RAR资源包，整体大小仅26KB，轻巧且便于直接查阅。目前已有265人学习/下载。内容围绕SAPI的核心组件展开，具体包括文本转语音（TTS）、语音识别（STT）、ISpVoice语音合成引擎、语音识别引擎，以及可自定义的语法和词汇表，并支持事件驱动处理；示例程序从初始化SAPI开始，到选择语音引擎、调整音速音调、读取文本、调用Speak方法合成语音，最后正确关闭并释放资源，完整展示了文本阅读程序的开发链路。通过这份资源，开发者既能理解SAPI对象模型和调用流程，也能直接参考示例改造出有声朗读、语音提示等实用工具，从而快速上手Windows语音编程。
1. sapi.zip_SAPI：Windows 老语音项目里最需要你搞懂的那包东西
第一次看到“sapi.zip_SAPI”这个命名，大多数人会以为它是一个可以直接解压安装的语音引擎包，或者是某个开源项目的发布产物。实际上，这个压缩包指向的是 Windows 平台上那套历史悠久但至今仍被大量桌面程序依赖的 SAPI（Speech Application Programming Interface）。语音合成、机器朗读、语音命令识别，只要是跑在 Windows 上的老系统，背后十有八九都有 sapi.dll 在支撑。这篇笔记按照我处理这类包的习惯来写：先拆包看结构，再分两步把 TTS 和 SR 跑通，把参数、边界和踩坑点一次性讲透，让拿到这个包的人能真正把它用起来。
2. 拆解 sapi.zip：先看懂包里是源码还是二进制，再决定用哪套 SAPI
2.1 压缩包里常见的文件形态与职责边界
我经手过的 sapi.zip 变形包，文件组成五花八门，但通常绕不开头文件、导入库、运行时组件和示例代码这几类。最常见的最小形态是sapi.h加上sapi.lib，另配一个或多个.cpp示例工程。拿到包的第一步不是解压后直接双击编译，而是先判断这个包到底是什么性质：里面有完整sln的是示例源码包，这种包可以直接打开编译，但里面的工程文件通常停留在 Visual Studio 6 或 2003 时代，需要升级；只有sapi.h和sapi.lib的是开发引用包，它只提供 C++ 接口声明和导入库，链接时还需要系统里有sapi.dll；如果包里只有一个裸的sapi.dll，那多半是运行时补丁包，主要给精简版系统补组件用。
判断包性质决定了后续动作，也关系到你会不会白折腾。SAPI 是 COM 体系，头文件和导入库必须与系统里的 sapi.dll 版本匹配。如果你把 2001 年前后的 sapi.h 拿来喂给新编译器，运气好能编过，运气不好就会出现大量“无法解析的外部符号”，因为 SAPI 5.1 和 SAPI 5.4 在接口定义上并不完全二进制兼容。我改造过一个老调度系统，工程里带着一份旧版 sapi.lib，一链接冒出 20 多个 LNK2019，换掉旧 lib 才消停。这也是为什么我不建议强力依赖包内自带头文件的原因。
下表是 sapi.zip 里最常见文件的职责说明，方便你打开包后对照：
| 文件 | 作用 | 使用阶段 |
|---|---|---|
| sapi.h | SAPI 主接口声明，包含语音合成与识别核心接口 | 编译时必须 |
| sapi.lib | 导入库，负责把接口调用符号链接到 sapi.dll | 链接时必须 |
| sapi.dll | 运行时组件，Win10/Win11 通常已内置在 System32 | 运行时必须 |
| sphelper.h | SAPI 的 C++ 辅助模板，提供令牌与音频流封装 | 按示例代码需要 |
| spstreamformat.h | 音频流格式辅助类，TTS 输出文件时常用 | 按示例代码需要 |
| sample_tts.cpp | 语音合成示例 | 参考或直接编译 |
| reco_demo.cpp | 语音识别示例 | 参考或直接编译 |
2.2 版本选型：SAPI 5.4 与旧包头文件之间的兼容边界
SAPI 从 5.1 走到 5.4，接口经历了多轮调整。Windows XP 时代默认是 SAPI 5.1，Windows Vista 开始内置 5.3，Win7 及以后统一是 5.4。sapi.zip 如果是老机器上扒下来的，头文件大概率停留在 5.1 或 5.2。怎么快速辨别？打开 sapi.h，搜索SAPI_VERSION或SAPI_BUILD_VERSION，值 54 就是 5.4，51 就是 5.1。很多人在新系统上用旧头文件编译没报错，运行却提示“语音引擎不可用”或“接口不支持”，就是头文件里的接口行为与系统语音引擎对不上。
我的选型原则很简单：不管压缩包里带的是什么版本，目标机器只要是 Win10/Win11，统一使用 Windows SDK 自带的 SAPI 5.4 头文件和导入库。包里的示例逻辑可以抄，但不要抄它的 sapi.h 和 sapi.lib。具体操作是在 VS 工程里把“附加包含目录”指向 Windows SDK 的include目录，而不是 sapi.zip 解压目录。如果示例代码用的是ISpVoice、ISpRecognizer这些经典接口，5.4 完全兼容；如果用到SpInit这种上古 API，那就只能当参考了，老实重写。
2.3 最小验证环境：先确认系统里真的有能用的语音引擎
写代码之前，先花两分钟确认目标机器上有可用的 SAPI 语音引擎，尤其是中文语音。很多精简版系统把语音包裁掉了，代码写得再对，调用Speak还是返回0x80045006。在 Windows 命令行里可以用 PowerShell 直接查注册表：
Get-ChildItem "HKLM:\SOFTWARE\Microsoft\Speech\Voices" -Recurse这个命令枚举的是 64 位视角下注册的语音引擎令牌。每条输出对应一个SPVOICETOKEN，里面有 FriendlyName 和 VoicePath。看到Microsoft Huihui Desktop、Microsoft Xiaoxiao这类中文名称，说明语音引擎就位；如果列表为空，需要到系统设置里安装中文语音包。还要注意，32 位程序读的是注册表WOW6432Node镜像，如果你用 64 位 PowerShell 查到的列表和 32 位程序能用的列表不一致，是很正常的。
还有一种情况是注册表能看到引擎，代码里也选了它，但读出来的是英文腔调。这通常不是代码问题，而是默认语音引擎没有选中中文令牌，需要显式调用SetToken或SelectToken。这个参数问题放在第 3 章解决。
3. 用 C++ 调通 SAPI 合成：从 SpVoice 到文件输出的一整套参数
3.1 初始化 COM 与创建 SpVoice 的最小步骤
SAPI 是 COM 接口，所以所有调用前置工作是初始化 COM 单元。很多翻车现场都是只创建接口没调CoInitializeEx，然后接口返回REGDB_E_NOTINITIALIZED。下面的代码是能编译的最小骨架，我建议先把这个流程跑通，再加业务逻辑：
#include <sapi.h> #include <iostream> int main() { HRESULT hr = CoInitializeEx(nullptr, COINIT_MULTITHREADED); if (FAILED(hr)) { std::cerr << "COM init failed: 0x" << std::hex << hr << std::endl; return 1; } ISpVoice* pVoice = nullptr; hr = CoCreateInstance(CLSID_SpVoice, nullptr, CLSCTX_ALL, IID_ISpVoice, reinterpret_cast<void**>(&pVoice)); if (FAILED(hr)) { std::cerr << "CoCreateInstance(SpVoice) failed: 0x" << std::hex << hr << std::endl; CoUninitialize(); return 1; } hr = pVoice->Speak(L"你好，这是 sapi 的测试。", SPF_DEFAULT, nullptr); if (FAILED(hr)) { std::cerr << "Speak failed: 0x" << std::hex << hr << std::endl; } pVoice->Release(); CoUninitialize(); return 0; }这段代码里有两个关键点。第一，COINIT_MULTITHREADED是 SAPI 接口最常见的 COM 模式。我用STA也能跑通，但在回调线程和事件等待时容易死锁，所以习惯在主线程直接初始化成 MTA。第二，SPF_DEFAULT是同步朗读标志，它会阻塞Speak直到朗读结束。如果你用SPF_ASYNC，后面必须用WaitUntilDone或事件同步，否则程序退出时语音线程还在读，声音戛然而止。新手先开同步，等整条链路稳定后再切异步。
3.2 语音、音量、语速：三个必调的发音参数
默认语音引擎按系统 locale 自动选，但老包里经常存在硬编码语音名导致中文被英文腔读的问题。显式选择语音令牌是解决这个问题的正路。我每次调通语音都会固定调三个参数：选语音、设置音量、设置语速。下面这套代码可以直接抄：
void ApplyVoiceSettings(ISpVoice* pVoice) { IEnumSpObjectTokens* pEnum = nullptr; // 第一个参数传空表示所有语音类别，第二个参数用属性过滤中文 pVoice->GetVoices(L"", L"Language=804", &pEnum); ULONG count = 0; if (pEnum && SUCCEEDED(pEnum->GetCount(&count)) && count > 0) { ISpObjectToken* pToken = nullptr; pEnum->Item(0, &pToken); pVoice->SetToken(pToken); pToken->Release(); } if (pEnum) pEnum->Release(); pVoice->SetVolume(100); // 0 到 100 pVoice->SetRate(0); // -10 到 10 pVoice->SetSyncSpeakTimeout(3000); // 超时保护 }GetVoices的第二个参数是属性过滤条件，Language=804对应中文简体，这样枚举出来的第一个令牌就是系统里的中文语音。注意不要把第一个参数写成L"Language=804"，很多老代码这么写其实是错的，第一个参数是类别名，传空字符串才是通用做法。SetRate(0)是正常语速，SetRate(-2)更适合读长文本，SetRate(3)适合做快速提示播报。SetSyncSpeakTimeout(3000)这个参数很多人不知道，默认超时是无限大，如果声卡驱动出问题，Speak会一直卡住，这里给它加了 3 秒保险。
3.3 输出到 WAV 文件：和扬声器播放完全不同的链路
实时播报只是语音合成的一半需求，另一半需求是把文本转成语音文件，再下发到客户端或融媒体平台。这时候要把SpVoice的输出从默认设备切换到ISpStream上。常见做法是创建CLSID_SpStream，绑定一个文件，再SetOutput指过去：
#include <spstreamformat.h> ISpStream* pStream = nullptr; HRESULT hr = CoCreateInstance(CLSID_SpStream, nullptr, CLSCTX_ALL, IID_ISpStream, reinterpret_cast<void**>(&pStream)); CSpStreamFormat format(SPFMT_22kHz16BitMono, &hr); hr = pStream->BindToFile(L"output.wav", SPFM_CREATE_ALWAYS, &format.FormatId(), format.WaveFormatExPtr(), 0); pVoice->SetOutput(pStream, TRUE); pVoice->Speak(L"把这段话写进文件", SPF_DEFAULT, nullptr); pStream->Close(); pStream->Release();这里SPFM_CREATE_ALWAYS表示文件已存在就清空重建。如果要多次追加内容到同一个文件，应该用SPFM_CREATE_NEW并自己处理文件拼接。SPFMT_22kHz16BitMono是单声道 22kHz 16 位量化，每分钟文件大小约 2.6MB。如果生成的文件要喂给语音识别引擎训练，建议用SPFMT_16kHz16BitMono，识别引擎普遍更喜欢 16kHz 采样率。我见过最典型的错误是输出完文件后忘了把输出设备切回来，导致后续再调Speak时声音进了文件而不是声卡，程序重启才恢复。这里补一个pVoice->SetOutput(nullptr, TRUE)就能避免。
注意：
SetOutput(nullptr, TRUE)在 SAPI 5.4 里表示把输出切回默认音频设备。老包代码里如果是用SetOutput(NULL, FALSE)，第二参数必须为 TRUE，否则新输出对象不会自动释放，容易造成内存泄漏。
4. 用 SAPI 识别：ISpRecognizer 与语法这两道关
4.1 创建共享识别器并等待结果的完整流程
语音合成是 SAPI 里比较顺的一段，识别复杂得多。首要区别是识别器分共享和进程内两种：CLSID_SpSharedRecognizer走系统语音识别服务，适合桌面助手；CLSID_SpInprocRecognizer在进程内跑，延迟更低但需要自己维护模型。sapi.zip 里给的示例大多用共享识别器，因为省事。下面这段是创建上下文并识别一个词的核心骨架：
#include <sapi.h> int reco_once() { CoInitializeEx(nullptr, COINIT_MULTITHREADED); ISpRecognizer* pReco = nullptr; HRESULT hr = CoCreateInstance(CLSID_SpRecognizer, nullptr, CLSCTX_ALL, IID_ISpRecognizer, reinterpret_cast<void**>(&pReco)); if (SUCCEEDED(hr)) hr = pReco->SetRecoState(SPRST_ACTIVE); ISpRecoContext* pContext = nullptr; if (SUCCEEDED(hr)) hr = pReco->CreateRecoContext(&pContext); if (SUCCEEDED(hr)) hr = pContext->SetInterest(SPFEI_RECOGNITION, SPFEI_RECOGNITION); ISpRecoGrammar* pGrammar = nullptr; if (SUCCEEDED(hr)) hr = pContext->CreateGrammar(0, &pGrammar); if (SUCCEEDED(hr)) { SPSTATEHANDLE hState = nullptr; pGrammar->GetState(L"Root", &hState); pGrammar->AddWordTransition(hState, hState, L"你好", L" ", SPWT_LEXICAL, nullptr, nullptr, nullptr); pGrammar->SetRuleState(L"Root", nullptr, SPRS_ACTIVE); } ISpRecoResult* pResult = nullptr; if (SUCCEEDED(hr) && pContext->WaitForEvent(5000, &pResult) == S_OK) { SPPHRASE* pPhrase = nullptr; pResult->GetPhrase(&pPhrase); if (pPhrase) { for (ULONG i = 0; i < pPhrase->Rule.ulCountOfElements; ++i) { wprintf(L"%s ", pPhrase->pElements[i].pszLexical); } ::CoTaskMemFree(pPhrase); } pResult->Release(); } pGrammar->Release(); pContext->Release(); pReco->Release(); CoUninitialize(); return 0; }这段代码已经能跑通一次识别。WaitForEvent(5000)会阻塞等待一条识别结果，5 秒超时后返回S_FALSE，这里有翻车风险：如果你把超时设成INFINITE，整个程序会挂在等待上，界面完全卡死。SetInterest指定只关心识别完成事件，避免其他语音事件干扰。在实际 GUI 程序里我不建议用这种阻塞式写法，第 6 章会讲事件回调方案。
4.2 限定语法还是自由听写？识别效果天差地别
SAPI 识别器默认看起来什么都能听，其实那是自由听写模式。托管在系统级识别引擎里的自由听写模型，在安静环境下准确率也只有八成左右，一旦有风扇声、键盘声就崩。sapi.zip 里的老示例多半直接用了注册表里的 dictation 配置，我第一次跑的时候对着麦克风喊“打开窗口”，结果识别出来的是一串无关词。之后我才意识到问题出在模式选错，而不是麦克风太差。
正确做法是给识别器挂一个识别语法树，只认你预先定义的那几个短语。第 4.1 节的代码就是限定语法：AddWordTransition把“你好”加进Root状态，语法加载后识别器只在这条语法上匹配。这个模式有两个好处：准确率能从 80% 跳到 95% 以上，响应速度也明显变快。缺点同样明显——不在语法里注册的词，它永远听不见。所以做命令控制类项目时，我会把所有命令词铺进一张表，循环AddWordTransition注册，而不是让识别器自由发挥。识别语法的设计要照顾同音词，比如“打开”和“打垮”在快速朗读时很像，能避就避。
4.3 从识别结果中提取文本：直接读 SPPHRASE 而不是拼字符串
很多刚接触 SAPI 的人拿到ISpRecoResult后会去找GetText方法。这个接口的参数比较绕，而且不同版本行为有差异。更干脆的做法是像第 4.1 节那样，用GetPhrase拿SPPHRASE结构，再遍历pElements。每个SPPHRASEELEMENT里有pszLexical、pszDisplayText和pszPronunciation，分别对应原始读音、显示文本和音标。代码里我打印的是pszLexical，它对中文输出的是近似拼音。如果你希望结果更接近书写形式，例如“你好”而不是“ni hao”，应该用pszDisplayText，它在 SAPI 识别引擎经过语言模型处理后，输出的是更稳定的文本形式。西文场景两者差别不大，中文场景差别很大。
内存处理是个容易漏的坑：GetPhrase返回的SPPHRASE结构由 COM 内存分配器分配，必须用CoTaskMemFree释放，不能普通free。我见过项目在循环里泄漏SPPHRASE，内存一路涨到 1GB 以上。另外，释放后整个pPhrase->pElements指针都会失效，所以如果你要把结果转成std::wstring再做后续逻辑，记得在释放前先拷贝出来。
5. SAPI 常见问题排查：解压后跑不通的 5 个真实坑
5.1 现象：Speak 返回 0x80045006，程序不报错但没有任何声音
原因：这个错误码是SPERR_NOT_FOUND，通常表示找不到对应的语音引擎或令牌。系统语音包被裁剪，或者代码里SelectToken指定了一个不存在的语音名，都可能导致这个结果。
解决：先用第 2 章的 PowerShell 命令查注册表里的 Voices，看 FriendlyName 和 VoicePath。然后在代码里用GetVoices枚举全部可用令牌，打印出来和你写的名字对照。这里有一个非常隐蔽的点：32 位进程读的是 WOW6432Node 注册表镜像，如果你用 64 位 PowerShell 查到一堆名字，不代表 32 位程序能看见它们。我实际上遇到过一台机器上语音引擎不存在却硬编码名字的情况，最后用GetVoices枚举才发现真正的令牌名和文档里写的不一样。
5.2 现象：x64 工程链接 sapi.lib 后出现数百个 LNK2019
原因：老包里的 sapi.lib 是 32 位导入库，x64 链接器当然找不到导出符号。另一种情况是包里的 sapi.h 与 Windows SDK 自带的头文件重复定义，产生一堆 C2011 或 LNK2005。
解决：把工程配置改成只使用 Windows SDK 的 sapi.lib，从项目文件里排除掉 sapi.zip 解压出来的 sapi.h 和 sapi.lib。如果项目必须兼容 32 位老机器，再单独建一个 x86 配置，各自链接各自位数的库。不要试图在同一个工程里同时引用两套头文件，那是自己给自己挖坑。
5.3 现象：CoCreateInstance 成功，但调用 SetOutput 或 SetRate 返回 REGDB_E_NOTINITIALIZED
原因：COM 没有初始化，或者初始化的线程模型和当前调用线程不一致。很多人把CoInitializeEx写在主线程入口，后续却在线程池回调里调用 SAPI 接口，线程池线程没有 COM 上下文，接口即使创建出来，后续调用也会挂。
解决：在真正调用 SAPI 的线程入口重新执行CoInitializeEx(nullptr, COINIT_MULTITHREADED)，并保证CoUninitialize成对出现。如果是窗口程序，建议在做串口或消息监听的工作线程里初始化，不要在OnCreate里初始化后放到任意线程使用。血泪教训是：我早期在定时器回调里调用 SAPI，为了省事没开 COM，直接导致音频文件生成失败，排查了一天才发现是 COM 线程模型问题。
5.4 现象：中文文本没有声音，英文朗读却正常
原因：默认语音引擎是英文语音，中文汉字映射不到发音引擎上。代码里没有显式选择中文语音令牌时，SAPI 会根据系统 locale 选择，但很多精简系统只装了英文语音。
解决：显式选择中文语音令牌。代码里最稳的方式是通过GetVoices(L"", L"Language=804", &pEnum)枚举后取第一个，而不是硬编码“Microsoft Huihui Desktop”。这个字符串在 Win10 和 Win11 上并不固定，硬编码迟早翻车。第 3 章的ApplyVoiceSettings就是干这个的。
5.5 现象：程序在开发机正常，拷到别的机器上说找不到 sapi.dll
原因：目标机器没有完整的 SAPI 运行库。Windows XP 时代需要单独装 SAPI SDK，现在 Win10/11 系统内置 sapi.dll 在 System32，但有些精简版系统把语音组件全砍了。
解决：直接把 sapi.dll 拷到程序目录不一定有效，因为 SAPI 组件是 COM 注册的，没有注册信息，直接加载也不一定被CoCreateInstance找到。最靠谱的方案是要求目标机器是完整版 Windows，或者用 DISM 把语音组件装回去。程序侧可以加一个启动检查，用LoadLibraryW(L"sapi.dll")探一下，如果加载失败就弹一个友好的错误提示，比运行时黑匣子给“接口不支持”要好得多。
6. 把 sapi.zip 里的示例改造成可维护模块：三处值得动刀的位置
6.1 用事件回调替代阻塞式 WaitForEvent
第 4 章的示例用WaitForEvent(5000)做阻塞识别，命令行下没问题，但放进 GUI 程序就会卡死界面。SAPI 支持把识别事件投递到窗口消息，核心方法是SetNotifyWindowMessage。常见做法是创建上下文之后，把窗口句柄和自定义消息传进去：
pContext->SetNotifyWindowMessage(hWnd, WM_APP + 101, 0, 0); pContext->SetInterest(SPFEI_RECOGNITION, SPFEI_RECOGNITION);然后在WndProc里响应这条消息，从消息参数里取出ISpRecoResult*，用完以后Release。这样识别完全异步，UI 不卡，用户交互也不会因为一段长停顿而假死。这是把老包代码移植到现代应用时最值得做的一步改动。
6.2 把语音合成封装成一个简单类
老代码里的ISpVoice*、ISpStream*散落在各个全局函数里，能用但不好维护。我会把整个 TTS 封装成SimpleTts类，构造函数初始化 COM 和创建SpVoice，析构函数负责释放，对外只暴露SpeakText和SaveToFile。这样业务层永远接触不到 COM 裸指针，也不会忘记释放。识别部分类似，封装成RecoEngine，对外暴露SetCommandList和StartListen。这套改法不改变 SAPI 行为，只是把命令式示例变成 RAII 风格，让后来接手的人少踩几次空指针。
6.3 验证改造成果的最快方法
最后分享一个我常用的验证技巧：把语音引擎的输出全部导向文件，然后拉几条边界输入跑回归。比如同一段文本分别用SetRate(-10)、SetRate(0)、SetRate(10)生成三个 WAV，检查文件大小和时长是否符合预期。识别模块则准备一份“命令词、同音词、无关词”三类测试集，统计命中率和误识别率。这比对着扬声器听声儿可靠得多，因为声卡直通会掩盖很多参数问题。我一直保留着“先录音再听”的习惯，也建议你把自动回归脚本留在工程里，方便后续改参数时对照。希望帮到你。
本文还有配套的精品资源，点击获取
