/* 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.
*
* Documentation
* -------------
*
* The libmpv C API is documented directly in this header. Note that most
* actual interaction with this player is done through
* options/commands/properties, which can be accessed through this API.
* Essentially everything is done with them, including loading a file,
* retrieving playback progress, and so on.
*
* These are documented elsewhere:
* * http://mpv.io/manual/master/#options
* * http://mpv.io/manual/master/#list-of-input-commands
* * http://mpv.io/manual/master/#properties
*
* You can also look at the examples here:
* * https://github.com/mpv-player/mpv-examples/tree/master/libmpv
*
* Event loop
* ----------
*
* In general, the API user should run an event loop in order to receive events.
* This event loop should call mpv_wait_event(), which will return once a new
* mpv client API is available. It is also 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
* -------------------------------
| 