summaryrefslogtreecommitdiffstats
path: root/DOCS/man/libmpv.rst
diff options
context:
space:
mode:
Diffstat (limited to 'DOCS/man/libmpv.rst')
-rw-r--r--DOCS/man/libmpv.rst59
1 files changed, 59 insertions, 0 deletions
diff --git a/DOCS/man/libmpv.rst b/DOCS/man/libmpv.rst
index d3e78aa5bc..909a2bb447 100644
--- a/DOCS/man/libmpv.rst
+++ b/DOCS/man/libmpv.rst
@@ -14,3 +14,62 @@ 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 explicitly 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 ``-1`` signals an error. In the latter case,
+the player prints an uninformative error message that loading failed.
+
+Return values other than ``0`` and ``-1`` are reserved, and trigger undefined
+behavior.
+
+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