Difference between revisions of "Mpv"

From ArchWiki
Jump to: navigation, search
(Add Category. See Help:Category.)
(Updated description for better key bindings.)
 
(162 intermediate revisions by 57 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-cn:Mpv]]
 +
{{Related articles start}}
 +
{{Related|MPlayer}}
 +
{{Related articles end}}
 +
 
 +
[http://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}} Qt5 frontend which provides its own ''mpv''.
+
[[Install]] the {{Pkg|mpv}} package from the [[official repositories]] or {{AUR|mpv-git}} from the [[Arch User Repository]].
 +
 
 +
=== Front ends ===
 +
 
 +
''mpv'' provides an elegant User Interface called OSC which appears when moving the mouse. To ease casual users, other graphical interfaces exist:
 +
 
 +
* {{App|Baka MPlayer|Free and open source, cross-platform, ''libmpv'' based multimedia player (Qt 5).|https://github.com/u8sand/Baka-MPlayer/|{{Pkg|baka-mplayer}}, {{AUR|baka-mplayer-git}}}}
 +
* {{App|bomi|Powerful and easy to use multimedia player (Qt 5).|https://bomi-player.github.io/|{{AUR|bomi}}, {{AUR|bomi-git}}}}
 +
* {{App|GNOME MPV|A simple frontend for ''mpv'' (GTK+ 3).|https://github.com/gnome-mpv/gnome-mpv/|{{AUR|gnome-mpv-git}}, {{AUR|gnome-mpv}}}}
 +
* {{App|[[Wikipedia:SMPlayer|SMPlayer]]|Qt multimedia player with extra features (CSS themes, YouTube integration, etc.) (Qt 5).|http://smplayer.sourceforge.net/|{{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}}}}
 +
 
 +
{{Note|CMPlayer/''bomi'' packages provide ''mpv'' internally.}}
  
 
== 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}} ([https://raw.githubusercontent.com/mpv-player/mpv/master/etc/mpv.conf example]) (settings), {{ic|input.conf}} (key bindings), and {{ic|lua-settings/osc.conf}} ([https://raw.githubusercontent.com/mpv-player/mpv/master/etc/input.conf example]) (on screen display).  For a full list of options, see the man page or the github docs [https://github.com/mpv-player/mpv/blob/master/DOCS/man/options.rst options.rst], [https://github.com/mpv-player/mpv/blob/master/DOCS/man/input.rst input.rst], and [https://github.com/mpv-player/mpv/blob/master/DOCS/man/osc.rst osc.rst].
{{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 {{ic|input.conf}} file ===
 +
 
 +
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.
 +
 
 +
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 since 0.18.1 ===
 +
 
 +
This entry only applies if you are using pulseaudio for mpv ({{ic|1=-ao=pulse}} or {{ic|1=ao=pulse}} in {{ic|mpv.conf}}).
 +
 +
Add the following to your {{ic|~/.config/mpv/input.conf}} to make volume changes work again from PulseAudio to mpv and vice versa:
 +
 
 +
/ add ao-volume -2
 +
SHIFT+* add ao-volume 2
 +
 
 +
Change the above to whatever volume keys you use. The above is the default of MPV only handles by "softvol" and with those lines handled by PulseAudio.
 +
 
 +
== 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 {{ic|1=--hwdec='method'}} option. You can find list of all available methods looking for {{ic|1=--hwdec=<api>}} in [[man page]] {{ic|mpv (1)}}. To make this persistent, add the line {{ic|1=hwdec=''method''}} to your configuration file.
 +
 
 +
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=vo=opengl}} [https://github.com/mpv-player/mpv/blob/master/DOCS/man/vo.rst] if possible.  
 +
 
 +
If hardware decoding cannot be used, ''mpv'' will automatically fall back to software decoding.
 +
 
 +
=== High quality video output ===
 +
 
 +
The {{ic|opengl-hq}} video output is an OpenGL output preconfigured with various options by the mpv developers. To make use of it, specify it in your configuration file.
 +
 
 +
{{hc|1=~/.config/mpv/mpv.conf|2=vo=opengl-hq}}
 +
 
 +
This comes with a GLSL debanding filter by default, which may lead to bad performance for some users, and can reduce the visual quality of grainy content. You can disable it easily though.
 +
 
 +
{{hc|1=~/.config/mpv/mpv.conf|2=vo=opengl-hq:deband=no}}
 +
 
 +
=== Automatically resuming from where you left off ===
 +
 
 +
The default key to quit ''mpv'', saving the video's current position and state, is {{ic|Shift+q}}. This key can be changed by adding the {{ic|quit_watch_later}} string in the key bindings configuration file.
 +
 
 +
To always automatically save the current playback position on quit, start ''mpv'' with a flag {{ic|--save-position-on-quit}}. To make option permanent, add line {{ic|save-position-on-quit}} to 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=drc}}.
 +
 
 +
=== Quickly cycle between multiple aspect ratio ===
 +
 
 +
You can cycle between aspect ratios using {{ic|Shift+a}} from version 0.8.0 onwards.
 +
 
 +
=== Drawing to a root window ===
 +
 
 +
Run ''mpv'' with {{ic|1=--wid=0}}. This tells ''mpv'' to draw onto a 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 {{ic|--force-window}} option.
  
An example configuration:
+
=== Use as a browser plugin ===
{{bc|1=
+
# default configuration that applies to every file
+
[default]
+
  
# use X11 for video output, use a wayland and framebuffer as fallbacks
+
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.
vo=xv,wayland,directfb
+
  
# use alsa for audio output, choose oss4 as fallback
+
[[Browser plugins#Video players workarounds]] page shows other easy ways to watch videos.
ao=alsa,oss
+
  
# multithreaded decoding of H264/MPEG-1/2 (valid: 0-16)
+
=== Improving mpv as a music player with Lua scripts ===
vd-lavc-threads=2
+
  
# prefer using six channels audio
+
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]
channels=6
+
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].
 +
[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.
  
# scale the subtitles to the 3% of the screen size
+
=== Twitch.tv streaming over mpv ===
sub-scale=3
+
  
# set the window title using the media filename, when not set with --title.
+
If {{Pkg|youtube-dl}} is installed, mpv can directly open a Twitch livestream.
title="${filename}"
+
  
# add black borders so the movies have the same aspect ratio of the monitor
+
Alternatively, {{Pkg|livestreamer}} can be used to stream Twitch. See [[Livestreamer#Twitch]].
# for wide screen monitors
+
vf=expand=::::1:16/9:16
+
  
# for non wide screen traditional monitors, alternative to the above item
+
Another alternative based on Livestreamer is this Lua script: https://gist.github.com/ChrisK2/8701184fe3ea7701c9cc
#vf=expand=::::1:4/3:16
+
  
# disable screensaver
+
=== youtube-dl and choosing formats ===
stop-screensaver="yes"
+
  
# execute a command every 30 seconds
+
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.
# 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
+
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.
#heartbeat-interval=600
+
  
# correct pitch when speed is faster or slower than 1.0
+
ytdl-format=bestvideo[height<=?1080]+bestaudio/best
af=scaletempo
+
  
# allow to seek in a file which is still downloading whilst watching it
+
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:
idx=yes
+
  
# allow to increase the maximal volume to 600%
+
ytdl-format=bestvideo[height<=?1080][vcodec!=vp9]+bestaudio/best
#softvol-max=600
+
  
# skip displaying some frames to maintain A/V sync on slow systems
+
=== youtube-dl audio with search ===
framedrop=yes
+
  
# more intense frame dropping (breaks decoding)
+
To find and play audio straight from your terminal with {{ic|mm "''search terms''"}} put the following function in your {{ic|.bashrc}}:
#framedrop=hard
+
  
# profile for up-mixing two channels audio to six channels
+
function mm() {
# use -profile 2chto6ch to activate
+
    mpv --no-video --ytdl-format=bestaudio ytdl://ytsearch10:"$@"
[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
+
=== Use mpv with a compositor ===
# use -profile 6chto2ch to activate
+
[6chto2ch]
+
af-add=pan=2:0.7:0:0:0.7:0.5:0:0:0.5:0.6:0.6:0:0
+
}}
+
  
See another example at https://github.com/mpv-player/mpv/blob/master/etc/example.conf.
+
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}}
  
== Enable VDPAU ==
+
== Vapoursynth ==
  
You can speed up the player using the GPU [[Wikipedia:VDPAU|VDPAU]] API. The procedure is the same of [[MPlayer#Enabling VDPAU|MPlayer]].
+
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''.
  
== Key bindings ==
+
To use vapoursynth filters you have to install the {{Pkg|vapoursynth}} package and compile ''mpv'' with the {{ic|--enable-vapoursynth}} build flag.
  
System key bindings are configured via {{ic|/etc/mpv/input.conf}}. Personal key bindings are stored in {{ic|~/.mpv/input.conf}}.
+
=== Debanding (flash3kyuu) ===
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 ===
+
To use the {{ic|f3k_db}} debanding filter install {{AUR|vapoursynth-plugin-flash3kyuu_deband-git}}{{Broken package link|{{aur-mirror|vapoursynth-plugin-flash3kyuu_deband-git}}}} and write a python script that uses the ''vapoursynth'' extension.
  
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.
+
The following sample script can be used to enable debanding in ''mpv''.
  
=== Quick aspect ratio change ===
+
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()
  
Append to your {{ic|input.conf}}:
+
Finally specify the python script in the config file or use a command line argument when executing mpv.
{{bc|
+
$ mpv --vf=vapoursynth=f3k_db.py <video_file>
F1 set aspect 1.3333
+
F2 set aspect 1.6
+
F3 set aspect 1.7777
+
F4 set aspect 1.85
+
F5 set aspect 0
+
}}
+
Now you are able to change the aspect ratio with {{ic|F1}} to {{ic|F5}}.
+

Latest revision as of 21:31, 14 August 2016

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 from the official repositories or mpv-gitAUR from the Arch User Repository.

Front ends

mpv provides an elegant User Interface called OSC which appears when moving the mouse. To ease casual users, other graphical interfaces exist:

  • Baka MPlayer — Free and open source, cross-platform, libmpv based multimedia player (Qt 5).
https://github.com/u8sand/Baka-MPlayer/ || baka-mplayer, baka-mplayer-gitAUR
  • bomi — Powerful and easy to use multimedia player (Qt 5).
https://bomi-player.github.io/ || bomiAUR, bomi-gitAUR
  • GNOME MPV — A simple frontend for mpv (GTK+ 3).
https://github.com/gnome-mpv/gnome-mpv/ || gnome-mpv-gitAUR, gnome-mpvAUR
  • SMPlayer — Qt multimedia player with extra features (CSS themes, YouTube integration, etc.) (Qt 5).
http://smplayer.sourceforge.net/ || 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
Note: CMPlayer/bomi packages provide mpv internally.

Configuration

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

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

This entry only applies if you are using pulseaudio for mpv (-ao=pulse or ao=pulse in mpv.conf).

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

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

Change the above to whatever volume keys you use. The above is the default of MPV only handles by "softvol" and with those lines handled by PulseAudio.

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 vo=opengl [1] if possible.

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

High quality video output

The opengl-hq video output is an OpenGL output preconfigured with various options by the mpv developers. To make use of it, specify it in your configuration file.

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

This comes with a GLSL debanding filter by default, which may lead to bad performance for some users, and can reduce the visual quality of grainy content. You can disable it easily though.

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

Automatically resuming from where you left off

The default key to quit mpv, saving the video's current position and state, is Shift+q. This key can be changed by adding the quit_watch_later string in the key bindings configuration file.

To always automatically save the current playback position on quit, start mpv with a flag --save-position-on-quit. To make option permanent, add line save-position-on-quit to 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=drc.

Quickly cycle between multiple aspect ratio

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

Drawing to a root window

Run mpv with --wid=0. This tells mpv to draw onto a 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.

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.

Browser plugins#Video players workarounds 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, livestreamer can be used to stream Twitch. 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

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

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)

To use the f3k_db debanding filter install vapoursynth-plugin-flash3kyuu_deband-gitAUR[broken link: archived in aur-mirror] 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>