内容
# 播客转录工具
无需任何麻烦即可转录任意播客集。只需一条命令，三个层级，无需设置烦恼。
```bash
# Apple Podcasts URL
podcast-transcribe "https://podcasts.apple.com/us/podcast/acquired/id1050467328"
# 节目名称 + 集数
podcast-transcribe "Marketing Against the Grain 416"
# 搜索并转录
podcast-transcribe "Lex Fridman latest"
# 本地音频文件
podcast-transcribe recording.mp3
```
## 三个层级
| 层级 | 质量 | 成本 | 设置 |
|------|---------|------|-------|
| **Gemini** (层级 1) | 说话者识别，时间戳，语气 | API 使用 | 设置 `GOOGLE_API_KEY` |
| **OpenAI Whisper API** (层级 1) | 清洁的转录稿，时间戳 | API 使用 | 设置 `OPENAI_API_KEY` |
| **本地 Whisper** (层级 2/3) | 清洁的转录稿，时间戳 | 免费 | 安装 whisper 或 whisper.cpp |
自动检测：找到 Gemini 密钥 → Gemini。找到 OpenAI 密钥 → Whisper API。找到本地二进制文件 → 本地。无需提示。
## 安装
```bash
git clone https://github.com/a692570/podcast-transcriber.git
cd podcast-transcriber
pip install -r requirements.txt
```
### 层级 1：API 密钥（最佳质量）
```bash
# Gemini（推荐：说话者识别 + 语气）
export GOOGLE_API_KEY="your-key-here"
# OpenAI Whisper API（备用）
export OPENAI_API_KEY="your-key-here"
```
获取密钥：
- Google AI：https://aistudio.google.com/apikey
- OpenAI：https://platform.openai.com/api-keys
### 层级 2：免费 Mac（无需 API 密钥）
选项 A：openai-whisper（Python）
```bash
pip install openai-whisper
```
选项 B：whisper.cpp（C++，更快）
```bash
brew install whisper-cpp
# 或从源代码构建：https://github.com/ggerganov/whisper.cpp
```
### 层级 3：免费 Windows（无需 API 密钥）
选项 A：openai-whisper（Python）
```powershell
pip install openai-whisper
```
选项 B：whisper.cpp
```powershell
# 从 https://github.com/ggerganov/whisper.cpp/releases 下载预编译的二进制文件
# 解压并添加到 PATH
```
## 使用
### 命令行界面
```bash
# 从 Apple Podcasts 转录
python scripts/podcast-transcribe.py "https://podcasts.apple.com/us/podcast/acquired/id1050467328"
# 按节目名称和集数转录
python scripts/podcast-transcribe.py "Acquired 400"
# 从 RSS 源转录
python scripts/podcast-transcribe.py "https://feeds.acquired.fm/acquired"
# 从 Spotify 转录
python scripts/podcast-transcribe.py "https://open.spotify.com/show/2Opy6fN6UYCgBkxRCbcXkI"
# 转录本地音频文件
python scripts/podcast-transcribe.py episode.mp3
# 强制使用特定层级
python scripts/podcast-transcribe.py episode.mp3 --tier gemini
# 输出为 JSON（包含说话者标签和 Gemini）
python scripts/podcast-transcribe.py episode.mp3 --format json
# 输出为 SRT 字幕
python scripts/podcast-transcribe.py episode.mp3 --format srt
# 搜索播客
python scripts/podcast-transcribe.py "tech podcasts" --search
# 保存到文件
python scripts/podcast-transcribe.py episode.mp3 -o transcript.txt
```
### MCP 服务器（Claude Desktop、Claude Code 等）
添加到您的 Claude Desktop 配置：
```json
{
"mcpServers": {
"podcast-transcriber": {
"command": "python",
"args": ["-m", "mcp_server.server"],
"cwd": "/path/to/podcast-transcriber"
}
}
}
```
或使用 uvx：
```json
{
"mcpServers": {
"podcast-transcriber": {
"command": "uvx",
"args": ["--directory", "/path/to/podcast-transcriber", "mcp", "run", "mcp_server/server.py"]
}
}
}
```
#### MCP 工具
| 工具 | 描述 |
|------|-------------|
| `transcribe_podcast(url, tier?, output_format?)` | 从 URL、搜索查询或 RSS 源转录 |
| `transcribe_audio(file_path, tier?, output_format?)` | 转录本地音频文件 |
| `search_podcast_tool(query, limit?)` | 按名称搜索播客 |
| `detect_tier_tool()` | 检查可用的转录层级 |
## 输出格式
### 文本（默认）
```
[00:00] 说话者 1：欢迎来到节目
[01:23] 说话者 2：谢谢你邀请我（兴奋）
[02:45] 说话者 1：让我们开始吧
```
### SRT
```
1
00:00:00,000 --> 00:00:03,000
说话者 1：欢迎来到节目
```
### VTT
```
WEBVTT
00:00:00.000 --> 00:00:03.000
<v 说话者 1>欢迎来到节目
```
### JSON
```json
{
"tier": "gemini",
"segments": [
{
"speaker": "说话者 1",
"start": "00:00",
"text": "欢迎来到节目",
"tone": "中立"
}
]
}
```
## 工作原理
1. **解析**: Apple Podcasts URL → iTunes 查找 API → RSS 源 URL。Spotify URL → 节目页面 → Apple 搜索 → RSS。直接 RSS/音频 URL 直接通过。
2. **查找集**: 解析 RSS 源，按标题/集数匹配，或获取最新集。
3. **下载**: 使用进度条流式传输音频。缓存在 `.downloads/` 中。
4. **转录**: 自动检测最佳可用层级。Gemini 用于说话者标签 + 语气。Whisper 用于清洁文本。
5. **格式化**: 以您首选的格式输出。
## 配置
将 `config.example.json` 复制到 `config.json` 并自定义：
```json
{
"tier": "auto",
"whisper_model": "base",
"output_format": "text",
"timeout_seconds": 300
}
```
所有 API 密钥均来自环境变量。切勿硬编码。
## 开发
```bash
# 安装开发依赖
pip install pytest
# 运行测试
pytest tests/
# 运行详细输出
pytest tests/ -v
```
## 许可证
MIT
