Difference between revisions of "Mpv"

From ArchWiki
Jump to: navigation, search
(Hardware Decoding)
(Tips and Tricks: add gnome wayland screen saver inhibitor)
 
(204 intermediate revisions by 70 users not shown)
Line 1: Line 1:
[[Category:Player]]
+
{{Lowercase title}}
From the [https://github.com/mpv-player/mpv development page]:
+
[[Category:Multimedia players]]
: ''Movie player based on [[MPlayer]] and mplayer2. It supports a wide variety of video file formats, audio and video codecs, and subtitle types. If you are wondering what's different from mplayer2 and MPlayer you can read more about the [https://github.com/mpv-player/mpv/blob/master/DOCS/man/en/changes.rst changes].''
+
[[ja:Mpv]]
 +
[[ru:Mpv]]
 +
[[zh-hans:Mpv]]
 +
{{Related articles start}}
 +
{{Related|MPlayer}}
 +
{{Related articles end}}
 +
 
 +
[https://mpv.io/ mpv] is a media player based on [[MPlayer]] and MPlayer2. It supports a wide variety of video file formats, audio and video codecs, and subtitle types. A comprehensive (although admittedly incomplete) list of differences between ''mpv'' and the aforementioned players can be found [https://github.com/mpv-player/mpv/blob/master/DOCS/mplayer-changes.rst here].
  
 
== Installation ==
 
== Installation ==
  
[[pacman|Install]] {{Pkg|mpv}} from the [[official repositories]] or {{AUR|mpv-git}} from the [[AUR]]. Alternatively install {{AUR|cmplayer}} or {{AUR|cmplayer-git}} Qt5 frontend which provides its own ''mpv''.
+
[[Install]] the {{Pkg|mpv}} package or {{AUR|mpv-git}} for the development version.
 +
 
 +
=== Front ends ===
 +
 
 +
mpv comes with a minimal GUI called On Screen Controller (OSC), that appears when moving the mouse. There are also other front ends available:
 +
 
 +
* {{App|Baka MPlayer|Free and open source, cross-platform, ''libmpv'' based multimedia player (Qt 5).|http://bakamplayer.u8sand.net/|{{Pkg|baka-mplayer}}, {{AUR|baka-mplayer-git}}}}
 +
* {{App|GNOME MPV|A simple frontend for ''mpv'' (GTK+ 3).|https://gnome-mpv.github.io/|{{AUR|gnome-mpv}}, {{AUR|gnome-mpv-git}}}}
 +
* {{App|Media Player Classic Qute Theater|A clone of [[Wikipedia:Media Player Classic|Media Player Classic]] reimplimented in Qt.|https://github.com/cmdrkotori/mpc-qt|{{AUR|mpc-qt-git}}}}
 +
* {{App|[[Wikipedia:SMPlayer|SMPlayer]]|Qt multimedia player with extra features (CSS themes, YouTube integration, etc.) (Qt 5).|https://www.smplayer.info/|{{Pkg|smplayer}}}}
 +
* {{App|xt7-player-mpv|Qt/Gambas GUI to mpv with a rich set of configurable options including filters and drivers, ladspa plugins support as well as library/playlist managment, YouTube, online radios, podcasts, DVB-T and more.|https://github.com/kokoko3k/xt7-player-mpv|{{AUR|xt7-player-mpv-git}}}}
 +
 
 +
=== Forks ===
 +
 
 +
* {{App|bomi|Powerful and easy to use multimedia player (Qt 5).|https://bomi-player.github.io/|{{AUR|bomi}}, {{AUR|bomi-git}}}}
  
 
== Configuration ==
 
== Configuration ==
  
System-wide configuration is located in {{ic|/etc/mpv/mpv.conf}}, whereas the user-local settings are stored in {{ic|~/.mpv/config}}. The complete list of options is located [https://github.com/mpv-player/mpv/blob/master/DOCS/man/en/options.rst here].
+
''mpv'''s configuration is read from the files {{ic|mpv.conf}} (settings), {{ic|input.conf}} (key bindings), and {{ic|lua-settings/osc.conf}} (on screen display). For a full list of options, see the {{man|1|mpv|url=https://mpv.io/manual/master/}} or the [https://github.com/mpv-player/mpv/tree/master/DOCS/man GitHub docs].
{{Tip|If you prefer a custom location for configurations, set the {{ic|MPV_HOME}} variable as you like in your shell configuration file. A predictable choice is {{ic|<nowiki>MPV_HOME=$XDG_CONFIG_HOME/mpv</nowiki>}}.}}
+
 
 +
If the [[environment variable]] {{ic|XDG_CONFIG_HOME}} is not set, user configuration files will be read from the {{ic|~/.config/mpv}} directory. System-wide configuration files are read from the {{ic|/etc/mpv}} directory.
 +
 
 +
=== An example input.conf file ===
  
An example configuration:
+
Copying the following into {{ic|~/.config/mpv/input.conf}} will add a number of useful keybindings to mpv such as rotating video 90 degrees, zooming and panning.
{{bc|1=
 
# default configuration that applies to every file
 
[default]
 
  
# try to use high quality opengl output, with standard opengl, classic xv, and wayland as fallbacks
+
Alt+RIGHT add video-rotate 90
# note: opengl has numerous quality/performance trade-off options.
+
Alt+LEFT add video-rotate -90
# as per the mpv(1), "opengl-hq" is just an alias for "opengl:lscale=lanczos2:dither-depth=auto:fbo-format=rgb16"
+
Alt+- add video-zoom -0.25
vo=opengl-hq,opengl,xv,wayland
+
Alt+= add video-zoom 0.25
 +
Alt+j add video-pan-x -0.05
 +
Alt+l add video-pan-x 0.05
 +
Alt+i add video-pan-y 0.05
 +
Alt+k add video-pan-y -0.05
  
# use alsa for audio output, choose pulse, or oss4 as fallback
+
=== mpv and PulseAudio/ALSA mixer controls since 0.18.1 ===
ao=alsa,pulse,oss
 
  
# prefer using 5.1 channels audio (defaults to 2 - see mpv --channels=help)  
+
This entry only applies if you are using pulseaudio for mpv ({{ic|1=-ao=pulse}} or {{ic|1=ao=pulse}} in {{ic|mpv.conf}}), or if you want to control your ALSA mixer volume with mpv.
# mixing is handled by libavcodec unless using "--af-add=pan" (see below)
+
channels=5.1
+
Add the following to your {{ic|~/.config/mpv/input.conf}} to make volume changes work again from PulseAudio/ALSA to mpv and vice versa:
  
# scale the subtitles to the 3% of the screen size
+
/ add ao-volume -2
sub-scale=3
+
SHIFT+* add ao-volume 2
  
# set the window title using the media filename (see Property Expansion section of mpv(1))
+
Change the above to whatever volume keys you use.
title="${filename}"
 
  
# add black borders so the movies have the same aspect ratio of the monitor
+
== Tips and Tricks ==
# for wide screen monitors
 
vf=expand=::::1:16/9:16
 
  
# for non wide screen traditional monitors, alternative to the above item
+
=== Hardware decoding ===
#vf=expand=::::1:4/3:16
 
  
# disable screensaver
+
See [[Hardware video acceleration]].
stop-screensaver="yes"
 
  
# execute a command every 30 seconds
+
Unlike ''mplayer'' and ''mplayer2'', ''mpv'' has both VA-API and VDPAU support built-in. To enable it, run ''mpv'' with the {{ic|1=--hwdec='method'}} option. You can find list of all available methods looking for {{ic|1=--hwdec=<api>}} in [[man page]] {{man|1|mpv|url=https://mpv.io/manual/master/}}. To make this persistent, add the line {{ic|1=hwdec=''method''}} to your configuration file.
# useful to disable a non-standard-compliant screensavers and to work around buggy behaviours
 
# BE WARNED: to avoid dangerous commands is your responsibility
 
#heartbeat-cmd="xscreensaver-command -deactivate &" # stop xscreensaver
 
  
# custom heartbeat frequency in seconds
+
When hardware decoding is used, the video output should generally be set to {{ic|opengl}} or {{ic|opengl-hq}} (or possibly {{ic|vdpau}} if using {{ic|1=hwdec=vdpau}}). In particular, {{ic|1=hwdec=vaapi}} should be used with {{ic|1=profile=opengl}} [https://github.com/mpv-player/mpv/blob/master/DOCS/man/vo.rst] if possible ({{ic|opengl-hq}} has sometimes huge CPU spikes when a video is read using this mode).
#heartbeat-interval=600
 
  
# correct pitch when speed is faster or slower than 1.0
+
If hardware decoding cannot be used, ''mpv'' will automatically fall back to software decoding.
af=scaletempo
 
  
# allow to seek in a file which is still downloading whilst watching it
+
By default, hardware decoding is enabled for codecs h264, vc1, wmv3, hevc, mpeg2video and vp9. It is however possible to specify codecs (e.g. {{ic|1=--hwdec-codecs=h264,mpeg2video}}) or allow all codecs ({{ic|1=hwdec-codecs=all}}) to use hardware decoding.
# from manpage:"this switch has no effect in the typical case" (usually done automatically by demuxers)
 
# idx=yes
 
  
# allow to increase the maximal volume to 600%
+
=== High quality video output ===
#softvol-max=600
 
  
# skip displaying some frames to maintain A/V sync on slow systems
+
The {{ic|opengl-hq}} profile is a high quality preset that uses the OpenGL video driver and enables various options selected by the mpv developers. To make use of it, specify it in your configuration file.
framedrop=yes
 
  
# profile for up-mixing two channels audio to six channels
+
{{hc|~/.config/mpv/mpv.conf|2=profile=opengl-hq}}
# use --profile 2chto6ch to activate
 
[2chto6ch]
 
af-add=pan=6:1:0:.4:0:.6:2:0:1:0:.4:.6:2
 
  
# profile to down-mixing six channels audio to two channels
+
This profile comes with a debanding filter that greatly reduces the amount of visible banding, blocking and other quantization artifacts, at the expensive of very slightly blurring some of the finest details. In practice, it's virtually always an improvement - the only reason to disable it would be for performance.
# use --profile 6chto2ch to activate
+
 
[6chto2ch]
+
If it leads to bad performance, you can disable it easily.
af-add=pan=2:0.7:0:0:0.7:0.5:0:0:0.5:0.6:0.6:0:0
+
 
 +
{{hc|~/.config/mpv/mpv.conf|2=
 +
profile=opengl-hq
 +
deband=no}}
 +
 
 +
The {{ic|opengl-hq}} profile defaults to the {{ic|spline36}} scaling filter for mid quality and speed. For the best quality video output, the manual states that if your hardware can run it, {{ic|ewa_lanczossharp}} is probably what you should use.
 +
 
 +
{{hc|~/.config/mpv/mpv.conf|2=
 +
profile=opengl-hq
 +
scale=ewa_lanczossharp
 +
cscale=ewa_lanczossharp
 
}}
 
}}
  
See another example at https://github.com/mpv-player/mpv/blob/master/etc/example.conf.
+
=== Save position on quit ===
 +
 
 +
By default you can save the position and quit by pressing {{ic|Shift+q}}. The shortcut can be changed by setting
 +
{{ic|quit_watch_later}} in the key bindings configuration file.
 +
 
 +
To automatically save the current playback position on quit, start ''mpv'' with {{ic|--save-position-on-quit}}, or add {{ic|save-position-on-quit}} to the configuration file.
 +
 
 +
=== Volume is too low ===
 +
 
 +
Set {{ic|1=volume-max=''value''}} in your configuration file to a reasonable amount, such as {{ic|1=volume-max=600}}. Additionally (or alternatively), you can utilize [[Wikipedia:Dynamic range compression|dynamic range compression]] with {{ic|1=af=acompressor}}.
  
== Hardware Decoding ==
+
=== Quickly cycle between aspect ratios ===
  
You can reduce the CPU usage (and extend mobile battery life) by enabling GPU hardware decoding for common video codecs. Unlike mplayer, and mplayer2, mpv has both [[Wikipedia:VDPAU|VDPAU]] and [[Wikipedia:VAAPI|VAAPI]] built-in! To enable hardware decoding, add --hwdec=<method> to the mpv command line, where <method> is one of "auto", "vdpau", "vaapi". To make this persistent, add the line hwdec=<method> to the config file. With hardwarde decoding --hwdec=[vdpau|vaapi], the video output must be specified as --vo=opengl (preferred) or --vo=[vdpau|vaapi]. While --vo=opengl should generally be of better quality,--vo=vdpau may give better frame timings, and --vo=vaapi may use less power. If hardware decoding can't be used, mpv will automatically fallback to software decoding.
+
You can cycle between aspect ratios using {{ic|Shift+a}} from version 0.8.0 onwards.
  
== Key bindings ==
+
=== Ignoring aspect ratio ===
  
System key bindings are configured via {{ic|/etc/mpv/input.conf}}. Personal key bindings are stored in {{ic|~/.mpv/input.conf}}.
+
You can ignore aspect ratio using {{ic|1=--keepaspect=''no''}}. To make option permanent, add line {{ic|1=keepaspect=''no''}} to configuration file.
Available keybinds and configuration are explained in the [https://github.com/mpv-player/mpv/blob/master/DOCS/man/en/mpv.rst manual pages].
 
  
=== Automatic resuming from where you left off ===
+
=== Draw to the root window ===
  
The default key to quit saving the video advance state is {{ic|Q}}. This behaviour is controlled by the {{ic|quit_watch_later}} string in the key bindings configuration file.
+
Run ''mpv'' with {{ic|1=--wid=0}}. ''mpv'' will draw to the window with a window ID of 0.
  
=== Quick aspect ratio change ===
+
=== Always show GUI ===
  
Append to your {{ic|input.conf}}:
+
It may be useful to always show the GUI window, even for audio files, especially when ''mpv'' is not started from terminal. This can be done by using {{ic|--force-window}} option.
{{bc|
+
 
F1 set aspect 1.3333
+
=== Hide GUI for video files ===
F2 set aspect 1.6
+
 
F3 set aspect 1.7777
+
It may be useful to hide the GUI window for video files. This can be done by using {{ic|--no-video}} option.
F4 set aspect 1.85
+
 
F5 set aspect 0
+
=== Restoring old OSC ===
 +
 
 +
Since version 0.21.0, mpv has replaced the on-screen controls by a bottombar. In case you want on-screen controls back, you can edit the mpv configuration [https://github.com/mpv-player/mpv/wiki/FAQ#i-want-the-old-osc-back as described here].
 +
 
 +
=== Use as a browser plugin ===
 +
 
 +
With the help of {{AUR|mozplugger}}, ''mpv'' can be used in a supported browser to play video. See [[Browser plugins#MozPlugger]] for configuration details. This coupled with a user script such as [http://isebaro.com/viewtube/?ln=en ViewTube], allows you to use ''mpv'' in place of a site's integrated video player.
 +
 
 +
It may be needed to specify a valid user agent for HTTP streaming, e.g. {{ic|1=user-agent="Mozilla/5.0 (X11; Linux x86_64; rv:49.0) Gecko/20100101 Firefox/49.0"}}.
 +
 
 +
[[Browser plugins#Multimedia playback]] page shows other easy ways to watch videos.
 +
 
 +
=== Improving mpv as a music player with Lua scripts ===
 +
 
 +
The development of mpv's Lua scripts are documented in [https://github.com/mpv-player/mpv/blob/master/DOCS/man/lua.rst DOCS/man/lua.rst]
 +
and examples are shown in [https://github.com/mpv-player/mpv/tree/master/TOOLS/lua TOOLS/lua]
 +
of the [https://github.com/mpv-player/mpv mpv repository].
 +
[https://web.archive.org/web/20160320001546/http://bamos.github.io/2014/07/05/mpv-lua-scripting/ This blog post] introduces the
 +
[https://github.com/bamos/dotfiles/blob/master/.mpv/scripts/music.lua music.lua] script,
 +
which shows how Lua scripts can be used to improve mpv as a music player.
 +
 
 +
=== Twitch.tv streaming over mpv ===
 +
 
 +
If {{Pkg|youtube-dl}} is installed, mpv can directly open a Twitch livestream.
 +
 
 +
Alternatively, {{Pkg|streamlink}} can be used to stream Twitch. If you want a GUI for launching these streams use {{aur|streamlink-twitch-gui}}. See [[Livestreamer#Twitch]].
 +
 
 +
Another alternative based on Livestreamer is this Lua script: https://gist.github.com/ChrisK2/8701184fe3ea7701c9cc
 +
 
 +
=== youtube-dl and choosing formats ===
 +
 
 +
The default {{ic|--ytdl-format}} is {{ic|bestvideo+bestaudio/best}}. For youtube videos that have 4K resolutions available, this may mean that your device will struggle to decode 4K VP9 encoded video in software even if the attached monitor is much lower resolution.
 +
 
 +
Setting the right youtube-dl format selectors can fix this easily though. In the following configuration example, only videos with a vertical resolution of 1080 pixels or less will be considered.
 +
 
 +
ytdl-format=bestvideo[height<=?1080]+bestaudio/best
 +
 
 +
If you wish to avoid a certain codec altogether because you cannot hardware-decode it, you can add this to the format selector. For example, we can additionally choose to ignore VP9 as follows:
 +
 
 +
ytdl-format=bestvideo[height<=?1080][vcodec!=vp9]+bestaudio/best
 +
 
 +
If you prefer best quality open codecs (VP9 and Opus), use:
 +
ytdl-format="((bestvideo[vcodec^=vp9]/bestvideo)+(bestaudio[acodec=opus]/bestaudio[acodec=vorbis]/bestaudio[acodec=aac]/bestaudio))/best"
 +
 
 +
=== youtube-dl audio with search ===
 +
 
 +
To find and play audio straight from your terminal with {{ic|mm "''search terms''"}} put the following function in your {{ic|.bashrc}}:
 +
 
 +
function mm() {
 +
    mpv --no-video --ytdl-format=bestaudio ytdl://ytsearch10:"$@"
 +
}
 +
 
 +
=== Use mpv with a compositor ===
 +
 
 +
If you're using a compositor (e.g. in KDE Plasma 5) and find that composition is disabled (e.g. in Plasma this would make you unable to present windows or see window thumbnails in the default app switcher) when mpv is playing a video, try {{ic|1=x11-bypass-compositor=no}}
 +
 
 +
=== Creating a single screenshot ===
 +
An example of creating a single screenshot, by using a start time ({{ic|HH:MM:SS}}):
 +
 
 +
$ mpv --no-audio --start=00:01:30 --frames=1 /path/to/video/file --o=/path/to/screenshot.png
 +
 
 +
Screenshots will be saved in /path/to/screenshot.png.
 +
 
 +
=== GNOME Blank screen (Wayland) ===
 +
 
 +
MPV may not suspend GNOME's Power Saving Settings if using Wayland (resulting in screen saver turning off the monitor while video is playing for example). A workaround is to add {{ic|gnome-session-inhibit}} to the beginning of the {{ic|1=Exec=}} line in {{ic|mpv.desktop}}.
 +
 
 +
== Vapoursynth ==
 +
 
 +
Vapoursynth is an alternative to AviSynth that can be used on Linux and allows for Video manipulation via python scripts. Vapoursynths python scripts can be used as video filters for ''mpv''.
 +
 
 +
To use vapoursynth filters you have to install the {{Pkg|vapoursynth}} package and compile ''mpv'' with the {{ic|--enable-vapoursynth}} build flag.
 +
 
 +
=== Debanding (flash3kyuu) ===
 +
 
 +
{{Note|Mpv already include a debanding shader which is enabled by default with the [[#High quality video output|opengl-hq profile]]. Refer to the manual for more information on how to tune it.}}
 +
 
 +
To use the {{ic|f3k_db}} debanding filter install {{Pkg|vapoursynth-plugin-f3kdb}} and write a python script that uses the ''vapoursynth'' extension.
 +
 
 +
The following sample script can be used to enable debanding in ''mpv''.
 +
 
 +
import vapoursynth as vs
 +
core = vs.get_core()
 +
 +
clip = video_in
 +
clip = core.std.Trim(clip, first=0, length=500000)
 +
clip = core.f3kdb.Deband(clip, grainy=0, grainc=0, output_depth=16)
 +
clip.set_output()
 +
 
 +
Finally specify the python script in the config file or use a command line argument when executing mpv.
 +
$ mpv --vf=vapoursynth=f3k_db.py <video_file>
 +
 
 +
== Troubleshooting ==
 +
 
 +
=== Fix jerky playback and tearing ===
 +
 
 +
mpv defaults to using the OpenGL video output device setting on hardware that supports it. In cases such as trying to play video back on a 4K display using a Intel HD4XXX series card or similar, you will find video playback unreliable, jerky to the point of stopping entirely at times and with major tearing when using any opengl output setting. If you experience any of these issues, using the XV (XVideo) video output device may help:
 +
 
 +
{{hc|1=~/.config/mpv/mpv.conf|2=profile=xv}}
 +
This VO is deprecated and will cause issues in recent versions of mpv, most noticeably is the osd looking very blurry.
 +
 
 +
It is possible to increase playback performance even more (especially on lower hardware), but this decreases the video quality dramatically in most cases.
 +
 
 +
The following [[#Configuration|options]] may be considered to increase the video playback performance:
 +
{{hc|~/.config/mpv/mpv.conf|2=
 +
vd-lavc-fast
 +
vd-lavc-skiploopfilter=<skipvalue>
 +
vd-lavc-skipframe=<skipvalue>
 +
vd-lavc-framedrop=<skipvalue>
 +
vd-lavc-threads=<threads>
 
}}
 
}}
Now you are able to change the aspect ratio with {{ic|F1}} to {{ic|F5}}.
+
 
 +
=== Problems with window compositors ===
 +
 
 +
Window compositors such as KWin or Mutter can cause trouble for playback smoothness. In such cases, it may help to set {{ic|1=x11-bypass-compositor=yes}} to make mpv also disable window compositing when playing in windowed mode (if supported by the compositor).
 +
 
 +
With KWin compositing and hardware decoding, you may also want to set {{ic|1=x11-bypass-compositor=no}} to keep compositing enabled in fullscreen, since reanabling compositing after leaving fullscreen may introduce stutter for a period of time.

Latest revision as of 15:34, 7 August 2017

Related articles

mpv is a media player based on MPlayer and MPlayer2. It supports a wide variety of video file formats, audio and video codecs, and subtitle types. A comprehensive (although admittedly incomplete) list of differences between mpv and the aforementioned players can be found here.

Installation

Install the mpv package or mpv-gitAUR for the development version.

Front ends

mpv comes with a minimal GUI called On Screen Controller (OSC), that appears when moving the mouse. There are also other front ends available:

  • Baka MPlayer — Free and open source, cross-platform, libmpv based multimedia player (Qt 5).
http://bakamplayer.u8sand.net/ || baka-mplayer, baka-mplayer-gitAUR
  • GNOME MPV — A simple frontend for mpv (GTK+ 3).
https://gnome-mpv.github.io/ || gnome-mpvAUR, gnome-mpv-gitAUR
https://github.com/cmdrkotori/mpc-qt || mpc-qt-gitAUR
  • SMPlayer — Qt multimedia player with extra features (CSS themes, YouTube integration, etc.) (Qt 5).
https://www.smplayer.info/ || smplayer
  • xt7-player-mpv — Qt/Gambas GUI to mpv with a rich set of configurable options including filters and drivers, ladspa plugins support as well as library/playlist managment, YouTube, online radios, podcasts, DVB-T and more.
https://github.com/kokoko3k/xt7-player-mpv || xt7-player-mpv-gitAUR

Forks

  • bomi — Powerful and easy to use multimedia player (Qt 5).
https://bomi-player.github.io/ || bomiAUR, bomi-gitAUR

Configuration

mpv's configuration is read from the files mpv.conf (settings), input.conf (key bindings), and lua-settings/osc.conf (on screen display). For a full list of options, see the mpv(1) or the GitHub docs.

If the environment variable XDG_CONFIG_HOME is not set, user configuration files will be read from the ~/.config/mpv directory. System-wide configuration files are read from the /etc/mpv directory.

An example input.conf file

Copying the following into ~/.config/mpv/input.conf will add a number of useful keybindings to mpv such as rotating video 90 degrees, zooming and panning.

Alt+RIGHT add video-rotate 90
Alt+LEFT add video-rotate -90
Alt+- add video-zoom -0.25
Alt+= add video-zoom 0.25
Alt+j add video-pan-x -0.05
Alt+l add video-pan-x 0.05
Alt+i add video-pan-y 0.05
Alt+k add video-pan-y -0.05

mpv and PulseAudio/ALSA mixer controls since 0.18.1

This entry only applies if you are using pulseaudio for mpv (-ao=pulse or ao=pulse in mpv.conf), or if you want to control your ALSA mixer volume with mpv.

Add the following to your ~/.config/mpv/input.conf to make volume changes work again from PulseAudio/ALSA to mpv and vice versa:

/ add ao-volume -2
SHIFT+* add ao-volume 2

Change the above to whatever volume keys you use.

Tips and Tricks

Hardware decoding

See Hardware video acceleration.

Unlike mplayer and mplayer2, mpv has both VA-API and VDPAU support built-in. To enable it, run mpv with the --hwdec='method' option. You can find list of all available methods looking for --hwdec=<api> in man page mpv(1). To make this persistent, add the line hwdec=method to your configuration file.

When hardware decoding is used, the video output should generally be set to opengl or opengl-hq (or possibly vdpau if using hwdec=vdpau). In particular, hwdec=vaapi should be used with profile=opengl [1] if possible (opengl-hq has sometimes huge CPU spikes when a video is read using this mode).

If hardware decoding cannot be used, mpv will automatically fall back to software decoding.

By default, hardware decoding is enabled for codecs h264, vc1, wmv3, hevc, mpeg2video and vp9. It is however possible to specify codecs (e.g. --hwdec-codecs=h264,mpeg2video) or allow all codecs (hwdec-codecs=all) to use hardware decoding.

High quality video output

The opengl-hq profile is a high quality preset that uses the OpenGL video driver and enables various options selected by the mpv developers. To make use of it, specify it in your configuration file.

~/.config/mpv/mpv.conf
profile=opengl-hq

This profile comes with a debanding filter that greatly reduces the amount of visible banding, blocking and other quantization artifacts, at the expensive of very slightly blurring some of the finest details. In practice, it's virtually always an improvement - the only reason to disable it would be for performance.

If it leads to bad performance, you can disable it easily.

~/.config/mpv/mpv.conf
profile=opengl-hq
deband=no

The opengl-hq profile defaults to the spline36 scaling filter for mid quality and speed. For the best quality video output, the manual states that if your hardware can run it, ewa_lanczossharp is probably what you should use.

~/.config/mpv/mpv.conf
profile=opengl-hq
scale=ewa_lanczossharp
cscale=ewa_lanczossharp

Save position on quit

By default you can save the position and quit by pressing Shift+q. The shortcut can be changed by setting quit_watch_later in the key bindings configuration file.

To automatically save the current playback position on quit, start mpv with --save-position-on-quit, or add save-position-on-quit to the configuration file.

Volume is too low

Set volume-max=value in your configuration file to a reasonable amount, such as volume-max=600. Additionally (or alternatively), you can utilize dynamic range compression with af=acompressor.

Quickly cycle between aspect ratios

You can cycle between aspect ratios using Shift+a from version 0.8.0 onwards.

Ignoring aspect ratio

You can ignore aspect ratio using --keepaspect=no. To make option permanent, add line keepaspect=no to configuration file.

Draw to the root window

Run mpv with --wid=0. mpv will draw to the window with a window ID of 0.

Always show GUI

It may be useful to always show the GUI window, even for audio files, especially when mpv is not started from terminal. This can be done by using --force-window option.

Hide GUI for video files

It may be useful to hide the GUI window for video files. This can be done by using --no-video option.

Restoring old OSC

Since version 0.21.0, mpv has replaced the on-screen controls by a bottombar. In case you want on-screen controls back, you can edit the mpv configuration as described here.

Use as a browser plugin

With the help of mozpluggerAUR, mpv can be used in a supported browser to play video. See Browser plugins#MozPlugger for configuration details. This coupled with a user script such as ViewTube, allows you to use mpv in place of a site's integrated video player.

It may be needed to specify a valid user agent for HTTP streaming, e.g. user-agent="Mozilla/5.0 (X11; Linux x86_64; rv:49.0) Gecko/20100101 Firefox/49.0".

Browser plugins#Multimedia playback page shows other easy ways to watch videos.

Improving mpv as a music player with Lua scripts

The development of mpv's Lua scripts are documented in DOCS/man/lua.rst and examples are shown in TOOLS/lua of the mpv repository. This blog post introduces the music.lua script, which shows how Lua scripts can be used to improve mpv as a music player.

Twitch.tv streaming over mpv

If youtube-dl is installed, mpv can directly open a Twitch livestream.

Alternatively, streamlink can be used to stream Twitch. If you want a GUI for launching these streams use streamlink-twitch-guiAUR. See Livestreamer#Twitch.

Another alternative based on Livestreamer is this Lua script: https://gist.github.com/ChrisK2/8701184fe3ea7701c9cc

youtube-dl and choosing formats

The default --ytdl-format is bestvideo+bestaudio/best. For youtube videos that have 4K resolutions available, this may mean that your device will struggle to decode 4K VP9 encoded video in software even if the attached monitor is much lower resolution.

Setting the right youtube-dl format selectors can fix this easily though. In the following configuration example, only videos with a vertical resolution of 1080 pixels or less will be considered.

ytdl-format=bestvideo[height<=?1080]+bestaudio/best

If you wish to avoid a certain codec altogether because you cannot hardware-decode it, you can add this to the format selector. For example, we can additionally choose to ignore VP9 as follows:

ytdl-format=bestvideo[height<=?1080][vcodec!=vp9]+bestaudio/best

If you prefer best quality open codecs (VP9 and Opus), use:

ytdl-format="((bestvideo[vcodec^=vp9]/bestvideo)+(bestaudio[acodec=opus]/bestaudio[acodec=vorbis]/bestaudio[acodec=aac]/bestaudio))/best"

youtube-dl audio with search

To find and play audio straight from your terminal with mm "search terms" put the following function in your .bashrc:

function mm() {
    mpv --no-video --ytdl-format=bestaudio ytdl://ytsearch10:"$@"
}

Use mpv with a compositor

If you're using a compositor (e.g. in KDE Plasma 5) and find that composition is disabled (e.g. in Plasma this would make you unable to present windows or see window thumbnails in the default app switcher) when mpv is playing a video, try x11-bypass-compositor=no

Creating a single screenshot

An example of creating a single screenshot, by using a start time (HH:MM:SS):

$ mpv --no-audio --start=00:01:30 --frames=1 /path/to/video/file --o=/path/to/screenshot.png

Screenshots will be saved in /path/to/screenshot.png.

GNOME Blank screen (Wayland)

MPV may not suspend GNOME's Power Saving Settings if using Wayland (resulting in screen saver turning off the monitor while video is playing for example). A workaround is to add gnome-session-inhibit to the beginning of the Exec= line in mpv.desktop.

Vapoursynth

Vapoursynth is an alternative to AviSynth that can be used on Linux and allows for Video manipulation via python scripts. Vapoursynths python scripts can be used as video filters for mpv.

To use vapoursynth filters you have to install the vapoursynth package and compile mpv with the --enable-vapoursynth build flag.

Debanding (flash3kyuu)

Note: Mpv already include a debanding shader which is enabled by default with the opengl-hq profile. Refer to the manual for more information on how to tune it.

To use the f3k_db debanding filter install vapoursynth-plugin-f3kdb and write a python script that uses the vapoursynth extension.

The following sample script can be used to enable debanding in mpv.

import vapoursynth as vs
core = vs.get_core()

clip = video_in
clip = core.std.Trim(clip, first=0, length=500000)
clip = core.f3kdb.Deband(clip, grainy=0, grainc=0, output_depth=16)
clip.set_output()

Finally specify the python script in the config file or use a command line argument when executing mpv.

$ mpv --vf=vapoursynth=f3k_db.py <video_file>

Troubleshooting

Fix jerky playback and tearing

mpv defaults to using the OpenGL video output device setting on hardware that supports it. In cases such as trying to play video back on a 4K display using a Intel HD4XXX series card or similar, you will find video playback unreliable, jerky to the point of stopping entirely at times and with major tearing when using any opengl output setting. If you experience any of these issues, using the XV (XVideo) video output device may help:

~/.config/mpv/mpv.conf
profile=xv

This VO is deprecated and will cause issues in recent versions of mpv, most noticeably is the osd looking very blurry.

It is possible to increase playback performance even more (especially on lower hardware), but this decreases the video quality dramatically in most cases.

The following options may be considered to increase the video playback performance:

~/.config/mpv/mpv.conf
vd-lavc-fast
vd-lavc-skiploopfilter=<skipvalue>
vd-lavc-skipframe=<skipvalue>
vd-lavc-framedrop=<skipvalue>
vd-lavc-threads=<threads>

Problems with window compositors

Window compositors such as KWin or Mutter can cause trouble for playback smoothness. In such cases, it may help to set x11-bypass-compositor=yes to make mpv also disable window compositing when playing in windowed mode (if supported by the compositor).

With KWin compositing and hardware decoding, you may also want to set x11-bypass-compositor=no to keep compositing enabled in fullscreen, since reanabling compositing after leaving fullscreen may introduce stutter for a period of time.