Skip to main content

Plex MPV Shim

Plex MPV Shim is a simple and lightweight Plex client. It supports Windows and Linux and is easy to install. The project offers an experience similar to Chromecast, but with direct play and subtitle support. The application requires another app to play content and does not save login information, making it ideal for applications where security is a concern. This project is significantly smaller and less complicated than Plex Media Player, and is written entirely in open-source Python.

The project supports the following:

  • Direct play of HEVC mkv files with subtitles.
  • Switching of subtitles and audio tracks.
  • Casting videos from the iOS mobile app and web app.
  • Seeking within a video using the seek bar and buttons.
  • Play, pause, and stop.
  • Using the built-in MPV controls. (OSD and keyboard shortcuts.)
  • Configuration of mpv via mpv.conf.
  • Connecting to shared servers.
  • Installing the package system-wide.
  • Skipping between videos.
  • Autoplaying the next video. (Can be disabled.)
  • Extra keyboard shortcuts: < > skip, u unwatched/stop, w watched/next
  • Playing multiple videos in a queue.
  • The app doesn't require or save any Plex passwords or tokens.
  • Executing commands before playing, after media end, and when stopped.
  • Configurable transcoding support. (Please see the section below.)
  • The application shows up in Plex dashboard and usage tracking.

You'll need libmpv1. To install plex-mpv-shim, run:

sudo pip3 install --upgrade plex-mpv-shim

The current Debian package for libmpv1 doesn't support the on-screen controller. If you'd like this, or need codecs that aren't packaged with Debian, you need to build mpv from source. Execute the following:

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

After installing the project, you can run it with plex-mpv-shim. If you'd like to run it without installing it, run ./run.py.

Keyboard Shortcuts:

  • Standard MPV shortcuts.
  • < > to skip episodes
  • q to close player
  • w to mark watched and skip
  • u to mark unwatched and quit

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

  • media_ended_cmd - When all media has played.
  • pre_media_cmd - Before the player displays. (Will wait for finish.)
  • stop_cmd - After stopping the player.
  • idle_cmd - After no activity for idle_cmd_delay seconds.

This project 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.

Interactive Menu

Plex-MPV-Shim 1.3 introduces the interactive menu. This allows for features that would be impossible to support through the remote control interface normally, such as:

  • Change subtitle or audio tracks. The full titles from the media file are shown.
  • Automatically change the subtitle and audio streams for an entire series at once.
  • Adjust video transcoding quality without restarting.
  • Change transcoding preferences without editing the config file.
  • Quit the player, marking the current video unwatched.

The interactive menu supports both the keyboard and the remote control. To open the menu from a phone, press the ok or home button. Press back to go back or close the menu. The keyboard shortcut to open the menu is c. Use the arrow keys, escape, and enter/space to navigate the menu.

Transcoding Support

Plex-MPV-Shim 1.2 introduces revamped transcoding support. It will automatically ask the server to see if transcoding is suggested, which enables Plex-MPV-Shim to play more of your library on the go. You can configure this or switch to the old local transcode decision system.

  • always_transcode: This will tell the client to always transcode, without asking. Default: false
    • This may be useful if you are using limited hardware that cannot handle advanced codecs.
    • You may have some luck changing client_profile in the configuration to a more restrictive one.
  • auto_transcode: This will ask the server to determine if transcoding is suggested. Default: true
    • transcode_kbps: Transcode bandwidth to request. Default: 2000
  • remote_transcode: This will check for transcoding using locally available metadata for remote servers only. Default: true
    • This will not take effect if auto_transcode is enabled.
    • Configuration options from auto_transcode are also used.
    • remote_kbps_thresh: The threshold to force transcoding. If this is lower than the configured server bandwidth, playback may fail.
  • adaptive_transcode: Tell the server to adjust the quality while streaming. Default: false

Pleas Note: Controlling Plex-MPV-Shim from the Plex web application only works on a LAN where a Plex Server resides. It does NOT have to be the one you are streaming from. An empty server will work.

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.)

  1. Install Python3 with PATH enabled. Install 7zip.
  2. After installing python3, open cmd as admin and run pip install pyinstaller python-mpv requests.
  3. Download libmpv.
  4. Extract the mpv-1.dll from the file and move it to the plex-mpv-shim folder.
  5. Open a regular cmd prompt. Navigate to the plex-mpv-shim folder.
  6. Run pyinstaller -cF --add-binary "mpv-1.dll;." --icon media.ico run.py.

Usage

To use plex-mpv-shim you merely need to start the application.

Your firewall will need to allow inbound TCP 3000 (for this application's web server) and inbound UDP 32410, 32412, 32413, 32414 (Plex's GDM ports).

Metadata

Release files for plex-mpv-shim 1.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for plex-mpv-shim 1.3.0
File Size Uploaded Provenance Actions
plex-mpv-shim-1.3.0.tar.gz 29.7 kB Without provenance Details for plex-mpv-shim-1.3.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for plex-mpv-shim 1.3.0
File Interpreter ABI Platform Actions
plex_mpv_shim-1.3.0-py3-none-any.whl Python 3 none any Details for plex_mpv_shim-1.3.0-py3-none-any.whl

Total release size: 61.1 kB

Release files / plex-mpv-shim-1.3.0.tar.gz

Download URL plex-mpv-shim-1.3.0.tar.gz
Size 29.7 kB
Tags Source
SHA-256 checksum
How to use checksums
50b53e3dfb68bc1d240bcaada405c32402bafa9bb5474f5def02626395ba9154
BLAKE2b-256 checksum
How to use checksums
d08e62cf75e6157c0b55beb026b6ab873612a922830f7ceac183e9f679ae0b58
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/1.14.0 pkginfo/1.5.0.1 requests/2.18.4 setuptools/41.2.0 requests-toolbelt/0.9.1 tqdm/4.28.1 CPython/3.7.3

Release files / plex_mpv_shim-1.3.0-py3-none-any.whl

Download URL plex_mpv_shim-1.3.0-py3-none-any.whl
Size 31.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
0cdd5a5857f771a6e90e4968912e9c5f6b83f3e0a393c6f4738da410800539f5
BLAKE2b-256 checksum
How to use checksums
d69d4b9bc3b5ff2987eb77901158d1ef9f0539da13c3679ee826ebd0ba7eaba8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/1.14.0 pkginfo/1.5.0.1 requests/2.18.4 setuptools/41.2.0 requests-toolbelt/0.9.1 tqdm/4.28.1 CPython/3.7.3

Security for plex-mpv-shim 1.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.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.3.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page