/* Permission to use, copy, modify, and/or distribute this software for any
* purpose with or without fee is hereby granted, provided that the above
* copyright notice and this permission notice appear in all copies.
*
* THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
* WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
* MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
* ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
* WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
* ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
* OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
*/
/*
* Note: the client API is licensed under ISC (see above) to ease
* interoperability with other licenses. But keep in mind that the
* mpv core is still mostly GPLv2+. It's up to lawyers to decide
* whether applications using this API are affected by the GPL.
* One argument against this is that proprietary applications
* using mplayer in slave mode is apparently tolerated, and this
* API is basically equivalent to slave mode.
*/
#ifndef MPV_CLIENT_API_H_
#define MPV_CLIENT_API_H_
#include <stdint.h>
#ifdef __cplusplus
extern "C" {
#endif
/**
* Mechanisms provided by this API
* -------------------------------
*
* This API provides general control over mpv playback. It does not give you
* direct access to individual components of the player, only the whole thing.
* It's somewhat equivalent to MPlayer's slave mode. You can send commands,
* retrieve or set playback status or settings with properties, and receive
* events.
*
* The API can be used in two ways:
* 1) Internally in mpv, to provide additional features to the command line
* player. Lua scripting uses this. (Currently there is no plugin API to
* get a client API handle in external user code. It has to be a fixed
* part of the player at compilation time.)
* 2) Using mpv as a library with mpv_create(). This basically allows embedding
* mpv in other applications.
*
* Event loop
* ----------
*
* In general, the API user should run an event loop in order to receive events.
* This even loop should call mpv_wait_event(), which will return once a new
* mpv client API is available. It should also be possible to integrate client
* API usage in other event loops (e.g. GUI toolkits) with the
* mpv_set_wakeup_callback() function, and then polling for events by calling
* mpv_wait_event() with a 0 timeout.
*
* Note that the event loop is detached from the actual player. Not calling
* mpv_wait_event() will not stop playback. It will eventually congest the
* event queue of your API handle, though.
*
* Synchronous vs. asynchronous calls
* ----------------------------------
*
* The API allows both synchronous and asynchronous calls. Synchronous calls
* have to wait until the playback core is ready, which currently can take
* an unbounded time (e.g. if network is slow or unresponsive). Asynchronous
* calls just queue operations as requests, and return the result of the
* operation as events.
*
* Asynchronous calls
* ------------------
*
* The client API includes asynchronous functions. These allow you to send
* requests instantly, and get replies as events at a later point. The
* requests are made with functions carrying the _async suffix, and replies
* are returned by mpv_wait_event() (interleaved with the normal event stream).
*
* A 64 bit userdata value is used to allow the user to associate requests
* with replies. The value is passed as reply_userdata parameter to the request
* function. The reply to the request will have the reply
* mpv_event->reply_userdata field set to the same value as the
* reply_userdata parameter of the corresponding request.
*
* This userdata value is arbitrary and is never interpreted by the API. Note
* that the userdata value 0 is also allowed, but then the client must be
* careful not accidentally interpret the mpv_event->reply_userdata if an
* event is not a reply. (For non-replies, this field is set to 0.)
*
* Currently, asynchronous calls are always strictly ordered (even with
* synchronous calls) for each client, although that may change in the future.
*
* Multithreading
* --------------
*
* The client API is generally fully thread-safe, unless otherwise noted.
* Currently, there is no real advantage in using more than 1 thread to access
* the client API, since everything is serialized through a single lock in the
* playback core.
*
* Basic environment requirements
* ------------------------------
*
* This documents basic requirements on the C environment. This is especially
* important if mpv is used as library with mpv_create().
*
* - The LC_NUMERIC locale category must be set to "C". If your program calls
* setlocale(), be sure not to use LC_ALL, or if you do, reset LC_NUMERIC
* to its sane default: setlocale(LC_NUMERIC, "C").
* - If a X11 based VO is used, mpv will set the xlib error handler. This error
* handler is process-wide, and there's no proper way to share it with other
* xlib users within the same process. This might confuse GUI toolkits.
* - mpv uses some other libraries that are not library-safe, such as Fribidi
* (used through libass), ALSA, FFmpeg, and possibly more.
* - The FPU precision must be set at least to double precision.
* - On Windows, mpv will call timeBeginPeriod(1).
* - SIGPIPE should be blocked. Some parts rely on this signal not crashing the
* process (such as ffmpeg OpenSSL support, or the mpv IPC code).
* - On memory exhaustion, mpv will kill the process.
*
* Embedding the video window
* --------------------------
*
* Currently you have to get the raw window handle, and set it as "wid" option.
* This works on X11, win32, and OSX only. In addition, it works with a few VOs
* only, and VOs which do not support this will just create a freestanding
* window.
*
* Both on X11 and win32, the player will fill the window referenced by the
* "wid" option fully and letterbox the video (i.e. add black bars if the
* aspect ratio of the window and the video mismatch).
*
* Also see client API examples and the mpv manpage.
*
* Compatibility
* -------------
*
* mpv development doesn't stand still, and changes to mpv internals as well as
* to its interface can cause compatibility issues to client API users.
*
* The API is versioned (see MPV_CLIENT_API_VERSION), and changes to it are
* documented in DOCS/client-api-changes.rst. The C API itself will probably
* remain compatible for a long time, but the functionality exposed by it
* could change more rapidly. For example, it's possible that options are
* renamed, or change the set of allowed values.
*
* Defensive programming should be used to potentially deal with the fact that
* options, commands, and properties could disappear, change their value range,
* or change the underlying datatypes. It might be a good idea to prefer
* MPV_FORMAT_STRING over other types to decouple your code from potential
* mpv changes.
*/
/**
* The version is incremented on each API change. The 16 lower bits form the
* minor version number, and the 16 higher bits the major version number. If
* the API becomes incompatible to previous versions, the major version
* number is incremented. This affects only C part, and not properties and
* options.
*
* Every API bump is described in DOCS/client-api-changes.rst
*
* You can use MPV_MAKE_VERSION() and compare the result with integer
* relational
|