29 files changed, 2686 insertions, 375 deletions

diff --git a/DOCS/client_api_examples/shared.h b/DOCS/client_api_examples/shared.h
new file mode 100644
index 0000000000..027c03f1e9
--- /dev/null
+++ b/DOCS/client_api_examples/shared.h
@@ -0,0 +1,10 @@
+#include <stdio.h>
+#include <stdlib.h>
+
+static inline void check_error(int status)
+{
+    if (status < 0) {
+        printf("mpv API error: %s\n", mpv_error_string(status));
+        exit(1);
+    }
+}
diff --git a/DOCS/client_api_examples/simple.c b/DOCS/client_api_examples/simple.c
new file mode 100644
index 0000000000..c5d8dc175c
--- /dev/null
+++ b/DOCS/client_api_examples/simple.c
@@ -0,0 +1,43 @@
+#include <stddef.h>
+#include <stdio.h>
+#include <stdlib.h>
+
+#include "libmpv/client.h"
+#include "shared.h"
+
+int main(int argc, char *argv[])
+{
+    if (argc != 2) {
+        printf("pass a single media file as argument\n");
+        return 1;
+    }
+
+    mpv_handle *ctx = mpv_create();
+    if (!ctx) {
+        printf("failed creating context\n");
+        return 1;
+    }
+
+    // Enable default key bindings, so the user can actually interact with
+    // the player (and e.g. close the window).
+    check_error(mpv_set_option_string(ctx, "input-default-bindings", "yes"));
+    check_error(mpv_set_option_string(ctx, "osc", "yes"));
+
+    // Done setting up options.
+    check_error(mpv_initialize(ctx));
+
+    // Play this file.
+    const char *cmd[] = {"loadfile", argv[1], NULL};
+    check_error(mpv_command(ctx, cmd));
+
+    // Let it play, and wait until the user quits.
+    while (1) {
+        mpv_event *event = mpv_wait_event(ctx, 10000);
+        printf("event: %s\n", mpv_event_name(event->event_id));
+        if (event->event_id == MPV_EVENT_SHUTDOWN)
+            break;
+    }
+
+    mpv_destroy(ctx);
+    return 0;
+}
diff --git a/DOCS/man/en/options.rst b/DOCS/man/en/options.rst
index 46586e69cf..44fe7ff6ca 100644
--- a/DOCS/man/en/options.rst
+++ b/DOCS/man/en/options.rst
@@ -2411,6 +2411,13 @@ OPTIONS
 
     Default: ``[-+-]``.
 
+``--no-terminal``, ``--terminal``
+    Disable any use of the terminal and stdin/stdout/stderr. This completely
+    silences any message output.
+
+    Unlike ``--really-quiet``, this disables input and terminal initialization
+    as well.
+
 ``--title=<string>``
     Set the window title. Properties are expanded on playback start.
     (See `Property Expansion`_.)
