Jellium Desktop: an unofficial Jellyfin client built on CEF and mpv

A client for a self-hosted Jellyfin server

Jellium Desktop exists to put a desktop front end on a Jellyfin server. Jellyfin is the open source media system it talks to, and this project is explicitly described as an unofficial client for it, which is worth holding onto as you read the rest: there is no affiliation with the Jellyfin project here, and the code and packaging decisions belong to this repository alone.

The audience is narrow and clearly defined. Someone runs Jellyfin on their own hardware, manages their own library, and wants a desktop application on top of it rather than the web interface in a browser tab. The interesting part is not that the client exists, since clients exist, but the specific combination it picks for rendering and for playback, which is what separates it from other ways of talking to a Jellyfin server.

The primary language is Rust, and the license is GPL-2.0, so if you plan to redistribute a modified build you have to work inside the GPL-2.0 terms. The repository root shows a `src/` directory holding a Cargo workspace, a `justfile` for task automation, `dev/` directories split per platform, `resources/`, and a `third_party/` tree.

CEF for the window, mpv for the picture

The architecture is two well-known pieces combined. The user interface runs in CEF, the Chromium Embedded Framework, which means the interface is a web document rendered in an embedded browser rather than a native widget toolkit. The video path is mpv, a command line media player that jellium embeds and drives instead of writing its own decoding pipeline.

The split explains what you get and what you do not. CEF brings HTML rendering, so the interface can be built the same way the Jellyfin web client is. mpv brings playback, and with it the library of codec and display handling that mpv already has. The tradeoff is that you inherit the size and complexity of an embedded Chromium, and that a second process, mpv, sits in the playback path.

The mpv side is not hidden. The justfile sets `JFN_MPV_INCLUDE_DIR` to `third_party/mpv/include`, and the recipe list includes a `run-mpv` entry described as running the mpv CLI, so the same binary is usable from the command line during development. The project also ships a `.gitmodules` file, which is consistent with a vendored third-party component rather than a pure dependency download.

Building and running through just recipes

Task running is handled by `just`, and the project treats it as the only supported entry point. The recipe list in the README groups the work:

[package]
appimage ...    # [linux] build AppImage
flatpak ...     # [linux] build Flatpak bundle
dmg             # [macos] build Apple Disk Image (.dmg)

The build itself is a Cargo build scoped to the workspace manifest under `src/`, and the test recipe depends on the build recipe running first:

cargo test --manifest-path src/Cargo.toml --workspace

For day to day work, `just run` starts the app and passes any arguments through, while `just run-mpv` starts the mpv CLI instead. Formatting and linting are separate recipes: `just fmt` runs `cargo fmt` over the workspace, `just fmt-check` adds the check flag, and `just clippy` runs clippy across all targets with warnings denied. On Unix the clippy recipe is stricter than a default invocation, adding `-D clippy::unwrap_used`, `-D clippy::expect_used`, and `-D clippy::panic`, so the project treats unchecked unwraps and explicit panics as lint errors in its own source.

The `justfile` also loads a dotenv file and exports `JELLIUM_DESKTOP_LOG_LEVEL` defaulting to `debug` and `JELLIUM_DESKTOP_LOG_FILE` defaulting to `build/run.log`, so a first run writes a debug log into the build directory unless you override those variables.

Nightly build archives and no tagged releases

Distribution is the part that catches new users out. The repository has no GitHub releases at all, and the prebuilt archive links point at nightly.link artifacts for the GitHub Actions workflows, so a URL labelled by workflow name and architecture resolves to the latest successful build of that workflow rather than to a version you can pin.

For Linux there is an AppImage for x86_64 and one for aarch64, a Flatpak bundle that the README explicitly labels as a non-Flathub bundle, and an AUR package named `jellium-desktop-git` for Arch Linux. The `-git` suffix in the AUR package name is the convention for packages that track the repository HEAD rather than a release, and it tells you the same thing the absence of releases does. macOS is covered by an Apple Silicon archive and an Intel archive. Windows is covered by x64 and arm64 archives.

The practical consequence is that you cannot deploy a fixed version without capturing the artifact yourself. If you run this on a fleet of machines, download the archive once, keep it in your own artifact store, and treat the nightly.link URL as the upstream, not as your source of truth. The AUR and Flatpak routes are worth a look too, since a package manager gives you a version string and an update path that a raw workflow link does not.

Platform split and the macOS quarantine step

The build is genuinely per platform, not merely cross-compiled. The justfile imports three separate files, `dev/linux/linux.just`, `dev/macos/macos.just`, and `dev/windows/windows.just`, and the Windows recipes take a different code path. The Windows test recipe sources `dev/windows/env.ps1` first, and the file comment says why: it loads the MSVC plus bindgen libclang environment that Rust needs on that platform before the test command will run. The Windows clippy recipe does the same. Linux and macOS need none of that, their recipes just call Cargo directly.

macOS has its own manual step after installation. The README instructs you to remove the quarantine attribute:

sudo xattr -cr /Applications/Jellium\ Desktop.app

That is a real friction point for anyone handing the app to other people. The command needs administrator rights, and a user who downloads the archive again later will hit the same prompt. The Flatpak bundle and the AUR package are Linux-side routes, so neither helps with this macOS step, and the Flatpak bundle is not on Flathub.

Cleanup recipes exist per platform as well, and the Windows variant uses PowerShell to remove `build` and `dist` before running `cargo clean --manifest-path src/Cargo.toml`.

What jellium does not settle for you

Three limitations are visible in the project itself. First, there is no version history for users. With no GitHub releases, an upgrade is whatever the nightly workflow produced most recently, and there is no changelog to diff against what you are running.

Second, the client is unofficial, and the README offers no compatibility statement about which Jellyfin server versions it tracks. The repository also has no published API documentation and no issue tracker guidance beyond the repository layout, so if a playback feature or a login flow misbehaves, your fallback is the mpv command line rather than another client that speaks the same server.

Third, the app needs two heavyweight pieces of native machinery, an embedded Chromium and a separate media player, and on Windows that means the MSVC and bindgen toolchain setup that the recipes go out of their way to load. Compared with driving mpv directly for local files, jellium adds a network protocol, a web-rendered interface, and a CEF dependency in exchange for library browsing and server sync. If your use case is playing a local file with mpv, jellium is the heavier option. If your use case is a shared library on your own server, it is the right one.

Editorial conclusion

Jellium Desktop suits someone who already runs a Jellyfin server and wants a client with mpv playback and a CEF interface, and who is comfortable tracking a nightly artifact rather than a versioned release. It does not suit users who want an official client, signed installers, or a stable download URL, since the project publishes no GitHub releases and the macOS bundle needs the quarantine attribute cleared by hand. Before installing, check that the nightly.link archive for your architecture matches your machine, and on macOS run the xattr removal shown in the README, otherwise the app will refuse to start.

Frequently asked questions

Official sources

1. andrewrabert/jellium-desktop on GitHub
2. Issues
3. License: GPL-2.0
4. Project website
5. README