diff options
Diffstat (limited to 'DOCS/man/mpv.rst')
| -rw-r--r-- | DOCS/man/mpv.rst | 686 |
1 files changed, 544 insertions, 142 deletions
diff --git a/DOCS/man/mpv.rst b/DOCS/man/mpv.rst index 92c0052c55..3b29124ea7 100644 --- a/DOCS/man/mpv.rst +++ b/DOCS/man/mpv.rst @@ -39,9 +39,15 @@ LIRC support - configure remotes as input devices instead). See the ``--input-`` options for ways to customize it. -The following listings are not necessarily complete. See ``etc/input.conf`` for -a list of default bindings. User ``input.conf`` files and Lua scripts can -define additional key bindings. +The following listings are not necessarily complete. See ``etc/input.conf`` +in the mpv source files for a list of default bindings. User ``input.conf`` +files and Lua scripts can define additional key bindings. + +See `COMMAND INTERFACE`_ and `Key names`_ sections for more details on +configuring keybindings. + +See also ``--input-test`` for interactive binding details by key, and the +`stats`_ built-in script for key bindings list (including print to terminal). Keyboard Control ---------------- @@ -58,7 +64,7 @@ Ctrl+LEFT and Ctrl+RIGHT Seek to the previous/next subtitle. Subject to some restrictions and might not always work; see ``sub-seek`` command. -Ctrl+Shift+Left and Ctrl+Shift+Right +Ctrl+Shift+LEFT and Ctrl+Shift+RIGHT Adjust subtitle delay so that the next or previous subtitle is displayed now. This is especially useful to sync subtitles to audio. @@ -88,7 +94,7 @@ Shift+Ctrl+BACKSPACE ENTER Go forward in the playlist. -p / SPACE +p and SPACE Pause (pressing again unpauses). \. @@ -104,7 +110,8 @@ q Q Like ``q``, but store the current playback position. Playing the same file - later will resume at the old playback position if possible. + later will resume at the old playback position if possible. See + `RESUMING PLAYBACK`_. / and * Decrease/increase volume. @@ -121,6 +128,9 @@ m \# Cycle through the available audio tracks. +E + Cycle through the available Editions. + f Toggle fullscreen (see also ``--fs``). @@ -134,7 +144,7 @@ w and W Decrease/increase pan-and-scan range. The ``e`` key does the same as ``W`` currently, but use is discouraged. -o (also P) +o and P Show progression bar, elapsed time and total duration on the OSD. O @@ -156,13 +166,16 @@ l L Toggle infinite looping. -Ctrl + and Ctrl - +Ctrl++ and Ctrl+- Adjust audio delay (A/V sync) by +/- 0.1 seconds. +Shift+g and Shift+f + Adjust subtitle font size by +/- 10%. + u - Switch between applying no style overrides to SSA/ASS subtitles, and - overriding them almost completely with the normal subtitle style. See - ``--sub-ass-override`` for more info. + Switch between applying only ``--sub-ass-*`` overrides (default) to SSA/ASS + subtitles, and overriding them almost completely with the normal subtitle + style. See ``--sub-ass-override`` for more info. V Toggle subtitle VSFilter aspect compatibility mode. See @@ -179,7 +192,7 @@ S Take a screenshot, without subtitles. (Whether this works depends on VO driver support.) -Ctrl s +Ctrl+s Take a screenshot, as the window shows it (with subtitles, OSD, and scaled video). @@ -192,39 +205,40 @@ Shift+PGUP and Shift+PGDWN Seek backward or forward by 10 minutes. (This used to be mapped to PGUP/PGDWN without Shift.) +b + Activate/deactivate debanding. + d - Activate/deactivate deinterlacer. + Cycle the deinterlacing filter. A Cycle aspect ratio override. -Ctrl h +Ctrl+h Toggle hardware video decoding on/off. Alt+LEFT, Alt+RIGHT, Alt+UP, Alt+DOWN Move the video rectangle (panning). -Alt + and Alt - - Combining ``Alt`` with the ``+`` or ``-`` keys changes video zoom. +Alt++ and Alt+- + Change video zoom. Alt+BACKSPACE Reset the pan/zoom settings. F8 - Show the playlist and the current position in it (useful only if a UI window - is used, broken on the terminal). + Show the playlist and the current position in it. F9 - Show the list of audio and subtitle streams (useful only if a UI window is - used, broken on the terminal). + Show the list of audio and subtitle streams. i and I Show/toggle an overlay displaying statistics about the currently playing file such as codec, framerate, number of dropped frames and so on. See `STATS`_ for more information. -del - Cycles visibility between never / auto (mouse-move) / always +DEL + Cycle OSC visibility between never / auto (mouse-move) / always \` Show the console. (ESC closes it again. See `CONSOLE`_.) @@ -244,18 +258,58 @@ corresponding adjustment.) 7 and 8 Adjust saturation. -Alt+0 (and command+0 on OSX) +Alt+0 (and Command+0 on macOS) Resize video window to half its original size. -Alt+1 (and command+1 on OSX) +Alt+1 (and Command+1 on macOS) Resize video window to its original size. -Alt+2 (and command+2 on OSX) +Alt+2 (and Command+2 on macOS) Resize video window to double its original size. -command + f (OSX only) +Command + f (macOS only) Toggle fullscreen (see also ``--fs``). +(The following keybindings open a selector in the console that lets you choose +from a list of items by typing part of the desired item and/or by navigating +them with keybindings: ``Down`` and ``Ctrl+n`` go down, ``Up`` and ``Ctrl+p`` go +up, ``Page down`` and ``Ctrl+f`` scroll down one page, and ``Page up`` and +``Ctrl+b`` scroll up one page.) + +g-p + Select a playlist entry. + +g-s + Select a subtitle track. + +g-S + Select a secondary subtitle track. + +g-a + Select an audio track. + +g-v + Select a video track. + +g-t + Select a track of any type. + +g-c + Select a chapter. + +g-l + Select a subtitle line to seek to. This currently requires ``ffmpeg`` in + ``PATH``, or in the same folder as mpv on Windows. + +g-d + Select an audio device. + +g-b + Select a defined input binding. + +g-r + Show the values of all properties. + (The following keys are valid if you have a keyboard with multimedia keys.) PAUSE @@ -267,6 +321,8 @@ STOP PREVIOUS and NEXT Seek backward/forward 1 minute. +ZOOMIN and ZOOMOUT + Change video zoom. If you miss some older key bindings, look at ``etc/restore-old-bindings.conf`` in the mpv git repository. @@ -284,11 +340,28 @@ Forward/Back button Skip to next/previous entry in playlist. Wheel up/down - Seek forward/backward 10 seconds. + Decrease/increase volume. Wheel left/right - Decrease/increase volume. + Seek forward/backward 10 seconds. + +Ctrl+Wheel up/down + Change video zoom. +Context Menu +------------- + +.. warning:: + + This feature is experimental. It may not work with all VOs. A libass based + fallback may be implemented in the future. + +Context Menu is a menu that pops up on the video window on user interaction +(mouse right click, etc.). + +To use this feature, you need to fill the ``menu-data`` property with menu +definition data, and add a keybinding to run the ``context-menu`` command, +which can be done with a user script. USAGE ===== @@ -387,6 +460,9 @@ It is started with ``%`` and has the following format:: ``mpv --vf=foo:option1=%`expr length "$NAME"`%"$NAME" test.avi`` +Note: where applicable with JSON-IPC, ``%n%`` is the length in UTF-8 bytes, +after decoding the JSON data. + Suboptions passed to the client API are also subject to escaping. Using ``mpv_set_option_string()`` is exactly like passing ``--name=data`` to the command line (but without shell processing of the string). Some options @@ -424,23 +500,32 @@ need to escape special characters. To work this around, the path can be additionally wrapped in the fixed-length syntax, e.g. ``%n%string_of_length_n`` (see above). -Some mpv options interpret paths starting with ``~``. Currently, the prefix -``~~/`` expands to the mpv configuration directory (usually ``~/.mpv/``). +Some mpv options interpret paths starting with ``~``. +Currently, the prefix ``~~home/`` expands to the mpv configuration directory +(usually ``~/.config/mpv/``). ``~/`` expands to the user's home directory. (The trailing ``/`` is always required.) The following paths are currently recognized: ================ =============================================================== Name Meaning ================ =============================================================== -``~~/`` mpv config dir (for example ``~/.mpv/``) +``~~/`` If the subpath exists in any of the mpv's config directories + the path of the existing file/dir is returned. Otherwise this + is equivalent to ``~~home/``. + Note that if --no-config is used ``~~/foobar`` will resolve to + ``foobar`` which can be unexpected. ``~/`` user home directory root (similar to shell, ``$HOME``) -``~~home/`` same as ``~~/`` +``~~home/`` mpv config dir (for example ``~/.config/mpv/``) ``~~global/`` the global config path, if available (not on win32) -``~~osxbundle/`` the OSX bundle resource path (OSX only) -``~~desktop/`` the path to the desktop (win32, OSX) -``~~exe_dir`` win32 only: the path to the directory containing the exe (for +``~~osxbundle/`` the macOS bundle resource path (macOS only) +``~~desktop/`` the path to the desktop (win32, macOS) +``~~exe_dir/`` win32 only: the path to the directory containing the exe (for config file purposes; ``$MPV_HOME`` overrides it) -``~~old_home`` do not use +``~~cache/`` the path to application cache data (``~/.cache/mpv/``) + On some platforms, this will be the same as ``~~home/``. +``~~state/`` the path to application state data (``~/.local/state/mpv/``) + On some platforms, this will be the same as ``~~home/``. +``~~old_home/`` do not use ================ =============================================================== @@ -498,24 +583,21 @@ String list and path list options ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ String lists are separated by ``,``. The strings are not parsed or interpreted -by the option system itself. However, most - -Path or file list options use ``:`` (Unix) or ``;`` (Windows) as separator, -instead of ``,``. +by the option system itself. However, most path or file list options use ``:`` +(Unix) or ``;`` (Windows) as separator, instead of ``,``. They support the following operations: ============= =============================================== Suffix Meaning ============= =============================================== --set Set a list of items (using the list separator, interprets escapes) +-set Set a list of items (using the list separator, escaped with backslash) -append Append single item (does not interpret escapes) -add Append 1 or more items (same syntax as -set) -pre Prepend 1 or more items (same syntax as -set) -clr Clear the option (remove all items) -remove Delete item if present (does not interpret escapes) --del Delete 1 or more items by integer index (deprecated) --toggle Append an item, or remove if if it already exists (no escapes) +-toggle Append an item, or remove it if it already exists (no escapes) ============= =============================================== ``-append`` is meant as a simple way to append a single item without having @@ -542,24 +624,31 @@ Suffix Meaning Keys are unique within the list. If an already present key is set, the existing key is removed before the new value is appended. -Filter options -~~~~~~~~~~~~~~ +If you want to pass a value without interpreting it for escapes or ``,``, it is +recommended to use the ``-append`` variant. When using libmpv, prefer using +``MPV_FORMAT_NODE_MAP``; when using a scripting backend or the JSON IPC, use an +appropriate structured data type. + +Prior to mpv 0.33, ``:`` was also recognized as separator by ``-set``. -This is a very complex option type for the ``--af`` and ``--vf`` options only. -They often require complicated escaping. See `VIDEO FILTERS`_ for details. They -support the following operations: +Object settings list options +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This is a very complex option type for some options, such as ``--af`` and ``--vf``. +They often require complicated escaping. See `VIDEO FILTERS`_ for details. + +They support the following operations: ============= =============================================== Suffix Meaning ============= =============================================== --set Set a list of filters (using ``,`` as separator) --append Append single filter --add Append 1 or more filters (same syntax as -set) --pre Prepend 1 or more filters (same syntax as -set) --clr Clear the option (remove all filters) --remove Delete filter if present --del Delete 1 or more filters by integer index or filter label (deprecated) --toggle Append a filter, or remove if if it already exists +-set Set a list of items (using ``,`` as separator) +-append Append single item +-add Append 1 or more items (same syntax as -set) +-pre Prepend 1 or more items (same syntax as -set) +-clr Clear the option (remove all items) +-remove Delete item if present +-toggle Append an item, or remove it if it already exists -help Pseudo operation that prints a help text to the terminal ============= =============================================== @@ -591,34 +680,39 @@ 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/mpv.conf``. For details and platform +user-specific one is ``~/.config/mpv/mpv.conf``. For details and platform specifics (in particular Windows paths) see the `FILES`_ section. 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. +command line override both. 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*, and if the value is omitted, *yes* is implied. Even +suboptions can be specified in this way. .. admonition:: Example configuration file :: - # Use GPU-accelerated video output by default. - vo=gpu - # Use quotes for text that can contain spaces: - term-status-msg="Time: ${time-pos}" + # Don't allow new windows to be larger than the screen. + autofit-larger=100%x100% + # Enable hardware decoding if available, =yes is implied. + hwdec + # Spaces don't have to be escaped. + osd-playing-msg=File: ${filename} -Escaping spaces and special characters +Escaping special characters -------------------------------------- -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 ``"``, -as well as with the fixed-length syntax (``%n%``) 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.) +This is done like with command line options. A config entry can be quoted with +``"``, ``'``, as well as with the fixed-length syntax (``%n%``) mentioned +before. This is like passing the exact contents of the quoted string as a +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). The shell is not involved here, so option +values only need to be quoted to escape ``#`` anywhere in the value, ``"``, +``'`` or ``%`` at the beginning of the value, and leading and trailing +whitespace. Putting Command Line Options into the Configuration File -------------------------------------------------------- @@ -632,7 +726,7 @@ Option Configuration file entry ``--flag`` ``flag`` ``-opt val`` ``opt=val`` ``--opt=val`` ``opt=val`` -``-opt "has spaces"`` ``opt="has spaces"`` +``-opt "has spaces"`` ``opt=has spaces`` ======================= ======================== File-specific Configuration Files @@ -641,11 +735,11 @@ File-specific Configuration Files You can also write file-specific configuration files. If you wish to have a configuration file for a file called 'video.avi', create a file named 'video.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 +``~/.config/mpv/``. You can also put the configuration file in the same directory as the file to be played. Both require you to set 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 +file-specific configuration is loaded from ``~/.config/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. @@ -676,28 +770,239 @@ or at runtime with the ``apply-profile <name>`` command. # a profile that can be enabled with --profile=big-cache [big-cache] cache=yes - demuxer-max-bytes=123400KiB + demuxer-max-bytes=512MiB demuxer-readahead-secs=20 - [slow] - profile-desc="some profile name" - # reference a builtin profile - profile=gpu-hq + [network] + profile-desc="profile for content over network" + force-window=immediate + # you can also include other profiles + profile=big-cache - [fast] - vo=vdpau + [reduce-judder] + video-sync=display-resample + interpolation=yes # using a profile again extends it - [slow] - framedrop=no - # you can also include other profiles - profile=big-cache + [network] + demuxer-max-back-bytes=512MiB + # reference a builtin profile + profile=fast + +Runtime profiles +---------------- +Profiles can be set at runtime with ``apply-profile`` command. Since this +operation is "destructive" (every item in a profile is simply set as an +option, overwriting the previous value), you can't just enable and disable +profiles again. -Auto profiles -------------- +As a partial remedy, there is a way to make profiles save old option values +before overwriting them with the profile values, and then restoring the old +values at a later point using ``apply-profile <profile-name> restore``. + +This can be enabled with the ``profile-restore`` option, which takes one of +the following options: + + ``default`` + Does nothing, and nothing can be restored (default). + + ``copy`` + When applying a profile, copy the old values of all profile options to a + backup before setting them from the profile. These options are reset to + their old values using the backup when restoring. + + Every profile has its own list of backed up values. If the backup + already exists (e.g. if ``apply-profile name`` was called more than + once in a row), the existing backup is no changed. The restore operation + will remove the backup. + + It's important to know that restoring does not "undo" setting an option, + but simply copies the old option value. Consider for example ``vf-add``, + appends an entry to ``vf``. This mechanism will simply copy the entire + ``vf`` list, and does _not_ execute the inverse of ``vf-add`` (that + would be ``vf-remove``) on restoring. + + Note that if a profile contains recursive profiles (via the ``profile`` + option), the options in these recursive profiles are treated as if they + were part of this profile. The referenced profile's backup list is not + used when creating or using the backup. Restoring a profile does not + restore referenced profiles, only the options of referenced profiles (as + if they were part of the main profile). + + ``copy-equal`` + Similar to ``copy``, but restore an option only if it has the same value + as the value effectively set by the profile. This tries to deal with + the situation when the user does not want the option to be reset after + interactively changing it. + +.. admonition:: Example + + :: + + [something] + profile-restore=copy-equal + vf-add=rotate=PI/2 # rotate by 90 degrees + + Then running these commands will result in behavior as commented: + + :: + + set vf vflip + apply-profile something + vf add hflip + apply-profile something + # vf == vflip,rotate=PI/2,hflip,rotate=PI/2 + apply-profile something restore + # vf == vflip + +Conditional auto profiles +------------------------- + +Profiles which have the ``profile-cond`` option set are applied automatically +if the associated condition matches (unless auto profiles are disabled). The +option takes a string, which is interpreted as Lua expression. If the +expression evaluates as truthy, the profile is applied. If the expression +errors or evaluates as falsy, the profile is not applied. This Lua code +execution is not sandboxed. + +Any variables in condition expressions can reference properties. If an +identifier is not already defined by Lua or mpv, it is interpreted as property. +For example, ``pause`` would return the current pause status. You cannot +reference properties with ``-`` this way since that would denote a subtraction, +but if the variable name contains any ``_`` characters, they are turned into +``-``. For example, ``playback_time`` would return the property +``playback-time``. + +A more robust way to access properties is using ``p.property_name`` or +``get("property-name", default_value)``. The automatic variable to property +magic will break if a new identifier with the same name is introduced (for +example, if a function named ``pause()`` were added, ``pause`` would return a +function value instead of the value of the ``pause`` property). + +Note that if a property is not available, it will return ``nil``, which can +cause errors if used in expressions. These are logged in verbose mode, and the +expression is considered to be false. + +Whenever a property referenced by a profile condition changes, the condition +is re-evaluated. If the return value of the condition changes from falsy or +error to truthy, the profile is applied. + +This mechanism tries to "unapply" profiles once the condition changes from +truthy to falsy or error. If you want to use this, you need to set +``profile-restore`` for the profile. Another possibility it to create another +profile with an inverse condition to undo the other profile. + +Recursive profiles can be used. But it is discouraged to reference other +conditional profiles in a conditional profile, since this can lead to tricky +and unintuitive behavior. + +.. admonition:: Example + + Make only HD video look funny: -Some profiles are loaded automatically. The following example demonstrates this: + :: + + [something] + profile-desc=HD video sucks + profile-cond=width >= 1280 + hue=-50 + + Make only videos containing "youtube" or "youtu.be" in their path brighter: + + :: + + [youtube] + profile-cond=path:find('youtu%.?be') + gamma=20 + + If you want the profile to be reverted if the condition goes to false again, + you can set ``profile-restore``: + + :: + + [something] + profile-desc=Mess up video when entering fullscreen + profile-cond=fullscreen + profile-restore=copy + vf-add=rotate=PI/2 # rotate by 90 degrees + + This appends the ``rotate`` filter to the video filter chain when entering + fullscreen. When leaving fullscreen, the ``vf`` option is set to the value + it had before entering fullscreen. Note that this would also remove any + other filters that were added during fullscreen mode by the user. Avoiding + this is trickier, and could for example be solved by adding a second profile + with an inverse condition and operation: + + :: + + [something] + profile-cond=fullscreen + vf-add=@rot:rotate=PI/2 + + [something-inv] + profile-cond=not fullscreen + vf-remove=@rot + +.. warning:: + + Every time an involved property changes, the condition is evaluated again. + If your condition uses ``p.playback_time`` for example, the condition is + re-evaluated approximately on every video frame. This is probably slow. + +This feature is managed by an internal Lua script. Conditions are executed as +Lua code within this script. Its environment contains at least the following +things: + +``(function environment table)`` + Every Lua function has an environment table. This is used for identifier + access. There is no named Lua symbol for it; it is implicit. + + The environment does "magic" accesses to mpv properties. If an identifier + is not already defined in ``_G``, it retrieves the mpv property of the same + name. Any occurrences of ``_`` in the name are replaced with ``-`` before + reading the property. The returned value is as retrieved by + ``mp.get_property_native(name)``. Internally, a cache of property values, + updated by observing the property is used instead, so properties that are + not observable will be stuck at the initial value forever. + + If you want to access properties, that actually contain ``_`` in the name, + use ``get()`` (which does not perform transliteration). + + Internally, the environment table has a ``__index`` meta method set, which + performs the access logic. + +``p`` + A "magic" table similar to the environment table. Unlike the latter, this + does not prefer accessing variables defined in ``_G`` - it always accesses + properties. + +``get(name [, def])`` + Read a property and return its value. If the property value is ``nil`` (e.g. + if the property does not exist), ``def`` is returned. + + This is superficially similar to ``mp.get_property_native(name)``. An + important difference is that this accesses the property cache, and enables + the change detection logic (which is essential to the dynamic runtime + behavior of auto profiles). Also, it does not return an error value as + second return value. + + The "magic" tables mentioned above use this function as backend. It does not + perform the ``_`` transliteration. + +In addition, the same environment as in a blank mpv Lua script is present. For +example, ``math`` is defined and gives access to the Lua standard math library. + +.. warning:: + + This feature is subject to change indefinitely. You might be forced to + adjust your profiles on mpv updates. + +Legacy auto profiles +-------------------- + +Some profiles are loaded automatically using a legacy mechanism. The following +example demonstrates this: .. admonition:: Auto profile loading @@ -705,14 +1010,15 @@ Some profiles are loaded automatically. The following example demonstrates this: [extension.mkv] profile-desc="profile for .mkv files" - vf=flip + vf=vflip The profile name follows the schema ``type.name``, where type can be ``protocol`` for the input/output protocol in use (see ``--list-protocols``), and ``extension`` for the extension of the path of the currently played file (*not* the file format). -This feature is very limited, and there are no other auto profiles. +This feature is very limited, and is considered soft-deprecated. Use conditional +auto profiles. Using mpv from other programs or scripts ======================================== @@ -724,7 +1030,7 @@ There are three choices for using mpv from other programs or scripts: addition, terminal behavior itself may change any time. Compatibility cannot be guaranteed. - Your code should work even if you pass ``--no-terminal``. Do not attempt + Your code should work even if you pass ``--terminal=no``. Do not attempt to simulate user input by sending terminal control codes to mpv's stdin. If you need interactive control, using ``--input-ipc-server`` is recommended. This gives you access to the `JSON IPC`_ over unix domain @@ -792,7 +1098,7 @@ listed. - ``AV:`` or ``V:`` (video only) or ``A:`` (audio only) - The current time position in ``HH:MM:SS`` format (``playback-time`` property) - The total file duration (absent if unknown) (``duration`` property) -- Playback speed, e.g. `` x2.0``. Only visible if the speed is not normal. This +- Playback speed, e.g. ``x2.0``. 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). (``speed`` property.) - Playback percentage, e.g. ``(13%)``. How much of the file has been played. @@ -848,7 +1154,8 @@ this with ``--untimed``, but it will likely break, unless the stream has no audio, and the input feeds data to the player at a constant rate. Another common problem is with MJPEG streams. These do not signal the correct -framerate. Using ``--untimed`` or ``--no-correct-pts --fps=60`` might help. +framerate. Using ``--untimed`` or ``--correct-pts=no --container-fps-override=60`` +might help. For livestreams, data can build up due to pausing the stream, due to slightly lower playback rate, or "buffering" pauses. If the demuxer cache is enabled, @@ -866,6 +1173,33 @@ Additional options that can be tried: - without audio ``--framedrop=no --speed=1.01`` may help for live sources (results can be mixed) +RESUMING PLAYBACK +================= + +mpv is capable of storing the playback position of the currently playing file +and resume from there the next time that file is played. This is done with the +commands ``quit-watch-later`` (bound to Shift+Q by default) and +``write-watch-later-config``, and with the ``--save-position-on-quit`` option. + +The difference between always quitting with a key bound to ``quit-watch-later`` +and using ``--save-position-on-quit`` is that the latter will save the playback +position even when mpv is closed with a method other than a keybinding, such as +clicking the close button in the window title bar. However if mpv is terminated +abruptly and doesn't have the time to save, then the position will not be saved. +For example, if you shutdown your system without closing mpv beforehand. + +mpv also stores options other than the playback position when they have been +modified after playback began, for example the volume and selected audio/subtitles, +and restores their values the next time the file is played. Which options are +saved can be configured with the ``--watch-later-options`` option. + +When playing multiple playlist entries, mpv checks if one them has a resume +config file associated, and if it finds one it restarts playback from it. For +example, if you use ``quit-watch-later`` on the 5th episode of a show, and +later play all the episodes, mpv will automatically resume playback from +episode 5. + +More options to configure this functionality are listed in `Watch Later`_. PROTOCOLS ========= @@ -880,8 +1214,8 @@ PROTOCOLS either aliases to documented protocols, or are just redirections to protocols implemented and documented in FFmpeg. - ``data:`` is supported in FFmpeg (not in Libav), but needs to be in the - format ``data://``. This is done to avoid ambiguity with filenames. You + ``data:`` is supported, but needs to be in the format ``data://``. + This is done to avoid ambiguity with filenames. You can also prefix it with ``lavf://`` or ``ffmpeg://``. ``ytdl://...`` @@ -927,17 +1261,28 @@ PROTOCOLS Digital TV via DVB. (Linux only.) -``mf://[filemask|@listfile]`` ``--mf-...`` +``mf://[@listfile|filemask|glob|printf-format]`` ``--mf-...`` Play a series of images as video. + If the URL path begins with ``@``, it is interpreted as the path to a file + containing a list of image paths separated by newlines. If the URL path + contains ``,``, it is interpreted as a list of image paths separated by + ``,``. If the URL path does not contain ``%`` and if on POSIX platforms, is + interpreted as a glob, and ``*`` is automatically appended if it was not + specified. Otherwise, the printf sequences ``%[.][NUM]d``, where ``NUM`` is + one, two, or three decimal digits, and ``%%`` and are interpreted. For + example, ``mf://image-%d.jpg`` plays files like ``image-1.jpg``, + ``image-2.jpg`` and ``image-10.jpg``, provided that there are no big gaps + between the files. + ``cdda://[device]`` ``--cdrom-device=PATH`` ``--cdda-...`` Play CD. ``lavf://...`` - Access any FFmpeg/Libav libavformat protocol. Basically, this passed the + Access any FFmpeg libavformat protocol. Basically, this passed the string after the ``//`` directly to libavformat. ``av://type:options`` @@ -995,6 +1340,34 @@ PROTOCOLS Stitch together parts of multiple files and play them. +``slice://start[-end]@URL`` + + Read a slice of a stream. + + ``start`` and ``end`` represent a byte range and accept + suffixes such as ``KiB`` and ``MiB``. ``end`` is optional. + + if ``end`` starts with ``+``, it is considered as offset from ``start``. + + Only works with seekable streams. + + Examples:: + + mpv slice://1g-2g@cap.ts + + This starts reading from cap.ts after seeking 1 GiB, then + reads until reaching 2 GiB or end of file. + + mpv slice://1g-+2g@cap.ts + + This starts reading from cap.ts after seeking 1 GiB, then + reads until reaching 3 GiB or end of file. + + mpv slice://100m@appending://cap.ts + + This starts reading from cap.ts after seeking 100MiB, then + reads until end of file. + ``null://`` Simulate an empty file. If opened for writing, it will discard all data. @@ -1023,7 +1396,7 @@ Currently this happens only in the following cases: or file associations provided by desktop environments) - if started from explorer.exe on Windows (technically, if it was started on Windows, and all of the stdout/stderr/stdin handles are unset) -- started out of the bundle on OSX +- started out of the bundle on macOS - if you manually use ``--player-operation-mode=pseudo-gui`` on the command line This mode applies options from the builtin profile ``builtin-pseudo-gui``, but @@ -1096,9 +1469,10 @@ behavior of mpv. ``HOME``, ``XDG_CONFIG_HOME`` Used to determine mpv config directory. If ``XDG_CONFIG_HOME`` is not set, - ``$HOME/.config/mpv`` is used. But note that if the directory as according - to XDG does not exist, ``$HOME/.config/mpv`` is created and used. See - `FILES`_. + ``$HOME/.config/mpv`` is used. + + ``$HOME/.mpv`` is always added to the list of config search paths with a + lower priority. ``MPV_HOME`` Directory where mpv looks for user settings. Overrides ``HOME``, and mpv @@ -1123,7 +1497,7 @@ behavior of mpv. ``DISPLAY`` Standard X11 display name to use. -FFmpeg/Libav: +FFmpeg: This library accesses various environment variables. However, they are not centrally documented, and documenting them is not our job. Therefore, this list is incomplete. @@ -1217,6 +1591,7 @@ input command can take an exit code: in this case, that exit code is returned. FILES ===== +Note that this section assumes Linux/BSD. On other platforms the paths may be different. For Windows-specifics, see `FILES ON WINDOWS`_ section. ``/usr/local/etc/mpv/mpv.conf`` @@ -1224,55 +1599,63 @@ For Windows-specifics, see `FILES ON WINDOWS`_ section. in default configuration will use ``/usr/local/etc/mpv/`` as config directory, while most Linux distributions will set it to ``/etc/mpv/``). - Ignored if ``$MPV_HOME`` is set. - -``~/.mpv/`` - Standard configuration files directory. The path is derived from the - ``$HOME`` environment variable (if unset, something stupid happens). +``~/.cache/mpv`` + The standard cache directory. Certain options within mpv may cause it to write + cache files to disk. This can be overridden by environment variables, in + ascending order: - If the ``$MPV_HOME`` environment variable is set, it is used as sole config - dir, and the other paths are not used. + :1: If ``$XDG_CACHE_HOME`` is set, then the derived cache directory + will be ``$XDG_CACHE_HOME/mpv``. + :2: If ``$MPV_HOME`` is set, then the derived cache directory will be + ``$MPV_HOME``. - If the directory does not exist (and no alternative config dirs exist), mpv - tries to create it and use it. + If the directory does not exist, mpv will try to create it automatically. -``~/.config/mpv/`` |