RepoMirrors
/
mpv
mirror of https://github.com/mpv-player/mpv
1
0
Fork 0
Code Issues Releases Wiki Activity
mpv/DOCS/man/libmpv.rst

80 lines
2.8 KiB
ReStructuredText
Raw Normal View History

DOCS: move libmpv stub to manpage And replace the sort-of duplicated explanations. (It's a bit funny to use weblinks to the generated web version of itself instead of proper RST links, but I think I don't care.)
2016-09-02 07:51:21 +00:00
EMBEDDING INTO OTHER PROGRAMS (LIBMPV)
======================================
mpv can be embedded into other programs as video/audio playback backend. The
recommended way to do so is using libmpv. See ``libmpv/client.h`` in the mpv
source code repository. This provides a C API. Bindings for other languages
might be available (see wiki).
Since libmpv merely allows access to underlying mechanisms that can control
mpv, further documentation is spread over a few places:
- https://github.com/mpv-player/mpv/blob/master/libmpv/client.h
DOCS: convert mpv.io and github links to https Discovered with: find . -type f \( -name '*.md' -o -name '*.rst' \) -exec grep -n 'http://' {} + All links to mpv.io or github.com/mpv-player that were http were converted to https.
2021-08-12 23:23:36 +00:00
- https://mpv.io/manual/master/#options
- https://mpv.io/manual/master/#list-of-input-commands
- https://mpv.io/manual/master/#properties
DOCS: move libmpv stub to manpage And replace the sort-of duplicated explanations. (It's a bit funny to use weblinks to the generated web version of itself instead of proper RST links, but I think I don't care.)
2016-09-02 07:51:21 +00:00
- https://github.com/mpv-player/mpv-examples/tree/master/libmpv
player: add experimental C plugin interface This basically reuses the scripting infrastructure. Note that this needs to be explicitly enabled at compilation. For one, enabling export for certain symbols from an executable seems to be quite toolchain-specific. It might not work outside of Linux and cause random problems within Linux. If C plugins actually become commonly used and this approach is starting to turn out as a problem, we can build mpv CLI as a wrapper for libmpv, which would remove the requirement that plugins pick up host symbols. I'm being lazy, so implementation/documentation are parked in existing files, even if that stuff doesn't necessarily belong there. Sue me, or better send patches.
2017-01-12 16:37:11 +00:00
C PLUGINS
=========
You can write C plugins for mpv. These use the libmpv API, although they do not
use the libmpv library itself.
cplugin: allow loading mpv_* symbols dynamically Defining MPV_CPLUGIN_DYNAMIC_SYM during plugin compilation will replace mpv_* functions with function pointers. Those pointer will be initialized when loading the plugin. It is recommended to use this symbol table when targeting Windows. The loader does not have notion of global symbols. Loading cplugin into mpv process will not allow this plugin to call any of the symbols that may be available in other modules. Instead cplugin has to link explicitly to specific PE binary, libmpv-2.dll/mpv.exe or any other binary that may have linked mpv statically. This limits portability of cplugin as it would need to be compiled separately for each of target PE binary that includes mpv's symbols. Which in practice is unrealictis, as we want one cplugin to be loaded without those restrictions. Instead of linking to any PE binary, we create function pointer for all mpv's exported symbols. For convinience names of entrypoints are redefined to those pointer so no changes are required in cplugin source code, except defining MPV_CPLUGIN_DYNAMIC_SYM. Those function pointer are exported to make them available for mpv to init with correct values during runtime, before calling `mpv_open_cplugin`. Note that those pointer are decorated with `selectany` attribute, so no need to worry about multiple definitions, linker will keep only single instance. This fixes cplugin usability on Windows. Without any API changes, only recompilation with -DMPV_CPLUGIN_DYNAMIC_SYM is needed.
2023-08-17 14:19:26 +00:00
They are enabled by default if compiler supports linking with the ``-rdynamic``
flag on Linux/BSD platforms. On Windows the are always enabled.
player: add experimental C plugin interface This basically reuses the scripting infrastructure. Note that this needs to be explicitly enabled at compilation. For one, enabling export for certain symbols from an executable seems to be quite toolchain-specific. It might not work outside of Linux and cause random problems within Linux. If C plugins actually become commonly used and this approach is starting to turn out as a problem, we can build mpv CLI as a wrapper for libmpv, which would remove the requirement that plugins pick up host symbols. I'm being lazy, so implementation/documentation are parked in existing files, even if that stuff doesn't necessarily belong there. Sue me, or better send patches.
2017-01-12 16:37:11 +00:00
C plugins location
------------------
C plugins are put into the mpv scripts directory in its config directory
cplugin: allow loading mpv_* symbols dynamically Defining MPV_CPLUGIN_DYNAMIC_SYM during plugin compilation will replace mpv_* functions with function pointers. Those pointer will be initialized when loading the plugin. It is recommended to use this symbol table when targeting Windows. The loader does not have notion of global symbols. Loading cplugin into mpv process will not allow this plugin to call any of the symbols that may be available in other modules. Instead cplugin has to link explicitly to specific PE binary, libmpv-2.dll/mpv.exe or any other binary that may have linked mpv statically. This limits portability of cplugin as it would need to be compiled separately for each of target PE binary that includes mpv's symbols. Which in practice is unrealictis, as we want one cplugin to be loaded without those restrictions. Instead of linking to any PE binary, we create function pointer for all mpv's exported symbols. For convinience names of entrypoints are redefined to those pointer so no changes are required in cplugin source code, except defining MPV_CPLUGIN_DYNAMIC_SYM. Those function pointer are exported to make them available for mpv to init with correct values during runtime, before calling `mpv_open_cplugin`. Note that those pointer are decorated with `selectany` attribute, so no need to worry about multiple definitions, linker will keep only single instance. This fixes cplugin usability on Windows. Without any API changes, only recompilation with -DMPV_CPLUGIN_DYNAMIC_SYM is needed.
2023-08-17 14:19:26 +00:00
(see the `FILES`_ section for details). They must have a ``.so`` or ``.dll``
file extension. They can also be explicitly loaded with the ``--script`` option.
player: add experimental C plugin interface This basically reuses the scripting infrastructure. Note that this needs to be explicitly enabled at compilation. For one, enabling export for certain symbols from an executable seems to be quite toolchain-specific. It might not work outside of Linux and cause random problems within Linux. If C plugins actually become commonly used and this approach is starting to turn out as a problem, we can build mpv CLI as a wrapper for libmpv, which would remove the requirement that plugins pick up host symbols. I'm being lazy, so implementation/documentation are parked in existing files, even if that stuff doesn't necessarily belong there. Sue me, or better send patches.
2017-01-12 16:37:11 +00:00
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
manpage: define stricter rules for C plugin return values Just in case.
2017-01-14 16:41:04 +00:00
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.
player: add experimental C plugin interface This basically reuses the scripting infrastructure. Note that this needs to be explicitly enabled at compilation. For one, enabling export for certain symbols from an executable seems to be quite toolchain-specific. It might not work outside of Linux and cause random problems within Linux. If C plugins actually become commonly used and this approach is starting to turn out as a problem, we can build mpv CLI as a wrapper for libmpv, which would remove the requirement that plugins pick up host symbols. I'm being lazy, so implementation/documentation are parked in existing files, even if that stuff doesn't necessarily belong there. Sue me, or better send patches.
2017-01-12 16:37:11 +00:00
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
DOCS/libmpv: fix typo in linkage section
2022-09-03 06:55:23 +00:00
libmpv. What your plugins use are not symbols from a libmpv binary, but
player: add experimental C plugin interface This basically reuses the scripting infrastructure. Note that this needs to be explicitly enabled at compilation. For one, enabling export for certain symbols from an executable seems to be quite toolchain-specific. It might not work outside of Linux and cause random problems within Linux. If C plugins actually become commonly used and this approach is starting to turn out as a problem, we can build mpv CLI as a wrapper for libmpv, which would remove the requirement that plugins pick up host symbols. I'm being lazy, so implementation/documentation are parked in existing files, even if that stuff doesn't necessarily belong there. Sue me, or better send patches.
2017-01-12 16:37:11 +00:00
symbols from the mpv host binary.
cplugin: allow loading mpv_* symbols dynamically Defining MPV_CPLUGIN_DYNAMIC_SYM during plugin compilation will replace mpv_* functions with function pointers. Those pointer will be initialized when loading the plugin. It is recommended to use this symbol table when targeting Windows. The loader does not have notion of global symbols. Loading cplugin into mpv process will not allow this plugin to call any of the symbols that may be available in other modules. Instead cplugin has to link explicitly to specific PE binary, libmpv-2.dll/mpv.exe or any other binary that may have linked mpv statically. This limits portability of cplugin as it would need to be compiled separately for each of target PE binary that includes mpv's symbols. Which in practice is unrealictis, as we want one cplugin to be loaded without those restrictions. Instead of linking to any PE binary, we create function pointer for all mpv's exported symbols. For convinience names of entrypoints are redefined to those pointer so no changes are required in cplugin source code, except defining MPV_CPLUGIN_DYNAMIC_SYM. Those function pointer are exported to make them available for mpv to init with correct values during runtime, before calling `mpv_open_cplugin`. Note that those pointer are decorated with `selectany` attribute, so no need to worry about multiple definitions, linker will keep only single instance. This fixes cplugin usability on Windows. Without any API changes, only recompilation with -DMPV_CPLUGIN_DYNAMIC_SYM is needed.
2023-08-17 14:19:26 +00:00
On Windows to make symbols from the host binary available, you have to define
MPV_CPLUGIN_DYNAMIC_SYM when compiling cplugin. This will load symbols
dynamically, before calling ``mpv_open_cplugin()``.
player: add experimental C plugin interface This basically reuses the scripting infrastructure. Note that this needs to be explicitly enabled at compilation. For one, enabling export for certain symbols from an executable seems to be quite toolchain-specific. It might not work outside of Linux and cause random problems within Linux. If C plugins actually become commonly used and this approach is starting to turn out as a problem, we can build mpv CLI as a wrapper for libmpv, which would remove the requirement that plugins pick up host symbols. I'm being lazy, so implementation/documentation are parked in existing files, even if that stuff doesn't necessarily belong there. Sue me, or better send patches.
2017-01-12 16:37:11 +00:00
Examples
--------
See:
- https://github.com/mpv-player/mpv-examples/tree/master/cplugins