Home

Awesome

Jellyfin MPV Shim

Current Release PyPI Translation Status Code Stype

Jellyfin MPV Shim is a cross-platform cast client for Jellyfin. It has support for all your advanced media files without transcoding, as well as tons of features which set it apart from other multimedia clients:

To learn more, keep reading. This README explains everything, including configuration, tips & tricks, and development information.

Getting Started

If you are on Windows, simply download the binary. If you are using Linux, you can install via flathub or install via pip. If you are on macOS, see the macOS Installation section below.

To use the client, simply launch it and log into your Jellyfin server. You’ll need to enter the URL to your server, for example http://server_ip:8096 or https://secure_domain. Make sure to include the subdirectory and port number if applicable. You can then cast your media from another Jellyfin application.

The application runs with a notification icon by default. You can use this to edit the server settings, view the application log, open the config folder, and open the application menu. Unlike Plex MPV Shim, authorization tokens for your server are stored on your device, but you are able to cast to the player regardless of location.

Note: Due to the huge number of questions and issues that have been submitted about URLs, I now tolerate bare IP addresses and not specifying the port by default. If you want to connect to port 80 instead of 8096, you must add the :80 to the URL because :8096 is now the default.

Limitations

Known Issues

Please also note that the on-screen controller for MPV (if available) cannot change the audio and subtitle track configurations for transcoded media. It also cannot load external subtitles. You must either use the menu or the application you casted from.

Please note the following issues with controlling SyncPlay:

Music playback sort-of works, but repeat, shuffle, and gapless playback have not been implemented and would require major changes to the application to properly support, as it was built for video.

The shader packs feature is sensitive to graphics hardware. It may simply just not work on your computer. You may be able to use the log files to get some more diagnostic information. If you're really unlucky, you'll have to disable the feature by pressing k to restore basic functionality. If you find the solution for your case, please send me any information you can provide, as every test case helps.

Advanced Features

Menu

To open the menu, press c on your computer or use the navigation controls in the mobile/web app.

The menu enables you to:

On your computer, use the mouse or arrow keys, enter, and escape to navigate. On your phone, use the arrow buttons, ok, back, and home to navigate.

Shader Packs

Shader packs are a recent feature addition that allows you to easily use advanced video shaders and video quality settings. These usually require a lot of configuration to use, but MPV Shim's default shader pack comes with FSRCNNX and Anime4K preconfigured. Try experimenting with video profiles! It may greatly improve your experience.

Shader Packs are ready to use as of the most recent MPV Shim version. To use, simply navigate to the Video Playback Profiles option and select a profile.

For details on the shader settings, please see default-shader-pack. If you would like to customize the shader pack, there are details in the configuration section.

SVP Integration

SVP integration allows you to easily configure SVP support, change profiles, and enable/disable SVP without having to exit the player. It is not enabled by default, please see the configuration instructions for instructions on how to enable it.

Display Mirroring

This feature allows media previews to show on your display before you cast the media, similar to Chromecast. It is not enabled by default. To enable it, do one of the following:

Then restart the application for the change to take effect. To quit the application on Windows with display mirroring enabled, press Alt+F4.

Keyboard Shortcuts

This program supports most of the keyboard shortcuts from MPV. The custom keyboard shortcuts are:

Here are the notable MPV keyboard shortcuts:

Configuration

The configuration file is located in different places depending on your platform. You can also open the configuration folder using the systray icon if you are using the shim version. When you launch the program on Linux or macOS from the terminal, the location of the config file will be printed. The locations are:

You can specify a custom configuration folder with the --config option.

Transcoding

You can adjust the basic transcoder settings via the menu.

Features

You can use the config file to enable and disable features.

Shell Command Triggers

You can execute shell commands on media state using the config file:

Subtitle Visual Settings

These settings may not works for some subtitle codecs or if subtitles are being burned in during a transcode. You can configure custom styled subtitle settings through the MPV config file.

External MPV

The client now supports using an external copy of MPV, including one that is running prior to starting the client. This may be useful if your distribution only provides MPV as a binary executable (instead of as a shared library), or to connect to MPV-based GUI players. Please note that SMPlayer exhibits strange behaviour when controlled in this manner. External MPV is currently the only working backend for media playback on macOS. Additionally, due to Flatpak sandbox restrictions, external mpv is not practical to use in most cases for the Flatpak version.

