Skip to main content

Firewood User Guide

Complete guide to using PinePods Firewood - your feature-rich terminal podcast client.

Interface Overview​

Firewood provides a tabbed interface with multiple sections for managing and listening to your podcasts. Each tab offers specific functionality for different aspects of podcast management.

Tab Switching:

  • Tab - Navigate between tabs sequentially
  • 1-9 - Jump directly to specific tabs by number
  • Arrow Keys / hjkl - Navigate within lists and content
  • Enter - Select/activate items
  • q / Ctrl+C - Quit application

Global Controls:

  • Space - Global play/pause toggle (works from any tab)
  • Ctrl+R - Refresh current page/content
  • Esc - Return to previous screen or cancel actions

Tab-by-Tab Guide​

🏠 Home Tab (1)​

Your dashboard for quick access to recent content and recommendations.

Features:

  • Recent Episodes: Latest episodes from your subscribed podcasts
  • Continue Listening: Resume episodes you've started but haven't finished
  • Quick Access: Jump to saved content and downloads
  • Activity Overview: See your listening progress and statistics

Navigation:

  • Use arrow keys to browse through recent episodes
  • Press Enter to start playing an episode
  • Episodes show title, podcast name, and publication date

🎵 Player Tab (2)​

Full-screen audio player with comprehensive playback controls.

Player Interface:

  • Episode Information: Title, podcast name, description
  • Artwork Display: Episode or podcast cover art
  • Progress Bar: Visual playback progress with time indicators
  • Control Buttons: Play, pause, skip forward/backward, volume

Playback Controls:

  • Space / Enter - Play/pause toggle
  • → / l - Skip forward 15 seconds
  • ← / h - Skip backward 15 seconds
  • ↑ / k - Increase volume
  • ↓ / j - Decrease volume
  • 0-9 - Seek to percentage (0% to 90%)
  • m - Mute/unmute audio

Advanced Features:

  • Progress Sync: Automatically syncs listening progress with PinePods server
  • Resume Playback: Pick up where you left off on any device
  • Smart Skip: Respects podcast chapter markers when available
  • Background Play: Continues playing while you browse other tabs

📻 Episodes Tab (3)​

Comprehensive episode management with filtering and search capabilities.

Content Views:

  • All Episodes: Complete feed of recent episodes from all subscriptions
  • In Progress: Episodes you've started but haven't finished
  • Completed: Episodes you've finished listening to

Features:

  • Auto-loading: Episodes load automatically as you scroll
  • Real-time Search: Filter episodes by title or podcast name
  • Status Tracking: Visual indicators for play status and progress
  • Batch Actions: Mark multiple episodes as played/unplayed

Navigation:

  • ↑/↓ - Browse episode list
  • Enter - Play selected episode
  • Space - Quick play/pause
  • / - Activate search mode
  • Esc - Clear search filter

🎙️ Podcasts Tab (4)​

Browse your podcast subscriptions with a dual-panel interface.

Layout:

  • Left Panel: List of subscribed podcasts
  • Right Panel: Episodes from the selected podcast

Navigation:

  • Tab - Switch between left and right panels
  • ↑/↓ or j/k - Navigate podcast list
  • Enter - Select podcast (loads episodes in right panel)
  • In episodes panel: ↑/↓ to browse, Enter to play

Features:

  • View all your podcast subscriptions organized alphabetically
  • See episode counts and latest episode information
  • Quick access to specific podcast episodes
  • Podcast artwork and descriptions (when available)

📝 Queue Tab (5)​

Manage your episode queue and listening order.

Features:

  • Queue Management: Add, remove, and reorder episodes
  • Queue Display: View your current listening queue
  • Episode Controls: Play episodes directly from queue
  • Queue Actions: Clear queue and manage playback order

Navigation:

  • ↑/↓ - Browse queue items
  • Enter - Play selected episode
  • d / Delete - Remove from queue
  • c - Clear entire queue

