🚀 Airwave

Self-hosted shared radio — everyone listens in sync

🎧 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

docker run -d -p 8000:8000 ghcr.io/76696265636f646572/airwave

Open → 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):

network_mode: host

Set your public URL:

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

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

⭐ 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.