manpage: document hook API

This shouldn't exist and for the most part is meant to be used by the
ytdl Lua script, but let's document it anyway. Since the Lua API handles
all the details, it's considered much more "stable" than the raw API,
which is why the raw API wasn't documented.

DOCS/man/input.rst

@@ -621,6 +621,67 @@ Input Commands that are Possibly Subject to Change
 Undocumented commands: ``tv_last_channel`` (TV/DVB only), ``get_property`` (?),
 ``ao_reload`` (experimental/internal).
 
+
+Hooks
+~~~~~
+
+Hooks are synchronous events between player core and a script or similar. This
+applies to the Lua scripting interface and the client API and only. Normally,
+events are supposed to be asynchronous, and the hook API provides an awkward
+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 following hooks are currently defined:
+
+``on_load``
+    Called when a file is to be opened, before anything is actually done.
+    For example, you could read and write the ``stream-open-filename``
+    property to redirect an URL to something else (consider support for
+    streaming sites which rarely give the user a direct media URL), or
+    you could set per-file options with by setting the property
+    ``file-local-options/<option name>``. The player will wait until all
+    hooks are run.
+
+``on_unload``
+    Run before closing a file, and before actually uninitializing
+    everything. It's not possible to resume playback in this state.
+
 Input Command Prefixes
 ----------------------
 

DOCS/man/lua.rst

@@ -745,17 +745,6 @@ guarantee a stable interface.
     recommended as neutral default value. ``fn`` is the function that will be
     called during execution of the hook.
 
-    Currently existing hooks:
-
-    ``on_load``
-        Called when a file is to be opened, before anything is actually done.
-        For example, you could read and write the ``stream-open-filename``
-        property to redirect an URL to something else (consider support for
-        streaming sites which rarely give the user a direct media URL), or
-        you could set per-file options with by setting the property
-        ``file-local-options/<option name>``. The player will wait until all
-        hooks are run.
-
-    ``on_unload``
-        Run before closing a file, and before actually uninitializing
-        everything. It's not possible to resume playback in this state.
+    See `Hooks`_ for currently existing hooks and what they do - only the hook
+    list is interesting; handling hook execution is done by the Lua script
+    function automatically.