summaryrefslogtreecommitdiffstats
path: root/DOCS/man/input.rst
diff options
context:
space:
mode:
authorwm4 <wm4@nowhere>2015-02-04 19:20:17 +0100
committerwm4 <wm4@nowhere>2015-02-04 23:04:21 +0100
commitf8dc5db315ce3ec3c3e9c8532f1290967bbe2336 (patch)
tree06e1691920d3db3cc01ce66e6e49b2d3c2ffdce0 /DOCS/man/input.rst
parente163284b6802fe6375536f48cea281062294eaa2 (diff)
downloadmpv-f8dc5db315ce3ec3c3e9c8532f1290967bbe2336.tar.bz2
mpv-f8dc5db315ce3ec3c3e9c8532f1290967bbe2336.tar.xz
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.
Diffstat (limited to 'DOCS/man/input.rst')
-rw-r--r--DOCS/man/input.rst61
1 files changed, 61 insertions, 0 deletions
diff --git a/DOCS/man/input.rst b/DOCS/man/input.rst
index d3d5790c15..954520147a 100644
--- a/DOCS/man/input.rst
+++ b/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
----------------------