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.

DOCS/client-api-changes.rst

@@ -31,6 +31,15 @@ API changes
         - 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

DOCS/man/lua.rst

@@ -648,28 +648,11 @@ List of events
 ``playback-restart``
     Start of playback after seek or after file was loaded.
 
-``tracks-changed``
-    The list of video/audio/sub tracks was updated. (This happens on playback
-    start, and very rarely during playback.)
-
-``track-switched``
-    A video/audio/subtitle track was switched on or off. This usually happens
-    when the user (or a script) changes the subtitle track and so on.
-
 ``idle``
     Idle mode is entered. This happens when playback ended, and the player was
     started with ``--idle`` or ``--force-window``. This mode is implicitly ended
     when the ``start-file`` or ``shutdown`` events happen.
 
-``pause``
-    Playback was paused. This also happens when for example the player is
-    paused on low network cache. Then the event type indicates the pause state
-    (like the property "pause" as opposed to the "core-idle" property), and you
-    might receive multiple ``pause`` events in a row.
-
-``unpause``
-    Playback was unpaused. See above for details.
-
 ``tick``
     Called after a video frame was displayed. This is a hack, and you should
     avoid using it. Use timers instead and maybe watch pausing/unpausing events
@@ -729,11 +712,9 @@ List of events
 ``audio-reconfig``
     Happens on audio output or filter reconfig.
 
-``metadata-update``
-    Metadata (like file tags) was updated.
-
-``chapter-change``
-    The current chapter possibly changed.
+The following events also happen, but are deprecated: ``tracks-changed``,
+``track-switched``, ``pause``, ``unpause``, ``metadata-update``,
+``chapter-change``. Use ``mp.observe_property()`` instead.
 
 Extras
 ------

libmpv/client.h

@@ -952,10 +952,18 @@ typedef enum mpv_event_id {
      * The list of video/audio/subtitle tracks was changed. (E.g. a new track
      * was found. This doesn't necessarily indicate a track switch; for this,
      * MPV_EVENT_TRACK_SWITCHED is used.)
+     *
+     * @deprecated This is equivalent to using mpv_observe_property() on the
+     *             "track-list" property. The event is redundant, and might
+     *             be removed in the far future.
      */
     MPV_EVENT_TRACKS_CHANGED    = 9,
     /**
      * A video/audio/subtitle track was switched on or off.
+     *
+     * @deprecated This is equivalent to using mpv_observe_property() on the
+     *             "vid", "aid", and "sid" properties. The event is redundant,
+     *             and might be removed in the far future.
      */
     MPV_EVENT_TRACK_SWITCHED    = 10,
     /**
@@ -981,10 +989,17 @@ typedef enum mpv_event_id {
      * If you don't want to deal with this, use mpv_observe_property() on the
      * "pause" property and ignore MPV_EVENT_PAUSE/UNPAUSE. Likewise, the
      * "core-idle" property tells you whether video is actually playing or not.
+     *
+     * @deprecated The event is redundant with mpv_observe_property() as
+     *             mentioned above, and might be removed in the far future.
      */
     MPV_EVENT_PAUSE             = 12,
     /**
      * Playback was unpaused. See MPV_EVENT_PAUSE for not so obvious details.
+     *
+     * @deprecated The event is redundant with mpv_observe_property() as
+     *             explained in the MPV_EVENT_PAUSE comments, and might be
+     *             removed in the far future.
      */
     MPV_EVENT_UNPAUSE           = 13,
     /**
@@ -1031,6 +1046,10 @@ typedef enum mpv_event_id {
      * Happens when metadata (like file tags) is possibly updated. (It's left
      * unspecified whether this happens on file start or only when it changes
      * within a file.)
+     *
+     * @deprecated This is equivalent to using mpv_observe_property() on the
+     *             "metadata" property. The event is redundant, and might
+     *             be removed in the far future.
      */
     MPV_EVENT_METADATA_UPDATE   = 19,
     /**
@@ -1052,6 +1071,10 @@ typedef enum mpv_event_id {
     MPV_EVENT_PROPERTY_CHANGE   = 22,
     /**
      * Happens when the current chapter changes.
+     *
+     * @deprecated This is equivalent to using mpv_observe_property() on the
+     *             "chapter" property. The event is redundant, and might
+     *             be removed in the far future.
      */
     MPV_EVENT_CHAPTER_CHANGE = 23
     // Internal note: adjust INTERNAL_EVENT_BASE when adding new events.