DOCS: add a file listing API changes for the client API

DOCS/client-api-changes.rst

@@ -0,0 +1,35 @@
+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
+===========
+
+ 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
+ 1.0    - the API is declared stable

DOCS/man/input.rst

@@ -987,6 +987,7 @@ Property list
                 "par"               MPV_FORMAT_DOUBLE
                 "colormatrix"       MPV_FORMAT_STRING
                 "colorlevels"       MPV_FORMAT_STRING
+                "primaries"         MPV_FORMAT_STRING
                 "chroma-location"   MPV_FORMAT_STRING
                 "rotate"            MPV_FORMAT_INT64
 

libmpv/client.h

@@ -114,7 +114,7 @@ extern "C" {
  *   handler is process-wide, and there's no proper way to share it with other
  *   xlib users within the same process. This might confuse GUI toolkits.
  * - mpv uses some other libraries that are not library-safe, such as Fribidi
- *   (used through libass), LittleCMS, ALSA, FFmpeg, and possibly more.
+ *   (used through libass), ALSA, FFmpeg, and possibly more.
  * - The FPU precision must be set at least to double precision.
  * - On Windows, mpv will call timeBeginPeriod(1).
  * - On memory exhaustion, mpv will kill the process.
@@ -131,6 +131,24 @@ extern "C" {
  * aspect ratio of the window and the video mismatch).
  *
  * On OSX, embedding is not yet possible, because Cocoa makes this non-trivial.
+ *
+ * Compatibility
+ * -------------
+ *
+ * mpv development doesn't stand still, and changes to mpv internals as well as
+ * to its interface can cause compatibility issues to client API users.
+ *
+ * The API is versioned (see MPV_CLIENT_API_VERSION), and changes to it are
+ * documented in DOCS/client-api-changes.rst. The C API itself will probably
+ * remain compatible for a long time, but the functionality exposed by it
+ * could change more rapidly. For example, it's possible that options are
+ * renamed, or change the set of allowed values.
+ *
+ * Defensive programming should be used to potentially deal with the fact that
+ * options, commands, and properties could disappear, change their value range,
+ * or change the underlying datatypes. It might be a good idea to prefer
+ * MPV_FORMAT_STRING over other types to decouple your code from potential
+ * mpv changes.
  */
 
 /**
@@ -139,8 +157,13 @@ extern "C" {
  * the API becomes incompatible to previous versions, the major version
  * number is incremented. This affects only C part, and not properties and
  * options.
+ *
+ * The version number is often converted into a human readable form by writing
+ * the major and minor version number in decimal. E.g.:
+ *      version 0x001001FF
+ *      becomes 16.511 (dec(0x0010) + "." + dec(0x01FF))
  */
-#define MPV_CLIENT_API_VERSION 0x00010000UL
+#define MPV_CLIENT_API_VERSION 0x00010001UL
 
 /**
  * Return the MPV_CLIENT_API_VERSION the mpv source has been compiled with.