main

Ghetto Blaster 📻

A terminal-based podcast player with vim-style keybindings, built in Rust with ratatui.

Features

  • 🎵 Native Rust Audio: No external dependencies (mpv not required!)
  • ⚡ Instant Startup: Async RSS loading with real-time feed updates
  • 💾 Offline Caching: Episodes cache to ~/Music/{feed}/ for instant replay
  • 🎛️ Winamp-inspired Media Console: Real-time controls, volume, seek, progress
  • 📱 Smart Feed Management: Loading indicators (⟳ Loading, ✓ Loaded, ✗ Error)
  • 💾🌐 Cache Indicators: See which episodes are cached vs streaming
  • ⌨️ Vim-style Navigation: hjkl movement, space for pause, ESC to go back
  • 🔄 Background Loading: TUI appears instantly while feeds load
  • 📊 Real-time UI: Progress tracking, volume control, playback status
  • 🖥️ Cross-platform: Works on macOS, Linux, and Windows

Quick Install

curl -sSL https://raw.githubusercontent.com/xlgmokha/ghetto-blaster/main/scripts/install.sh | bash

GitHub Releases

Download pre-built binaries from Releases

From Source

git clone https://github.com/xlgmokha/ghetto-blaster
cd ghetto-blaster
cargo build --release
sudo cp target/release/ghetto-blaster /usr/local/bin/

Cargo Install

cargo install --git https://github.com/xlgmokha/ghetto-blaster

Usage

cargo run

On first run, it creates a config file at ~/.config/ghetto-blaster.yml with some default feeds.

Keybindings

Feed List:

  • j/k or ↓/↑ - Navigate feeds
  • Enter - Select feed and view episodes
  • r - Refresh all feeds
  • q - Quit

Episode List:

  • j/k or ↓/↑ - Navigate episodes
  • Enter or Space - Play episode
  • h or ← or Esc - Back to feed list
  • q - Quit

During Playback (mpv controls):

  • Space - Pause/unpause
  • ←/→ - Seek backward/forward 10s
  • 0/9 - Volume down/up
  • m - Mute
  • q - Stop

Configuration

Edit ~/.config/ghetto-blaster.yml:

feeds:
  "My Podcast": "https://example.com/feed.xml"
  "Another Show": "https://another.example/rss"

radio:
  "CBC Radio": "https://radio-stream-url"
  
music_dirs:
  - "~/Music"

Architecture

  • main.rs: TUI setup and event loop
  • app.rs: Application state and navigation logic
  • config.rs: YAML configuration management
  • feed.rs: RSS parsing and episode data
  • player.rs: mpv process management

Development

# Check compilation
cargo check

# Run with debug info
RUST_LOG=debug cargo run

# Run tests
cargo test

TODO

  • Search functionality
  • Download episodes for offline listening
  • Playback position saving/resuming
  • Episode marking (played/unplayed)
  • Background downloads
  • Playlist management

License

MIT