Navidrome

Self-Hosted

Self‑hosted music streaming like Spotify

Active(75)

17.1kstars

0views

Updated Jul 31, 2025

Overview

Discover what makes Navidrome powerful

Navidrome is a self‑hosted, web‑based music streaming server written in **Go** that exposes a modern RESTful API compatible with the Subsonic specification. At its core, it ingests a file‑system based music library, builds lightweight metadata indexes (using `ffprobe` and ID3 tag readers), and serves audio streams on demand. The server can run natively or inside a container, making it ideal for edge devices such as Raspberry Pi or cloud VMs. It is licensed under the GPLv3, encouraging community contributions while maintaining strict open‑source compliance.

Large‑scale library handling

On‑the‑fly transcoding

Multi‑library & ACL support

Subsonic API compatibility

Overview

Navidrome is a self‑hosted, web‑based music streaming server written in Go that exposes a modern RESTful API compatible with the Subsonic specification. At its core, it ingests a file‑system based music library, builds lightweight metadata indexes (using ffprobe and ID3 tag readers), and serves audio streams on demand. The server can run natively or inside a container, making it ideal for edge devices such as Raspberry Pi or cloud VMs. It is licensed under the GPLv3, encouraging community contributions while maintaining strict open‑source compliance.

Key Features

Large‑scale library handling – Benchmarked with ~900 k songs (≈2/3 FLAC, 1/3 MP3) and proven to scale horizontally via stateless API servers behind a load balancer.
On‑the‑fly transcoding – Utilizes ffmpeg for real‑time conversion to user‑selected bitrates, preserving the original files and saving bandwidth.
Multi‑library & ACL support – Users can be scoped to specific libraries (e.g., music vs. audiobooks) with fine‑grained read/write permissions.
Subsonic API compatibility – Enables a wide range of third‑party clients (e.g., Plex, Emby, mobile apps) without custom adapters.
Theme & UI extensibility – The front‑end is a React/Material‑UI single‑page app; themes can be swapped by replacing the public directory or overriding CSS variables.

Technical Stack & Architecture

Layer	Technology
Runtime	Go (1.22+) – compiled binary, minimal dependencies
Web Server	`net/http` + Gorilla Mux for routing; HTTPS support via self‑signed or Let’s Encrypt
Database	SQLite (embedded) for user & library metadata; optional external PostgreSQL/MySQL for larger deployments
Media Indexing	`ffprobe` (FFmpeg) + ID3 tag parsers; background workers monitor file system changes
Transcoding	FFmpeg invoked via Go’s `exec` package; supports MP3, AAC, OGG, FLAC down‑conversion
Front‑end	React (TypeScript) + Material‑UI; served as static assets from the Go binary
Containerization	Official Docker images (alpine‑based), ready for Kubernetes or Docker Compose

The architecture follows a service‑declarative model: the Go binary runs as a single stateless service, persisting only configuration and SQLite metadata. This design enables horizontal scaling by running multiple replicas behind a reverse proxy, with the file system mounted as a shared volume or accessed via NFS/SMB.

Core Capabilities & APIs

RESTful endpoints for CRUD operations on users, libraries, and playlists.
WebSocket support for real‑time notifications (e.g., new song added).
OAuth2/OpenID Connect integration for external authentication providers.
Webhook hooks to trigger CI/CD pipelines or external scripts on events like songUploaded or userCreated.
CLI tooling (navidrome-cli) for automation and scripting of library scans, user creation, or metadata updates.

Deployment & Infrastructure

Navidrome is lightweight (≈20 MB binary) and can run on ARM or x86 architectures. Recommended hosting scenarios:

Edge devices: Raspberry Pi, NAS units – benefits from low memory footprint and local network streaming.
Cloud VMs: AWS EC2, DigitalOcean Droplets – scale by adding replicas; use external databases for persistence.
Container orchestration: Helm chart available for Kubernetes, with ConfigMap support for environment variables and secrets.

The service exposes a single HTTP port (default 4533) which can be TLS‑terminated at the edge or internally via certmagic. Persistent storage is handled through Docker volumes or mounted network shares.

Integration & Extensibility

Developers can extend Navidrome in several ways:

Plugins: The server exposes a plugin interface (Go plugins compiled as .so), allowing custom authentication backends or metadata enrichers.
Custom themes: Replace the static assets folder or override CSS variables; community themes are available on GitHub.
API clients: The Subsonic API is fully documented; libraries exist in multiple languages (Python, JavaScript, Kotlin) for rapid integration.
Webhook consumers: External services can subscribe to events via HTTP callbacks, enabling integrations with home‑automation or media management tools.

Developer Experience

The project follows a clear contribution workflow: pull requests are gated by automated tests, linting, and static analysis. Documentation is split into user and developer sections; the latter covers backend architecture, API reference, and plugin development. The active Discord community offers real‑time support, while the subreddit provides a forum for feature requests and troubleshooting. Continuous integration ensures that every commit is tested against multiple Go versions.

Use Cases

Home Media Server – A single user or family managing a large music collection, accessible from any device via the web UI or Subsonic clients.
Enterprise Audio Library – Multiple departments (HR, Marketing) maintain separate libraries with ACLs; the API can be consumed by internal dashboards.
IoT Audio Gateway – Running on a Raspberry Pi to stream music over a local network, with on‑the‑fly transcoding for low‑bandwidth devices. 4