Jellyfin MPV Shim

Last reviewed Sep 13, 2026 · 876 words

The best picture you will get out of a Jellyfin library on a desktop does not come from the Jellyfin web player or the official desktop app. It comes from Jellyfin MPV Shim, a 2,380-star Python tray program that registers your PC as a cast target and hands every stream to MPV. You pick what to watch on your phone or in a browser tab, and the video opens in a real MPV window with proper subtitle rendering, hardware decoding, and whatever shaders you have installed. The cost is a setup that involves a terminal, a config file, and no GUI worth speaking of.

It is a remote-controlled MPV, not a media player

Calling this a "client" undersells the trick. MPV Shim does not have a library browser of its own. It talks to your Jellyfin server, announces itself as a cast device, and then waits. When you tap the cast icon in the Jellyfin Android app or the web client and pick your desktop, the shim asks the server for a direct stream and passes the URL to an embedded MPV via python-mpv. Play, pause, seek, and audio or subtitle switching all arrive as remote commands from whatever device you picked the film on.

That design is why the quality is so good. MPV is doing the decoding, the scaling, and the subtitle compositing, and it does all three better than a browser's <video> tag or the Electron-wrapped web player. ASS subtitles with karaoke effects, 10-bit HEVC, high-bitrate remuxes that make Chromium stutter: MPV handles them the way it always has.

There is also a desktop mode that embeds the Jellyfin web UI in a window so you can browse locally, but I treat that as a bonus. The cast workflow is the reason to run this.

Installation is one pip command, and then one file

On Linux, macOS, or Windows:

pip3 install --upgrade jellyfin-mpv-shim
jellyfin-mpv-shim

You need MPV itself installed first (the shim bundles a copy on Windows builds; on Linux use your package manager). The first launch asks for your server URL and credentials, then sits in the system tray. The config lives at ~/.config/jellyfin-mpv-shim/conf.json, and the things worth changing straight away are direct_paths if your desktop can reach the media files over SMB or NFS (skips the HTTP stream entirely) and fullscreen so the window does not open small in a corner.

MPV's own options go in a separate mpv.conf in the same directory, exactly like a standalone MPV install. If you already have a tuned mpv.conf for your anime or your film library, copy it over and it behaves identically. RAM use sits around 256 MB with a 1080p stream running, most of that MPV's decode buffers.

Shader packs are the feature that justifies the hassle

The shim ships with a shader pack system built around Anime4K and a handful of upscaling and sharpening presets. You pick a profile from the tray menu and the shim sets the MPV glsl-shaders chain for you, so a 1080p anime episode on a 4K monitor gets the same treatment people spend hours configuring by hand. On a mid-range GPU the heavier Anime4K profiles cost real frames; the lighter ones are free at 1080p. There is a "none" profile for live-action content where these shaders make skin look like plastic.

SyncPlay is the other headline. Jellyfin's built-in watch-together feature works through the shim, so a group with mixed devices, some on the web client and one on a desktop running MPV, stays in sync. I have found it more reliable than the browser client at holding position through a seek.

The things it is not

It is desktop only. There is no version for an Android TV box or a Fire Stick; on those you want Jellyfin's own app. It is also not a substitute for the server-side transcoding settings covered in the Jellyfin setup walkthrough. When the shim asks for a stream it prefers direct play, and if your desktop cannot decode the codec, MPV will fall back to software decoding rather than asking the server to transcode. On a laptop that can mean fans.

Windows users get the smoothest ride because the release bundles MPV. Linux users occasionally hit a mismatch between a distro's MPV build and the python-mpv bindings after an update, and the fix is usually reinstalling the pip package. It is a small project maintained under the Jellyfin organisation, so it tracks server changes but does not move fast.

What I'd do

If you watch Jellyfin on a desktop or a PC plugged into a TV, install the shim, copy in your mpv.conf, enable direct_paths where the files are mounted locally, and pick everything from your phone. Keep the official desktop app around for library browsing if you like it, but let MPV do the playing. Anyone whose viewing happens on a TV box or a tablet should skip this and look at the rest of the media server category for the client that fits that screen.