╔══════════════════════════════╗
║       A E T H E R P O D      ║
║   Terminal Podcast Manager   ║
╚══════════════════════════════╝

AetherPod

Terminal Podcast Manager
Subscribe, browse, and play podcasts — all from your terminal.
BTW.. I use Arch

Screenshots

Features

• Subscribe to any RSS/Atom podcast feed
• Browse episodes in a sortable DataTable with live progress bars
• Zebra-striped lists — alternating row colors on feeds and episode tables for easy scanning
• Sort & filter feeds — alphabetical order toggle (s) and inline name filter (f)
• Play / pause / seek / speed control via mpv IPC
• Resume playback where you left off
• Cross-feed search
• Play queue — auto-plays next episode on natural end
• OPML import / export — migrate from other podcast apps
• Dark / light theme toggle
• Async feed refresh — instant cache on startup, background updates
• Splash screen — branded startup with subscription stats
• Audio EQ presets — 3 voice-optimized EQ profiles (Bright / Warm / Balanced) with lookahead limiter — toggle instantly with 1–4. mpv only: EQ requires mpv's lavfi audio filter bridge, so it works on Linux/macOS (mpv) but is unavailable on Windows (which uses VLC).
• Automatic update check — on startup, notifies you when a newer version is available (aetherpod -u to upgrade)

Download a Pre-Built Executable (Recommended)

No Python or pip needed. Grab the binary for your platform from the Releases page (or the latest Actions build artifacts):

The binaries are unsigned, so Windows SmartScreen and macOS Gatekeeper may warn on first run. Windows: click More info → Run anyway. macOS: xattr -d com.apple.quarantine aetherpod-macos.

Quick Start

Prerequisites

• Python 3.14+
• mpv (Linux/macOS) or VLC (Windows, or any platform) — audio player

Windows: VLC is detected automatically even when not on PATH (installed under Program Files or the registry). AetherPod uses VLC on Windows since mpv's control channel is Linux/macOS-only.

macOS: VLC.app and Homebrew are detected even when not on PATH (/Applications/VLC.app/Contents/MacOS/vlc, /opt/homebrew, /usr/local). mpv is preferred when present.

EQ on Windows: the audio EQ presets (1–4) require mpv and are therefore not available on Windows (VLC is used there). mpv-on-Windows support is on the roadmap.

# Install mpv (Arch)
sudo pacman -S mpv

# Install mpv (Debian/Ubuntu)
sudo apt install mpv

# Install mpv (macOS)
brew install mpv

Install

Choose one:

# Option A — Interactive installer (recommended)
git clone https://github.com/AetherSolDev/AetherPod.git
cd AetherPod
bash scripts/install.sh

# Option B — Makefile (system-wide)
make install

# Option C — Makefile (user-local, no root)
make install-user

# Option D — Manual venv
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
pip install -e .

scripts/install.sh walks you through system-wide, user-local, or venv installation.

Run

aetherpod           # Launch TUI
aetherpod --help    # CLI usage
aetherpod list     # List subscribed feeds

Notes

• Resume playback — AetherPod saves your position and resumes when you press Enter on a partially-played episode. This works reliably for local files. For streaming URLs, resume depends on whether the podcast host's CDN supports HTTP range requests (--start). If the episode restarts from the beginning, the CDN is rejecting the seek — this is a host limitation, not a bug. Downloading the episode would allow reliable resume.

Updating

AetherPod checks GitHub for a newer version on startup and shows a notification when one is available.

aetherpod -u    # Upgrade to the latest version

• Editable / pip installs — -u pulls the update straight from git (no release build needed).
• Executable installs — download the new binary from the Releases page (-u requires pip/git and will not work inside a bundled executable).

Usage

Data

Override state path with --data /custom/path.json (supports relative paths for USB portability).

License

GPLv3 — Free as in freedom.