Metadata-Version: 2.4
Name: macos-stt
Version: 0.1.0
Summary: macOS system speech recognition — zero config, fully offline, 63 languages
Author: macos-stt contributors
License: MIT
Project-URL: Homepage, https://github.com/bannana/macos-stt
Project-URL: Repository, https://github.com/bannana/macos-stt
Keywords: macos,speech,stt,speech-to-text,offline,apple-silicon
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyobjc-framework-speech>=10.0
Requires-Dist: typer>=0.9
Provides-Extra: server
Requires-Dist: fastapi>=0.100; extra == "server"
Requires-Dist: uvicorn>=0.20; extra == "server"
Requires-Dist: python-multipart>=0.0.5; extra == "server"
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: pytest-asyncio; extra == "dev"
Dynamic: license-file

# macos-stt

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

[![Python](https://img.shields.io/badge/python-%3E%3D3.9-blue)](https://www.python.org/)
[![macOS](https://img.shields.io/badge/platform-macOS-lightgrey)](https://apple.com/macos)
[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)

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

## 特点

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

## 安装

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

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

## 快速开始

### Python 库

```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

```bash
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 服务

```bash
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）

```python
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()     # 等最终结果
```

## 跟其他方案对比

| 库 | 底层引擎 | 要下载模型？ | 离线？ |
|---|---|---|---|
| `macos-stt` | **macOS 系统**（SFSpeechRecognizer） | **0** | ✅ |
| `openai-whisper` | Whisper | 1-3 GB | ✅ |
| `faster-whisper` | Whisper (CTranslate2) | 1-3 GB | ✅ |
| `mlx-whisper` | Whisper (MLX，Apple Silicon) | 1-3 GB | ✅ |
| `whisper.cpp` | Whisper (C++) | 1-3 GB | ✅ |

所有其他方案都要下载好几个 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](LICENSE)。
