mpv is a free and open source command-line media player. It is based on mplayer2, which in turn is based on the original MPlayer. Although there are still many similarities to its ancestors, mpv should generally be treated as a completely different program.
Default USE configuration provides the following core features: CLI player, Xorg support, audio and video playback, On-Screen Display (OSD) and On-Screen Controller (OSC), and Lua scripting interface.
Hardware video decoding is usually desired. mpv supports both VAAPI and VDPAU hardware decoding APIs via
vdpau USE flags respectively. You need to manually enable the API available on your system. mpv also supports NVDEC hardware decoding API via
nvenc USE flag (requires proprietary nvidia-drivers).
For a complete set of features please refer to the list of USE flags below.
USE flags for media-video/mpv Media player for the command line
||Add support for X11|
||Add support for media-libs/alsa-lib (Advanced Linux Sound Architecture)|
||Include support for the Mac OS X Aqua (Carbon/Cocoa) GUI|
||Enable support for various archive formats via app-arch/libarchive|
||Enable playback of Blu-ray filesystems|
||Add Compact Disk Digital Audio (Standard Audio CD) support|
||Enable the command-line player|
||Build the CoreAudio driver on Mac OS X systems|
||Enable extra debug codepaths, like asserts and extra output. If you want to get meaningful backtraces see https://wiki.gentoo.org/wiki/Project:Quality_Assurance/Backtraces|
||Enable Kernel Mode Setting / Direct Rendering Manager based video outputs|
||Add support for DVB (Digital Video Broadcasting)|
||Add support for DVDs|
||Enable support for various EGL-based video outputs / backends|
||Enable gamepad input support|
||Enable support for the iconv character set conversion library|
||Add support for the JACK Audio Connection Kit|
||Add JPEG image support|
||Add lcms support (color management engine)|
||Add support for colored ASCII-art graphics|
||Enable the shared library and headers (used by frontends / plugins)|
||Enable support for GPU accelerated video rendering with media-libs/libplacebo|
||Enable Lua scripting, OSC (On Screen Controller) GUI, and net-misc/yt-dlp support|
||Enable Multi-Media Abstraction Layer (MMAL) decoding support: Available e.g. on the Raspberry Pi|
||Add support for NVIDIA Encoder/Decoder (NVENC/NVDEC) API for hardware accelerated encoding and decoding on NVIDIA cards (requires x11-drivers/nvidia-drivers)|
||Add support for the Open Audio Library|
||Enable support for OpenGL-based video backends (Note: deprecated for X11, USE=egl provides the newer support for -gpu-api=opengl)|
||Enable sound support via native PipeWire backend|
||Add sound server support via media-libs/libpulse (may be PulseAudio or PipeWire)|
||Enable support for the Raspberry Pi|
||Enable high quality pitch correction via media-libs/rubberband|
||Enable media-libs/libsdl2 based video and audio outputs (Note: these outputs exist for compatibility reasons only, avoid if possible)|
||!!internal use only!! Security Enhanced Linux support, this must be set by the selinux profile or breakage will occur|
||Enable support for the sixel video backend using media-libs/libsixel|
||Enable sound support via media-sound/sndio|
||Enable dependencies and/or preparations necessary to run tests (usually controlled by FEATURES=test but can be toggled independently)|
||Install extra tools: mpv_identify.sh, mpv_idet.sh, and umpv|
||Enable subtitles charset discovery via app-i18n/uchardet|
||Enable Video Acceleration API for hardware decoding|
||Enable the Video Decode and Presentation API for Unix acceleration interface|
||Add support for 3D graphics and computing via the Vulkan cross-platform API|
||Enable dev-libs/wayland backend|
||Add in optional support for the Xvideo extension (an X API for video playback)|
||Enable libzimg support (for vf_fingerprint)|
||Add support for zlib (de)compression|
emerge --ask media-video/mpv
Install net-misc/yt-dlp to directly play URLs from YouTube and other popular streaming websites:
emerge --ask net-misc/yt-dlp
Install media-video/celluloid to have a GTK GUI front-end:
emerge --ask media-video/celluloid
mpv doesn't normally require any configuration. However, many aspects of the default behavior can be changed. Two most important parts of the configuration are player settings and key bindings. Both are briefly discussed below.
Player settings should be put into ~/.config/mpv/mpv.conf file using the following syntax: option=value. Everything after the # is considered a comment.
Nearly all command line options can be player settings. In most cases the equivalent of --option=value command line argument is option=value setting. Options that work without values can be enabled by setting them to yes and disabled by setting them to no.
To ease working with different configurations, profiles can be defined in the configuration file. A profile starts with its name in square brackets, e.g. [my-profile]. All following options will be a part of this profile. To end the profile, start another one or use the profile name default to continue with normal options.
For a complete list of available options please refer to the manual.
# Always allow seeking, e.g. allow seeking within a local cache of HTTP stream force-seekable=yes # Always open a video window even with no video force-window=yes # Don't exit when the end of playlist is reached keep-open=yes # Always save the current playback position on exit save-position-on-quit=yes # Create 'high-quality' profile [high-quality] # Describe this profile profile-desc="High quality rendering" # Include all settings from the default 'opengl-hq' profile profile=opengl-hq # Disable debanding for better performance deband=no
Key bindings should be put into ~/.config/mpv/input.conf file using the following syntax: key command. Everything after the # is considered a comment.
For a complete list of available commands please refer to the manual.
# Ctrl+q closes player Ctrl+q quit # D removes the current file from playlist D playlist-remove current # R shuffles the current playlist R playlist-shuffle
User scripts and plugins
All scripts and plugins from ~/.config/mpv/scripts/ directory are loaded automatically. Alternatively you can load a script or a plugin manually via command line, e.g. --script=/path/to/your/script.file.
Several Lua scripts are shipped with mpv and installed into /usr/share/mpv/lua/ directory. Upstream wiki also has an extensive list of 3rd party scripts and plugins.
If you have any problems with mpv, enable either logging to a file via
--log-fileoption or verbose terminal output via
Broken playback/crashes after updating FFmpeg/Libav/libass/etc.
TLDR: report a Gentoo bug, then rebuild mpv.
FFmpeg/Libav/libass are all known to introduce from time to time incompatible, ABI-breaking changes between minor releases. Usually SLOTs of these libraries remain the same between minor releases, i.e. an automatic mpv rebuild isn't triggered. This causes problems with mpv compiled against previous versions of these libraries. These problems vary from broken pieces of functionality to sudden crashes.
Upstream's answer in such cases is similar to "it's not our problem that others can't maintain proper ABI-compatibility, rebuild mpv". Please first report a Gentoo bug to notify maintainers about the existing breakage, then rebuild mpv.
"mpv was compiled against a different version of FFmpeg..." message
If you don't have any problems with mpv, ignore this message. Otherwise, please follow these instructions.
Broken hardware video decoding/high CPU usage
Always consult mpv log for any problems regarding hardware decoding. High CPU usage during video playback is a symptom of broken hardware decoding.
Firstly, make sure that your hardware supports the required video codec. The list of codecs supported by your GPU is available via
vdpauinfo commands for VAAPI and VDPAU decoding APIs respectively. The codec used in your video file is available in mpv log. If your GPU supports the required codec, but mpv doesn't do hardware decoding, try with
Secondly, make sure that you have the latest non-live (not 9999) mpv version available in tree. If the update to the latest version solves the problem, please report a Gentoo bug.
Now there are several things you can try:
- Enable hardware decoder with copy-back via
- VAAPI only: use vaapi output via
- VDPAU only: use vdpau output via
- VDPAU only: use X11/GLX backend for opengl output via
- Intel GPUs only: use modesetting Xorg driver from x11-base/xorg-server.
- Enable dumb-mode for opengl output via
- Use xv output via
Quote from upstream: "Libav is basically unsupported by mpv, except it still sort of compiles and many things work" . Patches are welcome for any issues regarding Libav.
Upstream maintains a list of user-visible changes. The most important ones are discussed below.
Volume in 0.18.1
Since version 0.18.1 the software volume control is always enabled. This means that volume controls don't change the system volume, e.g. per-application volume with PulseAudio.
If you want to restore the previous behaviour, define the following key bindings:
MOUSE_BTN5 add ao-volume -2 MOUSE_BTN6 add ao-volume +2 9 add ao-volume -2 0 add ao-volume +2 / add ao-volume -2 * add ao-volume +2 m cycle ao-mute VOLUME_DOWN add ao-volume -2 VOLUME_UP add ao-volume +2 MUTE cycle ao-mute
This covers only default volume key bindings as of version 0.18.0.
OSC in 0.21.0
In version 0.21.0 the default OSC layout was changed to bottombar.
If you want to restore the previous layout, add the following OSC settings:
layout=box seekbarstyle=slider deadzonesize=0 minmousemove=3
This covers only the default OSC layout as of version 0.20.0.
Deprecated VO/AO sub-options in 0.21.0
In version 0.21.0 all VO/AO sub-options were deprecated and replaced by options.
If you've been using those, refer to this replacement list.
Subtitles with .txt extension in 0.24.0
Since version 0.24.0 subtitles with .txt extension are no longer recognized as subtitles and thus no longer autoloaded. Please refer to the offending commit's message and this upstream issue for more info.
Deprecated audio/video filters in 0.25.0
In version 0.25.0 many builtin audio and video filters were deprecated.
- MPlayer — a powerful command-line media player
- VLC — a wildly popular, cross platform video player and streamer.