mpv/DOCS/interface-changes.rst

Introduction
============

mpv provides access to its internals via the following means:

- options
- commands
- properties
- events

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.

This document lists changes to them. New changes are added to the top.

Interface changes
=================

::

 --- mpv 0.28.0 ---
    - rename --hwdec=mediacodec option to mediacodec-copy, to reflect
      conventions followed by other hardware video decoding APIs
    - drop previously deprecated --heartbeat-cmd and --heartbeat--interval
      options
    - rename --vo=opengl to --vo=gpu
    - rename --opengl-backend to --gpu-context
    - rename --opengl-shaders to --glsl-shaders
    - rename --opengl-shader-cache-dir to --gpu-shader-cache-dir
    - rename --opengl-tex-pad-x/y to --gpu-tex-pad-x/y
    - rename --opengl-fbo-format to --fbo-format
    - rename --opengl-gamma to --gamma-factor
    - rename --opengl-debug to --gpu-debug
    - rename --opengl-sw to --gpu-sw
    - rename --opengl-vsync-fences to --swapchain-depth, and the interpretation
      slightly changed. Now defaults to 3.
    - rename the built-in profile `opengl-hq` to `gpu-hq`
    - the semantics of --opengl-es=yes are slightly changed -> now requires GLES
    - remove the (deprecated) alias --gpu-context=drm-egl
    - remove the (deprecated) --vo=opengl-hq
    - remove --opengl-es=force2 (use --opengl-es=yes --opengl-restrict=300)
    - the --msg-level option now affects --log-file
    - drop "audio-out-detected-device" property - this was unavailable on all
      audio output drivers for quite a while (coreaudio used to provide it)
    - deprecate --videotoolbox-format (use --hwdec-image-format, which affects
      most other hwaccels)
 --- mpv 0.27.0 ---
    - drop previously deprecated --field-dominance option
    - drop previously deprecated "osd" command
    - remove client API compatibility handling for "script", "sub-file",
      "audio-file", "external-file" (these cases used to log a deprecation
      warning)
    - drop deprecated --video-aspect-method=hybrid option choice
    - rename --hdr-tone-mapping to --tone-mapping (and generalize it)
    - --opengl-fbo-format changes from a choice to a string. Also, its value
      will be checked only on renderer initialization, rather than when the
      option is set.
    - Using opengl-cb now always assumes 8 bit per component depth, and dithers
      to this size. Before, it tried to figure out the depth of the first
      framebuffer that was ever passed to the renderer. Having GL framebuffers
      with a size larger than 8 bit per component is quite rare. If you need
      it, set the --dither-depth option instead.
    - --lavfi-complex can now be set during runtime. If you set this in
      expectation it would be applied only after a reload, you might observe
      weird behavior.
    - add --track-auto-selection to help with scripts/applications that
      make exclusive use of --lavfi-complex.
    - undeprecate --loop, and map it from --loop-playlist to --loop-file (the
      deprecation was to make sure no API user gets broken by a sudden behavior
      change)
    - remove previously deprecated vf_eq
    - remove that hardware deinterlace filters (vavpp, d3d11vpp, vdpaupp)
      changed their deinterlacing-enabled setting depending on what the
      --deinterlace option or property was set to. Now, a filter always does
      what its filter options and defaults imply. The --deinterlace option and
      property strictly add/remove its own filters. For example, if you run
      "mpv --vf=vavpp --deinterlace=yes", this will insert another, redundant
      filter, which is probably not what you want. For toggling a deinterlace
      filter manually, use the "vf toggle" command, and do not set the
      deinterlace option/property. To customize the filter that will be
      inserted automatically, use --vf-defaults. Details how this works will
      probably change in the future.
    - remove deinterlace=auto (this was not deprecated, but had only a very
      obscure use that stopped working with the change above. It was also
      prone to be confused with a feature not implemented by it: auto did _not_
      mean that deinterlacing was enabled on demand.)
    - add shortened mnemonic names for mouse button bindings, eg. mbtn_left
      the old numeric names (mouse_btn0) are deprecated
    - remove mouse_btn3_dbl and up, since they are only generated for buttons
      0-2 (these now print an error when sent from the 'mouse' command)
    - rename the axis bindings to wheel_up/down/etc. axis scrolling and mouse
      wheel scrolling are now conceptually the same thing
      the old axis_up/down names remain as deprecated aliases
 --- mpv 0.26.0 ---
    - remove remaining deprecated audio device options, like --alsa-device
      Some of them were removed in earlier releases.
    - introduce --replaygain... options, which replace the same functionality
      provided by the deprecated --af=volume:replaygain... mechanism.
    - drop the internal "mp-rawvideo" codec (used by --demuxer=rawvideo)
    - rename --sub-ass-style-override to --sub-ass-override, and rename the
      `--sub-ass-override=signfs` setting to `--sub-ass-override=scale`.
    - change default of --video-aspect-method to "bitstream". The "hybrid"
      method (old default) is deprecated.
    - remove property "video-params/nom-peak"
    - remove option --target-brightness
    - replace vf_format's `peak` suboption by `sig-peak`, which is relative to
      the reference white level instead of in cd/m^2
    - renamed the TRCs `st2084` and `std-b67` to `pq` and `hlg` respectively
    - the "osd" command is deprecated (use "cycle osd-level")
    - --field-dominance is deprecated (use --vf=setfield=bff or tff)
    - --really-quiet subtle behavior change
    - the deprecated handling of setting "no-" options via client API is dropped
    - the following options change to append-by-default (and possibly separator):
        --script
      also, the following options are deprecated:
        --sub-paths => --sub-file-paths
      the following options are deprecated for setting via API:
        "script" (use "scripts")
        "sub-file" (use "sub-files")
        "audio-file" (use "audio-files")
        "external-file" (use "external-files")
        (the compatibility hacks for this will be removed after this release)
    - remove property `vo-performance`, and add `vo-passes` as a more general
      replacement
    - deprecate passing multiple arguments to -add/-pre options (affects the
      vf/af commands too)
    - remove --demuxer-lavf-cryptokey. Use --demux-lavf-o=cryptokey=<hex> or
      --demux-lavf-o=decryption_key=<hex> instead (whatever fits your situation).
    - rename --opengl-dumb-mode=no to --opengl-dumb-mode=auto, and make `no`
      always disable it (unless forced on by hardware limitation).
    - generalize --scale-clamp, --cscale-clamp etc. to accept a float between
      0.0 and 1.0 instead of just being a flag. A value of 1.0 corresponds to
      the old `yes`, and a value of 0.0 corresponds to the old `no`.
 --- mpv 0.25.0 ---
    - remove opengl-cb dxva2 dummy hwdec interop
      (see git "vo_opengl: remove dxva2 dummy hwdec backend")
    - remove ppm, pgm, pgmyuv, tga choices from the --screenshot-format and
      --vo-image-format options
    - the "jpeg" choice in the option above now leads to a ".jpg" file extension
    - --af=drc is gone (you can use e.g. lavfi/acompressor instead)
    - remove image_size predefined uniform from OpenGL user shaders. Use
      input_size instead
    - add --sub-filter-sdh
    - add --sub-filter-sdh-harder
    - remove --input-app-events option (macOS)
    - deprecate most --vf and --af filters. Only some filters not in libavfilter
      will be kept.
      Also, you can use libavfilter filters directly (e.g. you can use
      --vf=name=opts instead of --vf=lavfi=[name=opts]), as long as the
      libavfilter filter's name doesn't clash with a mpv builtin filter.
      In the long term, --vf/--af syntax might change again, but if it does, it
      will switch to libavfilter's native syntax. (The above mentioned direct
      support for lavfi filters still has some differences, such as how strings
      are escaped.) If this happens, the non-deprecated builtin filters might be
      moved to "somewhere else" syntax-wise.
    - deprecate --loop - after a deprecation period, it will be undeprecated,
      but changed to alias --loop-file
    - add --keep-open-pause=no
    - deprecate --demuxer-max-packets
    - change --audio-file-auto default from "exact" to "no" (mpv won't load
      files with the same filename as the video, but different extension, as
      audio track anymore)
 --- mpv 0.24.0 ---
    - deprecate --hwdec-api and replace it with --opengl-hwdec-interop.
      The new option accepts both --hwdec values, as well as named backends.
      A minor difference is that --hwdec-api=no (which used to be the default)
      now actually does not preload any interop layer, while the new default
      ("") uses the value of --hwdec.
    - drop deprecated --ad/--vd features
    - drop deprecated --sub-codepage syntax
    - rename properties:
        - "drop-frame-count" to "decoder-frame-drop-count"
        - "vo-drop-frame-count" to "frame-drop-count"
      The old names still work, but are deprecated.
    - remove the --stream-capture option and property. No replacement.
      (--record-file might serve as alternative)
    - add --sub-justify
    - add --sub-ass-justify
    - internally there's a different way to enable the demuxer cache now
      it can be auto-enabled even if the stream cache remains disabled
 --- mpv 0.23.0 ---
    - remove deprecated vf_vdpaurb (use "--hwdec=vdpau-copy" instead)
    - the following properties now have new semantics:
        - "demuxer" (use "current-demuxer")
        - "fps" (use "container-fps")
        - "idle" (use "idle-active")
        - "cache" (use "cache-percent")
        - "audio-samplerate" (use "audio-params/samplerate")
        - "audio-channels" (use "audio-params/channel-count")
        - "audio-format" (use "audio-codec-name")
      (the properties equivalent to the old semantics are in parentheses)
    - remove deprecated --vo and --ao sub-options (like --vo=opengl:...), and
      replace them with global options. A somewhat complete list can be found
      here: https://github.com/mpv-player/mpv/wiki/Option-replacement-list#mpv-0210
    - remove --vo-defaults and --ao-defaults as well
    - remove deprecated global sub-options (like -demuxer-rawaudio format=...),
      use flat options (like --demuxer-rawaudio-format=...)
    - the --sub-codepage option changes in incompatible ways:
        - detector-selection and fallback syntax is deprecated
        - enca/libguess are removed and deprecated (behaves as if they hadn't
          been compiled-in)
        - --sub-codepage=<codepage> does not force the codepage anymore
          (this requires different and new syntax)
    - remove --fs-black-out-screens option for macOS
    - change how spdif codecs are selected. You can't enable spdif passthrough
      with --ad anymore. This was deprecated; use --audio-spdif instead.
    - deprecate the "family" selection with --ad/--vd
      forcing/excluding codecs with "+", "-", "-" is deprecated as well
    - explicitly mark --ad-spdif-dtshd as deprecated (it was done so a long time
      ago, but it didn't complain when using the option)
 --- mpv 0.22.0 ---
    - the "audio-device-list" property now sets empty device description to the
      device name as a fallback
    - add --hidpi-window-scale option for macOS
    - add audiounit audio output for iOS
    - make --start-time work with --rebase-start-time=no
    - add --opengl-early-flush=auto mode
    - add --hwdec=vdpau-copy, deprecate vf_vdpaurb
    - add tct video output for true-color and 256-color terminals
 --- mpv 0.21.0 ---
    - unlike in older versions, setting options at runtime will now take effect
      immediately (see for example issue #3281). On the other hand, it will also
      do runtime verification and reject option changes that do not work
      (example: setting the "vf" option to a filter during playback, which fails
      to initialize - the option value will remain at its old value). In general,
      "set name value" should be mostly equivalent to "set options/name value"
      in cases where the "name" property is not deprecated and "options/name"
      exists - deviations from this are either bugs, or documented as caveats
      in the "Inconsistencies between options and properties" manpage section.
    - deprecate _all_ --vo and --ao suboptions. Generally, all suboptions are
      replaced by global options, which do exactly the same. For example,
      "--vo=opengl:scale=nearest" turns into "--scale=nearest". In some cases,
      the global option is prefixed, e.g. "--vo=opengl:pbo" turns into
      "--opengl-pbo".
      Most of the exact replacements are documented here:
        https://github.com/mpv-player/mpv/wiki/Option-replacement-list
    - remove --vo=opengl-hq. Set --profile=opengl-hq instead. Note that this
      profile does not force the VO. This means if you use the --vo option to
      set another VO, it won't work. But this also means it can be used with
      opengl-cb.
    - remove the --vo=opengl "pre-shaders", "post-shaders" and "scale-shader"
      sub-options: they were deprecated in favor of "user-shaders"
    - deprecate --vo-defaults (no replacement)
    - remove the vo-cmdline command. You can set OpenGL renderer options
      directly via properties instead.
    - deprecate the device/sink options on all AOs. Use --audio-device instead.
    - deprecate "--ao=wasapi:exclusive" and "--ao=coreaudio:exclusive",
      use --audio-exclusive instead.
    - subtle changes in how "--no-..." options are treated mean that they are
      not accessible under "options/..." anymore (instead, these are resolved
      at parsing time). This does not affect options which start with "--no-",
      but do not use the mechanism for negation options.
      (Also see client API change for API version 1.23.)
    - rename the following properties
        - "demuxer" -> "current-demuxer"
        - "fps" -> "container-fps"
        - "idle" -> "idle-active"
        - "cache" -> "cache-percent"
      the old names are deprecated and will change behavior in mpv 0.23.0.
    - remove deprecated "hwdec-active" and "hwdec-detected" properties
    - deprecate the ao and vo auto-profiles (they never made any sense)
    - deprecate "--vo=direct3d_shaders" - use "--vo=direct3d" instead.
      Change "--vo=direct3d" to always use shaders by default.
    - deprecate --playlist-pos option, renamed to --playlist-start
    - deprecate the --chapter option, as it is redundant with --start/--end,
      and conflicts with the semantics of the "chapter" property
    - rename --sub-text-* to --sub-* and --ass-* to --sub-ass-* (old options
      deprecated)
    - incompatible change to cdda:// protocol options: the part after cdda://
      now always sets the device, not the span or speed to be played. No
      separating extra "/" is needed. The hidden --cdda-device options is also
      deleted (it was redundant with the documented --cdrom-device).
    - deprecate --vo=rpi. It will be removed in mpv 0.23.0. Its functionality
      was folded into --vo=opengl, which now uses RPI hardware decoding by
      treating it as a hardware overlay (without applying GL filtering). Also
      to be changed in 0.23.0: the --fs flag will be reset to "no" by default
      (like on the other platforms).
    - deprecate --mute=auto (informally has been since 0.18.1)
    - deprecate "resume" and "suspend" IPC commands. They will be completely
      removed in 0.23.0.
    - deprecate mp.suspend(), mp.resume(), mp.resume_all() Lua scripting
      commands, as well as setting mp.use_suspend. They will be completely
      removed in 0.23.0.
    - the "seek" command's absolute seek mode will now interpret negative
      seek times as relative from the end of the file (and clamps seeks that
      still go before 0)
    - add almost all options to the property list, meaning you can change
      options without adding "options/" to the property name (a new section
      has been added to the manpage describing some conflicting behavior
      between options and properties)
    - implement changing sub-speed during playback
    - make many previously fixed options changeable at runtime (for example
      --terminal, --osc, --ytdl, can all be enable/disabled after
      mpv_initialize() - this can be extended to other still fixed options
      on user requests)
 --- mpv 0.20.0 ---
    - add --image-display-duration option - this also means that image duration
      is not influenced by --mf-fps anymore in the general case (this is an
      incompatible change)
 --- mpv 0.19.0 ---
    - deprecate "balance" option/property (no replacement)
 --- mpv 0.18.1 ---
    - deprecate --heartbeat-cmd
    - remove --softvol=no capability:
        - deprecate --softvol, it now does nothing
        - --volume, --mute, and the corresponding 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
    - deprecate --sub-ass=no option by --ass-style-override=strip
      (also needs --embeddedfonts=no)
    - add "hwdec-interop" and "hwdec-current" properties
    - deprecated "hwdec-active" and "hwdec-detected" properties (to be removed
      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
      such as well.
    - the VO opengl fbo-format sub-option does not accept "rgb" or "rgba"
      anymore
    - all VO opengl prescalers have been removed (replaced by user scripts)
 --- mpv 0.17.0 ---
    - deprecate "track-list/N/audio-channels" property (use
      "track-list/N/demux-channel-count" instead)
    - remove write access to "stream-pos", and change semantics for read access
    - Lua scripts now don't suspend mpv by default while script code is run
    - add "cache-speed" property
    - rename --input-unix-socket to --input-ipc-server, and make it work on
      Windows too
    - change the exact behavior of the "video-zoom" property
    - --video-unscaled no longer disables --video-zoom and --video-aspect
      To force the old behavior, set --video-zoom=0 and --video-aspect=0
 --- mpv 0.16.0 ---
    - change --audio-channels default to stereo (use --audio-channels=auto to
      get the old default)
    - add --audio-normalize-downmix
    - change the default downmix behavior (--audio-normalize-downmix=yes to get
      the old default)
    - VO opengl custom shaders must now use "sample_pixel" as function name,
      instead of "sample"
    - change VO opengl scaler-resizes-only default to enabled
    - add VO opengl "interpolation-threshold" suboption (introduces new default
      behavior, which can change e.g. ``--video-sync=display-vdrop`` to the
      worse, but is usually what you want)
    - make "volume" and "mute" properties changeable even if no audio output is
      active (this gives not-ideal behavior if --softvol=no is used)
    - add "volume-max" and "mixer-active" properties
    - ignore --input-cursor option for events injected by input commands like
      "mouse", "keydown", etc.
 --- mpv 0.15.0 ---
    - change "yadif" video filter defaults
 --- mpv 0.14.0 ---
    - vo_opengl interpolation now requires --video-sync=display-... to be set
    - change some vo_opengl defaults (including changing tscale)
    - add "vsync-ratio", "estimated-display-fps" properties
    - add --rebase-start-time option
      This is a breaking change to start time handling. Instead of making start
      time handling an aspect of different options and properties (like
      "time-pos" vs. "playback-time"), make it dependent on the new option. For
      compatibility, the "time-start" property now always returns 0, so code
      which attempted to handle rebasing manually will not break.
 --- mpv 0.13.0 ---
    - remove VO opengl-cb frame queue suboptions (no replacement)
 --- mpv 0.12.0 ---
    - remove --use-text-osd (useless; fontconfig isn't a requirement anymore,
      and text rendering is also lazily initialized)
    - some time properties (at least "playback-time", "time-pos",
      "time-remaining", "playtime-remaining") now are unavailable if the time
      is unknown, instead of just assuming that the internal playback position
      is 0
    - add --audio-fallback-to-null option
    - replace vf_format outputlevels suboption with "video-output-levels" global
      property/option; also remove "colormatrix-output-range" property
    - vo_opengl: remove sharpen3/sharpen5 scale filters, add sharpen sub-option
 --- mpv 0.11.0 ---
    - add "af-metadata" property
 --- mpv 0.10.0 ---
    - add --video-aspect-method option
    - add --playlist-pos option
    - add --video-sync* options
      "display-sync-active" property
      "vo-missed-frame-count" property
      "audio-speed-correction" and "video-speed-correction" properties
    - remove --demuxer-readahead-packets and --demuxer-readahead-bytes
      add --demuxer-max-packets and --demuxer-max-bytes
      (the new options are not replacement and have very different semantics)
    - change "video-aspect" property: always settable, even if no video is
      running; always return the override - if no override is set, return
      the video's aspect ratio
    - remove disc-nav (DVD, BD) related properties and commands
    - add "option-info/<name>/set-locally" property
    - add --cache-backbuffer; change --cache-default default to 75MB
      the new total cache size is the sum of backbuffer and the cache size
      specified by --cache-default or --cache
    - add ``track-list/N/audio-channels`` property
    - change --screenshot-tag-colorspace default value
    - add --stretch-image-subs-to-screen
    - add "playlist/N/title" property
    - add --video-stereo-mode=no to disable auto-conversions
    - add --force-seekable, and change default seekability in some cases
    - add vf yadif/vavpp/vdpaupp interlaced-only suboptions
      Also, the option is enabled by default (Except vf_yadif, which has
      it enabled only if it's inserted by the deinterlace property.)
    - add --hwdec-preload
    - add ao coreaudio exclusive suboption
    - add ``track-list/N/forced`` property
    - add audio-params/channel-count and ``audio-params-out/channel-count props.
    - add af volume replaygain-fallback suboption
    - add video-params/stereo-in property
    - add "keypress", "keydown", and "keyup" commands
    - deprecate --ad-spdif-dtshd and enabling passthrough via --ad
      add --audio-spdif as replacement
    - remove "get_property" command
    - remove --slave-broken
    - add vo opengl custom shader suboptions (source-shader, scale-shader,
      pre-shaders, post-shaders)
    - completely change how the hwdec properties work:
        - "hwdec" now reflects the --hwdec option
        - "hwdec-detected" does partially what the old "hwdec" property did
          (and also, "detected-hwdec" is removed)
        - "hwdec-active" is added
    - add protocol-list property
    - deprecate audio-samplerate and audio-channels properties
      (audio-params sub-properties are the replacement)
    - add audio-params and audio-out-params properties
    - deprecate "audio-format" property, replaced with "audio-codec-name"
    - deprecate --media-title, replaced with --force-media-title
    - deprecate "length" property, replaced with "duration"
    - change volume property:
        - the value 100 is now always "unchanged volume" - with softvol, the
          range is 0 to --softvol-max, without it is 0-100
        - the minimum value of --softvol-max is raised to 100
    - remove vo opengl npot suboption
    - add relative seeking by percentage to "seek" command
    - add playlist_shuffle command
    - add --force-window=immediate
    - add ao coreaudio change-physical-format suboption
    - remove vo opengl icc-cache suboption, add icc-cache-dir suboption
    - add --screenshot-directory
    - add --screenshot-high-bit-depth
    - add --screenshot-jpeg-source-chroma
    - default action for "rescan_external_files" command changes
 --- mpv 0.9.0 ---