10分钟上手 SpeechRecognition：从 pip install 到第一个语音识别程序的分步教程
项目地址: https://gitcode.com/gh_mirrors/spee/speech_recognition-legacy 🎙️ SpeechRecognition 是一个经典的 Python 语音识别库，支持多种引擎与 API，可在线也可离线完成语音转文字。无论你是想给程序加一句"请说话"的语音交互，还是想批量转写音频文件，这篇 10 分钟教程都能带你从 pip install 一路走到能跑起来的第一个语音识别程序。
一、SpeechRecognition 是什么？能做什么？
一句话概括：用统一的 API 调用各种语音识别引擎，录音、转写、后台监听全都封装好了。
它支持的主要引擎：
| 引擎 | 类型 | 说明 |
|---|---|---|
| CMU Sphinx（PocketSphinx） | 离线 | 内置美式英语语言包，无需联网 |
| Google Speech Recognition | 在线 | 免费、开箱即用，支持多语言 |
| Google Cloud Speech API | 在线 | 云端版本，结果更丰富 |
| Azure / Bing / IBM / Wit.ai / Houndify | 在线 | 需各自申请 API Key |
| Snowboy 热词检测 | 离线 | 本地唤醒词 |
核心就三个对象，记住它们就入门了一半：
sr.Recognizer()—— 识别器，负责"听"和"转文字"sr.Microphone()—— 麦克风音频源sr.AudioFile()—— 音频文件音频源
二、一键安装 SpeechRecognition 的最快方法
第 1 步：安装主包
pip install SpeechRecognition
第 2 步：按需安装依赖（装多装少只影响功能范围）：
| 依赖 | 什么时候需要 | 安装方式 |
|---|---|---|
| PyAudio | 要用麦克风录音时 | Windows 直接 pip install pyaudio；Linux 先装 portaudio19-dev 再 pip 安装；macOS 先 brew install portaudio |
| PocketSphinx | 用离线识别 recognize_sphinx 时 | 仓库 third-party/ 目录自带 Windows 平台轮子包，可直接 pip 安装 |
| Google API Client | 用 Google Cloud Speech 时 | pip install google-cloud-speech |
| FLAC 编码器 | 非 x86 平台 | 常见系统已随库内置（见 speech_recognition/ 下的 flac 二进制文件） |
💡 不需要麦克风？不用离线识别？那装完主包就能干活了，缺失的依赖只会让对应功能报错，不会拖垮其他功能。
可选：从源码安装（适合想读代码、跑测试的读者）：
git clone https://gitcode.com/gh_mirrors/spee/speech_recognition-legacy
cd speech_recognition-legacy
python setup.py install
三、零代码体验：一条命令试出声控
装好 pyaudio 后，不用写一行代码，直接运行：
python -m speech_recognition
程序会提示"A moment of silence, please..."，先自动校准环境噪声，然后循环等待你说话，用 Google 语音识别把听到的内容打印出来。按 Ctrl + C 退出。这就是仓库内置的演示脚本（见 speech_recognition/__main__.py）在做的事——建议第一次上手就先跑它，验证麦克风链路没问题。
四、写第一个语音识别程序：麦克风版
验证通过后，写一个 10 行以内的小程序。核心流程只有四步：建识别器 → 打开麦克风 → 听 → 识别。
import speech_recognition as sr
r = sr.Recognizer()
# 1. 从麦克风获取音频
with sr.Microphone() as source:
print("请说话！")
audio = r.listen(source) # 听到说话开始录音，自动检测停顿结束
# 2. 离线识别（本地 Sphinx，无需联网）
try:
print("Sphinx 认为你说的是:", r.recognize_sphinx(audio))
except sr.UnknownValueError:
print("Sphinx 没听清")
# 3. 在线识别（Google，免费、更准）
try:
print("Google 认为你说的是:", r.recognize_google(audio))
except sr.UnknownValueError:
print("Google 没听清")
except sr.RequestError as e:
print("请求识别服务出错:", e)
保存为 my_first.py 运行即可。这段结构与官方示例 examples/microphone_recognition.py 完全一致，该示例还演示了 Azure、IBM、Wit.ai 等所有引擎的调用方式，可以当"引擎速查表"用。
⚠️
sr.UnknownValueError表示"没听清"，sr.RequestError表示"网络/请求失败"——这两个异常一定要捕获，否则一次没听清就会让程序崩溃。
五、第二个程序：转写音频文件（不需要麦克风）
没有麦克风？照样玩。仓库自带测试音频：examples/english.wav、examples/french.aiff、examples/chinese.flac，tests/ 目录还有 8 种采样率的 wav/aiff/flac 文件可供实验。
import speech_recognition as sr
r = sr.Recognizer()
# 把音频文件当作用源，一次读完整段音频
with sr.AudioFile("examples/english.wav") as source:
audio = r.record(source)
print("识别结果:", r.recognize_google(audio))
对应示例代码见 examples/audio_transcribe.py。支持的格式：WAV（须为 PCM 格式）、AIFF、FLAC。
六、识别不准？用"环境噪声校准"调好灵敏度
新手最常遇到的问题：不说话时也触发、或者刚启动时听不到。根源是能量阈值（energy_threshold）没调好，它决定了识别器对"什么时候该开始听"的敏感度，常见合理范围是 50 ~ 4000。
两招解决：
- 自动校准：录音前先让识别器安静监听 1 秒，自动设定合适的阈值：
with sr.Microphone() as source:
r.adjust_for_ambient_noise(source) # 校准环境噪声
audio = r.listen(source)
- 手动微调：嘈杂环境调大
r.energy_threshold，安静环境调小。
完整的校准演示在 examples/calibrate_energy_threshold.py。另外检查一下系统麦克风音量：太灵敏会拾取环境噪声，太迟钝会把人声当噪声丢掉。
七、新手常见问题速查表
| 症状 | 快速解决方案 |
|---|---|
报 No Default Input Device Available | 系统里没有默认输入设备，用 sr.Microphone(device_index=N) 指定麦克风 |
| 不知道麦克风索引号是多少 | 运行 sr.Microphone.list_microphone_names() 打印所有设备及对应索引 |
| 不说话也触发识别 | 调大 energy_threshold 或先 adjust_for_ambient_noise |
| 刚启动时识别不到声音 | 阈值初始过高，先调用 adjust_for_ambient_noise 校准 |
| 识别错语言/方言 | 给识别函数传 language="en-GB" 等更精确的语言代码 |
Python 2 打印中文报 UnicodeEncodeError | 把 print x 改为 print x.encode("utf8")（Python 3 不需要） |
树莓派上 listen 卡死 | 板载无音频输入，接 USB 声卡后指定 device_index |
这些问题在 README 的 Troubleshooting 一节都有详细说明，照着查基本 1 分钟定位。
八、进阶玩法与项目结构速览
跑通前两个程序后，可以按兴趣解锁这些进阶示例（都在 examples/ 目录）：
- 🔊 后台持续监听：
background_listening.py—— 主线程干别的活，麦克风在后台边听边识别 - 💾 保存录音到文件：
write_audio.py—— 把识别结果连同 WAV 音频一起存档 - 📊 查看完整识别结果：
extended_results.py——show_all=True拿到置信度等扩展数据 - 🧩 各种实用特性：
special_recognizer_features.py - 🧮 离线命令词识别：
tensorflow_commands.py+counting.gram语法规则文件，用 PocketSphinx 做离线数字/命令识别
项目结构速览：
| 路径 | 内容 |
|---|---|
speech_recognition/__init__.py | 库的全部核心代码 |
speech_recognition/__main__.py | python -m speech_recognition 演示入口 |
speech_recognition/pocketsphinx-data/en-US/ | 内置的离线英语识别模型 |
examples/ | 7 个官方用法示例 + 测试音频 |
tests/ | 单元测试和多采样率测试音频 |
reference/ | 完整 API 参考文档（library-reference.rst） |
third-party/ | PyAudio、PocketSphinx 等第三方包 |
九、小结：10 分钟你已完成的事
- ✅
pip install SpeechRecognition一键安装 - ✅
python -m speech_recognition零代码体验 - ✅ 手写麦克风识别小程序
- ✅ 转写音频文件的离线工作流
- ✅ 掌握噪声校准与常见问题自救
接下来建议的顺序：先跑 background_listening.py 感受"边听边干"的异步能力，再折腾离线 Sphinx 语言包（参考 reference/pocketsphinx.rst）让识别彻底摆脱网络。祝玩得开心！🚀
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
