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.

3 files changed, 48 insertions, 34 deletions

diff --git a/DOCS/client-api-changes.rst b/DOCS/client-api-changes.rst
index 83db23df30..a451f6e032 100644
--- a/DOCS/client-api-changes.rst
+++ b/DOCS/client-api-changes.rst
@@ -41,6 +41,9 @@ API changes
         - 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
diff --git a/DOCS/interface-changes.rst b/DOCS/interface-changes.rst
index 268a34c686..4aae43db7a 100644
--- a/DOCS/interface-changes.rst
+++ b/DOCS/interface-changes.rst
@@ -82,6 +82,8 @@ Interface changes
     - change vf_vavpp default to use the best deinterlace algorithm by default
     - remove a compatibility hack that allowed CLI aliases to be set as property
       (such as "sub-file"), deprecated in mpv 0.26.0
+    - deprecate the old command based hook API, and introduce a proper C API
+      (the high level Lua API for this does not change)
  --- mpv 0.28.0 ---
     - rename --hwdec=mediacodec option to mediacodec-copy, to reflect
       conventions followed by other hardware video decoding APIs
diff --git a/DOCS/man/input.rst b/DOCS/man/input.rst
index 120337e598..7efc700550 100644
--- a/DOCS/man/input.rst
+++ b/DOCS/man/input.rst
@@ -762,40 +762,8 @@ and obscure way to handle events that require stricter coordination. There are
 no API stability guarantees made. Not following the protocol exactly can make
 the player freeze randomly. Basically, nobody should use this API.
 
-There are two special commands involved. Also, the client must listen for
-client messages (``MPV_EVENT_CLIENT_MESSAGE`` in the C API).
-
-``hook-add <hook-name> <id> <priority>``
-    Subscribe to the hook identified by the first argument (basically, the
-    name of event). The ``id`` argument is an arbitrary integer chosen by the
-    user. ``priority`` is used to sort all hook handlers globally across all
-    clients. Each client can register multiple hook handlers (even for the
-    same hook-name). Once the hook is registered, it cannot be unregistered.
-
-    When a specific event happens, all registered handlers are run serially.
-    This uses a protocol every client has to follow explicitly. When a hook
-    handler is run, a client message (``MPV_EVENT_CLIENT_MESSAGE``) is sent to
-    the client which registered the hook. This message has the following
-    arguments:
-
-    1. the string ``hook_run``
-    2. the ``id`` argument the hook was registered with as string (this can be
-       used to correctly handle multiple hooks registered by the same client,
-       as long as the ``id`` argument is unique in the client)
-    3. something undefined, used by the hook mechanism to track hook execution
-       (currently, it's the hook-name, but this might change without warning)
-
-    Upon receiving this message, the client can handle the event. While doing
-    this, the player core will still react to requests, but playback will
-    typically be stopped.
-
-    When the client is done, it must continue the core's hook execution by
-    running the ``hook-ack`` command.
-
-``hook-ack <string>``
-    Run the next hook in the global chain of hooks. The argument is the 3rd
-    argument of the client message that starts hook execution for the
-    current client.
+The C API is described in the header files. The Lua API is described in the
+Lua section.
 
 The following hooks are currently defined:
 
@@ -830,6 +798,47 @@ The following hooks are currently defined:
     Run before closing a file, and before actually uninitializing
     everything. It's not possible to resume playback in this state.
 
+Legacy hook API
+~~~~~~~~~~~~~~~
+
+.. warning::
+
+    The legacy API is deprecated and will be removed soon.
+
+There are two special commands involved. Also, the client must listen for
+client messages (``MPV_EVENT_CLIENT_MESSAGE`` in the C API).
+
+``hook-add <hook-name> <id> <priority>``
+    Subscribe to the hook identified by the first argument (basically, the
+    name of event). The ``id`` argument is an arbitrary integer chosen by the
+    user. ``priority`` is used to sort all hook handlers globally across all
+    clients. Each client can register multiple hook handlers (even for the
+    same hook-name). Once the hook is registered, it cannot be unregistered.
+
+    When a specific event happens, all registered handlers are run serially.
+    This uses a protocol every client has to follow explicitly. When a hook
+    handler is run, a client message (``MPV_EVENT_CLIENT_MESSAGE``) is sent to
+    the client which registered the hook. This message has the following
+    arguments:
+
+    1. the string ``hook_run``
+    2. the ``id`` argument the hook was registered with as string (this can be
+       used to correctly handle multiple hooks registered by the same client,
+       as long as the ``id`` argument is unique in the client)
+    3. something undefined, used by the hook mechanism to track hook execution
+
+    Upon receiving this message, the client can handle the event. While doing
+    this, the player core will still react to requests, but playback will
+    typically be stopped.
+
+    When the client is done, it must continue the core's hook execution by
+    running the ``hook-ack`` command.
+
+``hook-ack <string>``
+    Run the next hook in the global chain of hooks. The argument is the 3rd
+    argument of the client message that starts hook execution for the
+    current client.
+
 Input Command Prefixes
 ----------------------