PinePods

PinePods is a full‑stack Rust application that delivers podcast management, playback, and synchronization across devices. The backend is a high‑performance Actix‑web service that exposes RESTful endpoints and WebSocket streams for real‑time state updates. The frontend is a WebAssembly (WASM) bundle built with Yew, which runs natively in the browser and provides a native‑app feel without sacrificing speed. The architecture is intentionally minimal: a single binary that can be containerized or compiled for ARM/Raspberry‑Pi, and a relational database (MySQL, MariaDB, or PostgreSQL) that holds all user data, podcast metadata, and playback state.

Technical Stack

The codebase follows a clean domain‑driven design: entities such as Podcast, Episode, and User are defined in a shared library, while the web service layer handles request routing, authentication (JWT), and background jobs for episode downloads. A lightweight task queue built on top of Tokio’s async runtime schedules download workers and sync jobs, ensuring the server remains responsive even under heavy media traffic.

Core Capabilities

• Multi‑user management: Role‑based access, per‑user subscription lists, and isolated playback state.
• Universal sync: Playback position, episode downloads, theme preferences, and smart playlists are stored server‑side and streamed to clients via WebSockets.
• Podcast discovery: Integrated search against the Podcast Index and iTunes APIs, with a pluggable caching layer to reduce external calls.
• Episode handling: Download, delete, and streaming of MP3/OPUS files via HTTP range requests.
• gPodder API: Full compatibility with AntennaPod, gpodder‑desktop, and other clients; can be toggled on/off per user.
• YouTube audio extraction: Subscribing to YouTube channels automatically creates “podcast‑style” feeds with audio‑only MP3s.
• Smart playlists: Declarative filters (e.g., “unplayed in last 30 days”) that sync across all devices.

Developers can extend functionality through the exposed REST API, which follows OpenAPI 3.0 specifications. The API surface includes endpoints for CRUD operations on podcasts, episodes, users, and playlists, as well as webhook hooks for external services (e.g., Slack notifications on new episode download).

Deployment & Infrastructure

PinePods is designed for self‑hosting on any Linux platform, from a Raspberry Pi to a production Kubernetes cluster. The Docker image contains the binary and a minimal Alpine runtime, keeping layers small (<200 MB). For Kubernetes, a Helm chart bundles the deployment with configurable resource requests/limits, persistent volume claims for media storage, and optional Ingress rules. The application is stateless except for the database and media files, which simplifies scaling: additional replicas can be spun up behind a load balancer without session stickiness.

Key deployment considerations:

• Database: Requires an existing MySQL/MariaDB/PostgreSQL instance. The schema is auto‑applied via Diesel migrations on startup.
• Media storage: Configurable mount path; can be a local disk, NFS share, or cloud object storage (via an S3‑compatible endpoint).
• Reverse proxy: HTTPS termination is recommended; the app accepts X‑Forwarded headers for correct host resolution.
• Resource limits: A single replica comfortably handles 50–100 concurrent users with moderate download traffic; CPU‑bound tasks are offloaded to a Tokio thread pool.

Integration & Extensibility

The architecture encourages plug‑in development:

• Search providers: Implement the search::Provider trait to swap between Podcast Index, iTunes, or a custom index.
• External sync: The gPodder API can be routed to third‑party services; developers can expose additional endpoints for custom clients.
• Webhooks: Subscribe to events such as episode_downloaded or podcast_subscribed via the built‑in webhook system.
• Theme engine: Themes are served as static assets; developers can add new CSS/JS bundles and register them in the UI settings.

Documentation is available on the official site, with a comprehensive API reference and example webhook payloads. The community maintains a Discord channel for real‑time support, and the GitHub repo encourages pull requests for new features.

Use Cases