Keyboard Shortcuts

You can reconfigure the custom keyboard shortcuts. You can also set them to null to disable the shortcut. Please note that disabling keyboard shortcuts may make some features unusable. Additionally, if you remap q, using the default shortcut will crash the player.

Shader Packs

Shader packs allow you to import MPV config and shader presets into MPV Shim and easily switch between them at runtime through the built-in menu. This enables easy usage and switching of advanced MPV video playback options, such as video upscaling, while being easy to use.

If you select one of the presets from the shader pack, it will override some MPV configurations and any shaders manually specified in mpv.conf. If you would like to customize the shader pack, use shader_pack_custom.

Trickplay Thumbnails

MPV will automatically display thumbnail previews. By default it uses the Trickplay images and falls back to chapter images. Please note that this feature will download and uncompress all of the chapter images before it becomes available for a video. For a 4 hour movie this causes disk usage of about 250 MB, but for the average TV episode it is around 40 MB. It also requires overriding the default MPV OSC, which may conflict with some custom user script. Trickplay is compatible with any OSC that uses thumbfast, as I have added a compatibility layer.

SVP Integration

To enable SVP integration, set svp_enable to true and enable "External control via HTTP" within SVP under Settings > Control options. Adjust the svp_url and svp_socket settings if needed.

Currently on Windows the built-in MPV does not work with SVP. You must download MPV yourself.

SyncPlay

You probably don't need to change these, but they are defined here in case you need to.

Debugging

These settings assist with debugging. You will often be asked to configure them when reporting an issue.

Other Configuration Options

Other miscellaneous configuration options. You probably won't have to change these.

Skip Intro Support

This functionality is considered experimental and requires the third-party SkipIntro server plugin. It works the same ways as it did on MPV Shim for Plex.

MPV Configuration

You can configure mpv directly using the mpv.conf and input.conf files. (It is in the same folder as conf.json.) This may be useful for customizing video upscaling, keyboard shortcuts, or controlling the application via the mpv IPC server.

Authorization

The cred.json file contains the authorization information. If you are having problems with the client, such as the Now Playing not appearing or want to delete a server, you can delete this file and add the servers again.

Tips and Tricks

Various tips have been found that allow the media player to support special functionality, albeit with more configuration required.

