Mpv

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.

USE flags
Default USE configuration provides the following core features: CLI player, X11 support, audio and video playback, On-Screen Display (OSD) and On-Screen Controller (OSC), and [//en.wikipedia.org/wiki/Lua_(programming_language) Lua] scripting interface.

Hardware video decoding is usually desired. mpv supports both VAAPI and VDPAU hardware decoding APIs via  and   USE flags respectively. You need to manually enable the API available on your system. mpv also supports [//developer.nvidia.com/ffmpeg CUDA] hardware decoding API via  USE flag, but it is only available on ~amd64 systems with NVIDIA GPUs and proprietary drivers.

For a complete set of features please refer to the list of USE flags below.

Additional software
Install to directly play URLs from YouTube and other popular streaming websites:

Install to have a GUI front-end:

Configuration
mpv doesn't normally require any configuration. However, many aspects of the default behaviour can be changed. Two most important parts of the configuration are player settings and key bindings. Both are briefly discussed below.

Player settings
Player settings should be put into 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 and disabled by setting them to.

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. . All following options will be a part of this profile. To end the profile, start another one or use the profile name to continue with normal options.

For a complete list of available options please refer to [//mpv.io/manual/stable/#options the manual].

Key bindings
Key bindings should be put into file using the following syntax:. Everything after the is considered a comment.

For a complete list of available commands please refer to [//mpv.io/manual/stable/#list-of-input-commands the manual].

Examples
Advanced real-world configurations from mpv contributors: [//github.com/pigoz/dotfiles/tree/master/mpv], [//github.com/Argon-/mpv-config].

Lua scripts
Core mpv functionality can be extended with [//en.wikipedia.org/wiki/Lua_(programming_language) Lua] scripts. All scripts from directory are loaded automatically. Alternatively you can load a script manually via command line, e.g. --script=/path/to/your/script.lua.

Several Lua scripts are shipped with mpv and installed into directory. Upstream wiki also has [//github.com/mpv-player/mpv/wiki/User-Scripts an extensive list of 3rd party scripts].

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  and   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  option.

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 output via   with   or.
 * VDPAU only: use output via   with   or.
 * VDPAU only: use backend for  output via.
 * Intel GPUs only: use Xorg driver from.
 * Enable dumb-mode for output via.
 * Use output via   with.

Tearing
[//en.wikipedia.org/wiki/Screen_tearing Tearing] is a video playback defect when displayed objects aren't properly lined up horizontally. Please refer to [//github.com/mpv-player/mpv/wiki/FAQ#Tearing the upstream FAQ].

Feature X is broken/unavailable with Libav
Quote from upstream: Libav is basically unsupported by mpv, except it still sort of compiles and many things work [//github.com/mpv-player/mpv/issues/3923#issuecomment-268120303]. Patches are welcome for any issues regarding Libav.

Update notes
Upstream maintains [//github.com/mpv-player/mpv/blob/master/DOCS/interface-changes.rst 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:

OSC in 0.21.0
In version 0.21.0 the default OSC layout was changed to [//raw.githubusercontent.com/mpv-player/mpv.io/master/source/images/mpv-screenshot.jpg ].

If you want to restore the previous layout, add the following [//mpv.io/manual/stable/#on-screen-controller OSC settings]:

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 [//github.com/mpv-player/mpv/wiki/Option-replacement-list#mpv-0210 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 [//github.com/mpv-player/mpv/commit/50991fac81eb56bc0985af2c9d31cd503302dcfe the offending commit's message] and [//github.com/mpv-player/mpv/issues/4144 this upstream issue] for more info.

If you want to restore the previous behaviour, use the following Lua script: autoloadtxt.lua.

Deprecated audio/video filters in 0.25.0
In version 0.25.0 many builtin audio and video filters were deprecated.

If you've been using those, migrate to [//ffmpeg.org/ffmpeg-filters.html FFmpeg]/[//libav.org/documentation/libavfilter.html Libav] filters.

External resources

 * [//github.com/mpv-player/mpv/wiki mpv wiki]
 * [//github.com/mpv-player/mpv/blob/master/DOCS/mplayer-changes.rst List of changes between mpv and mplayer]