diff options
Diffstat (limited to 'DOCS')
| -rw-r--r-- | DOCS/client-api-changes.rst | 3 | ||||
| -rw-r--r-- | DOCS/interface-changes.rst | 2 | ||||
| -rw-r--r-- | DOCS/man/input.rst | 77 |
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 ---------------------- |