/* 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 <stddef.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 es
|