Jellyfin MPV Shim
Jellyfin MPV Shim is a fully featured Jellyfin client built on top of MPV with support for offline sync, media browsing, background casting, syncplay, music, live TV, books, and photos. It does not depend on or use a webview and doesn't mess with MPV's video output pipeline, allowing for HDR and tone mapping support.
Download for Windows · Flathub (Linux) · pip (Linux) · macOS
More screenshots
 |
 |
| Playback | Music |
 |
 |
| Detail page | TV shows |
 |
 |
| Live TV guide | Comic reader |
 |
 |
| Audiobook | Epub reader |
Features
- Uncompromising Playback: MPV's rendering and video pipelines are completely untouched. It's not redirected, broken, or embedded in a toolkit. Native HDR and Dolby Vision are supported on Windows and Linux.
- Browse and play your entire library including films, shows, music, photos, Live TV and books, comics and audiobooks.
- Offline sync: download media for offline viewing, automatically if desired.
- Cast target: Fully controllable from Jellyfin web and mobile apps.
- SyncPlay: Watch media with friends, without screen shares or awkward syncing.
- Smart Subtitles: No need to set for every episode, they're remembered by default and can be forced globally.
- Video Enhancement: video upscaling, debanding, and motion interpolation.
- Advanced Audio: Audio passthrough and night mode so you can actually hear people talking.
- Seamless User & Server Switching via fast user switching and optional PINs.
- Keyboard, mouse, Jellyfin remote and game controller support, and all of MPV's shortcuts.
- MPRIS media controls on Linux, Discord Rich Presence, shell commands on playback events, and an external MPV if you prefer your own.
Getting started
Install it (below), launch it and log in. Enter your server's address, e.g.
http://192.168.1.10:8096 or https://jellyfin.example.com, including any subpath; port
8096 is assumed if you leave it out, so a server on port 80 needs :80. Quick Connect works
too.
Then browse from the window, or cast to it from another Jellyfin app. When a system tray is available, closing the window keeps it running there as a cast target; you can change that in Settings.
Windows
Download the installer from Releases.
There are ARM64 builds, and LEGACY64 builds for CPUs without x86-64-v3 support
(roughly pre-2013).
Linux
The Flatpak is the
most integrated option. To install with pip instead you need libmpv (or mpv). MPV 0.41
or newer is recommended:
pip3 install --upgrade jellyfin-mpv-shim
Optional extras:
- Tray icon: keeps it running in the background once the window closes (or enable
Keep Running in Background in Settings instead):
pip3 install 'jellyfin-mpv-shim[systray]', plus GObject and AppIndicator from your distribution (on Debian:python3-gi gir1.2-ayatanaappindicator3-0.1). The virtualenv must have--system-site-packages; with pipx,pipx install --system-site-packages 'jellyfin-mpv-shim[systray]'. - Discord Rich Presence:
pip3 install 'jellyfin-mpv-shim[discord]', then enable it in Settings.
With MPV older than 0.41, minimizing to the tray closes MPV rather than hiding its window, and
copy/paste in text fields needs wl-clipboard (Wayland) or xclip/xsel (X11).
If your distribution's MPV is old, mpv-build builds
a current one with libmpv by default; run sudo ldconfig afterwards. Add
-Dsdl2-gamepad=enabled to its mpv_options for controller support.
macOS
The application is not tested on Mac OS and is not formally supported. PRs to improve support and third-party packaging are welcome.
brew install python mpv pipx
pipx ensurepath
pipx install 'jellyfin-mpv-shim[systray]' # drop [systray] if you don't want the menu bar icon
jellyfin-mpv-shim
Using it
Controls and remotes
Use the mouse, or the arrow keys, Enter and Esc. The mouse's thumb buttons go back and forward a page; right-click Back (or Home at the top level) to jump anywhere in the history.
From a Jellyfin remote, use the arrows, OK, Back and Home. Menu opens the context menu of the selected item (Play, Queue, Mark Watched, Favorite, Download) or, during playback, the player's settings menu. Search jumps to the search box. Opening a film or episode lands on its Play button, so OK twice plays it.
During playback the controls have audio, subtitle and quality pickers, and the gear menu (or
c) holds speed, aspect, shader profiles, subtitle style, SyncPlay and screenshots.
Keyboard shortcuts
Most of MPV's keyboard shortcuts work. The app adds:
| Key | Action | Key | Action | |
|---|---|---|---|---|
< > |
Previous / next item | c |
Player settings menu | |
q |
Stop | k |
Unload the shader profile | |
w |
Mark watched and skip | u |
Mark unwatched and stop |
And the MPV ones you are most likely to want: space pause, ←/→ seek 5 s, ↑/↓ seek
1 min, f fullscreen, m mute, s / S screenshot with / without subtitles, , . step a
frame, [ ] speed ±10%, backspace reset speed, d deinterlace, Ctrl+Shift+←/→
subtitle delay.
All of these can be changed. See Keyboard shortcuts
and input.conf.
Live TV
With a tuner on your server, Live TV appears with your libraries, with the web client's six screens: Programs, Guide, Channels, Recordings, Schedule and Series (recording rules). Right-click any programme to record it or the series. Guide Settings are stored on the server, shared with the web client.
The guide shows one window of time and pages with the arrows, rather than scrolling sideways through 24 hours.
Books, comics and audiobooks
Books libraries browse by folder, as in the web client.
- Epub opens in a built-in reader with adjustable size, page colour and justification.
- Comics (
cbz,cbt) open in a built-in reader with fit-width and fit-page zoom. - Other formats (
pdf,mobi,azw3,cbr,cb7) open in your desktop's own application. - Audiobooks play like music, with chapter navigation, skip back 10 s / forward 30 s, and chapter marks on the seek bar. Resume continues from where you stopped; Play from Beginning is a separate button so you don't lose your place by accident.
The built-in readers save your position to the server as you turn pages, in the same form the web client uses, so you can carry on elsewhere. For formats read outside the app, use Progress… on the book's page to pull or push your page.
Jellyfin can only hand over a book as a whole file, so reading downloads it first, and your account needs the "Allow media downloads" permission to read books at all.
Fast user switching
Several people can share one player, each with their own servers and logins. In Settings → Servers, Add User, switch to it and add its servers. Once there is more than one user, a user picker appears beside the server picker in the top bar.
- Each user gets its own device identity, so two users on the same server don't share a session.
- Set PIN locks a user; optionally require it at startup too. This is a parental-control convenience, not security. Nothing is encrypted (although PINs are hashed).
Cast-target mode (headless)
For a machine that should only be a cast target, such as a shared TV, set headless to
true in the config file. It then shows "Ready to cast" instead of the library: casting,
playback and the player controls work; browsing, search and settings are not reachable from
the machine.
This is not a security feature. It stops casual use, not anyone with access to the config file or the tray menu.
Shader packs and SVP
The bundled shader pack offers upscaling and
enhancement profiles (FSRCNNX, Anime4K). Choose one from the player's gear menu under Change Video
Playback Profile. If video breaks, pick a different Graphics API for Shaders in Settings →
Playback → Video Enhancement; opengl is the most compatible. If the app won't start after
choosing a profile, launch it once with --reset-shaders; if the picture is merely garbled,
press k.
SVP can be controlled from the menu too; it needs some setup. See SVP integration. Please note that I don't have an SVP license (it used to be free on Linux), so the support is untested.
Configuration
Almost everything is in Settings, which has a search box. The complete reference, including options with no UI, is docs/configuration.md, along with where the config folder is (the tray icon can open it).
Tips and troubleshooting
Open on a specific monitor
In mpv.conf in the config folder, add fs-screen=N
(with fs=yes to open fullscreen), where N counts from 0. On Windows, the monitor number in
Display Settings minus one. If X11 reports your monitors as one screen, use geometry= with the
position xrandr shows instead, e.g. geometry=1920x1080+0+0. Restart the app after editing.
Volume on the mouse wheel
Add to input.conf:
WHEEL_UP add volume 5
WHEEL_DOWN add volume -5
Run multiple instances
--config /path/to/folder runs another, independent copy. Launching again with the same
folder just brings the running one forward. jellyfin-mpv-shim stop (with the same
--config, if any) shuts an instance down cleanly.
Arabic or Hebrew text drawn backwards
Some text is drawn with Pillow, which needs FriBiDi for right-to-left scripts and kerning; without it nothing errors, but RTL titles come out reversed and captions are slightly mis-measured. The Windows installer and the Flatpak include it. Elsewhere, check:
python3 -c "from PIL import features; print(features.check('raqm'))"
If this prints False, install FriBiDi (libfribidi0 on Debian/Ubuntu, fribidi on Fedora
and Arch). If pip built Pillow from source rather than using a wheel, also install libraqm's
development package and run pip3 install --force-reinstall --no-binary=pillow pillow.
Known issues
- Joining a SyncPlay group from a client that is casting to this one plays the media without enabling SyncPlay. Join from this player's own SyncPlay menu instead.
- Stopping playback leaves the group's content, not the group, as in the web client: SyncPlay → Resume local playback rejoins, and playing something else takes the group with you. Use SyncPlay → Leave to leave. SyncPlay can still be fragile — please report problems.
- Music has no gapless playback.
- A player counts as one device on a server; fast user switching gives each local user its own.
Development
Building, translating and testing: docs/development.md.
3 maintainers
Metadata
3 maintainers
Release files for jellyfin-mpv-shim 3.3.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| jellyfin_mpv_shim-3.3.0.tar.gz | 6.2 MB | Without provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| jellyfin_mpv_shim-3.3.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 11.2 MB
Release files / jellyfin_mpv_shim-3.3.0.tar.gz
| Download URL | jellyfin_mpv_shim-3.3.0.tar.gz |
|---|---|
| Size | 6.2 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
18075368b33e2dbd1129c03376553773d684b6dbfde77dcceddcaf4006ca7b39
|
|
BLAKE2b-256 checksum How to use checksums |
07fd46c848f37aeec91fa8fc33f61b921bd8764517806601378612ff30f07854
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.13.5
|
Release files / jellyfin_mpv_shim-3.3.0-py3-none-any.whl
| Download URL | jellyfin_mpv_shim-3.3.0-py3-none-any.whl |
|---|---|
| Size | 5.1 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
4d9236b464d5369922552d06a1313e8e7bfa0dfde53610ccb59291e6e3d5edcc
|
|
BLAKE2b-256 checksum How to use checksums |
7103b8d4b73728e25e0e54ca952184bfef07aafce75dd7e055886beed1d10be6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.13.5
|
Security for jellyfin-mpv-shim 3.3.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
