Main Features of Jellium-Desktop: A Cross-Platform Jellyfin Client in Rust

Jellium-Desktop is a cross-platform desktop client for Jellyfin that combines a modern Chromium web UI with native mpv video playback, GPU-accelerated overlay rendering, and deep OS-level media integration across Linux, macOS, and Windows.

The andrewrabert/jellium-desktop repository is built in Rust and delivers a native desktop experience for Jellyfin users by embedding the official web interface inside a custom application. Understanding the main features of jellium-desktop shows how it bridges browser-based media server UIs with high-performance hardware decoding and first-class desktop operating system integrations.

Chromium Embedded Framework (CEF) for the Jellyfin Web Interface

At the heart of the user interface is the Chromium Embedded Framework (CEF), which hosts the Jellyfin web client inside a native Chromium browser. In src/jfn_cef/src/lib.rs, the JfnCefLayer structure manages the CEF process and forwards UI events into the Rust backend. Rather than running as a separate window, the CEF view renders as an overlay texture that sits above the video layer, giving users the exact Jellyfin web experience while maintaining native application behavior.

Native Video Playback with mpv Integration

For video and audio rendering, Jellium-Desktop integrates a forked mpv located in third_party/mpv. The project does not rely on libmpv for actual media decoding; instead, the forked player handles hardware-accelerated video output directly. According to the source code in src/playback/src/coordinator.rs, libmpv is reserved for the control plane—specifically property observation, command issuance, and event handling. This split architecture ensures that playback benefits from mpv’s mature decoding pipeline while the Rust codebase retains full control over state and UI coordination.

GPU-Accelerated Overlay Composition

To prevent window-manager flicker and keep the UI crisp during fullscreen video, the application composites the CEF interface over the mpv surface using the GPU. In src/gpu_paint/src/painter.rs, the overlay renderer draws the CEF UI into a GPU texture that is composited directly on top of the video frame. The result is a seamless inset overlay that remains responsive without interfering with native video performance.

Deterministic Playback State Machine

Playback logic is driven by a single-threaded state machine implemented in src/playback/src/state_machine.rs. The machine consumes inputs from any thread, produces a canonical snapshot of the current playback state, and distributes events to registered sinks. This deterministic design eliminates race conditions and guarantees that all UI and system components observe the same state transitions. Developers can extend the pipeline by registering custom event sinks without modifying core logic.

The following Rust example demonstrates how to register a simple logging sink using the PlaybackCoordinator:

use jfn_playback::{PlaybackCoordinator, PlaybackEvent, EventSink};

fn log_sink(ev: &PlaybackEvent) {
    println!("Playback event: {:?} – snapshot: {:?}", ev.kind, ev.snapshot);
}

fn main() {
    let mut coordinator = PlaybackCoordinator::new().expect("Failed to init");
    coordinator.add_event_sink(Box::new(log_sink) as EventSink);
    coordinator.start();
    // … enqueue inputs or let other parts of the app drive playback …
}

System Media Controls and Hotkey Integration

Jellium-Desktop bridges playback events to operating-system media APIs so that hardware media keys, notification controls, and keyboard shortcuts work natively.

OS-Level Media Sinks

The system media-control sinks integrate with Windows SMTC, Linux MPRIS, and macOS MediaSession. These sinks are implemented in platform-specific crates such as src/windows_sink/src/lib.rs, enabling the application to publish now-playing metadata and respond to external play, pause, and seek commands issued by the OS.

Global Hotkey Handling

Cross-platform keyboard input is classified in src/playback/src/hotkey.rs. The module translates key-down events from Linux, macOS, and Windows into canonical playback actions including play/pause, seek, volume adjustment, and fullscreen toggling. Both global shortcuts and UI-focused shortcuts are supported, ensuring consistent control regardless of which window layer currently has focus.

Theme-Color Video Mode Sink

To keep the UI visually synchronized with playback state, src/playback/src/theme_color_sink.rs manages the ThemeColor video mode. When playback terminates, the sink automatically resets the theme video mode handler so that the interface transitions cleanly out of the media context.

The C FFI in src/playback/src/theme_color_sink.rs allows external callers—such as the CEF JavaScript bridge—to register a callback for theme video mode changes:

extern void jfn_playback_set_theme_video_mode_handler(void (*cb)(bool));

static void theme_video_mode(bool enable) {
    // implementation of UI change
}

int main() {
    jfn_playback_set_theme_video_mode_handler(theme_video_mode);
    // … run the client …
}

Cross-Platform Windowing Support

Jellium-Desktop targets Linux, macOS, and Windows through isolated platform crates that handle window-system plumbing. The repository includes src/wayland for Wayland subsurfaces, src/x11 for X11 shared memory, src/macos for Cocoa integration, and src/windows for native Windows services. The Wayland implementation in src/wayland/src/lib.rs demonstrates how the application creates subsurfaces and manages presentation feedback on Linux compositors.

Reproducible Build Workflow with Just

All build, test, and packaging steps are driven by the just task runner via the justfile in the repository root. This ensures a uniform workflow across every supported operating system. The typical development cycle uses three commands:

just deps    # fetch submodules, download CEF, install brew packages (macOS)

just build   # compile the Rust workspace and stage a runnable tree

just run     # launch the client with debug logging

Summary

• CEF-based web UI: Hosts the Jellyfin interface in src/jfn_cef/src/lib.rs and renders it as a GPU overlay above native video.
• Native mpv playback: Leverages a forked mpv for hardware-accelerated decoding while using libmpv strictly for control-plane operations in src/playback/src/coordinator.rs.
• Deterministic state management: A single-threaded state machine in src/playback/src/state_machine.rs produces canonical snapshots and feeds extensible event sinks.
• Deep OS integration: Supports Windows SMTC, Linux MPRIS, macOS MediaSession, global hotkeys, and theme-color sync through dedicated sink crates.
• Cross-platform windowing: Separate Rust crates handle Wayland, X11, macOS Cocoa, and Windows window-system specifics.
• Reproducible builds: The justfile standardizes dependency fetching, compilation, and execution across Linux, macOS, and Windows.

Frequently Asked Questions

What makes Jellium-Desktop different from watching Jellyfin in a browser?

Jellium-Desktop embeds the Jellyfin web UI via CEF while offloading actual video decoding to a forked mpv instance with GPU-backed overlay composition. This design gives users the familiar Jellyfin interface combined with native hardware decoding, fullscreen overlay rendering without flicker, and system-level media key support that standard browsers cannot provide.

How does the playback state machine ensure reliable behavior?

The state machine in src/playback/src/state_machine.rs runs on a single thread and serializes inputs from any thread into a canonical state snapshot. By distributing events to registered sinks from one central loop, the architecture guarantees that UI updates, media-control notifications, and hotkey responses all observe the exact same deterministic state.

Can developers extend Jellium-Desktop with custom playback integrations?

Yes. The sink architecture exposed by PlaybackCoordinator in src/playback/src/coordinator.rs allows developers to register custom EventSink implementations. Because the state machine dispatches events to every registered sink, new functionality—such as Discord Rich Presence or home-automation triggers—can be added without altering the core playback logic.

Which operating systems and Linux display servers are supported?

Jellium-Desktop supports Linux (both Wayland and X11), macOS, and Windows. The codebase contains dedicated platform crates in src/wayland, src/x11, src/macos, and src/windows that manage each windowing environment natively.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}