mStream Music

May 12, 2026 · View on GitHub

The music server that's also a file manager. Drop a file in your folder, upload one through the web UI, or paste a YouTube link — it plays. No accounts to set up, no scan to wait for.

MainSharedAdmin
mainsharedadmin

Check Out The Demo!

Discord Channel

Website

Why mStream?

Most self-hosted music servers — Navidrome, Jellyfin, Plex, Airsonic — scan your files into a database and show you their version of your library: virtual albums, hidden paths, files invisible until the next index run. Useful, but it means giving up the folder structure you built.

mStream's native API takes the opposite approach. The file browser is the music browser. The /media/<library>/ route streams files directly from disk via express.static — no per-request database lookup. Add a file to a watched folder and it's available immediately, on the next page refresh. The same web UI lets you upload, mkdir, rename, and download from YouTube — no SFTP or Docker volume gymnastics required.

mStreamNavidrome / Jellyfin / Plex
User account required to startOptional (public mode)Required
Upload via web UIYes (file explorer)No (Funkwhale has it)
YouTube → libraryYes (yt-dlp wrapper)No
New file appears in browserImmediatelyAfter scan
Folder hierarchy preservedYesHidden behind virtual library
First-party desktop appsServer + PlayerPlex yes; FOSS servers no
Open sourceYes (GPL-3.0)Plex no, others yes

Public mode is the "trusted local network" config: no user accounts required, every client gets full library access. It's the fastest path from git clone to playing music — point mStream at a folder, run it, browse, play. Add real users when you actually need them. For wider exposure, the admin API exposes lockAdmin to disable all writes server-wide, plus independent noUpload / noMkdir / noFileModify toggles for granular control.

Polished on both ends. mStream ships as two distinct desktop apps: mStream Server, a tray-resident server with auto-update and boot-on-startup, and mStream Desktop Player, a native window for the web UI on machines where you'd rather not have a browser tab open. For headless deployment, the official LinuxServer.io Docker image and npm install from source are first-class alternatives.

The Subsonic API caveat: third-party Subsonic clients (DSub, Symfonium, Substreamer) require the index to be populated for metadata-driven features — that's a Subsonic protocol limitation, not an mStream limitation. The "drop and play" experience is in the native UI; Subsonic clients still need a scan first.

Server Features

  • Folder-faithful library — files stream from /media/<library>/ via express.static; no per-request database lookup, no scan required to play
  • Manage music from the music server — upload, mkdir, rename via the file explorer; download from YouTube via yt-dlp integration. The web UI doubles as a file manager
  • Public mode — run with no user accounts on a trusted network; configure libraries and start streaming in one command
  • Granular write permissions — lockAdmin panic-button plus independent noUpload / noMkdir / noFileModify toggles. Tune live from the admin UI
  • Server runs as a desktop app — Windows (NSIS) / macOS (DMG) / Linux (AppImage) installers with system tray, auto-update, boot-on-startup. Or use the official LSIO Docker image for headless deployment
  • mStream Desktop Player — the mStream UI delivered as a native desktop app on Windows / macOS / Linux instead of a browser tab. Requires a running mStream server (local or remote)
  • Subsonic / OpenSubsonic API — works with DSub, play:Sub, Symfonium, Feishin, Supersonic, and other Subsonic clients
  • Full-text search — SQLite FTS5 with BM25 ranking and unicode diacritic folding (e.g. ros matches Sigur Rós). Surfaced through both the webapp search panel and Subsonic search3. A per-request algorithm param on /api/v1/db/search exposes a basic LIKE escape hatch for queries that need infix matching
  • Auto-DJ with BPM continuity, harmonic mixing, and similar-artists — POST /api/v1/db/random-songs accepts BPM windows (including octave-equivalent half/double tempo), Camelot key codes (1A..12B, expanded to every spelling the DB might contain), and library-resolved similar-artist names from GET /api/v1/lastfm/similar-artists. A multi-step fallback waterfall progressively relaxes constraints until at least one track matches, with a tier filter that prefers in-range picks over unknown-tag picks over known-wrong picks. The scanner extracts BPM/key from TBPM/TKEY (ID3v2) and BPM/KEY/INITIALKEY (Vorbis) tags at scan time
  • Multi-user accounts with per-library access control (when you need them)
  • DLNA / UPnP for casting to TVs and stereos
  • On-the-fly transcoding via ffmpeg (opus, mp3, aac)
  • Server-side audio playback for headless boxes (Rust audio engine + CLI fallback)
  • Multi-threaded Rust scanner — file-level parallelism via rayon, cgroup-aware thread sizing (Docker / k8s CPU quotas honored), backpressured pipeline. Generates 800-bar waveform previews during scan. JS fallback for max compatibility
  • Cross platform — Windows, OSX, Linux, FreeBSD, ARM
  • Light on memory and CPU, tested on multi-terabyte libraries

WebApp Features

  • Gapless Playback
  • Milkdrop Visualizer (Butterchurn)
  • Playlist Sharing via signed links
  • Upload, create, and rename files through the file explorer
  • Synced + plain lyrics (embedded, sidecar .lrc, or LRCLib — opt-in)
  • Waveform previews rendered at scan time
  • Album art auto-fetch from MusicBrainz, iTunes, and Deezer
  • Admin UI for server configuration

Installing mStream

Mobile Apps

mStream iOS App

mStream Android App

Made by Niera Tech

Quick Install from CLI

Deploying an mStream server is simple.

# Install From Git
git clone https://github.com/IrosTheBeggar/mStream.git

cd mStream

# Install dependencies and run
npm run-script wizard

Technical Details

  • Dependencies: NodeJS v22.5 or greater
  • Database: SQLite (via node:sqlite) — no external DB server required
  • Scanner: Pre-built Rust binary (Linux x64/arm/arm64 + musl, macOS x64/arm64, Windows x64); falls back to a pure-JS scanner when no binary matches the host
  • Supported File Formats: flac, mp3, wav, ogg, opus, aac, m4a, m4b
  • APIs: mStream /api/v1 (REST, OpenAPI spec) and Subsonic /rest (1.16.1 + OpenSubsonic extensions)

Credits

mStream is built on top of some great open-source libraries:

  • music-metadata - The metadata parser used by the JS scanner fallback
  • Lofty - Audio tag reader powering the Rust scanner
  • Symphonia - Pure-Rust audio decoder used to render waveform previews during a scan
  • Butterchurn - A clone of Milkdrop Visualizer written in JavaScript
  • Syncthing - Powers federation between mStream servers
  • LRCLib - Optional source for synced lyrics

And thanks to the LinuxServer.io group for maintaining the Docker image!