PodFetch
PodFetch is a lightweight command-line podcast downloader written in Rust. It helps you discover podcasts, resolve their RSS feeds, download new episodes, and organize them for local playback or self-hosted media servers such as Jellyfin or Audiobookshelf.
β¨ Features
- π Search for podcasts by name using PodcastAddict
- π Fall back to the Apple iTunes podcast search API when needed
- π‘ Accept either a podcast name or a direct RSS feed URL
- β¬οΈ Download new episodes only, tracking already-downloaded episodes in an archive file
- π·οΈ Tag downloaded audio files with title, artist, album, and embedded cover art
- π§Ύ Write metadata and cover images for media-library integration
- π Support configurable destination paths with placeholders for podcast name and author
- π¨ Interactive TUI (Terminal User Interface) with ratatui for a polished experience
- π Interactive wizard for podcast selection, search confirmation, and download configuration
- π Real-time download progress UI with scrollable active downloads and history
- β¨οΈ Keyboard shortcuts for navigation and control (Tab, ββ arrows, Ctrl-Q)
π¦ Installation
From the project directory:
Or build a release binary manually:
π Release targets
PodFetch now includes local release automation for several distribution formats:
- π§ Linux tarball: built as a portable archive for direct use on Linux systems
- π¦ AppImage: created with the AppImage build script for desktop-friendly Linux installs
- πͺ Windows zip: cross-compiled for Windows using
x86_64-pc-windows-gnu - π§ Arch Linux AUR: packaging metadata is available in aur/PKGBUILD
Build the release artifacts locally
# Build the Linux binary
# Build an AppImage
# Build Windows and Linux release assets, then publish a GitHub release
Requirements for Windows and AppImage builds
- Windows cross-compilation requires
x86_64-w64-mingw32-gccand the Rust Windows target - AppImage packaging uses
linuxdeploy, which is downloaded automatically by the script - If an icon is present as icon.png, the release scripts will generate icon.ico for the Windows executable
GitHub Pages site
A static landing page for GitHub Pages is available in docs/index.html. Publish the repositoryβs docs/ folder as the Pages source to make it live.
π₯οΈ User Interface
PodFetch features an interactive Terminal User Interface (TUI) built with ratatui.
Podcast Setup Wizard
On first run (or when not providing full CLI arguments), you'll be guided through an interactive wizard with 5 steps:
- Podcast Input - Enter a podcast name or RSS feed URL
- Search Confirmation - Choose to search the database or treat input as a URL
- Select Result - Browse and select from search results (if searching)
- Output Path - Confirm the download directory
- Review & Start - Review settings and start the download
Keyboard shortcuts in the wizard:
Enter- Move to next step / confirm selectionββ- Navigate through search resultsY/N/B- Quick keys for Yes (search) / No (URL) / BackCtrl-Q- Cancel and exit
Download Progress UI
Once downloads begin, you'll see a real-time progress interface with three sections:
- Current Downloads - Shows active downloads with individual progress bars
- Overall Progress Bar - Visual representation of total download progress
- History - Scrollable list of completed (β ) and failed (β) downloads
Keyboard shortcuts during downloads:
Tab- Switch focus between active downloads and history areasββ- Scroll the focused area (all downloads/history shown with scroll indicators)Ctrl-Q- Cancel all downloads and exit
β‘ Quick Start
On first run, PodFetch will prompt you through an interactive wizard to choose your download settings.
Example usage
# Search for a podcast by name and download its episodes
# Download from a known RSS feed directly
# Force the input to be treated as a search term
# Override the download folder and use a custom template
# Download up to 10 episodes at the same time
Command-line options
Options:
-s, --search: force the input to be treated as a search term (skip wizard's search confirmation step)-o, --output <PATH>: override the download path template (skips output path wizard step)-j, --jobs <N>: set the maximum number of concurrent downloads (default: 5)
Note: When all required arguments are provided (URL_OR_NAME, -s/URL decision, and optionally -o and -j), the wizard is skipped entirely and downloads begin immediately.
βοΈ How it works
- Configuration - PodFetch loads or creates a configuration file on first launch.
- Interactive Setup (if needed) - If not all required args are provided, launches an interactive wizard:
- Asks for podcast name or RSS URL
- Confirms search vs. URL treatment
- Shows search results for selection (if searching)
- Confirms output directory
- Shows final settings review
- Input Resolution - Accepts either:
- a direct RSS feed URL, or
- a podcast name, which is searched and resolved to an RSS feed
- Output Directory - Determines the output directory based on the configured template and the podcast metadata.
- Parallel Downloads - Downloads only episodes that have not already been recorded in the archive file, with configurable concurrent download limit.
- Metadata Tagging - Each downloaded file is tagged with metadata and cover art where possible.
- Progress Tracking - Real-time TUI displays active downloads, overall progress, and completed/failed history.
βοΈ Configuration
PodFetch stores its configuration in:
- Linux:
~/.local/share/podfetch/config.toml
Example configuration:
[]
= "~/Downloads/podfetch/{podcast_name}"
Supported path placeholders
{podcast_name}: sanitized podcast title{podcast_author}: sanitized author name
The tool also expands ~ to your home directory.
π Output layout
A typical download folder looks like this:
~/Downloads/podfetch/My Podcast/
βββ 01 - Episode Title.mp3
βββ 02 - Another Episode.m4a
βββ cover.jpg
βββ folder.jpg
βββ metadata.nfo
βββ downloaded_episodes.txt
π οΈ Development
β οΈ Notes and limitations
- Podcast discovery depends on external services such as PodcastAddict and Apple iTunes search.
- Some podcasts may not expose easily resolvable RSS URLs or may require manual handling.
- Downloads are based on the RSS feed content and the episode metadata from that feed.
- The project is licensed under GPL-2.0.
π License
This project is licensed under the GPL-2.0 License. See the LICENSE file for details.