mStream

mStream is a self‑hosted music streaming server built primarily with Node.js that delivers high‑fidelity audio (FLAC, MP3, Opus, etc.) to browsers and native mobile clients. It is designed for low resource consumption while supporting multi‑terabyte libraries, making it suitable for home NAS devices, Raspberry Pi setups, and cloud deployments. The architecture centers around an in‑memory database (LokiJS) for rapid metadata lookup and a lightweight HTTP/REST API that powers the web UI, mobile apps, and third‑party integrations.

Technical Stack

• Runtime: Node.js (v10+) – event‑driven, single‑threaded architecture that leverages asynchronous I/O for streaming.
• Database: LokiJS – a pure JavaScript, in‑memory data store with optional persistence; it stores song metadata and user playlists.
• Media Parsing: music-metadata – robust parser for ID3, FLAC tags, and more, ensuring accurate album art and tag retrieval.
• Visualization: Butterchurn – a JavaScript clone of Milkdrop, providing real‑time visual effects directly in the browser.
• Containerization: Official Docker image on LinuxServer.io, enabling quick deployment via docker run or Compose.
• Cross‑platform: Compiled binaries for Windows, macOS, Linux, and FreeBSD; ARM support via prebuilt images.

Core Capabilities

• Gapless Playback: Seamless transition between tracks using Web Audio API and pre‑buffering.
• Playlist Management: REST endpoints to create, update, delete, and share playlists; supports drag‑and‑drop uploads.
• Webhooks & API: Exposes a simple JSON‑based API for external services (e.g., Home Assistant, media bots). Custom endpoints can be added via middleware hooks.
• Metadata Caching: Indexes all supported formats on startup; incremental rescans are available through the UI.
• Streaming: Uses HTTP Range requests to allow seekable streaming; supports both progressive and chunked transfer.

Deployment & Infrastructure

• Self‑hosting: A single Docker container or binary runs on any modern OS; no database server required beyond LokiJS.
• Scalability: While designed for single‑user use, the stateless API and in‑memory database allow horizontal scaling with a shared storage backend (e.g., NFS) if needed.
• Resource Footprint: Typically < 200 MB RAM, ~0.5 CPU core on a Raspberry Pi; performance scales linearly with the number of concurrent streams.
• Backup: LokiJS persistence files can be snapshot‑copied; media libraries are stored on external volumes, simplifying backups.

Integration & Extensibility

• Plugin System: Developers can extend mStream by adding Express middleware or custom WebSocket handlers; the codebase is modular and heavily documented.
• Webhooks: External services can subscribe to events (track play, playlist change) via configurable webhook URLs.
• OAuth & SSO: Optional authentication layers can be integrated; the API accepts bearer tokens for secure access.
• Custom UI: The front‑end is built with vanilla JavaScript and CSS; developers may replace it with React/Vue without breaking the API.

Developer Experience

• Documentation: Comprehensive README, installation guides (Docker, binaries, source), and API reference are available on GitHub.
• Community: Active Discord channel for support; contributors welcome through pull requests and issue tracking.
• Licensing: MIT‑licensed, allowing commercial use without attribution requirements.
• Testing: Unit tests cover core modules; continuous integration ensures stability across Node.js versions.

Use Cases

• Home Media Server: Stream a personal library to any device, with offline sync for mobile apps.
• Artist Distribution: Small labels can host their catalog privately, offering direct streaming to fans without third‑party fees.
• IoT Integration: Embed mStream in a smart speaker or home automation system; the lightweight API fits constrained devices.
• Educational Labs: Students learning about media servers can experiment with real‑time streaming, metadata parsing, and WebSocket communication.

Advantages

• Performance: In‑memory LokiJS database eliminates disk I/O bottlenecks, enabling sub‑second metadata lookup.
• Flexibility: Full source control and a simple API allow developers to tailor the server for niche workflows.
• Privacy & Control: No external tracking; all data stays on the host machine.
• Cross‑Platform & ARM: Runs on mainstream OSes and low‑power hardware, lowering the barrier to entry.

mStream offers a lightweight yet feature‑rich foundation for developers who need a private, high‑quality music streaming solution without the overhead of heavyweight media servers.