From 7af6e64db748f71b472cd2b70ef7ebbe9da97859 Mon Sep 17 00:00:00 2001 From: wm4 Date: Sat, 27 Aug 2016 21:14:41 +0200 Subject: command: add property for current subtitle text Requested by someone. Reuses the code for terminal subtitle display. --- DOCS/man/input.rst | 7 +++++++ 1 file changed, 7 insertions(+) (limited to 'DOCS/man') diff --git a/DOCS/man/input.rst b/DOCS/man/input.rst index 8cdba41a3d..d720961226 100644 --- a/DOCS/man/input.rst +++ b/DOCS/man/input.rst @@ -1668,6 +1668,13 @@ Property list ``sub-use-margins`` (RW) See ``--sub-use-margins``. +``sub-text`` + Return the current subtitle text. Formatting is stripped. If a subtitle + is selected, but no text is currently visible, or the subtitle is not + text-based (i.e. DVD/BD subtitles), an empty string is returned. + + This property is experimental and might be removed in the future. + ``ass-vsfilter-aspect-compat`` (RW) See ``--ass-vsfilter-aspect-compat``. -- cgit v1.2.3 From 5086b2d4568bfd8b39a4418a2db4dbfbb1fae92f Mon Sep 17 00:00:00 2001 From: wm4 Date: Sun, 28 Aug 2016 18:15:37 +0200 Subject: player: add option to disable video OSD Normally, OSD can be disabled with --osd-level=0. But this also disables terminal OSD, and some users want _only_ the terminal OSD. Add --video-osd=no, which essentially disables the video OSD. Ideally, it should probably be possible to control terminal and video OSD levels independently, but that would require separate OSD timers (and other state) for both components, so don't do it. But because the current situation isn't too ideal, add a threat to the manpage that might be changed in the future. Fixes #3387. --- DOCS/man/options.rst | 23 +++++++++++++++++++---- 1 file changed, 19 insertions(+), 4 deletions(-) (limited to 'DOCS/man') diff --git a/DOCS/man/options.rst b/DOCS/man/options.rst index ec8f82349d..7cc66dcb8d 100644 --- a/DOCS/man/options.rst +++ b/DOCS/man/options.rst @@ -2890,6 +2890,17 @@ OSD Default: 0. +``--video-osd=`` + Enabled OSD rendering on the video window (default: yes). This can be used + in situations where terminal OSD is preferred. If you just want to disable + 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``). + + This option is somewhat experimental and could be replaced by another + mechanism in the future. + Screenshot ---------- @@ -3136,11 +3147,15 @@ Terminal Only show warnings or worse, and let the ao_alsa output show errors only. -``--term-osd, --no-term-osd``, ``--term-osd=force`` - Display OSD messages on the console when no video output is available. - Enabled by default. +``--term-osd=`` + Control whether OSD messages are shown on the console when no video output + is available (default: auto). + + :auto: use terminal OSD if no video output active + :no: disable terminal OSD + :force: use terminal OSD even if video output active - ``force`` enables terminal OSD even if a video window is created. + The ``auto`` mode also enables terminal OSD if ``--video-osd=no`` was set. ``--term-osd-bar``, ``--no-term-osd-bar`` Enable printing a progress bar under the status line on the terminal. -- cgit v1.2.3 From f42e4374d55a3b68b0c4fcb342d9cdcd5d15c9c7 Mon Sep 17 00:00:00 2001 From: wm4 Date: Sun, 28 Aug 2016 19:42:03 +0200 Subject: command: export profile list as a property Targeted at scripts, which can do whatever they want with it. This comes with the promise that they could get randomly broken any time. See #977. --- DOCS/man/input.rst | 8 ++++++++ 1 file changed, 8 insertions(+) (limited to 'DOCS/man') diff --git a/DOCS/man/input.rst b/DOCS/man/input.rst index d720961226..5892649fe5 100644 --- a/DOCS/man/input.rst +++ b/DOCS/man/input.rst @@ -2211,6 +2211,14 @@ Property list ``property-list`` Return the list of top-level properties. +``profile-list`` + Return the list of profiles and their contents. This is highly + implementation-specific, and may change any time. Currently, it returns + an array of options for each profile. Each option has a name and a value, + with the value currently always being a string. Note that the options array + is not a map, as order matters and duplicate entries are possible. Recursive + profiles are not expanded, and show up as special ``profile`` options. + Property Expansion ------------------ -- cgit v1.2.3 From 7614f2b3a6789c43e2fee1a2bbc0bdbcc72148f0 Mon Sep 17 00:00:00 2001 From: wm4 Date: Wed, 31 Aug 2016 13:22:32 +0200 Subject: vo_xv: remove an aliased option Trying to get rid of them, and no-colorkey is an instance of it. Kill it. --- DOCS/man/vo.rst | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) (limited to 'DOCS/man') diff --git a/DOCS/man/vo.rst b/DOCS/man/vo.rst index c775f6dde7..dda3ea61cd 100644 --- a/DOCS/man/vo.rst +++ b/DOCS/man/vo.rst @@ -49,9 +49,11 @@ Available video output drivers are: set Same as use but also sets the supplied color key. - ``ck-method=`` + ``ck-method=`` Sets the color key drawing method (default: man). + none + Disables color-keying. man Draw the color key manually (reduces flicker in some cases). bg @@ -63,9 +65,6 @@ Available video output drivers are: Changes the color key to an RGB value of your choice. ``0x000000`` is black and ``0xffffff`` is white. - ``no-colorkey`` - Disables color-keying. - ``buffers=`` Number of image buffers to use for the internal ringbuffer (default: 2). Increasing this will use more memory, but might help with the X server -- cgit v1.2.3 From b10dcecf7d71a076525bc2ac4b6bd72f4c453278 Mon Sep 17 00:00:00 2001 From: wm4 Date: Wed, 31 Aug 2016 17:28:42 +0200 Subject: client API: deprecate "no-..." option handling The client API can do this (and there are apparently some libmpv using projects which rely on this). But it's just unnecessary bloat as it requires a separate code path from the option parser. It would be better to remove this code. Formally deprecate it, including API bump and warning in the API changes file to make it really clear. --- DOCS/man/options.rst | 34 ++++++++++++++++++---------------- 1 file changed, 18 insertions(+), 16 deletions(-) (limited to 'DOCS/man') diff --git a/DOCS/man/options.rst b/DOCS/man/options.rst index 7cc66dcb8d..f5a706940d 100644 --- a/DOCS/man/options.rst +++ b/DOCS/man/options.rst @@ -36,15 +36,32 @@ Track Selection See also ``--alang``. mpv normally prints available audio tracks on the terminal when starting playback of a file. + ``--audio`` is an alias for ``--aid``. + + ``--aid=no`` or ``--audio=no`` or ``--no-audio`` disables audio playback. + (The latter variant does not work with the client API.) + ``--sid=`` Display the subtitle stream specified by ````. ``auto`` selects the default, ``no`` disables subtitles. - See also ``--slang``, ``--no-sub``. + ``--sub`` is an alias for ``--sid``. + + ``--sid=no`` or ``--sub=no`` or ``--no-sub`` disables subtitle decoding. + (The latter variant does not work with the client API.) ``--vid=`` Select video channel. ``auto`` selects the default, ``no`` disables video. + ``--video`` is an alias for ``--vid``. + + ``--vid=no`` or ``--video=no`` or ``--no-video`` disables video playback. + (The latter variant does not work with the client API.) + + If vudeo is disabled, mpv will try to download the audio only if media is + streamed with youtube-dl, because it saves bandwidth. This is done by + setting the ytdl_format to "bestaudio/best" in the ytdl_hook.lua script. + ``--ff-aid=``, ``--ff-sid=``, ``--ff-vid=`` Select audio/subtitle/video streams by the FFmpeg stream index. The FFmpeg stream index is relatively arbitrary, but useful when interacting with @@ -517,14 +534,6 @@ Video ``--vf-clr`` exist to modify a previously specified list, but you should not need these for typical use. -``--no-video`` - Do not play video. With some demuxers this may not work. In those cases - you can try ``--vo=null`` instead. - - mpv will try to download the audio only if media is streamed with - youtube-dl, because it saves bandwidth. This is done by setting the ytdl_format - to "bestaudio/best" in the ytdl_hook.lua script. - ``--untimed`` Do not sleep when outputting video frames. Useful for benchmarks when used with ``--no-audio.`` @@ -1092,9 +1101,6 @@ Audio Audio delay in seconds (positive or negative float value). Positive values delay the audio, and negative values delay the video. -``--no-audio`` - Do not play sound. - ``--mute=`` Set startup audio mute status. ``auto`` (default) will not change the mute status. @@ -1374,10 +1380,6 @@ Subtitles Subtitles in ASS format are normally not changed intentionally, but overriding them can be controlled with ``--ass-style-override``. - -``--no-sub`` - Do not select any subtitle when the file is loaded. - ``--sub-demuxer=<[+]name>`` Force subtitle demuxer type for ``--sub-file``. Give the demuxer name as printed by ``--sub-demuxer=help``. -- cgit v1.2.3 From c55d85992078e465f9e0b7b6998ccdc5f5e77703 Mon Sep 17 00:00:00 2001 From: wm4 Date: Wed, 31 Aug 2016 18:10:11 +0200 Subject: m_option: replace --no-video-aspect alias Instead, add a hacky OPT_ASPECT option type, which only exists to accept a "no" parameter, which in combination with the "--no-..." handling code makes --no-video-aspect work again. We can also remove the code in m_config.c, which only existed to make "--no-aspect" (a deprecated alias) to work. --- DOCS/man/options.rst | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) (limited to 'DOCS/man') diff --git a/DOCS/man/options.rst b/DOCS/man/options.rst index f5a706940d..b4a49a75db 100644 --- a/DOCS/man/options.rst +++ b/DOCS/man/options.rst @@ -712,13 +712,14 @@ Video This option has no effect if ``--video-unscaled`` option is used. -``--video-aspect=`` +``--video-aspect=`` Override video aspect ratio, in case aspect information is incorrect or missing in the file being played. See also ``--no-video-aspect``. - Two values have special meaning: + These values have special meaning: :0: disable aspect ratio handling, pretend the video has square pixels + :no: same as ``0`` :-1: use the video stream or container aspect (default) But note that handling of these special values might change in the future. @@ -727,10 +728,7 @@ Video - ``--video-aspect=4:3`` or ``--video-aspect=1.3333`` - ``--video-aspect=16:9`` or ``--video-aspect=1.7777`` - -``--no-video-aspect`` - Ignore aspect ratio information from video file and assume the video has - square pixels. See also ``--video-aspect``. + - ``--no-video-aspect`` or ``--video-aspect=no`` ``--video-aspect-method=`` This sets the default video aspect determination method (if the aspect is -- cgit v1.2.3 From 6b4f560f3ccca0f7db345bd7a6ed65e9307b432d Mon Sep 17 00:00:00 2001 From: wm4 Date: Thu, 1 Sep 2016 14:21:32 +0200 Subject: vo, ao: disable positional parameter suboptions Positional parameters cause problems because they can be ambiguous with flag options. If a flag option is removed or turned into a non-flag option, it'll usually be interpreted as value for the first sub-option (as positional parameter), resulting in very confusing error messages. This changes it into a simple "option not found" error. I don't expect that anyone really used positional parameters with --vo or --ao. Although the docs for --ao=pulse seem to encourage positional parameters for the host/sink options, which means it could possibly annoy some PulseAudio users. --vf and --af are still mostly used with positional parameters, so this must be a configurable option in the option parser. --- DOCS/man/ao.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'DOCS/man') diff --git a/DOCS/man/ao.rst b/DOCS/man/ao.rst index 8bddc98a42..0ab49e91fc 100644 --- a/DOCS/man/ao.rst +++ b/DOCS/man/ao.rst @@ -183,7 +183,7 @@ Available audio output drivers are: ``pulse`` PulseAudio audio output driver - ``[][:]`` + ``host=``, ``sink=`` Specify the host and optionally output sink to use. An empty string uses a local connection, "localhost" uses network transfer (most likely not what you want). -- cgit v1.2.3 From d32bee5f019f2c51839df16b7c7955dc33651cbe Mon Sep 17 00:00:00 2001 From: wm4 Date: Thu, 1 Sep 2016 20:00:43 +0200 Subject: command: add options to property list Now options are accessible through the property list as well, which unifies them to a degree. Not all options support runtime changes (meaning affected components need to be restarted for the options to take effects). Remove from the manpage those properties which are cleanly mapped to options anyway. From the user-perspective they're just options available through the property interface. --- DOCS/man/input.rst | 173 +++++---------------------------------------------- DOCS/man/options.rst | 5 +- 2 files changed, 18 insertions(+), 160 deletions(-) (limited to 'DOCS/man') diff --git a/DOCS/man/input.rst b/DOCS/man/input.rst index 5892649fe5..fbc7c8faa3 100644 --- a/DOCS/man/input.rst +++ b/DOCS/man/input.rst @@ -838,20 +838,12 @@ an option at runtime. Property list ------------- -``osd-level`` (RW) - See ``--osd-level``. +.. note:: -``osd-scale`` (RW) - OSD font size multiplier, see ``--osd-scale``. - -``loop`` (RW) - See ``--loop``. - -``loop-file`` (RW) - See ``--loop-file`` (uses ``yes``/``no``). - -``speed`` (RW) - See ``--speed``. + Most options can be set as runtime via properties as well. Just remove the + leading ``--`` from the option name. These are not documented. Only + properties which do not exist as option with the same name, or which have + very different behavior from the options are documented below. ``audio-speed-correction``, ``video-speed-correction`` Factor multiplied with ``speed`` at which the player attempts to play the @@ -1078,10 +1070,6 @@ Property list "title" MPV_FORMAT_STRING "default" MPV_FORMAT_FLAG -``ab-loop-a``, ``ab-loop-b`` (RW) - Set/get A-B loop points. See corresponding options and ``ab-loop`` command - for details. - ``angle`` (RW) Current DVD angle. @@ -1154,9 +1142,6 @@ Property list ``af-metadata/`` Equivalent to ``vf-metadata/``, but for audio filters. -``pause`` (RW) - Pause status. This is usually ``yes`` or ``no``. See ``--pause``. - ``idle`` Return ``yes`` if no file is loaded, but the player is staying around because of the ``--idle`` option. @@ -1236,25 +1221,12 @@ Property list is loaded, or when switching ordered chapter segments. This is because the same underlying code is used for seeking and resyncing.) -``hr-seek`` (RW) - See ``--hr-seek``. - ``mixer-active`` Return ``yes`` if the audio mixer is active, ``no`` otherwise. This option is relatively useless. Before mpv 0.18.1, it could be used to infer behavior of the ``volume`` property. -``volume`` (RW) - Current volume (see ``--volume`` for details). - -``volume-max`` (RW) - Current maximum value the volume property can be set to. (Equivalent to the - ``--volume-max`` option.) - -``mute`` (RW) - Current mute status (``yes``/``no``). - ``ao-volume`` (RW) System volume. This property is available only if mpv audio output is currently active, and only if the underlying implementation supports volume @@ -1266,9 +1238,6 @@ Property list Similar to ``ao-volume``, but controls the mute state. May be unimplemented even if ``ao-volume`` works. -``audio-delay`` (RW) - See ``--audio-delay``. - ``audio-codec`` Audio codec selected for decoding. @@ -1316,28 +1285,6 @@ Property list Same as ``audio-params``, but the format of the data written to the audio API. -``aid`` (RW) - Current audio track (similar to ``--aid``). - -``audio`` (RW) - Alias for ``aid``. - -``balance`` (RW) - Audio channel balance. (The implementation of this feature is rather odd. - It doesn't change the volumes of each channel, but instead sets up a pan - matrix to mix the left and right channels.) - - Deprecated. - -``fullscreen`` (RW) - See ``--fullscreen``. - -``deinterlace`` (RW) - See ``--deinterlace``. - -``field-dominance`` (RW) - See ``--field-dominance`` - ``colormatrix`` (R) Redirects to ``video-params/colormatrix``. This parameter (as well as similar ones) can be overridden with the ``format`` video filter. @@ -1345,42 +1292,9 @@ Property list ``colormatrix-input-range`` (R) See ``colormatrix``. -``video-output-levels`` (RW) - See ``--video-output-levels``, - ``colormatrix-primaries`` (R) See ``colormatrix``. -``taskbar-progress`` (RW) - See ``--taskbar-progress``. - -``ontop`` (RW) - See ``--ontop``. - -``border`` (RW) - See ``--border``. - -``on-all-workspaces`` (RW) - See ``--on-all-workspaces``. Unsetting may not work on all WMs. - -``framedrop`` (RW) - See ``--framedrop``. - -``gamma`` (RW) - See ``--gamma``. - -``brightness`` (RW) - See ``--brightness``. - -``contrast`` (RW) - See ``--contrast``. - -``saturation`` (RW) - See ``--saturation``. - -``hue`` (RW) - See ``--hue``. - ``hwdec`` (RW) Reflects the ``--hwdec`` option. @@ -1431,9 +1345,6 @@ Property list while no video is being decoded. All this reflects how detecting hw decoders are detected and used internally in mpv. -``panscan`` (RW) - See ``--panscan``. - ``video-format`` Video format as string. @@ -1600,6 +1511,9 @@ Property list ``video-aspect`` (RW) Video aspect, see ``--video-aspect``. + If video is active, this reports the effective aspect value, instead of + the value of the ``--video-aspect`` option. + ``osd-width``, ``osd-height`` Last known OSD width (can be 0). This is needed if you want to use the ``overlay-add`` command. It gives you the actual OSD size, which can be @@ -1608,24 +1522,6 @@ Property list ``osd-par`` Last known OSD display pixel aspect (can be 0). -``vid`` (RW) - Current video track (similar to ``--vid``). - -``video`` (RW) - Alias for ``vid``. - -``video-align-x``, ``video-align-y`` (RW) - See ``--video-align-x`` and ``--video-align-y``. - -``video-pan-x``, ``video-pan-y`` (RW) - See ``--video-pan-x`` and ``--video-pan-y``. - -``video-zoom`` (RW) - See ``--video-zoom``. - -``video-unscaled`` (W) - See ``--video-unscaled``. - ``program`` (W) Switch TS program (write-only). @@ -1638,36 +1534,6 @@ Property list On write, a channel-switch to the named channel on the same card is performed. Can also be used for channel switching. -``sid`` (RW) - Current subtitle track (similar to ``--sid``). - -``secondary-sid`` (RW) - Secondary subtitle track (see ``--secondary-sid``). - -``sub`` (RW) - Alias for ``sid``. - -``sub-delay`` (RW) - See ``--sub-delay``. - -``sub-pos`` (RW) - See ``--sub-pos``. - -``sub-visibility`` (RW) - See ``--sub-visibility``. - -``sub-forced-only`` (RW) - See ``--sub-forced-only``. - -``sub-scale`` (RW) - Subtitle font size multiplier. - -``ass-force-margins`` (RW) - See ``--ass-force-margins``. - -``sub-use-margins`` (RW) - See ``--sub-use-margins``. - ``sub-text`` Return the current subtitle text. Formatting is stripped. If a subtitle is selected, but no text is currently visible, or the subtitle is not @@ -1675,12 +1541,6 @@ Property list This property is experimental and might be removed in the future. -``ass-vsfilter-aspect-compat`` (RW) - See ``--ass-vsfilter-aspect-compat``. - -``ass-style-override`` (RW) - See ``--ass-style-override``. - ``stream-capture`` (RW) A filename, see ``--stream-capture``. Setting this will start capture using the given filename. Setting it to an empty string will stop it. @@ -1891,11 +1751,8 @@ Property list "title" MPV_FORMAT_STRING "time" MPV_FORMAT_DOUBLE -``af`` (RW) - See ``--af`` and the ``af`` command. - -``vf`` (RW) - See ``--vf`` and the ``vf`` command. +``af``, ``vf`` (RW) + See ``--vf``/``--af`` and the ``vf``/``af`` command. 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 @@ -1913,12 +1770,6 @@ Property list It's also possible to write the property using this format. -``video-rotate`` (RW) - See ``--video-rotate`` option. - -``video-stereo-mode`` (RW) - See ``--video-stereo-mode`` option. - ``seekable`` Return whether it's generally possible to seek in the current file. @@ -2158,6 +2009,10 @@ Property list require reloading the file for changes to take effect. If there is an equivalent property, prefer setting the property instead. + There shouldn't be any reason to access ``options/`` instead of + ````, except in situations in which the properties have different + behavior or conflicting semantics. + ``file-local-options/`` Similar to ``options/``, but when setting an option through this property, the option is reset to its old value once the current file has diff --git a/DOCS/man/options.rst b/DOCS/man/options.rst index b4a49a75db..e723d5cbbe 100644 --- a/DOCS/man/options.rst +++ b/DOCS/man/options.rst @@ -1091,7 +1091,10 @@ Audio Since mpv 0.18.1, this always controls the internal mixer (aka "softvol"). ``--balance=`` - How much left/right channels contribute to the audio. + How much left/right channels contribute to the audio. (The implementation + of this feature is rather odd. It doesn't change the volumes of each + channel, but instead sets up a pan matrix to mix the left and right + channels.) Deprecated. -- cgit v1.2.3 From e4e1dc3c79e192d6c4476a2b52f9ca890385d433 Mon Sep 17 00:00:00 2001 From: wm4 Date: Thu, 1 Sep 2016 20:01:02 +0200 Subject: command: rename/deprecate some conflicting property names These conflict with options of the same name, and prevent a "full" unification. Not addressed is the "cache" property, and possibly a few properties that behave differently from their equivalent options. --- DOCS/man/input.rst | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) (limited to 'DOCS/man') diff --git a/DOCS/man/input.rst b/DOCS/man/input.rst index fbc7c8faa3..defe6166bd 100644 --- a/DOCS/man/input.rst +++ b/DOCS/man/input.rst @@ -903,9 +903,11 @@ Property list list of format names, e.g. mp4 is ``mov,mp4,m4a,3gp,3g2,mj2`` (the list may grow in the future for any format). -``demuxer`` +``current-demuxer`` Name of the current demuxer. (This is useless.) + (Renamed from ``demuxer``.) + ``stream-path`` Filename (full path) of the stream layer filename. (This is probably useless. It looks like this can be different from ``path`` only when @@ -1142,10 +1144,12 @@ Property list ``af-metadata/`` Equivalent to ``vf-metadata/``, but for audio filters. -``idle`` +``idle-active`` Return ``yes`` if no file is loaded, but the player is staying around because of the ``--idle`` option. + (Renamed from ``idle``.) + ``core-idle`` Return ``yes`` if the playback core is paused, otherwise ``no``. This can be different ``pause`` in special situations, such as when the player @@ -1467,10 +1471,12 @@ Property list ``video-frame-info/tff`` ``video-frame-info/repeat`` -``fps`` +``container-fps`` Container FPS. This can easily contain bogus values. For videos that use modern container formats or video codecs, this will often be incorrect. + (Renamed from ``fps``.) + ``estimated-vf-fps`` Estimated/measured FPS of the video filter chain output. (If no filters are used, this corresponds to decoder output.) This uses the average of -- cgit v1.2.3 From 192a7344d91de24d486effba73383b1c2790acc2 Mon Sep 17 00:00:00 2001 From: wm4 Date: Thu, 1 Sep 2016 20:01:29 +0200 Subject: command: remove 2 deprecated properties They were delcared to be removed in mpv 0.20.0, and the next release will be 0.21.0. --- DOCS/man/input.rst | 18 ------------------ 1 file changed, 18 deletions(-) (limited to 'DOCS/man') diff --git a/DOCS/man/input.rst b/DOCS/man/input.rst index defe6166bd..baeb1703d9 100644 --- a/DOCS/man/input.rst +++ b/DOCS/man/input.rst @@ -1331,24 +1331,6 @@ Property list multiple interop drivers for the same hardware decoder, depending on platform and VO. -``hwdec-active`` - Deprecated. To be removed in mpv 0.20.0. Use ``hwdec-current`` instead. - - Return ``yes`` or ``no``, depending on whether any type of hardware decoding - is actually in use. - -``hwdec-detected`` - Deprecated. To be removed in mpv 0.20.0. - - If hardware decoding is active, this returns the hardware decoder in use. - Otherwise, it returns either ``no``, or if applicable, the currently loaded - hardware decoding API. This is known only once the VO has opened (and - possibly later). With some VOs (like ``opengl``), this is never known in - advance, but only when the decoder attempted to create the hw decoder - successfully. Also, hw decoders with ``-copy`` suffix will return ``no`` - while no video is being decoded. All this reflects how detecting hw decoders - are detected and used internally in mpv. - ``video-format`` Video format as string. -- cgit v1.2.3 From 1393d79417278dfa63a7a5c767093eaf3504edce Mon Sep 17 00:00:00 2001 From: wm4 Date: Thu, 1 Sep 2016 20:57:33 +0200 Subject: command: fix or document some property/option consistency issues Make some existing properties behave more like options. This mostly means they don't deny access if the associated component is not active, but redirects to the option. One kind of fishy change is that we apply --brightness etc. only if they're not set to the default value. This won't necessarily work with --vo=xv, but affects only cases where 1. the Xv adapter has been changed to non-defaults, and 2. the user tries to reset them with mpv by passing e.g. --brightness=0. We don't care about Xv, and the noted use-case is dumb, so this change is acceptable. --- DOCS/man/input.rst | 36 ++++++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) (limited to 'DOCS/man') diff --git a/DOCS/man/input.rst b/DOCS/man/input.rst index baeb1703d9..56fa6b355e 100644 --- a/DOCS/man/input.rst +++ b/DOCS/man/input.rst @@ -2062,6 +2062,42 @@ Property list is not a map, as order matters and duplicate entries are possible. Recursive profiles are not expanded, and show up as special ``profile`` options. +Inconsistencies between options and properties +---------------------------------------------- + +You can access (almost) all options as properties, though there are some +caveats with some properties (due to historical reasons): + +``vid``, ``aid``, ``sid`` + While playback is active, you can set existing tracks only. (The option + allows setting any track ID, and which tracks to enable is chosen at + loading time.) + +``deinterlace`` + While video is active, this behaves differently from the option. It will + never return the ``auto`` value (but the state as observed by the video + chain). You cannot set ``auto`` either. + +``video-aspect`` + While video is active, always returns the effective aspect ratio. + +``brightness`` (and other color options) + If ``--vo=xv`` is used, these properties may return the adapter's current + values instead of the option values. + +``display-fps`` + If a VO is created, this will return either the actual display FPS, or + an invalid value, instead of the option value. + +``cache`` + This behaves completely different as property: instead of configuring the + cache size like the option, it returns the cache state in percent. + +``demuxer``, ``idle``, ``length``, ``audio-samplerate``, ``audio-channels``, ``audio-format``, ``fps`` + These behave completely different as property, but are deprecated (newer + aliases which don't conflict have been added). After the deprecation period + they will be changed to the proper option behavior. + Property Expansion ------------------ -- cgit v1.2.3 From ce05413a87ee24e706bf3cc044bf7eec422d034a Mon Sep 17 00:00:00 2001 From: Niklas Haas Date: Fri, 2 Sep 2016 00:08:43 +0200 Subject: vo_opengl: remove pre/post/scale-shaders Deprecated in favor of user-shaders, which are functionally equivalent but superior. (Except in the case of scaler-shader, which has no direct replacement, but it turned out to be a very unpopular feature either way - most custom scalers don't fit into the mpv kernel infrastructure and are therefore implemented as user shaders either way) Signed-off-by: wm4 --- DOCS/man/vo.rst | 78 +++++++++++---------------------------------------------- 1 file changed, 15 insertions(+), 63 deletions(-) (limited to 'DOCS/man') diff --git a/DOCS/man/vo.rst b/DOCS/man/vo.rst index dda3ea61cd..2c7b995843 100644 --- a/DOCS/man/vo.rst +++ b/DOCS/man/vo.rst @@ -584,68 +584,9 @@ Available video output drivers are: better than without it) since it will extend the size to match only the milder of the scale factors between the axes. - ``pre-shaders=``, ``post-shaders=``, ``scale-shader=`` - Custom GLSL fragment shaders. - - pre-shaders (list) - These get applied after conversion to RGB and before linearization - and upscaling. Operates on non-linear RGB (same as input). This is - the best place to put things like sharpen filters. - scale-shader - This gets used instead of scale/cscale when those options are set - to ``custom``. The colorspace it operates on depends on the values - of ``linear-scaling`` and ``sigmoid-upscaling``, so no assumptions - should be made here. - post-shaders (list) - These get applied after upscaling and subtitle blending (when - ``blend-subtitles`` is enabled), but before color management. - Operates on linear RGB if ``linear-scaling`` is in effect, - otherwise non-linear RGB. This is the best place for colorspace - transformations (eg. saturation mapping). - - These files must define a function with the following signature:: - - vec4 sample_pixel(sampler2D tex, vec2 pos, vec2 tex_size) - - (If there is no string ``sample_pixel`` in the shader script, it will - use ``sample`` instead. This is a compatibility hack for older shader - scripts, and is deprecated.) - - The meanings of the parameters are as follows: - - sampler2D tex - The source texture for the shader. - vec2 pos - The position to be sampled, in coordinate space [0-1]. - vec2 tex_size - The size of the texture, in pixels. This may differ from image_size, - eg. for subsampled content or for post-shaders. - - In addition to these parameters, the following uniforms are also - globally available: - - float random - A random number in the range [0-1], different per frame. - int frame - A simple count of frames rendered, increases by one per frame and - never resets (regardless of seeks). - vec2 image_size - The size in pixels of the input image. - vec2 target_size - The size in pixels of the visible part of the scaled (and possibly - cropped) image. - - For example, a shader that inverts the colors could look like this:: - - vec4 sample(sampler2D tex, vec2 pos, vec2 tex_size) - { - vec4 color = texture(tex, pos); - return vec4(1.0 - color.rgb, color.a); - } - ``user-shaders=`` - Custom GLSL hooks. These are similar to ``post-shaders`` etc., but more - flexible: They can be injected at almost arbitrary points in the + Custom GLSL hooks. These are a flexible way to add custom fragment + shaders, which can be injected at almost arbitrary points in the rendering pipeline, and access all previous intermediate textures. .. admonition:: Warning @@ -738,8 +679,19 @@ Available video output drivers are: The raw bound texture itself. The use of this should be avoided unless absolutely necessary. - In addition, the global uniforms described in ``post-shaders`` are - also available. + In addition to these parameters, the following uniforms are also + globally available: + + float random + A random number in the range [0-1], different per frame. + int frame + A simple count of frames rendered, increases by one per frame and + never resets (regardless of seeks). + vec2 image_size + The size in pixels of the input image. + vec2 target_size + The size in pixels of the visible part of the scaled (and possibly + cropped) image. Internally, vo_opengl may generate any number of the following textures. Whenever a texture is rendered and saved by vo_opengl, all of -- cgit v1.2.3 From 3659f9e41646b95dc812640a49bb0b8cb879e441 Mon Sep 17 00:00:00 2001 From: wm4 Date: Fri, 2 Sep 2016 09:42:19 +0200 Subject: command: deprecate "cache" property, replace with "cache-percent" The --cache option and cache property conflict, so one of them has to be renamed. The option is probably used frequently, so initiate deprecation/rename of the property. --- DOCS/man/input.rst | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) (limited to 'DOCS/man') diff --git a/DOCS/man/input.rst b/DOCS/man/input.rst index 56fa6b355e..dbd6166df9 100644 --- a/DOCS/man/input.rst +++ b/DOCS/man/input.rst @@ -2089,11 +2089,7 @@ caveats with some properties (due to historical reasons): If a VO is created, this will return either the actual display FPS, or an invalid value, instead of the option value. -``cache`` - This behaves completely different as property: instead of configuring the - cache size like the option, it returns the cache state in percent. - -``demuxer``, ``idle``, ``length``, ``audio-samplerate``, ``audio-channels``, ``audio-format``, ``fps`` +``demuxer``, ``idle``, ``length``, ``audio-samplerate``, ``audio-channels``, ``audio-format``, ``fps``, ``cache`` These behave completely different as property, but are deprecated (newer aliases which don't conflict have been added). After the deprecation period they will be changed to the proper option behavior. -- cgit v1.2.3 From 907bf832970412a81cc3813ab07a634b116995c3 Mon Sep 17 00:00:00 2001 From: wm4 Date: Fri, 2 Sep 2016 09:48:35 +0200 Subject: manpage: mention the client API/interface change logs Also, I'm seeing that we still have mplayer-changes.rst - add a warning that it's outdated. --- DOCS/man/changes.rst | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) (limited to 'DOCS/man') diff --git a/DOCS/man/changes.rst b/DOCS/man/changes.rst index 92ec3444af..d1daa32bd7 100644 --- a/DOCS/man/changes.rst +++ b/DOCS/man/changes.rst @@ -8,6 +8,11 @@ There is no real changelog, but you can look at the following things: https://github.com/mpv-player/mpv/releases * The git log, which is the "real" changelog +* The files ``client-api-changes.rst`` and ``interface-changes.rst`` in the + ``DOCS`` sub directoryon the git repository, which document API and user + interface changes (the latter usually documents breaking changes only, rather + than additions). * The file ``mplayer-changes.rst`` in the ``DOCS`` sub directory on the git repository, which used to be in place of this section. It documents some - changes that happened since mplayer2 forked off MPlayer. + changes that happened since mplayer2 forked off MPlayer. (Not updated + anymore.) -- cgit v1.2.3 From c72df804604c8b7859af76d3503234725b501c96 Mon Sep 17 00:00:00 2001 From: wm4 Date: Fri, 2 Sep 2016 09:51:21 +0200 Subject: DOCS: move libmpv stub to manpage And replace the sort-of duplicated explanations. (It's a bit funny to use weblinks to the generated web version of itself instead of proper RST links, but I think I don't care.) --- DOCS/man/libmpv.rst | 16 ++++++++++++++++ DOCS/man/mpv.rst | 9 +-------- 2 files changed, 17 insertions(+), 8 deletions(-) create mode 100644 DOCS/man/libmpv.rst (limited to 'DOCS/man') diff --git a/DOCS/man/libmpv.rst b/DOCS/man/libmpv.rst new file mode 100644 index 0000000000..d3e78aa5bc --- /dev/null +++ b/DOCS/man/libmpv.rst @@ -0,0 +1,16 @@ +EMBEDDING INTO OTHER PROGRAMS (LIBMPV) +====================================== + +mpv can be embedded into other programs as video/audio playback backend. The +recommended way to do so is using libmpv. See ``libmpv/client.h`` in the mpv +source code repository. This provides a C API. Bindings for other languages +might be available (see wiki). + +Since libmpv merely allows access to underlying mechanisms that can control +mpv, further documentation is spread over a few places: + +- https://github.com/mpv-player/mpv/blob/master/libmpv/client.h +- http://mpv.io/manual/master/#options +- http://mpv.io/manual/master/#list-of-input-commands +- http://mpv.io/manual/master/#properties +- https://github.com/mpv-player/mpv-examples/tree/master/libmpv diff --git a/DOCS/man/mpv.rst b/DOCS/man/mpv.rst index 5a80319a78..bbfc6d4b7c 100644 --- a/DOCS/man/mpv.rst +++ b/DOCS/man/mpv.rst @@ -785,14 +785,7 @@ The profile always overrides other settings in ``mpv.conf``. .. include:: changes.rst - -EMBEDDING INTO OTHER PROGRAMS (LIBMPV) -====================================== - -mpv can be embedded into other programs as video/audio playback backend. The -recommended way to do so is using libmpv. See ``libmpv/client.h`` in the mpv -source code repository. This provides a C API. Bindings for other languages -might be available (see wiki). +.. include:: libmpv.rst ENVIRONMENT VARIABLES ===================== -- cgit v1.2.3 From 849480d0c9d5ef76bd3296034b2ad5019fb9c21d Mon Sep 17 00:00:00 2001 From: wm4 Date: Fri, 2 Sep 2016 15:59:40 +0200 Subject: vo_opengl: deprecate sub-options, add them as global options vo_opengl sub-option were always rather annoying to handle. It seems better to make them global options instead. This is simpler and easier to use. The only disadvantage we are aware of is that it's not clear that many/all of these new global options work with vo_opengl only. --vo=opengl-hq is also deprecated. There is extensive compatibility with the old behavior. One exception is that --vo-defaults will not apply to opengl-hq (though with opengl it still works). vo-cmdline is also dysfunctional and will be removed in a following commit. These changes also affect opengl-cb. The update mechanism is still rather inefficient: it requires syncing with the VO after each option change, rather than batching updates. There's also no granularity (video.c just updates "everything", and if auto-ICC profiles are enabled, vo_opengl.c will fetch them on each update). Most of the manpage changes were done by Niklas Haas . --- DOCS/man/options.rst | 799 ++++++++++++++++++++++++++++++++++++++++++++++++ DOCS/man/vo.rst | 849 +-------------------------------------------------- 2 files changed, 811 insertions(+), 837 deletions(-) (limited to 'DOCS/man') diff --git a/DOCS/man/options.rst b/DOCS/man/options.rst index e723d5cbbe..a4310208c5 100644 --- a/DOCS/man/options.rst +++ b/DOCS/man/options.rst @@ -3597,6 +3597,805 @@ DVB Default: ``no`` +OpenGL renderer options +----------------------- + +The following video options are currently all specific to ``--vo=opengl`` and +``-vo=opengl-cb`` only, which are the only VOs that implement them. + +``--opengl-dumb-mode=`` + This mode is extremely restricted, and will disable most extended OpenGL + features. This includes high quality scalers and custom shaders! + + It is intended for hardware that does not support FBOs (including GLES, + which supports it insufficiently), or to get some more performance out of + bad or old hardware. + + This mode is forced automatically if needed, and this option is mostly + useful for debugging. It's also enabled automatically if nothing uses + features which require FBOs. + + This option might be silently removed in the future. + +``--scale=`` + + ``bilinear`` + Bilinear hardware texture filtering (fastest, very low quality). This + is the default for compatibility reasons. + + ``spline36`` + Mid quality and speed. This is the default when using ``opengl-hq``. + + ``lanczos`` + Lanczos scaling. Provides mid quality and speed. Generally worse than + ``spline36``, but it results in a slightly sharper image which is good + for some content types. The number of taps can be controlled with + ``scale-radius``, but is best left unchanged. + + (This filter is an alias for ``sinc``-windowed ``sinc``) + + ``ewa_lanczos`` + Elliptic weighted average Lanczos scaling. Also known as Jinc. + Relatively slow, but very good quality. The radius can be controlled + with ``scale-radius``. Increasing the radius makes the filter sharper + but adds more ringing. + + (This filter is an alias for ``jinc``-windowed ``jinc``) + + ``ewa_lanczossharp`` + A slightly sharpened version of ewa_lanczos, preconfigured to use an + ideal radius and parameter. If your hardware can run it, this is + probably what you should use by default. + + ``mitchell`` + Mitchell-Netravali. The ``B`` and ``C`` parameters can be set with + ``--scale-param1`` and ``--scale-param2``. This filter is very good at + downscaling (see ``--dscale``). + + ``oversample`` + A version of nearest neighbour that (naively) oversamples pixels, so + that pixels overlapping edges get linearly interpolated instead of + rounded. This essentially removes the small imperfections and judder + artifacts caused by nearest-neighbour interpolation, in exchange for + adding some blur. This filter is good at temporal interpolation, and + also known as "smoothmotion" (see ``--tscale``). + + ``linear`` + A ``--tscale`` filter. + + There are some more filters, but most are not as useful. For a complete + list, pass ``help`` as value, e.g.:: + + mpv --scale=help + +``--scale-param1=``, ``--scale-param2=`` + Set filter parameters. Ignored if the filter is not tunable. Currently, + this affects the following filter parameters: + + bcspline + Spline parameters (``B`` and ``C``). Defaults to 0.5 for both. + + gaussian + Scale parameter (``t``). Increasing this makes the result blurrier. + Defaults to 1. + + oversample + Minimum distance to an edge before interpolation is used. Setting this + to 0 will always interpolate edges, whereas setting it to 0.5 will + never interpolate, thus behaving as if the regular nearest neighbour + algorithm was used. Defaults to 0.0. + +``--scale-blur=`` + Kernel scaling factor (also known as a blur factor). Decreasing this makes + the result sharper, increasing it makes it blurrier (default 0). If set to + 0, the kernel's preferred blur factor is used. Note that setting this too + low (eg. 0.5) leads to bad results. It's generally recommended to stick to + values between 0.8 and 1.2. + +``--scale-radius=`` + Set radius for tunable filters, must be a float number between 0.5 and + 16.0. Defaults to the filter's preferred radius if not specified. Doesn't + work for every scaler and VO combination. + + Note that depending on filter implementation details and video scaling + ratio, the radius that actually being used might be different (most likely + being increased a bit). + +``--scale-antiring=`` + Set the antiringing strength. This tries to eliminate ringing, but can + introduce other artifacts in the process. Must be a float number between + 0.0 and 1.0. The default value of 0.0 disables antiringing entirely. + + Note that this doesn't affect the special filters ``bilinear`` and + ``bicubic_fast``. + +``--scale-window=`` + (Advanced users only) Choose a custom windowing function for the kernel. + Defaults to the filter's preferred window if unset. Use + ``--scale-window=help`` to get a list of supported windowing functions. + +``--scale-wparam=`` + (Advanced users only) Configure the parameter for the window function given + by ``--scale-window``. Ignored if the window is not tunable. Currently, + this affects the following window parameters: + + kaiser + Window parameter (alpha). Defaults to 6.33. + blackman + Window parameter (alpha). Defaults to 0.16. + gaussian + Scale parameter (t). Increasing this makes the window wider. Defaults + to 1. + +``--scaler-lut-size=<4..10>`` + Set the size of the lookup texture for scaler kernels (default: 6). The + actual size of the texture is ``2^N`` for an option value of ``N``. So the + lookup texture with the default setting uses 64 samples. + + All weights are linearly interpolated from those samples, so increasing + the size of lookup table might improve the accuracy of scaler. + +``--scaler-resizes-only`` + Disable the scaler if the video image is not resized. In that case, + ``bilinear`` is used instead of whatever is set with ``--scale``. Bilinear + will reproduce the source image perfectly if no scaling is performed. + Enabled by default. Note that this option never affects ``--cscale``. + +``--opengl-pbo`` + Enable use of PBOs. On some drivers this can be faster, especially if the + source video size is huge (e.g. so called "4K" video). On other drivers it + might be slower or cause latency issues. + + In theory, this can sometimes lead to sporadic and temporary image + corruption (because reupload is not retried when it fails). + +``--dither-depth=`` + Set dither target depth to N. Default: no. + + no + Disable any dithering done by mpv. + auto + Automatic selection. If output bit depth cannot be detected, 8 bits per + component are assumed. + 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. + +``--dither-size-fruit=<2-8>`` + Set the size of the dither matrix (default: 6). The actual size of the + matrix is ``(2^N) x (2^N)`` for an option value of ``N``, so a value of 6 + gives a size of 64x64. The matrix is generated at startup time, and a large + matrix can take rather long to compute (seconds). + + Used in ``--dither=fruit`` mode only. + +``--dither=`` + Select dithering algorithm (default: fruit). (Normally, the + ``--dither-depth`` option controls whether dithering is enabled.) + +``--temporal-dither`` + Enable temporal dithering. (Only active if dithering is enabled in + general.) This changes between 8 different dithering patterns on each frame + by changing the orientation of the tiled dithering matrix. Unfortunately, + this can lead to flicker on LCD displays, since these have a high reaction + time. + +``--temporal-dither-period=<1-128>`` + Determines how often the dithering pattern is updated when + ``--temporal-dither`` is in use. 1 (the default) will update on every video + frame, 2 on every other frame, etc. + +``--opengl-debug`` + Check for OpenGL errors, i.e. call ``glGetError()``. Also, request a + debug OpenGL context (which does nothing with current graphics drivers + as of this writing). + +``--interpolation`` + Reduce stuttering caused by mismatches in the video fps and display refresh + rate (also known as judder). + + .. warning:: This requires setting the ``--video-sync`` option to one + of the ``display-`` modes, or it will be silently disabled. + This was not required before mpv 0.14.0. + + This essentially attempts to interpolate the missing frames by convoluting + the video along the temporal axis. The filter used can be controlled using + the ``--tscale`` setting. + + Note that this relies on vsync to work, see ``--opengl-swapinterval`` for + more information. + +``--opengl-swapinterval=`` + Interval in displayed frames between two buffer swaps. 1 is equivalent to + enable VSYNC, 0 to disable VSYNC. Defaults to 1 if not specified. + + Note that this depends on proper OpenGL vsync support. On some platforms + and drivers, this only works reliably when in fullscreen mode. It may also + require driver-specific hacks if using multiple monitors, to ensure mpv + syncs to the right one. Compositing window managers can also lead to bad + results, as can missing or incorrect display FPS information (see + ``--display-fps``). + +``--dscale=`` + Like ``--scale``, but apply these filters on downscaling instead. If this + option is unset, the filter implied by ``--scale`` will be applied. + +``--cscale=`` + As ``--scale``, but for interpolating chroma information. If the image is + not subsampled, this option is ignored entirely. + +``--tscale=`` + The filter used for interpolating the temporal axis (frames). This is only + used if ``--interpolation`` is enabled. The only valid choices for + ``--tscale`` are separable convolution filters (use ``--tscale=help`` to + get a list). The default is ``mitchell``. + + Note that the maximum supported filter radius is currently 3, due to + limitations in the number of video textures that can be loaded + simultaneously. + +``--tscale-clamp`` + Clamp the ``--tscale`` filter kernel's value range to [0-1]. This reduces + excessive ringing artifacts in the temporal domain (which typically + manifest themselves as short flashes or fringes of black, mostly around + moving edges) in exchange for potentially adding more blur. + +``--interpolation-threshold=<0..1,-1>`` + Threshold below which frame ratio interpolation gets disabled (default: + ``0.0001``). This is calculated as ``abs(disphz/vfps - 1) < threshold``, + where ``vfps`` is the speed-adjusted display FPS, and ``disphz`` the + display refresh rate. + + The default is intended to almost always enable interpolation if the + playback rate is even slightly different from the display refresh rate. But + note that if you use e.g. ``--video-sync=display-vdrop``, small deviations + in the rate can disable interpolation and introduce a discontinuity every + other minute. + + Set this to ``-1`` to disable this logic. + +``--dscale-radius``, ``--cscale-radius``, ``--tscale-radius``, etc. + Set filter parameters for ``--dscale``, ``--cscale`` and ``--tscale``, + respectively. + + See the corresponding options for ``--scale``. + +``--linear-scaling`` + Scale in linear light. It should only be used with a + ``--opengl-fbo-format`` that has at least 16 bit precision. + +``--correct-downscaling`` + When using convolution based filters, extend the filter size when + downscaling. Increases quality, but reduces performance while downscaling. + + This will perform slightly sub-optimally for anamorphic video (but still + better than without it) since it will extend the size to match only the + milder of the scale factors between the axes. + +``--opengl-shaders=`` + Custom GLSL hooks. These are a flexible way to add custom fragment shaders, + which can be injected at almost arbitrary points in the rendering pipeline, + and access all previous intermediate textures. + + .. admonition:: Warning + + The syntax is not stable yet and may change any time. + + The general syntax of a user shader looks like this:: + + //!METADATA ARGS... + //!METADATA ARGS... + + vec4 hook() { + ... + return something; + } + + //!METADATA ARGS... + //!METADATA ARGS... + + ... + + Each block of metadata, along with the non-metadata lines after it, defines + a single pass. Each pass can set the following metadata: + + HOOK (required) + The texture which to hook into. May occur multiple times within a + metadata block, up to a predetermined limit. See below for a list of + hookable textures. + + BIND + Loads a texture and makes it available to the pass, and sets up macros + to enable accessing it. See below for a list of set macros. By default, + no textures are bound. The special name HOOKED can be used to refer to + the texture that triggered this pass. + + SAVE + Gives the name of the texture to save the result of this pass into. By + default, this is set to the special name HOOKED which has the effect of + overwriting the hooked texture. + + WIDTH , HEIGHT + Specifies the size of the resulting texture for this pass. ``szexpr`` + refers to an expression in RPN (reverse polish notation), using the + operators + - * / > < !, floating point literals, and references to + sizes of existing texture and OUTPUT (such as MAIN.width or + CHROMA.height). By default, these are set to HOOKED.w and HOOKED.h, + respectively. + + WHEN + Specifies a condition that needs to be true (non-zero) for the shader + stage to be evaluated. If it fails, it will silently be omitted. (Note + that a shader stage like this which has a dependency on an optional + hook point can still cause that hook point to be saved, which has some + minor overhead) + + OFFSET ox oy + Indicates a pixel shift (offset) introduced by this pass. These pixel + offsets will be accumulated and corrected during the next scaling pass + (``cscale`` or ``scale``). The default values are 0 0 which correspond + to no shift. Note that offsets are ignored when not overwriting the + hooked texture. + + COMPONENTS n + Specifies how many components of this pass's output are relevant and + should be stored in the texture, up to 4 (rgba). By default, this value + is equal to the number of components in HOOKED. + + Each bound texture (via ``BIND``) will make available the following + definitions to that shader pass, where NAME is the name of the bound + texture: + + vec4 NAME_tex(vec2 pos) + The sampling function to use to access the texture at a certain spot + (in texture coordinate space, range [0,1]). This takes care of any + necessary normalization conversions. + vec4 NAME_texOff(vec2 offset) + Sample the texture at a certain offset in pixels. This works like + NAME_tex but additionally takes care of necessary rotations, so that + sampling at e.g. vec2(-1,0) is always one pixel to the left. + vec2 NAME_pos + The local texture coordinate of that texture, range [0,1]. + vec2 NAME_size + The (rotated) size in pixels of the texture. + mat2 NAME_rot + The rotation matrix associated with this texture. (Rotates pixel space + to texture coordinates) + vec2 NAME_pt + The (unrotated) size of a single pixel, range [0,1]. + sampler NAME_raw + The raw bound texture itself. The use of this should be avoided unless + absolutely necessary. + + In addition to these parameters, the following uniforms are also globally + available: + + float random + A random number in the range [0-1], different per frame. + int frame + A simple count of frames rendered, increases by one per frame and never + resets (regardless of seeks). + vec2 image_size + The size in pixels of the input image. + vec2 target_size + The size in pixels of the visible part of the scaled (and possibly + cropped) image. + + Internally, vo_opengl may generate any number of the following textures. + Whenever a texture is rendered and saved by vo_opengl, all of the passes + that have hooked into it will run, in the order they were added by the + user. This is a list of the legal hook points: + + RGB, LUMA, CHROMA, ALPHA, XYZ (resizable) + Source planes (raw). Which of these fire depends on the image format of + the source. + + CHROMA_SCALED, ALPHA_SCALED (fixed) + Source planes (upscaled). These only fire on subsampled content. + + NATIVE (resizable) + The combined image, in the source colorspace, before conversion to RGB. + + MAINPRESUB (resizable) + The image, after conversion to RGB, but before + ``--blend-subtitles=video`` is applied. + + MAIN (resizable) + The main image, after conversion to RGB but before upscaling. + + LINEAR (fixed) + Linear light image, before scaling. This only fires when + ``--linear-scaling`` is in effect. + + SIGMOID (fixed) + Sigmoidized light, before scaling. This only fires when + ``--sigmoid-upscaling`` is in effect. + + PREKERNEL (fixed) + The image immediately before the scaler kernel runs. + + POSTKERNEL (fixed) + The image immediately after the scaler kernel runs. + + SCALED (fixed) + The final upscaled image, before color management. + + OUTPUT (fixed) + The final output image, after color management but before dithering and + drawing to screen. + + Only the textures labelled with ``resizable`` may be transformed by the + pass. When overwriting a texture marked ``fixed``, the WIDTH, HEIGHT and + OFFSET must be left at their default values. + +``--deband`` + Enable the debanding algorithm. This greatly reduces the amount of visible + banding, blocking and other quantization artifacts, at the expensive of + very slightly blurring some of the finest details. In practice, it's + virtually always an improvement - the only reason to disable it would be + for performance. + +``--deband-iterations=<1..16>`` + The number of debanding steps to perform per sample. Each step reduces a + bit more banding, but takes time to compute. Note that the strength of each + step falls off very quickly, so high numbers (>4) are practically useless. + (Default 1) + +``--deband-threshold=<0..4096>`` + The debanding filter's cut-off threshold. Higher numbers increase the + debanding strength dramatically but progressively diminish image details. + (Default 64) + +``--deband-range=<1..64>`` + The debanding filter's initial radius. The radius increases linearly for + each iteration. A higher radius will find more gradients, but a lower + radius will smooth more aggressively. (Default 16) + + If you increase the ``--deband-iterations``, you should probably decrease + this to compensate. + +``--deband-grain=<0..4096>`` + Add some extra noise to the image. This significantly helps cover up + remaining quantization artifacts. Higher numbers add more noise. (Default + 48) + +``--sigmoid-upscaling`` + When upscaling, use a sigmoidal color transform to avoid emphasizing + ringing artifacts. This also implies ``--linear-scaling``. + +``--sigmoid-center`` + The center of the sigmoid curve used for ``--sigmoid-upscaling``, must be a + float between 0.0 and 1.0. Defaults to 0.75 if not specified. + +``--sigmoid-slope`` + The slope of the sigmoid curve used for ``--sigmoid-upscaling``, must be a + float between 1.0 and 20.0. Defaults to 6.5 if not specified. + +``--sharpen=`` + If set to a value other than 0, enable an unsharp masking filter. Positive + values will sharpen the image (but add more ringing and aliasing). Negative + values will blur the image. If your GPU is powerful enough, consider + alternatives like the ``ewa_lanczossharp`` scale filter, or the + ``--scale-blur`` option. + +``--opengl-glfinish`` + Call ``glFinish()`` before and after swapping buffers (default: disabled). + Slower, but might improve results when doing framedropping. Can completely + ruin performance. The details depend entirely on the OpenGL driver. + +``--opengl-waitvsync`` + Call ``glXWaitVideoSyncSGI`` after each buffer swap (default: disabled). + This may or may not help with video timing accuracy and frame drop. It's + possible that this makes video output slower, or has no effect at all. + + X11/GLX only. + +``--opengl-vsync-fences=`` + Synchronize the CPU to the Nth past frame using the ``GL_ARB_sync`` + extension. A value of 0 disables this behavior (default). A value of 1 + means it will synchronize to the current frame after rendering it. Like + ``--glfinish`` and ``--waitvsync``, this can lower or ruin performance. Its + advantage is that it can span multiple frames, and effectively limit the + number of frames the GPU queues ahead (which also has an influence on + vsync). + +``--opengl-dwmflush=`` + Calls ``DwmFlush`` after swapping buffers on Windows (default: auto). It + also sets ``SwapInterval(0)`` to ignore the OpenGL timing. Values are: no + (disabled), windowed (only in windowed mode), yes (also in full screen). + + The value ``auto`` will try to determine whether the compositor is active, + and calls ``DwmFlush`` only if it seems to be. + + This may help to get more consistent frame intervals, especially with + high-fps clips - which might also reduce dropped frames. Typically, a value + of ``windowed`` should be enough, since full screen may bypass the DWM. + + Windows only. + +``--opengl-dcomposition=`` + Allows DirectComposition when using the ANGLE backend (default: yes). + DirectComposition implies flip-model presentation, which can improve + rendering efficiency on Windows 8+ by avoiding a copy of the video frame. + mpv uses it by default where possible, but it can cause poor behaviour with + some drivers, such as a black screen or graphical corruption when leaving + full-screen mode. Use "no" to disable it. + + Windows with ANGLE only. + +``--opengl-sw`` + Continue even if a software renderer is detected. + +``--opengl-backend=`` + The value ``auto`` (the default) selects the windowing backend. You can + also pass ``help`` to get a complete list of compiled in backends (sorted + by autoprobe order). + + auto + auto-select (default) + cocoa + Cocoa/OS X + win + Win32/WGL + angle + Direct3D11 through the OpenGL ES translation layer ANGLE. This supports + almost everything the ``win`` backend does (if the ANGLE build is new + enough). + dxinterop (experimental) + Win32, using WGL for rendering and Direct3D 9Ex for presentation. Works + on Nvidia and AMD. Newer Intel chips with the latest drivers may also + work. + x11 + X11/GLX + wayland + Wayland/EGL + drm-egl + DRM/EGL + x11egl + X11/EGL + +``--opengl-es=`` + Select whether to use GLES: + + yes + Try to prefer ES over Desktop GL + no + Try to prefer desktop GL over ES + auto + Use the default for each backend (default) + +``--opengl-fbo-format=`` + Selects the internal format of textures used for FBOs. The format can + influence performance and quality of the video output. ``fmt`` can be one + of: rgb