Airwave
# 🚀 Airwave ### Self-hosted shared radio — everyone listens in sync     [](https://vuejs.org/) > 🎧 **Turn any link into a shared listening experience** Paste a YouTube, SoundCloud, Mixcloud, or Spotify playlist link → Airwave creates a **single live stream** → Everyone hears the **exact same audio, at the exact same time** No accounts. No premium APIs. No “press play at the same time.”  --- ## ⚡ Try it in 30 seconds ```bash docker run -d -p 8000:8000 ghcr.io/76696265636f646572/airwave ``` Open → [http://localhost:8000](http://localhost:8000) Paste a link → music starts → share the URL 🎉 --- ## 🎧 The idea (why this exists) Many music apps weren’t built for **shared listening**: * Everyone plays their **own stream** * Locked into one platform **Airwave solves this:** * One stream → multiple listeners * Works across browsers and Sonos * Import Spotify playlists → automatically matched to playable tracks * Multi-source playback (YouTube, SoundCloud, Mixcloud, direct URLs, optional local files) Simple idea. Huge difference. --- ## ✨ What makes Airwave different? ### 🔊 One shared live stream * Browsers connect as **SendSpin** clients * All listeners hear the same thing * No per-user transcoding * **Synchronized playback** across devices (SendSpin only) --- ### 📋 Collaborative queue * Anyone can add tracks * Drag & reorder in real time * Shared history --- ### ▶️ Multi-source playback * YouTube (videos + playlists) * SoundCloud (tracks + sets) * Mixcloud (shows) * Direct HTTP(S) URLs to audio when ffmpeg can read them * Local files 👉 Paste almost any music link — it just works --- ### 💿 Local files & folders * Point Airwave at one or more directories with **`AIRWAVE_LOCAL_MEDIA_ROOTS`** * Browse and queue tracks from the UI (paths must stay inside those roots) * Great for NAS mounts, a music library on disk, or bind-mounted folders in Docker --- ### 🎵 Spotify → playable music * Import Spotify playlists into your **library** * Auto-match tracks to YouTube, SoundCloud, or Mixcloud * Review and pick the best version for your shared stream --- ### 🔈 Sonos integration * Uses `/stream/live.mp3` * Discover speakers on your LAN * Group and control playback * Same stream as browser clients --- ### 🎮 Player experience * Play / pause / skip / repeat * Seek (when supported) * Fullscreen “Now Playing” * Lock screen controls (Media Session) --- ### 💡 WLED / ambient light sync (sound reactive) * Sync **WLED** lights to Airwave using **LedFX** * Perfect for party mode and room vibe --- ### 📚 Library & playlists * Create and manage playlists * Import YouTube or Spotify playlists * Merge playlists (with deduplication) * Pin and reorder --- ### 🔄 Playlist auto-sync * Turn on **Auto-sync** (🔁) for any imported playlist * New tracks are added automatically * Your order stays untouched **Optional:** remove tracks that disappear from the source (off by default) --- ## 🧑🤝🧑 Perfect for * 🎉 Parties (everyone queues music) * 🏠 Shared household audio * 🧑💻 Remote team listening * 🔊 Sonos multi-room setups * 🎧 Friends hanging out online --- ## 🧠 How it works ``` yt-dlp → ffmpeg → shared MP3 stream → all listeners ``` * One pipeline * One stream * Unlimited listeners --- ## 🐳 Docker (recommended) For full functionality (especially Sonos): ```yaml network_mode: host ``` Set your public URL: ```env AIRWAVE_PUBLIC_BASE_URL=http://192.168.1.50:8000 ``` For **local files**, mount host directories into the container and set `AIRWAVE_LOCAL_MEDIA_ROOTS` to those in-container paths (see **Configuration** below). --- ## ⚙️ Configuration ```env AIRWAVE_HOST=0.0.0.0 AIRWAVE_PORT=8000 AIRWAVE_PUBLIC_BASE_URL=http://192.168.1.50:8000 AIRWAVE_FFMPEG_PATH=./bin/ffmpeg AIRWAVE_FFPROBE_PATH=./bin/ffprobe AIRWAVE_YT_DLP_PATH=./bin/yt-dlp AIRWAVE_DENO_PATH=./bin/deno # Optional: allow browsing and queuing audio from these directories (server-side paths). # Comma-separated list, or a JSON array string, e.g. ["/music","/data/audio"]. # Leave unset to disable local media. In Docker, bind-mount the host folders and set paths inside the container. AIRWAVE_LOCAL_MEDIA_ROOTS=/path/to/music,/other/library AIRWAVE_MP3_BITRATE=128k AIRWAVE_CHUNK_SIZE=4096 AIRWAVE_STREAM_QUEUE_SIZE=16 AIRWAVE_LOG_LEVEL=info # Optional: SendSpin (browser clients + synchronized playback) AIRWAVE_SENDSPIN_ENABLED=true AIRWAVE_SENDSPIN_PORT=8927 AIRWAVE_SENDSPIN_NAME=Airwave AIRWAVE_SENDSPIN_MDNS_ENABLED=true # Optional: background playlist auto-sync (SyncService). Only playlists with Auto-sync # enabled in the UI are considered each pass. # Target seconds between the *start* of one sync pass and the start of the next (minimum 30). # If a pass takes longer than this, the next pass begins about a second after the long one ends. AIRWAVE_PLAYLIST_SYNC_INTERVAL_SECONDS=3600 # Max playlists to sync at once within a pass (1–10). AIRWAVE_PLAYLIST_SYNC_MAX_CONCURRENT=2 ``` `AIRWAVE_FFMPEG_PATH` and `AIRWAVE_FFPROBE_PATH` are configured independently. Point each one to the executable you want Airwave to use. `AIRWAVE_CHUNK_SIZE` is how many bytes are read from ffmpeg’s stdout per pull into the shared stream (default `4096`). Larger values mean fewer read syscalls; very small values increase overhead and can make occasional stutters more likely. `AIRWAVE_STREAM_QUEUE_SIZE` is the max depth of the in-memory buffer between ffmpeg and connected listeners (default `16`). Raise it if devices such as Sonos underrun the live stream. --- ## 🧱 Tech Stack * FastAPI * Vue 3 * yt-dlp * ffmpeg * SQLite --- ## 🏗 Architecture (simplified) * FastAPI API — HTTP + websocket endpoints, app state wiring * StreamEngine — playback worker & prefetch * FfmpegPipeline — transcoding & ffprobe probing * MediaSourceResolver — local files & direct media URLs * PlaylistService — queue/import orchestration * SyncService — optional background sync for imported playlists (off per playlist until enabled) * SendSpinServerService — synchronized playback (optional mDNS discovery) * SharedMp3Hub — fan-out * SonosService — LAN speaker discovery, grouping, and control * BinariesService — yt-dlp/ffmpeg/ffprobe/deno management * Repository — persistence --- ## 💬 Why Airwave? Because shared music should be: * simple * synced * platform-independent Not: * fragmented * locked-in * out of sync --- ## 🤝 Contributing Ideas, issues, and PRs welcome! 👉 See [CONTRIBUTING.md](./CONTRIBUTING.md) --- ## ⭐ Support If you like Airwave: * ⭐ Star the repo * 🐛 Report bugs * 💡 Suggest features * 📢 Share it --- ## 🧭 Final thought > Airwave isn’t a music player. > It’s a **shared radio for the internet.**