Podcast Ad Cleaner

🎧 AI-powered command-line tool that removes advertisements from podcasts and generates chapters with transcripts.

Features

• 🔍 Interactive podcast search using iTunes API
• 🤖 AI-powered ad detection using Ollama (local, free, unlimited)
• 📝 Full transcription with OpenAI Whisper
• 📑 Auto-chapter generation from topic changes
• ✂️ Surgical ad removal with ffmpeg
• 📦 Multiple output formats:
  • Clean MP3 audio (ad-free with embedded chapters)
  • VTT transcript with timestamps
  • Podcasting 2.0 chapters (JSON)
  • Processing report
• 🎵 ID3 chapter embedding - Chapters written directly into MP3 metadata (visible in Apple Podcasts, Overcast, Pocket Casts, etc.)

Demo

$ podcast-cleaner "glenn beck"

Searching...
1. The Glenn Beck Program (by Mercury Radio Arts)

Select: 1

[1/7] Downloading episode... ✓
[2/7] Transcribing with Whisper... ✓ (~15 min)
[3/7] AI analyzing for ads... ✓ (~10 min)
      → Ad detected at 0m20s: IQOS nicotine
      → Ad detected at 1m06s: Relief Factor
[4/7] Generating chapters... ✓
[5/7] Removing ads... ✓
[6/7] Creating outputs... ✓

✓ Complete!
Original: 42m → Cleaned: 39m (3m of ads removed)

Output files:
  • The-Glenn-Beck-Program-[date].mp3
  • The-Glenn-Beck-Program-[date].vtt
  • The-Glenn-Beck-Program-[date].chapters.json
  • The-Glenn-Beck-Program-[date].report.txt

Installation

Quick Install (Linux)

git clone https://github.com/adamc199/podcast-ad-cleaner.git
cd podcast-ad-cleaner
chmod +x install.sh
./install.sh

The install script will:

1. Install system dependencies (ffmpeg, yt-dlp, jq, curl)
2. Install Ollama (AI model server)
3. Download llama3.2:3b model (~2GB)
4. Install Whisper in Python virtual environment
5. Set up the podcast-cleaner command

Supported Distributions

• ✅ Ubuntu / Debian / Pop!_OS / Mint
• ✅ Arch Linux / Manjaro / EndeavourOS
• ✅ Fedora / RHEL / CentOS / Rocky
• ✅ openSUSE / SUSE

Manual Installation

If the install script doesn't work for your system:

1. Install system dependencies:

# Ubuntu/Debian
sudo apt install python3 python3-pip python3-venv ffmpeg curl jq yt-dlp

# Arch Linux
sudo pacman -S python python-pip ffmpeg curl jq yt-dlp

# Fedora
sudo dnf install python3 python3-pip ffmpeg curl jq

2. Install Ollama:

curl -fsSL https://ollama.ai/install.sh | sh
ollama serve &
ollama pull llama3.2:3b

3. Install Whisper:

python3 -m venv ~/.podcast-cleaner-env
source ~/.podcast-cleaner-env/bin/activate
pip install openai-whisper
deactivate

4. Make script executable:

chmod +x podcast-cleaner.sh

Usage

Basic

./podcast-cleaner.sh "podcast name"

Examples

# Search and process
./podcast-cleaner.sh "joe rogan"
./podcast-cleaner.sh "lex fridman"
./podcast-cleaner.sh "tim ferriss"

# Interactive mode
./podcast-cleaner.sh
# Then enter podcast name when prompted

What Happens

1. Search: Queries iTunes for podcasts matching your search
2. Select: Choose from up to 10 results
3. Download: Gets the latest episode from RSS feed
4. Transcribe: Full episode transcription with Whisper (~15 min for 60-min podcast)
5. Analyze: Ollama AI scans transcript for ads and topics (~10 min)
6. Remove: Cuts out detected ads with ffmpeg
7. Generate: Creates clean audio + chapters + transcript
8. Report: Shows statistics and file locations

Output Files

All files saved to: ~/cleaned-podcasts/

For each processed podcast, you get:

1. Clean MP3 Audio

Podcast-Name-Episode-Title.mp3

• Ad-free version
• Original audio quality preserved
• Properly merged segments

2. VTT Transcript

