diff options
| -rw-r--r-- | DOCS/man/input.rst | 61 | ||||
| -rw-r--r-- | DOCS/man/lua.rst | 17 |
2 files changed, 64 insertions, 14 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 ---------------------- diff --git a/DOCS/man/lua.rst b/DOCS/man/lua.rst index 347292cd7b..7cdc29e4ab 100644 --- a/DOCS/man/lua.rst +++ b/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. |