From f4b63071fc4307413e6ef113ffca46f951005778 Mon Sep 17 00:00:00 2001 From: Michael Forney Date: Thu, 28 Dec 2017 20:04:19 -0800 Subject: mpv: Track generated man page instead of patch --- pkg/mpv/gen.lua | 2 +- pkg/mpv/mpv.1 | 15201 +++++++++++++++++++++ pkg/mpv/patch/0002-Add-generated-man-page.patch | 15223 ---------------------- pkg/mpv/rev | 2 +- 4 files changed, 15203 insertions(+), 15225 deletions(-) create mode 100644 pkg/mpv/mpv.1 delete mode 100644 pkg/mpv/patch/0002-Add-generated-man-page.patch (limited to 'pkg') diff --git a/pkg/mpv/gen.lua b/pkg/mpv/gen.lua index 0b935de1..868cfd20 100644 --- a/pkg/mpv/gen.lua +++ b/pkg/mpv/gen.lua @@ -118,6 +118,6 @@ exe('mpv', { expand{'$builddir/pkg/', libs}, }) file('bin/mpv', '755', '$outdir/mpv') -man{'DOCS/man/mpv.1'} +man{'$dir/mpv.1'} fetch 'git' diff --git a/pkg/mpv/mpv.1 b/pkg/mpv/mpv.1 new file mode 100644 index 00000000..e698e6bd --- /dev/null +++ b/pkg/mpv/mpv.1 @@ -0,0 +1,15201 @@ +.\" Man page generated from reStructuredText. +. +.TH MPV 1 "" "" "multimedia" +.SH NAME +mpv \- a media player +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.SH SYNOPSIS +.nf +\fBmpv\fP [options] [file|URL|PLAYLIST|\-] +\fBmpv\fP [options] files +.fi +.sp +.SH DESCRIPTION +.sp +\fBmpv\fP 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. Special input URL +types are available to read input from a variety of sources other than disk +files. Depending on platform, a variety of different video and audio output +methods are supported. +.sp +Usage examples to get you started quickly can be found at the end of this man +page. +.SH INTERACTIVE CONTROL +.sp +mpv has a fully configurable, command\-driven control layer which allows you +to control mpv using keyboard, mouse, or remote control (there is no +LIRC support \- configure remotes as input devices instead). +.sp +See the \fB\-\-input\-\fP options for ways to customize it. +.sp +The following listings are not necessarily complete. See \fBetc/input.conf\fP for +a list of default bindings. User \fBinput.conf\fP files and Lua scripts can +define additional key bindings. +.SS Keyboard Control +.INDENT 0.0 +.TP +.B LEFT and RIGHT +Seek backward/forward 5 seconds. Shift+arrow does a 1 second exact seek +(see \fB\-\-hr\-seek\fP). +.TP +.B UP and DOWN +Seek forward/backward 1 minute. Shift+arrow does a 5 second exact seek (see +\fB\-\-hr\-seek\fP). +.TP +.B Ctrl+LEFT and Ctrl+RIGHT +Seek to the previous/next subtitle. Subject to some restrictions and +might not always work; see \fBsub\-seek\fP command. +.TP +.B [ and ] +Decrease/increase current playback speed by 10%. +.TP +.B { and } +Halve/double current playback speed. +.TP +.B BACKSPACE +Reset playback speed to normal. +.TP +.B < and > +Go backward/forward in the playlist. +.TP +.B ENTER +Go forward in the playlist. +.TP +.B p / SPACE +Pause (pressing again unpauses). +.TP +.B \&. +Step forward. Pressing once will pause, every consecutive press will +play one frame and then go into pause mode again. +.UNINDENT +.INDENT 0.0 +.TP +.B , +Step backward. Pressing once will pause, every consecutive press will +play one frame in reverse and then go into pause mode again. +.TP +.B q +Stop playing and quit. +.TP +.B Q +Like \fBq\fP, but store the current playback position. Playing the same file +later will resume at the old playback position if possible. +.TP +.B / and * +Decrease/increase volume. +.TP +.B 9 and 0 +Decrease/increase volume. +.TP +.B m +Mute sound. +.TP +.B _ +Cycle through the available video tracks. +.TP +.B # +Cycle through the available audio tracks. +.TP +.B f +Toggle fullscreen (see also \fB\-\-fs\fP). +.TP +.B ESC +Exit fullscreen mode. +.TP +.B T +Toggle stay\-on\-top (see also \fB\-\-ontop\fP). +.TP +.B w and e +Decrease/increase pan\-and\-scan range. +.TP +.B o (also P) +Show progression bar, elapsed time and total duration on the OSD. +.TP +.B O +Toggle OSD states between normal and playback time/duration. +.TP +.B v +Toggle subtitle visibility. +.TP +.B j and J +Cycle through the available subtitles. +.TP +.B x and z +Adjust subtitle delay by +/\- 0.1 seconds. +.TP +.B l +Set/clear A\-B loop points. See \fBab\-loop\fP command for details. +.TP +.B L +Toggle infinite looping. +.TP +.B Ctrl + and Ctrl \- +Adjust audio delay (A/V sync) by +/\- 0.1 seconds. +.TP +.B u +Switch between applying no style overrides to SSA/ASS subtitles, and +overriding them almost completely with the normal subtitle style. See +\fB\-\-sub\-ass\-override\fP for more info. +.TP +.B V +Toggle subtitle VSFilter aspect compatibility mode. See +\fB\-\-sub\-ass\-vsfilter\-aspect\-compat\fP for more info. +.TP +.B r and t +Move subtitles up/down. +.TP +.B s +Take a screenshot. +.TP +.B S +Take a screenshot, without subtitles. (Whether this works depends on VO +driver support.) +.TP +.B Ctrl s +Take a screenshot, as the window shows it (with subtitles, OSD, and scaled +video). +.TP +.B PGUP and PGDWN +Seek to the beginning of the previous/next chapter. In most cases, +"previous" will actually go to the beginning of the current chapter; see +\fB\-\-chapter\-seek\-threshold\fP\&. +.TP +.B Shift+PGUP and Shift+PGDWN +Seek backward or forward by 10 minutes. (This used to be mapped to +PGUP/PGDWN without Shift.) +.TP +.B d +Activate/deactivate deinterlacer. +.TP +.B A +Cycle aspect ratio override. +.UNINDENT +.sp +(The following keys are valid only when using a video output that supports the +corresponding adjustment, or the software equalizer (\fB\-\-vf=eq\fP).) +.INDENT 0.0 +.TP +.B 1 and 2 +Adjust contrast. +.TP +.B 3 and 4 +Adjust brightness. +.TP +.B 5 and 6 +Adjust gamma. +.TP +.B 7 and 8 +Adjust saturation. +.TP +.B Alt+0 (and command+0 on OSX) +Resize video window to half its original size. +.TP +.B Alt+1 (and command+1 on OSX) +Resize video window to its original size. +.TP +.B Alt+2 (and command+2 on OSX) +Resize video window to double its original size. +.TP +.B command + f (OSX only) +Toggle fullscreen (see also \fB\-\-fs\fP). +.UNINDENT +.sp +(The following keys are valid if you have a keyboard with multimedia keys.) +.INDENT 0.0 +.TP +.B PAUSE +Pause. +.TP +.B STOP +Stop playing and quit. +.TP +.B PREVIOUS and NEXT +Seek backward/forward 1 minute. +.UNINDENT +.sp +If you miss some older key bindings, look at \fBetc/restore\-old\-bindings.conf\fP +in the mpv git repository. +.SS Mouse Control +.INDENT 0.0 +.TP +.B button 3 and button 4 +Seek backward/forward 1 minute. +.TP +.B button 5 and button 6 +Decrease/increase volume. +.UNINDENT +.SH USAGE +.sp +Command line arguments starting with \fB\-\fP are interpreted as options, +everything else as filenames or URLs. All options except \fIflag\fP options (or +choice options which include \fByes\fP) require a parameter in the form +\fB\-\-option=value\fP\&. +.sp +One exception is the lone \fB\-\fP (without anything else), which means media data +will be read from stdin. Also, \fB\-\-\fP (without anything else) will make the +player interpret all following arguments as filenames, even if they start with +\fB\-\fP\&. (To play a file named \fB\-\fP, you need to use \fB\&./\-\fP\&.) +.sp +Every \fIflag\fP option has a \fIno\-flag\fP counterpart, e.g. the opposite of the +\fB\-\-fs\fP option is \fB\-\-no\-fs\fP\&. \fB\-\-fs=yes\fP is same as \fB\-\-fs\fP, \fB\-\-fs=no\fP +is the same as \fB\-\-no\-fs\fP\&. +.sp +If an option is marked as \fI(XXX only)\fP, it will only work in combination with +the \fIXXX\fP option or if \fIXXX\fP is compiled in. +.SS Legacy option syntax +.sp +The \fB\-\-option=value\fP syntax is not strictly enforced, and the alternative +legacy syntax \fB\-option value\fP and \fB\-\-option value\fP will also work. This is +mostly for compatibility with MPlayer. Using these should be avoided. Their +semantics can change any time in the future. +.sp +For example, the alternative syntax will consider an argument following the +option a filename. \fBmpv \-fs no\fP will attempt to play a file named \fBno\fP, +because \fB\-\-fs\fP is a flag option that requires no parameter. If an option +changes and its parameter becomes optional, then a command line using the +alternative syntax will break. +.sp +Currently, the parser makes no difference whether an option starts with \fB\-\-\fP +or a single \fB\-\fP\&. This might also change in the future, and \fB\-\-option value\fP +might always interpret \fBvalue\fP as filename in order to reduce ambiguities. +.SS Escaping spaces and other special characters +.sp +Keep in mind that the shell will partially parse and mangle the arguments you +pass to mpv. For example, you might need to quote or escape options and +filenames: +.INDENT 0.0 +.INDENT 3.5 +\fBmpv "filename with spaces.mkv" \-\-title="window title"\fP +.UNINDENT +.UNINDENT +.sp +It gets more complicated if the suboption parser is involved. The suboption +parser puts several options into a single string, and passes them to a +component at once, instead of using multiple options on the level of the +command line. +.sp +The suboption parser can quote strings with \fB"\fP and \fB[...]\fP\&. +Additionally, there is a special form of quoting with \fB%n%\fP described below. +.sp +For example, assume the hypothetical \fBfoo\fP filter can take multiple options: +.INDENT 0.0 +.INDENT 3.5 +\fBmpv test.mkv \-\-vf=foo:option1=value1:option2:option3=value3,bar\fP +.UNINDENT +.UNINDENT +.sp +This passes \fBoption1\fP and \fBoption3\fP to the \fBfoo\fP filter, with \fBoption2\fP +as flag (implicitly \fBoption2=yes\fP), and adds a \fBbar\fP filter after that. If +an option contains spaces or characters like \fB,\fP or \fB:\fP, you need to quote +them: +.INDENT 0.0 +.INDENT 3.5 +\fBmpv \(aq\-\-vf=foo:option1="option value with spaces",bar\(aq\fP +.UNINDENT +.UNINDENT +.sp +Shells may actually strip some quotes from the string passed to the commandline, +so the example quotes the string twice, ensuring that mpv receives the \fB"\fP +quotes. +.sp +The \fB[...]\fP form of quotes wraps everything between \fB[\fP and \fB]\fP\&. It\(aqs +useful with shells that don\(aqt interpret these characters in the middle of +an argument (like bash). These quotes are balanced (since mpv 0.9.0): the \fB[\fP +and \fB]\fP nest, and the quote terminates on the last \fB]\fP that has no matching +\fB[\fP within the string. (For example, \fB[a[b]c]\fP results in \fBa[b]c\fP\&.) +.sp +The fixed\-length quoting syntax is intended for use with external +scripts and programs. +.sp +It is started with \fB%\fP and has the following format: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +%n%string_of_length_n +.ft P +.fi +.UNINDENT +.UNINDENT +.INDENT 0.0 +.INDENT 3.5 +.IP "Examples" +.sp +\fBmpv \(aq\-\-vf=foo:option1=%11%quoted text\(aq test.avi\fP +.sp +Or in a script: +.sp +\fBmpv \-\-vf=foo:option1=%\(gaexpr length "$NAME"\(ga%"$NAME" test.avi\fP +.UNINDENT +.UNINDENT +.sp +Suboptions passed to the client API are also subject to escaping. Using +\fBmpv_set_option_string()\fP is exactly like passing \fB\-\-name=data\fP to the +command line (but without shell processing of the string). Some options +support passing values in a more structured way instead of flat strings, and +can avoid the suboption parsing mess. For example, \fB\-\-vf\fP supports +\fBMPV_FORMAT_NODE\fP, which lets you pass suboptions as a nested data structure +of maps and arrays. +.SS Paths +.sp +Some care must be taken when passing arbitrary paths and filenames to mpv. For +example, paths starting with \fB\-\fP will be interpreted as options. Likewise, +if a path contains the sequence \fB://\fP, the string before that might be +interpreted as protocol prefix, even though \fB://\fP can be part of a legal +UNIX path. To avoid problems with arbitrary paths, you should be sure that +absolute paths passed to mpv start with \fB/\fP, and prefix relative paths with +\fB\&./\fP\&. +.sp +Using the \fBfile://\fP pseudo\-protocol is discouraged, because it involves +strange URL unescaping rules. +.sp +The name \fB\-\fP itself is interpreted as stdin, and will cause mpv to disable +console controls. (Which makes it suitable for playing data piped to stdin.) +.sp +The special argument \fB\-\-\fP can be used to stop mpv from interpreting the +following arguments as options. +.sp +When using the client API, you should strictly avoid using \fBmpv_command_string\fP +for invoking the \fBloadfile\fP command, and instead prefer e.g. \fBmpv_command\fP +to avoid the need for filename escaping. +.sp +For paths passed to suboptions, the situation is further complicated by the +need to escape special characters. To work this around, the path can be +additionally wrapped in the fixed\-length syntax, e.g. \fB%n%string_of_length_n\fP +(see above). +.sp +Some mpv options interpret paths starting with \fB~\fP\&. Currently, the prefix +\fB~~/\fP expands to the mpv configuration directory (usually \fB~/.config/mpv/\fP). +\fB~/\fP expands to the user\(aqs home directory. (The trailing \fB/\fP is always +required.) There are the following paths as well: +.TS +center; +|l|l|. +_ +T{ +Name +T} T{ +Meaning +T} +_ +T{ +\fB~~home/\fP +T} T{ +same as \fB~~/\fP +T} +_ +T{ +\fB~~global/\fP +T} T{ +the global config path, if available (not on win32) +T} +_ +T{ +\fB~~osxbundle/\fP +T} T{ +the OSX bundle resource path (OSX only) +T} +_ +T{ +\fB~~desktop/\fP +T} T{ +the path to the desktop (win32, OSX) +T} +_ +.TE +.SS Per\-File Options +.sp +When playing multiple files, any option given on the command line usually +affects all files. Example: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +mpv \-\-a file1.mkv \-\-b file2.mkv \-\-c +.ft P +.fi +.UNINDENT +.UNINDENT +.TS +center; +|l|l|. +_ +T{ +File +T} T{ +Active options +T} +_ +T{ +file1.mkv +T} T{ +\fB\-\-a \-\-b \-\-c\fP +T} +_ +T{ +file2.mkv +T} T{ +\fB\-\-a \-\-b \-\-c\fP +T} +_ +.TE +.sp +(This is different from MPlayer and mplayer2.) +.sp +Also, if any option is changed at runtime (via input commands), they are not +reset when a new file is played. +.sp +Sometimes, it is useful to change options per\-file. This can be achieved by +adding the special per\-file markers \fB\-\-{\fP and \fB\-\-}\fP\&. (Note that you must +escape these on some shells.) Example: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +mpv \-\-a file1.mkv \-\-b \-\-\e{ \-\-c file2.mkv \-\-d file3.mkv \-\-e \-\-\e} file4.mkv \-\-f +.ft P +.fi +.UNINDENT +.UNINDENT +.TS +center; +|l|l|. +_ +T{ +File +T} T{ +Active options +T} +_ +T{ +file1.mkv +T} T{ +\fB\-\-a \-\-b \-\-f\fP +T} +_ +T{ +file2.mkv +T} T{ +\fB\-\-a \-\-b \-\-f \-\-c \-\-d \-\-e\fP +T} +_ +T{ +file3.mkv +T} T{ +\fB\-\-a \-\-b \-\-f \-\-c \-\-d \-\-e\fP +T} +_ +T{ +file4.mkv +T} T{ +\fB\-\-a \-\-b \-\-f\fP +T} +_ +.TE +.sp +Additionally, any file\-local option changed at runtime is reset when the current +file stops playing. If option \fB\-\-c\fP is changed during playback of +\fBfile2.mkv\fP, it is reset when advancing to \fBfile3.mkv\fP\&. This only affects +file\-local options. The option \fB\-\-a\fP is never reset here. +.SS List Options +.sp +Some options which store lists of option values can have action suffixes. For +example, you can set a \fB,\fP\-separated list of filters with \fB\-\-vf\fP, but the +option also allows you to append filters with \fB\-\-vf\-append\fP\&. +.sp +Options for filenames do not use \fB,\fP as separator, but \fB:\fP (Unix) or \fB;\fP +(Windows). +.TS +center; +|l|l|. +_ +T{ +Suffix +T} T{ +Meaning +T} +_ +T{ +\-add +T} T{ +Append 1 or more items (may become alias for \-append) +T} +_ +T{ +\-append +T} T{ +Append single item (avoids need for escaping) +T} +_ +T{ +\-clr +T} T{ +Clear the option +T} +_ +T{ +\-del +T} T{ +Delete an existing item by integer index +T} +_ +T{ +\-pre +T} T{ +Prepend 1 or more items +T} +_ +T{ +\-set +T} T{ +Set a list of items +T} +_ +.TE +.sp +Although some operations allow specifying multiple \fB,\fP\-separated items, using +this is strongly discouraged and deprecated, except for \fB\-set\fP\&. +.sp +Without suffix, the action taken is normally \fB\-set\fP\&. +.sp +Some options (like \fB\-\-sub\-file\fP, \fB\-\-audio\-file\fP, \fB\-\-opengl\-shader\fP) are +aliases for the proper option with \fB\-append\fP action. For example, +\fB\-\-sub\-file\fP is an alias for \fB\-\-sub\-files\-append\fP\&. +.SS Playing DVDs +.sp +DVDs can be played with the \fBdvd://[title]\fP syntax. The optional +title specifier is a number which selects between separate video +streams on the DVD. If no title is given (\fBdvd://\fP) then the longest +title is selected automatically by the library. This is usually what +you want. mpv does not support DVD menus. +.sp +DVDs which have been copied on to a hard drive or other mounted +filesystem (by e.g. the \fBdvdbackup\fP tool) are accommodated by +specifying the path to the local copy: \fB\-\-dvd\-device=PATH\fP\&. +Alternatively, running \fBmpv PATH\fP should auto\-detect a DVD directory +tree and play the longest title. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +DVD library choices +.sp +mpv uses a different default DVD library than MPlayer. MPlayer +uses libdvdread by default, and mpv uses libdvdnav by default. +Both libraries are developed in parallel, but libdvdnav is +intended to support more sophisticated DVD features such as menus +and multi\-angle playback. mpv uses libdvdnav for files specified +as either \fBdvd://...\fP or \fBdvdnav://...\fP\&. To use libdvdread, +which will produce behavior more like MPlayer, specify +\fBdvdread://...\fP instead. Some users have experienced problems +when using libdvdnav, in which playback gets stuck in a DVD menu +stream. These problems are reported to go away when auto\-selecting +the title (\fBdvd://\fP rather than \fBdvd://1\fP) or when using +libdvdread (e.g. \fBdvdread://0\fP). There are also outstanding bugs +in libdvdnav with seeking backwards and forwards in a video +stream. Specify \fBdvdread://...\fP to fix such problems. +.UNINDENT +.UNINDENT +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +DVD subtitles +.sp +DVDs use image\-based subtitles. Image subtitles are implemented as +a bitmap video stream which can be superimposed over the main +movie. mpv\(aqs subtitle styling and positioning options and keyboard +shortcuts generally do not work with image\-based subtitles. +Exceptions include options like \fB\-\-stretch\-dvd\-subs\fP and +\fB\-\-stretch\-image\-subs\-to\-screen\fP\&. +.UNINDENT +.UNINDENT +.SH CONFIGURATION FILES +.SS Location and Syntax +.sp +You can put all of the options in configuration files which will be read every +time mpv is run. The system\-wide configuration file \(aqmpv.conf\(aq is in your +configuration directory (e.g. \fB/etc/mpv\fP or \fB/usr/local/etc/mpv\fP), the +user\-specific one is \fB~/.config/mpv/mpv.conf\fP\&. For details and platform +specifics (in particular Windows paths) see the \fI\%FILES\fP section. +.sp +User\-specific options override system\-wide options and options given on the +command line override either. The syntax of the configuration files is +\fBoption=value\fP\&. Everything after a \fI#\fP is considered a comment. Options +that work without values can be enabled by setting them to \fIyes\fP and disabled by +setting them to \fIno\fP\&. Even suboptions can be specified in this way. +.INDENT 0.0 +.INDENT 3.5 +.IP "Example configuration file" +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +# Use opengl video output by default. +vo=opengl +# Use quotes for text that can contain spaces: +status\-msg="Time: ${time\-pos}" +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.UNINDENT +.SS Escaping spaces and special characters +.sp +This is done like with command line options. The shell is not involved here, +but option values still need to be quoted as a whole if it contains certain +characters like spaces. A config entry can be quoted with \fB"\fP, +as well as with the fixed\-length syntax (\fB%n%\fP) mentioned before. This is like +passing the exact contents of the quoted string as command line option. C\-style +escapes are currently _not_ interpreted on this level, although some options do +this manually. (This is a mess and should probably be changed at some point.) +.SS Putting Command Line Options into the Configuration File +.sp +Almost all command line options can be put into the configuration file. Here +is a small guide: +.TS +center; +|l|l|. +_ +T{ +Option +T} T{ +Configuration file entry +T} +_ +T{ +\fB\-\-flag\fP +T} T{ +\fBflag\fP +T} +_ +T{ +\fB\-opt val\fP +T} T{ +\fBopt=val\fP +T} +_ +T{ +\fB\-\-opt=val\fP +T} T{ +\fBopt=val\fP +T} +_ +T{ +\fB\-opt "has spaces"\fP +T} T{ +\fBopt="has spaces"\fP +T} +_ +.TE +.SS File\-specific Configuration Files +.sp +You can also write file\-specific configuration files. If you wish to have a +configuration file for a file called \(aqvideo.avi\(aq, create a file named +\(aqvideo.avi.conf\(aq with the file\-specific options in it and put it in +\fB~/.config/mpv/\fP\&. You can also put the configuration file in the same directory +as the file to be played. Both require you to set the \fB\-\-use\-filedir\-conf\fP +option (either on the command line or in your global config file). If a +file\-specific configuration file is found in the same directory, no +file\-specific configuration is loaded from \fB~/.config/mpv\fP\&. In addition, the +\fB\-\-use\-filedir\-conf\fP option enables directory\-specific configuration files. +For this, mpv first tries to load a mpv.conf from the same directory +as the file played and then tries to load any file\-specific configuration. +.SS Profiles +.sp +To ease working with different configurations, profiles can be defined in the +configuration files. A profile starts with its name in square brackets, +e.g. \fB[my\-profile]\fP\&. All following options will be part of the profile. A +description (shown by \fB\-\-profile=help\fP) can be defined with the +\fBprofile\-desc\fP option. To end the profile, start another one or use the +profile name \fBdefault\fP to continue with normal options. +.INDENT 0.0 +.INDENT 3.5 +.IP "Example mpv config file with profiles" +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +# normal top\-level option +fullscreen=yes + +# a profile that can be enabled with \-\-profile=big\-cache +[big\-cache] +cache=123400 +demuxer\-readahead\-secs=20 + +[slow] +profile\-desc="some profile name" +# reference a builtin profile +profile=opengl\-hq + +[fast] +vo=vdpau + +# using a profile again extends it +[slow] +framedrop=no +# you can also include other profiles +profile=big\-cache +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.UNINDENT +.SS Auto profiles +.sp +Some profiles are loaded automatically. The following example demonstrates this: +.INDENT 0.0 +.INDENT 3.5 +.IP "Auto profile loading" +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +[protocol.dvd] +profile\-desc="profile for dvd:// streams" +alang=en + +[extension.flv] +profile\-desc="profile for .flv files" +vf=flip +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.UNINDENT +.sp +The profile name follows the schema \fBtype.name\fP, where type can be +\fBprotocol\fP for the input/output protocol in use (see \fB\-\-list\-protocols\fP), +and \fBextension\fP for the extension of the path of the currently played file +(\fInot\fP the file format). +.sp +This feature is very limited, and there are no other auto profiles. +.SH TAKING SCREENSHOTS +.sp +Screenshots of the currently played file can be taken using the \(aqscreenshot\(aq +input mode command, which is by default bound to the \fBs\fP key. Files named +\fBmpv\-shotNNNN.jpg\fP will be saved in the working directory, using the first +available number \- no files will be overwritten. In pseudo\-GUI mode, the +screenshot will be saved somewhere else. See \fI\%PSEUDO GUI MODE\fP\&. +.sp +A screenshot will usually contain the unscaled video contents at the end of the +video filter chain and subtitles. By default, \fBS\fP takes screenshots without +subtitles, while \fBs\fP includes subtitles. +.sp +Unlike with MPlayer, the \fBscreenshot\fP video filter is not required. This +filter was never required in mpv, and has been removed. +.SH TERMINAL STATUS LINE +.sp +During playback, mpv shows the playback status on the terminal. It looks like +something like this: +.INDENT 0.0 +.INDENT 3.5 +\fBAV: 00:03:12 / 00:24:25 (13%) A\-V: \-0.000\fP +.UNINDENT +.UNINDENT +.sp +The status line can be overridden with the \fB\-\-term\-status\-msg\fP option. +.sp +The following is a list of things that can show up in the status line. Input +properties, that can be used to get the same information manually, are also +listed. +.INDENT 0.0 +.IP \(bu 2 +\fBAV:\fP or \fBV:\fP (video only) or \fBA:\fP (audio only) +.IP \(bu 2 +The current time position in \fBHH:MM:SS\fP format (\fBplayback\-time\fP property) +.IP \(bu 2 +The total file duration (absent if unknown) (\fBlength\fP property) +.IP \(bu 2 +Playback speed, e.g. \(ga\(ga x2.0\(ga\(ga. Only visible if the speed is not normal. This +is the user\-requested speed, and not the actual speed (usually they should +be the same, unless playback is too slow). (\fBspeed\fP property.) +.IP \(bu 2 +Playback percentage, e.g. \fB(13%)\fP\&. How much of the file has been played. +Normally calculated out of playback position and duration, but can fallback +to other methods (like byte position) if these are not available. +(\fBpercent\-pos\fP property.) +.IP \(bu 2 +The audio/video sync as \fBA\-V: 0.000\fP\&. This is the difference between +audio and video time. Normally it should be 0 or close to 0. If it\(aqs growing, +it might indicate a playback problem. (\fBavsync\fP property.) +.IP \(bu 2 +Total A/V sync change, e.g. \fBct: \-0.417\fP\&. Normally invisible. Can show up +if there is audio "missing", or not enough frames can be dropped. Usually +this will indicate a problem. (\fBtotal\-avsync\-change\fP property.) +.IP \(bu 2 +Encoding state in \fB{...}\fP, only shown in encoding mode. +.IP \(bu 2 +Display sync state. If display sync is active (\fBdisplay\-sync\-active\fP +property), this shows \fBDS: 2.500/13\fP, where the first number is average +number of vsyncs per video frame (e.g. 2.5 when playing 24Hz videos on 60Hz +screens), which might jitter if the ratio doesn\(aqt round off, or there are +mistimed frames (\fBvsync\-ratio\fP), and the second number of estimated number +of vsyncs which took too long (\fBvo\-delayed\-frame\-count\fP property). The +latter is a heuristic, as it\(aqs generally not possible to determine this with +certainty. +.IP \(bu 2 +Dropped frames, e.g. \fBDropped: 4\fP\&. Shows up only if the count is not 0. Can +grow if the video framerate is higher than that of the display, or if video +rendering is too slow. May also be incremented on "hiccups" and when the video +frame couldn\(aqt be displayed on time. (\fBvo\-drop\-frame\-count\fP property.) +If the decoder drops frames, the number of decoder\-dropped frames is appended +to the display as well, e.g.: \fBDropped: 4/34\fP\&. This happens only if +decoder frame dropping is enabled with the \fB\-\-framedrop\fP options. +(\fBdrop\-frame\-count\fP property.) +.IP \(bu 2 +Cache state, e.g. \fBCache: 2s+134KB\fP\&. Visible if the stream cache is enabled. +The first value shows the amount of video buffered in the demuxer in seconds, +the second value shows \fIadditional\fP data buffered in the stream cache in +kilobytes. (\fBdemuxer\-cache\-duration\fP and \fBcache\-used\fP properties.) +.UNINDENT +.SH PROTOCOLS +.sp +\fBhttp://...\fP, \fBhttps://\fP, ... +.INDENT 0.0 +.INDENT 3.5 +Many network protocols are supported, but the protocol prefix must always +be specified. mpv will never attempt to guess whether a filename is +actually a network address. A protocol prefix is always required. +.sp +Note that not all prefixes are documented here. Undocumented prefixes are +either aliases to documented protocols, or are just redirections to +protocols implemented and documented in FFmpeg. +.sp +\fBdata:\fP is supported in FFmpeg (not in Libav), but needs to be in the +format \fBdata://\fP\&. This is done to avoid ambiguity with filenames. You +can also prefix it with \fBlavf://\fP or \fBffmpeg://\fP\&. +.UNINDENT +.UNINDENT +.sp +\fBytdl://...\fP +.INDENT 0.0 +.INDENT 3.5 +By default, the youtube\-dl hook script (enabled by default for mpv CLI) +only looks at http URLs. Prefixing an URL with \fBytdl://\fP forces it to +be always processed by the script. This can also be used to invoke special +youtube\-dl functionality like playing a video by ID or invoking search. +.sp +Keep in mind that you can\(aqt pass youtube\-dl command line options by this, +and you have to use \fB\-\-ytdl\-raw\-options\fP instead. +.UNINDENT +.UNINDENT +.sp +\fB\-\fP +.INDENT 0.0 +.INDENT 3.5 +Play data from stdin. +.UNINDENT +.UNINDENT +.sp +\fBsmb://PATH\fP +.INDENT 0.0 +.INDENT 3.5 +Play a path from Samba share. +.UNINDENT +.UNINDENT +.sp +\fBbd://[title][/device]\fP \fB\-\-bluray\-device=PATH\fP +.INDENT 0.0 +.INDENT 3.5 +Play a Blu\-ray disc. Currently, this does not accept ISO files. Instead, +you must mount the ISO file as filesystem, and point \fB\-\-bluray\-device\fP +to the mounted directory directly. +.sp +\fBtitle\fP can be: \fBlongest\fP or \fBfirst\fP (selects the default +playlist); \fBmpls/\fP (selects .mpls playlist); +\fB\fP (select playlist with the same index). You can list +the available playlists with \fB\-\-msg\-level=bd=v\fP\&. +.UNINDENT +.UNINDENT +.sp +\fBdvd://[title|[starttitle]\-endtitle][/device]\fP \fB\-\-dvd\-device=PATH\fP +.INDENT 0.0 +.INDENT 3.5 +Play a DVD. DVD menus are not supported. If no title is given, the longest +title is auto\-selected. +.sp +\fBdvdnav://\fP is an old alias for \fBdvd://\fP and does exactly the same +thing. +.UNINDENT +.UNINDENT +.sp +\fBdvdread://...:\fP +.INDENT 0.0 +.INDENT 3.5 +Play a DVD using the old libdvdread code. This is what MPlayer and +older mpv versions use for \fBdvd://\fP\&. Use is discouraged. It\(aqs +provided only for compatibility and for transition, and to work +around outstanding dvdnav bugs (see "DVD library choices" above). +.UNINDENT +.UNINDENT +.sp +\fBtv://[channel][/input_id]\fP \fB\-\-tv\-...\fP +.INDENT 0.0 +.INDENT 3.5 +Analogue TV via V4L. Also useful for webcams. (Linux only.) +.UNINDENT +.UNINDENT +.sp +\fBpvr://\fP \fB\-\-pvr\-...\fP +.INDENT 0.0 +.INDENT 3.5 +PVR. (Linux only.) +.UNINDENT +.UNINDENT +.sp +\fBdvb://[cardnumber@]channel\fP \fB\-\-dvbin\-...\fP +.INDENT 0.0 +.INDENT 3.5 +Digital TV via DVB. (Linux only.) +.UNINDENT +.UNINDENT +.sp +\fBmf://[filemask|@listfile]\fP \fB\-\-mf\-...\fP +.INDENT 0.0 +.INDENT 3.5 +Play a series of images as video. +.UNINDENT +.UNINDENT +.sp +\fBcdda://[device]\fP \fB\-\-cdrom\-device=PATH\fP \fB\-\-cdda\-...\fP +.INDENT 0.0 +.INDENT 3.5 +Play CD. +.UNINDENT +.UNINDENT +.sp +\fBlavf://...\fP +.INDENT 0.0 +.INDENT 3.5 +Access any FFmpeg/Libav libavformat protocol. Basically, this passed the +string after the \fB//\fP directly to libavformat. +.UNINDENT +.UNINDENT +.sp +\fBav://type:options\fP +.INDENT 0.0 +.INDENT 3.5 +This is intended for using libavdevice inputs. \fBtype\fP is the libavdevice +demuxer name, and \fBoptions\fP is the (pseudo\-)filename passed to the +demuxer. +.sp +For example, \fBmpv av://lavfi:mandelbrot\fP makes use of the libavfilter +wrapper included in libavdevice, and will use the \fBmandelbrot\fP source +filter to generate input data. +.sp +\fBavdevice://\fP is an alias. +.UNINDENT +.UNINDENT +.sp +\fBfile://PATH\fP +.INDENT 0.0 +.INDENT 3.5 +A local path as URL. Might be useful in some special use\-cases. Note that +\fBPATH\fP itself should start with a third \fB/\fP to make the path an +absolute path. +.UNINDENT +.UNINDENT +.sp +\fBfd://123\fP +.INDENT 0.0 +.INDENT 3.5 +Read data from the given file descriptor (for example 123). This is similar +to piping data to stdin via \fB\-\fP, but can use an arbitrary file descriptor. +.UNINDENT +.UNINDENT +.sp +\fBfdclose://123\fP +.INDENT 0.0 +.INDENT 3.5 +Like \fBfd://\fP, but the file descriptor is closed after use. When using this +you need to ensure that the same fd URL will only be used once. +.UNINDENT +.UNINDENT +.sp +\fBedl://[edl specification as in edl\-mpv.rst]\fP +.INDENT 0.0 +.INDENT 3.5 +Stitch together parts of multiple files and play them. +.UNINDENT +.UNINDENT +.sp +\fBnull://\fP +.INDENT 0.0 +.INDENT 3.5 +Simulate an empty file. If opened for writing, it will discard all data. +The \fBnull\fP demuxer will specifically pass autoprobing if this protocol +is used (while it\(aqs not automatically invoked for empty files). +.UNINDENT +.UNINDENT +.sp +\fBmemory://data\fP +.INDENT 0.0 +.INDENT 3.5 +Use the \fBdata\fP part as source data. +.UNINDENT +.UNINDENT +.sp +\fBhex://data\fP +.INDENT 0.0 +.INDENT 3.5 +Like \fBmemory://\fP, but the string is interpreted as hexdump. +.UNINDENT +.UNINDENT +.SH PSEUDO GUI MODE +.sp +mpv has no official GUI, other than the OSC (\fI\%ON SCREEN CONTROLLER\fP), which +is not a full GUI and is not meant to be. However, to compensate for the lack +of expected GUI behavior, mpv will in some cases start with some settings +changed to behave slightly more like a GUI mode. +.sp +Currently this happens only in the following cases: +.INDENT 0.0 +.IP \(bu 2 +if started using the \fBmpv.desktop\fP file on Linux (e.g. started from menus +or file associations provided by desktop environments) +.IP \(bu 2 +if started from explorer.exe on Windows (technically, if it was started on +Windows, and all of the stdout/stderr/stdin handles are unset) +.IP \(bu 2 +started out of the bundle on OSX +.IP \(bu 2 +if you manually use \fB\-\-player\-operation\-mode=pseudo\-gui\fP on the command line +.UNINDENT +.sp +This mode applies options from the builtin profile \fBbuiltin\-pseudo\-gui\fP, but +only if these haven\(aqt been set in the user\(aqs config file or on the command line. +Also, for compatibility with the old pseudo\-gui behavior, the options in the +\fBpseudo\-gui\fP profile are applied unconditionally. In addition, the profile +makes sure to enable the pseudo\-GUI mode, so that \fB\-\-profile=pseudo\-gui\fP +works like in older mpv releases. The profiles are currently defined as follows: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +[builtin\-pseudo\-gui] +terminal=no +force\-window=yes +idle=once +screenshot\-directory=~~desktop/ +[pseudo\-gui] +player\-operation\-mode=pseudo\-gui +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +\fBWARNING:\fP +.INDENT 0.0 +.INDENT 3.5 +Currently, you can extend the \fBpseudo\-gui\fP profile in the config file the +normal way. This is deprecated. In future mpv releases, the behavior might +change, and not apply your additional settings, and/or use a different +profile name. +.UNINDENT +.UNINDENT +.SH OPTIONS +.SS Track Selection +.INDENT 0.0 +.TP +.B \fB\-\-alang=\fP +Specify a priority list of audio languages to use. Different container +formats employ different language codes. DVDs use ISO 639\-1 two\-letter +language codes, Matroska, MPEG\-TS and NUT use ISO 639\-2 three\-letter +language codes, while OGM uses a free\-form identifier. See also \fB\-\-aid\fP\&. +.INDENT 7.0 +.INDENT 3.5 +.IP "Examples" +.INDENT 0.0 +.IP \(bu 2 +\fBmpv dvd://1 \-\-alang=hu,en\fP chooses the Hungarian language track +on a DVD and falls back on English if Hungarian is not available. +.IP \(bu 2 +\fBmpv \-\-alang=jpn example.mkv\fP plays a Matroska file with Japanese +audio. +.UNINDENT +.UNINDENT +.UNINDENT +.TP +.B \fB\-\-slang=\fP +Specify a priority list of subtitle languages to use. Different container +formats employ different language codes. DVDs use ISO 639\-1 two letter +language codes, Matroska uses ISO 639\-2 three letter language codes while +OGM uses a free\-form identifier. See also \fB\-\-sid\fP\&. +.INDENT 7.0 +.INDENT 3.5 +.IP "Examples" +.INDENT 0.0 +.IP \(bu 2 +\fBmpv dvd://1 \-\-slang=hu,en\fP chooses the Hungarian subtitle track on +a DVD and falls back on English if Hungarian is not available. +.IP \(bu 2 +\fBmpv \-\-slang=jpn example.mkv\fP plays a Matroska file with Japanese +subtitles. +.UNINDENT +.UNINDENT +.UNINDENT +.TP +.B \fB\-\-aid=\fP +Select audio track. \fBauto\fP selects the default, \fBno\fP disables audio. +See also \fB\-\-alang\fP\&. mpv normally prints available audio tracks on the +terminal when starting playback of a file. +.sp +\fB\-\-audio\fP is an alias for \fB\-\-aid\fP\&. +.sp +\fB\-\-aid=no\fP or \fB\-\-audio=no\fP or \fB\-\-no\-audio\fP disables audio playback. +(The latter variant does not work with the client API.) +.TP +.B \fB\-\-sid=\fP +Display the subtitle stream specified by \fB\fP\&. \fBauto\fP selects +the default, \fBno\fP disables subtitles. +.sp +\fB\-\-sub\fP is an alias for \fB\-\-sid\fP\&. +.sp +\fB\-\-sid=no\fP or \fB\-\-sub=no\fP or \fB\-\-no\-sub\fP disables subtitle decoding. +(The latter variant does not work with the client API.) +.TP +.B \fB\-\-vid=\fP +Select video channel. \fBauto\fP selects the default, \fBno\fP disables video. +.sp +\fB\-\-video\fP is an alias for \fB\-\-vid\fP\&. +.sp +\fB\-\-vid=no\fP or \fB\-\-video=no\fP or \fB\-\-no\-video\fP disables video playback. +(The latter variant does not work with the client API.) +.sp +If video is disabled, mpv will try to download the audio only if media is +streamed with youtube\-dl, because it saves bandwidth. This is done by +setting the ytdl_format to "bestaudio/best" in the ytdl_hook.lua script. +.TP +.B \fB\-\-ff\-aid=\fP, \fB\-\-ff\-sid=\fP, \fB\-\-ff\-vid=\fP +Select audio/subtitle/video streams by the FFmpeg stream index. The FFmpeg +stream index is relatively arbitrary, but useful when interacting with +other software using FFmpeg (consider \fBffprobe\fP). +.sp +Note that with external tracks (added with \fB\-\-sub\-files\fP and similar +options), there will be streams with duplicate IDs. In this case, the +first stream in order is selected. +.TP +.B \fB\-\-edition=\fP +(Matroska files only) +Specify the edition (set of chapters) to use, where 0 is the first. If set +to \fBauto\fP (the default), mpv will choose the first edition declared as a +default, or if there is no default, the first edition defined. +.TP +.B \fB\-\-track\-auto\-selection=\fP +Enable the default track auto\-selection (default: yes). Enabling this will +make the player select streams according to \fB\-\-aid\fP, \fB\-\-alang\fP, and +others. If it is disabled, no tracks are selected. In addition, the player +will not exit if no tracks are selected, and wait instead (this wait mode +is similar to pausing, but the pause option is not set). +.sp +This is useful with \fB\-\-lavfi\-complex\fP: you can start playback in this +mode, and then set select tracks at runtime by setting the filter graph. +Note that if \fB\-\-lavfi\-complex\fP is set before playback is started, the +referenced tracks are always selected. +.UNINDENT +.SS Playback Control +.INDENT 0.0 +.TP +.B \fB\-\-start=\fP +Seek to given time position. +.sp +The general format for absolute times is \fB[[hh:]mm:]ss[.ms]\fP\&. If the time +is given with a prefix of \fB+\fP or \fB\-\fP, the seek is relative from the start +or end of the file. (Since mpv 0.14, the start of the file is always +considered 0.) +.sp +\fBpp%\fP seeks to percent position pp (0\-100). +.sp +\fB#c\fP seeks to chapter number c. (Chapters start from 1.) +.INDENT 7.0 +.INDENT 3.5 +.IP "Examples" +.INDENT 0.0 +.TP +.B \fB\-\-start=+56\fP, \fB\-\-start=+00:56\fP +Seeks to the start time + 56 seconds. +.TP +.B \fB\-\-start=\-56\fP, \fB\-\-start=\-00:56\fP +Seeks to the end time \- 56 seconds. +.TP +.B \fB\-\-start=01:10:00\fP +Seeks to 1 hour 10 min. +.TP +.B \fB\-\-start=50%\fP +Seeks to the middle of the file. +.TP +.B \fB\-\-start=30 \-\-end=40\fP +Seeks to 30 seconds, plays 10 seconds, and exits. +.TP +.B \fB\-\-start=\-3:20 \-\-length=10\fP +Seeks to 3 minutes and 20 seconds before the end of the file, plays +10 seconds, and exits. +.TP +.B \fB\-\-start=\(aq#2\(aq \-\-end=\(aq#4\(aq\fP +Plays chapters 2 and 3, and exits. +.UNINDENT +.UNINDENT +.UNINDENT +.TP +.B \fB\-\-end=