From Gentoo Wiki
Jump to:navigation Jump to:search
Other languages:

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, 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 vaapi and 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

X Add support for X11
alsa Add support for media-libs/alsa-lib (Advanced Linux Sound Architecture)
aqua Include support for the Mac OS X Aqua (Carbon/Cocoa) GUI
archive Enable support for various archive formats via app-arch/libarchive
bluray Enable playback of Blu-ray filesystems
cdda Add Compact Disk Digital Audio (Standard Audio CD) support
cli Enable the command-line player
coreaudio Build the CoreAudio driver on Mac OS X systems
debug Enable extra debug codepaths, like asserts and extra output. If you want to get meaningful backtraces see
drm Enable Kernel Mode Setting / Direct Rendering Manager based video outputs
dvb Add support for DVB (Digital Video Broadcasting)
dvd Add support for DVDs
egl Enable EGL (Embedded-System Graphics Library, interfacing between windowing system and OpenGL/GLES) support
gamepad Enable gamepad input support
iconv Enable support for the iconv character set conversion library
jack Add support for the JACK Audio Connection Kit
javascript Enable javascript support
jpeg Add JPEG image support
lcms Add lcms support (color management engine)
libcaca Add support for colored ASCII-art graphics
libmpv Enable the shared library and headers (used by frontends / plugins)
lua Enable Lua scripting, OSC (On Screen Controller) GUI, and net-misc/yt-dlp support
nvenc Add support for NVIDIA Encoder/Decoder (NVENC/NVDEC) API for hardware accelerated encoding and decoding on NVIDIA cards (requires x11-drivers/nvidia-drivers)
openal Add support for the Open Audio Library
opengl Enable support for OpenGL-based video backends (Note: deprecated for X11, USE=egl provides the newer support for -gpu-api=opengl)
pipewire Enable sound support via native PipeWire backend
pulseaudio Add sound server support via media-libs/libpulse (may be PulseAudio or PipeWire)
rubberband Enable high quality pitch correction via media-libs/rubberband
sdl Enable media-libs/libsdl2 based video and audio outputs (Note: these outputs exist for compatibility reasons only, avoid if possible)
selinux !!internal use only!! Security Enhanced Linux support, this must be set by the selinux profile or breakage will occur
sixel Enable support for the sixel video backend using media-libs/libsixel
sndio Enable sound support via media-sound/sndio
soc Use additional media-video/ffmpeg patches for efficient playback on some SoCs (e.g. ARM, RISC-V)
test Enable dependencies and/or preparations necessary to run tests (usually controlled by FEATURES=test but can be toggled independently)
tools Install extra tools:,, and umpv
uchardet Enable subtitles charset discovery via app-i18n/uchardet
vaapi Enable Video Acceleration API for hardware decoding
vdpau Enable the Video Decode and Presentation API for Unix acceleration interface
vulkan Add support for 3D graphics and computing via the Vulkan cross-platform API
wayland Enable dev-libs/wayland backend
xv Add in optional support for the Xvideo extension (an X API for video playback)
zimg Enable libzimg support (for vf_fingerprint)
zlib Add support for zlib compression


root #emerge --ask media-video/mpv

Additional software

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

root #emerge --ask net-misc/yt-dlp

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

root #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

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.

FILE ~/.config/mpv/mpv.confPlayer settings example
# Always allow seeking, e.g. allow seeking within a local cache of HTTP stream
# Always open a video window even with no video
# Don't exit when the end of playlist is reached
# Always save the current playback position on exit
# Create 'high-quality' profile
# Describe this profile
profile-desc="High quality rendering"
# Include all settings from the default 'opengl-hq' profile
# Disable debanding for better performance

Key bindings

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.

FILE ~/.config/mpv/input.confKey bindings example
# 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


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


User scripts and plugins

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.


If you have any problems with mpv, enable either logging to a file via --log-file option or verbose terminal output via -v option.

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

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.

Update notes

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:

FILE ~/.config/mpv/input.conf
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:

FILE ~/.config/mpv/lua-settings/osc.conf
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.

If you want to restore the previous behavior, 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/Libav filters.

See also

  • MPlayer — a powerful command-line media player
  • VLC — a wildly popular, cross platform video player and streamer.

External resources