1Introduction 2============ 3 4This file lists all changes that can cause compatibility issues when using 5mpv through the client API (libmpv and ``client.h``). Since the client API 6interfaces to input handling (commands, properties) as well as command line 7options, you should also look at ``interface-changes.rst``. 8 9Normally, changes to the C API that are incompatible to previous iterations 10receive a major version bump (i.e. the first version number is increased), 11while C API additions bump the minor version (i.e. the second number is 12increased). Changes to properties/commands/options may also lead to a minor 13version bump, in particular if they are incompatible. 14 15The version number is the same as used for MPV_CLIENT_API_VERSION (see 16``client.h`` how to convert between major/minor version numbers and the flat 1732 bit integer). 18 19Also, read the section ``Compatibility`` in ``client.h``, and compatibility.rst. 20 21Options, commands, properties 22============================= 23 24Changes to these are not listed here, but in ``interface-changes.rst``. (Before 25client API version 1.17, they were listed here partially.) 26 27This listing includes changes to the bare C API and behavior only, not what 28you can access with them. 29 30API changes 31=========== 32 33:: 34 35 --- mpv 0.33.0 --- 36 1.109 - add MPV_RENDER_API_TYPE_SW and related (software rendering API) 37 - inactivate the opengl_cb API (always fails to initialize now) 38 The opengl_cb API was deprecated over 2 years ago. Use the render API 39 instead. 40 1.108 - Deprecate MPV_EVENT_IDLE 41 - add mpv_event_start_file 42 - add the following fields to mpv_event_end_file: playlist_entry_id, 43 playlist_insert_id, playlist_insert_num_entries 44 - add mpv_event_to_node() 45 - add mpv_client_id() 46 1.107 - Remove the deprecated qthelper.hpp. This was obviously not part of the 47 libmpv API, only an "additionally" provided helper, thus this is not 48 considered an API change. If you are maintaining a project that relies 49 on this header, you can simply download this file and adjust the 50 include statement to use it instead: 51 52 https://raw.githubusercontent.com/mpv-player/mpv/v0.32.0/libmpv/qthelper.hpp 53 54 It is a good idea to write better wrappers for your use, though. 55 --- mpv 0.31.0 --- 56 1.107 - Deprecate MPV_EVENT_TICK 57 58 --- mpv 0.30.0 --- 59 1.106 - Add cancel_fn to mpv_stream_cb_info 60 1.105 - Fix deadlock problems with MPV_RENDER_PARAM_ADVANCED_CONTROL and if 61 the "vd-lavc-dr" option is enabled (which it is by default). 62 There were no actual API changes. 63 API users on older API versions and mpv releases should set 64 "vd-lavc-dr" to "no" to avoid these issues. 65 API users must still adhere to the tricky rules documented in render.h 66 to avoid other deadlocks. 67 1.104 - Deprecate struct mpv_opengl_drm_params. Replaced by mpv_opengl_drm_params_v2 68 - Deprecate MPV_RENDER_PARAM_DRM_DISPLAY. Replaced by MPV_RENDER_PARAM_DRM_DISPLAY_V2. 69 1.103 - redo handling of async commands 70 - add mpv_event_command and make it possible to return values from 71 commands issued with mpv_command_async() or mpv_command_node_async() 72 - add mpv_abort_async_command() 73 1.102 - rename struct mpv_opengl_drm_osd_size to mpv_opengl_drm_draw_surface_size 74 - rename MPV_RENDER_PARAM_DRM_OSD_SIZE to MPV_RENDER_PARAM_DRM_DRAW_SURFACE_SIZE 75 76 --- mpv 0.29.0 --- 77 1.101 - add MPV_RENDER_PARAM_ADVANCED_CONTROL and related API 78 - add MPV_RENDER_PARAM_NEXT_FRAME_INFO and related symbols 79 - add MPV_RENDER_PARAM_BLOCK_FOR_TARGET_TIME 80 - add MPV_RENDER_PARAM_SKIP_RENDERING 81 - add mpv_render_context_get_info() 82 1.100 - bump API number to avoid confusion with mpv release versions 83 - actually apply the GL_MP_MPGetNativeDisplay change for the new render 84 API. This also means compatibility for anything but x11 and wayland 85 through the old opengl-cb GL_MP_MPGetNativeDisplay method is now 86 unsupported. 87 - deprecate mpv_get_wakeup_pipe(). It's complex, but easy to replace 88 using normal API (just set a wakeup callback to a function which 89 writes to a pipe). 90 - add a 1st class hook API, which replaces the hacky mpv_command() 91 based one. The old API is deprecated and will be removed soon. The 92 old API was never meant to be stable, while the new API is. 93 1.29 - the behavior of mpv_terminate_destroy() and mpv_detach_destroy() 94 changes subtly (see documentation in the header file). In particular, 95 mpv_detach_destroy() will not leave the player running in all 96 situations anymore (it gets closer to refcounting). 97 - rename mpv_detach_destroy() to mpv_destroy() (the old function will 98 remain valid as deprecated alias) 99 - add mpv_create_weak_client(), which makes use of above changes 100 - MPV_EVENT_SHUTDOWN is now returned exactly once if a mpv_handle 101 should terminate, instead of spamming the event queue with this event 102 1.28 - deprecate the render opengl_cb API, and replace it with render.h 103 and render_gl.h. The goal is allowing support for APIs other than 104 OpenGL. The old API is emulated with the new API. 105 Likewise, the "opengl-cb" VO is renamed to "libmpv". 106 mpv_get_sub_api() is deprecated along the opengl_cb API. 107 The new API is relatively similar, but not the same. The rough 108 equivalents are: 109 mpv_opengl_cb_init_gl => mpv_render_context_create 110 mpv_opengl_cb_set_update_callback => mpv_render_context_set_update_callback 111 mpv_opengl_cb_draw => mpv_render_context_render 112 mpv_opengl_cb_report_flip => mpv_render_context_report_swap 113 mpv_opengl_cb_uninit_gl => mpv_render_context_free 114 The VO opengl-cb is also renamed to "libmpv". 115 Also, the GL_MP_MPGetNativeDisplay pseudo extension is not used by the 116 render API anymore, and the old opengl-cb API only handles the "x11" 117 and "wl" names anymore. Support for everything else has been removed. 118 The new render API uses proper API parameters, e.g. for X11 you pass 119 MPV_RENDER_PARAM_X11_DISPLAY directly. 120 - deprecate the qthelper.hpp header file. This provided some C++ helper 121 utility functions for Qt with use of libmpv. There is no reason to 122 keep this in the mpv git repository, nor to make it part of the libmpv 123 API. If you're using this header, you can safely copy it into your 124 project - it uses only libmpv public API. Alternatively, it could be 125 maintained in a separate repository by interested parties. 126 1.27 - make opengl-cb the default VO. This causes a subtle behavior change 127 if the API user called mpv_opengl_cb_init_gl(), but does not set 128 the "vo" option. Before, it would still have used another VO (like 129 on the CLI, e.g. vo=gpu). Now it'll behave as if vo=opengl-cb was 130 used. 131 --- mpv 0.28.0 --- 132 1.26 - remove glMPGetNativeDisplay("drm") support 133 - add mpv_opengl_cb_window_pos and mpv_opengl_cb_drm_params and 134 support via glMPGetNativeDisplay() for using it 135 - make --stop-playback-on-init-failure=no the default in libmpv (just 136 like in mpv CLI) 137 --- mpv 0.27.0 --- 138 1.25 - remove setting "no-" options via mpv_set_option*(). (See corresponding 139 deprecation in 0.23.0.) 140 --- mpv 0.25.0 --- 141 1.24 - add a MPV_ENABLE_DEPRECATED preprocessor symbol, which can be defined 142 by the user to exclude deprecated API symbols from the C headers 143 --- mpv 0.23.0 --- 144 1.24 - the deprecated mpv_suspend() and mpv_resume() APIs now do nothing. 145 --- mpv 0.22.0 --- 146 1.23 - deprecate setting "no-" options via mpv_set_option*(). For example, 147 instead of "no-video=" you should set "video=no". 148 - do not override the SIGPIPE signal handler anymore. This was done as 149 workaround for the FFmpeg TLS code, which has been fixed long ago. 150 - deprecate mpv_suspend() and mpv_resume(). They will be stubbed out 151 in mpv 0.23.0. 152 - make mpv_set_property() work to some degree before mpv_initialize(). 153 It can now be used instead of mpv_set_option(). 154 - semi-deprecate mpv_set_option()/mpv_set_option_string(). You should 155 use mpv_set_property() instead. There are some deprecated properties 156 which conflict with some options (see client.h remarks on 157 mpv_set_option()), for which mpv_set_option() might still be required. 158 In future mpv releases, the conflicting deprecated options/properties 159 will be removed, and mpv_set_option() will internally translate API 160 calls to mpv_set_property(). 161 - qthelper.hpp: deprecate get_property_variant, set_property_variant, 162 set_option_variant, command_variant, and replace them with 163 get_property, set_property, command. 164 --- mpv 0.19.0 --- 165 1.22 - add stream_cb API for custom protocols 166 --- mpv 0.18.1 --- 167 ---- - remove "status" log level from mpv_request_log_messages() docs. This 168 is 100% equivalent to "v". The behavior is still the same, thus no 169 actual API change. 170 --- mpv 0.18.0 --- 171 1.21 - mpv_set_property() changes behavior with MPV_FORMAT_NODE. Before this 172 change it rejected mpv_nodes with format==MPV_FORMAT_STRING if the 173 property was not a string or did not have special mechanisms in place 174 the function failed. Now it always invokes the option string parser, 175 and mpv_node with a basic data type works exactly as if the function 176 is invoked with that type directly. This new behavior is equivalent 177 to mpv_set_option(). 178 This also affects the mp.set_property_native() Lua function. 179 - generally, setting choice options/properties with "yes"/"no" options 180 can now be set as MPV_FORMAT_FLAG 181 - reading a choice property as MPV_FORMAT_NODE will now return a 182 MPV_FORMAT_FLAG value if the choice is "yes" (true) or "no" (false) 183 This implicitly affects Lua and JSON IPC interfaces as well. 184 - big changes to vo-cmdline on vo_opengl and vo_opengl_hq (but not 185 vo_opengl_cb): options are now normally not reset, but applied on top 186 of the current options. The special undocumented value "-" still 187 works, but now resets all options to before any vo-cmdline command 188 has been called. 189 --- mpv 0.12.0 --- 190 1.20 - deprecate "GL_MP_D3D_interfaces"/"glMPGetD3DInterface", and introduce 191 "GL_MP_MPGetNativeDisplay"/"glMPGetNativeDisplay" (this is a 192 backwards-compatible rename) 193 --- mpv 0.11.0 --- 194 --- mpv 0.10.0 --- 195 1.19 - add "GL_MP_D3D_interfaces" pseudo extension to make it possible to 196 use DXVA2 in OpenGL fullscreen mode in some situations 197 - mpv_request_log_messages() now accepts "terminal-default" as parameter 198 1.18 - add MPV_END_FILE_REASON_REDIRECT, and change behavior of 199 MPV_EVENT_END_FILE accordingly 200 - a bunch of interface-changes.rst changes 201 1.17 - mpv_initialize() now blocks SIGPIPE (details see client.h) 202 --- mpv 0.9.0 --- 203 1.16 - add mpv_opengl_cb_report_flip() 204 - introduce mpv_opengl_cb_draw() and deprecate mpv_opengl_cb_render() 205 - add MPV_FORMAT_BYTE_ARRAY 206 1.15 - mpv_initialize() will now load config files. This requires setting 207 the "config" and "config-dir" options. In particular, it will load 208 mpv.conf. 209 - minor backwards-compatible change to the "seek" and "screenshot" 210 commands (new flag syntax, old additional args deprecated) 211 --- mpv 0.8.0 --- 212 1.14 - add mpv_wait_async_requests() 213 - the --msg-level option changes its native type from a flat string to 214 a key-value list (setting/reading the option as string still works) 215 1.13 - add MPV_EVENT_QUEUE_OVERFLOW 216 1.12 - add class Handle to qthelper.hpp 217 - improve opengl_cb.h API uninitialization behavior, and fix the qml 218 example 219 - add mpv_create_client() function 220 1.11 - add OpenGL rendering interop API - allows an application to combine 221 its own and mpv's OpenGL rendering 222 Warning: this API is not stable yet - anything in opengl_cb.h might 223 be changed in completely incompatible ways in minor API bumps 224 --- mpv 0.7.0 --- 225 1.10 - deprecate/disable everything directly related to script_dispatch 226 (most likely affects nobody) 227 1.9 - add enum mpv_end_file_reason for mpv_event_end_file.reason 228 - add MPV_END_FILE_REASON_ERROR and the mpv_event_end_file.error field 229 for slightly better error reporting on playback failure 230 - add --stop-playback-on-init-failure option, and make it the default 231 behavior for libmpv only 232 - add qthelper.hpp set_option_variant() 233 - mark the following events as deprecated: 234 MPV_EVENT_TRACKS_CHANGED 235 MPV_EVENT_TRACK_SWITCHED 236 MPV_EVENT_PAUSE 237 MPV_EVENT_UNPAUSE 238 MPV_EVENT_METADATA_UPDATE 239 MPV_EVENT_CHAPTER_CHANGE 240 They are handled better with mpv_observe_property() as mentioned in 241 the documentation comments. They are not removed and still work. 242 1.8 - add qthelper.hpp 243 1.7 - add mpv_command_node(), mpv_command_node_async() 244 1.6 - modify "core-idle" property behavior 245 - MPV_EVENT_LOG_MESSAGE now always sends complete lines 246 - introduce numeric log levels (mpv_log_level) 247 --- mpv 0.6.0 --- 248 1.5 - change in X11 and "--wid" behavior again. The previous change didn't 249 work as expected, and now the behavior can be explicitly controlled 250 with the "input-x11-keyboard" option. This is only a temporary 251 measure until XEmbed is implemented and confirmed working. 252 Note: in 1.6, "input-x11-keyboard" was renamed to "input-vo-keyboard", 253 although the old option name still works. 254 1.4 - subtle change in X11 and "--wid" behavior 255 (this change was added to 0.5.2, and broke some things, see #1090) 256 --- mpv 0.5.0 --- 257 1.3 - add MPV_MAKE_VERSION() 258 1.2 - remove "stream-time-pos" property (no replacement) 259 1.1 - remap dvdnav:// to dvd:// 260 - add "--cache-file", "--cache-file-size" 261 - add "--colormatrix-primaries" (and property) 262 - add "primaries" sub-field to image format properties 263 - add "playback-time" property 264 - extend the "--start" option; a leading "+", which was previously 265 insignificant is now significant 266 - add "cache-free" and "cache-used" properties 267 - OSX: the "coreaudio" AO spdif code is split into a separate AO 268 --- mpv 0.4.0 --- 269 1.0 - the API is declared stable 270 271