⭐ Saved Tab (6)​

Access your bookmarked and favorite episodes.

Features:

  • Bookmarks: Episodes you've marked for later
  • Favorites: Your starred episodes and podcasts
  • Collections: Custom groups of related episodes
  • Quick Access: Fast filtering and search within saved content
  • Sync: Saved items sync across all your devices

Navigation:

  • ↑/↓ - Browse saved episodes
  • Enter - Play selected episode
  • r - Remove from saved
  • / - Search saved content

📥 Downloads Tab (7)​

Manage offline episode downloads for listening without internet.

Features:

  • Download Management: Queue, pause, cancel downloads
  • Offline Library: Browse downloaded episodes
  • Storage Monitoring: Track disk usage and manage space
  • Auto-download: Set rules for automatic episode downloads
  • Quality Settings: Choose download quality and format

Navigation:

  • ↑/↓ - Browse downloaded episodes
  • Enter - Play downloaded episode
  • d / Delete - Delete download
  • p - Pause/resume download

🔍 Search Tab (8)​

Discover new content and find specific episodes or podcasts.

Features:

  • Global Search: Find episodes across all your subscriptions
  • Podcast Discovery: Browse and subscribe to new podcasts
  • Advanced Filters: Filter by date, duration, podcast, etc.
  • Search History: Quick access to previous searches
  • Trending: See popular and recommended content

Navigation:

  • / - Enter search query
  • ↑/↓ - Browse search results
  • Enter - Play or subscribe to result
  • Esc - Clear search

⚙️ Settings Tab (9)​

Configure Firewood to match your preferences and setup.

Features:

  • Audio Settings: Output device, volume levels, equalizer
  • Remote Control: Configure network settings and port
  • Appearance: Themes, colors, and layout customization
  • Keyboard Shortcuts: Customize key bindings
  • Sync Settings: Server connection and sync preferences
  • Advanced Options: Debug settings and performance tuning

Navigation:

  • ↑/↓ - Browse settings categories
  • Enter - Modify setting
  • Esc - Cancel changes
  • s - Save settings

Micro-Player Controls​

Firewood includes an always-visible micro-player at the bottom of every screen, providing quick access to playback controls without switching to the Player tab.

Micro-Player Features:

  • Track Info: Current episode title and podcast name
  • Playback Status: Play/pause indicator and progress
  • Quick Controls: Play/pause, skip buttons
  • Time Display: Current position and total duration
  • Volume Indicator: Current volume level

Universal Controls:

  • Space - Play/pause from any screen
  • → / Ctrl+→ - Skip forward 15 seconds
  • ← / Ctrl+← - Skip backward 15 seconds
  • ↑ / Ctrl+↑ - Volume up
  • ↓ / Ctrl+↓ - Volume down

Remote Control Features​

Firewood can be controlled remotely from other devices on your network, making it perfect for integration with smart home systems or remote control from phones/tablets.

Network Discovery​

Automatic Discovery:

  • Firewood advertises itself via mDNS as _pinepods-remote._tcp.local.
  • Other devices can automatically find and connect to your Firewood instance
  • No manual IP configuration needed on the same network

Manual Connection:

  • Connect directly using IP:PORT (default port 8042)
  • Supports custom port configuration via environment variables

Remote Control API​

HTTP Endpoints:

  • GET /status - Get current playback status
  • POST /play - Play specific episode
  • POST /pause - Pause playback
  • POST /resume - Resume playback
  • POST /stop - Stop playback
  • POST /skip - Skip forward/backward by seconds
  • POST /seek - Seek to specific position
  • POST /volume - Set volume level

Web Integration: When implemented in PinePods web UI, you'll be able to:

  • "Beam" episodes directly to Firewood players
  • Control multiple Firewood instances from one interface
  • See all available players on your network
  • Sync playback across devices

Remote Control Setup​

Configuration:

