RepoMirrors
/
mpv
mirror of https://github.com/mpv-player/mpv
1
0
Fork 0
Code Issues Releases Wiki Activity
mpv/DOCS/interface-changes.rst

112 lines
5.1 KiB
ReStructuredText
Raw Normal View History

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
=================
::
command: add vsync-ratio property This is very "illustrative", unlike the video-speed-correction property, and thus useful. It can also be used to observe scheduling errors, which are not detected by the core. (These happen due to rounding errors; possibly not evne our fault, but coming from files with rounded timestamps and so on.)
2015-11-13 21:48:32 +00:00
--- mpv 0.14.0 ---
- add "vsync-ratio" property
player: handle rebasing start time differently Most of this is explained in the DOCS additions. This gives us slightly more sanity, because there is less interaction between the various parts. The goal is getting rid of the video_offset entirely. The simplification extends to the user API. In particular, we don't need to fix missing parts in the API, such as the lack for a seek command that seeks relatively to the start time. All these things are now transparent. (If someone really wants to know the real timestamps/start time, new properties would have to be added.)
2015-11-16 21:47:17 +00:00
- 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.
vo_opengl_cb: make operation more similar to normal VOs vo_opengl_cb is a special case, because we somehow have to render video asynchronously, all while "trusting" the API user to do it correctly. This didn't quite work, and a while ago a compromise using a timeout to prevent theoretically possible deadlocks was added. Make it even more synchronous. Basically, go all the way, and synchronize rendering between VO and user renderer thread to the full extent possible. This means the silly frame queue is dropped, and we event attempt to synchronize the GL SwapBuffer call (via mpv_opengl_cb_report_flip()). The changes introduced with commit dc33eb56 are effectively dropped. I don't even remember if they mattered. In the future, we might make all VOs fetch asynchronously from a frame queue, which would mostly remove the differences between vo_opengl and vo_opengl_cb, but this will take a while (if it will even be done).
2015-11-09 19:49:30 +00:00
--- mpv 0.13.0 ---
- remove VO opengl-cb frame queue suboptions (no replacement)
vo_opengl: remove sharpen scalers, add sharpen sub-option This turns the old scalers (inherited from MPlayer) into a pre- processing step (after color conversion and before scaling). The code for the "sharpen5" scaler is reused for this. The main reason MPlayer implemented this as scalers was perhaps because FBOs were too expensive, and making it a scaler allowed to implement this in 1 pass. But unsharp masking is not really a scaler, and I would guess the result is more like combining bilinear scaling and unsharp masking.
2015-09-23 20:43:27 +00:00
--- mpv 0.12.0 ---
options: remove --use-text-osd
2015-10-24 17:09:35 +00:00
- remove --use-text-osd (useless; fontconfig isn't a requirement anymore,
and text rendering is also lazily initialized)
command: make time properties unavailable if timestamp is unknown Let's hope this doesn't confuse client API users too much. It's still the best solution to get rid of corner cases where it actually return the wrong timestamp on start, and then suddenly jump.
2015-10-16 14:16:10 +00:00
- 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
audio: add option for falling back to ao_null The manpage entry explains this. (Maybe this option could be always enabled and removed. I don't quite remember what valid use-cases there are for just disabling audio entirely, other than that this is also needed for audio decoder init failure.)
2015-10-05 16:53:02 +00:00
- add --audio-fallback-to-null option
video: replace vf_format outputlevels option with global option The vf_format suboption is replaced with --video-output-levels (a global option and property). In particular, the parameter is removed from mp_image_params. The mechanism is moved to the "video equalizer", which also handles common video output customization like brightness and contrast controls. The new code is slightly cleaner, and the top-level option is slightly more user-friendly than as vf_format sub-option.
2015-09-29 19:12:26 +00:00
- replace vf_format outputlevels suboption with "video-output-levels" global
property/option; also remove "colormatrix-output-range" property
vo_opengl: remove sharpen scalers, add sharpen sub-option This turns the old scalers (inherited from MPlayer) into a pre- processing step (after color conversion and before scaling). The code for the "sharpen5" scaler is reused for this. The main reason MPlayer implemented this as scalers was perhaps because FBOs were too expensive, and making it a scaler allowed to implement this in 1 pass. But unsharp masking is not really a scaler, and I would guess the result is more like combining bilinear scaling and unsharp masking.
2015-09-23 20:43:27 +00:00
- vo_opengl: remove sharpen3/sharpen5 scale filters, add sharpen sub-option
af_lavfi: implement af-metadata property Works like vf-metadata. Unfortunately requires some code duplication (even though it's not much). Fixes #2311.
2015-09-11 21:04:02 +00:00
--- mpv 0.11.0 ---
- add "af-metadata" property
DOCS: cleanup API changes version markers Make it so that they don't need to be edited on release (no change in tense). Also, move the "stray" changes after client API version 1.19 to 1.19 itself.
2015-09-10 12:08:10 +00:00
--- mpv 0.10.0 ---
video: make container vs. bitstream aspect ratio configurable Utterly idiotic bullshit. Fixes #2259.
2015-08-30 21:01:46 +00:00
- add --video-aspect-method option
player: add --playlist-pos option Oddly often requested.
2015-08-22 20:08:17 +00:00
- add --playlist-pos option
player: add display sync mode If this mode is enabled, the player tries to strictly synchronize video to display refresh. It will adjust playback speed to match the display, so if you play 23.976 fps video on a 24 Hz screen, playback speed is increased by approximately 1/1000. Audio wll be resampled to keep up with playback. This is different from the default sync mode, which will sync video to audio, with the consequence that video might skip or repeat a frame once in a while to make video keep up with audio. This is still unpolished. There are some major problems as well; in particular, mkv VFR files won't work well. The reason is that Matroska is terrible and rounds timestamps to milliseconds. This makes it rather hard to guess the framerate of a section of video that is playing. We could probably fix this by just accepting jittery timestamps (instead of explicitly disabling the sync code in this case), but I'm not ready to accept such a solution yet. Another issue is that we are extremely reliant on OS video and audio APIs working in an expected manner, which of course is not too often the case. Consequently, the new sync mode is a bit fragile.
2015-08-10 16:43:25 +00:00
- add --video-sync* options
"display-sync-active" property
"vo-missed-frame-count" property
"audio-speed-correction" and "video-speed-correction" properties
demux: remove options to control minimum packet queue size Remove --demuxer-readahead-packets and --demuxer-readahead-bytes. These were a bit useless. They could force a minimum packet queue size, but controlling the queue size with --demuxer-readahead-secs is much nicer. It's fairly certain nobody ever used these options.
2015-08-05 21:38:23 +00:00
- remove --demuxer-readahead-packets and --demuxer-readahead-bytes
demux: add options to control maximum queue size Add --demuxer-max-packets and --demuxer-max-bytes, which control the maximum size of the packet queue. These can be helpful to avoid excessive memory usage. Memory usage is the reason why there's a limit in the first place. If a file is more or less broken, and audio and video don't line up, the decoders will fill up the packet queue trying to read more audio or video, and the maximum sizes are required to avoid unbounded memory allocation. Being able to override the maximum sizes is useful; either for restricting memory usage further, or enlarging the sizes when attempting to play various broken files.
2015-08-05 21:41:29 +00:00
add --demuxer-max-packets and --demuxer-max-bytes
(the new options are not replacement and have very different semantics)
DOCS: document video-aspect behavior change Forgotten in commit ae2f8fd0.
2015-08-05 19:29:09 +00:00
- 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
player: remove higher-level remains of DVD/BD menu support Nobody wanted to restore this, so it gets the boot. If anyone still wants to volunteer to restore menu support, this would be welcome. (I might even try it myself if I feel masochistic and like wasting a lot of time for nothing.) But if it does get restored, it should be done differently. There were many stupid things about how it was done. For example, it somehow tried to pull mp_nav_events through all the layers (including needing to "buffer" them in the demuxer), which was needlessly complicated. It could be done simpler. This code was already inactive, so this commit actually changes nothing. Also keep in mind that normal DVD/BD playback still works.
2015-08-03 21:33:03 +00:00
- remove disc-nav (DVD, BD) related properties and commands
command: add property indicating per-file options Fixes #2165, more or less.
2015-07-23 20:59:04 +00:00
- add "option-info/<name>/set-locally" property
cache: make backbuffer size configurable Allow setting an arbitrary amount, instead of the fixed 50%. This is nto striclty backwards compatible. The defaults don't change, but the --cache/--cache-default options now set the readahead portion. So in practice, users who configured this until now will see the double amount of cache being used, _plus_ the 75MB default backbuffer will be in use.
2015-07-22 21:38:45 +00:00
- 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
command: add track-list/N/audio-channels property Signed-off-by: wm4 <wm4@nowhere> (With some heavy modifications from the original patch.)
2015-07-03 00:33:54 +00:00
- add ``track-list/N/audio-channels`` property
screenshot: don't write PNG colorspace tags by default Generates too much discussion and confusion. Fixes #2051.
2015-07-18 16:33:54 +00:00
- change --screenshot-tag-colorspace default value
sub: add option for stretching image subtitles to screen Probably makes users happy who want bitmap subtitles to show up in the screen margins, and stops them from doing idiotic crap with vf_expand. Fixes #2098.
2015-07-18 12:36:17 +00:00
- add --stretch-image-subs-to-screen
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
DOCS: cleanup API changes version markers Make it so that they don't need to be edited on release (no change in tense). Also, move the "stray" changes after client API version 1.19 to 1.19 itself.
2015-09-10 12:08:10 +00:00
--- mpv 0.9.0 ---