macos-stt

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

每台 Mac 里都内置了一个强大的本地语音识别引擎——Siri 用它，听写也用它。但 Apple 没把它暴露给开发者。这个库就是来填坑的：不下载模型、不注册 API Key、不联网，直接调系统引擎。Apple Silicon 和 Intel Mac 都能用。

特点

• 零配置 — 不下载模型，不注册 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。