diff options
Diffstat (limited to '')
| -rw-r--r-- | DOCS/client-api-changes.rst | 9 | ||||
| -rw-r--r-- | DOCS/contribute.md | 26 | ||||
| -rw-r--r-- | DOCS/interface-changes.rst | 58 | ||||
| -rw-r--r-- | DOCS/interface-changes/example.txt | 1 | ||||
| -rw-r--r-- | DOCS/man/ao.rst | 78 | ||||
| -rw-r--r-- | DOCS/man/changes.rst | 3 | ||||
| -rw-r--r-- | DOCS/man/console.rst | 14 | ||||
| -rw-r--r-- | DOCS/man/encode.rst | 5 | ||||
| -rw-r--r-- | DOCS/man/input.rst | 241 | ||||
| -rw-r--r-- | DOCS/man/javascript.rst | 23 | ||||
| -rw-r--r-- | DOCS/man/lua.rst | 105 | ||||
| -rw-r--r-- | DOCS/man/mpv.rst | 115 | ||||
| -rw-r--r-- | DOCS/man/options.rst | 671 | ||||
| -rw-r--r-- | DOCS/man/osc.rst | 16 | ||||
| -rw-r--r-- | DOCS/man/stats.rst | 12 | ||||
| -rw-r--r-- | DOCS/man/vf.rst | 15 | ||||
| -rw-r--r-- | DOCS/man/vo.rst | 77 | ||||
| -rw-r--r-- | DOCS/mplayer-changes.rst | 6 | ||||
| -rw-r--r-- | DOCS/release-policy.md | 9 | ||||
| -rw-r--r-- | DOCS/tech-overview.txt | 71 |
20 files changed, 1015 insertions, 540 deletions
diff --git a/DOCS/client-api-changes.rst b/DOCS/client-api-changes.rst index f092647..7d34881 100644 --- a/DOCS/client-api-changes.rst +++ b/DOCS/client-api-changes.rst @@ -31,7 +31,12 @@ API changes =========== :: - + --- mpv 0.38.0 --- + 2.3 - partially revert the changes from API version 1.27, remove libmpv as + the default VO and move it to the bottom of the auto-probing order. + This restores the prior behavior on all platforms other than macOS, + but still auto selects libmpv/cocoa-cb on macOS if it was built with + support for cocoa-cb. --- mpv 0.37.0 --- 2.2 - add mpv_time_ns() --- mpv 0.36.0 --- @@ -273,7 +278,7 @@ API changes - extend the "--start" option; a leading "+", which was previously insignificant is now significant - add "cache-free" and "cache-used" properties - - OSX: the "coreaudio" AO spdif code is split into a separate AO + - macOS: the "coreaudio" AO spdif code is split into a separate AO --- mpv 0.4.0 --- 1.0 - the API is declared stable diff --git a/DOCS/contribute.md b/DOCS/contribute.md index 91422a7..4d2af4e 100644 --- a/DOCS/contribute.md +++ b/DOCS/contribute.md @@ -5,13 +5,13 @@ General ------- The main contact for mpv development is IRC, specifically #mpv -and #mpv-devel on Libera.chat. Github is used for code review and +and #mpv-devel on Libera.chat. GitHub is used for code review and long term discussions. Sending patches --------------- -- Make a github pull request, or send a link to a plaintext patch created with +- Make a GitHub pull request, or send a link to a plaintext patch created with ``git format-patch``. - Plain diffs posted as pastebins are not acceptable! (Especially if the http link returns HTML.) They only cause extra work for everyone, because they lack @@ -111,13 +111,13 @@ Always squash fixup commits when making changes to pull requests - If you make fixup commits to your pull request, you should generally squash them with "git rebase -i". We prefer to have pull requests in a merge ready state. -- We don't squash-merge (nor do we use github's feature that does this) because +- We don't squash-merge (nor do we use GitHub's feature that does this) because pull requests with multiple commits are perfectly legitimate, and the only thing that makes sense in non-trivial cases. - With complex pull requests, it *may* make sense to keep them separate, but they should be clearly marked as such. Reviewing commits is generally easier with fixups squashed. -- Reviewers are encouraged to look at individual commits instead of github's +- Reviewers are encouraged to look at individual commits instead of GitHub's "changes from all commits" view (which just encourages bad git and review practices). @@ -131,12 +131,24 @@ Touching user-visible parts may require updating the mpv docs - Changes to command line options (addition/modification/removal) must be documented in options.rst. - Changes to input properties or input commands must be documented in input.rst. -- All incompatible changes to the user interface (options, properties, commands) - must be documented with a small note in interface-changes.rst. (Additions may - be documented there as well, but this isn't required.) - Changes to the libmpv API must be reflected in the libmpv's headers doxygen, and in client-api-changes.rst. +Interface change policy +----------------------- + +- All incompatible changes to the user interface (options, properties, commands) + must be documented by making a new text file with a txt extension containing a + small note in the DOCS/interface-changes directory. +- The name of the file should be brief and related to the commit that makes the + change. +- Grouping multiple related changes in the same file is also OK. Just be sure to + put each separate change on a different line. +- Documenting additions in DOCS/interface-changes is optional but encouraged. +- interface-changes.rst is never directly updated except when making new major + releases. +- See DOCS/interface-changes/example.txt for an example. + Code formatting --------------- diff --git a/DOCS/interface-changes.rst b/DOCS/interface-changes.rst index f59f890..b55ef97 100644 --- a/DOCS/interface-changes.rst +++ b/DOCS/interface-changes.rst @@ -17,15 +17,65 @@ a large part of the user interface and APIs. Also see compatibility.rst. -This document lists changes to them. New changes are added to the top. Usually, -only incompatible or important changes are mentioned. New options/commands/etc. -are not always listed. +This document lists changes to them. New options/commands/etc. are not always +listed. + +**Never** write to this file directly except when making releases. New changes +are added in the interface-changes directory instead. See contribute.md for more +details. Interface changes ================= :: + --- mpv 0.38.0 --- + - add `term-size` property + - add the `escape-ass` command + - add `>` for fixed precision floating-point property expansion + - add `--input-comands` option + - change `--pulse-latency-hacks` default to `yes` + - add `context-menu` command + - add `menu-data` property + - add `--vo-tct-buffering` option + - add `begin-vo-dragging` command + - add `--deinterlace-field-parity` option + - add `--volume-gain`, `--volume-gain-min`, and `--volume-gain-max` options + - add `current-gpu-context` property + - add `--secondary-sub-ass-override` option + - add `--input-preprocess-wheel` option + - remove shared-script-properties (user-data is a replacement) + - add `--secondary-sub-delay`, decouple secondary subtitles from + `--sub-delay` + - add the `--osd-bar-border-size` option + - `--screenshot-avif-pixfmt` no longer defaults to yuv420p + - `--screenshot-avif-opts` defaults to lossless screenshot + - rename key `MP_KEY_BACK` to `MP_KEY_GO_BACK` + - add `--sub-filter-sdh-enclosures` option + - added the `mp.input` scripting API to query the user for textual input + - add `forced` choice to `subs-with-matching-audio` + - remove `--term-remaining-playtime` option + - change fallback deinterlace to bwdif + - add the command `load-config-file` + - add the command `load-input-conf` + - remove `--vo=rpi`, `--gpu-context=rpi`, and `--hwdec=mmal` + - add `auto` choice to `--deinterlace` + - change `--teletext-page` default from 100 to 0 ("subtitle" in lavc) + - change `--hidpi-window-scale` default to `no` + - add `insert-next`, `insert-next-play`, `insert-at`, and `insert-at-play` + actions to `loadfile` and `loadlist` commands + - add `index` argument to `loadfile` and `loadlist` commands + - move the `options` argument of the `loadfile` command from the third + parameter to the fourth (after `index`) + - add `--drag-and-drop=insert-next` option + - rename `--background` to `--background-color` + - remove `--alpha` and reintroduce `--background` option for better control + over blending alpha components into specific background types + - add `--border-background` option + - add `video-target-params` property + - add `hdr10plus` sub-parameter to `format` video filter + - remove `--focus-on-open` and add replacement `--focus-on` + - remove debanding from the high-quality profile --- mpv 0.37.0 --- - `--save-position-on-quit` and its associated commands now store state files in %LOCALAPPDATA% instead of %APPDATA% directory by default on Windows. @@ -239,7 +289,7 @@ Interface changes - names starting with "." in ~/.mpv/scripts/ (or equivalent) are now ignored - js modules: ~~/scripts/modules.js/ is no longer used, global paths can be set with custom init (see docs), dir-scripts first look at <dir>/modules/ - - the OSX bundle now logs to "~/Library/Logs/mpv.log" by default + - the macOS bundle now logs to "~/Library/Logs/mpv.log" by default - deprecate the --cache-secs option (once removed, the cache cannot be limited by time anymore) - remove deprecated legacy hook API ("hook-add", "hook-ack"). Use either the diff --git a/DOCS/interface-changes/example.txt b/DOCS/interface-changes/example.txt new file mode 100644 index 0000000..c52ee01 --- /dev/null +++ b/DOCS/interface-changes/example.txt @@ -0,0 +1 @@ +deprecate `--foo`, instead use `--bar=foo` as a replacement diff --git a/DOCS/man/ao.rst b/DOCS/man/ao.rst index 4e4e454..4ac1cc5 100644 --- a/DOCS/man/ao.rst +++ b/DOCS/man/ao.rst @@ -12,16 +12,59 @@ in the list. .. note:: - See ``--ao=help`` for a list of compiled-in audio output drivers. The - driver ``--ao=alsa`` is preferred. ``--ao=pulse`` is preferred on systems - where PulseAudio is used. On BSD systems, ``--ao=oss`` is preferred. + See ``--ao=help`` for a list of compiled-in audio output drivers sorted by + autoprobe order. Available audio output drivers are: -``alsa`` (Linux only) - ALSA audio output driver +``alsa`` + ALSA audio output driver. - See `ALSA audio output options`_ for options specific to this AO. + The following global options are supported by this audio output: + + ``--alsa-resample=yes`` + Enable ALSA resampling plugin. (This is disabled by default, because + some drivers report incorrect audio delay in some cases.) + + ``--alsa-mixer-device=<device>`` + Set the mixer device used with ``ao-volume`` (default: ``default``). + + ``--alsa-mixer-name=<name>`` + Set the name of the mixer element (default: ``Master``). This is for + example ``PCM`` or ``Master``. + + ``--alsa-mixer-index=<number>`` + Set the index of the mixer channel (default: 0). Consider the output of + "``amixer scontrols``", then the index is the number that follows the + name of the element. + + ``--alsa-non-interleaved`` + Allow output of non-interleaved formats (if the audio decoder uses + this format). Currently disabled by default, because some popular + ALSA plugins are utterly broken with non-interleaved formats. + + ``--alsa-ignore-chmap`` + Don't read or set the channel map of the ALSA device - only request the + required number of channels, and then pass the audio as-is to it. This + option most likely should not be used. It can be useful for debugging, + or for static setups with a specially engineered ALSA configuration (in + this case you should always force the same layout with ``--audio-channels``, + or it will work only for files which use the layout implicit to your + ALSA device). + + ``--alsa-buffer-time=<microseconds>`` + Set the requested buffer time in microseconds. A value of 0 skips requesting + anything from the ALSA API. This and the ``--alsa-periods`` option uses the + ALSA ``near`` functions to set the requested parameters. If doing so results + in an empty configuration set, setting these parameters is skipped. + + Both options control the buffer size. A low buffer size can lead to higher + CPU usage and audio dropouts, while a high buffer size can lead to higher + latency in volume changes and other filtering. + + ``--alsa-periods=<number>`` + Number of periods requested from the ALSA API. See ``--alsa-buffer-time`` + for further remarks. .. warning:: @@ -95,11 +138,21 @@ Available audio output drivers are: passthrough (even if the device reports it as supported). Use with extreme care. - ``coreaudio_exclusive`` (macOS only) Native macOS audio output driver using direct device access and exclusive mode (bypasses the sound server). +``avfoundation`` (macOS only) + Native macOS audio output driver using ``AVSampleBufferAudioRenderer`` + in AVFoundation, which supports `spatial audio + <https://support.apple.com/en-us/HT211775>`_. + + .. warning:: + + Turning on spatial audio may hang the playback + if mpv is not started out of the bundle, + though playback with spatial audio off always works. + ``openal`` OpenAL audio output driver. @@ -131,15 +184,12 @@ Available audio output drivers are: changes. "native" lets the sound server determine buffers. ``--pulse-latency-hacks=<yes|no>`` - Enable hacks to workaround PulseAudio timing bugs (default: no). If + Enable hacks to workaround PulseAudio timing bugs (default: yes). If enabled, mpv will do elaborate latency calculations on its own. If disabled, it will use PulseAudio automatically updated timing information. Disabling this might help with e.g. networked audio or some plugins, while enabling it might help in some unknown situations - (it used to be required to get good behavior on old PulseAudio versions). - - If you have stuttering video when using pulse, try to enable this - option. (Or try to update PulseAudio.) + (it is currently enabled due to known bugs with PulseAudio 16.0). ``--pulse-allow-suspended=<yes|no>`` Allow mpv to use PulseAudio even if the sink is suspended (default: no). @@ -167,8 +217,8 @@ Available audio output drivers are: By default the channel volumes are used. ``sdl`` - SDL 1.2+ audio output driver. Should work on any platform supported by SDL - 1.2, but may require the ``SDL_AUDIODRIVER`` environment variable to be set + SDL 2.0+ audio output driver. Should work on any platform supported by SDL + 2.0, but may require the ``SDL_AUDIODRIVER`` environment variable to be set appropriately for your system. .. note:: This driver is for compatibility with extremely foreign diff --git a/DOCS/man/changes.rst b/DOCS/man/changes.rst index 63de41c..3f5e0e1 100644 --- a/DOCS/man/changes.rst +++ b/DOCS/man/changes.rst @@ -10,8 +10,7 @@ There is no real changelog, but you can look at the following things: * The git log, which is the "real" changelog * The file https://github.com/mpv-player/mpv/blob/master/DOCS/interface-changes.rst documents changes to the command and user interface, such as options and - properties. (It usually documents breaking changes only, additions and - enhancements are often not listed.) + properties. * C API changes are listed in https://github.com/mpv-player/mpv/blob/master/DOCS/client-api-changes.rst * The file ``mplayer-changes.rst`` in the ``DOCS`` sub directory on the git diff --git a/DOCS/man/console.rst b/DOCS/man/console.rst index 49502b3..b9f169f 100644 --- a/DOCS/man/console.rst +++ b/DOCS/man/console.rst @@ -86,7 +86,11 @@ Shift+INSERT Paste text (uses the primary selection on X11 and Wayland). TAB and Ctrl+i - Complete the command or property name at the cursor. + Complete the text at the cursor. The first press inserts the longest common + prefix of the completions, and subsequent presses cycle through them. + +Shift+TAB + Cycle through the completions backwards. Ctrl+l Clear all log messages from the console. @@ -154,6 +158,11 @@ Configurable Options Set the font border size used for the REPL and the console. +``case_sensitive`` + Default: no on Windows, yes on other platforms. + + Whether Tab completion is case sensitive. Only works with ASCII characters. + ``history_dedup`` Default: true @@ -161,7 +170,8 @@ Configurable Options multiplied by "scale." ``font_hw_ratio`` - Default: 2.0 + Default: auto The ratio of font height to font width. Adjusts table width of completion suggestions. + Values in the range 1.8..2.5 make sense for common monospace fonts. diff --git a/DOCS/man/encode.rst b/DOCS/man/encode.rst index 399eba2..26f3d6c 100644 --- a/DOCS/man/encode.rst +++ b/DOCS/man/encode.rst @@ -77,9 +77,8 @@ You can encode files from one format/codec to another using this facility. and all pts are passed through as-is. Never seek backwards or use multiple input files in this mode! -``--no-ocopy-metadata`` - Turns off copying of metadata from input files to output files when - encoding (which is enabled by default). +``--ocopy-metadata=<yes|no>`` + Copy metadata from input files to output files when encoding (default: yes). ``--oset-metadata=<metadata-tag[,metadata-tag,...]>`` Specifies metadata to include in the output file. diff --git a/DOCS/man/input.rst b/DOCS/man/input.rst index 8dbf58b..6d6b64c 100644 --- a/DOCS/man/input.rst +++ b/DOCS/man/input.rst @@ -49,8 +49,8 @@ input.conf syntax ``[Shift+][Ctrl+][Alt+][Meta+]<key> [{<section>}] <command> ( ; <command> )*`` Note that by default, the right Alt key can be used to create special -characters, and thus does not register as a modifier. The option -``--no-input-right-alt-gr`` changes this behavior. +characters, and thus does not register as a modifier. This can be changed +with ``--input-right-alt-gr`` option. Newlines always start a new binding. ``#`` starts a comment (outside of quoted string arguments). To bind commands to the ``#`` key, ``SHARP`` can be used. @@ -264,7 +264,7 @@ Remember to quote string arguments in input.conf (see `Flat command syntax`_). ``ignore`` Use this to "block" keys that should be unbound, and do nothing. Useful for disabling default bindings, without disabling all bindings with - ``--no-input-default-bindings``. + ``--input-default-bindings=no``. ``seek <target> [<flags>]`` Change the playback position. By default, seeks by a relative amount of @@ -452,9 +452,9 @@ Remember to quote string arguments in input.conf (see `Flat command syntax`_). restarted if for example the new playlist entry is the same as the previous one. -``loadfile <url> [<flags> [<options>]]`` +``loadfile <url> [<flags> [<index> [<options>]]]`` Load the given file or URL and play it. Technically, this is just a playlist - manipulation command (which either replaces the playlist or appends an entry + manipulation command (which either replaces the playlist or adds an entry to it). Actual file loading happens independently. For example, a ``loadfile`` command that replaces the current file with a new one returns before the current file is stopped, and the new file even begins loading. @@ -469,15 +469,34 @@ Remember to quote string arguments in input.conf (see `Flat command syntax`_). Append the file, and if nothing is currently playing, start playback. (Always starts with the added file, even if the playlist was not empty before running this command.) - - The third argument is a list of options and values which should be set + <insert-next> + Insert the file into the playlist, directly after the current entry. + <insert-next-play> + Insert the file next, and if nothing is currently playing, start playback. + (Always starts with the added file, even if the playlist was not empty + before running this command.) + <insert-at> + Insert the file into the playlist, at the index given in the third + argument. + <insert-at-play> + Insert the file at the index given in the third argument, and if nothing + is currently playing, start playback. (Always starts with the added + file, even if the playlist was not empty before running this command.) + + The third argument is an insertion index, used only by the ``insert-at`` and + ``insert-at-play`` actions. When used with those actions, the new item will + be inserted at the index position in the playlist, or appended to the end if + index is less than 0 or greater than the size of the playlist. This argument + will be ignored for all other actions. + + The fourth argument is a list of options and values which should be set while the file is playing. It is of the form ``opt1=value1,opt2=value2,..``. When using the client API, this can be a ``MPV_FORMAT_NODE_MAP`` (or a Lua table), however the values themselves must be strings currently. These options are set during playback, and restored to the previous value at end of playback (see `Per-File Options`_). -``loadlist <url> [<flags>]`` +``loadlist <url> [<flags> [<index>]]`` Load the given playlist file or URL (like ``--playlist``). Second argument: @@ -490,6 +509,26 @@ Remember to quote string arguments in input.conf (see `Flat command syntax`_). Append the new playlist, and if nothing is currently playing, start playback. (Always starts with the new playlist, even if the internal playlist was not empty before running this command.) + <insert-next> + Insert the new playlist into the current internal playlist, directly + after the current entry. + <insert-next-play> + Insert the new playlist, and if nothing is currently playing, start + playback. (Always starts with the new playlist, even if the internal + playlist was not empty before running this command.) + <insert-at> + Insert the new playlist at the index given in the third argument. + <insert-at-play> + Insert the new playlist at the index given in the third argument, and if + nothing is currently playing, start playback. (Always starts with the + new playlist, even if the internal playlist was not empty before running + this command.) + + The third argument is an insertion index, used only by the ``insert-at`` and + ``insert-at-play`` actions. When used with those actions, the new playlist + will be inserted at the index position in the internal playlist, or appended + to the end if index is less than 0 or greater than the size of the internal + playlist. This argument will be ignored for all other actions. ``playlist-clear`` Clear the playlist, except the currently played file. @@ -655,7 +694,7 @@ Remember to quote string arguments in input.conf (see `Flat command syntax`_). wasn't started in detached mode, even if ``playback_only`` is false. - .. admonition:: Warning + .. warning:: Don't forget to set the ``playback_only`` field to false if you want the command to run while the player is in idle mode, or if you don't @@ -827,11 +866,13 @@ Remember to quote string arguments in input.conf (see `Flat command syntax`_). <double> The mouse event represents double-click. -``keypress <name>`` +``keypress <name> [<scale>]`` Send a key event through mpv's input handler, triggering whatever behavior is configured to that key. ``name`` uses the ``input.conf`` - naming scheme for keys and modifiers. Useful for the client API: key events - can be sent to libmpv to handle internally. + naming scheme for keys and modifiers. ``scale`` is used to scale numerical + change effected by the bound command (same mechanism as precise scrolling). + Useful for the client API: key events can be sent to libmpv to handle + internally. ``keydown <name>`` Similar to ``keypress``, but sets the ``KEYDOWN`` flag so that if the key is @@ -886,6 +927,9 @@ Remember to quote string arguments in input.conf (see `Flat command syntax`_). <keep-selection> Do not change current track selections. +``context-menu`` + Show context menu on the video window. See `Context Menu`_ section for details. + Input Commands that are Possibly Subject to Change -------------------------------------------------- @@ -1033,7 +1077,7 @@ Input Commands that are Possibly Subject to Change information about the key state. The special key name ``unmapped`` can be used to match any unmapped key. -``overlay-add <id> <x> <y> <file> <offset> <fmt> <w> <h> <stride>`` +``overlay-add <id> <x> <y> <file> <offset> <fmt> <w> <h> <stride> <dw> <dh>`` Add an OSD overlay sourced from raw data. This might be useful for scripts and applications controlling mpv, and which want to display things on top of the video window. @@ -1091,6 +1135,11 @@ Input Commands that are Possibly Subject to Change (Technically, the minimum size would be ``stride * (h - 1) + w * 4``, but for simplicity, the player will access all ``stride * h`` bytes.) + ``dw`` and ``dh`` specify the (optional) display size of the overlay. + The overlay visible portion of the overlay (``w`` and ``h``) is scaled to + in display to ``dw`` and ``dh``. If parameters are not present, the + values for ``w`` and ``h`` are used. + .. note:: Before mpv 0.18.1, you had to do manual "double buffering" when updating @@ -1213,6 +1262,18 @@ Input Commands that are Possibly Subject to Change use the ``mp.create_osd_overlay()`` helper instead of invoking this command directly. +``escape-ass <text>`` + Modify ``text`` so that commands and functions that interpret ASS tags, + such as ``osd-overlay`` and ``mp.create_osd_overlay``, will display it + verbatim, and return it. This can only be used through the client API or + from a script using ``mp.command_native``. + + .. admonition:: Example + + ``mp.osd_message(mp.command_native({"escape-ass", "foo {bar}"}))`` + + This line of Lua prints "foo \\{bar}" on the OSD. + ``script-message [<arg1> [<arg2> [...]]]`` Send a message to all clients, and pass it the following list of arguments. What this message means, how many arguments it takes, and what the arguments @@ -1329,6 +1390,16 @@ Input Commands that are Possibly Subject to Change relevant mode. Prints a warning if nothing could be done. See `Runtime profiles`_ for details. +``load-config-file <filename>`` + Load a configuration file, similar to the ``--include`` option. If the file + was already included, its previous options are not reset before it is + reparsed. + +``load-input-conf <filename>`` + Load an input configuration file, similar to the ``--input-conf`` option. If + the file was already included, its previous bindings are not reset before it + is reparsed. + ``load-script <filename>`` Load a script, similar to the ``--script`` option. Whether this waits for the script to finish initialization or not changed multiple times, and the @@ -1422,6 +1493,13 @@ Input Commands that are Possibly Subject to Change This command has an even more uncertain future than ``ab-loop-dump-cache`` and might disappear without replacement if the author decides it's useless. +``begin-vo-dragging`` + Begin window dragging if supported by the current VO. This command should + only be called while a mouse button is being pressed, otherwise it will + be ignored. The exact effect of this command depends on the VO implementation + of window dragging. For example, on Windows only the left mouse button can + begin window dragging, while X11 and Wayland allow other mouse buttons. + Undocumented commands: ``ao-reload`` (experimental/internal). List of events @@ -2157,6 +2235,11 @@ Property list ``af-metadata/<filter-label>`` Equivalent to ``vf-metadata/<filter-label>``, but for audio filters. +``deinterlace-active`` + Returns ``yes``/true if mpv's deinterlacing filter is active. Note that it + will not detect any manually inserted deinterlacing filters done via + ``--vf``. + ``idle-active`` Returns ``yes``/true if no file is loaded, but the player is staying around because of the ``--idle`` option. @@ -2318,12 +2401,6 @@ Property list Similar to ``ao-volume``, but controls the mute state. May be unimplemented even if ``ao-volume`` works. -``audio-codec`` - Audio codec selected for decoding. - -``audio-codec-name`` - Audio codec. - ``audio-params`` Audio format as output by the audio decoder. This has a number of sub-properties: @@ -2407,12 +2484,6 @@ Property list multiple interop drivers for the same hardware decoder, depending on platform and VO. -``video-format`` - Video format as string. - -``video-codec`` - Video codec selected for decoding. - ``width``, ``height`` Video size. This uses the size of the video as decoded, or if no video frame has been decoded yet, the (possibly incorrect) container indicated @@ -2579,6 +2650,11 @@ Property list Has the same sub-properties as ``video-params``. +``video-target-params`` + Same as ``video-params``, but with the target properties that VO outputs to. + + Has the same sub-properties as ``video-params``. + ``video-frame-info`` Approximate information of the current frame. Note that if any of these are used on OSD, the information might be off by a few frames due to OSD @@ -2661,7 +2737,10 @@ Property list in the list will be the one that Windows considers associated with the window (as determined by the MonitorFromWindow API.) On macOS these are the Display Product Names as used in the System Information and only one display - name is returned since a window can only be on one screen. + name is returned since a window can only be on one screen. On Wayland, these + are the wl_output names if protocol version >= 4 is used + (LVDS-1, HDMI-A-1, X11-1, etc.), or the wl_output model reported by the + geometry event if protocol version < 4 is used. ``display-fps`` The refresh rate of the current display. Currently, this is the lowest FPS @@ -2728,6 +2807,19 @@ Property list Any of these properties may be unavailable or set to dummy values if the VO window is not created or visible. +``term-size`` + The current terminal size. + + This has two sub-properties. + + ``term-size/w`` + width of the terminal in cells + ``term-size/h`` + height of the terminal in cells + + This property is not observable. Reacting to size changes requires + polling. + ``window-id`` Read-only - mpv's window id. May not always be available, i.e due to window not being opened yet or not being supported by the VO. @@ -2953,6 +3045,13 @@ Property list The codec name used by this track, for example ``h264``. Unavailable in some rare cases. + ``track-list/N/codec-desc`` + The codec descriptive name used by this track. + + ``track-list/N/codec-profile`` + The codec profile used by this track. Available only if the track has + been already decoded. + ``track-list/N/external`` ``yes``/true if the track is an external file, ``no``/false or unavailable otherwise. This is set for separate subtitle files. @@ -3013,6 +3112,11 @@ Property list ``track-list/N/demux-par`` Pixel aspect ratio. + ``track-list/N/format-name`` + Short name for format from ffmpeg. If the track is audio, this will be + the name of the sample format. If the track is video, this will be the + name of the pixel format. + ``track-list/N/audio-channels`` (deprecated) Deprecated alias for ``track-list/N/demux-channel-count``. @@ -3048,6 +3152,8 @@ Property list "external" MPV_FORMAT_FLAG "external-filename" MPV_FORMAT_STRING "codec" MPV_FORMAT_STRING + "codec-desc" MPV_FORMAT_STRING + "codec-profile" MPV_FORMAT_STRING "ff-index" MPV_FORMAT_INT64 "decoder-desc" MPV_FORMAT_STRING "demux-w" MPV_FORMAT_INT64 @@ -3325,39 +3431,19 @@ Property list ``current-vo`` Current video output driver (name as used with ``--vo``). +``current-gpu-context`` + Current GPU context of video output driver (name as used with ``--gpu-context``). + Valid for ``--vo=gpu`` and ``--vo=gpu-next``. + ``current-ao`` Current audio output driver (name as used with ``--ao``). -``shared-script-properties`` (RW) - This is a key/value map of arbitrary strings shared between scripts for - general use. The player itself does not use any data in it (although some - builtin scripts may). The property is not preserved across player restarts. - - This is very primitive, inefficient, and annoying to use. It's a makeshift - solution which could go away any time (for example, when a better solution - becomes available). This is also why this property has an annoying name. You - should avoid using it, unless you absolutely have to. - - Lua scripting has helpers starting with ``utils.shared_script_property_``. - They are undocumented because you should not use this property. If you still - think you must, you should use the helpers instead of the property directly. - - You are supposed to use the ``change-list`` command to modify the contents. - Reading, modifying, and writing the property manually could data loss if two - scripts update different keys at the same time due to lack of - synchronization. The Lua helpers take care of this. - - (There is no way to ensure synchronization if two scripts try to update the - same key at the same time.) - ``user-data`` (RW) This is a recursive key/value map of arbitrary nodes shared between clients for general use (i.e. scripts, IPC clients, host applications, etc). The player itself does not use any data in it (although some builtin scripts may). The property is not preserved across player restarts. - This is a more powerful replacement for ``shared-script-properties``. - Sub-paths can be accessed directly; e.g. ``user-data/my-script/state/a`` can be read, written, or observed. @@ -3368,6 +3454,48 @@ Property list and not using raw mode, the underlying content will be given (e.g. strings will be printed directly, rather than quoted and JSON-escaped). +``menu-data`` (RW) + This property stores the raw menu definition. See `Context Menu`_ section for details. + + ``type`` + Menu item type. Can be: ``separator``, ``submenu``, or empty. + + ``title`` + Menu item title. Required if type is not ``separator``. + + ``cmd`` + Command to execute when the menu item is clicked. + + ``shortcut`` + Menu item shortcut key which appears to the right of the menu item. + A shortcut key does not have to be functional; it's just a visual hint. + + ``state`` + Menu item state. Can be: ``checked``, ``disabled``, ``hidden``, or empty. + + ``submenu`` + Submenu items, which is required if type is ``submenu``. + + When querying the property with the client API using ``MPV_FORMAT_NODE``, or with + Lua ``mp.get_property_native``, this will return a mpv_node with the following + contents: + + :: + + MPV_FORMAT_NODE_ARRAY + MPV_FORMAT_NODE_MAP (menu item) + "type" MPV_FORMAT_STRING + "title" MPV_FORMAT_STRING + "cmd" MPV_FORMAT_STRING + "shortcut" MPV_FORMAT_STRING + "state" MPV_FORMAT_NODE_ARRAY[MPV_FORMAT_STRING] + "submenu" MPV_FORMAT_NODE_ARRAY[menu item] + + Writing to this property with the client API using ``MPV_FORMAT_NODE`` or with + Lua ``mp.set_property_native`` will trigger an immediate update of the menu if + mpv video output is currently active. You may observe the ``current-vo`` + property to check if this is the case. + ``working-directory`` The working directory of the mpv process. Can be useful for JSON IPC users, because the command line player usually works with relative paths. @@ -3430,9 +3558,8 @@ Property list ``ffmpeg-version`` The contents of the ``av_version_info()`` API call. This is a string which identifies the build in some way, either through a release version number, - or a git hash. This applies to Libav as well (the property is still named - the same.) This property is unavailable if mpv is linked against older - FFmpeg and Libav versions. + or a git hash. This property is unavailable if mpv is linked against older + FFmpeg versions. ``libass-version`` The value of ``ass_library_version()``. This is an integer, encoded in a @@ -3681,7 +3808,9 @@ Normally, properties are formatted as human-readable text, meant to be displayed on OSD or on the terminal. It is possible to retrieve an unformatted (raw) value from a property by prefixing its name with ``=``. These raw values can be parsed by other programs and follow the same conventions as the options -associated with the properties. +associated with the properties. Additionally, there is a ``>`` prefix to format +human-readable text, with fixed precision for floating-point values. This is +useful for printing values where a constant width is important. .. admonition:: Examples @@ -3690,6 +3819,10 @@ associated with the properties. - ``${=time-pos}`` expands to ``863.4`` (same time, plus 400 milliseconds - milliseconds are normally not shown in the formatted case) + - ``${avsync}`` expands to ``+0.003`` + - ``${>avsync}`` expands to ``+0.0030`` + - ``${=avsync}`` expands to ``0.003028`` + Sometimes, the difference in amount of information carried by raw and formatted property values can be rather big. In some cases, raw values have more information, like higher precision than seconds with ``time-pos``. Sometimes diff --git a/DOCS/man/javascript.rst b/DOCS/man/javascript.rst index bdbb04b..0edb01f 100644 --- a/DOCS/man/javascript.rst +++ b/DOCS/man/javascript.rst @@ -27,16 +27,17 @@ otherwise, the documented Lua options, script directories, loading, etc apply to JavaScript files too. Script initialization and lifecycle is the same as with Lua, and most of the Lua -functions at the modules ``mp``, ``mp.utils``, ``mp.msg`` and ``mp.options`` are -available to JavaScript with identical APIs - including running commands, -getting/setting properties, registering events/key-bindings/hooks, etc. +functions in the modules ``mp``, ``mp.utils``, ``mp.msg``, ``mp.options`` and +``mp.input`` are available to JavaScript with identical APIs - including running +commands, getting/setting properties, registering events/key-bindings/hooks, +etc. Differences from Lua -------------------- -No need to load modules. ``mp``, ``mp.utils``, ``mp.msg`` and ``mp.options`` -are preloaded, and you can use e.g. ``var cwd = mp.utils.getcwd();`` without -prior setup. +No need to load modules. ``mp``, ``mp.utils``, ``mp.msg``, ``mp.options`` and +``mp.input`` are preloaded, and you can use e.g. ``var cwd = +mp.utils.getcwd();`` without prior setup. Errors are slightly different. Where the Lua APIs return ``nil`` for error, the JavaScript ones return ``undefined``. Where Lua returns ``something, error`` @@ -195,6 +196,16 @@ meta-paths like ``~~/foo`` (other JS file functions do expand meta paths). ``mp.options.read_options(obj [, identifier [, on_update]])`` (types: string/boolean/number) +``mp.input.get(obj)`` (LE) + +``mp.input.terminate()`` + +``mp.input.log(message, style)`` + +``mp.input.log_error(message)`` + +``mp.input.set_log(log)`` + Additional utilities -------------------- diff --git a/DOCS/man/lua.rst b/DOCS/man/lua.rst index 5708e19..7377696 100644 --- a/DOCS/man/lua.rst +++ b/DOCS/man/lua.rst @@ -308,16 +308,17 @@ The ``mp`` module is preloaded, although it can be loaded manually with ``repeatable`` If set to ``true``, enables key repeat for this specific binding. + This option only makes sense when ``complex`` is not set to ``true``. ``complex`` - If set to ``true``, then ``fn`` is called on both key up and down - events (as well as key repeat, if enabled), with the first - argument being a table. This table has the following entries (and - may contain undocumented ones): + If set to ``true``, then ``fn`` is called on key down, repeat and up + events, with the first argument being a table. This table has the + following entries (and may contain undocumented ones): ``event`` Set to one of the strings ``down``, ``repeat``, ``up`` or - ``press`` (the latter if key up/down can't be tracked). + ``press`` (the latter if key up/down/repeat can't be + tracked). ``is_mouse`` Boolean Whether the event was caused by a mouse button. @@ -426,9 +427,9 @@ The ``mp`` module is preloaded, although it can be loaded manually with This depends on the property, and it's a valid feature request to ask for better update handling of a specific property. - If the ``type`` is ``none`` or ``nil``, sporadic property change events are - possible. This means the change function ``fn`` can be called even if the - property doesn't actually change. + If the ``type`` is ``none`` or ``nil``, the change function ``fn`` will be + called sporadically even if the property doesn't actually change. You should + therefore avoid using these types. You always get an initial change notification. This is meant to initialize the user's state to the current value of the property. @@ -862,6 +863,94 @@ strictly part of the guaranteed API. Turn the given value into a string. Formats tables and their contents. This doesn't do anything special; it is only needed because Lua is terrible. +mp.input functions +-------------------- + +This module lets scripts get textual input from the user using the console +REPL. + +``input.get(table)`` + Show the console to let the user enter text. + + The following entries of ``table`` are read: + + ``prompt`` + The string to be displayed before the input field. + + ``submit`` + A callback invoked when the user presses Enter. The first argument is + the text in the console. You can close the console from within the + callback by calling ``input.terminate()``. If you don't, the console + stays open and the user can input more text. + + ``opened`` + A callback invoked when the console is shown. This can be used to + present a list of options with ``input.set_log()``. + + ``edited`` + A callback invoked when the text changes. This can be used to filter a + list of options based on what the user typed with ``input.set_log()``, + like dmenu does. The first argument is the text in the console. + + ``complete`` + A callback invoked when the user presses TAB. The first argument is the + text before the cursor. The callback should return a table of the string + candidate completion values and the 1-based cursor position from which + the completion starts. console.lua will filter the suggestions beginning + with the the text between this position and the cursor, sort them + alphabetically, insert their longest common prefix, and show them when + there are multiple ones. + + ``closed`` + A callback invoked when the console is hidden, either because + ``input.terminate()`` was invoked from the other callbacks, or because + the user closed it with a key binding. The first argument is the text in + the console, and the second argument is the cursor position. + + ``default_text`` + A string to pre-fill the input field with. + + ``cursor_position`` + The initial cursor position, starting from 1. + + ``id`` + An identifier that determines which input history and log buffer to use + among the ones stored for ``input.get()`` calls. The input histories + and logs are stored in memory and do not persist across different mpv + invocations. Defaults to the calling script name with ``prompt`` + appended. + +``input.terminate()`` + Close the console. + +``input.log(message, style, terminal_style)`` + Add a line to the log buffer. ``style`` can contain additional ASS tags to + apply to ``message``, and ``terminal_style`` can contain escape sequences + that are used when the console is displayed in the terminal. + +``input.log_error(message)`` + Helper to add a line to the log buffer with the same color as the one the + console uses for errors. Useful when the user submits invalid input. + +``input.set_log(log)`` + Replace the entire log buffer. + + ``log`` is a table of strings, or tables with ``text``, ``style`` and + ``terminal_style`` keys. + + Example: + + :: + + input.set_log({ + "regular text", + { + text = "error text", + style = "{\\c&H7a77f2&}", + terminal_style = "\027[31m", + } + }) + Events ------ diff --git a/DOCS/man/mpv.rst b/DOCS/man/mpv.rst index e97422d..479458b 100644 --- a/DOCS/man/mpv.rst +++ b/DOCS/man/mpv.rst @@ -205,8 +205,11 @@ 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. @@ -218,18 +221,16 @@ 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. + 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 @@ -281,7 +282,7 @@ PREVIOUS and NEXT Seek backward/forward 1 minute. ZOOMIN and ZOOMOUT - Changes video zoom. + Change video zoom. If you miss some older key bindings, look at ``etc/restore-old-bindings.conf`` in the mpv git repository. @@ -304,6 +305,23 @@ Wheel up/down Wheel left/right 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 ===== @@ -651,8 +669,9 @@ 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 ``#`` and ``\``, ``"``, ``'`` or ``%`` -at the beginning of the value, and leading and trailing whitespace. +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 -------------------------------------------------------- @@ -710,22 +729,24 @@ 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=high-quality + [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 ---------------- @@ -968,7 +989,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 @@ -1092,7 +1113,7 @@ 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 --container-fps-override=60`` +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 @@ -1121,10 +1142,10 @@ commands ``quit-watch-later`` (bound to Shift+Q by default) and 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, for -example if you shutdown your system without closing mpv beforehand, unless of -course mpv is terminated abruptly and doesn't have the time to save (e.g. with -the KILL Unix signal). +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, @@ -1152,8 +1173,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://...`` @@ -1199,17 +1220,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`` @@ -1357,27 +1389,6 @@ works like in older mpv releases: change, and not apply your additional settings, and/or use a different profile name. -Linux desktop issues -==================== - -This subsection describes common problems on the Linux desktop. None of these -problems exist on systems like Windows or macOS. - -Disabling Screensaver ---------------------- - -By default, mpv tries to disable the OS screensaver during playback (only if -a VO using the OS GUI API is active). ``--stop-screensaver=no`` disables this. - -A common problem is that Linux desktop environments ignore the standard -screensaver APIs on which mpv relies. In particular, mpv uses the Screen Saver -extension (XSS) on X11, and the idle-inhibit protocol on Wayland. - -Before mpv 0.33.0, the X11 backend ran ``xdg-screensaver reset`` in 10 second -intervals when not paused in order to support screensaver inhibition in these -environments. This functionality was removed in 0.33.0, but it is possible to -call the ``xdg-screensaver`` command line program from a user script instead. - .. include:: options.rst @@ -1445,7 +1456,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. diff --git a/DOCS/man/options.rst b/DOCS/man/options.rst index e0445d4..9f17345 100644 --- a/DOCS/man/options.rst +++ b/DOCS/man/options.rst @@ -46,7 +46,7 @@ Track Selection ``--audio`` is an alias for ``--aid``. - ``--aid=no`` or ``--audio=no`` or ``--no-audio`` disables audio playback. + ``--aid=no`` or ``--audio=no`` disables audio playback. (The latter variant does not work with the client API.) .. note:: @@ -102,7 +102,7 @@ Track Selection ``--sub`` is an alias for ``--sid``. - ``--sid=no`` or ``--sub=no`` or ``--no-sub`` disables subtitle decoding. + ``--sid=no`` or ``--sub=no`` disables subtitle decoding. (The latter variant does not work with the client API.) ``--vid=<ID|auto|no>`` @@ -110,7 +110,7 @@ Track Selection ``--video`` is an alias for ``--vid``. - ``--vid=no`` or ``--video=no`` or ``--no-video`` disables video playback. + ``--vid=no`` or ``--video=no`` disables video playback. (The latter variant does not work with the client API.) If video is disabled, mpv will try to download the audio only if media is @@ -135,11 +135,13 @@ Track Selection Note that if ``--lavfi-complex`` is set before playback is started, the referenced tracks are always selected. -``--subs-with-matching-audio=<yes|no>`` - When autoselecting a subtitle track, select a full/non-forced one even if the selected - audio stream matches your preferred subtitle language (default: yes). If this option is - set to ``no``, a non-forced subtitle track that matches the audio language will never be - autoselected by mpv regardless of the value of ``--slang`` or ``--subs-fallback``. +``--subs-with-matching-audio=<yes|forced|no>`` + When autoselecting a subtitle track, select it even if the selected audio + stream matches you preferred subtitle language (default: yes). If this + option is set to ``no``, then no subtitle track that matches the audio + language will ever be autoselected by mpv regardless of ``--slang`` or + ``subs-fallback``. If set to ``forced``, then only forced subtitles + will be selected. ``--subs-match-os-language=<yes|no>`` When autoselecting a subtitle track, select the track that matches the language of your OS @@ -445,11 +447,10 @@ Playback Control will not enable looping again (the command will show ``(disabled)`` on the OSD message if both loop points are set, but ``ab-loop-count`` is 0). -``--ordered-chapters``, ``--no-ordered-chapters`` - Enabled by default. - Disable support for Matroska ordered chapters. mpv will not load or - search for video segments from other files, and will also ignore any - chapter order specified for the main file. +``--ordered-chapters=<yes|no>`` + Enable support for Matroska ordered chapters. mpv will load and + search for video segments from other files, and will also respect any + chapter order specified for the main file (default: yes). ``--ordered-chapters-files=<playlist-file>`` Loads the given file as playlist, and tries to use the files contained in @@ -853,11 +854,11 @@ Program Behavior May be dangerous if playing from untrusted media. -``--ytdl``, ``--no-ytdl`` +``--ytdl=<yes|no>`` Enable the youtube-dl hook-script. It will look at the input URL, and will play the video located on the website. This works with many streaming sites, not just the one that the script is named after. This requires a recent - version of youtube-dl to be installed on the system. (Enabled by default.) + version of youtube-dl to be installed on the system (default: yes). If the script can't do anything with an URL, it will do nothing. @@ -1053,11 +1054,11 @@ Watch Later named "watch_later" underneath the local state directory (usually ``~/.local/state/mpv/``). -``--no-resume-playback`` - Do not restore playback position from the ``watch_later`` configuration - subdirectory (usually ``~/.config/mpv/watch_later/``). +``--resume-playback=<yes|no>`` + Restore playback position from the ``watch_later`` configuration + subdirectory, usually ``~/.config/mpv/watch_later/`` (default: yes). -``--resume-playback-check-mtime`` +``--resume-playback-check-mtime=<yes|no>`` Only restore the playback position from the ``watch_later`` configuration subdirectory (usually ``~/.config/mpv/watch_later/``) if the file's modification time is the same as at the time of saving. This may prevent @@ -1129,7 +1130,7 @@ Video ``--untimed`` Do not sleep when outputting video frames. Useful for benchmarks when used - with ``--no-audio.`` + with ``--audio=no``. ``--framedrop=<mode>`` Skip displaying some frames to maintain A/V sync on slow systems, or @@ -1293,7 +1294,7 @@ Video or ``--vo=libmpv`` (iOS 9.0 and up) :videotoolbox-copy: copies video back into system RAM (macOS 10.8 or iOS 9.0 and up) :vaapi: requires ``--vo=gpu``, ``--vo=vaapi`` or ``--vo=dmabuf-wayland`` (Linux only) - :vaapi-copy: copies video back into system RAM (Linux with some GPUs only) + :vaapi-copy: copies video back into system RAM (Linux with some GPUs or Windows) :nvdec: requires ``--vo=gpu`` (Any platform CUDA is available) :nvdec-copy: copies video back to system RAM (Any platform CUDA is available) :drm: requires ``--vo=gpu`` (Linux only) @@ -1313,8 +1314,6 @@ Video :mediacodec: requires ``--vo=gpu --gpu-context=android`` or ``--vo=mediacodec_embed`` (Android only) :mediacodec-copy: copies video back to system RAM (Android only) - :mmal: requires ``--vo=gpu`` (Raspberry Pi only - default if available) - :mmal-copy: copies video back to system RAM (Raspberry Pi only) :cuda: requires ``--vo=gpu`` (Any platform CUDA is available) :cuda-copy: copies video back to system RAM (Any platform CUDA is available) :crystalhd: copies video back to system RAM (Any platform supported by hardware) @@ -1409,9 +1408,6 @@ Video affect this additionally. This can give incorrect results even with completely ordinary video sources. - ``rpi`` always uses the hardware overlay renderer, even with - ``--vo=gpu``. - ``mediacodec`` is not safe. It forces RGB conversion (not with ``-copy``) and how well it handles non-standard colorspaces is not known. In the rare cases where 10-bit is supported the bit depth of the output @@ -1497,10 +1493,13 @@ Video For the Vulkan GPU backend, decoding must always happen on the display device, and this option has no effect. -``--vaapi-device=<device file>`` +``--vaapi-device=<device file|adapter name>`` Choose the DRM device for ``vaapi-copy``. This should be the path to a DRM device file. (Default: ``/dev/dri/renderD128``) + On Windows this takes adapter name as an input. Will pick the default adapter + if unset. Alternatives are listed when the name "help" is given. + ``--panscan=<0.0-1.0>`` Enables pan-and-scan functionality (cropping the sides of e.g. a 16:9 video to make it fit a 4:3 display without black bands). The range @@ -1557,7 +1556,7 @@ Video also still be scaled in one dimension if the source uses non-square pixels (e.g. anamorphic widescreen DVDs). - This option is disabled if the ``--no-keepaspect`` option is used. + This option is disabled if ``--keepaspect=no`` is used. ``--video-pan-x=<value>``, ``--video-pan-y=<value>`` Moves the displayed video rectangle by the given value in the X or Y @@ -1569,7 +1568,7 @@ Video ``--video-pan-x=-0.1`` would move the video 192 pixels to the left and ``--video-pan-y=-0.1`` would move the video 108 pixels up. - This option is disabled if the ``--no-keepaspect`` option is used. + This option is disabled if ``--keepaspect=no`` is used. ``--video-rotate=<0-359|no>`` Rotate the video clockwise, in degrees. If ``no`` is given, the video is @@ -1597,7 +1596,7 @@ Video ``--video-zoom=1`` is twice the size, ``--video-zoom=-2`` is one fourth of the size, and so on. - This option is disabled if the ``--no-keepaspect`` option is used. + This option is disabled if ``--keepaspect=no`` is used. ``--video-scale-x=<value>``, ``--video-scale-y=<value>`` Multiply the video display size with the given value (default: 1.0). If a @@ -1605,8 +1604,8 @@ Video video will be either cut off, or black bars are added. This value is multiplied with the value derived from ``--video-zoom`` and - the normal video aspect ratio. This option is disabled if the - ``--no-keepaspect`` option is used. + the normal video aspect ratio. This option is disabled if + ``--keepaspect=no`` is used. ``--video-align-x=<-1-1>``, ``--video-align-y=<-1-1>`` Moves the video rectangle within the black borders, which are usually added @@ -1618,7 +1617,7 @@ Video If video and screen aspect match perfectly, these options do nothing. - This option is disabled if the ``--no-keepaspect`` option is used. + This option is disabled if ``--keepaspect=no`` is used. ``--video-margin-ratio-left=<val>``, ``--video-margin-ratio-right=<val>``, ``--video-margin-ratio-top=<val>``, ``--video-margin-ratio-bottom=<val>`` Set extra video margins on each border (default: 0). Each value is a ratio @@ -1633,7 +1632,7 @@ Video The margins are applied after 90° video rotation, but before any other video transformations. - This option is disabled if the ``--no-keepaspect`` option is used. + This option is disabled if ``--keepaspect=no`` is used. Subtitles still may use the margins, depending on ``--sub-use-margins`` and similar options. @@ -1644,8 +1643,8 @@ Video more generally useful. The behavior of these options may change to fit OSC requirements better, too. -``--correct-pts``, ``--no-correct-pts`` - ``--no-correct-pts`` switches mpv to a mode where video timing is +``--correct-pts=<yes|no>`` + ``--correct-pts=no`` switches mpv to a mode where video timing is determined using a fixed framerate value (either using the ``--container-fps-override`` option, or using file information). Sometimes, files with very broken timestamps can be played somewhat well in this mode. @@ -1657,25 +1656,35 @@ Video .. note:: - Works in ``--no-correct-pts`` mode only. + Works in ``--correct-pts=no`` mode only. -``--deinterlace=<yes|no>`` +``--deinterlace=<yes|no|auto>`` Enable or disable interlacing (default: no). Interlaced video shows ugly comb-like artifacts, which are visible on - fast movement. Enabling this typically inserts the yadif video filter in + fast movement. Enabling this typically inserts the bwdif video filter in order to deinterlace the video, or lets the video output apply deinterlacing if supported. - This behaves exactly like the ``deinterlace`` input property (usually - mapped to ``d``). + When using ``auto``, mpv will insert a deinterlacing filter if ffmpeg + detects that the video frame is interlaced. Be aware that there can be false + positives in certain cases, such as when files are encoded as interlaced + despite the video not actually being so. This is why ``auto`` is not the + default value. + + Keep in mind that using this filter **will** conflict with any manually + inserted deinterlacing filters, and that this will make video look worse if + it's not actually interlaced. - Keep in mind that this **will** conflict with manually inserted - deinterlacing filters, unless you take care. (Since mpv 0.27.0, even the - hardware deinterlace filters will conflict. Also since that version, - ``--deinterlace=auto`` was removed, which used to mean that the default - interlacing option of possibly inserted video filters was used.) +``--deinterlace-field-parity=<tff|bff|auto>`` + Specify the field parity/order when deinterlacing(default: auto) + Each frame of an interlaced video is divided into two fields, which are + then separately transmitted. Top field represents even lines while bottom + field represents odd lines. When deinterlacing the deinterlacer needs to + know the correct temporal order of the fields else the video will appear + jittery. - Note that this will make video look worse if it's not actually interlaced. + ``auto`` will automatically try to detect the field order of the video, + ``tff`` forces top field first while ``bff`` forces bottom field first. ``--frames=<number>`` Play/convert only first ``<number>`` video frames, then quit. @@ -1716,14 +1725,21 @@ Video By default, this is set to ``h264,vc1,hevc,vp8,vp9,av1``. Note that the hardware acceleration special codecs like ``h264_vdpau`` are not - relevant anymore, and in fact have been removed from Libav in this form. + relevant anymore, and in fact have been removed from FFmpeg in this form. This is usually only needed with broken GPUs, where a codec is reported as supported, but decoding causes more problems than it solves. + .. note:: + + On some broken drivers (e.g. NVIDIA on Linux), probing for codecs which + the GPU does not support can unnecessarily slow down video playback + initialization. To alleviate this, explicitly specify a list which + only includes the codecs supported on the setup. + .. admonition:: Example - ``mpv --hwdec=vdpau --vo=vdpau --hwdec-codecs=h264,mpeg2video`` + ``mpv --hwdec=vdpau --hwdec-codecs=h264,mpeg2video`` Enable vdpau decoding for h264 and mpeg2 only. ``--vd-lavc-check-hw-profile=<yes|no>`` @@ -1958,7 +1974,7 @@ Audio In earlier mpv versions you could use ``--ad`` to force the spdif wrapper. This does not work anymore. - .. admonition:: Warning + .. warning:: There is not much reason to use this. HDMI supports uncompressed multichannel PCM, and mpv supports lossless DTS-HD decoding via @@ -1979,13 +1995,13 @@ Audio .. admonition:: Examples ``--ad=mp3float`` - Prefer the FFmpeg/Libav ``mp3float`` decoder over all other MP3 + Prefer the FFmpeg ``mp3float`` decoder over all other MP3 decoders. ``--ad=help`` List all available decoders. - .. admonition:: Warning + .. warning:: Enabling compressed audio passthrough (AC3 and DTS via SPDIF/HDMI) with this option is not possible. Use ``--audio-spdif`` instead. @@ -1995,7 +2011,19 @@ Audio amplification. Negative values can be passed for compatibility, but are treated as 0. - Since mpv 0.18.1, this always controls the internal mixer (aka "softvol"). + Since mpv 0.18.1, this always controls the internal mixer (aka software + volume). + +``--volume-max=<100.0-1000.0>`` + Set the maximum amplification level in percent (default: 130). A value of + 130 will allow you to adjust the volume up to about double the normal level. + +``--volume-gain=<db>`` + Set the volume gain in dB. This is applied on top of other volume and gain + settings. + +``--volume-gain-max=<0.0-150.0>``, ``--volume-gain-min=<-150.0-0.0>`` + Set the volume gain range in dB (default: -96 dB min, 12 dB max). ``--replaygain=<no|track|album>`` Adjust volume gain according to replaygain values stored in the file @@ -2008,8 +2036,8 @@ Audio (default: 0). ``--replaygain-clip=<yes|no>`` - Prevent clipping caused by replaygain by automatically lowering the - gain (default). Use ``--replaygain-clip=no`` to disable this. + Allow the volume gain to clip (default: no). If this option is not + enabled, mpv automatically will prevent clipping by lowering the gain. ``--replaygain-fallback=<db>`` Gain in dB to apply if the file has no replay gain tags. This option @@ -2027,18 +2055,6 @@ Audio See also: ``--volume``. -``--softvol=<no|yes|auto>`` - Deprecated/unfunctional. Before mpv 0.18.1, this used to control whether - to use the volume controls of the audio output driver or the internal mpv - volume filter. - - The current behavior is that softvol is always enabled, i.e. as if this - option is set to ``yes``. The other behaviors are not available anymore, - although ``auto`` almost matches current behavior in most cases. - - The ``no`` behavior is still partially available through the ``ao-volume`` - and ``ao-mute`` properties. But there are no options to reset these. - ``--audio-demuxer=<[+]name>`` Use this audio demuxer type when using ``--audio-file``. Use a '+' before the name to force it; this will skip some checks. Give the demuxer name as @@ -2074,10 +2090,10 @@ Audio This is a key/value list option. See `List Options`_ for details. -``--ad-spdif-dtshd=<yes|no>``, ``--dtshd``, ``--no-dtshd`` +``--ad-spdif-dtshd=<yes|no>``, ``--dtshd=<yes|no>`` If DTS is passed through, use DTS-HD. - .. admonition:: Warning + .. warning:: This and enabling passthrough via ``--ad`` are deprecated in favor of using ``--audio-spdif=dts-hd``. @@ -2135,7 +2151,7 @@ Audio work-around for this on some AOs is to use ``--audio-exclusive=yes`` to circumvent the system mixer entirely. - .. admonition:: Warning + .. warning:: Using ``auto`` can cause issues when using audio over HDMI. The OS will typically report all channel layouts that _can_ go over HDMI, even if @@ -2179,8 +2195,8 @@ Audio ``--audio-samplerate=<Hz>`` Select the output sample rate to be used (of course sound cards have limits on this). If the sample frequency selected is different from that - of the current media, the lavrresample audio filter will be inserted into - the audio filter layer to compensate for the difference. + of the current media, the internal swresample audio filter will be inserted + into the audio filter layer to compensate for the difference. ``--gapless-audio=<no|yes|weak>`` Try to play consecutive audio files with no silence or disruption at the @@ -2217,7 +2233,7 @@ Audio then the buffered audio may run out before playback of the new file can start. -``--initial-audio-sync``, ``--no-initial-audio-sync`` +``--initial-audio-sync=<yes|no>`` When starting a video file or after events such as seeking, mpv will by default modify the audio stream to make it start from the same timestamp as video, by either inserting silence at the start or cutting away the @@ -2226,11 +2242,7 @@ Audio their start timestamps differ, and then video timing is gradually adjusted if necessary to reach correct synchronization later. -``--volume-max=<100.0-1000.0>`` - Set the maximum amplification level in percent (default: 130). A value of - 130 will allow you to adjust the volume up to about double the normal level. - -``--audio-file-auto=<no|exact|fuzzy|all>``, ``--no-audio-file-auto`` +``--audio-file-auto=<no|exact|fuzzy|all>`` Load additional audio files matching the video filename. The parameter specifies how external audio files are matched. @@ -2260,7 +2272,7 @@ Audio a larger buffer if it pleases. If the device creates a smaller buffer, additional audio is buffered in an additional software buffer. - Making this larger will make soft-volume and other filters react slower, + Making this larger may make soft-volume and other filters react slower, introduce additional issues on playback speed change, and block the player on audio format changes. A smaller buffer might lead to audio dropouts. @@ -2281,7 +2293,7 @@ Audio Not all AOs support this. - .. admonition:: Warning + .. warning:: This modifies certain subtle player behavior, like A/V-sync and underrun handling. Enabling this option is strongly discouraged. @@ -2308,8 +2320,18 @@ Subtitles Force subtitle demuxer type for ``--sub-file``. Give the demuxer name as printed by ``--sub-demuxer=help``. +``--sub-lavc-o=<key>=<value>[,<key>=<value>[,...]]`` + Pass AVOptions to libavcodec decoder. Note, a patch to make the o= + unneeded and pass all unknown options through the AVOption system is + welcome. A full list of AVOptions can be found in the FFmpeg manual. + + This is a key/value list option. See `List Options`_ for details. + ``--sub-delay=<sec>`` - Delays subtitles by ``<sec>`` seconds. Can be negative. + Delays primary subtitles by ``<sec>`` seconds. Can be negative. + +``--secondary-sub-delay=<sec>`` + Delays secondary subtitles by ``<sec>`` seconds. Can be negative. ``--sub-files=<file-list>``, ``--sub-file=<filename>`` Add a subtitle file to the list of external subtitles. @@ -2332,8 +2354,8 @@ Subtitles ``--secondary-sid=<ID|auto|no>`` Select a secondary subtitle stream. This is similar to ``--sid``. If a secondary subtitle is selected, it will be rendered as toptitle (i.e. on - the top of the screen) alongside the normal subtitle, and provides a way - to render two subtitles at once. + the top of the screen) alongside the normal subtitle by default, and + provides a way to render two subtitles at once. There are some caveats associated with this feature. For example, bitmap subtitles will always be rendered in their usual position, so selecting a @@ -2343,14 +2365,14 @@ Subtitles .. note:: Styling and interpretation of any formatting tags is disabled for the - secondary subtitle. Internally, the same mechanism as ``--no-sub-ass`` + secondary subtitle. Internally, the same mechanism as ``--sub-ass=no`` is used to strip the styling. .. note:: If the main subtitle stream contains formatting tags which display the subtitle at the top of the screen, it will overlap with the secondary - subtitle. To prevent this, you could use ``--no-sub-ass`` to disable + subtitle. To prevent this, you could use ``--sub-ass=no`` to disable styling in the main subtitle stream. ``--sub-scale=<0-100>`` @@ -2400,7 +2422,7 @@ Subtitles some margin between the bottom and the subtitle. Values above 100 move the subtitle further down. - .. admonition:: Warning + .. warning:: Text subtitles (as opposed to image subtitles) may be cut off if the value of the option is above 100. This is a libass restriction. @@ -2410,6 +2432,10 @@ Subtitles Using ``--sub-margin-y`` can achieve this in a better way. +``--secondary-sub-pos=<0-150>`` + Specify the position of secondary subtitles on the screen. This is similar + to ``--sub-pos`` but for secondary subtitles. + ``--sub-speed=<0.1-10.0>`` Multiply the subtitle event timestamps with the given value. Can be used to fix the playback speed for frame-based subtitle formats. Affects text @@ -2442,7 +2468,7 @@ Subtitles :normal: FreeType autohinter, normal mode :native: font native hinter - .. admonition:: Warning + .. warning:: Enabling hinting can lead to mispositioned text (in situations it's supposed to match up video background), or reduce the smoothness @@ -2489,6 +2515,12 @@ Subtitles This also controls some bitmap subtitle overrides, as well as HTML tags in formats like SRT, despite the name of the option. +``--secondary-sub-ass-override=<yes|no|force|scale|strip>`` + Control whether user secondary substyle overrides should be applied. This + works exactly like ``--sub-ass-override``. + + Default: strip. + ``--sub-ass-force-margins`` Enables placing toptitles and subtitles in black borders when they are available, if the subtitles are in the ASS format. @@ -2585,8 +2617,8 @@ Subtitles canvas size. Can be useful to test broken subtitles, which often happen when the video was trancoded, while attempting to keep the old subtitles. -``--sub-ass``, ``--no-sub-ass`` - Render ASS subtitles natively (enabled by default). +``--sub-ass=<yes|no>`` + Render ASS subtitles natively (default: yes). .. note:: @@ -2595,17 +2627,17 @@ Subtitles using ``--sub-ass-override=style`` should give better results without breaking subtitles too much. - If ``--no-sub-ass`` is specified, all tags and style declarations are + If ``--sub-ass=no`` is specified, all tags and style declarations are stripped and ignored on display. The subtitle renderer uses the font style as specified by the ``--sub-`` options instead. .. note:: - Using ``--no-sub-ass`` may lead to incorrect or completely broken + Using ``--sub-ass=no`` may lead to incorrect or completely broken rendering of ASS/SSA subtitles. It can sometimes be useful to forcibly override the styling of ASS subtitles, but should be avoided in general. -``--sub-auto=<no|exact|fuzzy|all>``, ``--no-sub-auto`` +``--sub-auto=<no|exact|fuzzy|all>`` Load additional subtitle files matching the video filename. The parameter specifies how external subtitle files are matched. ``exact`` is enabled by default. @@ -2721,11 +2753,11 @@ Subtitles This is a path list option. See `List Options`_ for details. -``--sub-visibility``, ``--no-sub-visibility`` +``--sub-visibility=<yes|no>`` Can be used to disable display of subtitles, but still select and decode them. -``--secondary-sub-visibility``, ``--no-secondary-sub-visibility`` +``--secondary-sub-visibility=<yes|no>`` Can be used to disable display of secondary subtitles, but still select and decode them. @@ -2735,12 +2767,26 @@ Subtitles Matroska-style ASS subtitle packets. It should be unique, and libass uses it for fast elimination of duplicates. This option disables caching of subtitles across seeks, so after a seek libass can't eliminate subtitle - packets with the same ReadOrder as earlier packets. + packets with the same ReadOrder as earlier packets. Note that enabling this + option can result in broken subtitle behavior if you are not actually + playing one of the aforementioned broken mkv files. + +``--teletext-page=<-1-999>`` + Select a teletext page number to decode. -``--teletext-page=<1-999>`` This works for ``dvb_teletext`` subtitle streams, and if FFmpeg has been compiled with support for it. + Values ``1-999`` are for individual pages. Special value ``0`` (default) + matches all subtitle pages. Special value ``-1`` matches all pages. + + Note that page ``100`` is the default start page of actual teletext. It is + also the former default value of this option. + + See the ``libzvbi-teletext`` section in FFmpeg documentation for details. + + Default: 0 + ``--sub-past-video-end`` After the last frame of video, if this option is enabled, subtitles will continue to update based on audio timestamps. Otherwise, the subtitles @@ -2760,8 +2806,8 @@ Subtitles .. note:: The ``--sub-font`` option (and many other style related ``--sub-`` - options) are ignored when ASS-subtitles are rendered, unless the - ``--no-sub-ass`` option is specified. + options) are ignored when ASS-subtitles are rendered, unless + ``--sub-ass=no`` is specified. This used to support fontconfig patterns. Starting with libass 0.13.0, this stopped working. @@ -2779,7 +2825,8 @@ Subtitles ``--sub-shadow-offset`` to change its size relative to the text. ``--sub-blur=<0..20.0>`` - Gaussian blur factor. 0 means no blur applied (default). + Gaussian blur factor applied to the sub font border. + 0 means no blur applied (default). ``--sub-bold=<yes|no>`` Format text on bold. @@ -2846,7 +2893,7 @@ Subtitles Control to which corner of the screen text subtitles should be aligned to (default: ``center``). - Never applied to ASS subtitles, except in ``--no-sub-ass`` mode. Likewise, + Never applied to ASS subtitles, except in ``--sub-ass=no`` mode. Likewise, this does not apply to image subtitles. ``--sub-align-y=<top|center|bottom>`` @@ -2892,8 +2939,12 @@ Subtitles This is intended for English, but may in part work for other languages too. The intention is that it can be always enabled so may not remove all parts added. - It removes speaker labels (like MAN:), upper case text in parentheses and - any text in brackets. + + It removes speaker labels (like MAN:) and any text enclosed within symbols like + parentheses or brackets as specified by the ``--sub-filter-sdh-enclosures`` option. + Note that parenthesis (full width parenthesis and the normal variant) are a special + case and only upper case text is removed. For more filtering, you can use the + ``--sub-filter-sdh-harder`` option. Default: ``no``. @@ -2904,6 +2955,15 @@ Subtitles Default: ``no``. +``--sub-filter-sdh-enclosures=<string>`` + Specify a string of characters that ``--sub-filter-sdh`` will use to potentially + remove text. Text that is enclosed within characters specified by this string will + be removed. Note that bracket characters with known pairs (such as ``(`` or ``[``) + will be mapped internally to their matching right hand character, so you only need + to specify left hand characters. + + Default: ``([（``. + ``--sub-filter-regex-...=...`` Set a list of regular expressions to match on text subtitles, and remove any lines that match (default: empty). This is a string list option. See @@ -3116,17 +3176,17 @@ Window This option does not affect the framerate used for ``mf://`` or ``--merge-files``. For that, use ``--mf-fps`` instead. - Setting ``--image-display-duration`` hides the OSC and does not track - playback time on the command-line output, and also does not duplicate - the image frame when encoding. To force the player into "dumb mode" - and actually count out seconds, or to duplicate the image when - encoding, you need to use ``--demuxer=lavf --demuxer-lavf-o=loop=1``, - and use ``--length`` or ``--frames`` to stop after a particular time. + When viewing images, the playback time is not tracked on the command line + output, and the image frame is not duplicated when encoding. To force the + player into "dumb mode" and actually count out seconds, or to duplicate the + image when encoding, you need to use ``--demuxer=lavf + --demuxer-lavf-o=loop=1``, and use ``--length`` or ``--frames`` to stop + after a particular time. ``--force-window=<yes|no|immediate>`` Create a video output window even if there is no video. This can be useful when pretending that mpv is a GUI application. Currently, the window - always has the size 640x480, and is subject to ``--geometry``, + always has the size 960x540, and is subject to ``--geometry``, ``--autofit``, and similar options. .. warning:: @@ -3139,7 +3199,7 @@ Window mode can be used to create the window always on program start, but this may cause other issues. -``--taskbar-progress``, ``--no-taskbar-progress`` +``--taskbar-progress=<yes|no>`` (Windows only) Enable/disable playback progress rendering in taskbar (Windows 7 and above). @@ -3148,14 +3208,14 @@ Window ``--snap-window`` (Windows only) Snap the player window to screen edges. -``--drag-and-drop=<no|auto|replace|append>`` - (X11, Wayland and Windows only) - Controls the default behavior of drag and drop on platforms that support this. - ``auto`` will obey what the underlying os/platform gives mpv. Typically, holding - shift during the drag and drop will append the item to the playlist. Otherwise, - it will completely replace it. ``replace`` and ``append`` always force replacing - and appending to the playlist respectively. ``no`` disables all drag and drop - behavior. +``--drag-and-drop=<no|auto|replace|append|insert-next>`` + Controls the default behavior of drag and drop on platforms that support + this. ``auto`` will obey what the underlying os/platform gives mpv. + Typically, holding shift during the drag and drop will append the item to + the playlist. Otherwise, it will completely replace it. ``replace``, + ``append``, and ``insert-next`` always force replacing, appending to, and + inserting next into the playlist respectively. ``no`` disables all drag and + drop behavior. ``--ontop`` Makes the player window stay on top of other windows. @@ -3173,10 +3233,13 @@ Window :desktop: On top of the Desktop behind windows and Desktop icons. :level: A level as integer. -``--focus-on-open``, ``--no-focus-on-open`` +``--focus-on=<never|open|all>``, (macOS only) - Focus the video window on creation and makes it the front most window. This - is on by default. + Focus the video window and make it the front most window on specific events (default: open). + + :never: Never focus the window on open or new file load events. + :open: Focus the window on creation, eg when a vo is initialised. + :all: Focus the window on open and new file load event. ``--window-corners=<default|donotround|round|roundsmall>`` (Windows only) @@ -3187,14 +3250,14 @@ Window :round: Round the corners if appropriate :roundsmall: Round the corners if appropriate, with a small radius -``--border``, ``--no-border`` +``--border=<yes|no>`` Play video with window border and decorations. Since this is on by default, use ``--no-border`` to disable the standard window decorations. -``--title-bar``, ``--no-title-bar`` - (Windows only) +``--title-bar=<yes|no>`` + (Windows and X11 only) Play video with the window title bar. Since this is on by default, - use --no-title-bar to hide the title bar. The --no-border option takes + use ``--title-bar=no`` to hide the title bar. The ``--border`` option takes precedence. ``--on-all-workspaces`` @@ -3234,6 +3297,11 @@ Window This option does not work properly with all window managers. + .. admonition:: Note (Wayland) + + Wayland does not allow a client to position itself so this option will + only affect the window size. + .. admonition:: Examples ``50:40`` @@ -3248,7 +3316,7 @@ Window ``50%x50%`` Forces the window width and height to half the screen width and height. Will show black borders to compensate for the video aspect - ratio (with most VOs and without ``--no-keepaspect``). + ratio (with most VOs and with ``--keepaspect=yes``). ``50%+10+10/2`` Sets the window to half the screen widths, and positions it 10 pixels below/left of the top left corner of the screen, on the @@ -3296,8 +3364,8 @@ Window of the screen width, or higher than 60% of the screen height. ``--autofit-larger=<[W[xH]]>`` - This option behaves exactly like ``--autofit``, except the window size is - only changed if the window would be larger than the specified size. + This option behaves exactly like ``--autofit``, except that it sets the + maximum size of the window. .. admonition:: Example @@ -3372,20 +3440,19 @@ Window be the default behavior. Currently only affects X11 and SDL VOs. ``--auto-window-resize=<yes|no>`` - (Wayland, Win32, and X11) By default, mpv will automatically resize itself if the video's size changes (i.e. advancing forward in a playlist). Setting this to ``no`` disables this behavior so the window size never changes automatically. This option does not have any impact on the ``--autofit`` or ``--geometry`` options. -``--no-keepaspect``, ``--keepaspect`` - ``--no-keepaspect`` will always stretch the video to window size, and will +``--keepaspect=<yes|no>`` + ``--keepaspect=no`` will always stretch the video to window size, and will disable the window manager hints that force the window aspect ratio. (Ignored in fullscreen mode.) -``--no-keepaspect-window``, ``--keepaspect-window`` - ``--keepaspect-window`` (the default) will lock the window size to the - video aspect. ``--no-keepaspect-window`` disables this behavior, and will +``--keepaspect-window=<yes|no>`` + ``--keepaspect-window=yes`` (the default) will lock the window size to the + video aspect. ``--keepaspect-window=no`` disables this behavior, and will instead add black bars if window aspect and video aspect mismatch. Whether this actually works depends on the VO backend. (Ignored in fullscreen mode.) @@ -3402,13 +3469,12 @@ Window - ``--monitoraspect=4:3`` or ``--monitoraspect=1.3333`` - ``--monitoraspect=16:9`` or ``--monitoraspect=1.7777`` -``--hidpi-window-scale``, ``--no-hidpi-window-scale`` - (macOS, Windows, X11, and Wayland only) - Scale the window size according to the backing scale factor (default: yes). - On regular HiDPI resolutions the window opens with double the size but appears - as having the same size as on non-HiDPI resolutions. +``--hidpi-window-scale=<yes|no>`` + Scale the window size according to the backing DPI scale factor from the OS + (default: no). For example, if the OS DPI scaling is set to 200%, mpv's window + size will be multiplied by 2. -``--native-fs``, ``--no-native-fs`` +``--native-fs=<yes|no>`` (macOS only) Uses the native fullscreen mechanism of the OS (default: yes). @@ -3423,10 +3489,12 @@ Window the screensaver will re-enable when playback is not active. ``always`` will always disable the screensaver. Note that stopping the screensaver is only possible if a video output is available (i.e. there is an open mpv window). + This is not supported on all video outputs, platforms, or desktop environments. - This is not supported on all video outputs or platforms. Sometimes it is - implemented, but does not work (especially with Linux "desktops"). Read the - `Disabling Screensaver`_ section very carefully. + Before mpv 0.33.0, the X11 backend ran ``xdg-screensaver reset`` in 10 second + intervals when not paused in order to support screensaver inhibition in some + environments. This functionality was removed in 0.33.0, but it is possible to + call the ``xdg-screensaver`` command line program from a user script instead. ``--wid=<ID>`` This tells mpv to attach to an existing window. If a VO is selected that @@ -3455,11 +3523,11 @@ Window ``--hwdec=mediacodec`` for direct rendering using MediaCodec, or with ``--vo=gpu --gpu-context=android`` (with or without ``--hwdec=mediacodec``). -``--no-window-dragging`` - Don't move the window when clicking on it and moving the mouse pointer. +``--window-dragging=<yes|no>`` + Move the window when clicking on it and moving the mouse pointer (default: yes). ``--x11-name=<string>`` - Set the window class name for X11-based video output methods. + Set the window instance name for X11-based video output methods. ``--x11-netwm=<yes|no|auto>`` (X11 only) @@ -3511,7 +3579,7 @@ Window mechanism in case there is good/bad behavior with whatever your combination of hardware/drivers/etc. happens to be. -``--x11-wid-title`` ``--no-x11-wid-title`` +``--x11-wid-title=<yes|no>`` Whether or not to set the window title when mpv is embedded on X11 (default: ``no``). @@ -4009,36 +4077,52 @@ Demuxer Input ----- -``--native-keyrepeat`` +``--native-keyrepeat=<yes|no>`` Use system settings for keyrepeat delay and rate, instead of - ``--input-ar-delay`` and ``--input-ar-rate``. (Whether this applies - depends on the VO backend and how it handles keyboard input. Does not - apply to terminal input.) + ``--input-ar-delay`` and ``--input-ar-rate`` (default: no). + Whether this applies depends on the VO backend and how it handles + keyboard input. Does not apply to terminal input. ``--input-ar-delay`` - Delay in milliseconds before we start to autorepeat a key (0 to disable). + Delay in milliseconds before we start to autorepeat a key (default: 200). + Set it to 0 to disable. ``--input-ar-rate`` - Number of key presses to generate per second on autorepeat. + Number of key presses to generate per second on autorepeat (default: 40). ``--input-conf=<filename>`` Specify input configuration file other than the default location in the mpv configuration directory (usually ``~/.config/mpv/input.conf``). -``--no-input-default-bindings`` - Disable default-level ("weak") key bindings. These are bindings which config - files like ``input.conf`` can override. It currently affects the builtin key - bindings, and keys which scripts bind using ``mp.add_key_binding`` (but not - ``mp.add_forced_key_binding`` because this overrides ``input.conf``). +``--input-default-bindings=<yes|no>`` + Enable default-level ("weak") key bindings (default: yes). These are bindings + which config files like ``input.conf`` can override. It currently affects the + builtin key bindings, and keys which scripts bind using ``mp.add_key_binding`` + (but not ``mp.add_forced_key_binding`` because this overrides ``input.conf``). -``--no-input-builtin-bindings`` - Disable loading of built-in key bindings during start-up. This option is - applied only during (lib)mpv initialization, and if used then it will not - be not possible to enable them later. May be useful to libmpv clients. +``--input-builtin-bindings=<yes|no>`` + Enable loading of built-in key bindings during start-up (default: yes). This + option is applied only during (lib)mpv initialization, and if disabled then it + will not be not possible to enable them later. May be useful to libmpv clients. ``--input-cmdlist`` Prints all commands that can be bound to keys. +``--input-commands=<cmd1,cmd2,...>`` + Define a list of commands for mpv to run. The syntax is the same as format + as ``input.conf`` but without the key binding argument at the beginning. + When this option is set at startup, the commands will run after audio and + video playback are about to begin if applicable (in idle mode with no file, + it will run immediately). When changing values at runtime, the commands will + also run as soon as possible. + + This is a string list option. See `List Options`_ for details. + + .. admonition:: Example + + ``--input-commands="playlist-play-index 1,set ao-volume 40"`` + sets the playlist index to 1 and the ao-volume to 40 + ``--input-doubleclick-time=<milliseconds>`` Time in milliseconds to recognize two consecutive button presses as a double-click (default: 300). @@ -4060,8 +4144,8 @@ Input work (key bindings that normally quit will be shown on OSD only, just like any other binding). See `INPUT.CONF`_. -``--input-terminal``, ``--no-input-terminal`` - ``--no-input-terminal`` prevents the player from reading key events from +``--input-terminal=<yes|no>`` + ``--input-terminal=no`` prevents the player from reading key events from standard input. Useful when reading data from standard input. This is automatically enabled when ``-`` is found on the command line. There are situations where you have to set it manually, e.g. if you open @@ -4116,13 +4200,12 @@ Input ``--input-gamepad=<yes|no>`` Enable/disable SDL2 Gamepad support. Disabled by default. -``--input-cursor``, ``--no-input-cursor`` +``--input-cursor=<yes|no>`` Permit mpv to receive pointer events reported by the video output driver. Necessary to use the OSC, or to select the buttons in DVD menus. Support depends on the VO in use. -``--input-cursor-passthrough``, ``--no-input-cursor-passthrough`` - (X11 and Wayland only) +``--input-cursor-passthrough=<yes|no>`` Tell the backend windowing system to allow pointer events to passthrough the mpv window. This allows windows under mpv to instead receive pointer events as if the mpv window was never there. @@ -4138,8 +4221,22 @@ Input implemented. Whether media keys work when the mpv window is focused is implementation-defined. -``--input-right-alt-gr``, ``--no-input-right-alt-gr`` - (Cocoa and Windows only) +``--input-preprocess-wheel=<yes|no>`` + Preprocess ``WHEEL_*`` events so that while scrolling on the horizontal + or vertical direction, the events aren't generated for another direction + even when the two directions are scrolled together (default: yes). + + This preprocessing can be beneficial for preventing accidentally seeking + while changing the volume by scrolling on a touchpad with the default + keybind. Due to the deadzone mechanism used, disabling the preprocessing + allows for diagonal scrolling (such as panning) and potentially reduces + input latency. + + Note that disabling the preprocessing does not affect any filtering done + by the OS/driver before these events are delivered to mpv, if any. + +``--input-right-alt-gr=<yes|no>`` + (macOS and Windows only) Use the right Alt key as Alt Gr to produce special characters. If disabled, count the right Alt as an Alt modifier key. Enabled by default. @@ -4169,11 +4266,11 @@ Input OSD --- -``--osc``, ``--no-osc`` +``--osc=<yes|no>`` Whether to load the on-screen-controller (default: yes). -``--no-osd-bar``, ``--osd-bar`` - Disable display of the OSD bar. +``--osd-bar=<yes|no>`` + Enable display of the OSD bar (default: yes). You can configure this on a per-command basis in input.conf using ``osd-`` prefixes, see ``Input Command Prefixes``. If you want to disable the OSD @@ -4259,11 +4356,18 @@ OSD ``--osd-bar-h=<0.1-50>`` Height of the OSD bar, in percentage of the screen height (default: 3.125). +``--osd-bar-border-size=<size>`` + Size of the border of the OSD bar in scaled pixels (see ``--sub-font-size`` + for details). + + Default: 0.5. + ``--osd-back-color=<color>`` See ``--sub-color``. Color used for OSD text background. ``--osd-blur=<0..20.0>`` - Gaussian blur factor. 0 means no blur applied (default). + Gaussian blur factor applied to the OSD font border. + 0 means no blur applied (default). ``--osd-bold=<yes|no>`` Format text on bold. @@ -4357,7 +4461,7 @@ OSD all OSD rendering, use ``--osd-level=0``. It does not affect subtitles or overlays created by scripts (in particular, - the OSC needs to be disabled with ``--no-osc``). + the OSC needs to be disabled with ``--osc=no``). This option is somewhat experimental and could be replaced by another mechanism in the future. @@ -4547,15 +4651,14 @@ Screenshot Default: ``libaom-av1`` ``--screenshot-avif-pixfmt=<format>`` - Specify the pixel format to the libavcodec encoder. - - Default: ``yuv420p`` + Specify the pixel format for the libavcodec encoder. Defaults to empty, + which lets mpv pick one close to the source format. ``--screenshot-avif-opts=key1=value1,key2=value2,...`` Specifies libavcodec options for selected encoder. For more information, consult the FFmpeg documentation. - Default: ``usage=allintra,crf=32,cpu-used=8,tune=ssim`` + Default: ``usage=allintra,crf=0,cpu-used=8`` Note: the default is only guaranteed to work with the libaom-av1 encoder. Above options may not be valid and or optimal for other encoders. @@ -4564,8 +4667,8 @@ Screenshot .. admonition:: Example - "``--screenshot-avif-opts=crf=32,aq-mode=complexity``" - sets the crf to 32 and quantization (aq-mode) to complexity based. + "``--screenshot-avif-opts=crf=23,aq-mode=complexity``" + sets the crf to 23 and quantization (aq-mode) to complexity based. ``--screenshot-sw=<yes|no>`` Whether to use software rendering for screenshots (default: no). @@ -4696,8 +4799,6 @@ Audio Resampler This controls the default options of any resampling done by mpv (but not within libavfilter, within the system audio API resampler, or any other places). -It also sets the defaults for the ``lavrresample`` audio filter. - ``--audio-resample-filter-size=<length>`` Length of the filter with respect to the lower sampling rate. (default: 16) @@ -4718,9 +4819,6 @@ It also sets the defaults for the ``lavrresample`` audio filter. (default: no). If this is disabled, downmix can cause clipping. If it's enabled, the output might be too quiet. It depends on the source audio. - Technically, this changes the ``normalize`` suboption of the - ``lavrresample`` audio filter, which performs the downmixing. - If downmix happens outside of mpv for some reason, or in the decoder (decoder downmixing), or in the audio output (system mixer), this has no effect. @@ -4736,7 +4834,7 @@ It also sets the defaults for the ``lavrresample`` audio filter. ``--audio-swresample-o=<string>`` Set AVOptions on the SwrContext or AVAudioResampleContext. These should - be documented by FFmpeg or Libav. + be documented by FFmpeg. This is a key/value list option. See `List Options`_ for details. @@ -4754,15 +4852,15 @@ Terminal ``--really-quiet`` Display even less output and status messages than with ``--quiet``. -``--no-terminal``, ``--terminal`` - Disable any use of the terminal and stdin/stdout/stderr. This completely - silences any message output. +``--terminal=<yes|no>`` + ``--terminal=no`` disables any use of the terminal and stdin/stdout/stderr. + This completely silences any message output. Unlike ``--really-quiet``, this disables input and terminal initialization as well. -``--no-msg-color`` - Disable colorful console output on terminals. +``--msg-color=<yes|no>`` + Enable colorful console output on terminals (default: yes). ``--msg-level=<module1=level1,module2=level2,...>`` Control verbosity directly for each module. The ``all`` module changes the @@ -4821,7 +4919,7 @@ Terminal The ``auto`` mode also enables terminal OSD if ``--video-osd=no`` was set. -``--term-osd-bar``, ``--no-term-osd-bar`` +``--term-osd-bar=<yes|no>`` Enable printing a progress bar under the status line on the terminal. (Disabled by default.) @@ -4840,10 +4938,6 @@ Terminal See `Property Expansion`_. -``--term-remaining-playtime``, ``--no-term-remaining-playtime`` - When printing out the time on the terminal, show the remaining time adjusted by - playback speed. Default: ``yes`` - ``--term-status-msg=<string>`` Print out a custom string during playback instead of the standard status line. Expands properties. See `Property Expansion`_. @@ -4884,9 +4978,6 @@ Cache of the cache in kilobytes. Use e.g. ``--cache --demuxer-max-bytes=123k`` instead. -``--no-cache`` - Turn off input stream caching. See ``--cache``. - ``--cache-secs=<seconds>`` How many seconds of audio/video to prefetch if the cache is active. This overrides the ``--demuxer-readahead-secs`` option if and only if the cache @@ -5055,7 +5146,7 @@ Network ``--user-agent=<string>`` Use ``<string>`` as user agent for HTTP streaming. -``--cookies``, ``--no-cookies`` +``--cookies=<yes|no>`` Support cookies when making HTTP requests. Disabled by default. ``--cookies-file=<filename>`` @@ -5093,11 +5184,11 @@ Network ``--tls-ca-file=<filename>`` Certificate authority database file for use with TLS. (Silently fails with - older FFmpeg or Libav versions.) + older FFmpeg versions.) ``--tls-verify`` Verify peer certificates when using TLS (e.g. with ``https://...``). - (Silently fails with older FFmpeg or Libav versions.) + (Silently fails with older FFmpeg versions.) ``--tls-cert-file`` A file containing a certificate to use in the handshake with the @@ -5111,7 +5202,7 @@ Network ``--network-timeout=<seconds>`` Specify the network timeout in seconds (default: 60 seconds). This affects - at least HTTP. The special value 0 uses the FFmpeg/Libav defaults. If a + at least HTTP. The special value 0 uses the FFmpeg defaults. If a protocol is used which does not support timeouts, this option is silently ignored. @@ -5205,57 +5296,6 @@ DVB An example ``input.conf`` could contain: ``H cycle dvbin-channel-switch-offset up``, ``K cycle dvbin-channel-switch-offset down`` -ALSA audio output options -------------------------- - - -``--alsa-device=<device>`` - Deprecated, use ``--audio-device`` (requires ``alsa/`` prefix). - -``--alsa-resample=yes`` - Enable ALSA resampling plugin. (This is disabled by default, because - some drivers report incorrect audio delay in some cases.) - -``--alsa-mixer-device=<device>`` - Set the mixer device used with ``ao-volume`` (default: ``default``). - -``--alsa-mixer-name=<name>`` - Set the name of the mixer element (default: ``Master``). This is for - example ``PCM`` or ``Master``. - -``--alsa-mixer-index=<number>`` - Set the index of the mixer channel (default: 0). Consider the output of - "``amixer scontrols``", then the index is the number that follows the - name of the element. - -``--alsa-non-interleaved`` - Allow output of non-interleaved formats (if the audio decoder uses - this format). Currently disabled by default, because some popular - ALSA plugins are utterly broken with non-interleaved formats. - -``--alsa-ignore-chmap`` - Don't read or set the channel map of the ALSA device - only request the - required number of channels, and then pass the audio as-is to it. This - option most likely should not be used. It can be useful for debugging, - or for static setups with a specially engineered ALSA configuration (in - this case you should always force the same layout with ``--audio-channels``, - or it will work only for files which use the layout implicit to your - ALSA device). - -``--alsa-buffer-time=<microseconds>`` - Set the requested buffer time in microseconds. A value of 0 skips requesting - anything from the ALSA API. This and the ``--alsa-periods`` option uses the - ALSA ``near`` functions to set the requested parameters. If doing so results - in an empty configuration set, setting these parameters is skipped. - - Both options control the buffer size. A low buffer size can lead to higher - CPU usage and audio dropouts, while a high buffer size can lead to higher - latency in volume changes and other filtering. - -``--alsa-periods=<number>`` - Number of periods requested from the ALSA API. See ``--alsa-buffer-time`` - for further remarks. - GPU renderer options ----------------------- @@ -5287,8 +5327,8 @@ them. (This filter is an alias for ``jinc``-windowed ``jinc``) ``ewa_lanczossharp`` - A slightly sharpened version of ewa_lanczos. This is the default when - using the ``high-quality`` profile. + A slightly sharpened version of ``ewa_lanczos``. This is the default + when using the ``high-quality`` profile. ``ewa_lanczos4sharpest`` Very sharp scaler, but also slightly slower than ``ewa_lanczossharp``. @@ -5297,8 +5337,10 @@ them. built-in anti-ringing, so no extra action needs to be taken. ``mitchell`` - Mitchell-Netravali. The ``B`` and ``C`` parameters can be set with - ``--scale-param1`` and ``--scale-param2``. + Mitchell-Netravali. Piecewise cubic filter with a support of radius 2.0. + Provides a balanced compromise of all scaling artifacts. This filter has + both ``B`` and ``C`` set to ``1/3``. The ``B`` and ``C`` parameters can + be controlled with ``--scale-param1`` and ``--scale-param2``. ``hermite`` Hermite spline. Similar to ``bicubic`` but with ``B`` set to ``0.0``. @@ -5307,10 +5349,9 @@ them. default for ``--dscale``. ``catmull_rom`` - Catmull-Rom. A Cubic filter in the same vein as ``mitchell``, where - the ``B`` and ``C`` parameters are ``0.0`` and ``0.5`` respectively. - This filter is sharper than ``mitchell``, but it results in more - ringing. + Catmull-Rom spline. Similar to ``mitchell``, but with ``B`` and ``C`` + set to ``0.0`` and ``0.5`` respectively. This filter is sharper than + ``mitchell``, but prone to ringing. ``oversample`` A version of nearest neighbour that (naively) oversamples pixels, so @@ -5532,14 +5573,16 @@ them. no Disable any dithering done by mpv. auto - Automatic selection. If output bit depth cannot be detected, 8 bits per - component are assumed. + Automatic selection. + On ``--vo=gpu``: detected depth or 8 bpc otherwise + On ``--vo=gpu-next``: detected depth or 8 bpc (for SDR target) 8 Dither to 8 bit output. - Note that the depth of the connected video display device cannot be - detected. Often, LCD panels will do dithering on their own, which conflicts - with this option and leads to ugly output. + Note that the on-the-wire bit depth cannot be detected except when using + ``gpu-api=d3d11``. Explicitly setting the value to your display's bit depth + is recommended, as dithering performed by some LCD panels can be of low + quality. ``--dither-size-fruit=<2-8>`` Set the size of the dither matrix (default: 6). The actual size of the @@ -5729,6 +5772,11 @@ them. from Windows 10. Thus on older systems it will only automatically utilize the rgba8 output format. + .. note:: + + For ``--vo=gpu-next``, this is used as a best-effort hint and + libplacebo has the last say on which format is utilized. + ``--d3d11-output-csp=<auto|srgb|linear|pq|bt.2020>`` Select a specific D3D11 output color space to utilize for D3D11 rendering. "auto" is the default, which will select the color space of the desktop @@ -5774,7 +5822,7 @@ them. ``--wayland-disable-vsync=<yes|no>`` Disable mpv's internal vsync for Wayland-based video output (default: no). This is mainly useful for benchmarking wayland VOs when combined with - ``video-sync=display-desync``, ``--no-audio``, and ``--untimed=yes``. + ``video-sync=display-desync``, ``--audio=no``, and ``--untimed=yes``. ``--wayland-edge-pixels-pointer=<value>`` Defines the size of an edge border (default: 16) to initiate client side @@ -5787,8 +5835,8 @@ them. ``--spirv-compiler=<compiler>`` Controls which compiler is used to translate GLSL to SPIR-V. This is - (currently) only relevant for ``--gpu-api=vulkan`` and `--gpu-api=d3d11`. - The possible choices are currently only: + only relevant for ``--gpu-api=d3d11`` with ``--vo=gpu``. + The possible choices are currently: auto Use the first available compiler. (Default) @@ -5798,7 +5846,7 @@ them. .. note:: - This option is deprecated, since there is only one reasonable value. + This option is deprecated, since there is only one usable value. It may be removed in the future. ``--glsl-shader=<file>``, ``--glsl-shaders=<file-list>`` @@ -5811,7 +5859,7 @@ them. and overwrites the internal list with it. The latter is a path list option (see `List Options`_ for details). - .. admonition:: Warning + .. warning:: The syntax is not stable yet and may change any time. @@ -6192,21 +6240,21 @@ them. software renderer, and ``auto`` only falls back to the software renderer when the usual pixel format couldn't be created. - macOS only. + macOS and cocoa-cb only. ``--cocoa-cb-10bit-context=<yes|no>`` Creates a 10bit capable pixel format for the context creation (default: yes). Instead of 8bit integer framebuffer a 16bit half-float framebuffer is requested. - macOS only. + macOS and cocoa-cb only. ``--macos-title-bar-appearance=<appearance>`` Sets the appearance of the title bar (default: auto). Not all combinations of appearances and ``--macos-title-bar-material`` materials make sense or are unique. Appearances that are not supported by you current macOS version fall back to the default value. - macOS and cocoa-cb only + macOS only ``<appearance>`` can be one of the following: @@ -6231,7 +6279,7 @@ them. ``--macos-title-bar-appearance`` appearances make sense or are unique. Materials that are not supported by you current macOS version fall back to the default value. - macOS and cocoa-cb only + macOS only ``<material>`` can be one of the following: @@ -6280,7 +6328,7 @@ them. 1000ms since it's possible that Apple or the user changes the system defaults. Anything higher than 1000ms though seems too long and shouldn't be set anyway. - (macOS and cocoa-cb only) + (macOS) ``--macos-app-activation-policy=<regular|accessory|prohibited>`` @@ -6310,6 +6358,7 @@ them. :precise: Syncs to the time of the next vertical display refresh reported by the CVDisplayLink callback provided information :system: No manual syncing, depend on the layer mechanic and the next drawable + :feedback: Same as precise but uses the presentation feedback core mechanism ``--android-surface-size=<WxH>`` Set dimensions of the rendering surface used by the Android gpu context. @@ -6328,8 +6377,6 @@ them. auto auto-select (default) - cocoa - Cocoa/macOS (deprecated, use --vo=libmpv instead) win Win32/WGL winvk @@ -6355,7 +6402,7 @@ them. drm DRM/EGL displayvk - VK_KHR_display. This backend is roughly the Vukan equivalent of + VK_KHR_display. This backend is roughly the Vulkan equivalent of DRM/EGL, allowing for direct rendering via Vulkan without a display manager. x11egl @@ -6816,8 +6863,11 @@ them. files contain uncompressed LUTs. Their size depends on the ``--icc-3dlut-size``, and can be very big. - NOTE: On ``--vo=gpu``, this is not cleaned automatically, so old, unused - cache files may stick around indefinitely. + On `--vo=gpu-next`, files that have not been accessed in the last 24 hours + may be cleared if the cache limit (1.5 GiB) is exceeded. + + On ``--vo=gpu``, this is not cleaned automatically, so old, unused cache + files may stick around indefinitely. ``--icc-cache-dir`` The directory where icc cache is stored. Cache is stored in the system's @@ -6902,35 +6952,35 @@ them. softsubbed ASS signs to match the video colors, but may cause SRT subtitles or similar to look slightly off. -``--alpha=<blend-tiles|blend|yes|no>`` - Decides what to do if the input has an alpha component. +``--background=<none|color|tiles>`` + If the frame has an alpha component, decide what kind of background, if any, + to blend it with. This does nothing if there is no alpha component. - blend-tiles + color + Blend the frame against the background color (``--background-color``, + normally black). + tiles Blend the frame against a 16x16 gray/white tiles background (default). - blend - Blend the frame against the background color (``--background``, normally - black). - yes - Try to create a framebuffer with alpha component. This only makes sense - if the video contains alpha information (which is extremely rare) or if - you make the background color transparent. May not be supported on all - platforms. If alpha framebuffers are unavailable, it silently falls - back on a normal framebuffer. Note that if you set the ``--fbo-format`` - option to a non-default value, a format with alpha must be specified, - or this won't work. Whether this really works depends on the windowing - system and desktop environment. - no - Ignore alpha component. + none + Do not blend the frame and leave the alpha as is. + + Before mpv 0.38.0, this option used to accept a color value specifying the + background color. This is now done by the ``--background-color`` option. + Use that instead. + +``--background-color=<color>`` + Color used to draw parts of the mpv window not covered by video. See the + ``--sub-color`` option for how colors are defined. + +``--border-background=<none|color|tiles>`` + Same as ``--background`` but only applies to the black bar/border area of + the window. ``vo=gpu-next`` only. Defaults to ``color``. ``--opengl-rectangle-textures`` Force use of rectangle textures (default: no). Normally this shouldn't have any advantages over normal textures. Note that hardware decoding overrides this flag. Could be removed any time. -``--background=<color>`` - Color used to draw parts of the mpv window not covered by video. See the - ``--sub-color`` option for how colors are defined. - ``--gpu-tex-pad-x``, ``--gpu-tex-pad-y`` Enlarge the video source textures by this many pixels. For debugging only (normally textures are sized exactly, but due to hardware decoding interop @@ -6965,11 +7015,14 @@ them. ``--gpu-shader-cache`` Store and load compiled GLSL shaders in the cache directory (Default: ``yes``). Normally, shader compilation is very fast, so this is not usually - needed. It mostly matters for anything based on D3D11 (including ANGLE), as - well as on some other proprietary drivers. Enabling this can improve startup - performance on these platforms. + needed. It mostly matters for anything involving GLSL to SPIR-V conversion, + that is: D3D11, ANGLE or Vulkan, as well as on some other proprietary + drivers. Enabling this can improve startup performance on these platforms. + + On `--vo=gpu-next`, files that have not been accessed in the last 24 hours + may be cleared if the cache limit (128 MiB) is exceeded. - NOTE: On ``--vo=gpu``, is not cleaned automatically, so old, unused cache + On ``--vo=gpu``, this is not cleaned automatically, so old, unused cache files may stick around indefinitely. ``--gpu-shader-cache-dir`` @@ -7006,9 +7059,9 @@ Miscellaneous Specifying ``--autosync=0``, the default, will cause frame timing to be based entirely on audio delay measurements. Specifying ``--autosync=1`` will do the same, but will subtly change the A/V correction algorithm. An - uneven video framerate in a video which plays fine with ``--no-audio`` can + uneven video framerate in a video which plays fine with ``--audio=no`` can often be helped by setting this to an integer value greater than 1. The - higher the value, the closer the timing will be to ``--no-audio``. Try + higher the value, the closer the timing will be to ``--audio=no``. Try ``--autosync=30`` to smooth out problems with sound drivers which do not implement a perfect audio delay measurement. With this value, if large A/V sync offsets occur, they will only take about 1 or 2 seconds to settle diff --git a/DOCS/man/osc.rst b/DOCS/man/osc.rst index c791d75..9ed338a 100644 --- a/DOCS/man/osc.rst +++ b/DOCS/man/osc.rst @@ -211,6 +211,13 @@ Configurable Options Alpha of the seekable ranges, 0 (opaque) to 255 (fully transparent). +``scrollcontrols`` + Default: yes + + By default, going up or down with the mouse wheel can trigger certain + actions (such as seeking) if the mouse is hovering an OSC element. + Set to ``no`` to disable any special mouse wheel behavior. + ``deadzonesize`` Default: 0.5 @@ -300,7 +307,7 @@ Configurable Options String that supports property expansion that will be displayed as OSC title. - ASS tags are escaped, and newlines and trailing slashes are stripped. + ASS tags are escaped and newlines are converted to spaces. ``tooltipborder`` Default: 1 @@ -393,6 +400,13 @@ Configurable Options Supports ``left`` and ``right`` which will place the controls on those respective sides. +``windowcontrols_title`` + Default: ${media-title} + + String that supports property expansion that will be displayed as the + windowcontrols title. + ASS tags are escaped, and newlines and trailing slashes are stripped. + ``greenandgrumpy`` Default: no diff --git a/DOCS/man/stats.rst b/DOCS/man/stats.rst index 88238bc..7ddf851 100644 --- a/DOCS/man/stats.rst +++ b/DOCS/man/stats.rst @@ -85,6 +85,18 @@ Configurable Options respective duration. This can result in overlapping text when multiple scripts decide to print text at the same time. +``term_width_limit`` + Default: -1 + + Sets the terminal width. + A value of 0 means the width is infinite, -1 means it's automatic. + +``term_height_limit`` + Default: -1 + + Sets the terminal height. + A value of 0 means the height is infinite, -1 means it's automatic. + ``plot_perfdata`` Default: yes diff --git a/DOCS/man/vf.rst b/DOCS/man/vf.rst index 1423e4c..59175e7 100644 --- a/DOCS/man/vf.rst +++ b/DOCS/man/vf.rst @@ -204,10 +204,13 @@ Available mpv-only filters are: Available color spaces are: :auto: automatic selection (default) - :bt.601: ITU-R BT.601 (SD) - :bt.709: ITU-R BT.709 (HD) - :bt.2020-ncl: ITU-R BT.2020 non-constant luminance system - :bt.2020-cl: ITU-R BT.2020 constant luminance system + :bt.601: ITU-R Rec. BT.601 (SD) + :bt.709: ITU-R Rec. BT.709 (HD) + :bt.2020-ncl: ITU-R Rec. BT.2020 (non-constant luminance) + :bt.2020-cl: ITU-R Rec. BT.2020 (constant luminance) + :bt.2100-pq: ITU-R Rec. BT.2100 ICtCp PQ variant + :bt.2100-hlg: ITU-R Rec. BT.2100 ICtCp HLG variant + :dolbyvision: Dolby Vision :smpte-240m: SMPTE-240M ``<colorlevels>`` @@ -313,6 +316,10 @@ Available mpv-only filters are: Whether or not to include Dolby Vision metadata (default: yes). If disabled, any Dolby Vision metadata will be stripped from frames. + ``<hdr10plus=yes|no>`` + Whether or not to include HDR10+ metadata (default: yes). If + disabled, any HDR10+ metadata will be stripped from frames. + ``<film-grain=yes|no>`` Whether or not to include film grain metadata (default: yes). If disabled, any film grain metadata will be stripped from frames. diff --git a/DOCS/man/vo.rst b/DOCS/man/vo.rst index 5ee4eaa..41fcb71 100644 --- a/DOCS/man/vo.rst +++ b/DOCS/man/vo.rst @@ -325,7 +325,7 @@ Available video output drivers are: ``null`` Produces no video output. Useful for benchmarking. - Usually, it's better to disable video with ``--no-video`` instead. + Usually, it's better to disable video with ``--video=no`` instead. The following global options are supported by this video output: @@ -336,6 +336,21 @@ Available video output drivers are: ``caca`` Color ASCII art video output driver that works on a text console. + This driver reserves some keys for runtime configuration. These keys are + hardcoded and cannot be bound: + + d and D + Toggle dithering algorithm. + + a and A + Toggle antialiasing method. + + h and H + Toggle charset method. + + c and C + Toggle color method. + .. note:: This driver is a joke. ``tct`` @@ -348,7 +363,7 @@ Available video output drivers are: performance. Note: the TCT image output is not synchronized with other terminal output - from mpv, which can lead to broken images. The options ``--no-terminal`` or + from mpv, which can lead to broken images. The options ``--terminal=no`` or ``--really-quiet`` can help with that. ``--vo-tct-algo=<algo>`` @@ -361,6 +376,25 @@ Available video output drivers are: Uses spaces. Causes vertical resolution to drop twofolds, but in theory works in more places. + ``--vo-tct-buffering=<pixel|line|frame>`` + Specifies the size of data batches buffered before being sent to the + terminal. + + TCT image output is not synchronized with other terminal output from mpv, + which can lead to broken images. Sending data to the terminal in small + batches may improve parallelism between terminal processing and mpv + processing but incurs a static overhead of generating tens of thousands + of small writes. Also, depending on the terminal used, sending frames in + one chunk might help with tearing of the output, especially if not used + with ``--really-quiet`` and other logs interrupt the data stream. + + pixel + Send data to terminal for each pixel. + line + Send data to terminal for each line. (Default) + frame + Send data to terminal for each frame. + ``--vo-tct-width=<width>`` ``--vo-tct-height=<height>`` Assume the terminal has the specified character width and/or height. These default to 80x25 if the terminal size cannot be determined. @@ -567,30 +601,6 @@ Available video output drivers are: This also supports many of the options the ``gpu`` VO has, depending on the backend. -``rpi`` (Raspberry Pi) - Native video output on the Raspberry Pi using the MMAL API. - - The following global options are supported by this video output: - - ``--rpi-display=<number>`` - Select the display number on which the video overlay should be shown - (default: 0). - - ``--rpi-layer=<number>`` - Select the dispmanx layer on which the video overlay should be shown - (default: -10). Note that mpv will also use the 2 layers above the - selected layer, to handle the window background and OSD. Actual video - rendering will happen on the layer above the selected layer. - - ``--rpi-background=<yes|no>`` - Whether to render a black background behind the video (default: no). - Normally it's better to kill the console framebuffer instead, which - gives better performance. - - ``--rpi-osd=<yes|no>`` - Enabled by default. If disabled with ``no``, no OSD layer is created. - This also means there will be no subtitles rendered. - ``drm`` (Direct Rendering Manager) Video output driver using Kernel Mode Setting / Direct Rendering Manager. Should be used when one doesn't want to install full-blown graphical @@ -651,17 +661,20 @@ Available video output drivers are: lower resolution (the video when handled by the hwdec will be on the drmprime-video plane and at full 4K resolution) - ``--drm-format=<xrgb8888|xrgb2101010>`` + ``--drm-format=<xrgb8888|xbgr8888|xrgb2101010|xbgr2101010|yuyv>`` Select the DRM format to use (default: xrgb8888). This allows you to - choose the bit depth of the DRM mode. xrgb8888 is your usual 24 bit per - pixel/8 bits per channel packed RGB format with 8 bits of padding. - xrgb2101010 is a packed 30 bits per pixel/10 bits per channel packed RGB - format with 2 bits of padding. + choose the bit depth and color type of the DRM mode. + + xrgb8888 is your usual 24bpp packed RGB format with 8 bits of padding. + xrgb2101010 is a 30bpp packed RGB format with 2 bits of padding. + yuyv is a 32bpp packed YUV 4:2:2 format. No planar formats are currently + supported. There are cases when xrgb2101010 will work with the ``drm`` VO, but not with the ``drm`` backend for the ``gpu`` VO. This is because with the ``gpu`` VO, in addition to requiring support in your DRM driver, - requires support for xrgb2101010 in your EGL driver + requires support for xrgb2101010 in your EGL driver. + yuyv only ever works with the ``drm`` VO. ``--drm-draw-surface-size=<[WxH]>`` Sets the size of the surface used on the draw plane. The surface will diff --git a/DOCS/mplayer-changes.rst b/DOCS/mplayer-changes.rst index 6ecb1d0..35bf501 100644 --- a/DOCS/mplayer-changes.rst +++ b/DOCS/mplayer-changes.rst @@ -135,10 +135,10 @@ Miscellaneous * Support for precise scrolling which scales the parameter of commands. If the input doesn't support precise scrolling the scale factor stays 1. * Allow changing/adjusting video filters at runtime. (This is also used to make - the ``D`` key insert vf_yadif if deinterlacing is not supported otherwise). + the ``D`` key insert vf_bwdif if deinterlacing is not supported otherwise). * Improved support for .cue files. -Mac OS X +macOS ~~~~~~~~ * Native OpenGL backend. @@ -177,7 +177,7 @@ Internal changes * General code cleanups (including refactoring or rewrites of many parts). * New build system. * Many bug fixes and removal of long-standing issues. -* Generally preferring FFmpeg/Libav over internal demuxers, decoders, and +* Generally preferring FFmpeg over internal demuxers, decoders, and filters. Detailed Listing of User-visible Changes diff --git a/DOCS/release-policy.md b/DOCS/release-policy.md index 2426ab4..23bc48b 100644 --- a/DOCS/release-policy.md +++ b/DOCS/release-policy.md @@ -26,8 +26,13 @@ While on master: - Update the `VERSION` file. -- Update `DOCS/client-api-changes.rst` and `DOCS/interface-changes.rst` - (in particular, update the last version numbers if necessary) +- Update `DOCS/client-api-changes.rst` (in particular, update the last version + number if necessary) + +- Run `TOOLS/gen-interface-changes.py` to refresh `DOCS/interface-changes.rst`, + edit manually as necessary. + +- Delete all `.txt` files in the `DOCS/interface-changes` directory except for `example.txt`. - Create signed commit with changes. diff --git a/DOCS/tech-overview.txt b/DOCS/tech-overview.txt index e723f78..ca565c7 100644 --- a/DOCS/tech-overview.txt +++ b/DOCS/tech-overview.txt @@ -11,7 +11,7 @@ player/*.c: * main(): * basic initializations (e.g. init_libav() and more) * pre-parse command line (verbosity level, config file locations) - * load config files (parse_cfgfiles()) + * load config files (mp_parse_cfgfiles()) * parse command line, add files from the command line to playlist (m_config_parse_mp_command_line()) * check help options etc. (call handle_help_options()), possibly exit @@ -45,7 +45,7 @@ player/*.c: Things worth saying about the playback core: - most state is in MPContext (core.h), which is not available to the subsystems (and should not be made available) - - the currently played tracks are in mpctx->current_tracks, and decoder + - the currently played tracks are in mpctx->current_track, and decoder state in track.dec/d_sub - the other subsystems rarely call back into the frontend, and the frontend polls them instead (probably a good thing) @@ -126,15 +126,16 @@ options/options.h, options/options.c ... to get a copy of its options. - See m_config.h (below) how to access options. + See m_config_core.h (below) how to access options. - The actual option parser is spread over m_option.c, m_config.c, and - parse_commandline.c, and uses the option table in options.c. + The actual option parser is spread over m_option.c, m_config_frontend.c, + and parse_commandline.c, and uses the option table in options.c. -options/m_config.h & m_config.c: - Code for querying and managing options. This (unfortunately) contains both - declarations for the "legacy-ish" global m_config struct, and ways to access - options in a threads-safe way anywhere, like m_config_cache_alloc(). +options/m_config_*.h & m_config_*.c: + Code for querying and managing options. m_config_frontend.h contains + declarations for the "legacy-ish" global m_config struct, while + m_config_core.h provides ways to access options in a threads-safe way + anywhere, like m_config_cache_alloc(). m_config_cache_alloc() lets anyone read, observe, and write options in any thread. The only state it needs is struct mpv_global, which is an opaque @@ -165,16 +166,15 @@ stream/*: E.g. if mpv sees "http://something" on the command line, it will pick stream_lavf.c based on the prefix, and pass the rest of the filename to it. - Some stream inputs are quite special: stream_dvd.c turns DVDs into mpeg + Some stream inputs are quite special: stream_dvdnav.c turns DVDs into mpeg streams (DVDs are actually a bunch of vob files etc. on a filesystem), - stream_tv.c provides TV input including channel switching. Some stream inputs are just there to invoke special demuxers, like stream_mf.c. (Basically to make the prefix "mf://" do something special.) demux/: Demuxers split data streams into audio/video/sub streams, which in turn - are split in packets. Packets (see demux_packet.h) are mostly byte chunks + are split in packets. Packets (see packet.h) are mostly byte chunks tagged with a playback time (PTS). These packets are passed to the decoders. Most demuxers have been removed from this fork, and the only important and @@ -189,6 +189,14 @@ demux/: cache, which is implemented as a list of packets. The cache is complex because it support seeking, multiple ranges, prefetching, and so on. +filters/: + Filter related code. filter.c contains the generic filtering framework + which converts input frames to output frames (audio, video, or demux + packet data). f_decoder_wrapper.c is a source filter which connects the + frontend with the actual audio and video decoders. f_output_chain.c handles + VO/AO output conversions. f_autoconvert.c automatically inserts the + appropriate conversion filters if format conversion is needed. + video/: This contains several things related to audio/video decoding, as well as video filters. @@ -197,22 +205,18 @@ video/: internally. video/decode/: - vd_*.c are video decoders. (There's only vd_lavc.c left.) dec_video.c - handles most of connecting the frontend with the actual decoder. + vd_*.c are video decoders. (There's only vd_lavc.c left.) video/filter/: - vf_*.c and vf.c form the video filter chain. They are fed by the video - decoder, and output the filtered images to the VOs though vf_vo.c. By - default, no video filters (except vf_vo) are used. vf_scale is automatically - inserted if the video output can't handle the video format used by the - decoder. + vf_*.c are video filters. They are fed by the video decoder, and output the + filtered images to the VOs. By default, no video filters are used. video/out/: Video output. They also create GUI windows and handle user input. In most cases, the windowing code is shared among VOs, like x11_common.c for X11 and w32_common.c for Windows. The VOs stand between frontend and windowing code. - vo_gpu can pick a windowing system at runtime, e.g. the same binary can - provide both X11 and Cocoa support on OSX. + vo_gpu and vo_gpu_next can pick a windowing system at runtime, e.g. the same + binary can provide both X11 and Cocoa support on macOS. VOs can be reconfigured at runtime. A vo_reconfig() call can change the video resolution and format, without destroying the window. @@ -224,13 +228,13 @@ audio/: compressed formats used for spdif.) audio/decode/: - ad_*.c and dec_audio.c handle audio decoding. ad_lavc.c is the - decoder using ffmpeg. ad_spdif.c is not really a decoder, but is used for - compressed audio passthrough. + ad_*.c handle audio decoding. ad_lavc.c is the decoder using ffmpeg. + ad_spdif.c is not really a decoder, but is used for compressed audio + passthrough. audio/filter/: - Audio filter chain. af_lavrresample is inserted if any form of conversion - between audio formats is needed. + Audio filters. af_scaletempo2 is inserted by default if playback is different + from normal speed. audio/out/: Audio outputs. @@ -238,9 +242,9 @@ audio/out/: Unlike VOs, AOs can't be reconfigured on a format change. On audio format changes, the AO will simply be closed and re-opened. - There are wrappers to support for two types of audio APIs: push.c and - pull.c. ao.c calls into one of these. They contain generic code to deal - with the data flow these APIs impose. + buffer.c is the wrapper to support for two types of audio APIs: push and + pull. ao.c calls into that. It contains generic code to deal with the data + flow these APIs impose. Note that mpv synchronizes the video to the audio. That's the reason why buggy audio drivers can have a bad influence on playback quality. @@ -257,10 +261,7 @@ sub/: in turn asks dec_sub.c for subtitle overlay bitmaps, which relays the request to one of the sd_*.c subtitle decoders/renderers. - Subtitle loading is in demux/. The MPlayer subreader.c is mostly gone - parts - of it survive in demux_subreader.c. It's used as last fallback, or to handle - some text subtitle types on Libav. It should go away eventually. Normally, - subtitles are loaded via demux_lavf.c. + Subtitle loading is in demux/. Normally, subtitles are loaded via demux_lavf.c. The subtitles are passed to dec_sub.c and the subtitle decoders in sd_*.c as they are demuxed. All text subtitles are rendered by sd_ass.c. If text @@ -272,8 +273,8 @@ sub/: sd_ass.c's internal state. etc/: - The file input.conf is actually integrated into the mpv binary by the - build system. It contains the default keybindings. + The files input.conf and builtin.conf are actually integrated into the mpv + binary by the build system. They contain the default configs and keybindings. Best practices and Concepts within mpv ====================================== |