rss-podcast-downloader

Overview

A powerful and flexible Python tool for downloading, managing, and archiving podcast episodes from any RSS feed. Designed as a "set it and forget it" solution with intelligent resume capabilities and multi-feed support.

The tool creates clean, portable filenames and enriches your media library by automatically writing episode metadata (title, album, artist, date, genre) to downloaded MP3 files. A local SQLite database tracks all downloaded episodes, preventing duplicates and enabling seamless management of podcasts from multiple feeds.

Features

Download Resuming: Automatically tracks downloaded episodes in a local SQLite database and skips them on subsequent runs
Multi-Feed Support: Tracks episodes from multiple RSS feeds independently using feed-specific IDs
MP3 Metadata Tagging: Automatically writes ID3 tags including:
- Title (episode title)
- Album (podcast title)
- Artist (podcast author)
- Date (publication date)
- Genre (customizable or from RSS feed)
- Comments (episode summary)
Smart Filename Sanitization: Converts episode titles to clean, ASCII-only, filesystem-friendly filenames with date prefix
Download Limiting: Use --num-episodes to check only the latest N episodes for quick syncing
Optional Text Export: Save episode summaries in separate .txt files alongside audio
Robust Error Handling: Retry logic with exponential backoff for failed downloads
Command-Line Interface: Simple CLI for specifying RSS feed URL and save directory

Filename Convention

Files are saved with a consistent, sortable naming pattern:

YYYY-MM-DD_lowercase_and_ascii_title.mp3

The prepended date is the publication date of the podcast episode, making it easy to browse chronologically.

Usage

Installation

git clone https://github.com/johnsosoka/rss-podcast-downloader.git
cd rss-podcast-downloader
pip install -r requirements.txt

Basic Usage

python rss-podcast-downloader.py <RSS_FEED_URL> <SAVE_DIRECTORY> [OPTIONS]

Arguments

Argument	Description	Required
`RSS_FEED_URL`	The URL of the podcast's RSS feed	Yes
`SAVE_DIRECTORY`	Local directory where podcast files will be saved	Yes

Options

Option	Description
`--num-episodes N`	Check only the N most recent episodes for new downloads
`--save_text`	Save episode summaries in separate `.txt` files
`--mp3-genre GENRE`	Specify custom genre tag (defaults to RSS feed tag or "Podcast")

Examples

Initial download of all episodes:

python rss-podcast-downloader.py "http://example.com/podcast.rss" "./podcasts/MyShow"

Daily sync of latest 5 episodes:

python rss-podcast-downloader.py "http://example.com/podcast.rss" "./podcasts/MyShow" --num-episodes 5

Sync with text file export:

python rss-podcast-downloader.py "http://another-feed.com/rss" "./podcasts/AnotherShow" --save_text

Custom genre tag:

python rss-podcast-downloader.py "http://example.com/podcast.rss" "./podcasts/MyShow" --mp3-genre "Technology"

Database

The tool maintains a downloads.db SQLite database in the script directory with two tables:

feeds: Stores feed URLs and titles
episodes: Tracks downloaded episodes with GUID, title, publication date, and file path

This enables resumable downloads across multiple feeds without re-downloading existing content.