v3: Library Browser, Offline Sync, and Jellyfin v12 Support

MPV Shim v3 reinvents the client. There's now a full library browser inside MPV, supporting all Jellyfin media types including videos, books, audiobooks, comics, photos, and music. Offline Sync, Live TV, and fast user/server switching are also added. This is also the first MPV Shim version to support Jellyfin v12 without legacy auth turned on.

More Screenshots

This is all done without any webviews or heavy copies of Chromium. Nothing touches MPV's video output either, MPV Shim draws into MPV so gpu-next works perfectly. We don't redirect it or recomposite it. HDR, Dolby Vision, and custom shaders all work.

MPV Shim retains the ability to use MPV's default player controls and has improved support for custom OSCs and player keybinds. You can also configure the player to start minimized and stay out of the way, like the past versions did, or you can use the new 10ft browser UI with gamepads, cast controls, and keyboard navigation from your couch. There's also optional presets for audio passthrough, improved shaders with per-library support, and volume normalization (night mode).

Changes:

• Browse and search your entire media library within MPV.
  • Playlists, collections, detail pages, favorites, genres, and live tv.
  • Per-library view customization.
  • Sort and filter library pages.
  • Supports built-in and custom themes.
• Offline sync support
  • Supports movies, shows, playlists, music, and books.
  • Optionally download new episodes of shows you're watching automatically.
  • Progress is automatically synced with your server.
  • Supports skip intro, trickplay, and media artwork.
  • Media playback while online prefers downloaded copies, allowing large syncplay watch parties that would normally exceed server capacity.
• Improved Player UI
  • Supports subtitle/audio track switching even for external subtitles and transcodes.
  • Standalone skip intro/credits button, meaning skip intro doesn't need to steal seek.
  • Chapter navigation, next/prev episode, volume control, trickplay, and media info.
  • Classic MPV OSC and custom OSCs (tested with uosc and modernz) are supported too.
  • Keyboard shortcuts are only claimed when needed, arrow keys are now yours in input.conf.
• Music support
  • Browse by song, album, artist, album artist, and genre.
  • Now playing UI integrated into library browser.
  • Playlist creation, editing, and bulk update.
• Books support
  • Audiobook support, including chapters, resume, and multi-file editions
  • Inline epub and comic book viewer (CBZ and CBT only)
  • Any format can be opened in an external viewer if you have one installed.
