Koel

What Koel does

Koel scans a music collection and serves it through a browser player designed to feel like a commercial streaming app. The interface includes themes, an equalizer, visualizers and crossfade, and playback can be synced and remote-controlled across devices. Smart playlists, podcasts and internet radio sit next to the music library, and Koel pulls artist and album information from Last.fm, Spotify, MusicBrainz, Wikipedia and YouTube.

Koel also implements the OpenSubsonic API, so third-party apps such as Feishin, Amperfy, Symfonium, Tempo, substreamer and play:Sub can stream from it. Each user signs in to those apps with their email and a dedicated API key rather than the account password. The documentation lists what the Subsonic layer does not cover: sharing, bookmarks, chat and play-queue sync. The developer also publishes Koel Player, an official mobile app for iOS and Android.

Community edition and Koel Plus

Koel is open core. The repository is MIT-licensed, and the Community edition supports several users with Admin, Manager, User and Guest roles, but all users share one library (playlists, favorites and statistics stay private). Koel Plus, bought once per installation with future updates included, unlocks:

• private libraries per user, with sharing and collaboration
• music stored in S3-compatible storage, Dropbox, SFTP or WebDAV
• single sign-on and proxy authentication
• a folder-based media browser
• white labeling and custom themes
• an AI assistant that takes natural-language commands, and a Ticketmaster integration

The Plus code is in the public repository and checks for an activated license key before enabling these features, so the source is open but the features are paid.

Self-hosting Koel

Koel needs PHP 8.2 or later with the required extensions, and a database supported by Laravel; MySQL, MariaDB, PostgreSQL and SQLite are tested. There are five ways to install it: a standalone binary based on FrankenPHP that needs no Composer or Node.js and includes Caddy with automatic HTTPS, a pre-compiled archive, a source build (with Composer, Node.js 20 or later and pnpm), the official Docker image, or a community Railway template. Outside the standalone binary, a web server such as Apache, nginx or Caddy must point at the public/ directory.

FFmpeg transcodes lossless files to AAC at a configurable bitrate. FLAC is passed through by default because modern browsers support it, while formats such as AIFF and APE are always transcoded. The documentation asks you to back up the database before every upgrade, and password reset emails need a configured mailer.

Hosted version

There is no hosted Koel service. A public demo is available on koel.dev.

Limitations

The shared library in the Community edition makes Koel less suited to households where each person keeps their own music, unless you pay for Plus. Folder browsing and cloud storage are also Plus features. The Subsonic API is incomplete for clients that rely on sharing, bookmarks or queue sync.

Who it suits

Koel suits individuals and families who listen mostly in the browser and want a player that looks and feels like Spotify, with a permissive license. Organizations that want separate libraries, SSO and branding can buy Plus. For a fully free multi-library server, compare Navidrome.