diff options
Diffstat (limited to 'DOCS/man/libmpv.rst')
-rw-r--r-- | DOCS/man/libmpv.rst | 56 |
1 files changed, 56 insertions, 0 deletions
diff --git a/DOCS/man/libmpv.rst b/DOCS/man/libmpv.rst index d3e78aa5bc..a85b2ed569 100644 --- a/DOCS/man/libmpv.rst +++ b/DOCS/man/libmpv.rst @@ -14,3 +14,59 @@ mpv, further documentation is spread over a few places: - http://mpv.io/manual/master/#list-of-input-commands - http://mpv.io/manual/master/#properties - https://github.com/mpv-player/mpv-examples/tree/master/libmpv + +C PLUGINS +========= + +You can write C plugins for mpv. These use the libmpv API, although they do not +use the libmpv library itself. + +Currently, they must be explicitlx enabled at build time with +``--enable-cplugins``. They are available on Linux/BSD platforms only. + +C plugins location +------------------ + +C plugins are put into the mpv scripts directory in its config directory +(see the `FILES`_ section for details). They must have a ``.so`` file extension. +They can also be explicitly loaded with the ``--script`` option. + +API +--- + +A C plugin must export the following function:: + + int mpv_open_cplugin(mpv_handle *handle) + +The plugin function will be called on loading time. This function does not +return as long as your plugin is loaded (it runs in its own thread). The +``handle`` will be deallocated as soon as the plugin function returns. + +The return value is interpreted as error status. A value of ``0`` is +interpreted as success, while any other value signals an error. In the latter +case, the player prints an uninformative error message that loading failed. + +Within the plugin function, you can call libmpv API functions. The ``handle`` +is created by ``mpv_create_client()`` (or actually an internal equivalent), +and belongs to you. You can call ``mpv_wait_event()`` to wait for things +happening, and so on. + +Note that the player might block until your plugin calls ``mpv_wait_event()`` +for the first time. This gives you a chance to install initial hooks etc. +before playback begins. + +The details are quite similar to Lua scripts. + +Linkage to libmpv +----------------- + +The current implementation requires that your plugins are **not** linked against +libmpv. What your plugins uses are not symbols from a libmpv binary, but +symbols from the mpv host binary. + +Examples +-------- + +See: + +- https://github.com/mpv-player/mpv-examples/tree/master/cplugins |