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
π¦ 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.
οΏ½π Quick Start
On first run, PodFetch will prompt you to choose a default download directory template.
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-o, --output <PATH>: override the download path template-j, --jobs <N>: set the maximum number of concurrent downloads (default: 5)
βοΈ How it works
- PodFetch loads or creates a configuration file on first launch.
- It accepts either:
- a direct RSS feed URL, or
- a podcast name, which is searched and resolved to an RSS feed
- It determines an output directory based on the configured template and the podcast metadata.
- It downloads only episodes that have not already been recorded in the archive file.
- Each downloaded file is tagged with metadata and cover art where possible.
βοΈ 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.