Summary

Subwave provides a personal internet radio station experience, acting as an agentic AI DJ that curates music and commentary for a single, shared broadcast. It targets users seeking a radio-like listening experience over personalized playlists, offering an AI-driven approach to music selection and on-air personality. The primary benefit is a unique, dynamic broadcast controlled by an AI, rather than listener-driven playback.

How It Works

The core architecture centers on a single Icecast stream, ensuring all listeners receive the same broadcast simultaneously. An AI DJ, powered by swappable LLM providers (e.g., Ollama, OpenAI) and TTS engines (e.g., Piper, ElevenLabs), selects music from the user's Navidrome library and generates between-track commentary, station idents, and weather updates. Music selection can be influenced by time of day, weather, and mood, with custom skills allowing for extensible DJ segments. The system runs self-hosted via Docker Compose.

Quick Start & Requirements

• Primary Install: Recommended CLI: curl -fsSL https://cli.getsubwave.com | sh followed by subwave setup. Raw Docker install involves downloading docker-compose.yml and .env.example, configuring .env, and running docker compose up -d.
• Prerequisites: Docker, Navidrome server (≥0.62 recommended for security and sonicSimilarity extension), an LLM provider (local or API key), and optionally a separate Docker profile for heavy TTS engines (~5-6 GB).
• Links: Project site: getsubwave.com, Demo player: getsubwave.com/listen, Setup: getsubwave.com/setup, Operator Manual: getsubwave.com/manual.

Highlighted Details

• Shared Broadcast: Emphasizes a true radio experience where everyone hears the same content concurrently, with no listener-side skip functionality.
• AI DJ & Personas: Leverages LLMs for track selection and commentary, supporting multiple DJ personas with distinct voices and writing styles.
• Swappable AI/TTS: LLM providers and TTS engines can be changed at runtime via the admin UI without redeploying.
• Pluggable Skills: DJ segments like weather or news are implemented as editable files, allowing customization without code changes.
• Library Observatory: A data-art visualization of the music library, mapping tracks by genre and energy, with detailed dossiers.
• Multi-Platform Access: Offers native iOS/Android apps, a PWA, and a terminal UI (TUI).

Maintenance & Community

Community support is available via a Discord server. Contribution guidelines are provided in CONTRIBUTING.md. The project appears actively maintained, with tagged releases published to GHCR.

Licensing & Compatibility

The project is licensed under the MIT license, which is permissive for commercial use and integration into closed-source projects.

Limitations & Caveats

The design intentionally omits listener-side skip buttons and per-listener shuffling, prioritizing a traditional radio broadcast feel. Certain core components, like the controller code, require a rebuild rather than a simple restart due to build-time asset copying. Several subsystems, including the queue, playback path, crossfade, and LLM layer, have non-obvious constraints that require careful attention during modification, as detailed in CLAUDE.md.