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.
Installation
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) |
+cli
|
Enable the command-line player |
+drm
|
Enable Kernel Mode Setting / Direct Rendering Manager based video outputs |
+egl
|
Enable EGL (Embedded-System Graphics Library, interfacing between windowing system and OpenGL/GLES) support |
+iconv
|
Enable support for the iconv character set conversion library |
+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 |
+uchardet
|
Enable subtitles charset discovery via app-i18n/uchardet |
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 |
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 https://wiki.gentoo.org/wiki/Project:Quality_Assurance/Backtraces |
dvb
|
Add support for DVB (Digital Video Broadcasting) |
dvd
|
Add support for DVDs |
gamepad
|
Enable gamepad input support |
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 |
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: mpv_identify.sh, mpv_idet.sh, and umpv |
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 |
Emerge
root #emerge --ask media-video/mpvAdditional software
Install net-misc/yt-dlp to directly play URLs from YouTube and other popular streaming websites:
root #emerge --ask net-misc/yt-dlpInstall media-video/celluloid to have a GTK GUI front-end:
root #emerge --ask media-video/celluloidConfiguration
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.
~/.config/mpv/mpv.confPlayer settings example# 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
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.
~/.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
Examples
Advanced real-world configurations from mpv contributors: [1], [2].
Usage
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.
Troubleshooting
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=vaapiwith--hwdec=vaapior--hwdec=vaapi-copy. - VDPAU only: use vdpau output via
--vo=vdpauwith--hwdec=vdpauor--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=xvwith--hwdec=auto-copy.
Tearing
Tearing is a video playback defect when displayed objects aren't properly lined up horizontally. Please refer to the upstream FAQ.
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:
~/.config/mpv/input.confMOUSE_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:
~/.config/mpv/lua-settings/osc.conflayout=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.
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.