Feishin: A Self-Hosted Music Player That Speaks Three Server APIs

What Feishin Actually Solves

Self-hosted music servers usually ship with a web interface that works, but feels like an afterthought. Feishin is a dedicated client that replaces that interface with a modern desktop app. It targets people who run Navidrome, Jellyfin, or any OpenSubsonic-compatible server and want a consistent player across those backends. The README positions it as a rewrite of Sonixd, so it inherits a focus on playback quality and UI polish rather than server administration. If you manage a music server and find its default UI lacking, Feishin gives you a separate front end without touching the server itself.

The MPV Backend Is the Core Difference

Feishin offers two player backends: MPV and a web player. The desktop client supports both; the web version only supports the web player. MPV is a significant choice because it handles a wider range of audio codecs and output modes than a browser-based player. The README instructs users to point Feishin at their MPV binary on first startup. That step is a real dependency: if you do not have MPV installed, you must download it or install it via a package manager. This design gives Feishin a tangible advantage for audiophiles who need gapless playback or exotic formats, but it also adds a setup hurdle that a pure web player would avoid.

Three APIs, One Client: The Compatibility Promise

Feishin does not talk to servers directly; it speaks their APIs. The README lists Navidrome, Jellyfin, and OpenSubsonic as supported server types. The Docker Compose example shows a SERVER_TYPE environment variable that accepts jellyfin, navidrome, or subsonic, case insensitive. That breadth is the project's main selling point. You can switch servers without switching clients. However, the feature list reveals a bias: the smart playlist editor is marked as Navidrome-only. Jellyfin and Subsonic users get the core playback and scrobbling, but not that editor. So the compatibility is real, but not uniform. Each API has its own quirks, and Feishin's feature set reflects where the developer has spent time.

Getting It Running: Desktop, Docker, and Environment Variables

The recommended path is the desktop client, downloadable from the releases page. Linux users have two extra options: a Flathub package or an AppImage installer script. The script takes a target directory and can also enable experimental native Wayland mode. For example: curl 'https://raw.githubusercontent.com/jeffvli/feishin/refs/heads/development/install-feishin-appimage' | sh -s -- /your/app/dir. The same script supports a remove argument for uninstallation. Docker users can run the container with docker run --name feishin -p 9180:9180 ghcr.io/jeffvli/feishin:latest. The web version is hosted at feishin.vercel.app, but it only uses the web player backend. Configuration relies heavily on environment variables: SERVER_NAME, SERVER_TYPE, SERVER_URL, and SERVER_LOCK to hard-code a server and lock it. REMOTE_URL handles split-horizon setups where the public URL differs from the internal one. PUBLIC_PATH lets you host under a subpath. These variables make Feishin scriptable, which is useful for kiosk or shared setups.

Configuration Details That Matter

First startup asks for the MPV binary path. After restart, you add a server through the Manage servers menu. The README stresses entering the full URL including protocol and port. For Navidrome, it recommends enabling "Save password" and raising SessionTimeout to 72 hours to avoid repeated logins. Linux users must choose a password store: libsecret is the default, but kwallet4/5/6 are supported and must be set explicitly in Settings > Window > Passwords/secret store. This is a practical detail that can trip up KDE users. The README also mentions an ANALYTICS_DISABLED=true variable to turn off Umami tracking in the Docker and web versions. That is a privacy control worth noting, though the desktop client's tracking behavior is not described.

Limitations and Wrong-Use Cases

The most obvious limitation is the web client's lack of MPV support. If you only use the hosted web version, you lose the backend that makes Feishin distinctive. The smart playlist editor is Navidrome-only, so Jellyfin or Subsonic users miss that feature. The README does not mention offline playback, gapless playback, or multi-room sync. If those matter to you, Feishin may not be the right tool. Also, the Wayland mode is explicitly experimental in Electron and "not officially supported," so Linux users on Wayland should expect possible instability. Finally, the project is GPL-3.0, which means any modified distribution must also be GPL-3.0. That is fine for personal use, but a consideration if you plan to embed or redistribute it.

Alternatives and How They Differ

The obvious alternative is the built-in web UI of your server, which has zero setup but often lacks desktop integration. Another is Sonixd, the project Feishin rewrites. Sonixd is also by jeffvli and supports similar backends, but Feishin is the newer codebase with a modern UI and MPV backend. A more distinct alternative is Jellyfin's own desktop client, which is tightly integrated with Jellyfin but does not work with Navidrome or Subsonic. If you run a single server, that client might be simpler. But Feishin's value is consolidation: one client for multiple server types. The trade-off is that it does not go as deep into any single server's features as a first-party client would.

Maintenance and Upgrade Considerations

The repository shows active development, with releases v1.15.1, v1.15.0, and v1.14.0 within a short span in July 2026. The default branch is development, which suggests a rolling release model. That means fixes and features arrive frequently, but it also means you should pin a specific version in production rather than tracking latest. The Docker image is tagged latest, so you need to manage updates manually. The README does not document a migration path for config between versions, so upgrades may require re-entering settings. The GPL-3.0 license is permissive for personal use but imposes obligations if you distribute modified binaries. Check the release notes for each version to see if any breaking changes affect your server API compatibility.

Editorial conclusion

Adopt Feishin if you run Navidrome, Jellyfin, or an OpenSubsonic server and want a single desktop client with MPV playback and lyrics. Skip it if you need deep Jellyfin features like collections or user-specific views, or if you prefer a purely web-based player without Electron. Before adopting, verify your server's API version, test the MPV path on your OS, and confirm the smart playlist editor works with your Navidrome version. Also check the GPL-3.0 license if you plan to redistribute modified builds.

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes