path: root/DOCS/client-api-changes.rst

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, you should also look at ``interface-changes.rst``.

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``, and compatibility.rst.

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.

API changes
===========

::
 --- mpv 0.38.0 ---
 2.3    - partially revert the changes from API version 1.27, remove libmpv as
          the default VO and move it to the bottom of the auto-probing order.
          This restores the prior behavior on all platforms other than macOS,
          but still auto selects libmpv/cocoa-cb on macOS if it was built with
          support for cocoa-cb.
 --- mpv 0.37.0 ---
 2.2    - add mpv_time_ns()
 --- mpv 0.36.0 ---
 2.1    - add mpv_del_property()
 --- mpv 0.35.0 ---
 2.0    - remove headers/functions of the obsolete opengl_cb API
        - remove mpv_opengl_init_params.extra_exts field
        - remove deprecated mpv_detach_destroy. Use mpv_destroy instead.
        - remove obsolete mpv_suspend and mpv_resume
        - remove deprecated SCRIPT_INPUT_DISPATCH, PAUSE and UNPAUSE, TRACKS_CHANGED
          TRACK_SWITCHED, METADATA_UPDATE, CHAPTER_CHANGE events
 --- mpv 0.33.0 ---
 1.109  - add MPV_RENDER_API_TYPE_SW and related (software rendering API)
        - inactivate the opengl_cb API (always fails to initialize now)
          The opengl_cb API was deprecated over 2 years ago. Use the render API
          instead.
 1.108  - Deprecate MPV_EVENT_IDLE
        - add mpv_event_start_file
        - add the following fields to mpv_event_end_file: playlist_entry_id,
          playlist_insert_id, playlist_insert_num_entries
        - add mpv_event_to_node()
        - add mpv_client_id()
 1.107  - Remove the deprecated qthelper.hpp. This was obviously not part of the
          libmpv API, only an "additionally" provided helper, thus this is not
          considered an API change. If you are maintaining a project that relies
          on this header, you can simply download this file and adjust the
          include statement to use it instead:

            https://raw.githubusercontent.com/mpv-player/mpv/v0.32.0/libmpv/qthelper.hpp

          It is a good idea to write better wrappers for your use, though.
 --- mpv 0.31.0 ---
 1.107  - Deprecate MPV_EVENT_TICK
 --- mpv 0.30.0 ---
 1.106  - Add cancel_fn to mpv_stream_cb_info
 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.
          API users must still adhere to the tricky rules documented in render.h
          to avoid other deadlocks.
 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.
 1.103  - redo handling of async commands
        - add mpv_event_command and make it possible to return values from
          commands issued with mpv_command_async() or mpv_command_node_async()
        - add mpv_abort_async_command()
 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
 --- mpv 0.29.0 ---
 1.101  - add MPV_RENDER_PARAM_ADVANCED_CONTROL and related API
        - 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()
 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.
        - 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).
        - 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.
 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).
        - rename mpv_detach_destroy() to mpv_destroy() (the old function will
          remain valid as deprecated alias)
        - add mpv_create_weak_client(), which makes use of above changes
        - MPV_EVENT_SHUTDOWN is now returned exactly once if a mpv_handle
          should terminate, instead of spamming the event queue with this event
 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".
          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.
        - 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.
 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.
 --- mpv 0.28.0 ---
 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
        - make --stop-playback-on-init-failure=no the default in libmpv (just
          like in mpv CLI)
 --- mpv 0.27.0 ---
 1.25   - remove setting "no-" options via mpv_set_option*(). (See corresponding
          deprecation in 0.23.0.)
 --- 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
 --- mpv 0.23.0 ---
 1.24   - the deprecated mpv_suspend() and mpv_resume() APIs now do nothing.
 --- mpv 0.22.0 ---
 1.23   - deprecate setting "no-" options via mpv_set_option*(). For example,
          instead of "no-video=" you should set "video=no".
        - do not override the SIGPIPE signal handler anymore. This was done as
          workaround for the FFmpeg TLS code, which has been fixed long ago.
        - deprecate mpv_suspend() and mpv_resume(). They will be stubbed out
          in mpv 0.23.0.
        - 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.hpp: deprecate get_property_variant, set_property_variant,
          set_option_variant, command_variant, and replace them with
          get_property, set_property, command.
 --- mpv 0.19.0 ---
 1.22   - add stream_cb API for custom protocols
 --- 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.
 --- mpv 0.18.0 ---
 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.
        - 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.
        - 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.
 --- mpv 0.12.0 ---
 1.20   - deprecate "GL_MP_D3D_interfaces"/"glMPGetD3DInterface", and introduce
          "GL_MP_MPGetNativeDisplay"/"glMPGetNativeDisplay" (this is a
          backwards-compatible rename)
 --- mpv 0.11.0 ---
 --- mpv 0.10.0 ---
 1.19   - add "GL_MP_D3D_interfaces" pseudo extension to make it possible to
          use DXVA2 in OpenGL fullscreen mode in some situations
        - mpv_request_log_messages() now accepts "terminal-default" as parameter
 1.18   - add MPV_END_FILE_REASON_REDIRECT, and change behavior of
          MPV_EVENT_END_FILE accordingly
        - a bunch of interface-changes.rst changes
 1.17   - mpv_initialize() now blocks SIGPIPE (details see client.h)
 --- mpv 0.9.0 ---
 1.16   - add mpv_opengl_cb_report_flip()
        - introduce mpv_opengl_cb_draw() and deprecate mpv_opengl_cb_render()
        - add MPV_FORMAT_BYTE_ARRAY
 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.
        - minor backwards-compatible change to the "seek" and "screenshot"
          commands (new flag syntax, old additional args deprecated)
 --- mpv 0.8.0 ---
 1.14   - add mpv_wait_async_requests()
        - 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)
 1.13   - add MPV_EVENT_QUEUE_OVERFLOW
 1.12   - add class Handle to qthelper.hpp
        - improve opengl_cb.h API uninitialization behavior, and fix the qml
          example
        - add mpv_create_client() function
 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
 --- mpv 0.7.0 ---
 1.10   - deprecate/disable everything directly related to script_dispatch
          (most likely affects nobody)
 1.9    - add enum mpv_end_file_reason for mpv_event_end_file.reason
        - add MPV_END_FILE_REASON_ERROR and the mpv_event_end_file.error field
          for slightly better error reporting on playback failure
        - add --stop-playback-on-init-failure option, and make it the default
          behavior for libmpv only
        - add qthelper.hpp set_option_variant()
        - 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.
 1.8    - add qthelper.hpp
 1.7    - add mpv_command_node(), mpv_command_node_async()
 1.6    - modify "core-idle" property behavior
        - MPV_EVENT_LOG_MESSAGE now always sends complete lines
        - introduce numeric log levels (mpv_log_level)
 --- mpv 0.6.0 ---
 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.
          Note: in 1.6, "input-x11-keyboard" was renamed to "input-vo-keyboard",
          although the old option name still works.
 1.4    - subtle change in X11 and "--wid" behavior
          (this change was added to 0.5.2, and broke some things, see #1090)
 --- mpv 0.5.0 ---
 1.3    - add MPV_MAKE_VERSION()
 1.2    - remove "stream-time-pos" property (no replacement)
 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
        - macOS: the "coreaudio" AO spdif code is split into a separate AO
 --- mpv 0.4.0 ---
 1.0    - the API is declared stable