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

251 lines
14 KiB
ReStructuredText
Raw Permalink 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
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
options, you should also look at ``interface-changes.rst``.
DOCS: add a file listing API changes for the client API
2014-07-02 23:24:41 +00:00
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).
DOCS/compatibility.rst: add this file Another thing nobody will read. I'm attempting to document the rules by which incompatible changes can be made. These rules have always been present in this project, but I don't think they were written down. Or maybe they were, but I forgot where. I think due to the time of the day it became increasingly incoherent (not necessarily near the end of the text). Hopefully no logical or freudian lapses in there.
2019-10-05 00:11:55 +00:00
Also, read the section ``Compatibility`` in ``client.h``, and compatibility.rst.
DOCS: add a file listing API changes for the client API
2014-07-02 23:24:41 +00:00
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
Options, commands, properties
=============================
Changes to these are not listed here, but in ``interface-changes.rst``. (Before
client API version 1.17, they were listed here partially.)
This listing includes changes to the bare C API and behavior only, not what
you can access with them.
DOCS: add a file listing API changes for the client API
2014-07-02 23:24:41 +00:00
API changes
===========
DOCS/client-api-changes: try to fix rst formatting again
2014-07-06 17:05:45 +00:00
::
DOCS/client-api-changes.rst: fix formatting
2019-10-22 13:48:34 +00:00
Release 0.31.0
2019-12-28 11:07:07 +00:00
--- mpv 0.31.0 ---
client API: deprecate tick event This is conceptually outdated and should not exist. This affects Lua scripting and JSON IPC too.
2019-12-22 13:35:32 +00:00
1.107 - Deprecate MPV_EVENT_TICK
Release 0.31.0
2019-12-28 11:07:07 +00:00
--- mpv 0.30.0 ---
stream_cb: add cancel_fn callback This allows stream_cb backends to implement blocking behavior inside read_fn, and still get notified when the user wants to cancel and stop playback. Signed-off-by: Aman Gupta <aman@tmm1.net>
2019-09-26 23:11:48 +00:00
1.106 - Add cancel_fn to mpv_stream_cb_info
client API: fix potential deadlock problems by throwing more shit at it The render API (vo_libmpv) had potential deadlock problems with MPV_RENDER_PARAM_ADVANCED_CONTROL. This required vd-lavc-dr to be enabled (the default). I never observed these deadlocks in the wild (doesn't mean they didn't happen), although I could specifically provoke them with some code changes. The problem was mostly about DR (direct rendering, letting the video decoder write to OpenGL buffer memory). Allocating/freeing a DR image needs to be done on the OpenGL thread, even though _lots_ of threads are involved with handling images. Freeing a DR image is a special case that can happen any time. dr_helper.c does most of the evil magic of achieving this. Unfortunately, there was a (sort of) circular lock dependency: freeing an image while certain internal locks are held would trigger the user's context update callback, which in turn would call mpv_render_context_update(), which processed all pending free requests, and then acquire an internal lock - which the caller might not release until a further DR image could be freed. "Solve" this by making freeing DR images asynchronous. This is slightly risky, but actually not much. The DR images will be free'd eventually. The biggest disadvantage is probably that debugging might get trickier. Any solution to this problem will probably add images to free to some sort of queue, and then process it later. I considered making this more explicit (so there'd be a point where the caller forcibly waits for all queued items to be free'd), but discarded these ideas as this probably would only increase complexity. Another consequence is that freeing DR images on the GL thread is not synchronous anymore. Instead, it mpv_render_context_update() will do it with a delay. This seems roundabout, but doesn't actually change anything, and avoids additional code. This also fixes that the render API required the render API user to remain on the same thread, even though this wasn't documented. As such, it was a bug. OpenGL essentially forces you to do all GL usage on a single thread, but in theory the API user could for example move the GL context to another thread. The API bump is because I think you can't make enough noise about this. Since we don't backport fixes to old versions, I'm specifically stating that old versions are broken, and I'm supplying workarounds. Internally, dr_helper_create() does not use pthread_self() anymore, thus the vo.c change. I think it's better to make binding to the current thread as explicit as possible. Of course it's not sure that this fixes all deadlocks (probably not).
2019-09-26 12:07:33 +00:00
1.105 - Fix deadlock problems with MPV_RENDER_PARAM_ADVANCED_CONTROL and if
the "vd-lavc-dr" option is enabled (which it is by default).
There were no actual API changes.
API users on older API versions and mpv releases should set
"vd-lavc-dr" to "no" to avoid these issues.
client API: be explicit about usage rules and deadlocks some more I think a popular libmpv application did exactly this: enabling advanced control, and then receiving deadlocks. I didn't confirm it, though. In any case, the API docs should avoid tricking users into making this easy mistake.
2019-09-26 12:09:14 +00:00
API users must still adhere to the tricky rules documented in render.h
to avoid other deadlocks.
drm: fix libmpv ABI breakage introduced in 351c083487050c88adb0e3d60f2174850f869018 Extending the client-allocated mpv_opengl_drm_params struct constituted a break of ABI that could cause UB. Create a clean break by deprecating "drm_params" and related structs and enum values, and replacing it with "drm_params_v2". Also fix some comments and code that wrongly assumed that open could return any other negative number than -1 for failure. This commit updates the libmpv version to 1.104
2019-09-12 19:00:50 +00:00
1.104 - Deprecate struct mpv_opengl_drm_params. Replaced by mpv_opengl_drm_params_v2
- Deprecate MPV_RENDER_PARAM_DRM_DISPLAY. Replaced by MPV_RENDER_PARAM_DRM_DISPLAY_V2.
Merge commit '559a400ac36e75a8d73ba263fd7fa6736df1c2da' into wm4-commits--merge-edition This bumps libmpv version to 1.103
2018-12-05 18:02:03 +00:00
1.103 - redo handling of async commands
client API: add returning of data from async commands This was not done sooner out of laziness.
2018-05-10 12:33:10 +00:00
- add mpv_event_command and make it possible to return values from
commands issued with mpv_command_async() or mpv_command_node_async()
command: add a way to abort asynchronous commands Many asynchronous commands are potentially long running operations, such as loading something from network or running a foreign process. Obviously it shouldn't just be possible for them to freeze the player if they don't terminate as expected. Also, there will be situations where you want to explicitly stop some of those operations explicitly. So add an infrastructure for this. Commands have to support this explicitly. The next commit uses this to actually add support to a command.
2018-05-12 16:46:37 +00:00
- add mpv_abort_async_command()
drm: rename plane options to better, invariant, names This commit bumps the libmpv version to 1.102 drm-osd-plane -> drm-draw-plane drm-video-plane -> drm-drmprime-video-plane drm-osd-size -> drm-draw-surface-size "draw plane", as in the plane that OpenGL draws to, whether it be video + OSD or just OSD. "drmprime video plane", as in the plane used for hwdec video imported via drmprime. "draw surface size", as in the size of the surface used for the draw plane The new names are invariant whether or not hwdec_drmprime_drm is being used or not. The original naming was very confusing, as when doing regular rendering (swdec or vaapi) the video would be displayed on the "OSD plane", and the "Video plane" would remain unused.
2018-12-01 11:01:17 +00:00
1.102 - rename struct mpv_opengl_drm_osd_size to mpv_opengl_drm_draw_surface_size
- rename MPV_RENDER_PARAM_DRM_OSD_SIZE to MPV_RENDER_PARAM_DRM_DRAW_SURFACE_SIZE
DOCS/client-api-changes: try to fix rst formatting again
2014-07-06 17:05:45 +00:00
vo: make opengl-cb first in the autoprobing order This should be helpful for the new OSX Cocoa backend, which uses opengl-cb internally. Since it comes with a behavior change that could possibly interfere with libmpv/opengl_cb users, we mark it as explicit API change.
2018-02-12 23:49:13 +00:00
--- mpv 0.29.0 ---
client API: preparations for allowing render API to use DR etc. DR (letting the decoder allocate texture memory) requires running the allocation on the render thread. This is rather hard with the render API, because the user controls this thread and when it's entered. It was not possible until now. This commit adds a bunch of infrastructure to make this possible. We add a new optional mode (MPV_RENDER_PARAM_ADVANCED_CONTROL) which basically lets the user's render thread and libmpv agree how this should be done. Misuse would lead to deadlocks. To make this less likely, strictly document thread safety/locking issues. In particular, document which libmpv functions can be called without issues. (The rest has to be assumed unsafe.) The worst issue is destruction of the render context while video is still active. To avoid certain unintended recursive locks (i.e. deadlocks, unless we'd make the locks recursive), make the update callback lock separate. Make "killing" the video chain asynchronous, so we can do extra work while video is being destroyed. Because losing wakeups is a big deal, setting the update callback now triggers a wakeup. (It would have been better if the wakeup callback were a parameter to mpv_render_context_create(), but too late.) This commit does not add DR yet; the following commit does this.
2018-04-20 17:26:04 +00:00
1.101 - add MPV_RENDER_PARAM_ADVANCED_CONTROL and related API
client API: add some render API extensions for timing Attempts to enable the following things: - let a render API user do "proper" audio-sync video timing itself - make it possible to not re-render repeated frames if the API user has better mechanisms available (e.g. waiting for a DisplayLink cycle instead) - allow the user to delay or skip redraws if it makes sense Basically this information will be needed by API users who want to be "clever" about optimizing timing and rendering.
2018-04-20 22:26:58 +00:00
- add MPV_RENDER_PARAM_NEXT_FRAME_INFO and related symbols
- add MPV_RENDER_PARAM_BLOCK_FOR_TARGET_TIME
- add MPV_RENDER_PARAM_SKIP_RENDERING
- add mpv_render_context_get_info()
client API: add a new way to pass X11 Display etc. to render API Hardware decoding things often need access to additional handles from the windowing system, such as the X11 or Wayland display when using vaapi. The opengl-cb had nothing dedicated for this, and used the weird GL_MP_MPGetNativeDisplay GL extension (which was mpv specific and not officially registered with OpenGL). This was awkward, and a pain due to having to emulate GL context behavior (like needing a TLS variable to store context for the pseudo GL extension function). In addition (and not inherently due to this), we could pass only one resource from mpv builtin context backends to hwdecs. It was also all GL specific. Replace this with a newer mechanism. It works for all RA backends, not just GL. the API user can explicitly pass the objects at init time via mpv_render_context_create(). Multiple resources are naturally possible. The API uses MPV_RENDER_PARAM_* defines, but internally we use strings. This is done for 2 reasons: 1. trying to leave libmpv and internal mechanisms decoupled, 2. not having to add public API for some of the internal resource types (especially D3D/GL interop stuff). To remain sane, drop support for obscure half-working opengl-cb things, like the DRM interop (was missing necessary things), the RPI window thing (nobody used it), and obscure D3D interop things (not needed with ANGLE, others were undocumented). In order not to break ABI and the C API, we don't remove the associated structs from opengl_cb.h. The parts which are still needed (in particular DRM interop) needs to be ported to the render API.
2018-03-22 16:05:01 +00:00
1.100 - bump API number to avoid confusion with mpv release versions
- actually apply the GL_MP_MPGetNativeDisplay change for the new render
API. This also means compatibility for anything but x11 and wayland
through the old opengl-cb GL_MP_MPGetNativeDisplay method is now
unsupported.
client API: deprecate mpv_get_wakeup_pipe() I don't think anything even uses it.
2018-03-23 15:24:17 +00:00
- deprecate mpv_get_wakeup_pipe(). It's complex, but easy to replace
using normal API (just set a wakeup callback to a function which
writes to a pipe).
client API: add a first class hook API, and deprecate old API As it turns out, there are multiple libmpv users who saw a need to use the hook API. The API is kind of shitty and was never meant to be actually public (it was mostly a hack for the ytdl script). Introduce a proper API and deprecate the old one. The old one will probably continue to work for a few releases, but will be removed eventually. There are some slight changes to the old API, but if a user followed the manual properly, it won't break. Mostly untested. Appears to work with ytdl_hook.
2018-03-23 15:24:49 +00:00
- add a 1st class hook API, which replaces the hacky mpv_command()
based one. The old API is deprecated and will be removed soon. The
old API was never meant to be stable, while the new API is.
client API: cleanup mpv_handle termination This changes how mpv_terminate_destroy() and mpv_detach_destroy() behave. The doxygen in client.h tries to point out the differences. The goal is to make this more useful to the API user (making it behave like refcounting). This will be refined in follow up commits. Initialization is unfortunately closely tied to termination, so that changes as well. This also removes earlier hacks that make sure that some parts of FFmpeg initialization are run in the playback thread (instead of the user's thread). This does not matter with standard FFmpeg, and I have no reason to care about this anymore.
2018-03-09 03:46:09 +00:00
1.29 - the behavior of mpv_terminate_destroy() and mpv_detach_destroy()
changes subtly (see documentation in the header file). In particular,
mpv_detach_destroy() will not leave the player running in all
situations anymore (it gets closer to refcounting).
client API: rename mpv_detach_destroy() to mpv_destroy() Since this has clearer semantics now, the old name is just clunky and confusing.
2018-03-09 05:05:50 +00:00
- rename mpv_detach_destroy() to mpv_destroy() (the old function will
remain valid as deprecated alias)
client API: add mpv_create_weak_client()
2018-03-09 05:00:51 +00:00
- add mpv_create_weak_client(), which makes use of above changes
client API: send MPV_EVENT_SHUTDOWN only once Before this change, mpv_wait_event() could inconsistently return multiple MPV_EVENT_SHUTDOWN events to a single mpv_handle, up to the point of spamming the event queue under certain circumstances. Change this and just send it exactly once to each mpv_handle. Some client API users might have weird requirements about destroying their state asynchronously (and not reacting immediately to the SHUTDOWN event). This change will help a bit to make this less weird and surprising.
2018-03-09 10:53:48 +00:00
- MPV_EVENT_SHUTDOWN is now returned exactly once if a mpv_handle
should terminate, instead of spamming the event queue with this event
client API: deprecate opengl-cb API and introduce a replacement API The purpose of the new API is to make it useable with other APIs than OpenGL, especially D3D11 and vulkan. In theory it's now possible to support other vo_gpu backends, as well as backends that don't use the vo_gpu code at all. This also aims to get rid of the dumb mpv_get_sub_api() function. The life cycle of the new mpv_render_context is a bit different from mpv_opengl_cb_context, and you explicitly create/destroy the new context, instead of calling init/uninit on an object returned by mpv_get_sub_api(). In other to make the render API generic, it's annoyingly EGL style, and requires you to pass in API-specific objects to generic functions. This is to avoid explicit objects like the internal ra API has, because that sounds more complicated and annoying for an API that's supposed to never change. The opengl_cb API will continue to exist for a bit longer, but internally there are already a few tradeoffs, like reduced thread-safety. Mostly untested. Seems to work fine with mpc-qt.
2018-02-20 12:30:18 +00:00
1.28 - deprecate the render opengl_cb API, and replace it with render.h
and render_gl.h. The goal is allowing support for APIs other than
OpenGL. The old API is emulated with the new API.
Likewise, the "opengl-cb" VO is renamed to "libmpv".
mpv_get_sub_api() is deprecated along the opengl_cb API.
The new API is relatively similar, but not the same. The rough
equivalents are:
mpv_opengl_cb_init_gl => mpv_render_context_create
mpv_opengl_cb_set_update_callback => mpv_render_context_set_update_callback
mpv_opengl_cb_draw => mpv_render_context_render
mpv_opengl_cb_report_flip => mpv_render_context_report_swap
mpv_opengl_cb_uninit_gl => mpv_render_context_free
The VO opengl-cb is also renamed to "libmpv".
client API: add a new way to pass X11 Display etc. to render API Hardware decoding things often need access to additional handles from the windowing system, such as the X11 or Wayland display when using vaapi. The opengl-cb had nothing dedicated for this, and used the weird GL_MP_MPGetNativeDisplay GL extension (which was mpv specific and not officially registered with OpenGL). This was awkward, and a pain due to having to emulate GL context behavior (like needing a TLS variable to store context for the pseudo GL extension function). In addition (and not inherently due to this), we could pass only one resource from mpv builtin context backends to hwdecs. It was also all GL specific. Replace this with a newer mechanism. It works for all RA backends, not just GL. the API user can explicitly pass the objects at init time via mpv_render_context_create(). Multiple resources are naturally possible. The API uses MPV_RENDER_PARAM_* defines, but internally we use strings. This is done for 2 reasons: 1. trying to leave libmpv and internal mechanisms decoupled, 2. not having to add public API for some of the internal resource types (especially D3D/GL interop stuff). To remain sane, drop support for obscure half-working opengl-cb things, like the DRM interop (was missing necessary things), the RPI window thing (nobody used it), and obscure D3D interop things (not needed with ANGLE, others were undocumented). In order not to break ABI and the C API, we don't remove the associated structs from opengl_cb.h. The parts which are still needed (in particular DRM interop) needs to be ported to the render API.
2018-03-22 16:05:01 +00:00
Also, the GL_MP_MPGetNativeDisplay pseudo extension is not used by the
render API anymore, and the old opengl-cb API only handles the "x11"
and "wl" names anymore. Support for everything else has been removed.
The new render API uses proper API parameters, e.g. for X11 you pass
MPV_RENDER_PARAM_X11_DISPLAY directly.
client API: deprecate qthelper.hpp It's a WTF that we have something as specific in the API. It could be argued that we should provide helpers for other language and GUI toolkit combinations. Obviously that's not going to scale, and it's somewhat likely that it will bitrot. The rest is said in the API changelog.
2018-03-13 09:45:17 +00:00
- deprecate the qthelper.hpp header file. This provided some C++ helper
utility functions for Qt with use of libmpv. There is no reason to
keep this in the mpv git repository, nor to make it part of the libmpv
API. If you're using this header, you can safely copy it into your
project - it uses only libmpv public API. Alternatively, it could be
maintained in a separate repository by interested parties.
vo: make opengl-cb first in the autoprobing order This should be helpful for the new OSX Cocoa backend, which uses opengl-cb internally. Since it comes with a behavior change that could possibly interfere with libmpv/opengl_cb users, we mark it as explicit API change.
2018-02-12 23:49:13 +00:00
1.27 - make opengl-cb the default VO. This causes a subtle behavior change
if the API user called mpv_opengl_cb_init_gl(), but does not set
the "vo" option. Before, it would still have used another VO (like
on the CLI, e.g. vo=gpu). Now it'll behave as if vo=opengl-cb was
used.
options: drop some previously deprecated options A release has been made, so drop options deprecated for that release. Also drop some options which have been deprecated a much longer time before. Also fix a typo in client-api-changes.rst.
2017-12-25 10:43:04 +00:00
--- mpv 0.28.0 ---
client API: minor bump + change entry for DRM related opengl-cb changes Commit cfcee4cfe705 forgot those.
2017-10-23 19:11:31 +00:00
1.26 - remove glMPGetNativeDisplay("drm") support
- add mpv_opengl_cb_window_pos and mpv_opengl_cb_drm_params and
support via glMPGetNativeDisplay() for using it
client API: change --stop-playback-on-init-failure default This was off for mpv CLI, but on for libmpv. The motivation behind this was that it would be confusing for applications if libmpv continued playback in a severely "degraded" way (without either audio or video), and that it would be better to fail early. In reality the behavior was just a confusing difference to mpv CLI, and has confused actual users as well. Get rid of it. Not bothering with a version bump, since this is so minor, and it's easy to ensure compatibility in affected applications by just setting the option explicitly. (Also adding the missing next-release-marker in client-api-changes.rst.)
2017-12-17 13:03:33 +00:00
- make --stop-playback-on-init-failure=no the default in libmpv (just
like in mpv CLI)
Release 0.27.0
2017-09-13 01:40:14 +00:00
--- mpv 0.27.0 ---
client API: drop old "no-" option emulation You could do mpv_set_option(h, "no-fs", ""), which would behave like "--no-fs" on the command line. At one point, this had to be emulated for compatibility, and printed a deprecation warning. This was almost a year ago, so remove it.
2017-06-26 17:55:40 +00:00
1.25 - remove setting "no-" options via mpv_set_option*(). (See corresponding
deprecation in 0.23.0.)
client API: add MPV_ENABLE_DEPRECATED symbol (Of course this is on by default, because otherwise we'd randomly break downstream applications.)
2017-04-20 04:16:23 +00:00
--- mpv 0.25.0 ---
1.24 - add a MPV_ENABLE_DEPRECATED preprocessor symbol, which can be defined
by the user to exclude deprecated API symbols from the C headers
client API: turn mpv_suspend() and mpv_resume() into stubs As threatened by the API changes document. This commit also removes or stubs equivalent calls in IPC and Lua scripting. The stubs are left to maintain ABI compatibility. The semantics of the API functions have been close enough to doing nothing that this probably won't even break existing API users. Probably.
2016-11-22 13:47:50 +00:00
--- mpv 0.23.0 ---
1.24 - the deprecated mpv_suspend() and mpv_resume() APIs now do nothing.
DOCS: update interface changes
2016-11-20 16:37:22 +00:00
--- mpv 0.22.0 ---
client API: deprecate "no-..." option handling The client API can do this (and there are apparently some libmpv using projects which rely on this). But it's just unnecessary bloat as it requires a separate code path from the option parser. It would be better to remove this code. Formally deprecate it, including API bump and warning in the API changes file to make it really clear.
2016-08-31 15:28:42 +00:00
1.23 - deprecate setting "no-" options via mpv_set_option*(). For example,
instead of "no-video=" you should set "video=no".
client API: remove SIGPIPE overriding code This workaround prevented that libmpv users could accidentally crash when the SIGPIPE signal was triggered by FFmpeg's OpenSSL/GnuTLS usage. But it also modifies the global signal handler state, so remove it now that this workaround is not required anymore.
2016-09-15 11:13:23 +00:00
- do not override the SIGPIPE signal handler anymore. This was done as
workaround for the FFmpeg TLS code, which has been fixed long ago.
client API: declare mpv_suspend/mpv_resume deprecated They're useless, and I have no idea what they're actually supposed to do (wrt. pending input processing changes). Also remove their implicit uses from the IPC handlers.
2016-09-16 12:24:31 +00:00
- deprecate mpv_suspend() and mpv_resume(). They will be stubbed out
Fix some future release version numbers Since the recent release was named 0.22.0 instead of 0.21.1, bump all mentions of 0.22.0 to 0.23.0. These were planned removals of deprecated versions, which obviously didn't happen in 0.22.0.
2016-11-21 19:17:41 +00:00
in mpv 0.23.0.
client API: more or less deprecate mpv_set_option() With the merging of options and properties, the mpv_set_option() function is close to being useless, and mpv_set_property() can be used for everything instead. There are certain conflicts remaining, which are explained in depth in the docs. For now, none of this should affect existing code using the client API. Make mpv_set_property() redirect to mpv_set_option() before initialization. Remove some options marked as M_OPT_FIXED. The "pause" and "speed" options cannot be written anymore without the playloop being notified by it, so the M_OPT_FIXED does nothing. For "vo-mmcss-profile", the problem was lack of synchronization, which has been added. I'm not sure what the problem was with "frames" - I think it was only marked as M_OPT_FIXED because changing it during playback will have no effect. Except for pause/speed, these changes are needed to make them writable as properties after mpv_initialize(). Also replace all remaining uses of CONF_GLOBAL with M_OPT_FIXED.
2016-09-21 14:19:56 +00:00
- make mpv_set_property() work to some degree before mpv_initialize().
It can now be used instead of mpv_set_option().
- semi-deprecate mpv_set_option()/mpv_set_option_string(). You should
use mpv_set_property() instead. There are some deprecated properties
which conflict with some options (see client.h remarks on
mpv_set_option()), for which mpv_set_option() might still be required.
In future mpv releases, the conflicting deprecated options/properties
will be removed, and mpv_set_option() will internally translate API
calls to mpv_set_property().
qthelper: introduce new convenience functions (Why the heck is the C++ helper not in a separate repository?)
2016-09-26 14:45:55 +00:00
- qthelper.hpp: deprecate get_property_variant, set_property_variant,
DOCS/client-api-changes.rst: fix typo
2016-11-15 22:49:09 +00:00
set_option_variant, command_variant, and replace them with
get_property, set_property, command.
client API: deprecate "no-..." option handling The client API can do this (and there are apparently some libmpv using projects which rely on this). But it's just unnecessary bloat as it requires a separate code path from the option parser. It would be better to remove this code. Formally deprecate it, including API bump and warning in the API changes file to make it really clear.
2016-08-31 15:28:42 +00:00
--- mpv 0.19.0 ---
client API: bump API for stream_cb Forgotten in previous commit. Also minor semi-related change: remove the extra "," from the mpv_sub_api enum, which I accidentally added in the previous commit. (C99 is fine with trailing ",", C89 strictly speaking not. So do this for maximum compatibility.)
2016-08-07 17:40:17 +00:00
1.22 - add stream_cb API for custom protocols
client API: remove "status" log level from mpv_request_event docs Although it appears to be accepted by the function, MSGL_STATUS messages are never passed to the client API. Consequently "status" has the same meaning as "v" and is useless.
2016-07-08 12:11:52 +00:00
--- mpv 0.18.1 ---
---- - remove "status" log level from mpv_request_log_messages() docs. This
is 100% equivalent to "v". The behavior is still the same, thus no
actual API change.
DOCS: change version references from 0.17.1 to 0.18.0 0.17.1 was never released, so the actual 0.18.0 release takes its place.
2016-06-25 10:39:08 +00:00
--- mpv 0.18.0 ---
client API: improve mpv_set_property() handling of MPV_FORMAT_NODE If a mpv_node wrapped a string, the behavior was different from calling mpv_set_property() with MPV_FORMAT_STRING directly. Change this. The original intention was to be strict about types if MPV_FORMAT_NODE is used. But I think the result was less than ideal, and the same change towards less strict behavior was made to mpv_set_option() ages ago.
2016-04-15 09:31:24 +00:00
1.21 - mpv_set_property() changes behavior with MPV_FORMAT_NODE. Before this
change it rejected mpv_nodes with format==MPV_FORMAT_STRING if the
property was not a string or did not have special mechanisms in place
the function failed. Now it always invokes the option string parser,
and mpv_node with a basic data type works exactly as if the function
is invoked with that type directly. This new behavior is equivalent
to mpv_set_option().
This also affects the mp.set_property_native() Lua function.
client API: access choices as flags if appropriate Options/properties that are choices, and which include "yes" or "no" values (or both) can now be read and written as MPV_FORMAT_FLAG. For write access, rejecting flags in these cases was obnoxiously unintuitive and inconvenient. For read access, the value of this is less convincing, and actually it's a major API change. At this point I probably have to admit that the finer details of the client API are very unstable.
2016-05-04 15:37:54 +00:00
- generally, setting choice options/properties with "yes"/"no" options
can now be set as MPV_FORMAT_FLAG
- reading a choice property as MPV_FORMAT_NODE will now return a
MPV_FORMAT_FLAG value if the choice is "yes" (true) or "no" (false)
This implicitly affects Lua and JSON IPC interfaces as well.
vo_opengl: apply vo-cmdline command incrementally Instead of implicitly resetting the options to defaults and then applying the options, they're always applied on top of the current options (in the same way adding new options to the CLI command line will). This does not apply to vo_opengl_cb, because that has an even worse mess which I refuse to deal with.
2016-06-05 14:56:34 +00:00
- big changes to vo-cmdline on vo_opengl and vo_opengl_hq (but not
vo_opengl_cb): options are now normally not reset, but applied on top
of the current options. The special undocumented value "-" still
works, but now resets all options to before any vo-cmdline command
has been called.
client API: rename GL_MP_D3D_interfaces This is a pseudo-OpenGL extension for letting libmpv query native windowing system handles from the API user. (It uses the OpenGL extension mechanism because I'm lazy. In theory it would be nicer to let the user pass them with mpv_opengl_cb_init_gl(), but this would require a more intrusive API change to extend its argument list.) The naming of the extension and associated function was unnecessarily Windows specific (using "D3D"), even though it would work just fine for other platforms. So deprecate the old names and introduce new ones. The old ones still work.
2015-09-24 19:07:16 +00:00
--- mpv 0.12.0 ---
1.20 - deprecate "GL_MP_D3D_interfaces"/"glMPGetD3DInterface", and introduce
"GL_MP_MPGetNativeDisplay"/"glMPGetNativeDisplay" (this is a
backwards-compatible rename)
DOCS: update client API changes for release
2015-09-22 23:12:15 +00:00
--- mpv 0.11.0 ---
client API: rename GL_MP_D3D_interfaces This is a pseudo-OpenGL extension for letting libmpv query native windowing system handles from the API user. (It uses the OpenGL extension mechanism because I'm lazy. In theory it would be nicer to let the user pass them with mpv_opengl_cb_init_gl(), but this would require a more intrusive API change to extend its argument list.) The naming of the extension and associated function was unnecessarily Windows specific (using "D3D"), even though it would work just fine for other platforms. So deprecate the old names and introduce new ones. The old ones still work.
2015-09-24 19:07:16 +00:00
--- mpv 0.10.0 ---
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
1.19 - add "GL_MP_D3D_interfaces" pseudo extension to make it possible to
client API, dxva2: add a workaround for OpenGL fullscreen issues This is basically a hack for drivers which prevent the mpv DXVA2 decoder glue from working if OpenGL is in fullscreen mode. Since it doesn't add any "hard" new API to the client API, some of the code would be required for a true zero-copy hw decoding pipeline, and sine it isn't too much code after all, this is probably acceptable.
2015-07-03 14:37:01 +00:00
use DXVA2 in OpenGL fullscreen mode in some situations
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_request_log_messages() now accepts "terminal-default" as parameter
client API: add MPV_END_FILE_REASON_REDIRECT Requested. Minor incompatible behavior change, as it was signalling MPV_END_FILE_REASON_EOF previously.
2015-06-11 19:39:48 +00:00
1.18 - add MPV_END_FILE_REASON_REDIRECT, and change behavior of
MPV_EVENT_END_FILE accordingly
- a bunch of interface-changes.rst changes
Always block SIGPIPE globally OpenSSL and GnuTLS are still causing this problem (although FFmpeg could be blamed as well - but not really). In particular, it was happening to libmpv users and in cases the pseudo-gui profile is used. This was because all signal handling is in the terminal code, so if terminal is disabled, it won't be set. This was obviously a questionable shortcut. Avoid further problems by always blocking the signal. This is done even for libmpv, despite our policy of not messing with global state. Explicitly document this in the libmpv docs. It turns out that a version bump to 1.17 was forgotten for the addition of MPV_FORMAT_BYTE_ARRAY, so document that change as part of 1.16.
2015-05-11 15:38:35 +00:00
1.17 - mpv_initialize() now blocks SIGPIPE (details see client.h)
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 ---
vo_opengl_cb: add a function to report vsync time And also let vo.c know of it. Currently, this does not help much, but will facilitate future improvements.
2015-04-09 17:30:26 +00:00
1.16 - add mpv_opengl_cb_report_flip()
vo_opengl_cb: deprecate mpv_opengl_cb_render() Its vp parameter made no sense anymore. Introduce a new one.
2015-04-09 17:31:01 +00:00
- introduce mpv_opengl_cb_draw() and deprecate mpv_opengl_cb_render()
Always block SIGPIPE globally OpenSSL and GnuTLS are still causing this problem (although FFmpeg could be blamed as well - but not really). In particular, it was happening to libmpv users and in cases the pseudo-gui profile is used. This was because all signal handling is in the terminal code, so if terminal is disabled, it won't be set. This was obviously a questionable shortcut. Avoid further problems by always blocking the signal. This is done even for libmpv, despite our policy of not messing with global state. Explicitly document this in the libmpv docs. It turns out that a version bump to 1.17 was forgotten for the addition of MPV_FORMAT_BYTE_ARRAY, so document that change as part of 1.16.
2015-05-11 15:38:35 +00:00
- add MPV_FORMAT_BYTE_ARRAY
player, client API: refactor cplayer init, reduce client API differences Move the command line parsing and some other things to the common init routine shared between command line player and client API. This means they're using almost exactly the same code now. The main intended side effect is that the client API will load mpv.conf; though still only if config loading is enabled. (The cplayer still avoids creating an extra thread, passes a command line, and prints an exit status to the terminal. It also has some different defaults.)
2015-03-05 10:17:22 +00:00
1.15 - mpv_initialize() will now load config files. This requires setting
the "config" and "config-dir" options. In particular, it will load
mpv.conf.
client API: mention the changes to the seek/screenshot commands Also fix a typo in the manpage.
2015-03-05 11:41:43 +00:00
- minor backwards-compatible change to the "seek" and "screenshot"
commands (new flag syntax, old additional args deprecated)
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.8.0 ---
client API: add mpv_wait_async_requests() This does what it's documented to do. The implementation reuses the code in mpv_detach_destroy(). Due to the way async requests currently work, just sending a synchronous dummy request (like a "ignore" command) would be enough to ensure synchronization, but this code will continue to work even if this changes. The line "ctx->event_mask = 0;" is removed, but it shouldn't be needed. (If a client is somehow very slow to terminate, this could silence an annoying queue overflow message, but all in all it does nothing.) Calling mpv_wait_async_requests() and mpv_wait_event() concurrently is in theory allowed, so change pthread_cond_signal() to pthread_cond_broadcast() to avoid missed wakeups. As requested in issue #1542.
2015-02-02 16:24:33 +00:00
1.14 - add mpv_wait_async_requests()
DOCS/client-api-changes: mark 0.8.0 release (There was a missing version bump for the msg-level change; just move it under 1.14.)
2015-02-17 22:42:25 +00:00
- the --msg-level option changes its native type from a flat string to
a key-value list (setting/reading the option as string still works)
client API: notify API user on event queue overflow Before this, we merely printed a message to the terminal. Now the API user can determine this properly. This might be important for API users which somehow maintain complex state, which all has to be invalidated if (state-changing) events are missing due to an overflow. This also forces the client API user to empty the event queue, which is good, because otherwise the event queue would reach the "filled up" state immediately again due to further asynchronous events being added to the queue. Also add some minor improvements to mpv_wait_event() documentation, and some other minor cosmetic changes.
2015-01-19 18:54:20 +00:00
1.13 - add MPV_EVENT_QUEUE_OVERFLOW
client API: qthelper: add a refcounting wrapper around mpv_handle This is useful to deal with crazy Qt object lifetime issues (the following commit needs it).
2014-12-30 21:24:57 +00:00
1.12 - add class Handle to qthelper.hpp
client API: add function to create new mpv_handles from existing ones This may or may not be useful for client API users. Fold this API extension into the previous API bump. The previous bump was only yesterday, so it's ok.
2014-12-31 19:32:35 +00:00
- improve opengl_cb.h API uninitialization behavior, and fix the qml
example
- add mpv_create_client() function
client API: expose OpenGL renderer This adds API to libmpv that lets host applications use the mpv opengl renderer. This is a more flexible (and possibly more portable) option to foreign window embedding (via --wid). This assumes that methods like context sharing and multithreaded OpenGL rendering are infeasible, and that a way is needed to integrate it with an application that uses a single thread to render everything. Add an example that does this with QtQuick/qml. The example is relatively lazy, but still shows how relatively simple the integration is. The FBO indirection could probably be avoided, but would require more work (and would probably lead to worse QtQuick integration, because it would have to ignore transformations like rotation). Because this makes mpv directly use the host application's OpenGL context, there is no platform specific code involved in mpv, except for hw decoding interop. main.qml is derived from some Qt example. The following things are still missing: - a way to do better video timing - expose GL renderer options, allow changing them at runtime - support for color equalizer controls - support for screenshots
2014-12-09 16:47:02 +00:00
1.11 - add OpenGL rendering interop API - allows an application to combine
its own and mpv's OpenGL rendering
Warning: this API is not stable yet - anything in opengl_cb.h might
be changed in completely incompatible ways in minor API bumps
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.7.0 ---
input, lua: redo input handling Much of it is the same, but now there's the possibility to distinguish key down/up events in the Lua API.
2014-11-23 14:08:49 +00:00
1.10 - deprecate/disable everything directly related to script_dispatch
(most likely affects nobody)
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: qthelper: add set_option_variant()
2014-10-30 10:26:31 +00:00
- add qthelper.hpp set_option_variant()
client API: deprecate some events Following the discussion in #1253. The events won't be removed for a while, though. (Or maybe never, unless we run out of bits for the uint64_t event mask.) This is not a real change (the events still work, and the alternative mechanisms were established a few API revisions earlier), but for the sake of notifying API users, update DOCS/client-api-changes.rst.
2014-11-08 08:59:38 +00:00
- mark the following events as deprecated:
MPV_EVENT_TRACKS_CHANGED
MPV_EVENT_TRACK_SWITCHED
MPV_EVENT_PAUSE
MPV_EVENT_UNPAUSE
MPV_EVENT_METADATA_UPDATE
MPV_EVENT_CHAPTER_CHANGE
They are handled better with mpv_observe_property() as mentioned in
the documentation comments. They are not removed and still work.
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)
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.6.0 ---
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: 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.5.0 ---
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: 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.4.0 ---
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