Content
# podcast-transcriber
Transcribe any podcast episode with zero friction. One command, three tiers, no setup headaches.
```bash
# Apple Podcasts URL
podcast-transcribe "https://podcasts.apple.com/us/podcast/acquired/id1050467328"
# Show name + episode
podcast-transcribe "Marketing Against the Grain 416"
# Search and transcribe
podcast-transcribe "Lex Fridman latest"
# Local audio file
podcast-transcribe recording.mp3
```
## Three Tiers
| Tier | Quality | Cost | Setup |
|------|---------|------|-------|
| **Gemini** (Tier 1) | Speaker diarization, timestamps, tone | API usage | Set `GOOGLE_API_KEY` |
| **OpenAI Whisper API** (Tier 1) | Clean transcript, timestamps | API usage | Set `OPENAI_API_KEY` |
| **Local Whisper** (Tier 2/3) | Clean transcript, timestamps | Free | Install whisper or whisper.cpp |
Auto-detection: Gemini key found → Gemini. OpenAI key found → Whisper API. Local binary found → local. No hints needed.
## Install
```bash
git clone https://github.com/a692570/podcast-transcriber.git
cd podcast-transcriber
pip install -r requirements.txt
```
### Tier 1: API Keys (Best Quality)
```bash
# Gemini (recommended: speaker diarization + tone)
export GOOGLE_API_KEY="your-key-here"
# OpenAI Whisper API (fallback)
export OPENAI_API_KEY="your-key-here"
```
Get keys:
- Google AI: https://aistudio.google.com/apikey
- OpenAI: https://platform.openai.com/api-keys
### Tier 2: Free Mac (No API Key)
Option A: openai-whisper (Python)
```bash
pip install openai-whisper
```
Option B: whisper.cpp (C++, faster)
```bash
brew install whisper-cpp
# or build from source: https://github.com/ggerganov/whisper.cpp
```
### Tier 3: Free Windows (No API Key)
Option A: openai-whisper (Python)
```powershell
pip install openai-whisper
```
Option B: whisper.cpp
```powershell
# Download precompiled binary from https://github.com/ggerganov/whisper.cpp/releases
# Extract and add to PATH
```
## Usage
### CLI
```bash
# Transcribe from Apple Podcasts
python scripts/podcast-transcribe.py "https://podcasts.apple.com/us/podcast/acquired/id1050467328"
# Transcribe by show name + episode number
python scripts/podcast-transcribe.py "Acquired 400"
# Transcribe from RSS feed
python scripts/podcast-transcribe.py "https://feeds.acquired.fm/acquired"
# Transcribe from Spotify
python scripts/podcast-transcribe.py "https://open.spotify.com/show/2Opy6fN6UYCgBkxRCbcXkI"
# Transcribe local audio file
python scripts/podcast-transcribe.py episode.mp3
# Force a specific tier
python scripts/podcast-transcribe.py episode.mp3 --tier gemini
# Output as JSON (includes speaker labels with Gemini)
python scripts/podcast-transcribe.py episode.mp3 --format json
# Output as SRT subtitles
python scripts/podcast-transcribe.py episode.mp3 --format srt
# Search for podcasts
python scripts/podcast-transcribe.py "tech podcasts" --search
# Save to file
python scripts/podcast-transcribe.py episode.mp3 -o transcript.txt
```
### MCP Server (Claude Desktop, Claude Code, etc.)
Add to your Claude Desktop config:
```json
{
"mcpServers": {
"podcast-transcriber": {
"command": "python",
"args": ["-m", "mcp_server.server"],
"cwd": "/path/to/podcast-transcriber"
}
}
}
```
Or with uvx:
```json
{
"mcpServers": {
"podcast-transcriber": {
"command": "uvx",
"args": ["--directory", "/path/to/podcast-transcriber", "mcp", "run", "mcp_server/server.py"]
}
}
}
```
#### MCP Tools
| Tool | Description |
|------|-------------|
| `transcribe_podcast(url, tier?, output_format?)` | Transcribe from URL, search query, or RSS feed |
| `transcribe_audio(file_path, tier?, output_format?)` | Transcribe a local audio file |
| `search_podcast_tool(query, limit?)` | Search for podcasts by name |
| `detect_tier_tool()` | Check which transcription tier is available |
## Output Formats
### Text (default)
```
[00:00] Speaker 1: Welcome to the show
[01:23] Speaker 2: Thanks for having me (excited)
[02:45] Speaker 1: Let's dive in
```
### SRT
```
1
00:00:00,000 --> 00:00:03,000
Speaker 1: Welcome to the show
```
### VTT
```
WEBVTT
00:00:00.000 --> 00:00:03.000
<v Speaker 1>Welcome to the show
```
### JSON
```json
{
"tier": "gemini",
"segments": [
{
"speaker": "Speaker 1",
"start": "00:00",
"text": "Welcome to the show",
"tone": "neutral"
}
]
}
```
## How It Works
1. **Resolve**: Apple Podcasts URL → iTunes lookup API → RSS feed URL. Spotify URL → show page → Apple search → RSS. Direct RSS/audio URLs pass through.
2. **Find episode**: Parse RSS feed, match by title/number, or grab latest.
3. **Download**: Stream audio with progress bar. Caches in `.downloads/`.
4. **Transcribe**: Auto-detect best available tier. Gemini for speaker labels + tone. Whisper for clean text.
5. **Format**: Output in your preferred format.
## Configuration
Copy `config.example.json` to `config.json` and customize:
```json
{
"tier": "auto",
"whisper_model": "base",
"output_format": "text",
"timeout_seconds": 300
}
```
All API keys come from environment variables. Never hardcode them.
## Development
```bash
# Install dev dependencies
pip install pytest
# Run tests
pytest tests/
# Run with verbose output
pytest tests/ -v
```
## License
MIT