# Custom port (default: 8042)
export FIREWOOD_REMOTE_PORT=8080

# Disable remote control
export FIREWOOD_REMOTE_DISABLED=true

# Run Firewood
pinepods_firewood

Testing Remote Control: Use the included Python test script:

# Discover Firewood players
python test_remote_control.py --discover

# Interactive control
python test_remote_control.py -u http://IP:PORT --interactive

Audio and Playback​

Supported Formats​

Firewood supports all major podcast audio formats:

  • MP3 - Most common podcast format
  • AAC/M4A - Apple's audio format
  • OGG/Vorbis - Open source format
  • FLAC - Lossless audio format
  • WAV - Uncompressed audio

Playback Features​

Streaming:

  • Direct streaming from PinePods server
  • No local storage required for streaming
  • Automatic quality adjustment based on connection

Progress Tracking:

  • Syncs listening position with PinePods server
  • Resume playback across devices
  • Marks episodes as played automatically

Audio Controls:

  • Variable speed playback (planned)
  • Sleep timer (planned)
  • Chapter navigation (planned)
  • Noise reduction (planned)

Keyboard Shortcuts Reference​

Global Shortcuts​

KeyAction
TabSwitch tabs
1-9Jump to tab
SpacePlay/pause
qQuit
Ctrl+CForce quit
Ctrl+RRefresh
KeyAction
↑/↓ or k/jNavigate up/down
←/→ or h/lNavigate left/right
EnterSelect/activate
EscBack/cancel

Player Controls​

KeyAction
SpacePlay/pause
→Skip forward 15s
←Skip backward 15s
↑Volume up
↓Volume down
mMute/unmute
0-9Seek to percentage

List Management​

KeyAction
/Search/filter
EscClear search
Page Up/DownScroll pages
Home/EndGo to top/bottom

Tips and Best Practices​

Efficient Navigation​

  • Use Number Keys: Quickly jump between tabs with 1-9
  • Master the Micro-Player: Control playback without leaving your current tab
  • Search Everything: Use / to quickly filter long lists
  • Keyboard First: Learn the shortcuts for faster navigation

Managing Large Libraries​

  • Use Filters: Episode tab filters help manage large subscription lists
  • Save Important Episodes: Use the Saved tab for episodes you want to return to
  • Queue Management: Build listening queues for organized podcast sessions
  • Regular Cleanup: Mark episodes as played to keep lists manageable

Remote Control Tips​

  • Multiple Instances: Run Firewood on multiple devices for whole-home audio
  • Port Management: Use custom ports if you have conflicts
  • Network Setup: Ensure devices are on same network for auto-discovery
  • Firewall: Allow mDNS (port 5353) for automatic discovery

Performance Optimization​

  • Refresh Wisely: Use r to refresh content when needed
  • Background Updates: Let Firewood handle automatic syncing
  • Network Patience: Allow time for episode lists to load on slower connections

Troubleshooting​

Common Issues​

Audio Not Playing:

  • Check system audio settings and volume
  • Verify ALSA libraries are installed (Linux)
  • Test with different episodes to isolate the issue

Connection Problems:

  • Verify PinePods server is running and accessible
  • Check network connectivity and firewall settings
  • Try manual server URL entry

Performance Issues:

  • Close other resource-intensive applications
  • Check available system memory
  • Update to latest Firewood version

Remote Control Not Working:

  • Ensure devices are on same network
  • Check if port is blocked by firewall
  • Try manual IP:PORT connection

Getting Help​

  • GitHub Issues: Report bugs and request features
  • Documentation: Check README.md and other docs in the repository
  • Community: Join discussions in GitHub Discussions
  • Logs: Enable debug logging with RUST_LOG=debug pinepods_firewood

Enjoy your podcast listening experience with Firewood! This terminal-based client brings the power and convenience of PinePods directly to your command line, with all the features you need for managing and enjoying your favorite shows.