omniMux

A self-hosted music server that lets you search YouTube, cache tracks to your library, and stream everything through a Spotify-like PWA. Built on top of Navidrome with a FastAPI middleware layer and a SvelteKit frontend.

Your music. Your server. No middlemen.

Live demo → omnimux.wwel.sh (guest access, read-only library)

Table of contents

• Why omniMux?
• Features
• Stack
• Quick start
• Configuration
• FAQ
• Project structure
• License

Why omniMux?

Streaming services rent you access to music you'll never own, lock your library behind monthly fees, and vanish the moment licensing deals fall through. omniMux flips that: search YouTube, keep the files on your own hardware, and stream them from anywhere over a PWA you install once. No cloud. No subscription. No gatekeepers. Just your music, on your server.

Features

🎧 AutoDJ Beat-locked crossfades, tempo matching, and realistic pitch/speed slop — plus 10+ music visualizers driven by high-res iTunes album art.	🔎 YouTube Search Find any track and cache it locally. Topic channel results rank first for clean, official-quality audio.	💿 Album Detection Open any album and see missing tracks found on YouTube — one-click import fills the gaps.
🎤 Artist Pages Browse an artist's local albums alongside their full YouTube discography in one unified view.	📋 Playlist Import Paste a YouTube playlist URL — omniMux queues all tracks and builds a matching Navidrome playlist automatically.	🧠 Mood Analysis Every download is analysed for mood, BPM, energy, and key via mood-detector.
📱 PWA Installable on desktop and mobile with a responsive mobile mini-player. Works offline once tracks are cached.	⚡ Instant Search Server-side cache (1 h for tracks, 2 h for albums) makes repeated YouTube searches feel instant.	🔁 Shuffle & Loop Shuffle the queue, loop all, or loop one — the basics, done right.

Stack

Layer	Tech
Music server	Navidrome (Subsonic API)
API	Python · FastAPI · yt-dlp · ytmusicapi · mutagen
Frontend	SvelteKit 5 · TypeScript
Audio analysis	mood-detector
Infrastructure	Docker Compose

Quick start

Prerequisites: Docker and Docker Compose.

git clone https://github.com/usr-wwelsh/omnimux.git
cd omniMux

Edit docker-compose.yml and set a real value for JWT_SECRET, then:

docker compose up -d

Service	URL
Web app	http://localhost:8801
API	http://localhost:8800
Navidrome	http://localhost:4533

On first run, open Navidrome at :4533, create an admin account, then log into the omniMux web app with those same credentials.

Configuration

All configuration is via environment variables in docker-compose.yml:

Variable	Default	Description
NAVIDROME_URL	http://navidrome:4533	Internal URL of the Navidrome service
MUSIC_DIR	/music	Where downloaded audio files are stored
DATA_DIR	/data	Where the SQLite database is stored
JWT_SECRET	change-me-in-production	Secret used to sign auth tokens — change this

FAQ

Why the heck an AutoDJ? Real DJs are great — but who doesn't want a personal robot DJ running on their own hardware? AutoDJ analyses every track for BPM, key, mood, and energy using deterministic DSP (no AI, no cloud), then crossfades between them with beat-locked transitions. It's just math, and it slaps.

Why YouTube? It's the largest music catalogue on the planet and the only one without a paywall. Topic channels are officially uploaded by labels and provide near-CD-quality audio for most releases.

Can I use my existing music library? Yes — drop your files into the MUSIC_DIR volume and Navidrome will scan them. omniMux treats YouTube as an augmentation to your library, not a replacement.

Does it work on iOS? Yes, via the PWA. Safari → Share → Add to Home Screen. Requires HTTPS, so expose it through a reverse proxy or a Cloudflare Tunnel.

Why not just use Spotify? Because you don't own anything on Spotify. The day they drop a track, raise prices, or go under, your library is gone. omniMux tracks live as files on your disk.

Project structure

music-server/
├── api/                  # FastAPI backend
│   ├── routers/          # auth, search, download endpoints
│   ├── services/         # youtube, navidrome, download worker, cache
│   └── db/               # SQLAlchemy models + async SQLite
├── web/                  # SvelteKit PWA
│   └── src/
│       ├── routes/       # pages (search, library, artist, album, playlists, browse)
│       ├── components/   # Player, MiniPlayer, AlbumCard, TrackList, …
│       └── lib/          # subsonic.ts, api.ts, player store
└── docker-compose.yml

License

MIT © usr-wwelsh