Podcast-Name-Episode-Title.vtt

• WebVTT format with timestamps
• Full transcription of cleaned audio
• Compatible with video players

3. Podcasting 2.0 Chapters

Podcast-Name-Episode-Title.chapters.json

• JSON format chapter markers
• Auto-generated from topic changes
• Can be imported into podcast apps
• Compatible with Podcasting 2.0 spec

4. Processing Report

Podcast-Name-Episode-Title.report.txt

• Summary of processing
• All ads detected (with timestamps)
• All chapters generated
• Duration statistics

How Ad Detection Works

Method 1: Chapter Markers

Scans RSS feed for <psc:chapter> tags with [Ad] in the title:

<psc:chapter start="10:18" title="[Ad] Sponsor Name"/>

Method 2: AI Transcript Analysis

Ollama analyzes the full transcript looking for:

• Sponsor reads ("brought to you by", "sponsored by")
• Product promotions and calls to action
• Promo codes and discount offers
• Financial service ads (credit cards, loans, etc.)
• Phrases like "let's take a break", "after this message"

Method 3: Context Understanding

The AI distinguishes between:

• ✅ Commercial ads: Sponsor reads, product promotions
• ❌ Editorial content: Product mentions in news/discussion
• ❌ Show announcements: Subscribe requests, content previews

Chapter Generation

If the podcast doesn't include chapters in its RSS feed, the AI automatically generates them by:

• Detecting major topic changes in the transcript
• Identifying natural segment boundaries
• Creating descriptive titles based on content
• Following Podcasting 2.0 chapter specification

Performance

Processing Time

For a 60-minute podcast:

• Download: ~5 seconds
• Transcription (Whisper): ~15-20 minutes
• AI Analysis (Ollama): ~10-15 minutes
• Audio processing: ~1 minute
• Total: 30-45 minutes

This is a one-time process. The output is permanent and can be listened to immediately.

System Requirements

• CPU: Multi-core recommended (Whisper and Ollama use CPU)
• RAM: 4GB minimum, 8GB recommended
• Disk: ~3GB for models + space for processed podcasts
• OS: Linux (Ubuntu, Arch, Fedora, etc.)

Speed Optimization

Current (balanced):

• Whisper: base model
• Ollama: llama3.2:3b (2GB)

Faster (less accurate): Edit script to use:

• Whisper: tiny model (~50% faster)
• Skip chapter generation

More Accurate (slower):

ollama pull qwen2.5:7b
# Edit script to use qwen2.5:7b instead of llama3.2:3b

Tested Podcasts

Podcast	Ads Detected	Result
Podnews Weekly Review	2 ads (1 marked, 1 AI-detected)	✅ 90s removed
Matt Walsh Show	1 credit card ad (AI-detected)	✅ 90s removed
Glenn Beck Program	Multiple ads (in progress)	⏳ Testing

Configuration

Output Directory

Default: ~/cleaned-podcasts/

To change, edit podcast-cleaner.sh:

OUTPUT_DIR="$HOME/my-podcasts"

Ad Duration

Default estimation:

• Pre-roll (first 2 min): 90 seconds
• Mid-roll: 60 seconds

To adjust, edit the script:

AD_DUR=90  # Change to desired duration

Whisper Model

Default: base (balanced)

Options:

• tiny - Fastest, less accurate
• base - Recommended (default)
• small - More accurate, slower
• medium - Very accurate, very slow

Edit script:

$WHISPER original.mp3 --model base  # Change 'base' to desired model

Ollama Model

Default: llama3.2:3b (2GB)

Alternatives:

# Download better model
ollama pull qwen2.5:7b  # 4.7GB, better quality

# Edit script to use it
ollama run qwen2.5:7b  # Replace llama3.2:3b

Troubleshooting

"Whisper not found"

# Check installation
ls ~/.podcast-cleaner-env/bin/whisper

# Reinstall
python3 -m venv ~/.podcast-cleaner-env
source ~/.podcast-cleaner-env/bin/activate
pip install openai-whisper

"Ollama not responding"

# Start Ollama
ollama serve &

# Check it's running
ollama list

# Test it
ollama run llama3.2:3b "Hello"

"No podcasts found"

• Check your search term spelling
• Try more general terms (e.g., "rogan" instead of "joe rogan experience")
• Some podcasts may not be in iTunes directory

