Koel — Self-Hosted Music Streaming Server

Introduction

Koel is a personal music streaming server built with Laravel on the back end and Vue.js on the front end. It lets you upload or point to your own music library and stream it from any web browser, giving you full control over your media without relying on third-party services.

What Koel Does

• Streams your personal music library through a responsive web interface
• Scans local directories to index MP3, FLAC, OGG, and other audio formats
• Supports playlist creation, smart playlists based on rules, and favorites
• Provides streaming via the S3-compatible storage or local filesystem
• Offers a built-in equalizer, lyrics display, and last.fm scrobbling integration

Architecture Overview

Koel follows a standard Laravel MVC architecture with a Vue.js single-page application front end. The server indexes music metadata from the filesystem or cloud storage into a MySQL or PostgreSQL database. Audio files are served directly via HTTP streaming. The front end communicates with the back end through a RESTful JSON API, and real-time features use Laravel broadcasting.

Self-Hosting & Configuration

• Requires PHP 8.1+, a database (MySQL/MariaDB/PostgreSQL/SQLite), and a web server (Nginx or Apache)
• Run php artisan koel:init to set up database, create admin account, and configure storage
• Set MEDIA_PATH in .env to point to your music directory
• Optional: configure S3 or S3-compatible storage for cloud-hosted libraries
• Supports Docker deployment via the official koel/docker image

Key Features

• Clean, responsive web UI that works on desktop and mobile browsers
• Smart playlists with rule-based filters (genre, artist, play count, etc.)
• Built-in music download and transcoding support
• Last.fm scrobbling and artist/album artwork fetching
• RESTful API for third-party integrations and mobile clients

Comparison with Similar Tools

• Navidrome — Subsonic-compatible, lower resource usage, but fewer UI features
• Funkwhale — Federated and social, but heavier to deploy
• Jellyfin — Broader media support (video, photos), but music UI is less focused
• Plex — Polished experience with mobile apps, but proprietary and cloud-dependent
• Airsonic — Java-based Subsonic fork, mature but less actively maintained

FAQ

Q: What audio formats does Koel support? A: Koel supports any format your browser can decode natively, including MP3, FLAC, OGG, AAC, and WAV. Server-side transcoding is available for unsupported formats.

Q: Can I use Koel on mobile devices? A: Yes. The web UI is fully responsive. There are also third-party Subsonic-compatible apps that work with Koel via its Subsonic API compatibility layer.

Q: Does Koel support multi-user access? A: Yes. You can create multiple user accounts, each with their own playlists and preferences, managed through the admin panel.

Q: How does Koel handle large music libraries? A: Koel indexes metadata into the database during scanning. Libraries with tens of thousands of tracks work well. For very large collections, use a dedicated database server and queue-based scanning.

Sources

• https://github.com/koel/koel
• https://docs.koel.dev