Introduction============ mpv provides access to its internals via the following means: - options- commands- properties- events- hooks The sum of these mechanisms is sometimes called command interface. All of these are important for interfacing both with end users and API users(which include Lua scripts, libmpv, and the JSON IPC). As such, they constitutea 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. Interface changes================= :: --- 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. - change `--subs-with-matching-audio` default from `no` to `yes` - change `--subs-fallback` default from `no` to `default` - add the `--hdr-peak-percentile` option - include `--hdr-peak-percentile` in the `gpu-hq` profile - change `--audiotrack-pcm-float` default from `no` to `yes` - add video-params/aspect-name - change type of `--sub-pos` to float - The remaining time printed in the terminal is now adjusted for speed by default. You can disable this with `--no-term-remaining-playtime`. - add `playlist-path` and `playlist/N/playlist-path` properties - add `--x11-wid-title` option - add `--libplacebo-opts` option - add `--audio-file-exts`, `--cover-art-auto-exts`, and `--sub-auto-exts` - change `slang` default back to NULL - remove special handling of the `auto` value from `--alang/slang/vlang` options - add `--subs-match-os-language` as a replacement for `--slang=auto` - add `always` option to `--subs-fallback-forced` - remove `auto` choice from `--sub-forced-only` - remove `auto-forced-only` property - rename `--sub-forced-only` to `--sub-forced-events-only` - remove `sub-forced-only-cur` property (`--sub-forced-events-only` is a replacement) - add `hdr-metadata` property - change `--directory-mode` default to `lazy` - remove deprecated `video-aspect` property - add `--video-crop` - add `video-params/crop-[w,h,x,y]` - remove `--tone-mapping-mode` - change `--subs-fallback-forced` so that it works alongside `--slang` - add `--icc-3dlut-size=auto` and make it the default - add `--scale=ewa_lanczos4sharpest` - remove `--scale-wblur`, `--cscale-wblur`, `--dscale-wblur`, `--tscale-wblur` - remove `bcspline` filter (`bicubic` is now the same as `bcspline`) - rename `--cache-dir` and `--cache-unlink-files` to `--demuxer-cache-dir` and `--demuxer-cache-unlink-files` - enable `--correct-downscaling`, `--linear-downscaling`, `--sigmoid-upscaling` - `--cscale` defaults to `--scale` if not defined - change `--tscale` default to `oversample` - change `--dither-depth` to `auto` - deprecate `--profile=gpu-hq`, add `--profile=<fast|high-quality>` - change `--dscale` default to `hermite` - update defaults to `--hdr-peak-decay-rate=20`, `--hdr-scene-threshold-low=1.0`, `--hdr-scene-threshold-high=3.0` - update defaults to `--deband-threshold=48`, `--deband-grain=32` - add `--directory-mode=auto` and make it the default - remove deprecated `--profile=opengl-hq` - remove several legacy fallbacks for old deprecated options (now they will just error out like normal) - remove deprecated `drop-frame-count` and `vo-drop-frame-count` property aliases - remove the ability to write to the `display-fps` property (use `override-display-fps` instead) - writing the current value to playlist-pos will no longer restart playback (use `playlist-play-index` instead) - remove deprecated `--oaoffset`, `--oafirst`, `--ovoffset`, `--ovfirst`, `--demuxer-force-retry-on-eof`, `--fit-border` options - remove deprecated `--record-file` option - remove deprecated `--vf-defaults` and `--af-defaults` options - `--drm-connector` no longer allows selecting the card number (use `--drm-device` instead) - add `--title-bar` option - add `--window-corners` option - rename `--cdrom-device` to `--cdda-device` - remove `--scale-cutoff`, `--cscale-cutoff`, `--dscale-cutoff`, `--tscale-cutoff` - remove `--scaler-lut-size` - deprecate shared-script-properties (user-data is a replacement) - add `--backdrop-type` option - add `--window-affinity` option --- mpv 0.36.0 --- - add `--target-contrast` - Target luminance value is now also applied when ICC profile is used. `--icc-use-luma` has been added to use ICC profile luminance value. If target luminance and ICC luminance is not used, old behavior apply, defaulting to 203 nits. (Only applies for `--vo=gpu-next`) - `playlist/N/title` gets set upon opening the file if it wasn't already set and a title is available. - add the `--vo=kitty` video output driver, as well as the options `--vo-kitty-cols`, `--vo-kitty-rows`, `--vo-kitty-width`, `--vo-kitty-height`, `--vo-kitty-left`, `--vo-kitty-top`, `--vo-kitty-config-clear`, `--vo-kitty-alt-screen` and `--vo-kitty-use-shm` - add `--force-render` - add `--vo-sixel-config-clear`, `--vo-sixel-alt-screen` and `--vo-sixel-buffered` - add `--wayland-content-type` - deprecate `--vo-sixel-exit-clear` and alias it to `--vo-sixel-alt-screen` - deprecate `--drm-atomic` - add `--demuxer-hysteresis-secs` - add `--video-sync=display-tempo` - the `start` option is no longer unconditionally written by watch-later. It is still written by default but you may need to explicitly add `start` depending on how you have `--watch-later-options` configured. - add `--vd-lavc-dr=auto` and make it the default - add support for the fractional scale protocol in wayland - in wayland, hidpi window scaling now scales the window by the compositor's dpi scale factor by default (can be disabled with --no-hidpi-window-scale if fractional scaling support exists). - change --screenshot-tag-colorspace default value from `no` to `yes` - undeprecate vf_sub - add `--tone-mapping=st2094-40` and `--tone-mapping=st2094-10` - change `--screenshot-jxl-effort` default from `3` to `4`. - add `--tone-mapping-visualize` - change type of `--brightness`, `--saturation`, `--contrast`, `--hue` and `--gamma` to float. - add `platform` property - add `--auto-window-resize` - `--save-position-on-quit` and its associated commands now store state files in the XDG_STATE_HOME directory by default. This only has an effect on linux/bsd systems. - mpv now implictly saves cache files in XDG_CACHE_HOME by default. This only has an effect if the user enables options that would lead to cache being stored and only makes a difference on linux/bsd systems. - `--cache-on-disk` no longer requires explictly setting the `--cache-dir` option - add `--icc-cache` and `--gpu-shader-cache` options to control whether or not to save cache files for these features; explictly setting `--icc-cache-dir` and `--gpu-shader-cache` is no longer required - remove the `--tone-mapping-crosstalk` option - add `--gamut-mapping-mode=perceptual|relative|saturation|absolute|linear` - add `--corner-rounding` option - change `--subs-with-matching-audio` default from `yes` to `no` - change `--slang` default from blank to `auto` - add `--input-cursor-passthrough` option to allow pointer events to completely passthrough the mpv window - icc and gpu-shader cache are now saved by default (use --no-icc-shader-cache and --no-gpu-shader-cache to disable) - add `--directory-mode=recursive|lazy|ignore` - `--hwdec=yes` is now mapped to `auto-safe` rather than `auto` (also used by ctrl+h keybind) - add `--hdr-contrast-recovery` and `--hdr-contrast-smoothness` - include `--hdr-contrast-recovery` in the `gpu-hq` profile --- mpv 0.35.0 --- - add the `--vo=gpu-next` video output driver, as well as the options `--allow-delayed-peak-detect`, `--builtin-scalers`, `--interpolation-preserve` `--lut`, `--lut-type`, `--image-lut`, `--image-lut-type` and `--target-lut` along with it. - add `--target-colorspace-hint` - add `--tone-mapping-crosstalk` - add `--tone-mapping` options `auto`, `spline` and `bt.2446a` - add `--inverse-tone-mapping` - add `--gamut-mapping-mode`, replacing `--gamut-clipping` and `--gamut-warning` - add `--tone-mapping-mode`, replacing `--tone-mapping-desaturate` and `--tone-mapping-desaturate-exponent`. - add `dolbyvision` sub-parameter to `format` video filter - `--sub-visibility` no longer has any effect on secondary subtitles - add `film-grain` sub-parameter to `format` video filter - add experimental `--vo=dmabuf-wayland` video output driver - add `--x11-present` for controlling whether to use xorg's present extension - add `engine` option to the `rubberband` audio filter to support the new engine introduced in rubberband 3.0.0. Defaults to `finer` (new engine). - add `--wayland-configure-bounds` option - deprecate `--gamma-factor` - deprecate `--gamma-auto` - remove `--vulkan-disable-events` - add `--glsl-shader-opts` --- mpv 0.34.0 --- - deprecate selecting by card number with `--drm-connector`, add `--drm-device` which can be used instead - add `--screen-name` and `--fs-screen-name` flags to allow selecting the screen by its name instead of the index - add `--macos-geometry-calculation` to change the rectangle used for screen position and size calculation. the old behavior used the whole screen, which didn't take the menu bar and Dock into account. The new default behaviour includes both. To revert to the old behavior set this to `whole`. - add an additional optional `albumart` argument to the `video-add` command, which tells mpv to load the given video as album art. - undeprecate `--cache-secs` option - remove `--icc-contrast` and introduce `--icc-force-contrast`. The latter defaults to the equivalent of the old `--icc-contrast=inf`, and can instead be used to specifically set the contrast to any value. - add a `--watch-later-options` option to allow configuring which options quit-watch-later saves - make `current-window-scale` writeable and use it in the default input.conf - add `--input-builtin-bindings` flag to control loading of built-in key bindings during start-up (default: yes). - add ``track-list/N/image`` sub-property - remove `--opengl-restrict` option - js custom-init: use filename ~~/init.js instead of ~~/.init.js (dot) --- mpv 0.33.0 --- - add `--d3d11-exclusive-fs` flag to enable D3D11 exclusive fullscreen mode when the player enters fullscreen. - directories in ~/.mpv/scripts/ (or equivalent) now have special semantics (see mpv Lua scripting docs) - 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 - 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 libmpv API (mpv_hook_add(), mpv_hook_continue()), or the Lua scripting wrappers (mp.add_hook()). - improve how property change notifications are delivered on events and on hooks. In particular, a hook event is only returned to a client after all changes initiated before the hook point were delivered to the same client. In addition, it should no longer happen that events and property change notifications were interleaved in bad ways (it could happen that a property notification delivered after an event contained a value that was valid only before the event happened). - the playlist-pos and playlist-pos-1 properties now can return and accept -1, and are never unavailable. Out of range indexes are now accepted, but behave like writing -1. - the playlist-pos and playlist-pos-1 properties deprecate the current behavior when writing back the current value to the property: currently, this restarts playback, but in the future, it will do nothing. Using the "playlist-play-index" command is recommended instead. - add "playlist-play-index" command - add playlist-current-pos, playlist-playing-pos properties - Lua end-file events set the "error" field; this is deprecated; use the "file_error" instead for this specific event. Scripts relying on the "error" field for end-file will silently break at some point in the future. - remove deprecated --input-file option, add --input-ipc-client, which is vaguely a replacement of the removed option, but not the same - change another detail for track selection options (see --aid manpage entry) - reading loop-file property as native property or mpv_node will now return "inf" instead of boolean true (also affects loop option) - remove some --vo-direct3d-... options (it got dumbed down; use --vo=gpu) - remove video-params/plane-depth property (was too vaguely defined) - remove --video-sync-adrop-size option (implementation was changed, no replacement for what this option did) - undeprecate --video-sync=display-adrop - deprecate legacy auto profiles (profiles starting with "extension." and "protocol."). Use conditional auto profiles instead. - the "subprocess" command does not connect spawned processes' stdin to mpv's stdin anymore. Instead, stdin is connected to /dev/null by default. To get the old behavior, set the "passthrough_stdin" argument to true. - key/value list options do not accept ":" as item separator anymore, only ",". This means ":" is always considered part of the value. - remove deprecated --vo-vdpau-deint option - add `delete-watch-later-config` command to complement `write-watch-later-config` --- mpv 0.32.0 --- - change behavior when using legacy option syntax with options that start with two dashes (``--`` instead of a ``-``). Now, using the recommended syntax is required for options starting with ``--``, which means an option value must be strictly passed after a ``=``, instead of as separate argument. For example, ``--log-file f.txt`` was previously accepted and behaved like ``--log-file=f.txt``, but now causes an error. Use of legacy syntax that is still supported now prints a deprecation warning. --- mpv 0.31.0 --- - add `--resume-playback-check-mtime` to check consistent mtime when restoring playback state. - add `--d3d11-output-csp` to enable explicit selection of a D3D11 swap chain color space. - the --sws- options and similar now affect vo_image and screenshot conversion (does not matter as much for vo_gpu, which does most of this with shaders) - add a builtin "sw-fast" profile, which restores performance settings for software video conversion. These were switched to higher quality since mpv 0.30.0 (related to the previous changelog entry). This affects video outputs like vo_x11 and vo_drm, and screenshots, but not much else. - deprecate --input-file (there are no plans to remove this short-term, but it will probably eventually go away <- that was a lie) - deprecate --video-sync=display-adrop (might be removed if it's in the way; undeprecated or readded if it's not too much of a problem) - deprecate all input section commands (these will be changed/removed, as soon as mpv internals do not require them anymore) - remove deprecated --playlist-pos alias (use --playlist-start) - deprecate --display-fps, introduce --override-display-fps. The display-fps property now is unavailable if no VO exists (or the VO did not return a display FPS), instead of returning the option value in this case. The property will keep existing, but writing to it is deprecated. - the vf/af properties now do not reject the set value anymore, even if filter chain initialization fails. Instead, the vf/af options are always set to the user's value, even if it does not reflect the "runtime" vf/af chain. - the vid/aid/sid/secondary-sid properties (and their aliases: "audio", "video", "sub") will now allow setting any track ID; before this change, only IDs of actually existing tracks could be set (the restriction was active the MPV_EVENT_FILE_LOADED/"file-loaded" event was sent). Setting an ID for which no track exists is equivalent to disabling it. Note that setting the properties to non-existing tracks may report it as selected track for a small time window, until it's forced back to "no". The exact details how this is handled may change in the future. - remove old Apple Remote support, including --input-appleremote - add MediaPlayer support and remove the old Media Key event tap on macOS. this possibly also re-adds the Apple Remote support - the "edition" property now strictly returns the value of the option, instead of the runtime value. The new "current-edition" property needs to be queried to read the runtime-chosen edition. This is a breaking change for any users which expected "edition" to return the runtime-chosen edition at default settings (--edition=auto). - the "window-scale" property now strictly returns the value of the option, instead of the actual size of the window. The new "current-window-scale" property needs to be queried to read the value as indicated by the current window size. This is a breaking change. - explicitly deprecate passing more than 1 item to "-add" suffix in key/value options (for example --script-opts-add). This was actually always deprecated, like with other list options, but the option parser did not print a warning in this particular case. - deprecate -del for list options (use -remove instead, which is by content instead of by integer index) - if `--fs` is used but `--fs-screen` is not set, mpv will now use `--screen` instead. - change the default of --hwdec to "no" on RPI. The default used to be "mmal" specifically if 'Raspberry Pi support' was enabled at configure time (equivalent to --enable-rpi). Use --hwdec=mmal to get the old behavior. --- mpv 0.30.0 --- - add `--d3d11-output-format` to enable explicit selection of a D3D11 swap chain format. - rewrite DVB channel switching to use an integer value `--dvbin-channel-switch-offset` for switching instead of the old stream controls which are now gone. Cycling this property up or down will change the offset to the channel which was initially tuned to. Example for `input.conf`: `H cycle dvbin-channel-switch-offset up`, `K cycle dvbin-channel-switch-offset down`. - adapt `stream_dvb` to support writing to `dvbin-prog` at runtime and also to consistently use dvbin-configuration over URI parameters when provided - add `--d3d11-adapter` to enable explicit selection of a D3D11 rendering adapter by name. - rename `--drm-osd-plane-id` to `--drm-draw-plane`, `--drm-video-plane-id` to `--drm-drmprime-video-plane` and `--drm-osd-size` to `--drm-draw-surface-size` to better reflect what the options actually control, that the values they accept aren't actually internal DRM ID's (like with similar options in ffmpeg's KMS support), and that the video plane is only used when the drmprime overlay hwdec interop is active, with the video being drawn to the draw plane otherwise. - in addition to the above, the `--drm-draw-plane` and `--drm-drmprime-video-plane` options now accept either an integer index, or the values primary or overlay. `--drm-draw-plane` now defaults to primary and `--drm-drmprime-video-plane` defaults to overlay. This should be similar to previous behavior on most drivers due to how planes are usually sorted. - rename --opensles-frames-per-buffer to --opensles-frames-per-enqueue to better reflect its purpose. In the past it overrides the buffer size the AO requests (but not the default/value of the generic --audio-buffer option). Now it only guarantees that the soft buffer size will not be smaller than itself while setting the size per Enqueue. - add --opensles-buffer-size-in-ms, allowing user to tune the soft buffer size. It overrides the --audio-buffer option unless it's set to 0 (with the default being 250). - remove `--linear-scaling`, replaced by `--linear-upscaling` and `--linear-downscaling`. This means that `--sigmoid-upscaling` no longer implies linear light downscaling as well, which was confusing. - the built-in `gpu-hq` profile now includes` --linear-downscaling`. - support for `--spirv-compiler=nvidia` has been removed, leaving `shaderc` as the only option. The `--spirv-compiler` option itself has been marked as deprecated, and may be removed in the future. - split up `--tone-mapping-desaturate`` into strength + exponent, instead of only using a single value (which previously just controlled the exponent). The strength now linearly blends between the linear and nonlinear tone mapped versions of a color. - add --hdr-peak-decay-rate and --hdr-scene-threshold-low/high - add --tone-mapping-max-boost - ipc: require that "request_id" fields are integers. Other types are still accepted for compatibility, but this will stop in the future. Also, if no request_id is provided, 0 will be assumed. - mpv_command_node() and mp.command_native() now support named arguments (see manpage). If you want to use them, use a new version of the manpage as reference, which lists the definitive names. - edition and disc title switching will now fully reload playback (may have consequences for scripts, client API, or when using file-local options) - with the removal of the stream cache, the following properties and options were dropped: `cache`, `cache-size`, `cache-free`, `cache-used`, `--cache-default`, `--cache-initial`, `--cache-seek-min`, `--cache-backbuffer`, `--cache-file`, `--cache-file-size` - the --cache option does not take a number value anymore - remove async playback abort hack. This may make it impossible to abort playback if --demuxer-thread=no is forced. - remove `--macos-title-bar-style`, replaced by `--macos-title-bar-material` and `--macos-title-bar-appearance`. - The default for `--vulkan-async-compute` has changed to `yes` from `no` with the move to libplacebo as the back-end for vulkan rendering. - Remove "disc-titles", "disc-title", "disc-title-list", and "angle" properties. dvd:// does not support title ranges anymore. - Remove all "tv-..." options and properties, along with the classic Linux analog TV support. - remove "program" property (no replacement) - always prefer EGL over GLX, which helps with AMD/vaapi, but will break vdpau with --vo=gpu - use --gpu-context=x11 to be able to use vdpau. This does not affect --vo=vdpau or --hwdec=vdpau-copy. - remove deprecated --chapter option - deprecate --record-file - add `--demuxer-cue-codepage` - add ``track-list/N/demux-bitrate``, ``track-list/N/demux-rotation`` and ``track-list/N/demux-par`` property - Deprecate ``--video-aspect`` and add ``--video-aspect-override`` to replace it. (The `video-aspect` option remains unchanged.) --- mpv 0.29.0 --- - drop --opensles-sample-rate, as --audio-samplerate should be used if desired - drop deprecated --videotoolbox-format, --ff-aid, --ff-vid, --ff-sid, --ad-spdif-dtshd, --softvol options - fix --external-files: strictly never select any tracks from them, unless explicitly selected (this may or may not be expected) - --ytdl is now always enabled, even for libmpv - add a number of --audio-resample-* options, which should from now on be used instead of --af-defaults=lavrresample:... - deprecate --vf-defaults and --af-defaults. These didn't work with the lavfi bridge, so they have very little use left. The only potential use is with af_lavrresample (going to be deprecated, --audio-resample-... set its defaults), and various hw deinterlacing filters (like vf_vavpp), for which you will have to stop using --deinterlace=yes, and instead use the vf toggle commands and the filter enable/disable flag to customize it. - deprecate --af=lavrresample. Use the ``--audio-resample-...`` options to customize resampling, or the libavfilter ``--af=aresample`` filter. - add --osd-on-seek - remove outfmt sub-parameter from "format" video filter (no replacement) - some behavior changes in the video filter chain, including: - before, using an incompatible filter with hwdec would disable hwdec; now it disables the filter at runtime instead - inserting an incompatible filter with hwdec at runtime would refuse to insert the filter; now it will add it successfully, but disables the filter slightly later - some behavior changes in the audio filter chain, including: - a manually inserted lavrresample filter is not necessarily used for sample format conversion anymore, so it's pretty useless - changing playback speed will not respect --af-defaults anymore - having libavfilter based filters after the scaletempo or rubberband filters is not supported anymore, and may desync if playback speed is changed (libavfilter does not support the metadata for playback speed) - the lavcac3enc filter does not auto detach itself anymore; instead it passes through the data after converting it to the sample rate and channel configuration the ac3 encoder expects; also, if the audio format changes midstream in a way that causes the filter to switch between PCM and AC3 output, the audio output won't be reconfigured, and audio playback will fail due to libswresample being unable to convert between PCM and AC3 (Note: the responsible developer didn't give a shit. Later changes might have improved or worsened this.) - inserting a filter that changes the output sample format will not reconfigure the AO - you need to run an additional "ao-reload" command to force this if you want that - using "strong" gapless audio (--gapless-audio=yes) can fail if the audio formats are not convertible (such as switching between PCM and AC3 passthrough) - if filters do not pass through PTS values correctly, A/V sync can result over time. Some libavfilter filters are known to be affected by this, such as af_loudnorm, which can desync over time, depending on how the audio track was muxed (af_lavfi's fix-pts suboption can help). - remove out-format sub-parameter from "format" audio filter (no replacement) - --lavfi-complex now requires uniquely named filter pads. In addition, unconnected filter pads are not allowed anymore (that means every filter pad must be connected either to another filter, or to a video/audio track or video/audio output). If they are disconnected at runtime, the stream will probably stall. - rename --vo=opengl-cb to --vo=libmpv (goes in hand with the opengl-cb API deprecation, see client-api-changes.rst) - deprecate the OpenGL cocoa backend, option choice --gpu-context=cocoa when used with --gpu-api=opengl (use --vo=libmpv) - make --deinterlace=yes always deinterlace, instead of trying to check certain unreliable video metadata. Also flip the defaults of all builtin HW deinterlace filters to always deinterlace. - change vf_vavpp default to use the best deinterlace algorithm by default - remove a compatibility hack that allowed CLI aliases to be set as property (such as "sub-file"), deprecated in mpv 0.26.0 - deprecate the old command based hook API, and introduce a proper C API (the high level Lua API for this does not change) - rename the the lua-settings/ config directory to script-opts/ - the way the player waits for scripts getting loaded changes slightly. Now scripts are loaded in parallel, and block the player from continuing playback only in the player initialization phase. It could change again in the future. (This kind of waiting was always a feature to prevent that playback is started while scripts are only half-loaded.) - deprecate --ovoffset, --oaoffset, --ovfirst, --oafirst - remove the following encoding options: --ocopyts (now the default, old timestamp handling is gone), --oneverdrop (now default), --oharddup (you need to use --vf=fps=VALUE), --ofps, --oautofps, --omaxfps - remove --video-stereo-mode. This option was broken out of laziness, and nobody wants to fix it. Automatic 3D down-conversion to 2D is also broken, although you can just insert the stereo3d filter manually. The obscurity of 3D content doesn't justify such an option anyway. - change cycle-values command to use the current value, instead of an internal counter that remembered the current position. - remove deprecated ao/vo auto profiles. Consider using scripts like auto-profiles.lua instead. - --[c]scale-[w]param[1|2] and --tone-mapping-param now accept "default", and if set to that value, reading them as property will also return "default", instead of float nan as in previous versionsLines 1–500 of 958. Load more
Introduction ============ mpv provides access to its internals via the following means: - options - commands - properties - events - hooks The sum of these mechanisms is sometimes called command interface. All of these are important for interfacing both with end users and API users (which include Lua scripts, libmpv, and the JSON IPC). As such, they constitute 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. Interface changes ================= :: --- 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. - change `--subs-with-matching-audio` default from `no` to `yes` - change `--subs-fallback` default from `no` to `default` - add the `--hdr-peak-percentile` option - include `--hdr-peak-percentile` in the `gpu-hq` profile - change `--audiotrack-pcm-float` default from `no` to `yes` - add video-params/aspect-name - change type of `--sub-pos` to float - The remaining time printed in the terminal is now adjusted for speed by default. You can disable this with `--no-term-remaining-playtime`. - add `playlist-path` and `playlist/N/playlist-path` properties - add `--x11-wid-title` option - add `--libplacebo-opts` option - add `--audio-file-exts`, `--cover-art-auto-exts`, and `--sub-auto-exts` - change `slang` default back to NULL - remove special handling of the `auto` value from `--alang/slang/vlang` options - add `--subs-match-os-language` as a replacement for `--slang=auto` - add `always` option to `--subs-fallback-forced` - remove `auto` choice from `--sub-forced-only` - remove `auto-forced-only` property - rename `--sub-forced-only` to `--sub-forced-events-only` - remove `sub-forced-only-cur` property (`--sub-forced-events-only` is a replacement) - add `hdr-metadata` property - change `--directory-mode` default to `lazy` - remove deprecated `video-aspect` property - add `--video-crop` - add `video-params/crop-[w,h,x,y]` - remove `--tone-mapping-mode` - change `--subs-fallback-forced` so that it works alongside `--slang` - add `--icc-3dlut-size=auto` and make it the default - add `--scale=ewa_lanczos4sharpest` - remove `--scale-wblur`, `--cscale-wblur`, `--dscale-wblur`, `--tscale-wblur` - remove `bcspline` filter (`bicubic` is now the same as `bcspline`) - rename `--cache-dir` and `--cache-unlink-files` to `--demuxer-cache-dir` and `--demuxer-cache-unlink-files` - enable `--correct-downscaling`, `--linear-downscaling`, `--sigmoid-upscaling` - `--cscale` defaults to `--scale` if not defined - change `--tscale` default to `oversample` - change `--dither-depth` to `auto` - deprecate `--profile=gpu-hq`, add `--profile=<fast|high-quality>` - change `--dscale` default to `hermite` - update defaults to `--hdr-peak-decay-rate=20`, `--hdr-scene-threshold-low=1.0`, `--hdr-scene-threshold-high=3.0` - update defaults to `--deband-threshold=48`, `--deband-grain=32` - add `--directory-mode=auto` and make it the default - remove deprecated `--profile=opengl-hq` - remove several legacy fallbacks for old deprecated options (now they will just error out like normal) - remove deprecated `drop-frame-count` and `vo-drop-frame-count` property aliases - remove the ability to write to the `display-fps` property (use `override-display-fps` instead) - writing the current value to playlist-pos will no longer restart playback (use `playlist-play-index` instead) - remove deprecated `--oaoffset`, `--oafirst`, `--ovoffset`, `--ovfirst`, `--demuxer-force-retry-on-eof`, `--fit-border` options - remove deprecated `--record-file` option - remove deprecated `--vf-defaults` and `--af-defaults` options - `--drm-connector` no longer allows selecting the card number (use `--drm-device` instead) - add `--title-bar` option - add `--window-corners` option - rename `--cdrom-device` to `--cdda-device` - remove `--scale-cutoff`, `--cscale-cutoff`, `--dscale-cutoff`, `--tscale-cutoff` - remove `--scaler-lut-size` - deprecate shared-script-properties (user-data is a replacement) - add `--backdrop-type` option - add `--window-affinity` option --- mpv 0.36.0 --- - add `--target-contrast` - Target luminance value is now also applied when ICC profile is used. `--icc-use-luma` has been added to use ICC profile luminance value. If target luminance and ICC luminance is not used, old behavior apply, defaulting to 203 nits. (Only applies for `--vo=gpu-next`) - `playlist/N/title` gets set upon opening the file if it wasn't already set and a title is available. - add the `--vo=kitty` video output driver, as well as the options `--vo-kitty-cols`, `--vo-kitty-rows`, `--vo-kitty-width`, `--vo-kitty-height`, `--vo-kitty-left`, `--vo-kitty-top`, `--vo-kitty-config-clear`, `--vo-kitty-alt-screen` and `--vo-kitty-use-shm` - add `--force-render` - add `--vo-sixel-config-clear`, `--vo-sixel-alt-screen` and `--vo-sixel-buffered` - add `--wayland-content-type` - deprecate `--vo-sixel-exit-clear` and alias it to `--vo-sixel-alt-screen` - deprecate `--drm-atomic` - add `--demuxer-hysteresis-secs` - add `--video-sync=display-tempo` - the `start` option is no longer unconditionally written by watch-later. It is still written by default but you may need to explicitly add `start` depending on how you have `--watch-later-options` configured. - add `--vd-lavc-dr=auto` and make it the default - add support for the fractional scale protocol in wayland - in wayland, hidpi window scaling now scales the window by the compositor's dpi scale factor by default (can be disabled with --no-hidpi-window-scale if fractional scaling support exists). - change --screenshot-tag-colorspace default value from `no` to `yes` - undeprecate vf_sub - add `--tone-mapping=st2094-40` and `--tone-mapping=st2094-10` - change `--screenshot-jxl-effort` default from `3` to `4`. - add `--tone-mapping-visualize` - change type of `--brightness`, `--saturation`, `--contrast`, `--hue` and `--gamma` to float. - add `platform` property - add `--auto-window-resize` - `--save-position-on-quit` and its associated commands now store state files in the XDG_STATE_HOME directory by default. This only has an effect on linux/bsd systems. - mpv now implictly saves cache files in XDG_CACHE_HOME by default. This only has an effect if the user enables options that would lead to cache being stored and only makes a difference on linux/bsd systems. - `--cache-on-disk` no longer requires explictly setting the `--cache-dir` option - add `--icc-cache` and `--gpu-shader-cache` options to control whether or not to save cache files for these features; explictly setting `--icc-cache-dir` and `--gpu-shader-cache` is no longer required - remove the `--tone-mapping-crosstalk` option - add `--gamut-mapping-mode=perceptual|relative|saturation|absolute|linear` - add `--corner-rounding` option - change `--subs-with-matching-audio` default from `yes` to `no` - change `--slang` default from blank to `auto` - add `--input-cursor-passthrough` option to allow pointer events to completely passthrough the mpv window - icc and gpu-shader cache are now saved by default (use --no-icc-shader-cache and --no-gpu-shader-cache to disable) - add `--directory-mode=recursive|lazy|ignore` - `--hwdec=yes` is now mapped to `auto-safe` rather than `auto` (also used by ctrl+h keybind) - add `--hdr-contrast-recovery` and `--hdr-contrast-smoothness` - include `--hdr-contrast-recovery` in the `gpu-hq` profile --- mpv 0.35.0 --- - add the `--vo=gpu-next` video output driver, as well as the options `--allow-delayed-peak-detect`, `--builtin-scalers`, `--interpolation-preserve` `--lut`, `--lut-type`, `--image-lut`, `--image-lut-type` and `--target-lut` along with it. - add `--target-colorspace-hint` - add `--tone-mapping-crosstalk` - add `--tone-mapping` options `auto`, `spline` and `bt.2446a` - add `--inverse-tone-mapping` - add `--gamut-mapping-mode`, replacing `--gamut-clipping` and `--gamut-warning` - add `--tone-mapping-mode`, replacing `--tone-mapping-desaturate` and `--tone-mapping-desaturate-exponent`. - add `dolbyvision` sub-parameter to `format` video filter - `--sub-visibility` no longer has any effect on secondary subtitles - add `film-grain` sub-parameter to `format` video filter - add experimental `--vo=dmabuf-wayland` video output driver - add `--x11-present` for controlling whether to use xorg's present extension - add `engine` option to the `rubberband` audio filter to support the new engine introduced in rubberband 3.0.0. Defaults to `finer` (new engine). - add `--wayland-configure-bounds` option - deprecate `--gamma-factor` - deprecate `--gamma-auto` - remove `--vulkan-disable-events` - add `--glsl-shader-opts` --- mpv 0.34.0 --- - deprecate selecting by card number with `--drm-connector`, add `--drm-device` which can be used instead - add `--screen-name` and `--fs-screen-name` flags to allow selecting the screen by its name instead of the index - add `--macos-geometry-calculation` to change the rectangle used for screen position and size calculation. the old behavior used the whole screen, which didn't take the menu bar and Dock into account. The new default behaviour includes both. To revert to the old behavior set this to `whole`. - add an additional optional `albumart` argument to the `video-add` command, which tells mpv to load the given video as album art. - undeprecate `--cache-secs` option - remove `--icc-contrast` and introduce `--icc-force-contrast`. The latter defaults to the equivalent of the old `--icc-contrast=inf`, and can instead be used to specifically set the contrast to any value. - add a `--watch-later-options` option to allow configuring which options quit-watch-later saves - make `current-window-scale` writeable and use it in the default input.conf - add `--input-builtin-bindings` flag to control loading of built-in key bindings during start-up (default: yes). - add ``track-list/N/image`` sub-property - remove `--opengl-restrict` option - js custom-init: use filename ~~/init.js instead of ~~/.init.js (dot) --- mpv 0.33.0 --- - add `--d3d11-exclusive-fs` flag to enable D3D11 exclusive fullscreen mode when the player enters fullscreen. - directories in ~/.mpv/scripts/ (or equivalent) now have special semantics (see mpv Lua scripting docs) - 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 - 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 libmpv API (mpv_hook_add(), mpv_hook_continue()), or the Lua scripting wrappers (mp.add_hook()). - improve how property change notifications are delivered on events and on hooks. In particular, a hook event is only returned to a client after all changes initiated before the hook point were delivered to the same client. In addition, it should no longer happen that events and property change notifications were interleaved in bad ways (it could happen that a property notification delivered after an event contained a value that was valid only before the event happened). - the playlist-pos and playlist-pos-1 properties now can return and accept -1, and are never unavailable. Out of range indexes are now accepted, but behave like writing -1. - the playlist-pos and playlist-pos-1 properties deprecate the current behavior when writing back the current value to the property: currently, this restarts playback, but in the future, it will do nothing. Using the "playlist-play-index" command is recommended instead. - add "playlist-play-index" command - add playlist-current-pos, playlist-playing-pos properties - Lua end-file events set the "error" field; this is deprecated; use the "file_error" instead for this specific event. Scripts relying on the "error" field for end-file will silently break at some point in the future. - remove deprecated --input-file option, add --input-ipc-client, which is vaguely a replacement of the removed option, but not the same - change another detail for track selection options (see --aid manpage entry) - reading loop-file property as native property or mpv_node will now return "inf" instead of boolean true (also affects loop option) - remove some --vo-direct3d-... options (it got dumbed down; use --vo=gpu) - remove video-params/plane-depth property (was too vaguely defined) - remove --video-sync-adrop-size option (implementation was changed, no replacement for what this option did) - undeprecate --video-sync=display-adrop - deprecate legacy auto profiles (profiles starting with "extension." and "protocol."). Use conditional auto profiles instead. - the "subprocess" command does not connect spawned processes' stdin to mpv's stdin anymore. Instead, stdin is connected to /dev/null by default. To get the old behavior, set the "passthrough_stdin" argument to true. - key/value list options do not accept ":" as item separator anymore, only ",". This means ":" is always considered part of the value. - remove deprecated --vo-vdpau-deint option - add `delete-watch-later-config` command to complement `write-watch-later-config` --- mpv 0.32.0 --- - change behavior when using legacy option syntax with options that start with two dashes (``--`` instead of a ``-``). Now, using the recommended syntax is required for options starting with ``--``, which means an option value must be strictly passed after a ``=``, instead of as separate argument. For example, ``--log-file f.txt`` was previously accepted and behaved like ``--log-file=f.txt``, but now causes an error. Use of legacy syntax that is still supported now prints a deprecation warning. --- mpv 0.31.0 --- - add `--resume-playback-check-mtime` to check consistent mtime when restoring playback state. - add `--d3d11-output-csp` to enable explicit selection of a D3D11 swap chain color space. - the --sws- options and similar now affect vo_image and screenshot conversion (does not matter as much for vo_gpu, which does most of this with shaders) - add a builtin "sw-fast" profile, which restores performance settings for software video conversion. These were switched to higher quality since mpv 0.30.0 (related to the previous changelog entry). This affects video outputs like vo_x11 and vo_drm, and screenshots, but not much else. - deprecate --input-file (there are no plans to remove this short-term, but it will probably eventually go away <- that was a lie) - deprecate --video-sync=display-adrop (might be removed if it's in the way; undeprecated or readded if it's not too much of a problem) - deprecate all input section commands (these will be changed/removed, as soon as mpv internals do not require them anymore) - remove deprecated --playlist-pos alias (use --playlist-start) - deprecate --display-fps, introduce --override-display-fps. The display-fps property now is unavailable if no VO exists (or the VO did not return a display FPS), instead of returning the option value in this case. The property will keep existing, but writing to it is deprecated. - the vf/af properties now do not reject the set value anymore, even if filter chain initialization fails. Instead, the vf/af options are always set to the user's value, even if it does not reflect the "runtime" vf/af chain. - the vid/aid/sid/secondary-sid properties (and their aliases: "audio", "video", "sub") will now allow setting any track ID; before this change, only IDs of actually existing tracks could be set (the restriction was active the MPV_EVENT_FILE_LOADED/"file-loaded" event was sent). Setting an ID for which no track exists is equivalent to disabling it. Note that setting the properties to non-existing tracks may report it as selected track for a small time window, until it's forced back to "no". The exact details how this is handled may change in the future. - remove old Apple Remote support, including --input-appleremote - add MediaPlayer support and remove the old Media Key event tap on macOS. this possibly also re-adds the Apple Remote support - the "edition" property now strictly returns the value of the option, instead of the runtime value. The new "current-edition" property needs to be queried to read the runtime-chosen edition. This is a breaking change for any users which expected "edition" to return the runtime-chosen edition at default settings (--edition=auto). - the "window-scale" property now strictly returns the value of the option, instead of the actual size of the window. The new "current-window-scale" property needs to be queried to read the value as indicated by the current window size. This is a breaking change. - explicitly deprecate passing more than 1 item to "-add" suffix in key/value options (for example --script-opts-add). This was actually always deprecated, like with other list options, but the option parser did not print a warning in this particular case. - deprecate -del for list options (use -remove instead, which is by content instead of by integer index) - if `--fs` is used but `--fs-screen` is not set, mpv will now use `--screen` instead. - change the default of --hwdec to "no" on RPI. The default used to be "mmal" specifically if 'Raspberry Pi support' was enabled at configure time (equivalent to --enable-rpi). Use --hwdec=mmal to get the old behavior. --- mpv 0.30.0 --- - add `--d3d11-output-format` to enable explicit selection of a D3D11 swap chain format. - rewrite DVB channel switching to use an integer value `--dvbin-channel-switch-offset` for switching instead of the old stream controls which are now gone. Cycling this property up or down will change the offset to the channel which was initially tuned to. Example for `input.conf`: `H cycle dvbin-channel-switch-offset up`, `K cycle dvbin-channel-switch-offset down`. - adapt `stream_dvb` to support writing to `dvbin-prog` at runtime and also to consistently use dvbin-configuration over URI parameters when provided - add `--d3d11-adapter` to enable explicit selection of a D3D11 rendering adapter by name. - rename `--drm-osd-plane-id` to `--drm-draw-plane`, `--drm-video-plane-id` to `--drm-drmprime-video-plane` and `--drm-osd-size` to `--drm-draw-surface-size` to better reflect what the options actually control, that the values they accept aren't actually internal DRM ID's (like with similar options in ffmpeg's KMS support), and that the video plane is only used when the drmprime overlay hwdec interop is active, with the video being drawn to the draw plane otherwise. - in addition to the above, the `--drm-draw-plane` and `--drm-drmprime-video-plane` options now accept either an integer index, or the values primary or overlay. `--drm-draw-plane` now defaults to primary and `--drm-drmprime-video-plane` defaults to overlay. This should be similar to previous behavior on most drivers due to how planes are usually sorted. - rename --opensles-frames-per-buffer to --opensles-frames-per-enqueue to better reflect its purpose. In the past it overrides the buffer size the AO requests (but not the default/value of the generic --audio-buffer option). Now it only guarantees that the soft buffer size will not be smaller than itself while setting the size per Enqueue. - add --opensles-buffer-size-in-ms, allowing user to tune the soft buffer size. It overrides the --audio-buffer option unless it's set to 0 (with the default being 250). - remove `--linear-scaling`, replaced by `--linear-upscaling` and `--linear-downscaling`. This means that `--sigmoid-upscaling` no longer implies linear light downscaling as well, which was confusing. - the built-in `gpu-hq` profile now includes` --linear-downscaling`. - support for `--spirv-compiler=nvidia` has been removed, leaving `shaderc` as the only option. The `--spirv-compiler` option itself has been marked as deprecated, and may be removed in the future. - split up `--tone-mapping-desaturate`` into strength + exponent, instead of only using a single value (which previously just controlled the exponent). The strength now linearly blends between the linear and nonlinear tone mapped versions of a color. - add --hdr-peak-decay-rate and --hdr-scene-threshold-low/high - add --tone-mapping-max-boost - ipc: require that "request_id" fields are integers. Other types are still accepted for compatibility, but this will stop in the future. Also, if no request_id is provided, 0 will be assumed. - mpv_command_node() and mp.command_native() now support named arguments (see manpage). If you want to use them, use a new version of the manpage as reference, which lists the definitive names. - edition and disc title switching will now fully reload playback (may have consequences for scripts, client API, or when using file-local options) - with the removal of the stream cache, the following properties and options were dropped: `cache`, `cache-size`, `cache-free`, `cache-used`, `--cache-default`, `--cache-initial`, `--cache-seek-min`, `--cache-backbuffer`, `--cache-file`, `--cache-file-size` - the --cache option does not take a number value anymore - remove async playback abort hack. This may make it impossible to abort playback if --demuxer-thread=no is forced. - remove `--macos-title-bar-style`, replaced by `--macos-title-bar-material` and `--macos-title-bar-appearance`. - The default for `--vulkan-async-compute` has changed to `yes` from `no` with the move to libplacebo as the back-end for vulkan rendering. - Remove "disc-titles", "disc-title", "disc-title-list", and "angle" properties. dvd:// does not support title ranges anymore. - Remove all "tv-..." options and properties, along with the classic Linux analog TV support. - remove "program" property (no replacement) - always prefer EGL over GLX, which helps with AMD/vaapi, but will break vdpau with --vo=gpu - use --gpu-context=x11 to be able to use vdpau. This does not affect --vo=vdpau or --hwdec=vdpau-copy. - remove deprecated --chapter option - deprecate --record-file - add `--demuxer-cue-codepage` - add ``track-list/N/demux-bitrate``, ``track-list/N/demux-rotation`` and ``track-list/N/demux-par`` property - Deprecate ``--video-aspect`` and add ``--video-aspect-override`` to replace it. (The `video-aspect` option remains unchanged.) --- mpv 0.29.0 --- - drop --opensles-sample-rate, as --audio-samplerate should be used if desired - drop deprecated --videotoolbox-format, --ff-aid, --ff-vid, --ff-sid, --ad-spdif-dtshd, --softvol options - fix --external-files: strictly never select any tracks from them, unless explicitly selected (this may or may not be expected) - --ytdl is now always enabled, even for libmpv - add a number of --audio-resample-* options, which should from now on be used instead of --af-defaults=lavrresample:... - deprecate --vf-defaults and --af-defaults. These didn't work with the lavfi bridge, so they have very little use left. The only potential use is with af_lavrresample (going to be deprecated, --audio-resample-... set its defaults), and various hw deinterlacing filters (like vf_vavpp), for which you will have to stop using --deinterlace=yes, and instead use the vf toggle commands and the filter enable/disable flag to customize it. - deprecate --af=lavrresample. Use the ``--audio-resample-...`` options to customize resampling, or the libavfilter ``--af=aresample`` filter. - add --osd-on-seek - remove outfmt sub-parameter from "format" video filter (no replacement) - some behavior changes in the video filter chain, including: - before, using an incompatible filter with hwdec would disable hwdec; now it disables the filter at runtime instead - inserting an incompatible filter with hwdec at runtime would refuse to insert the filter; now it will add it successfully, but disables the filter slightly later - some behavior changes in the audio filter chain, including: - a manually inserted lavrresample filter is not necessarily used for sample format conversion anymore, so it's pretty useless - changing playback speed will not respect --af-defaults anymore - having libavfilter based filters after the scaletempo or rubberband filters is not supported anymore, and may desync if playback speed is changed (libavfilter does not support the metadata for playback speed) - the lavcac3enc filter does not auto detach itself anymore; instead it passes through the data after converting it to the sample rate and channel configuration the ac3 encoder expects; also, if the audio format changes midstream in a way that causes the filter to switch between PCM and AC3 output, the audio output won't be reconfigured, and audio playback will fail due to libswresample being unable to convert between PCM and AC3 (Note: the responsible developer didn't give a shit. Later changes might have improved or worsened this.) - inserting a filter that changes the output sample format will not reconfigure the AO - you need to run an additional "ao-reload" command to force this if you want that - using "strong" gapless audio (--gapless-audio=yes) can fail if the audio formats are not convertible (such as switching between PCM and AC3 passthrough) - if filters do not pass through PTS values correctly, A/V sync can result over time. Some libavfilter filters are known to be affected by this, such as af_loudnorm, which can desync over time, depending on how the audio track was muxed (af_lavfi's fix-pts suboption can help). - remove out-format sub-parameter from "format" audio filter (no replacement) - --lavfi-complex now requires uniquely named filter pads. In addition, unconnected filter pads are not allowed anymore (that means every filter pad must be connected either to another filter, or to a video/audio track or video/audio output). If they are disconnected at runtime, the stream will probably stall. - rename --vo=opengl-cb to --vo=libmpv (goes in hand with the opengl-cb API deprecation, see client-api-changes.rst) - deprecate the OpenGL cocoa backend, option choice --gpu-context=cocoa when used with --gpu-api=opengl (use --vo=libmpv) - make --deinterlace=yes always deinterlace, instead of trying to check certain unreliable video metadata. Also flip the defaults of all builtin HW deinterlace filters to always deinterlace. - change vf_vavpp default to use the best deinterlace algorithm by default - remove a compatibility hack that allowed CLI aliases to be set as property (such as "sub-file"), deprecated in mpv 0.26.0 - deprecate the old command based hook API, and introduce a proper C API (the high level Lua API for this does not change) - rename the the lua-settings/ config directory to script-opts/ - the way the player waits for scripts getting loaded changes slightly. Now scripts are loaded in parallel, and block the player from continuing playback only in the player initialization phase. It could change again in the future. (This kind of waiting was always a feature to prevent that playback is started while scripts are only half-loaded.) - deprecate --ovoffset, --oaoffset, --ovfirst, --oafirst - remove the following encoding options: --ocopyts (now the default, old timestamp handling is gone), --oneverdrop (now default), --oharddup (you need to use --vf=fps=VALUE), --ofps, --oautofps, --omaxfps - remove --video-stereo-mode. This option was broken out of laziness, and nobody wants to fix it. Automatic 3D down-conversion to 2D is also broken, although you can just insert the stereo3d filter manually. The obscurity of 3D content doesn't justify such an option anyway. - change cycle-values command to use the current value, instead of an internal counter that remembered the current position. - remove deprecated ao/vo auto profiles. Consider using scripts like auto-profiles.lua instead. - --[c]scale-[w]param[1|2] and --tone-mapping-param now accept "default", and if set to that value, reading them as property will also return "default", instead of float nan as in previous versions