diff --git a/common/msg.c b/common/msg.c
index 7ac3d1b665..9b93a3fb7a 100644
--- a/common/msg.c
+++ b/common/msg.c
@@ -45,6 +45,7 @@ struct mp_log_root {
     struct mpv_global *global;
     // --- protected by mp_msg_lock
     char *msglevels;
+    bool use_terminal;  // make accesses to stderr/stdout
     bool smode;         // slave mode compatibility glue
     bool module;
     bool termosd;       // use terminal control codes for status line
@@ -98,18 +99,22 @@ static bool match_mod(const char *name, bstr mod)
 static void update_loglevel(struct mp_log *log)
 {
     pthread_mutex_lock(&mp_msg_lock);
-    log->level = MSGL_STATUS + log->root->verbose; // default log level
-    // Stupid exception for the remains of -identify
-    if (match_mod(log->verbose_prefix, bstr0("identify")))
-        log->level = -1;
-    bstr s = bstr0(log->root->msglevels);
-    bstr mod;
-    int level;
-    while (mp_msg_split_msglevel(&s, &mod, &level) > 0) {
-        if (match_mod(log->verbose_prefix, mod))
-            log->level = level;
+    log->level = -1;
+    log->terminal_level = -1;
+    if (log->root->use_terminal) {
+        log->level = MSGL_STATUS + log->root->verbose; // default log level
+        // Stupid exception for the remains of -identify
+        if (match_mod(log->verbose_prefix, bstr0("identify")))
+            log->level = -1;
+        bstr s = bstr0(log->root->msglevels);
+        bstr mod;
+        int level;
+        while (mp_msg_split_msglevel(&s, &mod, &level) > 0) {
+            if (match_mod(log->verbose_prefix, mod))
+                log->level = level;
+        }
+        log->terminal_level = log->root->use_terminal ? log->level : -1;
     }
-    log->terminal_level = log->level;
     for (int n = 0; n < log->root->num_buffers; n++)
         log->level = MPMAX(log->level, log->root->buffers[n]->level);
     log->reload_counter = log->root->reload_counter;
@@ -372,8 +377,11 @@ void mp_msg_update_msglevels(struct mpv_global *global)
     root->verbose = opts->verbose;
     root->module = opts->msg_module;
     root->smode = opts->msg_identify;
-    root->color = opts->msg_color && isatty(fileno(stdout));
-    root->termosd = !opts->slave_mode && isatty(fileno(stderr));
+    root->use_terminal = opts->use_terminal;
+    if (root->use_terminal) {
+        root->color = opts->msg_color && isatty(fileno(stdout));
+        root->termosd = !opts->slave_mode && isatty(fileno(stderr));
+    }
 
     talloc_free(root->msglevels);
     root->msglevels = talloc_strdup(root, global->opts->msglevels);
diff --git a/libmpv/client.h b/libmpv/client.h
new file mode 100644
index 0000000000..2f1b415285
--- /dev/null
+++ b/libmpv/client.h
@@ -0,0 +1,809 @@
+/* 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
+
+/**
+ * Warning: this API is still work in progress. This notice will be removed
+ * once the API is considered reasonably stable.
+ */
+
+/**
+ * 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 (with mpv_wait_event())
+ * in order to receive events, although it also should 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.
+ * - The FPU precision must be set at least to double precision.
+ * - On Windows, mpv will call timeBeginPeriod(1).
+ *
+ * Embedding the video window
+ * --------------------------
+ *
+ * Currently you have to get the raw window handle, and set it as "wid" option.
+ * This works on X11 and win32 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).
+ */
+
+/**
+ * The version is incremented on each change. The 16 lower bits are incremented
+ * if something in mpv is changed that might affect the client API, but doesn't
+ * change C API itself (like the removal of an option or a property). The higher
+ * 16 bits are incremented if the C API itself changes.
+ */
+#define MPV_CLIENT_API_VERSION 0x00000000UL
+
+/**
+ * Return the MPV_CLIENT_API_VERSION the mpv source has been compiled with.
+ */
+unsigned long mpv_client_api_version(void);
+
+/**
+ * Client context used by the client API. Every client has its own private
+ * handle.
+ */
+typedef struct mpv_handle mpv_handle;
+
+/**
+ * List of error codes than can be returned by API functions. 0 and positive
+ * return values always mean success, negative values are always errors.
+ */
+typedef enum mpv_error {
+    /**
+     * No error happened (used to signal successful operation).
+     * Keep in mind that many API functions returning error codes can also
+     * return positive values, which also indicate success. API users can
+     * hardcode the fact that ">= 0" means success.
+     */
+    MPV_ERROR_SUCCESS           = 0,
+    /**
+     * The event ringbuffer is full. This means the client is choked, and can't
+     * receive any events. This can happen when too many asynchronous requests
+     * have been made, but not answered. Probably never happens in practice,
+     * unless the mpv core is frozen for some reason, and the client keeps
+     * making asynchronous requests. (Bugs in the client API implementation
+     * could also trigger this, e.g. if events become "lost".)
+     */
+    MPV_ERROR_EVENT_QUEUE_FULL = -1,
+    /**
+     * Memory allocation failed.
+     */
+    MPV_ERROR_NOMEM             = -2,
+    /**
+     * The mpv core wasn't configured and initialized yet. See the notes in
+     * mpv_create().
+     */
+    MPV_ERROR_UNINITIALIZED     = -3,
+    /**
+     * Generic catch-all error if a parameter is set to an invalid or
+     * unsupported value. This is used if there is no better error code.
+     */
+    MPV_ERROR_INVALID_PARAMETER = -4,
+    /**
+     * Trying to set an option that doesn't exist.
+     */
+    MPV_ERROR_OPTION_NOT_FOUND  = -5,
+    /**
+     * Trying to set an option using an unsupported MPV_FORMAT.
+     */
+    MPV_ERROR_OPTION_FORMAT     = -6,
+    /**
+     * Setting the option failed. Typically this happens if the provided option
+     * value could not be parsed.
+     */
+    MPV_ERROR_OPTION_ERROR      = -7,
+    /**
+     * The accessed property doesn't exist.
+     */
+    MPV_ERROR_PROPERTY_NOT_FOUND = -8,
+    /**
+     * Trying to set or get a property using an unsupported MPV_FORMAT.
+     */
+    MPV_ERROR_PROPERTY_FORMAT    = -9,
+    /**
+     * The property exists, but is not available. This usually happens when the
+     * associated subsystem is not active, e.g. querying audio parameters while
+     * audio is disabled.
+     */
+    MPV_ERROR_PROPERTY_UNAVAILABLE = -10,
+    /**
+     * Error setting or getting a property.
+     */
+    MPV_ERROR_PROPERTY_ERROR    = -11,
+} mpv_error;
+
+/**
+ * Return a string describing the error. For unknown errors, the string
+ * "unknown error" is returned.
+ *
+ * @param error error number, see enum mpv_error
+ * @return A static string describing the error. The string is completely
+ *         static, i.e. doesn't need to be deallocated, and is valid forever.
+ */
+const char *mpv_error_string(int error);
+
+/**
+ * General function to deallocate memory returned by some of the API functions.
+ * Call this only if it's explicitly documented as allowed. Calling this on
+ * mpv memory not owned by the caller will lead to undefined behavior.
+ *
+ * @param data A valid pointer returned by the API, or NULL.
+ */
+void mpv_free(void *data);
+
+/**
+ * Return the name of this client handle. Every client has its own unique
+ * name, which is mostly used for user interface purposes.
+ *
+ * @return The client name. The string is read-only and is valid until
+ *         mpv_destroy() is called.
+ */
+const char *mpv_client_name(mpv_handle *ctx);
+
+/**
+ * Create a new mpv instance and an associated client API handle to control
+ * the mpv instance. This instance is in a pre-initialized state,
+ * and needs to be initialized to be actually used with most other API
+ * functions.
+ *
+ * Most API functions will return MPV_ERROR_UNINITIALIZED in the uninitialized
+ * state. You can call mpv_set_option() (or mpv_set_option_string() and other
+ * variants) to set initial options. After this, call mpv_initialize() to start
+ * the player, and then use e.g. mpv_command() to start playback of a file.
+ *
+ * The point of separating handle creation and actual initialization is that
+ * you can configure things which can't be changed during runtime.
+ *
+ * Unlike the command line player, this will have initial settings suitable
+ * for embedding in applications. The following settings are different:
+ * - stdin/stdout/stderr and the terminal will never be accessed. This is
+ *   equivalent to setting the --no-terminal option.
+ *   (Technically, this also suppresses C signal handling.)
+ * - No config files will be loaded. This is roughly equivalent to using
+ *   --no-config (but actually the code path for loading config files is
+ *   disabled).
+ * - Idle mode is enabled, which means the playback core will enter idle mode
+ *   if there are no more files to play on the internal playlist, instead of
+ *   exiting. This is equivalent to the --idle option.
+ * - Disable parts of input handling.
+ *
+ * All this assumes that API users want a mpv instance that is strictly
+ * isolated from the command line player's configuration, user settings, and
+ * so on. You can re-enable disabled features by setting the appropriate
+ * options.
+ *
+ * The mpv command line parser is not available through this API, but you can
+ * set individual options with mpv_set_option(). Files for playback must be
+ * loaded with mpv_command() or others.
+ *
+ * Note that you should avoid doing concurrent accesses on the uninitialized
+ * client handle. (Whether concurrent access is definitely allowed or not has
+ * yet to be decided.)
+ *
+ * @return a new mpv client API handle
+ */
+mpv_handle *mpv_create(void);
+
+/**
+ * Initialize an uninitialized mpv instance. If the mpv instance is already
+ * running, an error is retuned.
+ *
+ * This function needs to be called to make full use of the client API if the
+ * client API handle was created with mpv_create().
+ *
+ * @return error code
+ */
+int mpv_initialize(mpv_handle *ctx);
+
+/**
+ * Disconnect and destroy the client context. ctx will be deallocated with this
+ * API call. This leaves the player running. If you want to be sure that the
+ * player is terminated, send a "quit" command, and wait until the
+ * MPV_EVENT_SHUTDOWN event is received.
+ */
+void mpv_destroy(mpv_handle *ctx);
+
+/**
+ * Stop the playback thread. Normally, the client API stops the playback thread
+ * automatically in order to process requests. However, the playback thread is
+ * restarted again after the request was processed. Then the playback thread
+ * will continue to display the next video frame, during which it will not
+ * reply to any requests. (This takes up to 50ms.)
+ *
+ * (Internally, it first renders the video and other things, and then blocks
+ * until it can be displayed - and it won't react to anything else in that
+ * time. The main reason for that is that the VO is in a "in between" state,
+ * in which it can't process normal requests - for example, OSD redrawing or
+ * screenshots would be broken.)
+ *
+ * This is usually a problem: only 1 request per video frame will be executed,
+ * which will make the client API to appear extremely slow.
+ *
+ * Suspending the playback thread allows you to prevent the playback thread from
+ * running, so that you can make multiple accesses without being blocked.
+ *
+ * Suspension is reentrant and recursive for convenience. Any thread can call
+ * the suspend function multiple times, and the playback thread will remain
+ * suspended until the last thread resumes it. Note that during suspension,
+ * clients still have concurrent access to the core, which is serialized through
+ * a single mutex.
+ *
+ * Call mpv_resume() to resume the playback thread. You must call mpv_resume()
+ * for each mpv_suspend() call. Calling mpv_resume() more often than
+ * mpv_suspend() is not allowed.
+ *
+ * Calling this on an uninitialized player (see mpv_create()) will deadlock.
+ *
+ * Note: the need for this call might go away at some point.
+ */
+void mpv_suspend(mpv_handle *ctx);
+
+/**
+ * See mpv_suspend().
+ */
+void mpv_resume(mpv_handle *ctx);
+
+/**
+ * Data format for options and properties. The API functions to get/set
+ * properties and options support multiple formats, and this enum describes
+ * them.
+ */
+typedef enum mpv_format {
+    /**
+     * Invalid.
+     */
+    MPV_FORMAT_NONE             = 0,
+    /**
+     * The basic type is char*. It returns the raw property string, like
+     * using ${=property} in input.conf (see input.rst).
+     *
+     * Example for reading:
+     *
+     *     char *result = NULL;
+     *     if (mpv_get_property(ctx, "property", MPV_FORMAT_STRING, &result) < 0)
+     *         goto error;
+     *     printf("%s\n", result);
+     *     mpv_free(result);
+     *
+     * Example for writing:
+     *
+     *     char *value = "the new value";
+     *     mpv_set_property(ctx, "property", MPV_FORMAT_STRING, (void *)value);
+     *
+     */
+    MPV_FORMAT_STRING           = 1,
+    /**
+     * The basic type is char*. It returns the OSD property string, like
+     * using ${property} in input.conf (see input.rst). In many cases, this
+     * is the same as the raw string, but in other cases it's formatted for
+     * display on OSD. It's intended to be human readable. Do not attempt to
+     * parse these strings.
+     *
+     * Only valid when doing read access. The rest works like MPV_FORMAT_STRING.
+     */
+    MPV_FORMAT_OSD_STRING       = 2,
+} mpv_format;
+
+/**
+ * Set an option. Note that you can't normally set options during runtime. It
+ * works in uninitialized state (see mpv_create()), and in some cases in idle
+ * mode.
+ *
+ * You can use mpv_set_property() to change options during playback, but this
+ * does not work with all options.
+ *
+ * @param name Option name. This is the same as on the mpv command line, but
+ *             without the leading "--".
+ * @param format see enum mpv_format. Currently, only MPV_FORMAT_STRING is valid.
+ * @param[in] data Option value (according to the format).
+ * @return error code
+ */
+int mpv_set_option(mpv_handle *ctx, const char *name, mpv_format format,
+                   void *data);
+
+/**
+ * Convenience function to set an option to a string value. This is like
+ * calling mpv_set_option() with MPV_FORMAT_STRING.
+ *
+ * @return error code
+ */
+int mpv_set_option_string(mpv_handle *ctx, const char *name, const char *data);
+
+/**
+ * Send a command to the player. Commands are the same as those used in
+ * input.conf, except that this function takes parameters in a pre-split
+ * form.
+ *
+ * The commands and their parameters are documented in input.rst.
+ *
+ * Caveat: currently, commands do not report whether they run successfully. If
+ *         the command exists and its arguments are not broken, always success
+ *         will be returned.
+ *
+ * @param[in] args NULL-terminated list of strings. Usually, the first item
+ *                 is the command, and the following items are arguments.
+ * @return error code
+ */
+int mpv_command(mpv_handle *ctx, const char **args);
+
+/**
+ * Same as mpv_command, but use input.conf parsing for splitting arguments.
+ * This is slightly simpler, but also more error prone, since arguments may
+ * need quoting/escaping.
+ */
+int mpv_command_string(mpv_handle *ctx, const char *args);
+
+/**
+ * Same as mpv_command, but run the command asynchronously.
+ *
+ * Commands are executed asynchronously. You will receive a
+ * MPV_EVENT_COMMAND_REPLY event. (This event will also have an
+ * error code set if running the command failed.)
+ *
+ * @param reply_userdata see section about asynchronous calls
+ * @param args NULL-terminated list of strings (see mpv_command())
+ * @return error code
+ */
+int mpv_command_async(mpv_handle *ctx, uint64_t reply_userdata,
+                      const char **args);
+
+/**
+ * Set a property to a given value. Properties are essentially variables which
+ * can be queried or set at runtime. For example, writing to the pause property
+ * will actually pause or unpause playback.
+ *
+ * @param name The property name. See input.rst for a list of properties.
+ * @param format see enum mpv_format. Currently, only MPV_FORMAT_STRING is valid.
+ * @param[in] data Option value.
+ * @return error code
+ */
+int mpv_set_property(mpv_handle *ctx, const char *name, mpv_format format,
+                     void *data);
+
+/**
+ * Convenience function to set a property to a string value.
+ *
+ * This is like calling mpv_set_property() with MPV_FORMAT_STRING.
+ */
+int mpv_set_property_string(mpv_handle *ctx, const char *name, const char *data);
+
+/**
+ * Set a property asynchronously. You will receive the result of the operation
+ * as MPV_EVENT_PROPERTY_SET_REPLY event. The mpv.error field will contain the
+ * result status of the operation. Otherwise, this function is similar to
+ * mpv_set_property().
+ *
+ * @param reply_userdata see section about asynchronous calls
+ * @param name The property name.
+ * @param format see enum mpv_format. Currently, only MPV_FORMAT_STRING is valid.
+ * @param[in] data Option value. The value will be copied by the function.
+ * @return error code if sending the request failed
+ */
+int mpv_set_property_async(mpv_handle *ctx, uint64_t reply_userdata,
+                           const char *name, mpv_format format, void *data);
+
+/**
+ * Read the value of the given property.
+ *
+ * @param name The property name.
+ * @param format see enum mpv_format.
+ * @param[out] data Pointer to the variable holding the option value. On
+ *                  success, the variable will be set to a copy of the option
+ *                  value. You can free the value with mpv_free().
+ * @return error code
+ */
+int mpv_get_property(mpv_handle *ctx, const char *name, mpv_format format,
+                     void *data);
+
+/**
+ * Return the value of the property with the given name as string. This is
+ * equivalent to mpv_get_property() with MPV_FORMAT_STRING.
+ *
+ * On error, NULL is returned. Use mpv_get_property() if you want fine-grained
+ * error reporting.
+ *
+ * @param name The property name.
+ * @return Property value, or NULL if the property can't be retrieved. Free
+ *         the string with mpv_free().
+ */
+char *mpv_get_property_string(mpv_handle *ctx, const char *name);
+
+/**
+ * Return the property as "OSD" formatted string. This is the same as
+ * mpv_get_property_string, but using MPV_FORMAT_OSD_STRING.
+ *
+ * @return Property value, or NULL if the property can't be retrieved. Free
+ *         the string with mpv_free().
+ */
+char *mpv_get_property_osd_string(mpv_handle *ctx, const char *name);
+
+/**
+ * Get a property asynchronously. You will receive the result of the operation
+ * as well as the property data with the MPV_EVENT_GET_PROPERTY_REPLY event.
+ *
+ * @param reply_userdata see section about asynchronous calls
+ * @param name The property name.
+ * @param format see enum mpv_format.
+ * @return error code if sending the request failed
+ */
+int mpv_get_property_async(mpv_handle *ctx, uint64_t reply_userdata,
+                           const char *name, mpv_format format);
+
+typedef enum mpv_event_id {
+    /**
+     * Nothing happened. Happens on timeouts or sporadic wakeups.
+     */
+    MPV_EVENT_NONE              = 0,
+    /**
+     * Happens when the player quits. The player enters a state where it tries
+     * to disconnect all clients. Most requests to the player will fail, and
+     * mpv_wait_event() will always return instantly (returning new shutdown
+     * events if no other events are queued). The client should react to this
+     * and quit with mpv_destroy() as soon as possible.
+     */
+    MPV_EVENT_SHUTDOWN          = 1,
+    /**
+     * See mpv_request_log_messages().
+     */
+    MPV_EVENT_LOG_MESSAGE       = 2,
+    /**
+     * Reply to a mpv_get_property_async() request.
+     * See also mpv_event and mpv_event_property.
+     */
+    MPV_EVENT_GET_PROPERTY_REPLY = 3,
+    /**
+     * Reply to a mpv_set_property_async() request.
+     * (Unlike MPV_EVENT_GET_PROPERTY, mpv_event_property is not used.)
+     */
+    MPV_EVENT_SET_PROPERTY_REPLY = 4,
+    /**
+     * Reply to a mpv_command_async() request.
+     */
+    MPV_EVENT_COMMAND_REPLY     = 5,
+    /**
+     * Notification before playback start of a file.
+     */
+    MPV_EVENT_START_FILE        = 6,
+    /**
+     * Notification after playback end (after the file was unloaded).
+     */
+    MPV_EVENT_END_FILE          = 7,
+    /**
+     * Notification when the file has been loaded (headers were read etc.), and
+     * decoding starts.
+     */
+    MPV_EVENT_PLAYBACK_START    = 8,
+    /**
+     * The list of video/audio/subtitle tracks was changed.
+     */
+    MPV_EVENT_TRACKS_CHANGED    = 9,
+    /**
+     * A video/audio/subtitle track was switched on or off.
+     */
+    MPV_EVENT_TRACK_SWITCHED    = 10,
+    /**
+     * Idle mode was entered. In this mode, no file is played, and the playback
+     * core waits for new commands. (The command line player normally quits
+     * instead of entering idle mode, unless --idle was specified. If mpv
+     * was started with mpv_create(), idle mode is enabled by default.)
+     */
+    MPV_EVENT_IDLE              = 11,
+    /**
+     * Playback was paused.
+     */
+    MPV_EVENT_PAUSE             = 12,
+    /**
+     * Playback was unpaused.
+     */
+    MPV_EVENT_UNPAUSE           = 13,
+    /**
+     * Sent every time after a video frame is displayed (or in lower frequency
+     * if there is no video, or playback is paused).
+     */
+    MPV_EVENT_TICK              = 14,
+    /**
+     * Triggered by the script_dispatch input command. The command uses the
+     * client name (see mpv_client_name()) to dispatch keyboard or mouse input
+     * to a client.
+     */
+    MPV_EVENT_SCRIPT_INPUT_DISPATCH = 15,
+} mpv_event_id;
+
+/**
+ * Return a string describing the event. For unknown events, NULL is returned.
+ *
+ * Note that all events actually returned by the API will also yield a non-NULL
+ * string with this function.
+ *
+ * @param event event ID, see see enum