🎵 PinePods Firewood

A TUI (terminal user interface) podcast client for PinePods. Stream your podcasts from the terminal, with listening progress kept in sync with the server.

✨ Features

🖥️ Terminal User Interface

• Sidebar layout: every page one key away, with a now-playing bar and the keys for the page you're on always on screen
• Pages: Home, Feed, Podcasts, Queue, Saved, Downloads, Search, Devices, Now Playing and Settings, plus episode details with show notes
• Filter as you type: / narrows any list; Search queries your server as you type
• Themes: the same 25 themes as the PinePods web app, starting with the one you picked there, or your terminal's own colors
• Keys you can change: vim-style and arrow keys by default, ? lists them, keymap.toml rebinds them
• Mouse: click to select, click again to play or open, scroll lists, click the progress bar to seek
• Never waits: everything loads in the background, with a spinner while it does and a short message when something fails
• Session Persistence: Remembers your login between sessions (the API key is kept in the OS keychain)

🎧 Audio Playback

• Streaming: Playback starts within a second or two, and seeking anywhere fetches just that part of the episode. Episodes your server has downloaded (and YouTube videos) play from the server's copy; everything else from the feed
• Playback Controls: Play/pause, skip forward/backward, seek, volume
• Speed: 0.5× to 3× without changing pitch, starting from each podcast's speed setting in PinePods
• Skips: Jumps over ads and silence PinePods has detected (silence follows the podcast's trim-silence setting), and over a podcast's intro and outro skip times
• Queue: When an episode ends it's marked played and the next one in your queue starts
• Progress Tracking: Resumes where you left off and saves your position to the server while you listen
• Reconnects: Rides out short network drops and picks up where you were
• Formats: MP3, AAC/M4A, FLAC, Ogg Vorbis and WAV

🚀 Installation

🎯 Quick Install (Recommended)

One-liner installer (Linux/macOS/Windows):

curl -sSL https://raw.githubusercontent.com/madeofpendletonwool/pinepods-firewood/main/install.sh | bash

📦 Package Managers

# Homebrew (macOS/Linux)
brew install pinepods-firewood

# Cargo (Rust)
cargo install pinepods-firewood

# Arch Linux (AUR)
yay -S pinepods-firewood

# Ubuntu/Debian
wget https://github.com/madeofpendletonwool/pinepods-firewood/releases/latest/download/pinepods-firewood_VERSION_amd64.deb
sudo dpkg -i pinepods-firewood_*.deb

📥 Manual Downloads

Download pre-built binaries from GitHub Releases:

• Linux: pinepods-firewood-linux-amd64.tar.gz
• macOS: pinepods-firewood-macos-amd64.tar.gz (Intel) / pinepods-firewood-macos-arm64.tar.gz (Apple Silicon)
• Windows: pinepods-firewood-windows-amd64.zip

🔨 Build from Source

Prerequisites:

• Rust toolchain (1.75+)
• System dependencies:

  # Ubuntu/Debian
  sudo apt install pkg-config libasound2-dev libssl-dev
  
  # Fedora
  sudo dnf install pkg-config alsa-lib-devel openssl-devel
  
  # Arch Linux
  sudo pacman -S pkg-config alsa-lib openssl
  
  # macOS (with Homebrew)
  brew install pkg-config

Build:

git clone https://github.com/madeofpendletonwool/pinepods-firewood.git
cd pinepods-firewood
cargo build --release
sudo cp target/release/pinepods_firewood /usr/local/bin/

📖 Complete Installation Guide - All methods, troubleshooting, and platform-specific instructions.

📱 Usage

First Launch

1. Server Setup: Enter your PinePods server URL
2. Authentication: Login with your PinePods credentials
3. Multi-Factor: Complete MFA if enabled
4. Timezone: Select your timezone for episode timestamps

Getting around

• 1–9, 0 jump to a sidebar entry (in the order shown; change it in Settings). Tab / Shift+Tab step through them
• j/k or ↑/↓ move, g/G first/last, Ctrl+D/U page down/up
• Enter plays an episode or opens a podcast. i (or l) opens an episode's details and show notes. Esc goes back
• / filters the list you're on; Enter keeps the filter, Esc clears it
• ? shows every key for the page you're on. q quits (Ctrl+C works anywhere, even mid-typing)

Playing

• Space play/pause, ←/→ skip back/forward (15 s by default; change it in Settings)
• [ / ] slower/faster (0.5× to 3×, pitch stays the same), +/- volume
• n opens Now Playing, which adds = for normal speed, t to toggle trimming silence for the podcast and x to stop

On any episode

• a add to or remove from the queue, A play next
• s save/unsave, d have the server download it (or delete its copy), m mark played/unplayed
• o play it on another of your devices

Pages

• Home: where you left off, new episodes and your most-played podcasts
• Feed: recent episodes from every subscription. f cycles All / Unplayed / In progress / Played
• Podcasts: your subscriptions; Enter lists a podcast's episodes
• Queue: K/J move an episode up/down, t/b to the top/bottom, x remove, S shuffle, C twice to clear
• Saved and Downloads: episodes you've saved, and the ones your server has a copy of
• Search: episodes from the podcasts you follow
• Devices: your other players (see Remote Control)
• Settings: theme, starting volume, skip length, audio output, the name other devices see, sidebar order, and the key bindings and log files

Themes

Firewood starts with the theme you picked in the PinePods web app, so a change there shows up the next time it opens. Picking a theme in Settings stops that. The Terminal theme uses your terminal's own colors. Firewood uses 24-bit color where the terminal says it supports it and the nearest 256-color match elsewhere; FIREWOOD_COLOR=truecolor or FIREWOOD_COLOR=256 overrides the guess.

Key bindings

Settings → Key bindings writes ~/.config/pinepods-firewood/keymap.toml with every binding commented out. Uncomment a line and change its keys, then restart:

[global]
quit = ["q", "ctrl+q"]

[queue]
move_up = ["U", "shift+up"]

Keys look like "q", "G", "space", "enter", "ctrl+r", "shift+up" or "f5". A mistake in the file shows as a message at startup and leaves the defaults in place.

Mouse

Clicking selects, clicking the selected row again plays or opens it, and the wheel scrolls. With the mouse on, selecting text in most terminals needs Shift (Option in some macOS terminals) held down; FIREWOOD_NO_MOUSE=1 turns it off.

🔧 Development

Project Structure

src/
├── api/           # Typed PinePods API client
├── audio/         # Audio output thread
├── auth/          # Login flow and saved session
├── nowplaying/    # Remote control over the server's now-playing socket
├── playback/      # Playback core and progress sync
├── theme/         # The web app's themes, adapted for a terminal
└── tui/           # Terminal user interface
    ├── app.rs     # Sidebar, now-playing bar, overlays, input routing
    ├── keymap.rs  # Default bindings and keymap.toml
    ├── task.rs    # Background loading
    ├── ui/        # Shared widgets: lists, episode rows, show notes
    └── pages/     # The screens

Key Technologies

• TUI: Ratatui for terminal interface
• Audio: Rodio for playback
• HTTP: reqwest with rustls
• Async: Tokio runtime

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature-name
3. Make your changes
4. Test thoroughly (especially TUI interactions)
5. Submit a pull request

Testing

# Run tests
cargo test

# Debug logging (any tracing EnvFilter directive works)
FIREWOOD_LOG=debug cargo run

Logs are written to a daily file under the platform's local data directory (~/Library/Application Support/pinepods-firewood/logs on macOS, ~/.local/share/pinepods-firewood/logs on Linux), and kept for a week.

📡 Remote Control

Firewood holds a socket to your PinePods server (/ws/api/nowplaying) so your other devices can see what it's playing and control it, and it can control them. Nothing listens on your network; the server relays everything. The web and mobile apps can beam episodes to Firewood like to any other device, and it accepts their commands.

• Other devices see it as Firewood · <hostname>. Change that in Settings.
• FIREWOOD_REMOTE_DISABLED=1 turns the socket off.
• If the Devices page says the server has no now-playing socket, the server is older than the now-playing release, or a reverse proxy in front of it doesn't pass WebSocket upgrades on /ws/api/ through.

🐛 Troubleshooting

Common Issues

"ALSA lib" errors:

# Install ALSA development libraries
sudo apt install libasound2-dev  # Ubuntu/Debian
sudo dnf install alsa-lib-devel   # Fedora

Authentication failures:

• Verify PinePods server URL (include http/https)
• Check server connectivity
• Ensure correct username/password
• Complete MFA if enabled

📄 License

This project is licensed under the GNU General Public License v3.0; see the LICENSE file for details.

🙏 Acknowledgments

• PinePods - The podcast management platform
• Ratatui - Terminal UI framework
• Rodio - Cross-platform audio playback

🗺️ Roadmap

• History, playlists and collections
• Chapters and transcripts
• Podcast discovery and subscribing
• A command palette
• Cover art in terminals that can show images
• Media keys and the system's now-playing controls (MPRIS on Linux, Now Playing on macOS)
• Headless mode, for a Raspberry Pi or speaker box that other devices play on

---

Made with ❤️ for the PinePods ecosystem