Jellyfin MPV Shim: a cast target that became a full client
MPV-Based Jellyfin Client with Offline Sync
At a glance
- What is it?
- A Python client that renders its own interface inside MPV rather than embedding a web view, plays media without transcoding, and in version 3 gained an in-player library browser and offline sync.
- Who is it for?
- The technical bet in this project is that drawing the interface into MPV itself, rather than wrapping a web view, keeps you on MPV's own rendering path. That is why HDR, Dolby Vision and custom shaders work, and why the release notes are explicit that nothing redirects or recomposites MPV's video output.
- Can I use it commercially?
- Check first. The repository uses a licence we do not classify automatically, so read its LICENSE file before any commercial use.
- Is it still maintained?
- Yes. The repository last received commits 1 day ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on October 7, 2026, and from our analysis. They are not legal advice.
Editorial analysis
Two descriptions of the same project, and which one is current
The project describes itself twice, in two different places, and the difference is the most interesting thing in the repository metadata.
The repository description calls it an MPV-based Jellyfin client with offline sync. The package metadata on PyPI calls it a way to cast media from Jellyfin mobile and web apps to MPV. Both were accurate at different times, and the release history shows which one describes version 3.
Version 3.0.0, published in September 2026, is titled Library Browser, Offline Sync, and Jellyfin v12 Support. The release notes say the client is reinvented, with a full library browser inside MPV covering videos, books, audiobooks, comics, photos and music, plus offline sync, Live TV and fast user and server switching. It is also the first version to work with a Jellyfin v12 server without legacy authentication enabled.
So if you are evaluating this client, the cast-target framing is the historical one. What you are installing now is a desktop client whose origin was being a cast target, which is also why it still describes itself as running in the background as one.
The README's opening line gives the current summary: a cross-platform Jellyfin client that can run in the background as a cast target or act as a fully-featured desktop client with offline sync support.
Drawing the UI inside MPV rather than beside it
The architectural decision worth understanding before anything else is that this client does not embed a web view. The v3 release notes are explicit that it is done without webviews or heavy copies of Chromium, and that nothing touches MPV's video output either: the client draws into MPV so `gpu-next` works properly, without redirecting or recompositing it. HDR, Dolby Vision and custom shaders all work as a result.
That is a real constraint that pays off. The usual way to build a desktop client for a media server is a web view, which brings a browser engine, its own GPU compositing path and a set of video playback compromises along with it. Avoiding that path means MPV's rendering pipeline stays intact, which matters to anyone using tone mapping or a shader pack.
The dependency list in `pyproject.toml` reflects the same design. It requires Python 3.9 or newer, and depends on python-mpv, the Jellyfin API client library, python-mpv-jsonipc for MPV's JSON IPC with a version floor called out in a comment, and requests. Pillow is a hard requirement rather than an optional extra, with an explanatory comment: the in-player library browser replaced the older Tk one, every tile, the playback HUD and the cast screen are rasterized with Pillow, and logging in goes through that browser. The comment states that without it the application falls back to the command line interface, which is a materially different product.
Features that go beyond playing a file
Direct play through MPV is the baseline, and the README's list is mostly about things other clients do not attempt. SyncPlay lets you watch with friends. Live TV is described in full: a channel guide, channels, recordings, schedule and series rules, including the ability to schedule recordings.
There is a shim mode that runs in the background, and the Jellyfin mobile apps can fully control the client. Display mirroring, described as Chromecast-like, is on by default rather than opt-in. You can trigger shell commands on certain events, and Discord Rich Presence will share your media activity if you want it to.
Two quality-of-life items deserve specific mention because they address the tedium of watching a series. Subtitle and audio preferences persist across episodes, so you are not resetting them every time, and the text-based menu can change subtitles or audio for an entire series at once while showing you the actual track names.
Shader packs and SVP integration are supported, and you can point the client at an external MPV of your choice. Most of the player, and MPV itself, is documented as extensively configurable, with the configuration living in `docs/configuration.md`.
The menu itself is opened with the c key or from the mobile and web apps, and the README is candid that most of its options are now reachable more easily through the player UI's gear menu, which it calls the newer interface.
Limitations and known issues, stated plainly
This is the part of the README that makes the project credible, because the limitations are specific and the known issues are unflattering about the author's own feature.
The structural limitation comes first. A single active session still reports as one device to a given server. The README does not pretend otherwise and points at fast user switching, which keeps each local user on its own device identity, and at the upstream feature request for marking a device as shared.
SyncPlay gets three honest paragraphs. If you attempt to join a SyncPlay group while casting to MPV Shim, it will play the media but will not activate SyncPlay; you have to activate it from the player UI's SyncPlay menu or from the menu inside MPV. Stopping playback leaves the group rather than the content, so you either resume from the library's SyncPlay bar, or you play something else and the whole group follows you to it, and `SyncPlay` then `Leave` is what actually leaves. With no GUI, or after casting to a shim whose library was never opened, stopping does leave the group outright, because there is no menu left to leave it from. The README then says SyncPlay can still be fragile and may need a rejoin or a client restart.
Music playback works, but gapless playback is not planned. Shader packs are sensitive to graphics hardware, and if the application fails to launch there is a `--reset-shaders` command line argument, with the k key offered as the in-session fix when the picture is merely garbled.
Getting it onto your machine
The README splits installation by platform. On Windows you download the binary from the releases page. On Linux you can install via Flathub or via pip. macOS has its own section with a setup script in the repository.
The repository tree confirms this is a multi-platform project rather than one script with a Windows branch. There are Windows build scripts for arm64, debug and regular builds, an Inno Setup definition named `Jellyfin MPV Shim.iss` for the Windows installer, a macOS setup script, a Flatpak directory, a HiDPI manifest, and desktop icon assets in both ICO and ICNS formats. Packaging scripts for artifacts and package generation sit at the root, alongside a script for regenerating translation templates.
Signing in is the only configuration the README asks for. Launch the client, enter your server URL, include the subdirectory and port if you have one, then cast from another Jellyfin application or use quick connect. There is a note here about a change of default worth knowing: bare IP addresses are now tolerated and the port is no longer required, with 8096 as the default, so connecting to port 80 explicitly means typing `:80` yourself. The maintainer attributes this to the volume of questions about URLs.
Two smaller details are easy to miss. The client runs with a notification icon by default on Windows and on Linux when installed that way, and there is a setting to run it in the background without the icon. There is also a `seed_from_jellyfin_web.py` script in the root, which suggests the shim can be populated from an existing web client session rather than typed in by hand.
The pre-release trail and what the v3 series was doing
The three most recent tags are v3.0.0 and two pre-releases, which is a more informative sequence than a list of stable versions would be. v3.0.0pre13 in August 2026 added book playback and audiobook handling, plus key bindings and interface fixes. v3.0.0pre14 later that month was explicitly about polishing, and its notes say the v3 series is slowing down feature work and that the rate of defects being logged has dropped, while also asking people to report showstopping bugs quickly.
That pre-release added game controller support, which has to be enabled in settings so it does not grab controllers unexpectedly, and notes that for anyone bringing their own MPV through a PyPI install, controller support must be compiled into MPV, which is not the default in mpv-build. It also shipped a searchable settings page with optional presets for debanding, tone mapping, rendering and network preload, and settings that need a restart say so and offer one.
Two performance notes from the same release are the kind of thing you only learn from users. Trickplay thumbnails are now fetched lazily, which removes 800MB temporary files for long movies, and an upstream MPV fix stops trickplay from breaking on HDR video. JXL image decoding is supported when installed.
One maintenance signal is easy to overlook and relevant to anyone worried about a big desktop application rotting. The `systray` extra for the notification icon has a deprecated `gui` alias kept deliberately, with a comment explaining that the old extra name appears in install instructions people have already copied, and that an unknown extra is only a warning while a missing tray is not.
Editorial conclusion
The technical bet in this project is that drawing the interface into MPV itself, rather than wrapping a web view, keeps you on MPV's own rendering path. That is why HDR, Dolby Vision and custom shaders work, and why the release notes are explicit that nothing redirects or recomposites MPV's video output. What v3 adds is scope: an in-player library browser, offline sync, Live TV and faster user switching, with Jellyfin v12 support. The limitations are documented with equal precision, from the single-device-identity problem to SyncPlay needing you to join from the player's own menu. Install from Flathub on Linux or the release binary on Windows, and decide about the deprecated GUI extra before you copy an old install line from the documentation.
Frequently asked questions
What is the purpose of Jellyfin MPV Shim?
It is a cross-platform Jellyfin client built on MPV that plays media directly without transcoding. It can run in the background as a cast target that the Jellyfin mobile and web apps control, and it can also act as a full desktop client, which is what version 3 added with its in-player library browser and offline sync.
Does Jellyfin MPV Shim need transcoding or a bundled browser?
It plays most media directly through MPV rather than transcoding, and version 3 explicitly uses no webviews or bundled copies of Chromium. Because the client draws into MPV without redirecting or recompositing its video output, gpu-next, HDR, Dolby Vision and custom shaders still work.
Why does SyncPlay not activate when I cast to MPV Shim?
That is a documented known issue: joining a SyncPlay group while casting plays the media but does not turn SyncPlay on. You have to activate it from the player UI's SyncPlay menu or from the menu inside MPV. The README also notes SyncPlay can be fragile and may need a rejoin or a client restart.
How do I install Jellyfin MPV Shim on Linux or Windows?
On Linux the README lists two routes, Flathub or pip. On Windows you download the binary from the releases page. The repository also carries a Flatpak directory, Windows build and Inno Setup scripts, and a macOS setup script, so all three platforms are packaged from the same source.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/jellyfin-jellyfin-mpv-shim)