# speak2txt

**Repository Path**: machinelearningLS/speak2txt

## Basic Information

- **Project Name**: speak2txt
- **Description**: 一个简单、强大、支持中文的命令行音频转文本工具，基于 OpenAI Whisper，支持批量处理、字幕生成、GPU 加速和离线部署。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-06-25
- **Last Updated**: 2026-06-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🗣️ speak2txt — 音频转文字工具（基于 Whisper）

> 一个简单、强大、支持中文的命令行音频转文本工具，基于 OpenAI Whisper，支持批量处理、字幕生成、GPU 加速和离线部署。

![Python](https://img.shields.io/badge/Python-3.8%2B-blue)
![License](https://img.shields.io/badge/License-MIT-green)
![Whisper](https://img.shields.io/badge/Model-Whisper%20(large--v2%2Fv3)-orange)

将你的 `.wav`、`.mp3`、`.m4a` 等音频文件一键转为文本或字幕，支持自动语言识别，中文转录准确率高！

---

## ✨ 功能亮点

- ✅ **自动 GPU 加速**（CUDA 可用时自动启用）
- ✅ **批量转录**：支持通配符（如 `*.mp3`）
- ✅ **双输出格式**：
  - `.txt`：带元信息的完整转录文本
  - `.srt`：标准字幕文件（带时间戳，可用于视频播放器）
- ✅ **多语言支持**：自动检测或手动指定语言（如 `zh`、`en`、`ja`）
- ✅ **离线部署**：支持自定义模型目录，无需联网
- ✅ **中文友好**：全中文日志、提示与输出
- ✅ **错误隔离**：单个文件失败不影响整体流程

---

## 🚀 快速开始

### 1. 安装依赖

```bash
# 安装核心库
pip install openai-whisper tqdm

# 确保系统已安装 ffmpeg（音频处理必需）
# Ubuntu/Debian:
sudo apt install ffmpeg
# macOS (Homebrew):
brew install ffmpeg
# Windows: 从 https://ffmpeg.org/ 下载并加入 PATH

> 💡 **中文用户推荐使用 `large-v2` 或 `large-v3` 模型以获得最佳效果**
```
### 2. 下载模型（可选，首次运行会自动下载）

```bash
# 首次运行会自动下载到 ~/.cache/whisper/
# 如需离线使用，请提前下载模型（见下文“离线部署”）
```

### 3. 转录音频

```bash
# 转录单个文件（自动检测语言）
python speak_to_txt.py 录音.wav

# 中文音频 + 生成字幕
python speak_to_txt.py 会议.mp3 --language zh --srt

# 批量转录所有 MP3（使用 small 模型）
python speak_to_txt.py *.mp3 --model small

# 使用自定义模型目录（离线部署）
python speak_to_txt.py interview.m4a --model-root ./models --model large-v2
```

---

## 📂 输出文件

对输入文件 `example.mp3`，将生成：

- `example_转录文本.txt`：包含语言、耗时、完整文本
- `example.srt`（如果加了 `--srt`）：标准字幕文件，可直接用于 VLC、PotPlayer 等播放器

---

## 🛠️ 命令行参数

```bash
usage: speak_to_txt.py [-h] [--model MODEL] [--language LANGUAGE] [--srt]
                       [--model-root MODEL_ROOT] [--verbose]
                       audio_files [audio_files ...]

位置参数:
  audio_files           一个或多个音频文件路径（支持通配符，如 *.mp3）

可选参数:
  -h, --help            显示帮助信息
  --model MODEL         Whisper 模型大小（默认: turbo）
                        可选: tiny, base, small, medium, large, large-v2, turbo
  --language LANGUAGE   指定语言代码（如: zh=中文, en=英文）
                        不指定则自动检测
  --srt                 同时生成 .srt 字幕文件
  --model-root PATH     指定模型缓存目录（离线部署用）
  --verbose             显示详细调试日志
```

---

## 🌐 离线部署指南

1. **下载模型文件**：
```
  _MODELS = {
      "tiny.en": "https://openaipublic.azureedge.net/main/whisper/models/d3dd57d32accea0b295c96e26691aa14d8822fac7d9d27d5dc00b4ca2826dd03/tiny.en.pt",
      "tiny": "https://openaipublic.azureedge.net/main/whisper/models/65147644a518d12f04e32d6f3b26facc3f8dd46e5390956a9424a650c0ce22b9/tiny.pt",
      "base.en": "https://openaipublic.azureedge.net/main/whisper/models/25a8566e1d0c1e2231d1c762132cd20e0f96a85d16145c3a00adf5d1ac670ead/base.en.pt",
      "base": "https://openaipublic.azureedge.net/main/whisper/models/ed3a0b6b1c0edf879ad9b11b1af5a0e6ab5db9205f891f668f8b0e6c6326e34e/base.pt",
      "small.en": "https://openaipublic.azureedge.net/main/whisper/models/f953ad0fd29cacd07d5a9eda5624af0f6bcf2258be67c92b79389873d91e0872/small.en.pt",
      "small": "https://openaipublic.azureedge.net/main/whisper/models/9ecf779972d90ba49c06d968637d720dd632c55bbf19d441fb42bf17a411e794/small.pt",
      "medium.en": "https://openaipublic.azureedge.net/main/whisper/models/d7440d1dc186f76616474e0ff0b3b6b879abc9d1a4926b7adfa41db2d497ab4f/medium.en.pt",
      "medium": "https://openaipublic.azureedge.net/main/whisper/models/345ae4da62f9b3d59415adc60127b97c714f32e89e936602e85993674d08dcb1/medium.pt",
      "large-v1": "https://openaipublic.azureedge.net/main/whisper/models/e4b87e7e0bf463eb8e6956e646f1e277e901512310def2c24bf0e11bd3c28e9a/large-v1.pt",
      "large-v2": "https://openaipublic.azureedge.net/main/whisper/models/81f7c96c852ee8fc832187b0132e569d6c3065a3252ed18e56effd0b6a73e524/large-v2.pt",
      "large-v3": "https://openaipublic.azureedge.net/main/whisper/models/e5b1a55b89c1367dacf97e3e19bfd829a01529dbfdeefa8caeb59b3f1b81dadb/large-v3.pt",
      "large": "https://openaipublic.azureedge.net/main/whisper/models/e5b1a55b89c1367dacf97e3e19bfd829a01529dbfdeefa8caeb59b3f1b81dadb/large-v3.pt",
      "large-v3-turbo": "https://openaipublic.azureedge.net/main/whisper/models/aff26ae408abcba5fbf8813c21e62b0941638c5f6eebfb145be0c9839262a19a/large-v3-turbo.pt",
      "turbo": "https://openaipublic.azureedge.net/main/whisper/models/aff26ae408abcba5fbf8813c21e62b0941638c5f6eebfb145be0c9839262a19a/large-v3-turbo.pt",
  }
```
2. **地址失效？**：
   小秘密：这些地址我是在查看whisper.__init__.py时发现的，将来版本更新换地址的话，记得到这里去找找看^_^

3. **运行时指定目录**：
   ```bash
   python speak_to_txt.py audio.wav --model-root ./models --model large-v2
   ```

> ✅ 此方式完全离线，适合内网或生产环境

---

## 📦 项目结构

```
speak2txt/
├── speak_to_txt.py       # 主程序
├── README.md             # 本文件
└── models/               # （可选）本地模型目录
```

---

## ❓ 常见问题

**Q: 首次运行很慢？**  
A: 如果您未提前下载模型，那么首次会自动下载模型，建议提前下载。另外，如果选择`large`模型，需要先载入内存或显存，后续处理极快。

**Q: 中文识别不准？**  
A: 请使用 `--model large` 或 `turbo`，并指定 `--language zh`。
   `large`: 高精度,分为 `large-v2`和 `large-v3`，`large` == `large-v3`
   `turbo`: 基于`large-v3`的turbo版，体积与`medium`接近，只有`large`的一半（1.58G），`turbo` == `large-v3-trubo`，中文效果很好，推荐使用。

**Q: 提示 “ffmpeg not found”？**  
A: 请安装 `ffmpeg` 并确保其在系统 PATH 中。

**Q: 能在无 GPU 的机器上运行吗？**  
A: 可以！会自动回退到 CPU，只是速度较慢。

---

## 📜 许可证

本项目基于 MIT 许可证开源。Whisper 模型由 OpenAI 发布，遵循 [MIT 许可证](https://github.com/openai/whisper/blob/main/LICENSE)。

---

## 🙌 致谢

- [OpenAI Whisper](https://github.com/openai/whisper)
- [Hugging Face](https://huggingface.co/openai)

---
## 👤 作者的废话

本工具项目名 `speak2txt`有点low，但功能绝不“low” 😉由 **[@sieding]** 精（东）心（拼）打（西）造（凑）。 项目虽小，但用过的都说好！✨

> 💬 欢迎提 Issue、PR，或直接联系我交流改进！
---