podfetch 0.2.0

A lightweight CLI/TUI client for searching and downloading podcasts including metadata for self-hosting via audiobookshelf, jellyfin, etc.
podfetch-0.2.0 is not a library.

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:

cargo install --path .

Or build a release binary manually:

cargo build --release
./target/release/podfetch --help

πŸš€ 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
cargo build --release

# Build an AppImage
./scripts/build-appimage.sh build

# Build Windows and Linux release assets, then publish a GitHub release
./scripts/release-github.sh

Requirements for Windows and AppImage builds

  • Windows cross-compilation requires x86_64-w64-mingw32-gcc and 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:

  1. Podcast Input - Enter a podcast name or RSS feed URL
  2. Search Confirmation - Choose to search the database or treat input as a URL
  3. Select Result - Browse and select from search results (if searching)
  4. Output Path - Confirm the download directory
  5. Review & Start - Review settings and start the download

Keyboard shortcuts in the wizard:

  • Enter - Move to next step / confirm selection
  • ↑↓ - Navigate through search results
  • Y / N / B - Quick keys for Yes (search) / No (URL) / Back
  • Ctrl-Q - Cancel and exit

Download Progress UI

Once downloads begin, you'll see a real-time progress interface with three sections:

  1. Current Downloads - Shows active downloads with individual progress bars
  2. Overall Progress Bar - Visual representation of total download progress
  3. 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
podfetch "Darknet Diaries"

# Download from a known RSS feed directly
podfetch https://example.com/podcast.xml

# Force the input to be treated as a search term
podfetch --search "The Joe Rogan Experience"

# Override the download folder and use a custom template
podfetch -o "~/Music/podcasts/{podcast_name}" "My Podcast"

# Download up to 10 episodes at the same time
podfetch -j 10 "My Podcast"

Command-line options

podfetch [OPTIONS] [URL_OR_NAME]

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

  1. Configuration - PodFetch loads or creates a configuration file on first launch.
  2. 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
  3. Input Resolution - Accepts either:
    • a direct RSS feed URL, or
    • a podcast name, which is searched and resolved to an RSS feed
  4. Output Directory - Determines the output directory based on the configured template and the podcast metadata.
  5. Parallel Downloads - Downloads only episodes that have not already been recorded in the archive file, with configurable concurrent download limit.
  6. Metadata Tagging - Each downloaded file is tagged with metadata and cover art where possible.
  7. 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:

[config]
download_dir = "~/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

cargo fmt
cargo build
cargo test

⚠️ 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.