{"id":17527005,"url":"https://github.com/madeofpendletonwool/pinepods-firewood","last_synced_at":"2026-06-08T11:32:39.354Z","repository":{"id":196509115,"uuid":"683703943","full_name":"madeofpendletonwool/pinepods-firewood","owner":"madeofpendletonwool","description":"A light client for Pinepods that can be used to beam podcasts to","archived":false,"fork":false,"pushed_at":"2025-08-27T00:17:31.000Z","size":14764,"stargazers_count":8,"open_issues_count":3,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-03-05T13:00:03.386Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/madeofpendletonwool.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-08-27T12:46:10.000Z","updated_at":"2026-01-07T09:48:37.000Z","dependencies_parsed_at":"2023-10-19T14:25:13.356Z","dependency_job_id":"9b9f3489-502d-4acd-9654-574afcae4729","html_url":"https://github.com/madeofpendletonwool/pinepods-firewood","commit_stats":null,"previous_names":["madeofpendletonwool/pinepods-firewood"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/madeofpendletonwool/pinepods-firewood","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/madeofpendletonwool%2Fpinepods-firewood","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/madeofpendletonwool%2Fpinepods-firewood/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/madeofpendletonwool%2Fpinepods-firewood/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/madeofpendletonwool%2Fpinepods-firewood/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/madeofpendletonwool","download_url":"https://codeload.github.com/madeofpendletonwool/pinepods-firewood/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/madeofpendletonwool%2Fpinepods-firewood/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34061122,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-08T02:00:07.615Z","response_time":111,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-20T15:02:55.988Z","updated_at":"2026-06-08T11:32:39.349Z","avatar_url":"https://github.com/madeofpendletonwool.png","language":"Rust","funding_links":[],"categories":["Rust"],"sub_categories":[],"readme":"# 🎵 PinePods Firewood\n\nA comprehensive TUI (Terminal User Interface) podcast client for PinePods that doubles as a remote-controllable player. Stream your podcasts in style from the terminal and control playback remotely from the web interface or other devices on your network.\n\n![Pinepods Logo](assets/pinepods-logo.jpeg)\n\n## ✨ Features\n\n### 🖥️ **Terminal User Interface**\n- **Beautiful TUI**: Full-featured terminal interface with intuitive navigation\n- **Podcast Browser**: Browse your subscribed podcasts with two-panel view\n- **Episode Management**: View recent, saved, queued, and downloaded episodes\n- **Audio Player**: Built-in player with play/pause, skip (±15s), volume control\n- **Micro-Player**: Always-visible playback controls at bottom of every screen\n- **Search**: Find episodes and podcasts quickly\n- **Session Persistence**: Remembers your login between sessions\n\n### 🌐 **Remote Control System**\n- **mDNS Discovery**: Automatically discoverable on local network\n- **HTTP API**: RESTful endpoints for remote control\n- **Web UI Integration**: Ready for \"beam to Firewood\" functionality\n- **Smart Port Management**: Automatic port fallback if conflicts occur\n- **Multi-Instance**: Run multiple Firewood players simultaneously\n\n### 🎧 **Audio Playback**\n- **Streaming Support**: Direct episode streaming from PinePods server\n- **Playback Controls**: Play/pause, skip forward/backward, seek, volume\n- **Progress Tracking**: Syncs listening progress with PinePods server\n- **Format Support**: Supports all audio formats via Symphonia decoder\n\n## 🚀 Installation\n\n### 🎯 Quick Install (Recommended)\n\n**One-liner installer** (Linux/macOS/Windows):\n```bash\ncurl -sSL https://raw.githubusercontent.com/madeofpendletonwool/pinepods-firewood/main/install.sh | bash\n```\n\n### 📦 Package Managers\n\n```bash\n# Homebrew (macOS/Linux)\nbrew install pinepods-firewood\n\n# Cargo (Rust)\ncargo install pinepods-firewood\n\n# Arch Linux (AUR)\nyay -S pinepods-firewood\n\n# Ubuntu/Debian\nwget https://github.com/madeofpendletonwool/pinepods-firewood/releases/latest/download/pinepods-firewood_VERSION_amd64.deb\nsudo dpkg -i pinepods-firewood_*.deb\n```\n\n### 📥 Manual Downloads\n\nDownload pre-built binaries from [GitHub Releases](https://github.com/madeofpendletonwool/pinepods-firewood/releases/latest):\n- **Linux**: `pinepods-firewood-linux-amd64.tar.gz`\n- **macOS**: `pinepods-firewood-macos-amd64.tar.gz` (Intel) / `pinepods-firewood-macos-arm64.tar.gz` (Apple Silicon)  \n- **Windows**: `pinepods-firewood-windows-amd64.zip`\n\n### 🔨 Build from Source\n\n**Prerequisites:**\n- Rust toolchain (1.75+)\n- System dependencies:\n  ```bash\n  # Ubuntu/Debian\n  sudo apt install pkg-config libasound2-dev libssl-dev\n  \n  # Fedora\n  sudo dnf install pkg-config alsa-lib-devel openssl-devel\n  \n  # Arch Linux\n  sudo pacman -S pkg-config alsa-lib openssl\n  \n  # macOS (with Homebrew)\n  brew install pkg-config\n  ```\n\n**Build:**\n```bash\ngit clone https://github.com/madeofpendletonwool/pinepods-firewood.git\ncd pinepods-firewood\ncargo build --release\nsudo cp target/release/pinepods_firewood /usr/local/bin/\n```\n\n📖 **[Complete Installation Guide](INSTALLATION.md)** - All methods, troubleshooting, and platform-specific instructions.\n\n## 📱 Usage\n\n### First Launch\n1. **Server Setup**: Enter your PinePods server URL\n2. **Authentication**: Login with your PinePods credentials\n3. **Multi-Factor**: Complete MFA if enabled\n4. **Timezone**: Select your timezone for episode timestamps\n\n### Navigation\n- **Tab**: Switch between tabs (Home, Podcasts, Episodes, Player, etc.)\n- **1-9**: Quick tab switching\n- **Arrow Keys/hjkl**: Navigate lists\n- **Enter**: Select item\n- **Space**: Global play/pause\n- **r**: Refresh current page\n- **q/Ctrl+C**: Quit\n\n### Tabs Overview\n\n#### 🏠 **Home** *(Implemented)*\n- Recent episodes from subscriptions\n- Continue listening recommendations\n- Quick access to saved/downloaded content\n\n#### 🎙️ **Podcasts** *(Implemented)*\n- **Left Panel**: Subscribed podcasts list\n- **Right Panel**: Episodes for selected podcast\n- **Navigation**: Tab/arrows to switch panels\n- **Playback**: Enter to play selected episode\n\n#### 📻 **Episodes** *(Implemented)*\n- Recent episodes from all subscriptions\n- **Filters**: All, In Progress, Completed\n- **Auto-load**: Episodes load automatically\n- **Search**: Real-time episode filtering\n\n#### 🎵 **Player** *(Implemented)*\n- Full-screen player interface\n- Playback controls (play/pause/skip)\n- Progress bar with time display\n- Volume control\n- Episode artwork and metadata\n\n#### 📝 **Queue** *(Planned)*\n- Manage episode queue\n- Drag-and-drop reordering\n- Bulk operations\n\n#### ⭐ **Saved** *(Planned)*\n- Bookmarked episodes\n- Personal favorites\n- Offline access preparation\n\n#### 📥 **Downloads** *(Planned)*\n- Downloaded episode management\n- Offline playback\n- Storage usage monitoring\n\n#### 🔍 **Search** *(Planned)*\n- Global episode/podcast search\n- Advanced filters\n- Podcast discovery\n\n#### ⚙️ **Settings** *(Planned)*\n- Audio output configuration\n- Remote control settings\n- Theme customization\n- Keyboard shortcuts\n\n## 🌐 Remote Control\n\nFirewood includes a built-in HTTP server that makes it discoverable and controllable over your local network.\n\n### 🔧 **Configuration**\n\n**Environment Variables:**\n```bash\n# Custom port (default: 8042)\nexport FIREWOOD_REMOTE_PORT=8080\n\n# Disable remote control\nexport FIREWOOD_REMOTE_DISABLED=true\n\n# Run with custom settings\ncargo run\n```\n\n**Port Fallback System:**\nIf the preferred port is busy, Firewood automatically tries:\n1. Preferred port (default: 8042)\n2. Preferred + 1, + 2 (8043, 8044)  \n3. Common ports: 8080-8083, 3000-3002, 4000-4002, 9000-9002\n4. OS-assigned random port (ultimate fallback)\n\n### 🕵️ **Discovery**\n\nFirewood advertises itself via mDNS as:\n- **Service**: `_pinepods-remote._tcp.local.`\n- **Properties**: \n  - `version`: Firewood version\n  - `server`: Connected PinePods server URL\n- **Auto-Discovery**: Web UI can scan and connect automatically\n\n### 📡 **HTTP API**\n\n| Endpoint | Method | Description | Body Example |\n|----------|---------|-------------|--------------|\n| `/` | GET | Get player info | - |\n| `/status` | GET | Get playback status | - |\n| `/play` | POST | Play episode | `{\"episode_url\": \"...\", \"episode_title\": \"...\", \"podcast_name\": \"...\", \"episode_duration\": 3600}` |\n| `/pause` | POST | Pause playback | - |\n| `/resume` | POST | Resume playback | - |\n| `/stop` | POST | Stop playback | - |\n| `/skip` | POST | Skip seconds | `{\"seconds\": 15}` (negative for backward) |\n| `/seek` | POST | Seek to position | `{\"position\": 120}` |\n| `/volume` | POST | Set volume | `{\"volume\": 0.7}` (0.0-1.0) |\n\n### 🧪 **Testing \u0026 Manual Control**\n\nA Python test script is included for discovery and manual control:\n\n```bash\n# Setup (one time)\npython3 -m venv venv\nsource venv/bin/activate\npip install -r requirements.txt\n\n# Discover Firewood players on network\npython test_remote_control.py --discover\n\n# Interactive control\npython test_remote_control.py -u http://IP:PORT --interactive\n\n# Direct connection (if you know the IP/port)\npython test_remote_control.py -u http://192.168.1.100:8042 --interactive\n```\n\n**Interactive Commands:**\n- `s` - Show playback status\n- `p` - Pause/resume toggle\n- `stop` - Stop playback\n- `+15` - Skip forward 15 seconds\n- `-15` - Skip backward 15 seconds  \n- `vol 75` - Set volume to 75%\n- `play` - Play test episode\n- `q` - Quit\n\n## 🔗 Web UI Integration *(Future)*\n\nWhen implemented in the PinePods web interface:\n\n1. **Network Scan**: Web UI discovers Firewood players via mDNS\n2. **Player List**: Shows available players with their names and server info\n3. **Episode Beaming**: \"Play on Firewood\" button on episode pages\n4. **Remote Control**: Volume, skip, pause controls in web interface\n5. **Multi-Room**: Control multiple Firewood players simultaneously\n\n## 🔧 Development\n\n### Project Structure\n```\nsrc/\n├── api/           # PinePods API client\n├── audio/         # Audio playback engine\n├── auth/          # Authentication \u0026 session management\n├── config/        # Configuration handling\n├── helpers/       # Utility functions\n├── remote/        # Remote control server \u0026 mDNS\n└── tui/           # Terminal user interface\n    └── pages/     # Individual TUI screens\n```\n\n### Key Technologies\n- **TUI**: [Ratatui](https://github.com/ratatui-org/ratatui) for terminal interface\n- **Audio**: [Rodio](https://github.com/RustAudio/rodio) for playback\n- **HTTP**: [Axum](https://github.com/tokio-rs/axum) for remote control server\n- **mDNS**: [mdns-sd](https://github.com/keepsimple1/mdns-sd) for service discovery\n- **Async**: [Tokio](https://tokio.rs/) runtime\n\n### Contributing\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature-name`\n3. Make your changes\n4. Test thoroughly (especially TUI interactions)\n5. Submit a pull request\n\n### Testing\n\n```bash\n# Run tests\ncargo test\n\n# Test with debug logging\nRUST_LOG=debug cargo run\n\n# Test remote control\npython test_remote_control.py --help\n\n# Test port fallback\nFIREWOOD_REMOTE_PORT=9999 cargo run\n```\n\n## 🐛 Troubleshooting\n\n### Common Issues\n\n**\"ALSA lib\" errors:**\n```bash\n# Install ALSA development libraries\nsudo apt install libasound2-dev  # Ubuntu/Debian\nsudo dnf install alsa-lib-devel   # Fedora\n```\n\n**Port conflicts:**\n```bash\n# Check what's using the port\nss -tlnp | grep 8042\n\n# Use different port\nexport FIREWOOD_REMOTE_PORT=8080\n```\n\n**Authentication failures:**\n- Verify PinePods server URL (include http/https)\n- Check server connectivity\n- Ensure correct username/password\n- Complete MFA if enabled\n\n**mDNS discovery fails:**\n- Ensure devices are on same network\n- Check firewall settings (allow mDNS port 5353)\n- Try manual connection with IP:PORT\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- [PinePods](https://github.com/madeofpendletonwool/PinePods) - The podcast management platform\n- [Ratatui](https://github.com/ratatui-org/ratatui) - Terminal UI framework\n- [Rodio](https://github.com/RustAudio/rodio) - Cross-platform audio playback\n\n## 🗺️ Roadmap\n\n### Near Term (v0.2.0)\n- [ ] Complete Queue management\n- [ ] Saved episodes functionality  \n- [ ] Download management\n- [ ] Search implementation\n- [ ] Settings page with audio/remote config\n\n### Medium Term (v0.3.0)\n- [ ] Offline playback support\n- [ ] Playlist management\n- [ ] Keyboard shortcut customization\n- [ ] Theme system\n- [ ] Performance optimizations\n\n### Long Term (v1.0.0)\n- [ ] Web UI integration (PinePods side)\n- [ ] Multi-room synchronization\n- [ ] Plugin system\n- [ ] Advanced discovery options\n- [ ] Mobile companion app\n\n---\n\n**Made with ❤️ for the PinePods ecosystem**","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmadeofpendletonwool%2Fpinepods-firewood","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmadeofpendletonwool%2Fpinepods-firewood","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmadeofpendletonwool%2Fpinepods-firewood/lists"}