Koel Player: the native mobile app for a self-hosted music server

A native client because the web version has limits

Koel Player is the mobile app for Koel, and the README states the reason for it in one line: it provides a complete mobile app experience and does not have the limitations of the mobile web version. Supports both iOS and Android.

That framing matters because it says what the project is not. Koel Player is not a server, it is a client for one, and it does not try to be a general purpose music player. The value it offers is entirely in the delta between a mobile browser tab and a real application: the platform integrations, the offline behaviour, the way a native app handles background playback, the media session that lets the phone show the track on a lock screen, and the fact that the app talks to your own instance rather than to a hosted service.

The project is MIT licensed, and the homepage is koel.dev with the documentation for the wider system at docs.koel.dev, which is where the mobile support and limitation page the README links to lives. The distinction between the app and the server is visible in the repository names, with the server living in the `koel/koel` organisation repository and the client in `koel/player`.

The distribution is through the two app stores, with an App Store listing under the identifier 1576886982 and a Google Play listing under the package name `phanan.koel.app`. The README also notes that you can, of course, build the project and install the app on your own, which matters for anyone self-hosting who would rather not depend on a store.

A badge for unit tests points at a `unit.yml` workflow, so the app has continuous test coverage on every change rather than relying on manual testing before a release.

Flutter and Dart, and what that means for the platform folders

Koel Player is built on Flutter and Dart, and the repository layout is the direct consequence of that choice.

The top level has `android/`, `ios/`, `linux/` and `macos/` directories. The first two are the mobile targets, and the presence of `linux/` and `macos/` is the interesting part: a Flutter project generates host folders for every platform you enable, and shipping a Linux and macOS host alongside the two mobile ones means the same codebase is being prepared to build on desktop as well. Whether those desktop builds are distributed is not something the README says, so the safe reading is that the project is set up to build for them rather than that it publishes desktop artefacts.

The `lib/` directory holds the Dart source and `assets/` the bundled resources, with a separate `metadata/` directory that is likely store listing files rather than application code, since the README links a project banner made of app store screenshots. `test/` is the unit test directory the workflow badge refers to.

The Flutter project metadata is all present and current in style. There is a `.flutter` directory and a `.metadata` file, which are the two files Flutter itself writes to record the SDK it generated the project with, and a `pubspec.lock` alongside a `pubspec.yaml`. A committed lock file is what makes a build reproducible, so the CI workflow and any local build use the same dependency versions.

For contributors, the tooling is standard Flutter. There is an `analysis_options.yaml`, which is the Dart analyser configuration, and a `.github/` directory holding the unit test workflow. The README points newcomers to the Flutter resources, a lab for writing a first Flutter app and a cookbook of useful samples, plus the online documentation with tutorials, samples and the API reference.

There is also a `CLAUDE.md` at the root and a `.gitmodules` file, so part of the project is composed of submodules that have to be initialised before the project will build.

Releases stopped in 2021, the repository did not

The release history and the commit history tell different stories, and the gap between them is the thing to understand before you rely on this app.

The listed releases are v1.1.0 from 2021-09-26, v1.0.1 from 2021-08-08 and v1.0.0 from 2021-08-08. Three releases, the first of them on the same day as the second, and then nothing tagged for the better part of five years.

The last push to the repository was on 2026-08-22, which is recent. So the code is being worked on, or at least the repository is being maintained, while the versioned artefacts have not moved since 2021.

There is a plausible reading of that, and it is visible in the store identifiers. The Google Play package name is `phanan.koel.app`, a different naming scheme from the project name, and the App Store identifier is a bare numeric id. Both suggest the published app is distributed under a separate identity from the repository, and that the current published build may be produced by a pipeline outside this repository rather than by a release tag here.

Whatever the arrangement, the practical consequence for a user is the same. If you install Koel Player from the App Store or Google Play, you are running a build that was released years ago, and the question to ask is whether that build still speaks the protocol your Koel server expects. The README points at the mobile support and limitation documentation, which is where the current guidance on what the app does and does not do lives.

The repository itself is MIT licensed, and there is a `hacktoberfest` topic tag alongside flutter, dart, android, ios, mobile and music, which is a hint that the project takes outside contributions, particularly around the yearly Hacktoberfest period, when a lot of first-time contributors pick small open projects.

What a self-hosted music client has to solve that a streaming app does not

The interesting engineering question in this project is not the player but the server relationship, and it is worth spelling out because it shapes every design decision in the client.

Koel is your own server. That means the address of the library can change, the network it sits on can change, and the version of the server can be a version the app was never tested against. It also means the credentials are the user's own, stored on the user's own phone, and the app has no account system of its own to fall back on.

The most visible consequence of that is the reason the app exists at all. A mobile web version has the limitations a mobile web version has: browser media restrictions, awkward background playback, and a screen that is a web page pretending to be an app. The README's claim is that the native app does not have those limitations, and the pieces of a Flutter mobile app that address them are the ones a web page cannot reach, particularly the media session and the background audio session.

The second consequence is failure handling. A streaming app that cannot reach its service shows a spinner and moves on. A self-hosted client that cannot reach the server has to distinguish between the server being down, the network being down, the address being wrong and the credentials being wrong, and the user is the only one who can fix any of those. That is the work that sits behind a screen the README does not describe.

The third is that the data model is the server's. A Koel server exposes its library over an API, and the client renders whatever that API returns, which means new server features do not automatically appear in an app that has not been updated, and old app builds may not understand new API responses. This is the maintenance tension behind the release gap.

None of this is criticism of the project, which has been in the position of being the official app for a self-hosted service for years. It is the reason the readme points at documentation rather than describing features, and the reason the app store build, not the repository, is what most users will ever run.

What the app is not, and how the maintenance signals read

It is worth being precise about the boundary, because a self-hosted music client can easily be mistaken for a music service.

Koel Player holds no library of its own. The library is on the server you run, and the app is a way of reaching it from a phone. There is no account to create, no subscription and no catalogue, and the project description says it plainly, the official mobile app for Koel.

That boundary also decides what the app cannot do. It cannot work without a reachable Koel instance, it cannot share a listening session with a browser session in any way the documentation describes, and it cannot stream from anywhere else.

The maintenance signals, read together, tell a coherent story. There is a unit test workflow, so changes are checked. There is a `CLAUDE.md` at the root and a `.gitmodules` file, so there is tooling for working with the repository and for composing in external pieces. And there is a `hacktoberfest` tag, which in practice means the project has a habit of receiving contributions from people who have never contributed before, which brings a particular kind of maintenance burden that a mature project does not have.

The last push on 2026-08-22 against a last release in September 2021 is consistent with a project that is still in use and still worth touching, but whose release process no longer runs through this repository's tags. For a user, that means the app store build is the thing to look at, and the repository is where you go if you want to build it yourself, which the README explicitly invites.

Editorial conclusion

Adopt Koel Player if you run a Koel server and want a native iOS or Android client rather than the web version, since that is the reason the app exists and the stated motivation for it. Do not expect an actively released project, because the newest tagged version is v1.1.0 from 2021 even though the repository is still being pushed to, and check first whether the app store build matches what the current server version expects, since an app that has not been released in years is being kept alive by a different route than new versions.

Frequently asked questions

Official sources

1. Issues
2. koel/player on GitHub
3. Project website
4. README
5. Releases