summaryrefslogtreecommitdiffstats
path: root/DOCS/man/mpv.rst
diff options
context:
space:
mode:
authorwm4 <wm4@nowhere>2014-06-20 23:01:12 +0200
committerwm4 <wm4@nowhere>2014-06-20 23:01:12 +0200
commitf5e175647515b5e34c265dadad524e83c695cc93 (patch)
tree3a8b79e8182dc53a5763d7bb37af0c5b283b8e82 /DOCS/man/mpv.rst
parent199e3b27630ae45cd396b8af4fbb5bcccf0e2456 (diff)
downloadmpv-f5e175647515b5e34c265dadad524e83c695cc93.tar.bz2
mpv-f5e175647515b5e34c265dadad524e83c695cc93.tar.xz
DOCS: remove en/ sub-directory
This additional sub-directory doesn't serve any purpose anymore. Get rid of it.
Diffstat (limited to 'DOCS/man/mpv.rst')
-rw-r--r--DOCS/man/mpv.rst720
1 files changed, 720 insertions, 0 deletions
diff --git a/DOCS/man/mpv.rst b/DOCS/man/mpv.rst
new file mode 100644
index 0000000000..ec03c4d252
--- /dev/null
+++ b/DOCS/man/mpv.rst
@@ -0,0 +1,720 @@
+mpv
+###
+
+##############
+a movie player
+##############
+
+:Copyright: GPLv2+
+:Manual section: 1
+:Manual group: multimedia
+
+SYNOPSIS
+========
+
+| **mpv** [options] [file|URL|-]
+| **mpv** [options] --playlist=PLAYLIST
+| **mpv** [options] files
+
+DESCRIPTION
+===========
+
+**mpv** is a movie 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.
+
+Usage examples to get you started quickly can be found at the end of this man
+page.
+
+
+INTERACTIVE CONTROL
+===================
+
+mpv has a fully configurable, command-driven control layer which allows you
+to control mpv using keyboard, mouse, joystick or remote control (with
+LIRC). See the ``--input-`` options for ways to customize it.
+
+Keyboard Control
+----------------
+
+LEFT and RIGHT
+ Seek backward/forward 10 seconds. Shift+arrow does a 1 second exact seek
+ (see ``--hr-seek``).
+
+UP and DOWN
+ Seek forward/backward 1 minute. Shift+arrow does a 5 second exact seek (see
+ ``--hr-seek``).
+
+PGUP and PGDWN
+ Seek forward/backward 10 minutes.
+
+[ and ]
+ Decrease/increase current playback speed by 10%.
+
+{ and }
+ Halve/double current playback speed.
+
+BACKSPACE
+ Reset playback speed to normal.
+
+< and >
+ Go backward/forward in the playlist.
+
+ENTER
+ Go forward in the playlist, even over the end.
+
+p / SPACE
+ Pause (pressing again unpauses).
+
+\.
+ Step forward. Pressing once will pause movie, every consecutive press will
+ play one frame and then go into pause mode again.
+
+,
+ Step backward. Pressing once will pause movie, every consecutive press will
+ play one frame in reverse and then go into pause mode again.
+
+q / ESC
+ Stop playing and quit.
+
+Q
+ Like ``q``, but store the current playback position. Playing the same file
+ later will resume at the old playback position if possible.
+
+U
+ Stop playing (and quit if ``--idle`` is not used).
+
+\+ and -
+ Adjust audio delay by +/- 0.1 seconds.
+
+/ and *
+ Decrease/increase volume.
+
+9 and 0
+ Decrease/increase volume.
+
+( and )
+ Adjust audio balance in favor of left/right channel.
+
+m
+ Mute sound.
+
+\_
+ Cycle through the available video tracks.
+
+\#
+ Cycle through the available audio tracks.
+
+TAB (MPEG-TS and libavformat only)
+ Cycle through the available programs.
+
+f
+ Toggle fullscreen (see also ``--fs``).
+
+T
+ Toggle stay-on-top (see also ``--ontop``).
+
+w and e
+ Decrease/increase pan-and-scan range.
+
+o
+ Toggle OSD states: none / seek / seek + timer / seek + timer + total time.
+
+d
+ Toggle frame dropping states: none / skip display / skip decoding (see
+ ``--framedrop``).
+
+v
+ Toggle subtitle visibility.
+
+j and J
+ Cycle through the available subtitles.
+
+F
+ Toggle displaying "forced subtitles".
+
+x and z
+ Adjust subtitle delay by +/- 0.1 seconds.
+
+V
+ Toggle subtitle VSFilter aspect compatibility mode. See
+ ``--ass-vsfilter-aspect-compat`` for more info.
+
+r and t
+ Move subtitles up/down.
+
+s
+ Take a screenshot.
+
+S
+ Take a screenshot, without subtitles. (Whether this works depends on VO
+ driver support.)
+
+I
+ Show filename on the OSD.
+
+P
+ Show progression bar, elapsed time and total duration on the OSD.
+
+! and @
+ Seek to the beginning of the previous/next chapter. In most cases,
+ "previous" will actually go to the beginning of the current chapter; see
+ ``--chapter-seek-threshold``.
+
+D (``--vo=vdpau``, ``--vf=yadif`` only)
+ Activate/deactivate deinterlacer.
+
+A
+ Cycle through the available DVD angles.
+
+c
+ Change YUV colorspace.
+
+(The following keys are valid only when using a video output that supports the
+corresponding adjustment, or the software equalizer (``--vf=eq``).)
+
+1 and 2
+ Adjust contrast.
+
+3 and 4
+ Adjust brightness.
+
+5 and 6
+ Adjust gamma.
+
+7 and 8
+ Adjust saturation.
+
+(The following keys are valid only on OSX.)
+
+command + 0
+ Resize movie window to half its original size.
+ (On other platforms, you can bind keys to change the ``window-scale``
+ property.)
+
+command + 1
+ Resize movie window to its original size.
+
+command + 2
+ Resize movie window to double its original size.
+
+command + f
+ Toggle fullscreen (see also ``--fs``).
+
+command + [ and command + ]
+ Set movie window alpha.
+
+(The following keys are valid if you have a keyboard with multimedia keys.)
+
+PAUSE
+ Pause.
+
+STOP
+ Stop playing and quit.
+
+PREVIOUS and NEXT
+ Seek backward/forward 1 minute.
+
+(The following keys are only valid if you compiled with TV or DVB input
+support.)
+
+h and k
+ Select previous/next channel.
+
+n
+ Change norm.
+
+u
+ Change channel list.
+
+Mouse Control
+-------------
+
+button 3 and button 4
+ Seek backward/forward 1 minute.
+
+button 5 and button 6
+ Decrease/increase volume.
+
+
+USAGE
+=====
+
+Every *flag* option has a *no-flag* counterpart, e.g. the opposite of the
+``--fs`` option is ``--no-fs``. ``--fs=yes`` is same as ``--fs``, ``--fs=no``
+is the same as ``--no-fs``.
+
+If an option is marked as *(XXX only)*, it will only work in combination with
+the *XXX* option or if *XXX* is compiled in.
+
+.. note::
+
+ The suboption parser (used for example for ``--ao=pcm`` suboptions)
+ supports a special kind of string-escaping intended for use with external
+ GUIs.
+
+It has the following format::
+
+ %n%string_of_length_n
+
+.. admonition:: Examples
+
+ ``mpv --ao=pcm:file=%10%C:test.wav test.avi``
+
+ Or in a script:
+
+ ``mpv --ao=pcm:file=%`expr length "$NAME"`%"$NAME" test.avi``
+
+Paths
+-----
+
+Some care must be taken when passing arbitrary paths and filenames to mpv. For
+example, paths starting with ``-`` will be interpreted as options. Likewise,
+if a path contains the sequence ``://``, the string before that might be
+interpreted as protocol prefix, even though ``://`` 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 ``/``, and relative paths with ``./``.
+
+The name ``-`` itself is interpreted as stdin, and will cause mpv to disable
+console controls. (Which makes it suitable for playing data piped to stdin.)
+
+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 ``%n%string_of_length_n`` syntax (see above).
+
+Some mpv options interpret paths starting with ``~``. Currently, the prefix
+``~~/`` expands to the mpv configuration directory (usually ``~/.mpv/``).
+``~/`` expands to the user's home directory. (The trailing ``/`` is always
+required.)
+
+Per-File Options
+----------------
+
+When playing multiple files, any option given on the command line usually
+affects all files. Example::
+
+ mpv --a file1.mkv --b file2.mkv --c
+
+=============== ===========================
+File Active options
+=============== ===========================
+file1.mkv ``--a --b --c``
+file2.mkv ``--a --b --c``
+=============== ===========================
+
+(This is different from MPlayer and mplayer2.)
+
+Also, if any option is changed at runtime (via input commands), they are not
+reset when a new file is played.
+
+Sometimes, it is useful to change options per-file. This can be achieved by
+adding the special per-file markers ``--{`` and ``--}``. (Note that you must
+escape these on some shells.) Example::
+
+ mpv --a file1.mkv --b --\{ --c file2.mkv --d file3.mkv --e --\} file4.mkv --f
+
+=============== ===========================
+File Active options
+=============== ===========================
+file1.mkv ``--a --b --f``
+file2.mkv ``--a --b --f --c --d --e``
+file3.mkv ``--a --b --f --c --d --e``
+file4.mkv ``--a --b --f``
+=============== ===========================
+
+Additionally, any file-local option changed at runtime is reset when the current
+file stops playing. If option ``--c`` is changed during playback of
+``file2.mkv``, it is reset when advancing to ``file3.mkv``. This only affects
+file-local options. The option ``--a`` is never reset here.
+
+CONFIGURATION FILES
+===================
+
+Location and Syntax
+-------------------
+
+You can put all of the options in configuration files which will be read every
+time mpv is run. The system-wide configuration file 'mpv.conf' is in your
+configuration directory (e.g. ``/etc/mpv`` or ``/usr/local/etc/mpv``), the
+user-specific one is ``~/.mpv/config``.
+User-specific options override system-wide options and options given on the
+command line override either. The syntax of the configuration files is
+``option=<value>``; everything after a *#* is considered a comment. Options
+that work without values can be enabled by setting them to *yes* and disabled by
+setting them to *no*. Even suboptions can be specified in this way.
+
+.. admonition:: Example configuration file
+
+ ::
+
+ # Use opengl video output by default.
+ vo=opengl
+ # Use quotes for text that can contain spaces:
+ status-msg="Time: ${time-pos}"
+
+Putting Command Line Options into the Configuration File
+--------------------------------------------------------
+
+Almost all command line options can be put into the configuration file. Here
+is a small guide:
+
+======================= ========================
+Option Configuration file entry
+======================= ========================
+``--flag`` ``flag``
+``-opt val`` ``opt=val``
+``--opt=val`` ``opt=val``
+``-opt "has spaces"`` ``opt="has spaces"``
+======================= ========================
+
+File-specific Configuration Files
+---------------------------------
+
+You can also write file-specific configuration files. If you wish to have a
+configuration file for a file called 'movie.avi', create a file named
+'movie.avi.conf' with the file-specific options in it and put it in
+``~/.mpv/``. You can also put the configuration file in the same directory
+as the file to be played, as long as you give the ``--use-filedir-conf``
+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 ``~/.mpv``. In addition, the
+``--use-filedir-conf`` 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.
+
+
+Profiles
+--------
+
+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. ``[my-profile]``. All following options will be part of the profile. A
+description (shown by ``--profile=help``) can be defined with the
+``profile-desc`` option. To end the profile, start another one or use the
+profile name ``default`` to continue with normal options.
+
+.. admonition:: Example mpv profile
+
+ ::
+
+ [vo.vdpau]
+ # Use hardware decoding (might break playback of some h264 files)
+ hwdec=vdpau
+
+ [protocol.dvd]
+ profile-desc="profile for dvd:// streams"
+ vf=pp=hb/vb/dr/al/fd
+ alang=en
+
+ [extension.flv]
+ profile-desc="profile for .flv files"
+ vf=flip
+
+ [ao.alsa]
+ device=spdif
+
+
+TAKING SCREENSHOTS
+==================
+
+Screenshots of the currently played file can be taken using the 'screenshot'
+input mode command, which is by default bound to the ``s`` key. Files named
+``shotNNNN.jpg`` will be saved in the working directory, using the first
+available number - no files will be overwritten.
+
+A screenshot will usually contain the unscaled video contents at the end of the
+video filter chain and subtitles. By default, ``S`` takes screenshots without
+subtitles, while ``s`` includes subtitles.
+
+The ``screenshot`` video filter is not required when using a recommended GUI
+video output driver. It should normally not be added to the config file, as
+taking screenshots is handled by the VOs, and adding the screenshot filter will
+break hardware decoding. (The filter may still be useful for taking screenshots
+at a certain point within the video chain when using multiple video filters.)
+
+PROTOCOLS
+=========
+
+``http://...``, ``https://``, ...
+ 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.
+
+``-``
+ Play data from stdin.
+
+``smb://PATH``
+ Play a path from Samba share.
+
+``bd://[title][/device]`` ``--bluray-device=PATH``
+ Play a Blu-Ray disc. Currently, this does not accept iso files. Instead,
+ you must mount the iso file as filesystem, and point ``--bluray-device``
+ to the mounted directly.
+
+``bdnav://[title][/device]``
+ Play a Blu-Ray disc, with navigation features enabled. This feature is
+ permanently experimental.
+
+``dvd://[title|[starttitle]-endtitle][/device]`` ``--dvd-device=PATH``
+ Play a DVD. If you want dvdnav menus, use ``dvd://menu``. If no title
+ is given, the longest title is auto-selected.
+
+ ``dvdnav://`` is an old alias for ``dvd://`` and does exactly the same
+ thing.
+
+``dvdread://...:``
+ Play a DVD using the old libdvdread code. This is what MPlayer and older
+ mpv versions use for ``dvd://``. Use is discouraged. It's provided only
+ for compatibility and for transition.
+
+``tv://[channel][/input_id]`` ``--tv-...``
+ Analogue TV via V4L. Also useful for webcams. (Linux only.)
+
+``pvr://`` ``--pvr-...``
+ PVR. (Linux only.)
+
+``dvb://[cardnumber@]channel`` ``--dvbin-...``
+ Digital TV via DVB. (Linux only.)
+
+``mf://[filemask|@listfile]`` ``--mf-...``
+ Play a series of images as video.
+
+``cdda://track[-endtrack][:speed][/device]`` ``--cdrom-device=PATH`` ``--cdda-...``
+ Play CD.
+
+``lavf://...``
+ Access any FFmpeg/Libav libavformat protocol. Basically, this passed the
+ string after the ``//`` directly to libavformat.
+
+``av://type:options``
+ This is intended for using libavdevice inputs. ``type`` is the libavdevice
+ demuxer name, and ``options`` is the (pseudo-)filename passed to the
+ demuxer.
+
+ For example, ``mpv av://lavfi:mandelbrot`` makes use of the libavfilter
+ wrapper included in libavdevice, and will use the ``mandelbrot`` source
+ filter to generate input data.
+
+ ``avdevice://`` is an alias.
+
+``file://PATH``
+ A local path as URL. Might be useful in some special use-cases. Note that
+ ``PATH`` itself should start with a third ``/`` to make the path an
+ absolute path.
+
+``edl://[edl specification as in edl-mpv.rst]``
+ Stitch together parts of multiple files and play them.
+
+``null://``
+ Simulate an empty file.
+
+``memory://data``
+ Use the ``data`` part as source data.
+
+.. include:: options.rst
+
+.. include:: ao.rst
+
+.. include:: vo.rst
+
+.. include:: af.rst
+
+.. include:: vf.rst
+
+.. include:: encode.rst
+
+.. include:: input.rst
+
+.. include:: osc.rst
+
+.. include:: lua.rst
+
+.. include:: changes.rst
+
+ENVIRONMENT VARIABLES
+=====================
+
+There are a number of environment variables that can be used to control the
+behavior of mpv.
+
+``HOME``
+ Used to determine mpv config directory: ``$HOME/.mpv``
+
+``TERM``
+ Used to determine terminal type.
+
+``MPV_HOME``
+ Directory where mpv looks for user settings. Overrides ``HOME``, and mpv
+ will try to load the config file as ``$MPV_HOME/config``.
+
+``MPV_VERBOSE`` (see also ``-v`` and ``--msg-level``)
+ Set the initial verbosity level across all message modules (default: 0).
+ This is an integer, and the resulting verbosity corresponds to the number
+ of ``--v`` options passed to the command line.
+
+``MPV_LEAK_REPORT``
+ If set to ``1``, enable internal talloc leak reporting. Note that this can
+ cause trouble with multithreading, so only developers should use this.
+
+``LADSPA_PATH``
+ Specifies the search path for LADSPA plugins. If it is unset, fully
+ qualified path names must be used.
+
+``DISPLAY``
+ Standard X11 display name to use.
+
+FFmpeg/Libav:
+ This library accesses various environment variables. However, they are not
+ centrally documented, and documenting them is not our job. Therefore, this
+ list is incomplete.
+
+ Notable environment variables:
+
+ ``http_proxy``
+ URL to proxy for ``http://`` and ``https://`` URLs.
+
+ ``no_proxy``
+ List of domain patterns for which no proxy should be used.
+ List entries are separated by ``,``. Patterns can include ``*``.
+
+libdvdcss:
+ ``DVDCSS_CACHE``
+ Specify a directory in which to store title key values. This will
+ speed up descrambling of DVDs which are in the cache. The
+ ``DVDCSS_CACHE`` directory is created if it does not exist, and a
+ subdirectory is created named after the DVD's title or manufacturing
+ date. If ``DVDCSS_CACHE`` is not set or is empty, libdvdcss will use
+ the default value which is ``${HOME}/.dvdcss/`` under Unix and
+ the roaming application data directory (``%APPDATA%``) under
+ Windows. The special value "off" disables caching.
+
+ ``DVDCSS_METHOD``
+ Sets the authentication and decryption method that libdvdcss will use
+ to read scrambled discs. Can be one of ``title``, ``key`` or ``disc``.
+
+ key
+ is the default method. libdvdcss will use a set of calculated
+ player keys to try and get the disc key. This can fail if the drive
+ does not recognize any of the player keys.
+
+ disc
+ is a fallback method when key has failed. Instead of using player
+ keys, libdvdcss will crack the disc key using a brute force
+ algorithm. This process is CPU intensive and requires 64 MB of
+ memory to store temporary data.
+
+ title
+ is the fallback when all other methods have failed. It does not
+ rely on a key exchange with the DVD drive, but rather uses a crypto
+ attack to guess the title key. On rare cases this may fail because
+ there is not enough encrypted data on the disc to perform a
+ statistical attack, but on the other hand it is the only way to
+ decrypt a DVD stored on a hard disc, or a DVD with the wrong region
+ on an RPC2 drive.
+
+ ``DVDCSS_RAW_DEVICE``
+ Specify the raw device to use. Exact usage will depend on your
+ operating system, the Linux utility to set up raw devices is raw(8)
+ for instance. Please note that on most operating systems, using a raw
+ device requires highly aligned buffers: Linux requires a 2048 bytes
+ alignment (which is the size of a DVD sector).
+
+ ``DVDCSS_VERBOSE``
+ Sets the libdvdcss verbosity level.
+
+ :0: Outputs no messages at all.
+ :1: Outputs error messages to stderr.
+ :2: Outputs error messages and debug messages to stderr.
+
+ ``DVDREAD_NOKEYS``
+ Skip retrieving all keys on startup. Currently disabled.
+
+ ``HOME``
+ FIXME: Document this.
+
+
+EXIT CODES
+==========
+
+Normally **mpv** returns 0 as exit code after finishing playback successfully.
+If errors happen, the following exit codes can be returned:
+
+ :1: Error initializing mpv. This is also returned if unknown options are
+ passed to mpv.
+ :2: The file passed to mpv couldn't be played. This is somewhat fuzzy:
+ currently, playback of a file is considered to be successful if
+ initialization was mostly successful, even if playback fails
+ immediately after initialization.
+ :3: There were some files that could be played, and some files which
+ couldn't (using the definition of success from above).
+
+Note that quitting the player manually will always lead to exit code 0,
+overriding the exit code that would be returned normally. Also, the ``quit``
+input command can take an exit code: in this case, that exit code is returned.
+
+FILES
+=====
+
+``/usr/local/etc/mpv/mpv.conf``
+ mpv system-wide settings (depends on ``--prefix`` passed to configure)
+
+``~/.mpv/config``
+ mpv user settings
+
+``~/.mpv/input.conf``
+ input bindings (see ``--input-keylist`` for the full list)
+
+``~/.mpv/lua/``
+ All files in this directly are loaded as if they were passed to the
+ ``--lua`` option. They are loaded in alphabetical order, and sub-directories
+ and files with no ``.lua`` extension are ignored. The ``--load-scripts=no``
+ option disables loading these files.
+
+
+EXAMPLES OF MPV USAGE
+=====================
+
+Blu-ray playback:
+ - ``mpv bd:////path/to/disc``
+ - ``mpv bd:// --bluray-device=/path/to/disc``
+
+Play in Japanese with English subtitles:
+ ``mpv dvd://1 --alang=ja --slang=en``
+
+Play only chapters 5, 6, 7:
+ ``mpv dvd://1 --chapter=5-7``
+
+Play only titles 5, 6, 7:
+ ``mpv dvd://5-7``
+
+Play a multiangle DVD:
+ ``mpv dvd://1 --dvd-angle=2``
+
+Play from a different DVD device:
+ ``mpv dvd://1 --dvd-device=/dev/dvd2``
+
+Play DVD video from a directory with VOB files:
+ ``mpv dvd://1 --dvd-device=/path/to/directory/``
+
+Stream from HTTP:
+ ``mpv http://example.com/example.avi``
+
+Stream using RTSP:
+ ``mpv rtsp://server.example.com/streamName``
+
+Play a libavfilter graph:
+ ``mpv avdevice://lavfi:mandelbrot``
+
+AUTHORS
+=======
+
+mpv is a MPlayer fork based on mplayer2, which in turn is a fork of MPlayer.
+
+MPlayer was initially written by Arpad Gereoffy. See the ``AUTHORS`` file for
+a list of some of the many other contributors.
+
+MPlayer is (C) 2000-2013 The MPlayer Team
+
+This man page was written mainly by Gabucino, Jonas Jermann and Diego Biurrun.