• Live TV including channels, guide, and recording.
• Quick connect support (#555).
• Fast switching between servers and different users, with optional PIN for users.
• Full keyboard, jellyfin cast navigation, and gamepad support.
  • Gamepad requires a supported MPV build if you install via PyPI and must be enabled.
• Video Improvements
  • Dolby vision works, note old MPV versions may need vo=gpu-next in mpv.conf.
  • Per library and per-series shader packs now supported.
  • Added audio passthrough, exclusive mode support, and "night mode" audio normalization option.
  • Allow enabling hardware decoding via settings, either always or only for >1080p videos.
  • Secondary subtitles
  • Optional deband, tone mapping, rendering, and network setting presets.
• New searchable settings UI allows configuring most aspects of the client.
• HiDPI support.
• Syncplay doesn't stall when seeking anymore. Buffering and stopping is now handled correctly.
  • Groups can now be joined from the home screen.
• Jellyfin v12 is supported and all auth goes through the Authorization header.
• Added handling for GNOME's strangeness.
  • Added client-side decorations.
  • Suppress background operation by default when no systray is available.
• Wayland is properly supported and actually tested.

For users upgrading from 2.10:

• If you wish to disable OSC or use a custom OSC, select the appropriate option under Player Controls Style in settings.
• Display mirroring is supported by default, if you previously used display_mirroring for a chromecast-like experience, you can achieve that with the headless config option.
• Most keyboard shortcut settings are now in input.conf and auto-migrate unless you used mpv_ext_no_ovr.
• 32 bit Windows support was dropped due to it not working for several years and no one complaining about it.
• The "auto set subtitles" feature was removed due to Jellyfin's session persistence being flakey, it is replaced by remembering subtitles/audio between episodes and language overrides.

When upgrading/installing on Linux via PyPI, use:

pip install --upgrade "jellyfin-mpv-shim[all]"

You can also install on Linux via Flathub. Note flathub may take a few hours to publish post release, if you're impatient you can download the attached flatpak file instead. Confirmed v3 is now on Flathub. If you install via PyPI in other ways or run the application directly from a git clone, you may get errors due to updated dependencies.

About testing: This is a huge release which covers a lot of new ground. To help keep bugs down, the project has adopted automated testing including extensive unit tests, integration tests over multiple MPV backends, and end-to-end tests which test over a newly built fake jellyfin library generator and fake live tv/guide provider. Thank you to everyone who has beta tested the pre-releases and reported bugs, I could not have done it without you.

About Windows Downloads:

• If your CPU is older than roughly 2013 or you get a 0xc0000142 error you need to use the LEGACY64 build.
• You do not need administrator rights to install the software.
• You can avoid warnings on files by unblocking the file in the properties dialog.

Development was assisted using AI.

Pre-release 14: Settings, Gamepad, and UI Polish

This pre-release is mostly polishing the app, the v3 series is slowing down
feature work and the rate of defects being logged has dropped. If you find a
show stopping bug, please log it asap!

The settings UI is now contains presets for more MPV settings and is searchable.
Game controller support is also added, it must be enabled via settings so it
doesn't grab game controllers when unexpected.

Major Additions

• Game controllers now supported
  • Supports the same navigation as the Jellyfin Play On Navigation and keyboard.
  • For those bringing their own MPV (i.e. PyPI installs) controller support must be compiled into MPV, which is not the default in mpv-build.
• Better settings page
  • Added optional presets for deband, tone mapping, rendering, and network preload.
  • You can now search the settings page, making it faster to find a specific option.
  • If a setting needs a restart, it tells you and offers the option to restart.

Improvements

• Trickplay is lazily fetched now, so no more 800MB temp files for long movies.
  • It also, due to an upstream MPV fix, stops breaking trickplay on HDR videos.
• JXL image decoding is supported if you install pillow-jxl. (Optional, #704)
• Windows has proper text rendering, previously it was falling back to basic rendering.
  • Notably this makes text sizing more reliable and allows RTL text display.
• Details pages now contain links to metadata providers.
• Navigating back to the home page is faster.
• Made application UI margins/spacing/phrasing more consistent.

Bugs fixed from last release

• Fixed carousel buttons behaving oddly after back nav.
• Fixed mouse losing focus on some input devices or WMs. (#700)
• Fixed issue where MPV's console lost keybinds.
• Fixed jank when starting media causing library to flash.
• Fixed "Clear All" being broken in the filter panel.
• Fixed language filter set/reset issues.
• Fixed issue where pagination loses library sorts.
• Fixed Latest TV Shows using wrong sort.
• Fixed issues where application didn't clean up temp files from systray.
• Dropped broken 32 bit windows build.
  • The build was broken and no one had complained for years.

To install on Linux, install via pip:

pip install --pre --upgrade jellyfin-mpv-shim[all]

Or via the attached flatpak file:

flatpak install --user --bundle jellyfin-mpv-shim_v3.0.0pre14_amd64.flatpak

Development was assisted using AI.

Pre-release 13: Books & Comics, Key Bindings, UI/UX fixes

This pre-release adds book playback!

Namely audiobooks with chapters, but also epub and comics (CBZ/CBT only) are supported.
You can also read other formats, but they'll be opened in an external reader not within
MPV Shim, assuming you have one installed. The built-in epub reader is designed for novels
and basic markup such as paragraphs, lists, headings, and images. If your epub books are
more complicated you can use the open in external reader feature for those too.

Also of note, MPV Shim only steals keybinds from mpv when needed, arrow keys for instance
are not bound unless menu UI is open or syncplay is active.

Major Additions

• Book playback!
  • Audiobooks are supported now, including chapter and multi-file variants.
  • EPUBs and comics can be viewed within the MPV window. (No new dependencies.)
  • All book types can be opened using an external viewer is one is available.
  • Offline downloads for books are also supported, books download on first open.
• You can now set shader packs on a per-series and per-library basis.
  • Very useful for Anime4K in particular.
• Newly added media info dialogs allow seeing details about the current media file.
  • Within playback, it'll show details such as MPV FPS, transcoding reason (if applicable), hardware encoding.
  • The traditional MPV info UI is still available via the i key.
• Browser filter pane is revamped and includes new filters specific to Jellyfin v12 when available.
• Added text size and minimum text size adjustments. Text sizing is also more consistent now.
• Key bindings are now claimed, not set globally. No more messing with your arrow keys!
  • All user keybinds which affect seeking and play/pause are now intercepted only when needed by Syncplay.
  • If you customized keybinds with the old settings, they'll be migrated to input.conf.
• Added buttons/context menu entries for deleting media. (Requires confirmation.)
• You can now turn hardware decoding on via the settings UI.
  • It defaults to off because MPV developers still see frequent breakage with it.
  • You can also selectively enable it for files over 1080p.
• Offline sync now remembers playback that happens while online or via other clients.
• Added settings for deinterlacing and temporal scaling to settings UI.

Improvements

• Detail pages now also show poster/thumbnail images instead of just the backdrop.
• Improved search to show more entity types and more results for each type.
• Allow MPV-style player mouse bindings (still uses click-to-pause by default). (#669)
• Multi-version files get a badge displaying the number of versions.
• Added "Play Next" option to context menus.
• Auto-download now supports downloading in batches (disabled by default). (#661)
• Fixed icons in browser to use the same icons jellyfin-web uses.
• Reduced RAM usage required for browser.
• CLI mode for builds without lua/osc support now works again. (It had been broken for years...)
• Added Windows ARM64 CI build.
• For GNOME users, the (lack of) systray and window decorations is now detected and dealt with...
  • CSD is drawn inside the MPV UI, the top bar is draggable, and a resize handle is added.
  • If no systray exists, you have to opt into running in the background.
• Add theme mode to use shadows instead of badges
• Add a "Super Dark" theme which uses grey as accent color and shadows
• Use full-width backdrops on detail pages
• Add backdrop banners to Season pages
• Add justify (now default) and centered display modes for browse pages to cut down on large voids in margins

Bug fixed from last release

• Fixed ordering of songs in the music browser to order by actual track name not track number.
• Use a larger systray icon to improve HiDPI
• Make cover size only affect images and not text size
• Fix Live TV cutting off times when displaying as posters.
• .strm files should now play properly and save runtime
• Fixed bug where detail page sometimes ignored subtitle/audio selection
• Allow skipping backwards before the begining of queued items, when possible. (#650)
• Fixed issue where window title fails to reset (#647)
• Fixed cache eviction and cache cleanup issues
• Fixed auto-download ignoring episode limit
• Fixed broken pending downloads stopping entire download queue
• Fixed issue where syncplay group creation failed on home page
• Fixed issue where syncplay didn't allow changing what is playing due to leaving group instead
• Fixed photos not showing on accounts not allowed to download (still affects books due to server limits)
• Shader packs don't apply to photos now
• Fixed issue where duplicate people in cast row causes unexpected behaviour
• Fixed ENTER opening OSD menu when not expected
• Fixed positioning consistency of carousel headings
• Fixed the unplayed count badge overflowing when more than 99
• Added permission check for collections actions
• Fixed breakage where Live TV might not fully refresh
• Fixed mouse back/forward buttons broken while playing audio.
• [Pre13] Fix bug where pre12 broke cursor autohide.

To install on Linux, install via pip:

pip install --pre --upgrade jellyfin-mpv-shim[all]

Or via the attached flatpak file:

flatpak install --user --bundle jellyfin-mpv-shim_v3.0.0pre13_amd64.flatpak

Development was assisted using AI. This pre-release replaces pre12 which was broken on release.

Pre-release 11: Library views, Remove Legacy Auth, UI/UX fixes

This pre-release mostly consists of UI/UX feedback work as well as filling in
gaps between this client and jellyfin-web. It also gains Jellyfin v12 compatability
by dropping api_key from URLs in favor of header-based auth everywhere.

Major Additions

• View settings can be customized per-library.
  • Banners, logos, list view, etc are supported.
  • Synced with jf-web.
• Added screens to match jf-web: Favorites, Genres, and Networks
• Home screen and other carousels now have clickable headings to browse all the items on a new page.
• Added play buttons to tiles, like web has saving you a pagenav to play something.
• Added photo album support and improved mixed media UI for home videos.

Improvements

• Scrolling is continuous again by default, it only snaps when the renderer starts missing render dealines.
• Added a Play All option to some libraries which didn't already have them.
• Added support for Commercial, Preview, and Recap skipping.
• Skip Intro and Skip Credits now work on downloadeds, previously they didn't even when internet access was available.
  • Requires re-downloading of existing items.
• Episode backdrops are now used on the home screen for continue/next-up to avoid spoilers. (Configurable)
• More adjustment for Jellyfin OSC appearance and auto-hide duration. (#620)
• "No player controls" added as player OSC option, replaces enable_osc. (#615)
• Mouse back/forward buttons can be used for chapter navigation. (#614, disabled by default.)
• Mouse back/forward buttons now navigate like a web browser does in the library.
  • Right click the back button (or home on the home page) to jump or go forward.
• Cast controls are now more usable, with hamburger added for context menu and search added.
• Added "Date Episode Added" sort option to TV libraries.
• The app uses the Authorization header for everything now, gaining Jellyfin v12 compatability without enabling legacy auth.
• The home page now updates when videos are watched or progress is made on other clients.
• Artwork rendering now uses the same heuristics as jf-web to set defaults.
• PGUP/PGDWN/HOME/END scroll the UI now.
• The application now has end-to-end tests that can automatically test the UI against a real Jellyfin server.
  • Test uses a fake library generator and a fake tv source to automatically bring up a Jellyfin server for testing.

Bug fixed from last release

• Improved library browsing performance for thumbnail rendering, home page drilldowns, genres, and instant mix.
• Fixed issue where skipping one chapter back skips to the next episode in some cases.
• Fixed scrollbar losing position when new items are loaded. (#617)
• Made trickplay more performant (#618)
• Made hover bubble when trickplay is disabled centered properly (#612)
• Fixed zero duration bubble for durationless content (#618)
• Removed subtitle offset during HUD hover that only applied to SRT subtitles.
• Fixed issue where keyboard nav could get disabled after video playback.
• Fixed mpv console being unusable due to default ENTER to activate UI keybind.
• Fixed possible crash from trickplay and mpv restart contention.
• Fixed issue where HDR->SDR change isn't processed outside of playback screen.
• Fixed issue where stopping playback could hold the player until the session stop finished.
• Fixed request spam during backdrop displaying window resizes. (#592)
• Removed transcode warning text that displayed under HUD.
• Fixed chapter markers not responding to scaling (#620)
• Fix issue where text can overflow on certain DPI scaling settings.
• Fix issue where nebula selections outlines could overflow with the top UI bar.
• Use css-cover style placement for posters on all themes, not just nebula.
• Hide syncplay and Live TV DVR when their respective permission checks fail.

To install on Linux, install via pip:

pip install --pre --upgrade jellyfin-mpv-shim[all]

Or via the attached flatpak file:

flatpak install --user --bundle jellyfin-mpv-shim_v3.0.0pre11_amd64.flatpak

Development was assisted using AI.

Pre-release 10: Theming and Live TV

This pre-release adds theming, better passthrough support (tested against a real optical SPDIF card on Linux), and full Live TV support.

Changes:

• Add full Live TV support including browsing, guides, recordings, and scheduling.
  • Should match jellyfin-web's UI. Report any gaps or issues.
  • Tested by me against faketvsource and by another community member against an HDHomeRun.
• Add theming system.
  • Allows users to create themes in the form of json documents, which can be placed in the config directory.
  • Added a contributed nebula theme as well as ports of the themes from jellyfin-web.
  • Carousel < and > buttons in the UI now render and behave like jellyfin-web.
• Improved audio passthrough support.
  • Added exclusive mode support (where applicable) and device selection.
• TV show episodes updates show as posters instead of letterboxed thumbnail previews.
• Toggle for Discord Rich Presence added to settings screen.
• Ported over translations from jellyfin-web where applicable and made the new UI translatable on Weblate.

Bug fixes:

• Fixed UI freeze and possible blank page rendering bug in paginated mode.
• Back button now restores scroll position.
• Fixed blank window flashing in external mpv mode.
• Fixed issue where i playback info screen persists in media browser.
• Fixed issue where ac3 transcoder would be attached to streams where passthrough should be enabled.
• Fixed several old syncplay protocol violations.
  • Seeking would cause all clients to wait until someone manually paused and played the video.
  • Stopping playback wasn't handled correctly.
  • Buffering wasn't reported, causing de-syncs between members.
  • Resync commands were ignored by the duplicate command filter.
  • A possible race condition might cause lost pause/play events.

To install on Linux, install via pip:

pip install --pre --upgrade jellyfin-mpv-shim[all]

Or via the attached flatpak file:

flatpak install --user --bundle jellyfin-mpv-shim_v3.0.0pre10_amd64.flatpak

Development was assisted using AI.

Pre-Release 9: General Client Improvements

This pre-release fixes a number of problems that people testing the previous v8 pre-release found and generally improves the usability of the new MPV-based UI.

New features:

• Optionally download new episodes automatically in the background from currently watched shows and the Next Up list.
• The home screen now honors custom ordering and library exclusions.
• Added audio passthrough settings and night mode support.
  • Night mode normalizes volume so dialogue is the same loudness as explosions and other "cinematic" effects.
• You can now switch the library pages to use pagination if preferred.
• Application now supports running in the background even without the systray components installed.
  • To quit, simply run with the stop command line argument or open the client again and disable running in the background.
• Added ArtCNN and fixed issue where enabling shaders disabled Vulkan support.
  • Pre-release Note: On Linux, to use shaders, you must git clone the repo, run git checkout local-ui-mpvtk && ./gen_pkg.sh, and then pip install .[all]
  • Added a --reset-shaders command line flag for if shaders render the UI unusable.
• Added secondary subtitle support.

Bug fixes:

• Fixed HiDPI scaling and added the ability to re-configure app scaling.
• Several fixes applied for application geometry. It should now be remembered and not resize itself.
• HDR video output fixed and the grey background around videos removed.
• Live TV should properly close the stream when closed. Also added basic homepage display support.
• Made scroll less laggy and unusable. You can re-configure scrolling amounts in settings.
• Fixed numpad support and added tab/shift+tab in UI integrations.
• Fixed issue where older versions of MPV didn't show anything when launching application.
• Improved video loading handling to avoid problems with slow loading or duration-less streams.
• Display mirroring does not summon the browser while closed.
• Various UI rendering issues fixed.
• Enable music video libraries. (They're just videos.)

To install this pre-release on Linux, use:

pip install --upgrade --force-reinstall "jellyfin-mpv-shim[all]@git+https://github.com/jellyfin/jellyfin-mpv-shim@local-ui-mpvtk"

Development was assisted using AI.

Pre-Release 8: MPV-Based UI (Early Preview)

This pre-release changes the main UI to use the same window as MPV, making MPV Shim a more polished desktop player experience. It also supports display mirroring for the normal UI and both the library browser and player can be driven entirely with keyboard/remote cast navigation controls.

Changes:

• Switch to new mpv-based library browser UI.
• MPV OSC UI can now be driven via keyboard.
  • Defaults are still mpv controls, press ENTER to switch to UI mode.
  • You can still switch to the classic MPV OSC if you prefer via settings.
• Display mirroring and remote UI control support.
• Improvements to player lifecycle to make playback more robust.
  • Playback errors are better handled now, instead of the player silently breaking and hanging for 30 seconds.
  • You can also now optionally request a transcode on direct playback failure.
• Performance improvements to homescreen loading times.

This changes how the UI works considerably. All UI is now rendered inside of MPV, tkinter is not used anymore. For Linux users, this has a substantial benefit of not requiring custom tkinter builds on Flatpak and means that the entire UI should be Wayland compatible. No compromise to the playback pipeline was made, unlike past approaches with Jellyfin Media Player which required redirecting video output through another UI, with a significant performance and rendering cost.

To install this pre-release on Linux, use:

pip install --upgrade --force-reinstall "jellyfin-mpv-shim[all]@git+https://github.com/jellyfin/jellyfin-mpv-shim@local-ui-mpvtk"

Development was assisted using AI. Please note this is a preview build for users to test and experiment with, stability is not guaranteed, this will need extensive QA on my part before it becomes a production release.

Pre-Release 7: Better MPV UI

This pre-release introduces an improved MPV OSC, which exposes all the functionality you would expect the player UI to support, including:

• Full support for switching subtitle streams including external ones.
• An actual skip intro button which doesn't override seeking via the UI.
• A working volume slider.
• Next/Prev episode buttons and chapter skipping.
• Easier access to SyncPlay.
• Better icons across the entire application.
• Update check added to main UI. (Latent, won't actually see until full release.)

The new UI is optional, to switch back to classic MPV UI, simply go to settings, change the option, and restart the application. The new UI doesn't affect keybinds at all.

To install this pre-release on Linux, use:

pip install --upgrade "jellyfin-mpv-shim[all]"
pip install --upgrade --force-reinstall "git+https://github.com/jellyfin/jellyfin-mpv-shim@local-ui"

(First command ensures gui dependencies, second command installs prerelease.)

Development was assisted using AI.

Pre-Release 5: User Switching, Playlist Editing & Music Support!

This is the fifth pre-release of the new local media UI. It adds playlist editing support (including batch editing) as well as Music support. Music downloads are also supported, currently by playlist only. You can now also add and switch between users easily without having to log out and log back in other accounts.

Changes:

• Add fast user account switching.
  • Supports multiple servers per user, so selecting can switch shared servers too.
  • Allows locking a user behind a PIN code for privacy.
• Make minimizing on close optional.
• Library UX improved:
  • Favorites support
  • A-Z jump strip support
  • Additional sorting orders
  • Shuffle support
  • Cast & crew added to Movie & TV Show pages
  • Multi-version support added
  • Media info added to media pages
  • Search results now grouped by media type
• Syncplay can now be joined from the library home page.
• Added music support:
  • Mini player now shows in library browser.
  • Supports playlist operations on queue and repeat modes.
  • Volume is remembered, separately from main playback.
  • Instant mix is supported
  • Browse by song, genre, album, artist, and album artist.
• Added playlist editing support:
  • Multi-select re-ordering and removal of items from playlists.
  • Adding most item types to playlists.
  • Creation of new playlists, public and private.

Development was assisted using AI.

Offline Sync & Browse Pre-Release 4 - Playlists & QA

This is the forth pre-release of the new local media UI. It fixes a ton of bugs and adds offline playlists support on top of the already existing Movies & TV offline support. Music remains unsupported.

Changes:

• Playlist support and playlist downloads
• Setting user-data/media-source/Path, for auto applying profile (#556)
• Adds ability to relocate downloads folder. (#557)
• Add handling of restarting MPV and allow auto-terminating it when idle to free memory.
• Improved handling of external MPV, may close many issues people have with it.
• Extensive manual regression testing. (Test list)
• Added extensive unit and integration tests to help catch issues before they affect users.
• Fix bug caused by (#556)

Development was assisted using AI.