ad-begone

Nobody likes ads. Instead of skipping them, let’s remove them altogether.

This Python package provides a CLI tool, ad-begone, that watches a directory for MP3 files, detects ads in them, and removes them. It is intended for use with Audiobookshelf, which provides exactly this sort of directory.

How it works

1. Transcribe – Uses OpenAI’s Whisper API to transcribe podcast audio into timestamped segments
2. Annotate – Sends segments to the GPT-4o Chat Completions API to classify each segment as content or ad
3. Trim – Removes ad segments and inserts a short notification sound where ads were removed

Prerequisites

• Python 3.12+
• ffmpeg (required by pydub for audio processing)
• An OpenAI API key set as OPENAI_API_KEY in your environment

Installation

pip install .

Usage

usage: ad-begone [-h] [--directory DIRECTORY] [--sleep SLEEP] [--model MODEL]

Remove ads from a podcast episode.

options:
  -h, --help            show this help message and exit
  --directory DIRECTORY
                        Path to the podcast directory. (default: .)
  --sleep SLEEP         Sleep time in seconds between processing runs. (default: 600)
  --model MODEL         OpenAI model to use for ad classification. (default: None)

Examples

Watch a directory

# Watch a directory (checks every 10 minutes by default)
ad-begone --directory /path/to/podcasts

# Custom interval (in seconds)
ad-begone --directory /path/to/podcasts --sleep 300

Process a single file

python -m ad_begone.remove_ads episode.mp3

Docker

# Set your API key in .env or export it
export OPENAI_API_KEY=sk-...

# Place podcast files in ./podcasts/
docker compose up

The compose configuration mounts ./podcasts to /data inside the container and runs with restart: unless-stopped.

License

GPL-3.0