mpv/DOCS/interface-changes.rst

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

mpv provides access to its internal 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.10.0 will be released ---
    - 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 is released ---
DOCS: add a changelog for option/command/property changes All these make up both user interface and API. It's a good idea to actually keep track of changes to it. 2015-05-22 17:00:13 +00:00			`Introduction`
			`============`

			`mpv provides access to its internal 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.10.0 will be released ---`
player: parse and expose m3u playlist titles Requested. Closes #2100. 2015-07-10 19:22:35 +00:00			`- add "playlist/N/title" property`
video: add a way to disable automatic stereo conversion Fixes #2111. 2015-07-10 16:04:34 +00:00			`- add --video-stereo-mode=no to disable auto-conversions`
player: disable seeking even if the cache is enabled Until now, if a stream wasn't seekable, but the stream cache was enabled (--cache), we've enabled seeking anyway. The idea was that at least short seeks would typically fall within the cache. And if not, the user was out of luck and terrible things happened. In other words, it was unreliable. Be stricter about it and remove this behavior. Effectively, this will for example disable seeking in piped data. Instead of trying to be clever, add an --force-seekable option, which will always enable seeking if the user really wants it. 2015-07-08 20:04:35 +00:00			`- add --force-seekable, and change default seekability in some cases`
vf_vdpaupp: don't attempt to deinterlace progressive frames 2015-07-08 13:14:38 +00:00			`- 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.)`
vo_opengl_cb, vo_opengl: add option for preloading hwdec context See manpage additions. This is mainly useful for vo_opengl_cb, but can also be applied to vo_opengl. On a side note, gl_hwdec_load_api() should stop using a name string, and instead always use the IDs. This should be cleaned up another time. 2015-07-07 12:53:58 +00:00			`- add --hwdec-preload`
ao_coreaudio: add exclusive suboption 2015-07-03 17:21:22 +00:00			`- add ao coreaudio exclusive suboption`
DOCS: fix recent typos Pointed out by a certain wiiaboo. 2015-06-28 11:23:16 +00:00			- add ``track-list/N/forced`` property
audio: output human-readable channel layouts too This gets you the "logical" channel layout, instead of the exact thing we're sending to the AO. (Tired of the cryptic shit ALSA gives me.) 2015-06-25 17:10:24 +00:00			- add audio-params/channel-count and ``audio-params-out/channel-count props.
DOCS: document some recent interface additions 2015-06-24 12:40:03 +00:00			`- add af volume replaygain-fallback suboption`
			`- add video-params/stereo-in property`
command: add keypress, keydown, and keyup commands. These commands are used to simulate keypresses using the key names from input.conf. 2015-06-10 23:56:56 +00:00			`- add "keypress", "keydown", and "keyup" commands`
audio: add --audio-spdif as new method for enabling passthrough This provides a new method for enabling spdif passthrough. The old method via --ad (--ad=spdif:ac3 etc.) is deprecated. The deprecated method will probably stop working at some point. This also supports PCM fallback. One caveat is that it will lose at least 1 audio packet in doing so. (I don't care enough to prevent this.) (This is named after the old S/PDIF connector, because it uses the same underlying technology as far as the higher level protoco is concerned. Also, the user should be renamed that passthrough is backwards.) 2015-06-05 20:35:43 +00:00			`- deprecate --ad-spdif-dtshd and enabling passthrough via --ad`
			`add --audio-spdif as replacement`
command: remove deprecated get_property command This command has been deprecated in the 0.8.x and 0.9.x releases - get rid of it. Its only point ever was MPlayer compatibility, which broke years ago anyway. 2015-05-27 16:08:02 +00:00			`- remove "get_property" command`
options: remove --slave-broken It has been deprecated for ages. 2015-05-27 16:01:26 +00:00			`- remove --slave-broken`
DOCS: interface-changes: mention recent vo_opengl additions 2015-05-27 09:28:21 +00:00			`- add vo opengl custom shader suboptions (source-shader, scale-shader,`
			`pre-shaders, post-shaders)`
command: change the hwdec properties Another very minor step towards property/option unification. Not bothering with interface compatibility here. 2015-05-25 19:44:48 +00:00			`- 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`
command: add protocol-list property Fixes #1972. 2015-05-23 13:26:55 +00:00			`- add protocol-list property`
command: deprecate audio-samplerate Also replace their implementation with the recently introduced properties. One significant difference is that audio-channels using OSD formatting does not print the channel layout. The user can just use the replacement property instead. 2015-05-22 18:28:20 +00:00			`- deprecate audio-samplerate and audio-channels properties`
			`(audio-params sub-properties are the replacement)`
command: add audio-params and audio-out-params properties 2015-05-22 18:23:47 +00:00			`- add audio-params and audio-out-params properties`
command: rename audio-format property Clashes with the option. 2015-05-22 18:05:04 +00:00			`- deprecate "audio-format" property, replaced with "audio-codec-name"`
options: rename --media-title option Conflicts with the property. 2015-05-22 18:03:14 +00:00			`- deprecate --media-title, replaced with --force-media-title`
command: deprecate the "length" property It collides with the --length option. 2015-05-22 18:02:47 +00:00			`- deprecate "length" property, replaced with "duration"`
DOCS: add a changelog for option/command/property changes All these make up both user interface and API. It's a good idea to actually keep track of changes to it. 2015-05-22 17:00:13 +00:00			`- 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 is released ---`