diff options
Diffstat (limited to 'DOCS')
| -rw-r--r-- | DOCS/client-api-changes.rst | 6 | ||||
| -rw-r--r-- | DOCS/interface-changes.rst | 23 | ||||
| -rw-r--r-- | DOCS/man/input.rst | 78 | ||||
| -rw-r--r-- | DOCS/man/lua.rst | 2 | ||||
| -rw-r--r-- | DOCS/man/options.rst | 65 | ||||
| -rw-r--r-- | DOCS/man/vf.rst | 6 | ||||
| -rw-r--r-- | DOCS/man/vo.rst | 17 | ||||
| -rw-r--r-- | DOCS/tech-overview.txt | 2 |
8 files changed, 119 insertions, 80 deletions
diff --git a/DOCS/client-api-changes.rst b/DOCS/client-api-changes.rst index 8ef01a05e1..2027ed9fcf 100644 --- a/DOCS/client-api-changes.rst +++ b/DOCS/client-api-changes.rst @@ -32,7 +32,11 @@ API changes :: - --- mpv 0.17.1 --- + --- mpv 0.18.1 --- + ---- - remove "status" log level from mpv_request_log_messages() docs. This + is 100% equivalent to "v". The behavior is still the same, thus no + actual API change. + --- mpv 0.18.0 --- 1.21 - mpv_set_property() changes behavior with MPV_FORMAT_NODE. Before this change it rejected mpv_nodes with format==MPV_FORMAT_STRING if the property was not a string or did not have special mechanisms in place diff --git a/DOCS/interface-changes.rst b/DOCS/interface-changes.rst index 7ffbbd60e0..d2e1ee4e7f 100644 --- a/DOCS/interface-changes.rst +++ b/DOCS/interface-changes.rst @@ -19,7 +19,26 @@ Interface changes :: - --- mpv 0.17.1 --- + --- mpv 0.18.1 --- + - deprecate --heartbeat-cmd + - remove --softvol=no capability: + - deprecate --softvol, it now does nothing + - --volume, --mute, and the corrsponding properties now always control + softvol, and behave as expected without surprises (e.g. you can set + them normally while no audio is initialized) + - rename --softvol-max to --volume-max (deprecated alias is added) + - the --volume-restore-data option and property are removed without + replacement. They were _always_ internal, and used for watch-later + resume/restore. Now --volume/--mute are saved directly instead. + - the previous point means resuming files with older watch-later configs + will print an error about missing --volume-restore-data (which you can + ignore), and will not restore the previous value + - as a consequence, volume controls will no longer control PulseAudio + per-application value, or use the system mixer's per-application + volume processing + - system or per-application volume can still be controlled with the + ao-volume and ao-mute properties (there are no command line options) + --- mpv 0.18.0 --- - now ab-loops are active even if one of the "ab-loop-a"/"-b" properties is unset ("no"), in which case the start of the file is used if the A loop point is unset, and the end of the file for an unset B loop point @@ -27,7 +46,7 @@ Interface changes (also needs --embeddedfonts=no) - add "hwdec-interop" and "hwdec-current" properties - deprecated "hwdec-active" and "hwdec-detected" properties (to be removed - in mpv 0.19.0) + in mpv 0.20.0) - choice option/property values that are "yes" or "no" will now be returned as booleans when using the mpv_node functions in the client API, the "native" property accessors in Lua, and the JSON API. They can be set as diff --git a/DOCS/man/input.rst b/DOCS/man/input.rst index d58f2dc4d5..9c4df6152b 100644 --- a/DOCS/man/input.rst +++ b/DOCS/man/input.rst @@ -459,6 +459,8 @@ Input Commands that are Possibly Subject to Change Remove all filters. Note that like the other sub-commands, this does not control automatically inserted filters. + The argument is always needed. E.g. in case of ``clr`` use ``vf clr ""``. + You can assign labels to filter by prefixing them with ``@name:`` (where ``name`` is a user-chosen arbitrary identifier). Labels can be used to refer to filters by name in all of the filter chain modification commands. @@ -561,29 +563,20 @@ Input Commands that are Possibly Subject to Change the resolution is reduced to that of the video's. You can read the ``osd-width`` and ``osd-height`` properties. At least with ``--vo-xv`` and anamorphic video (such as DVD), ``osd-par`` should be read as well, and the - overlay should be aspect-compensated. (Future directions: maybe mpv should - take care of some of these things automatically, but it's hard to tell - where to draw the line.) + overlay should be aspect-compensated. ``id`` is an integer between 0 and 63 identifying the overlay element. The ID can be used to add multiple overlay parts, update a part by using this command with an already existing ID, or to remove a part with ``overlay-remove``. Using a previously unused ID will add a new overlay, - while reusing an ID will update it. (Future directions: there should be - something to ensure different programs wanting to create overlays don't - conflict with each others, should that ever be needed.) + while reusing an ID will update it. ``x`` and ``y`` specify the position where the OSD should be displayed. ``file`` specifies the file the raw image data is read from. It can be either a numeric UNIX file descriptor prefixed with ``@`` (e.g. ``@4``), - or a filename. The file will be mapped into memory with ``mmap()``. Some VOs - will pass the mapped pointer directly to display APIs (e.g. opengl or - vdpau), so no actual copying is involved. Truncating the source file while - the overlay is active will crash the player. You shouldn't change the data - while the overlay is active, because the data is essentially accessed at - random points. Instead, call ``overlay-add`` again (preferably with a - different memory region to prevent tearing). + or a filename. The file will be mapped into memory with ``mmap()``, + copied, and unmapped before the command returns (changed in mpv 0.18.1). It is also possible to pass a raw memory address for use as bitmap memory by passing a memory address as integer prefixed with an ``&`` character. @@ -616,15 +609,14 @@ 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.) - .. admonition:: Warning + .. note:: - When updating the overlay, you should prepare a second shared memory - region (e.g. make use of the offset parameter) and add this as overlay, - instead of reusing the same memory every time. Otherwise, you might - get the equivalent of tearing, when your application and mpv write/read - the buffer at the same time. Also, keep in mind that mpv might access - an overlay's memory at random times whenever it feels the need to do - so, for example when redrawing the screen. + Before mpv 0.18.1, you had to do manual "double buffering" when updating + an overlay by replacing it with a different memory buffer. Since mpv + 0.18.1, the memory is simply copied and doesn't reference any of the + memory indicated by the command's arguments after the commend returns. + If you want to use this command before mpv 0.18.1, reads the old docs + to see how to handle this correctly. ``overlay-remove <id>`` Remove an overlay added with ``overlay-add`` and the same ID. Does nothing @@ -1242,29 +1234,31 @@ Property list See ``--hr-seek``. ``mixer-active`` - Return ``yes`` if the audio mixer is active, ``no`` otherwise. This has - implications for ``--softvol=no`` mode: if the mixer is inactive, changing - ``volume`` doesn't actually change anything on the system mixer. If the - ``--volume`` or ``--mute`` option are used, these might not be applied - properly until the mixer becomes active either. (The options, if set, will - just overwrite the mixer state at audio initialization.) - - While the behavior with ``mixer-active==yes`` is relatively well-defined, - the ``no`` case will provide possibly wrong or insignificant values. + Return ``yes`` if the audio mixer is active, ``no`` otherwise. - Note that an active mixer does not necessarily imply active audio output, - although this is implied in the current implementation. + 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). Also see ``mixer-active`` - property. + Current volume (see ``--volume`` for details). -``volume-max`` - Current maximum value the volume property can be set to. (This may depend - on the ``--softvol-max`` option.) +``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``). Also see ``mixer-active`` property. + 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 + control. What this option does depends on the API. For example, on ALSA + this usually changes system-wide audio, while with PulseAudio this controls + per-application volume. + +``ao-mute`` (RW) + Similar to ``ao-volume``, but controls the mute state. May be unimplemented + even if ``ao-volume`` works. ``audio-delay`` (RW) See ``--audio-delay``. @@ -1388,7 +1382,7 @@ Property list properties to see whether this was successful. Unlike in mpv 0.9.x and before, this does not return the currently active - hardware decoder. Since mpv 0.17.1, ``hwdec-current`` is available for + hardware decoder. Since mpv 0.18.0, ``hwdec-current`` is available for this purpose. ``hwdec-current`` @@ -1412,13 +1406,13 @@ Property list platform and VO. ``hwdec-active`` - Deprecated. To be removed in mpv 0.19.0. Use ``hwdec-current`` instead. + 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.19.0. + 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 @@ -2134,7 +2128,7 @@ Property list (Note that if an option is marked as file-local, even ``options/`` will access the local value, and the ``old`` value, which will be restored on - end of playback, can not be read or written until end of playback.) + end of playback, cannot be read or written until end of playback.) ``option-info/<name>`` Additional per-option information. diff --git a/DOCS/man/lua.rst b/DOCS/man/lua.rst index b0d66c1760..99ff6ffce9 100644 --- a/DOCS/man/lua.rst +++ b/DOCS/man/lua.rst @@ -175,7 +175,7 @@ The ``mp`` module is preloaded, although it can be loaded manually with Similar to ``mp.set_property``, but set the given property using its native type. - Since there are several data types which can not represented natively in + Since there are several data types which cannot represented natively in Lua, this might not always work as expected. For example, while the Lua wrapper can do some guesswork to decide whether a Lua table is an array or a map, this would fail with empty tables. Also, there are not many diff --git a/DOCS/man/options.rst b/DOCS/man/options.rst index a42d87912b..f9c32e5a9d 100644 --- a/DOCS/man/options.rst +++ b/DOCS/man/options.rst @@ -638,15 +638,15 @@ Video In some cases, RGB conversion is forced, which means the RGB conversion is performed by the hardware decoding API, instead of the OpenGL code used by ``--vo=opengl``. This means certain obscure colorspaces may - not display correctly, and not certain filtering (such as debanding) - can not be applied in an ideal way. + not display correctly, not certain filtering (such as debanding) + cannot be applied in an ideal way. ``vdpau`` is usually safe. If deinterlacing enabled (or the ``vdpaupp`` video filter is active in general), it forces RGB conversion. The latter currently does not treat certain colorspaces like BT.2020 correctly - (which is mostly a mpv-specific restriction). If the ``vdpauprb`` - retrieves image data without RGB conversion, but does not work with - postprocessing. + (which is mostly a mpv-specific restriction). The ``vdpauprb`` video + filter retrieves image data without RGB conversion and is safe (but + precludes use of vdpau postprocessing). ``vaapi`` is safe if the ``vaapi-egl`` backend is indicated in the logs. If ``vaapi-glx`` is indicated, and the video colorspace is either BT.601 @@ -1072,14 +1072,10 @@ Audio ``--volume=<value>`` Set the startup volume. 0 means silence, 100 means no volume reduction or - amplification. A value of -1 (the default) will not change the volume. See - also ``--softvol``. + amplification. Negative values can be passed for compatibility, but are + treated as 0. - .. note:: - - This was changed after the mpv 0.9 release. Before that, 100 actually - meant maximum volume. At the same time, the volume scale was made cubic, - so the old values won't match up with the new ones anyway. + Since mpv 0.18.1, this always controls the internal mixer (aka "softvol"). ``--audio-delay=<sec>`` Audio delay in seconds (positive or negative float value). Positive values @@ -1094,20 +1090,17 @@ Audio See also: ``--volume``. -``--softvol=<mode>`` - Control whether to use the volume controls of the audio output driver or - the internal mpv volume filter. +``--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. - :no: prefer audio driver controls, use the volume filter only if - absolutely needed - :yes: always use the volume filter - :auto: prefer the volume filter if the audio driver uses the system mixer - (default) + The current behavior is as if this option was set to ``yes``. The other + behaviors are not available anymore, although ``auto`` almost matches + current behavior in most cases. - The intention of ``auto`` is to avoid changing system mixer settings from - within mpv with default settings. mpv is a video player, not a mixer panel. - On the other hand, mixer controls are enabled for sound servers like - PulseAudio, which provide per-application volume. + 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 @@ -1264,10 +1257,12 @@ Audio their start timestamps differ, and then video timing is gradually adjusted if necessary to reach correct synchronization later. -``--softvol-max=<100.0-1000.0>`` +``--volume-max=<100.0-1000.0>``, ``--softvol-max=<...>`` 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. + ``--softvol-max`` is a deprecated alias and should not be used. + ``--audio-file-auto=<no|exact|fuzzy|all>``, ``--no-audio-file-auto`` Load additional audio files matching the video filename. The parameter specifies how external audio files are matched. ``exact`` is enabled by @@ -1276,7 +1271,7 @@ Audio :no: Don't automatically load external audio files. :exact: Load the media filename with audio file extension (default). :fuzzy: Load all audio files containing media filename. - :all: Load all aufio files in the current and ``--audio-file-paths`` + :all: Load all audio files in the current and ``--audio-file-paths`` directories. ``--audio-file-paths=<path1:path2:...>`` @@ -1320,7 +1315,7 @@ Subtitles .. note:: Changing styling and position does not work with all subtitles. Image-based - subtitles (DVD, Bluray/PGS, DVB) can not changed for fundamental reasons. + subtitles (DVD, Bluray/PGS, DVB) cannot changed for fundamental reasons. Subtitles in ASS format are normally not changed intentionally, but overriding them can be controlled with ``--ass-style-override``. @@ -2019,6 +2014,14 @@ Window be the default behavior. Currently only affects X11 VOs. ``--heartbeat-cmd=<command>`` + + .. warning:: + + This option is redundant with Lua scripting. Further, it shouldn't be + needed for disabling screensaver anyway, since mpv will call + ``xdg-screensaver`` when using X11 backend. As a consequence this + option has been deprecated with no direct replacement. + Command that is executed every 30 seconds during playback via *system()* - i.e. using the shell. The time between the commands can be customized with the ``--heartbeat-interval`` option. The command is not run while playback @@ -2438,7 +2441,7 @@ Demuxer stop reading additional packets as soon as one of the limits is reached. (The limits still can be slightly overstepped due to technical reasons.) - Set these limits highher if you get a packet queue overflow warning, and + Set these limits higher if you get a packet queue overflow warning, and you think normal playback would be possible with a larger packet queue. See ``--list-options`` for defaults and value range. @@ -2463,7 +2466,7 @@ Demuxer ``--force-seekable=<yes|no>`` If the player thinks that the media is not seekable (e.g. playing from a - pipe, or it's a http stream with a server that doesn't support range + pipe, or it's an http stream with a server that doesn't support range requests), seeking will be disabled. This option can forcibly enable it. For seeks within the cache, there's a good chance of success. @@ -3290,7 +3293,7 @@ Cache With ``auto``, the cache will usually be enabled for network streams, using the size set by ``--cache-default``. With ``yes``, the cache will always be enabled with the size set by ``--cache-default`` (unless the - stream can not be cached, or ``--cache-default`` disables caching). + stream cannot be cached, or ``--cache-default`` disables caching). May be useful when playing files from slow media, but can also have negative effects, especially with file formats that require a lot of @@ -3685,7 +3688,7 @@ Miscellaneous video or audio outputs are not possible, but you can use filters to merge them into one. - The complex filter can not be changed yet during playback. It's also not + The complex filter cannot be changed yet during playback. It's also not possible to change the tracks connected to the filter at runtime. Other tracks, as long as they're not connected to the filter, and the corresponding output is not connected to the filter, can still be freely diff --git a/DOCS/man/vf.rst b/DOCS/man/vf.rst index b4e4438f78..6a5c44f1cc 100644 --- a/DOCS/man/vf.rst +++ b/DOCS/man/vf.rst @@ -214,7 +214,7 @@ Available filters are: Format name, e.g. rgb15, bgr24, 420p, etc. (default: don't change). ``<outfmt>`` Format name that should be substituted for the output. If they do not - have the same bytes per pixel and chroma subsamplimg, it will fail. + have the same bytes per pixel and chroma subsampling, it will fail. ``<colormatrix>`` Controls the YUV to RGB color space conversion when playing video. There are various standards. Normally, BT.601 should be used for SD video, and @@ -288,6 +288,8 @@ Available filters are: :adobe: Adobe RGB (1998) :prophoto: ProPhoto RGB (ROMM) :cie1931: CIE 1931 RGB + :dci-p3: DCI-P3 (Digital Cinema) + :v-gamut: Panasonic V-Gamut primaries ``<gamma>`` Gamma function the source file was encoded with. Normally this should be set @@ -311,6 +313,8 @@ Available filters are: :gamma2.8: Pure power curve (gamma 2.8) :prophoto: ProPhoto RGB (ROMM) curve :st2084: SMPTE ST2084 (HDR) curve + :std-b67: ARIB STD-B67 (Hybrid Log-gamma) curve + :v-log: Panasonic V-Log transfer curve ``<peak>`` Reference peak illumination for the video file. This is mostly diff --git a/DOCS/man/vo.rst b/DOCS/man/vo.rst index bdc317fc8f..b80244ca6c 100644 --- a/DOCS/man/vo.rst +++ b/DOCS/man/vo.rst @@ -465,7 +465,7 @@ Available video output drivers are: 8 Dither to 8 bit output. - Note that the depth of the connected video display device can not be + 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 ``opengl``'s dithering and leads to ugly output. @@ -629,6 +629,9 @@ Available video output drivers are: 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:: @@ -979,6 +982,8 @@ Available video output drivers are: CIE 1931 RGB (not to be confused with CIE XYZ) dci-p3 DCI-P3 (Digital Cinema Colorspace), SMPTE RP431-2 + v-gamut + Panasonic V-Gamut (VARICAM) primaries ``target-trc=<value>`` Specifies the transfer characteristics (gamma) of the display. Video @@ -1003,6 +1008,16 @@ Available video output drivers are: ProPhoto RGB (ROMM) st2084 SMPTE ST2084 (HDR) curve, PQ OETF + std-b67 + ARIB STD-B67 (Hybrid Log-gamma) curve, also known as BBC/NHK HDR + v-log + Panasonic V-Log (VARICAM) curve + + NOTE: When using HDR output formats, mpv will encode to the specified + curve but it will not set any HDMI flags or other signalling that + might be required for the target device to correctly display the + HDR signal. The user should independently guarantee this before + using these signal formats for display. ``target-brightness=<1..100000>`` Specifies the display's approximate brightness in cd/m^2. When playing diff --git a/DOCS/tech-overview.txt b/DOCS/tech-overview.txt index 914b2222b4..e53f00b7be 100644 --- a/DOCS/tech-overview.txt +++ b/DOCS/tech-overview.txt @@ -123,7 +123,7 @@ options/options.h, options/options.c parser-mpcmd.c, and uses the option table in options.c. input/input.c: - This translates keyboard input comming from VOs and other sources (such + This translates keyboard input coming from VOs and other sources (such as remote control devices like Apple IR or client API commands) to the key bindings listed in the user's (or the builtin) input.conf and turns them into items of type struct mp_cmd. These commands are queued, and read |