Open on Specific Monitor (#19)

Please note: Edits to the mpv.conf will not take effect until you restart the application. You can open the config directory by using the menu option in the system tray icon.

Option 1: Select fullscreen output screen through MPV. Determine which screen you would like MPV to show up on.

Add the following to your mpv.conf in the config directory, replacing 0 with the number from the previous step:

fs=yes
fs-screen=0

Option 2: (Linux Only) If option 1 does not work, both of your monitors are likely configured as a single "screen".

Run xrandr. It should look something like this:

Screen 0: minimum 8 x 8, current 3520 x 1080, maximum 16384 x 16384
VGA-0 connected 1920x1080+0+0 (normal left inverted right x axis y axis) 521mm x 293mm
   1920x1080     60.00*+
   1680x1050     59.95
   1440x900      59.89
   1280x1024     75.02    60.02
   1280x960      60.00
   1280x800      59.81
   1280x720      60.00
   1152x864      75.00
   1024x768      75.03    70.07    60.00
   800x600       75.00    72.19    60.32    56.25
   640x480       75.00    59.94
LVDS-0 connected 1600x900+1920+180 (normal left inverted right x axis y axis) 309mm x 174mm
   1600x900      59.98*+

If you want MPV to open on VGA-0 for instance, add the following to your mpv.conf in the config directory:

fs=yes
geometry=1920x1080+0+0

Option 3: (Linux Only) If your window manager supports it, you can tell the window manager to always open on a specific screen.

Control Volume with Mouse Wheel (#48)

Add the following to input.conf:

WHEEL_UP add volume 5
WHEEL_DOWN add volume -5

MPRIS Plugin (#54)

Set mpv_ext to true in the config. Add script=/path/to/mpris.so to mpv.conf.

Run Multiple Instances (#45)

You can pass --config /path/to/folder to run another copy of the player. Please note that running multiple copies of the desktop client is currently not supported.

Audio Passthrough

You can edit mpv.conf to support audio passthrough. A user on Reddit had luck with this config:

audio-spdif=ac3,dts,eac3 # (to use the passthrough to receiver over hdmi)
audio-channels=2 # (not sure this is necessary, but i keep it in because it works)
af=scaletempo,lavcac3enc=yes:640:3 # (for aac 5.1 tracks to the receiver)

MPV Crashes with "The sub-scale option must be a floating point number or a ratio"

Run the jellyfin-mpv-shim program with LC_NUMERIC=C.

Use with gnome-mpv/celluloid (#61)

You can use gnome-mpv with MPV Shim, but you must launch gnome-mpv separately before MPV Shim. (gnome-mpv doesn't support the MPV command options directly.)

Configure MPV Shim with the following options (leave the other ones):

{
    "mpv_ext": true,
    "mpv_ext_ipc": "/tmp/gmpv-socket",
    "mpv_ext_path": null,
    "mpv_ext_start": false,
    "enable_osc": false
}

Then within gnome-mpv, click the application icon (top left) > Preferences. Configure the following Extra MPV Options:

--idle --input-ipc-server=/tmp/gmpv-socket

Heavy Memory Usage

A problem has been identified where MPV can use a ton of RAM after media has been played, and this RAM is not always freed when the player goes into idle mode. Some users have found that using external MPV lessens the memory leak. To enable external MPV on Windows:

On Linux, the process is similar, except that you don't need to set the mpv_ext_path variable. On macOS, external MPV is already the default and is the only supported player mode.

In the long term, I may look into a method of terminating MPV when not in use. This will require a lot of changes to the software.

Player Sizing (#91)

MPV by default may force the window size to match the video aspect ratio, instead of allowing resizing and centering the video accordingly. Add the following to mpv.conf to enable resizing of the window freely, if desired:

no-keepaspect-window

Development

If you'd like to run the application without installing it, run ./run.py. The project is written entirely in Python 3. There are no closed-source components in this project. It is fully hackable.

The project is dependent on python-mpv, python-mpv-jsonipc, and jellyfin-apiclient-python. If you are using Windows and would like mpv to be maximize properly, pywin32 is also needed. The GUI component uses pystray and tkinter, but there is a fallback cli mode. The mirroring dependencies are Jinja2 and pywebview, along with platform-specific dependencies. (See the installation and building guides for details on platform-specific dependencies for display mirroring.)

This project is based Plex MPV Shim, which is based on https://github.com/wnielson/omplex, which is available under the terms of the MIT License. The project was ported to python3, modified to use mpv as the player, and updated to allow all features of the remote control api for video playback.

The Jellyfin API client comes from Jellyfin for Kodi. The API client was originally forked for this project and is now a separate package.

The css file for desktop mirroring is from jellyfin-chromecast and is subject to GPL v2.0.

The shaders included in the shader pack are also available under verious open source licenses, which you can read about here.

Local Dev Installation

If you are on Windows there are additional dependencies. Please see the Windows Build Instructions.

  1. Install the dependencies: pip3 install --upgrade python-mpv jellyfin-apiclient-python pystray Jinja2 pywebview python-mpv-jsonipc pypresence.
    • If you run ./gen_pkg.sh --install, it will also fetch these for you.
    • Note: Recent distributions make pip unusable by default. Consider using conda or add a virtualenv to your user's path.
  2. Clone this repository: git clone https://github.com/jellyfin/jellyfin-mpv-shim
    • You can also download a zip build.
  3. cd to the repository: cd jellyfin-mpv-shim
  4. Run prepare script: ./gen_pkg.sh
    • To do this manually, download the web client, shader pack, and build the language files.
  5. Ensure you have a copy of libmpv1 or mpv available.
  6. Install any platform-specific dependencies from the respective install tutorials.
  7. You should now be able to run the program with ./run.py. Installation is possible with sudo pip3 install ..
    • You can also install the package with ./gen_pkg.sh --install.

Translation

This project uses gettext for translation. The current template language file is base.pot in jellyfin_mpv_shim/messages/.

To regenerate base.pot and update an existing translation with new strings:

./regen_pot.sh

To compile all *.po files to *.mo:

./gen_pkg.sh --skip-build

Linux Installation

You can install the software from flathub. The pip installation is less integrated but takes up less space if you're not already using flatpak.

If you are on Linux, you can install via pip. You'll need libmpv1 or mpv installed.

sudo pip3 install --upgrade jellyfin-mpv-shim

If you would like the GUI and systray features, also install pystray and tkinter:

sudo pip3 install pystray
sudo apt install python3-tk

If you would like display mirroring support, install the mirroring dependencies:

sudo apt install python3-jinja2 python3-webview
# -- OR --
sudo pip3 install jellyfin-mpv-shim[mirror]
sudo apt install gir1.2-webkit2-4.0

Discord rich presence support:

sudo pip3 install jellyfin-mpv-shim[discord]

You can build mpv from source to get better codec support. Execute the following:

sudo pip3 install --upgrade python-mpv
sudo apt install autoconf automake libtool libharfbuzz-dev libfreetype6-dev libfontconfig1-dev libx11-dev libxrandr-dev libvdpau-dev libva-dev mesa-common-dev libegl1-mesa-dev yasm libasound2-dev libpulse-dev libuchardet-dev zlib1g-dev libfribidi-dev git libgnutls28-dev libgl1-mesa-dev libsdl2-dev cmake wget python g++ libluajit-5.1-dev
git clone https://github.com/mpv-player/mpv-build.git
cd mpv-build
echo --enable-libmpv-shared > mpv_options
./rebuild -j4
sudo ./install
sudo ldconfig

<h2 id="osx-installation">macOS Installation</h2>

Currently on macOS only the external MPV backend seems to be working. I cannot test on macOS, so please report any issues you find.

To install the CLI version:

  1. Install brew. (Instructions)
  2. Install python3 and mpv. brew install python mpv
  3. Install jellyfin-mpv-shim. pip3 install --upgrade jellyfin-mpv-shim
  4. Run jellyfin-mpv-shim.

If you'd like to install the GUI version, you need a working copy of tkinter.

  1. Install pyenv. (Instructions)
  2. Install TK and mpv. brew install tcl-tk mpv
  3. Install python3 with TK support. FLAGS="-I$(brew --prefix tcl-tk)/include" pyenv install 3.8.1
  4. Set this python3 as the default. pyenv global 3.8.1
  5. Install jellyfin-mpv-shim and pystray. pip3 install --upgrade 'jellyfin-mpv-shim[gui]'
  6. Run jellyfin-mpv-shim.

Display mirroring is not tested on macOS, but may be installable with 'pip3 install --upgrade 'jellyfin-mpv-shim[mirror]'`.

Building on Windows

There is a prebuilt version for Windows in the releases section. When following these directions, please take care to ensure both the python and libmpv libraries are either 64 or 32 bit. (Don't mismatch them.)

If you'd like to build the installer, please install Inno Setup to build the installer. If you'd like to build a 32 bit version, download the 32 bit version of mpv-1.dll and copy it into a new folder called mpv32. You'll also need WebBrowserInterop.x86.dll. You may also need to edit the batch file for 32 bit builds to point to the right python executable.

  1. Install Git for Windows. Open Git Bash and run git clone https://github.com/jellyfin/jellyfin-mpv-shim; cd jellyfin-mpv-shim.
    • You can update the project later with git pull.
  2. Install Python3 with PATH enabled. Install 7zip.
  3. After installing python3, open cmd as admin and run pip install --upgrade pyinstaller python-mpv jellyfin-apiclient-python pywin32 pystray Jinja2 pywebview python-mpv-jsonipc pypresence.
  4. Download libmpv.
  5. Extract the mpv-2.dll from the file and move it to the jellyfin-mpv-shim folder.
  6. Open a regular cmd prompt. Navigate to the jellyfin-mpv-shim folder.
  7. Run get_pywebview_natives.py.
  8. Run ./gen_pkg.sh --skip-build using the Git for Windows console.
    • This builds the translation files and downloads the shader packs.
  9. Run build-win.bat.