macos-stt

macOS 系统语音识别 — 零配置，全离线，63 种语言。

Stop downloading 3GB models. Your Mac already has a world-class speech recognizer built in. Siri uses it. Dictation uses it. Now your Python scripts can too. Zero model downloads, zero API keys, zero network. Works on Apple Silicon and Intel.

特点

• 零配置 — 不下载模型，不注册 Key，不签协议
• 全离线 — 飞行模式也能用，数据不离开本机
• 63 种语言 — Apple 引擎支持的所有语言，含中文（zh-CN）、粤语（yue-CN）、日语、英语等
• 三种接口 — Python 库、CLI 命令行、HTTP 服务
• 快 — M1 Pro 上 3 秒音频约 300ms 完成（ANE 加速）

安装

pip install macos-stt
# 仅支持 macOS，Python 3.9+

# 可选：HTTP 服务
pip install macos-stt[server]

快速开始

Python 库

from macos_stt import recognize, recognize_bytes, list_languages

# 查看支持的语言
print(len(list_languages()))  # 63

# 识别音频文件（WAV、MP3、M4A 等所有 macOS 支持的格式）
text = recognize("录音.wav", language="zh-CN")
print(text)

# 识别 PCM 字节流
with open("audio.pcm", "rb") as f:
    text = recognize_bytes(f.read(), sample_rate=16000, language="zh-CN")

CLI

macos-stt 录音.wav                        # 默认中文
macos-stt --lang en-US audio.mp3           # 英文
macos-stt --json 录音.wav                  # JSON 输出
cat audio.pcm | macos-stt --raw --sr 16000  # 管道输入
macos-stt list-languages                   # 列出 63 种语言
macos-stt serve --port 8765                # 启动 HTTP 服务

HTTP 服务

macos-stt serve

# POST /transcribe       — 文件上传识别
# POST /transcribe/raw   — base64 PCM 字节流
# GET  /languages        — 语言列表
# GET  /health           — 健康检查

# 测试：
curl -F "file=@录音.wav" -F "lang=zh-CN" http://127.0.0.1:8765/transcribe

流式识别（Beta）

from macos_stt.streaming import StreamingRecognizer

sr = StreamingRecognizer(language="zh-CN")
sr.start()
sr.feed(audio_chunk_1)  # 逐块喂入
sr.feed(audio_chunk_2)
result = sr.finish()     # 等最终结果

跟其他方案对比

所有其他方案都要下载好几个 G 的模型。macos-stt 用的是 Mac 上已有的引擎。

API 参考

recognize(path, *, language="zh-CN", timeout=15.0) -> RecognitionResult

识别音频文件。支持 WAV、MP3、M4A、FLAC 等 macOS 所有原生格式。

recognize_bytes(data, sample_rate, *, language="zh-CN", timeout=15.0) -> RecognitionResult

识别原始 16-bit 单声道 PCM 字节流。不需要写临时文件。

RecognitionResult

• text: str — 识别文字
• confidence: float — 固定 1.0（系统引擎不暴露逐词置信度）
• language: str — 使用的语言代码

原理

通过 PyObjC 桥接 Apple 的 SFSpeechRecognizer。核心踩坑：

• SFSpeechRecognizer 的回调必须由主线程 RunLoop 派发——用子线程 + CFRunLoop 处理
• 音频通过临时 WAV 文件传给 SFSpeechURLRecognitionRequest
• 授权在首次调用时自动请求并缓存
• 流式模式用 SFSpeechAudioBufferRecognitionRequest + dispatch_sync 主队列

后续计划

macos-stt 是 macos-ml 家族的第一个项目。macOS 上还有很多未暴露的系统 ML 能力：

• macos-audio — SNAudioClassifier，425+ 种声音分类（狗叫、婴儿哭、玻璃碎…）
• macos-embed — NLEmbedding，7 种语言词向量，零下载
• macos-vision — Vision 框架，OCR、人脸检测、图像相似度

有兴趣一起搞的，欢迎开 Issue 讨论。

License

MIT. 详见 LICENSE。