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

62 lines
2.8 KiB
ReStructuredText
Raw Normal View History

DOCS: add a file listing API changes for the client API
2014-07-02 23:24:41 +00:00
Introduction
============
This file lists all changes that can cause compatibility issues when using
mpv through the client API (libmpv and ``client.h``). Since the client API
interfaces to input handling (commands, properties) as well as command line
options, this list is interesting for other uses of mpv, such as the Lua
scripting interface, key bindings in ``input.rst``, or plain command line
usage.
Normally, changes to the C API that are incompatible to previous iterations
receive a major version bump (i.e. the first version number is increased),
while C API additions bump the minor version (i.e. the second number is
increased). Changes to properties/commands/options may also lead to a minor
version bump, in particular if they are incompatible.
The version number is the same as used for MPV_CLIENT_API_VERSION (see
``client.h`` how to convert between major/minor version numbers and the flat
32 bit integer).
Also, read the section ``Compatibility`` in ``client.h``.
API changes
===========
DOCS/client-api-changes: try to fix rst formatting again
2014-07-06 17:05:45 +00:00
::
client API: add an enum for mpv_event_end_file.reason Using magic integer values was an attempt to keep the API less verbose. But it was probably not a good idea. Reason 1 (restart) is not made explicit, because it is not used anymore starting with the previous commit. For ABI compatibility, the value is left as a hole in the enum.
2014-10-28 14:44:25 +00:00
1.9 - add enum mpv_end_file_reason for mpv_event_end_file.reason
client API: better error reporting Give somewhat more information on playback failure.
2014-10-28 15:19:07 +00:00
- add MPV_END_FILE_REASON_ERROR and the mpv_event_end_file.error field
for slightly better error reporting on playback failure
player: add an option to abort playback on partial init failures This is probably what libmpv users want; and it also improves error reporting (or we'd have to add a way to communicate such mid-playback failures as events).
2014-10-28 18:51:44 +00:00
- add --stop-playback-on-init-failure option, and make it the default
behavior for libmpv only
client API: add qthelper.hpp This provides some helper functions and classes for C++/Qt. As the top of qthelper.hpp says, this is built on top of the client API, and is a mere helper provided for convenience. Maybe this should be a separate library, but on the other hand I don't see much of a point in that. It's also header-only, but C++ people like such things. This makes it easier for us, because we don't need to care about ABI compatibility. The client API doesn't change, but bump it so that those who are using this header can declare a proper dependency.
2014-10-13 19:38:54 +00:00
1.8 - add qthelper.hpp
client API: add mpv_command_node[_async] Allows passing native types as arguments. Also some minor doc improvements, including giving some (natural) improvements to mpv_free_node_contents(). Note: mpv_command_node_async() is completely untested.
2014-10-10 21:58:59 +00:00
1.7 - add mpv_command_node(), mpv_command_node_async()
client API: clarify pause/unpause events, modify core-idle property Whether you consider the semantics weird or not depends on your use case, but I suppose it's a bit confusing anyway. At this point, we keep MPV_EVENT_PAUSE/UNPAUSE for compatibility only. Make the "core-idle" property somewhat more useful in this context.
2014-10-07 19:01:19 +00:00
1.6 - modify "core-idle" property behavior
msg, client API: buffer partial lines The API could return partial lines, meaning the message could stop in the middle of a line, and the next message would have the rest of it (or just the next part of it). This was a pain for the user, so do the nasty task of buffering the lines ourselves. Now only complete lines are sent. To make things even easier for the API user, don't put multiple lines into a single event, but split them. The terminal output code needed something similar (inserting a prefix header on start of each line). To avoid code duplication, this commit refactors the terminal output so that lines are split in a single place.
2014-10-08 11:11:55 +00:00
- MPV_EVENT_LOG_MESSAGE now always sends complete lines
client API: introduce numeric log levels Maybe using strings for log levels was a mistake (too broad and too impractical), so I'm adding numeric log level at least for the receiver side. This makes it easier to map mpv log levels to other logging systems. I'm still too stingy to add a function to set the log level by a numeric value, though. The numeric values are not directly mapped to the internal mpv values, because then almost every file in mpv would have to include the client API header. Coalesce this into API version 1.6, since 1.6 was bumped just yesterday.
2014-10-08 12:15:14 +00:00
- introduce numeric log levels (mpv_log_level)
client API: clarify pause/unpause events, modify core-idle property Whether you consider the semantics weird or not depends on your use case, but I suppose it's a bit confusing anyway. At this point, we keep MPV_EVENT_PAUSE/UNPAUSE for compatibility only. Make the "core-idle" property somewhat more useful in this context.
2014-10-07 19:01:19 +00:00
--- mpv 0.6.0 is released ---
client API, X11: change default keyboard input handling again Commit 64b7811c tried to do the "right thing" with respect to whether keyboard input should be enabled or not. It turns out that X11 does something stupid by design. All modern toolkits work around this native X11 behavior, but embedding breaks these workarounds. The only way to handle this correctly is the XEmbed protocol. It needs to be supported by the toolkit, and probably also some mpv support. But Qt has inconsistent support for it. In Qt 4, a X11 specific embedding widget was needed. Qt 5.0 doesn't support it at all. Qt 5.1 apparently supports it via QWindow, but if it really does, I couldn't get it to work. So add a hack instead. The new --input-x11-keyboard option controls whether mpv should enable keyboard input on the X11 window or not. In the command line player, it's enabled by default, but in libmpv it's disabled. This hack has the same problem as all previous embedding had: move the mouse outside of the window, and you don't get keyboard input anymore. Likewise, mpv will steal all keyboard input from the parent application as long as the mouse is inside of the mpv window. Also see issue #1090.
2014-09-28 18:11:00 +00:00
1.5 - change in X11 and "--wid" behavior again. The previous change didn't
work as expected, and now the behavior can be explicitly controlled
with the "input-x11-keyboard" option. This is only a temporary
measure until XEmbed is implemented and confirmed working.
client API: rename --input-x11-keyboard to --input-vo-keyboard Apparently we need this for Cocoa too. (The option was X11 specific in the hope that only X11 would need this hack.)
2014-10-09 16:28:37 +00:00
Note: in 1.6, "input-x11-keyboard" was renamed to "input-vo-keyboard",
although the old option name still works.
x11: when using --wid, inherit event flags from parent window When embedding a X window, it's hard to control whether it receives mouse/keyboard input or not. It seems the X protocol itself makes this hard (basically due to the outdated design mismatching with modern toolkits), and we have to take care of these things explicitly. Simply do this by manually querying and using the parent window event flags. This restores some MPlayer behavior (it doesn't add back exactly the same code, but it's very similar). This probably has some potential to interfere with libmpv embedding, so bump the client API minor. CC: @mpv-player/stable (if applied, client-api-changes.rst has to be adjusted to include the 0.5.2 release)
2014-08-31 12:26:31 +00:00
1.4 - subtle change in X11 and "--wid" behavior
client API, X11: change default keyboard input handling again Commit 64b7811c tried to do the "right thing" with respect to whether keyboard input should be enabled or not. It turns out that X11 does something stupid by design. All modern toolkits work around this native X11 behavior, but embedding breaks these workarounds. The only way to handle this correctly is the XEmbed protocol. It needs to be supported by the toolkit, and probably also some mpv support. But Qt has inconsistent support for it. In Qt 4, a X11 specific embedding widget was needed. Qt 5.0 doesn't support it at all. Qt 5.1 apparently supports it via QWindow, but if it really does, I couldn't get it to work. So add a hack instead. The new --input-x11-keyboard option controls whether mpv should enable keyboard input on the X11 window or not. In the command line player, it's enabled by default, but in libmpv it's disabled. This hack has the same problem as all previous embedding had: move the mouse outside of the window, and you don't get keyboard input anymore. Likewise, mpv will steal all keyboard input from the parent application as long as the mouse is inside of the mpv window. Also see issue #1090.
2014-09-28 18:11:00 +00:00
(this change was added to 0.5.2, and broke some things, see #1090)
DOCS: mark the recent release in client-api-changes.rst Also add instructions to release-policy.md, since this can be easily forgotten. CC: @mpv-player/stable
2014-08-12 19:55:42 +00:00
--- mpv 0.5.0 is released ---
client API: add and use the MPV_MAKE_VERSION macro This is probably nicer. The actual version number doesn't change (other than the minor being incremented). The "| 0UL" is to make the type unsigned long int, like it was before.
2014-08-05 00:23:14 +00:00
1.3 - add MPV_MAKE_VERSION()
Remove stream_pts stuff This was used by DVD/BD, but its usage was removed with one of the previous commits.
2014-07-06 17:05:59 +00:00
1.2 - remove "stream-time-pos" property (no replacement)
DOCS: add a file listing API changes for the client API
2014-07-02 23:24:41 +00:00
1.1 - remap dvdnav:// to dvd://
- add "--cache-file", "--cache-file-size"
- add "--colormatrix-primaries" (and property)
- add "primaries" sub-field to image format properties
- add "playback-time" property
- extend the "--start" option; a leading "+", which was previously
insignificant is now significant
- add "cache-free" and "cache-used" properties
- OSX: the "coreaudio" AO spdif code is split into a separate AO
DOCS/client-api-changes: try to fix rst formatting again
2014-07-06 17:05:45 +00:00
--- mpv 0.4.0 is released ---
DOCS: add a file listing API changes for the client API
2014-07-02 23:24:41 +00:00
1.0 - the API is declared stable
DOCS/client-api-changes: try to fix rst formatting again
2014-07-06 17:05:45 +00:00