Processing is very slow

This is normal! AI analysis takes time:

• 60-min podcast = 30-45 minutes processing
• Run overnight or during other work
• Consider using screen or tmux for long-running jobs

Wrong ads removed

Check the .report.txt file to see what AI detected. The AI is conservative and may miss some ads. You can:

1. Manually edit the chapter JSON to mark additional ads
2. Use a larger Ollama model for better detection
3. Adjust the ad duration estimates in the script

Technical Details

Ad Detection Algorithm

1. Transcribe full episode with Whisper
2. Split transcript into ~5-minute chunks
3. Analyze each chunk with Ollama:
   • Identify commercial language
   • Find sponsor mentions
   • Detect calls to action
4. Cross-reference with RSS chapter markers
5. Deduplicate and sort detected ads
6. Estimate durations based on position
7. Extract clean segments with ffmpeg
8. Concatenate into final output

Output Formats

VTT Transcript:

WEBVTT

00:00:00.000 --> 00:00:03.600
The last word in podcasting news.

00:00:03.840 --> 00:00:09.200
This is the Pod News Weekly Review...

Podcasting 2.0 Chapters:

{
  "version": "1.2.0",
  "chapters": [
    {"startTime": 0, "title": "Introduction"},
    {"startTime": 300, "title": "Main Topic"}
  ]
}

Privacy & Cost

• ✅ 100% Free: No API costs, completely local processing
• ✅ Private: All transcripts stay on your machine
• ✅ Unlimited: No rate limits or quotas
• ✅ Open Source: MIT License

Limitations

• Only processes the latest episode from a feed
• Transcription takes real time (unavoidable with Whisper)
• AI accuracy depends on clear sponsor language
• Requires decent CPU for reasonable performance
• Linux only (macOS support possible, Windows via WSL)

Roadmap

• Batch processing (multiple episodes)
• macOS support
• GUI option (web interface)
• Voice change detection (host vs announcer)
• Audio fingerprinting for known ads
• User-contributed ad database
• Episode selection (not just latest)
• Cloud AI option (for faster processing)

Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test with multiple podcasts
5. Submit a pull request

License

MIT License - See LICENSE file

Author

Created by adamc199

Acknowledgments

• OpenAI Whisper for speech-to-text
• Ollama for local AI inference
• Meta's Llama 3.2 model
• iTunes Search API
• FFmpeg project
• yt-dlp for audio downloading

Support

For issues, questions, or feature requests:

• Open an issue on GitHub
• Include your Linux distribution
• Attach the processing report file if relevant

FAQ

Q: How accurate is the ad detection?
A: Very good for clearly marked ads and obvious sponsor reads. May miss subtle product placements or conversational ads.

Q: Can I process old episodes?
A: Currently only processes the latest episode. Batch processing coming soon.

Q: Does this work with all podcasts?
A: Works with any podcast that has an RSS feed accessible via iTunes. Some private/premium podcasts may not be searchable.

Q: Is it legal to remove ads?
A: You're downloading and modifying audio for personal use. Check your local laws. This tool is for personal use only.

Q: Can I speed it up?
A: Use --model tiny for Whisper (50% faster, less accurate) or get a faster CPU. Transcription is the bottleneck.

Q: Why not use cloud AI?
A: Local processing is free, unlimited, and private. Cloud APIs have costs and rate limits. However, you can modify the script to use cloud APIs if desired.

Q: Can this run on Raspberry Pi?
A: Technically yes, but it would be very slow (hours per episode). Recommended: x86_64 CPU with 4+ cores.

Examples

Podnews Weekly Review

Original: 84 minutes
Cleaned: 82 minutes
Removed: 2 minutes (Buzzsprout sponsor + marked ad)
Chapters: 15 generated from topics

Matt Walsh Show

Original: 62 minutes
Cleaned: 61 minutes
Removed: 1 minute (credit card ad)
Chapters: 8 generated

Glenn Beck Program

Original: 42 minutes
Processing: In progress...
Expected: Multiple sponsor reads (IQOS, Relief Factor, etc.)

---

⭐ Star this repo if you find it useful!

🐛 Found a bug? Open an issue!

🚀 Want a feature? Submit a PR!