Mpv

USE flags[edit | edit source]

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 Lua scripting interface.

Hardware video decoding is usually desired. mpv supports both VAAPI and VDPAU hardware decoding APIs via vaapi and vdpau USE flags respectively. You need to manually enable the API available on your system. mpv also supports CUDA hardware decoding API via cuda 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.

Emerge[edit | edit source]

Additional software[edit | edit source]

Install net-misc/youtube-dl to directly play URLs from YouTube and other popular streaming websites:

Install media-video/celluloid to have a GTK GUI front-end:

Player settings[edit | edit source]

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[edit | edit source]

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

Examples[edit | edit source]

Advanced real-world configurations from mpv contributors: [1], [2].

User scripts and plugins[edit | edit source]

Core mpv functionality can be extended with Lua or JavaScript scripts or C 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.

Broken playback/crashes after updating FFmpeg/Libav/libass/etc.[edit | edit source]

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[edit | edit source]

If you don't have any problems with mpv, ignore this message. Otherwise, please follow these instructions.

Broken hardware video decoding/high CPU usage[edit | edit source]

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 vainfo and 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 --hwdec-codecs=all 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 --hwdec=auto-copy.
• VAAPI only: use vaapi output via --vo=vaapi with --hwdec=vaapi or --hwdec=vaapi-copy.
• VDPAU only: use vdpau output via --vo=vdpau with --hwdec=vdpau or --hwdec=vdpau-copy.
• VDPAU only: use X11/GLX backend for opengl output via --opengl-backend=x11.
• Intel GPUs only: use modesetting Xorg driver from x11-base/xorg-server.
• Enable dumb-mode for opengl output via --opengl-dumb-mode=yes.
• Use xv output via --vo=xv with --hwdec=auto-copy.

Tearing[edit | edit source]

Tearing is a video playback defect when displayed objects aren't properly lined up horizontally. Please refer to the upstream FAQ.

Feature X is broken/unavailable with Libav[edit | edit source]

Quote from upstream: ''Libav is basically unsupported by mpv, except it still sort of compiles and many things work''[3]. Patches are welcome for any issues regarding Libav.

Volume in 0.18.1[edit | edit source]

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

OSC in 0.21.0[edit | edit source]

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

Deprecated VO/AO sub-options in 0.21.0[edit | edit source]

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[edit | edit source]

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.

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

Deprecated audio/video filters in 0.25.0[edit | edit source]

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

If you've been using those, migrate to FFmpeg/Libav filters.