mpv

From Gentoo Wiki
Jump to: navigation, search
This page contains changes which are not marked for translation.

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

USE flags for media-video/mpv Media player based on MPlayer and mplayer2

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 Build mpv CLI player
coreaudio Build the CoreAudio driver on Mac OS X systems
cplugins Enable C plugins support
cuda Enable hardware video decoding via Nvidia CUDA
drm Enable Kernel Mode Setting / Direct Rendering Manager based video output
egl Enable support for various EGL-based video outputs / backends
gbm Enable Graphics Buffer Manager based EGL video backend
javascript Enable javascript support
jpeg Enable support for saving screenshots in JPEG format
lcms Add lcms support (color management engine)
libass Enable OSD (On Screen Display) and subtitles support via media-libs/libass
libcaca Add support for colored ASCII-art graphics
libmpv Build mpv shared library
lua Enable Lua scripting, OSC (On Screen Controller) GUI and net-misc/youtube-dl hook-script
openal Add support for the Open Audio Library
opengl Enable support for various OpenGL-based video backends
raspberry-pi Enable support for the Raspberry Pi
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)
tools Install extra tools: mpv_identify.sh, mpv_idet.sh, and umpv
uchardet Enable subtitles charset discovery via app-i18n/uchardet
v4l Enable support for video4linux (using linux-headers or userspace libv4l libraries)
vaapi Enable Video Acceleration API for hardware decoding
vulkan Enable support for various Vulkan-based video backends
wayland Enable dev-libs/wayland backend
zsh-completion Enable zsh completion support

Emerge

root #emerge --ask media-video/mpv

Additional software

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

root #emerge --ask net-misc/youtube-dl

Install media-video/gnome-mpv to have a GTK+ GUI front-end:

root #emerge --ask media-video/gnome-mpv

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 ~/.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
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.

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

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

Important
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

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
Note
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
layout=box
seekbarstyle=slider
deadzonesize=0
minmousemove=3
Note
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 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/Libav filters.

See also

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

External resources