libmpv  20200718-git-96cdf53
development library for the MPV media player
Looking for a C++ dev?
I'm looking for work. Hire me!
client.h
Go to the documentation of this file.
1 /* Copyright (C) 2017 the mpv developers
2  *
3  * Permission to use, copy, modify, and/or distribute this software for any
4  * purpose with or without fee is hereby granted, provided that the above
5  * copyright notice and this permission notice appear in all copies.
6  *
7  * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
8  * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
9  * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
10  * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
11  * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
12  * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
13  * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
14  */
15 
16 /*
17  * Note: the client API is licensed under ISC (see above) to enable
18  * other wrappers outside of mpv. But keep in mind that the
19  * mpv core is by default still GPLv2+ - unless built with
20  * --enable-lgpl, which makes it LGPLv2+.
21  */
22 
23 #ifndef MPV_CLIENT_API_H_
24 #define MPV_CLIENT_API_H_
25 
26 #include <stddef.h>
27 #include <stdint.h>
28 
29 #ifdef __cplusplus
30 extern "C" {
31 #endif
32 
33 /**
34  * Mechanisms provided by this API
35  * -------------------------------
36  *
37  * This API provides general control over mpv playback. It does not give you
38  * direct access to individual components of the player, only the whole thing.
39  * It's somewhat equivalent to MPlayer's slave mode. You can send commands,
40  * retrieve or set playback status or settings with properties, and receive
41  * events.
42  *
43  * The API can be used in two ways:
44  * 1) Internally in mpv, to provide additional features to the command line
45  * player. Lua scripting uses this. (Currently there is no plugin API to
46  * get a client API handle in external user code. It has to be a fixed
47  * part of the player at compilation time.)
48  * 2) Using mpv as a library with mpv_create(). This basically allows embedding
49  * mpv in other applications.
50  *
51  * Documentation
52  * -------------
53  *
54  * The libmpv C API is documented directly in this header. Note that most
55  * actual interaction with this player is done through
56  * options/commands/properties, which can be accessed through this API.
57  * Essentially everything is done with them, including loading a file,
58  * retrieving playback progress, and so on.
59  *
60  * These are documented elsewhere:
61  * * http://mpv.io/manual/master/#options
62  * * http://mpv.io/manual/master/#list-of-input-commands
63  * * http://mpv.io/manual/master/#properties
64  *
65  * You can also look at the examples here:
66  * * https://github.com/mpv-player/mpv-examples/tree/master/libmpv
67  *
68  * Event loop
69  * ----------
70  *
71  * In general, the API user should run an event loop in order to receive events.
72  * This event loop should call mpv_wait_event(), which will return once a new
73  * mpv client API is available. It is also possible to integrate client API
74  * usage in other event loops (e.g. GUI toolkits) with the
75  * mpv_set_wakeup_callback() function, and then polling for events by calling
76  * mpv_wait_event() with a 0 timeout.
77  *
78  * Note that the event loop is detached from the actual player. Not calling
79  * mpv_wait_event() will not stop playback. It will eventually congest the
80  * event queue of your API handle, though.
81  *
82  * Synchronous vs. asynchronous calls
83  * ----------------------------------
84  *
85  * The API allows both synchronous and asynchronous calls. Synchronous calls
86  * have to wait until the playback core is ready, which currently can take
87  * an unbounded time (e.g. if network is slow or unresponsive). Asynchronous
88  * calls just queue operations as requests, and return the result of the
89  * operation as events.
90  *
91  * Asynchronous calls
92  * ------------------
93  *
94  * The client API includes asynchronous functions. These allow you to send
95  * requests instantly, and get replies as events at a later point. The
96  * requests are made with functions carrying the _async suffix, and replies
97  * are returned by mpv_wait_event() (interleaved with the normal event stream).
98  *
99  * A 64 bit userdata value is used to allow the user to associate requests
100  * with replies. The value is passed as reply_userdata parameter to the request
101  * function. The reply to the request will have the reply
102  * mpv_event->reply_userdata field set to the same value as the
103  * reply_userdata parameter of the corresponding request.
104  *
105  * This userdata value is arbitrary and is never interpreted by the API. Note
106  * that the userdata value 0 is also allowed, but then the client must be
107  * careful not accidentally interpret the mpv_event->reply_userdata if an
108  * event is not a reply. (For non-replies, this field is set to 0.)
109  *
110  * Asynchronous calls may be reordered in arbitrarily with other synchronous
111  * and asynchronous calls. If you want a guaranteed order, you need to wait
112  * until asynchronous calls report completion before doing the next call.
113  *
114  * See also the section "Asynchronous command details" in the manpage.
115  *
116  * Multithreading
117  * --------------
118  *
119  * The client API is generally fully thread-safe, unless otherwise noted.
120  * Currently, there is no real advantage in using more than 1 thread to access
121  * the client API, since everything is serialized through a single lock in the
122  * playback core.
123  *
124  * Basic environment requirements
125  * ------------------------------
126  *
127  * This documents basic requirements on the C environment. This is especially
128  * important if mpv is used as library with mpv_create().
129  *
130  * - The LC_NUMERIC locale category must be set to "C". If your program calls
131  * setlocale(), be sure not to use LC_ALL, or if you do, reset LC_NUMERIC
132  * to its sane default: setlocale(LC_NUMERIC, "C").
133  * - If a X11 based VO is used, mpv will set the xlib error handler. This error
134  * handler is process-wide, and there's no proper way to share it with other
135  * xlib users within the same process. This might confuse GUI toolkits.
136  * - mpv uses some other libraries that are not library-safe, such as Fribidi
137  * (used through libass), ALSA, FFmpeg, and possibly more.
138  * - The FPU precision must be set at least to double precision.
139  * - On Windows, mpv will call timeBeginPeriod(1).
140  * - On memory exhaustion, mpv will kill the process.
141  * - In certain cases, mpv may start sub processes (such as with the ytdl
142  * wrapper script).
143  * - Using UNIX IPC (off by default) will override the SIGPIPE signal handler,
144  * and set it to SIG_IGN.
145  * - mpv will reseed the legacy C random number generator by calling srand() at
146  * some random point once.
147  * - mpv may start sub processes, so overriding SIGCHLD, or waiting on all PIDs
148  * (such as calling wait()) by the parent process or any other library within
149  * the process must be avoided. libmpv itself only waits for its own PIDs.
150  *
151  * Encoding of filenames
152  * ---------------------
153  *
154  * mpv uses UTF-8 everywhere.
155  *
156  * On some platforms (like Linux), filenames actually do not have to be UTF-8;
157  * for this reason libmpv supports non-UTF-8 strings. libmpv uses what the
158  * kernel uses and does not recode filenames. At least on Linux, passing a
159  * string to libmpv is like passing a string to the fopen() function.
160  *
161  * On Windows, filenames are always UTF-8, libmpv converts between UTF-8 and
162  * UTF-16 when using win32 API functions. libmpv never uses or accepts
163  * filenames in the local 8 bit encoding. It does not use fopen() either;
164  * it uses _wfopen().
165  *
166  * On OS X, filenames and other strings taken/returned by libmpv can have
167  * inconsistent unicode normalization. This can sometimes lead to problems.
168  * You have to hope for the best.
169  *
170  * Also see the remarks for MPV_FORMAT_STRING.
171  *
172  * Embedding the video window
173  * --------------------------
174  *
175  * Using the render API (in render_cb.h) is recommended. This API requires
176  * you to create and maintain an OpenGL context, to which you can render
177  * video using a specific API call. This API does not include keyboard or mouse
178  * input directly.
179  *
180  * There is an older way to embed the native mpv window into your own. You have
181  * to get the raw window handle, and set it as "wid" option. This works on X11,
182  * win32, and OSX only. It's much easier to use than the render API, but
183  * also has various problems.
184  *
185  * Also see client API examples and the mpv manpage. There is an extensive
186  * discussion here:
187  * https://github.com/mpv-player/mpv-examples/tree/master/libmpv#methods-of-embedding-the-video-window
188  *
189  * Compatibility
190  * -------------
191  *
192  * mpv development doesn't stand still, and changes to mpv internals as well as
193  * to its interface can cause compatibility issues to client API users.
194  *
195  * The API is versioned (see MPV_CLIENT_API_VERSION), and changes to it are
196  * documented in DOCS/client-api-changes.rst. The C API itself will probably
197  * remain compatible for a long time, but the functionality exposed by it
198  * could change more rapidly. For example, it's possible that options are
199  * renamed, or change the set of allowed values.
200  *
201  * Defensive programming should be used to potentially deal with the fact that
202  * options, commands, and properties could disappear, change their value range,
203  * or change the underlying datatypes. It might be a good idea to prefer
204  * MPV_FORMAT_STRING over other types to decouple your code from potential
205  * mpv changes.
206  *
207  * Also see: DOCS/compatibility.rst
208  *
209  * Future changes
210  * --------------
211  *
212  * This are the planned changes that will most likely be done on the next major
213  * bump of the library:
214  *
215  * - remove all symbols and include files that are marked as deprecated
216  * - reassign enum numerical values to remove gaps
217  * - remove the mpv_opengl_init_params.extra_exts field
218  * - change the type of mpv_event_end_file.reason
219  * - disabling all events by default
220  */
221 
222 /**
223  * The version is incremented on each API change. The 16 lower bits form the
224  * minor version number, and the 16 higher bits the major version number. If
225  * the API becomes incompatible to previous versions, the major version
226  * number is incremented. This affects only C part, and not properties and
227  * options.
228  *
229  * Every API bump is described in DOCS/client-api-changes.rst
230  *
231  * You can use MPV_MAKE_VERSION() and compare the result with integer
232  * relational operators (<, >, <=, >=).
233  */
234 #define MPV_MAKE_VERSION(major, minor) (((major) << 16) | (minor) | 0UL)
235 #define MPV_CLIENT_API_VERSION MPV_MAKE_VERSION(1, 109)
236 
237 /**
238  * The API user is allowed to "#define MPV_ENABLE_DEPRECATED 0" before
239  * including any libmpv headers. Then deprecated symbols will be excluded
240  * from the headers. (Of course, deprecated properties and commands and
241  * other functionality will still work.)
242  */
243 #ifndef MPV_ENABLE_DEPRECATED
244 #define MPV_ENABLE_DEPRECATED 1
245 #endif
246 
247 /**
248  * Return the MPV_CLIENT_API_VERSION the mpv source has been compiled with.
249  */
250 unsigned long mpv_client_api_version(void);
251 
252 /**
253  * Client context used by the client API. Every client has its own private
254  * handle.
255  */
256 typedef struct mpv_handle mpv_handle;
257 
258 /**
259  * List of error codes than can be returned by API functions. 0 and positive
260  * return values always mean success, negative values are always errors.
261  */
262 typedef enum mpv_error {
263  /**
264  * No error happened (used to signal successful operation).
265  * Keep in mind that many API functions returning error codes can also
266  * return positive values, which also indicate success. API users can
267  * hardcode the fact that ">= 0" means success.
268  */
270  /**
271  * The event ringbuffer is full. This means the client is choked, and can't
272  * receive any events. This can happen when too many asynchronous requests
273  * have been made, but not answered. Probably never happens in practice,
274  * unless the mpv core is frozen for some reason, and the client keeps
275  * making asynchronous requests. (Bugs in the client API implementation
276  * could also trigger this, e.g. if events become "lost".)
277  */
279  /**
280  * Memory allocation failed.
281  */
283  /**
284  * The mpv core wasn't configured and initialized yet. See the notes in
285  * mpv_create().
286  */
288  /**
289  * Generic catch-all error if a parameter is set to an invalid or
290  * unsupported value. This is used if there is no better error code.
291  */
293  /**
294  * Trying to set an option that doesn't exist.
295  */
297  /**
298  * Trying to set an option using an unsupported MPV_FORMAT.
299  */
301  /**
302  * Setting the option failed. Typically this happens if the provided option
303  * value could not be parsed.
304  */
306  /**
307  * The accessed property doesn't exist.
308  */
310  /**
311  * Trying to set or get a property using an unsupported MPV_FORMAT.
312  */
314  /**
315  * The property exists, but is not available. This usually happens when the
316  * associated subsystem is not active, e.g. querying audio parameters while
317  * audio is disabled.
318  */
320  /**
321  * Error setting or getting a property.
322  */
324  /**
325  * General error when running a command with mpv_command and similar.
326  */
328  /**
329  * Generic error on loading (usually used with mpv_event_end_file.error).
330  */
332  /**
333  * Initializing the audio output failed.
334  */
336  /**
337  * Initializing the video output failed.
338  */
340  /**
341  * There was no audio or video data to play. This also happens if the
342  * file was recognized, but did not contain any audio or video streams,
343  * or no streams were selected.
344  */
346  /**
347  * When trying to load the file, the file format could not be determined,
348  * or the file was too broken to open it.
349  */
351  /**
352  * Generic error for signaling that certain system requirements are not
353  * fulfilled.
354  */
356  /**
357  * The API function which was called is a stub only.
358  */
360  /**
361  * Unspecified error.
362  */
364 } mpv_error;
365 
366 /**
367  * Return a string describing the error. For unknown errors, the string
368  * "unknown error" is returned.
369  *
370  * @param error error number, see enum mpv_error
371  * @return A static string describing the error. The string is completely
372  * static, i.e. doesn't need to be deallocated, and is valid forever.
373  */
374 const char *mpv_error_string(int error);
375 
376 /**
377  * General function to deallocate memory returned by some of the API functions.
378  * Call this only if it's explicitly documented as allowed. Calling this on
379  * mpv memory not owned by the caller will lead to undefined behavior.
380  *
381  * @param data A valid pointer returned by the API, or NULL.
382  */
383 void mpv_free(void *data);
384 
385 /**
386  * Return the name of this client handle. Every client has its own unique
387  * name, which is mostly used for user interface purposes.
388  *
389  * @return The client name. The string is read-only and is valid until the
390  * mpv_handle is destroyed.
391  */
392 const char *mpv_client_name(mpv_handle *ctx);
393 
394 /**
395  * Return the ID of this client handle. Every client has its own unique ID. This
396  * ID is never reused by the core, even if the mpv_handle at hand gets destroyed
397  * and new handles get allocated.
398  *
399  * IDs are never 0 or negative.
400  *
401  * Some mpv APIs (not necessarily all) accept a name in the form "@<id>" in
402  * addition of the proper mpv_client_name(), where "<id>" is the ID in decimal
403  * form (e.g. "@123"). For example, the "script-message-to" command takes the
404  * client name as first argument, but also accepts the client ID formatted in
405  * this manner.
406  *
407  * @return The client name. The string is read-only and is valid until the
408  * mpv_handle is destroyed.
409  */
410 int64_t mpv_client_id(mpv_handle *ctx);
411 
412 /**
413  * Create a new mpv instance and an associated client API handle to control
414  * the mpv instance. This instance is in a pre-initialized state,
415  * and needs to be initialized to be actually used with most other API
416  * functions.
417  *
418  * Some API functions will return MPV_ERROR_UNINITIALIZED in the uninitialized
419  * state. You can call mpv_set_property() (or mpv_set_property_string() and
420  * other variants, and before mpv 0.21.0 mpv_set_option() etc.) to set initial
421  * options. After this, call mpv_initialize() to start the player, and then use
422  * e.g. mpv_command() to start playback of a file.
423  *
424  * The point of separating handle creation and actual initialization is that
425  * you can configure things which can't be changed during runtime.
426  *
427  * Unlike the command line player, this will have initial settings suitable
428  * for embedding in applications. The following settings are different:
429  * - stdin/stdout/stderr and the terminal will never be accessed. This is
430  * equivalent to setting the --no-terminal option.
431  * (Technically, this also suppresses C signal handling.)
432  * - No config files will be loaded. This is roughly equivalent to using
433  * --config=no. Since libmpv 1.15, you can actually re-enable this option,
434  * which will make libmpv load config files during mpv_initialize(). If you
435  * do this, you are strongly encouraged to set the "config-dir" option too.
436  * (Otherwise it will load the mpv command line player's config.)
437  * For example:
438  * mpv_set_option_string(mpv, "config-dir", "/my/path"); // set config root
439  * mpv_set_option_string(mpv, "config", "yes"); // enable config loading
440  * (call mpv_initialize() _after_ this)
441  * - Idle mode is enabled, which means the playback core will enter idle mode
442  * if there are no more files to play on the internal playlist, instead of
443  * exiting. This is equivalent to the --idle option.
444  * - Disable parts of input handling.
445  * - Most of the different settings can be viewed with the command line player
446  * by running "mpv --show-profile=libmpv".
447  *
448  * All this assumes that API users want a mpv instance that is strictly
449  * isolated from the command line player's configuration, user settings, and
450  * so on. You can re-enable disabled features by setting the appropriate
451  * options.
452  *
453  * The mpv command line parser is not available through this API, but you can
454  * set individual options with mpv_set_property(). Files for playback must be
455  * loaded with mpv_command() or others.
456  *
457  * Note that you should avoid doing concurrent accesses on the uninitialized
458  * client handle. (Whether concurrent access is definitely allowed or not has
459  * yet to be decided.)
460  *
461  * @return a new mpv client API handle. Returns NULL on error. Currently, this
462  * can happen in the following situations:
463  * - out of memory
464  * - LC_NUMERIC is not set to "C" (see general remarks)
465  */
466 mpv_handle *mpv_create(void);
467 
468 /**
469  * Initialize an uninitialized mpv instance. If the mpv instance is already
470  * running, an error is returned.
471  *
472  * This function needs to be called to make full use of the client API if the
473  * client API handle was created with mpv_create().
474  *
475  * Only the following options are required to be set _before_ mpv_initialize():
476  * - options which are only read at initialization time:
477  * - config
478  * - config-dir
479  * - input-conf
480  * - load-scripts
481  * - script
482  * - player-operation-mode
483  * - input-app-events (OSX)
484  * - all encoding mode options
485  *
486  * @return error code
487  */
488 int mpv_initialize(mpv_handle *ctx);
489 
490 /**
491  * Disconnect and destroy the mpv_handle. ctx will be deallocated with this
492  * API call.
493  *
494  * If the last mpv_handle is detached, the core player is destroyed. In
495  * addition, if there are only weak mpv_handles (such as created by
496  * mpv_create_weak_client() or internal scripts), these mpv_handles will
497  * be sent MPV_EVENT_SHUTDOWN. This function may block until these clients
498  * have responded to the shutdown event, and the core is finally destroyed.
499  */
500 void mpv_destroy(mpv_handle *ctx);
501 
502 #if MPV_ENABLE_DEPRECATED
503 /**
504  * @deprecated use mpv_destroy(), which has exactly the same semantics (the
505  * deprecation is a mere rename)
506  *
507  * Since mpv client API version 1.29:
508  * If the last mpv_handle is detached, the core player is destroyed. In
509  * addition, if there are only weak mpv_handles (such as created by
510  * mpv_create_weak_client() or internal scripts), these mpv_handles will
511  * be sent MPV_EVENT_SHUTDOWN. This function may block until these clients
512  * have responded to the shutdown event, and the core is finally destroyed.
513  *
514  * Before mpv client API version 1.29:
515  * This left the player running. If you want to be sure that the
516  * player is terminated, send a "quit" command, and wait until the
517  * MPV_EVENT_SHUTDOWN event is received, or use mpv_terminate_destroy().
518  */
519 void mpv_detach_destroy(mpv_handle *ctx);
520 #endif
521 
522 /**
523  * Similar to mpv_destroy(), but brings the player and all clients down
524  * as well, and waits until all of them are destroyed. This function blocks. The
525  * advantage over mpv_destroy() is that while mpv_destroy() merely
526  * detaches the client handle from the player, this function quits the player,
527  * waits until all other clients are destroyed (i.e. all mpv_handles are
528  * detached), and also waits for the final termination of the player.
529  *
530  * Since mpv_destroy() is called somewhere on the way, it's not safe to
531  * call other functions concurrently on the same context.
532  *
533  * Since mpv client API version 1.29:
534  * The first call on any mpv_handle will block until the core is destroyed.
535  * This means it will wait until other mpv_handle have been destroyed. If you
536  * want asynchronous destruction, just run the "quit" command, and then react
537  * to the MPV_EVENT_SHUTDOWN event.
538  * If another mpv_handle already called mpv_terminate_destroy(), this call will
539  * not actually block. It will destroy the mpv_handle, and exit immediately,
540  * while other mpv_handles might still be uninitializing.
541  *
542  * Before mpv client API version 1.29:
543  * If this is called on a mpv_handle that was not created with mpv_create(),
544  * this function will merely send a quit command and then call
545  * mpv_destroy(), without waiting for the actual shutdown.
546  */
548 
549 /**
550  * Create a new client handle connected to the same player core as ctx. This
551  * context has its own event queue, its own mpv_request_event() state, its own
552  * mpv_request_log_messages() state, its own set of observed properties, and
553  * its own state for asynchronous operations. Otherwise, everything is shared.
554  *
555  * This handle should be destroyed with mpv_destroy() if no longer
556  * needed. The core will live as long as there is at least 1 handle referencing
557  * it. Any handle can make the core quit, which will result in every handle
558  * receiving MPV_EVENT_SHUTDOWN.
559  *
560  * This function can not be called before the main handle was initialized with
561  * mpv_initialize(). The new handle is always initialized, unless ctx=NULL was
562  * passed.
563  *
564  * @param ctx Used to get the reference to the mpv core; handle-specific
565  * settings and parameters are not used.
566  * If NULL, this function behaves like mpv_create() (ignores name).
567  * @param name The client name. This will be returned by mpv_client_name(). If
568  * the name is already in use, or contains non-alphanumeric
569  * characters (other than '_'), the name is modified to fit.
570  * If NULL, an arbitrary name is automatically chosen.
571  * @return a new handle, or NULL on error
572  */
573 mpv_handle *mpv_create_client(mpv_handle *ctx, const char *name);
574 
575 /**
576  * This is the same as mpv_create_client(), but the created mpv_handle is
577  * treated as a weak reference. If all mpv_handles referencing a core are
578  * weak references, the core is automatically destroyed. (This still goes
579  * through normal uninit of course. Effectively, if the last non-weak mpv_handle
580  * is destroyed, then the weak mpv_handles receive MPV_EVENT_SHUTDOWN and are
581  * asked to terminate as well.)
582  *
583  * Note if you want to use this like refcounting: you have to be aware that
584  * mpv_terminate_destroy() _and_ mpv_destroy() for the last non-weak
585  * mpv_handle will block until all weak mpv_handles are destroyed.
586  */
587 mpv_handle *mpv_create_weak_client(mpv_handle *ctx, const char *name);
588 
589 /**
590  * Load a config file. This loads and parses the file, and sets every entry in
591  * the config file's default section as if mpv_set_option_string() is called.
592  *
593  * The filename should be an absolute path. If it isn't, the actual path used
594  * is unspecified. (Note: an absolute path starts with '/' on UNIX.) If the
595  * file wasn't found, MPV_ERROR_INVALID_PARAMETER is returned.
596  *
597  * If a fatal error happens when parsing a config file, MPV_ERROR_OPTION_ERROR
598  * is returned. Errors when setting options as well as other types or errors
599  * are ignored (even if options do not exist). You can still try to capture
600  * the resulting error messages with mpv_request_log_messages(). Note that it's
601  * possible that some options were successfully set even if any of these errors
602  * happen.
603  *
604  * @param filename absolute path to the config file on the local filesystem
605  * @return error code
606  */
607 int mpv_load_config_file(mpv_handle *ctx, const char *filename);
608 
609 #if MPV_ENABLE_DEPRECATED
610 
611 /**
612  * This does nothing since mpv 0.23.0 (API version 1.24). Below is the
613  * description of the old behavior.
614  *
615  * Stop the playback thread. This means the core will stop doing anything, and
616  * only run and answer to client API requests. This is sometimes useful; for
617  * example, no new frame will be queued to the video output, so doing requests
618  * which have to wait on the video output can run instantly.
619  *
620  * Suspension is reentrant and recursive for convenience. Any thread can call
621  * the suspend function multiple times, and the playback thread will remain
622  * suspended until the last thread resumes it. Note that during suspension, all
623  * clients still have concurrent access to the core, which is serialized through
624  * a single mutex.
625  *
626  * Call mpv_resume() to resume the playback thread. You must call mpv_resume()
627  * for each mpv_suspend() call. Calling mpv_resume() more often than
628  * mpv_suspend() is not allowed.
629  *
630  * Calling this on an uninitialized player (see mpv_create()) will deadlock.
631  *
632  * @deprecated This function, as well as mpv_resume(), are deprecated, and
633  * will stop doing anything soon. Their semantics were never
634  * well-defined, and their usefulness is extremely limited. The
635  * calls will remain stubs in order to keep ABI compatibility.
636  */
637 void mpv_suspend(mpv_handle *ctx);
638 
639 /**
640  * See mpv_suspend().
641  */
642 void mpv_resume(mpv_handle *ctx);
643 
644 #endif
645 
646 /**
647  * Return the internal time in microseconds. This has an arbitrary start offset,
648  * but will never wrap or go backwards.
649  *
650  * Note that this is always the real time, and doesn't necessarily have to do
651  * with playback time. For example, playback could go faster or slower due to
652  * playback speed, or due to playback being paused. Use the "time-pos" property
653  * instead to get the playback status.
654  *
655  * Unlike other libmpv APIs, this can be called at absolutely any time (even
656  * within wakeup callbacks), as long as the context is valid.
657  *
658  * Safe to be called from mpv render API threads.
659  */
660 int64_t mpv_get_time_us(mpv_handle *ctx);
661 
662 /**
663  * Data format for options and properties. The API functions to get/set
664  * properties and options support multiple formats, and this enum describes
665  * them.
666  */
667 typedef enum mpv_format {
668  /**
669  * Invalid. Sometimes used for empty values. This is always defined to 0,
670  * so a normal 0-init of mpv_format (or e.g. mpv_node) is guaranteed to set
671  * this it to MPV_FORMAT_NONE (which makes some things saner as consequence).
672  */
674  /**
675  * The basic type is char*. It returns the raw property string, like
676  * using ${=property} in input.conf (see input.rst).
677  *
678  * NULL isn't an allowed value.
679  *
680  * Warning: although the encoding is usually UTF-8, this is not always the
681  * case. File tags often store strings in some legacy codepage,
682  * and even filenames don't necessarily have to be in UTF-8 (at
683  * least on Linux). If you pass the strings to code that requires
684  * valid UTF-8, you have to sanitize it in some way.
685  * On Windows, filenames are always UTF-8, and libmpv converts
686  * between UTF-8 and UTF-16 when using win32 API functions. See
687  * the "Encoding of filenames" section for details.
688  *
689  * Example for reading:
690  *
691  * char *result = NULL;
692  * if (mpv_get_property(ctx, "property", MPV_FORMAT_STRING, &result) < 0)
693  * goto error;
694  * printf("%s\n", result);
695  * mpv_free(result);
696  *
697  * Or just use mpv_get_property_string().
698  *
699  * Example for writing:
700  *
701  * char *value = "the new value";
702  * // yep, you pass the address to the variable
703  * // (needed for symmetry with other types and mpv_get_property)
704  * mpv_set_property(ctx, "property", MPV_FORMAT_STRING, &value);
705  *
706  * Or just use mpv_set_property_string().
707  *
708  */
710  /**
711  * The basic type is char*. It returns the OSD property string, like
712  * using ${property} in input.conf (see input.rst). In many cases, this
713  * is the same as the raw string, but in other cases it's formatted for
714  * display on OSD. It's intended to be human readable. Do not attempt to
715  * parse these strings.
716  *
717  * Only valid when doing read access. The rest works like MPV_FORMAT_STRING.
718  */
720  /**
721  * The basic type is int. The only allowed values are 0 ("no")
722  * and 1 ("yes").
723  *
724  * Example for reading:
725  *
726  * int result;
727  * if (mpv_get_property(ctx, "property", MPV_FORMAT_FLAG, &result) < 0)
728  * goto error;
729  * printf("%s\n", result ? "true" : "false");
730  *
731  * Example for writing:
732  *
733  * int flag = 1;
734  * mpv_set_property(ctx, "property", MPV_FORMAT_FLAG, &flag);
735  */
737  /**
738  * The basic type is int64_t.
739  */
741  /**
742  * The basic type is double.
743  */
745  /**
746  * The type is mpv_node.
747  *
748  * For reading, you usually would pass a pointer to a stack-allocated
749  * mpv_node value to mpv, and when you're done you call
750  * mpv_free_node_contents(&node).
751  * You're expected not to write to the data - if you have to, copy it
752  * first (which you have to do manually).
753  *
754  * For writing, you construct your own mpv_node, and pass a pointer to the
755  * API. The API will never write to your data (and copy it if needed), so
756  * you're free to use any form of allocation or memory management you like.
757  *
758  * Warning: when reading, always check the mpv_node.format member. For
759  * example, properties might change their type in future versions
760  * of mpv, or sometimes even during runtime.
761  *
762  * Example for reading:
763  *
764  * mpv_node result;
765  * if (mpv_get_property(ctx, "property", MPV_FORMAT_NODE, &result) < 0)
766  * goto error;
767  * printf("format=%d\n", (int)result.format);
768  * mpv_free_node_contents(&result).
769  *
770  * Example for writing:
771  *
772  * mpv_node value;
773  * value.format = MPV_FORMAT_STRING;
774  * value.u.string = "hello";
775  * mpv_set_property(ctx, "property", MPV_FORMAT_NODE, &value);
776  */
778  /**
779  * Used with mpv_node only. Can usually not be used directly.
780  */
782  /**
783  * See MPV_FORMAT_NODE_ARRAY.
784  */
786  /**
787  * A raw, untyped byte array. Only used only with mpv_node, and only in
788  * some very specific situations. (Some commands use it.)
789  */
791 } mpv_format;
792 
793 /**
794  * Generic data storage.
795  *
796  * If mpv writes this struct (e.g. via mpv_get_property()), you must not change
797  * the data. In some cases (mpv_get_property()), you have to free it with
798  * mpv_free_node_contents(). If you fill this struct yourself, you're also
799  * responsible for freeing it, and you must not call mpv_free_node_contents().
800  */
801 typedef struct mpv_node {
802  union {
803  char *string; /** valid if format==MPV_FORMAT_STRING */
804  int flag; /** valid if format==MPV_FORMAT_FLAG */
805  int64_t int64; /** valid if format==MPV_FORMAT_INT64 */
806  double double_; /** valid if format==MPV_FORMAT_DOUBLE */
807  /**
808  * valid if format==MPV_FORMAT_NODE_ARRAY
809  * or if format==MPV_FORMAT_NODE_MAP
810  */
812  /**
813  * valid if format==MPV_FORMAT_BYTE_ARRAY
814  */
816  } u;
817  /**
818  * Type of the data stored in this struct. This value rules what members in
819  * the given union can be accessed. The following formats are currently
820  * defined to be allowed in mpv_node:
821  *
822  * MPV_FORMAT_STRING (u.string)
823  * MPV_FORMAT_FLAG (u.flag)
824  * MPV_FORMAT_INT64 (u.int64)
825  * MPV_FORMAT_DOUBLE (u.double_)
826  * MPV_FORMAT_NODE_ARRAY (u.list)
827  * MPV_FORMAT_NODE_MAP (u.list)
828  * MPV_FORMAT_BYTE_ARRAY (u.ba)
829  * MPV_FORMAT_NONE (no member)
830  *
831  * If you encounter a value you don't know, you must not make any
832  * assumptions about the contents of union u.
833  */
835 } mpv_node;
836 
837 /**
838  * (see mpv_node)
839  */
840 typedef struct mpv_node_list {
841  /**
842  * Number of entries. Negative values are not allowed.
843  */
844  int num;
845  /**
846  * MPV_FORMAT_NODE_ARRAY:
847  * values[N] refers to value of the Nth item
848  *
849  * MPV_FORMAT_NODE_MAP:
850  * values[N] refers to value of the Nth key/value pair
851  *
852  * If num > 0, values[0] to values[num-1] (inclusive) are valid.
853  * Otherwise, this can be NULL.
854  */
856  /**
857  * MPV_FORMAT_NODE_ARRAY:
858  * unused (typically NULL), access is not allowed
859  *
860  * MPV_FORMAT_NODE_MAP:
861  * keys[N] refers to key of the Nth key/value pair. If num > 0, keys[0] to
862  * keys[num-1] (inclusive) are valid. Otherwise, this can be NULL.
863  * The keys are in random order. The only guarantee is that keys[N] belongs
864  * to the value values[N]. NULL keys are not allowed.
865  */
866  char **keys;
867 } mpv_node_list;
868 
869 /**
870  * (see mpv_node)
871  */
872 typedef struct mpv_byte_array {
873  /**
874  * Pointer to the data. In what format the data is stored is up to whatever
875  * uses MPV_FORMAT_BYTE_ARRAY.
876  */
877  void *data;
878  /**
879  * Size of the data pointed to by ptr.
880  */
881  size_t size;
883 
884 /**
885  * Frees any data referenced by the node. It doesn't free the node itself.
886  * Call this only if the mpv client API set the node. If you constructed the
887  * node yourself (manually), you have to free it yourself.
888  *
889  * If node->format is MPV_FORMAT_NONE, this call does nothing. Likewise, if
890  * the client API sets a node with this format, this function doesn't need to
891  * be called. (This is just a clarification that there's no danger of anything
892  * strange happening in these cases.)
893  */
894 void mpv_free_node_contents(mpv_node *node);
895 
896 /**
897  * Set an option. Note that you can't normally set options during runtime. It
898  * works in uninitialized state (see mpv_create()), and in some cases in at
899  * runtime.
900  *
901  * Using a format other than MPV_FORMAT_NODE is equivalent to constructing a
902  * mpv_node with the given format and data, and passing the mpv_node to this
903  * function.
904  *
905  * Note: this is semi-deprecated. For most purposes, this is not needed anymore.
906  * Starting with mpv version 0.21.0 (version 1.23) most options can be set
907  * with mpv_set_property() (and related functions), and even before
908  * mpv_initialize(). In some obscure corner cases, using this function
909  * to set options might still be required (see below, and also section
910  * "Inconsistencies between options and properties" on the manpage). Once
911  * these are resolved, the option setting functions might be fully
912  * deprecated.
913  *
914  * The following options still need to be set either _before_
915  * mpv_initialize() with mpv_set_property() (or related functions), or
916  * with mpv_set_option() (or related functions) at any time:
917  * - options shadowed by deprecated properties:
918  * - demuxer (property deprecated in 0.21.0)
919  * - idle (property deprecated in 0.21.0)
920  * - fps (property deprecated in 0.21.0)
921  * - cache (property deprecated in 0.21.0)
922  * - length (property deprecated in 0.10.0)
923  * - audio-samplerate (property deprecated in 0.10.0)
924  * - audio-channels (property deprecated in 0.10.0)
925  * - audio-format (property deprecated in 0.10.0)
926  * - deprecated options shadowed by properties:
927  * - chapter (option deprecated in 0.21.0)
928  * - playlist-pos (option deprecated in 0.21.0)
929  * The deprecated properties were removed in mpv 0.23.0.
930  *
931  * @param name Option name. This is the same as on the mpv command line, but
932  * without the leading "--".
933  * @param format see enum mpv_format.
934  * @param[in] data Option value (according to the format).
935  * @return error code
936  */
937 int mpv_set_option(mpv_handle *ctx, const char *name, mpv_format format,
938  void *data);
939 
940 /**
941  * Convenience function to set an option to a string value. This is like
942  * calling mpv_set_option() with MPV_FORMAT_STRING.
943  *
944  * @return error code
945  */
946 int mpv_set_option_string(mpv_handle *ctx, const char *name, const char *data);
947 
948 /**
949  * Send a command to the player. Commands are the same as those used in
950  * input.conf, except that this function takes parameters in a pre-split
951  * form.
952  *
953  * The commands and their parameters are documented in input.rst.
954  *
955  * Does not use OSD and string expansion by default (unlike mpv_command_string()
956  * and input.conf).
957  *
958  * @param[in] args NULL-terminated list of strings. Usually, the first item
959  * is the command, and the following items are arguments.
960  * @return error code
961  */
962 int mpv_command(mpv_handle *ctx, const char **args);
963 
964 /**
965  * Same as mpv_command(), but allows passing structured data in any format.
966  * In particular, calling mpv_command() is exactly like calling
967  * mpv_command_node() with the format set to MPV_FORMAT_NODE_ARRAY, and
968  * every arg passed in order as MPV_FORMAT_STRING.
969  *
970  * Does not use OSD and string expansion by default.
971  *
972  * The args argument can have one of the following formats:
973  *
974  * MPV_FORMAT_NODE_ARRAY:
975  * Positional arguments. Each entry is an argument using an arbitrary
976  * format (the format must be compatible to the used command). Usually,
977  * the first item is the command name (as MPV_FORMAT_STRING). The order
978  * of arguments is as documented in each command description.
979  *
980  * MPV_FORMAT_NODE_MAP:
981  * Named arguments. This requires at least an entry with the key "name"
982  * to be present, which must be a string, and contains the command name.
983  * The special entry "_flags" is optional, and if present, must be an
984  * array of strings, each being a command prefix to apply. All other
985  * entries are interpreted as arguments. They must use the argument names
986  * as documented in each command description. Some commands do not
987  * support named arguments at all, and must use MPV_FORMAT_NODE_ARRAY.
988  *
989  * @param[in] args mpv_node with format set to one of the values documented
990  * above (see there for details)
991  * @param[out] result Optional, pass NULL if unused. If not NULL, and if the
992  * function succeeds, this is set to command-specific return
993  * data. You must call mpv_free_node_contents() to free it
994  * (again, only if the command actually succeeds).
995  * Not many commands actually use this at all.
996  * @return error code (the result parameter is not set on error)
997  */
998 int mpv_command_node(mpv_handle *ctx, mpv_node *args, mpv_node *result);
999 
1000 /**
1001  * This is essentially identical to mpv_command() but it also returns a result.
1002  *
1003  * Does not use OSD and string expansion by default.
1004  *
1005  * @param[in] args NULL-terminated list of strings. Usually, the first item
1006  * is the command, and the following items are arguments.
1007  * @param[out] result Optional, pass NULL if unused. If not NULL, and if the
1008  * function succeeds, this is set to command-specific return
1009  * data. You must call mpv_free_node_contents() to free it
1010  * (again, only if the command actually succeeds).
1011  * Not many commands actually use this at all.
1012  * @return error code (the result parameter is not set on error)
1013  */
1014 int mpv_command_ret(mpv_handle *ctx, const char **args, mpv_node *result);
1015 
1016 /**
1017  * Same as mpv_command, but use input.conf parsing for splitting arguments.
1018  * This is slightly simpler, but also more error prone, since arguments may
1019  * need quoting/escaping.
1020  *
1021  * This also has OSD and string expansion enabled by default.
1022  */
1023 int mpv_command_string(mpv_handle *ctx, const char *args);
1024 
1025 /**
1026  * Same as mpv_command, but run the command asynchronously.
1027  *
1028  * Commands are executed asynchronously. You will receive a
1029  * MPV_EVENT_COMMAND_REPLY event. This event will also have an
1030  * error code set if running the command failed. For commands that
1031  * return data, the data is put into mpv_event_command.result.
1032  *
1033  * The only case when you do not receive an event is when the function call
1034  * itself fails. This happens only if parsing the command itself (or otherwise
1035  * validating it) fails, i.e. the return code of the API call is not 0 or
1036  * positive.
1037  *
1038  * Safe to be called from mpv render API threads.
1039  *
1040  * @param reply_userdata the value mpv_event.reply_userdata of the reply will
1041  * be set to (see section about asynchronous calls)
1042  * @param args NULL-terminated list of strings (see mpv_command())
1043  * @return error code (if parsing or queuing the command fails)
1044  */
1045 int mpv_command_async(mpv_handle *ctx, uint64_t reply_userdata,
1046  const char **args);
1047 
1048 /**
1049  * Same as mpv_command_node(), but run it asynchronously. Basically, this
1050  * function is to mpv_command_node() what mpv_command_async() is to
1051  * mpv_command().
1052  *
1053  * See mpv_command_async() for details.
1054  *
1055  * Safe to be called from mpv render API threads.
1056  *
1057  * @param reply_userdata the value mpv_event.reply_userdata of the reply will
1058  * be set to (see section about asynchronous calls)
1059  * @param args as in mpv_command_node()
1060  * @return error code (if parsing or queuing the command fails)
1061  */
1062 int mpv_command_node_async(mpv_handle *ctx, uint64_t reply_userdata,
1063  mpv_node *args);
1064 
1065 /**
1066  * Signal to all async requests with the matching ID to abort. This affects
1067  * the following API calls:
1068  *
1069  * mpv_command_async
1070  * mpv_command_node_async
1071  *
1072  * All of these functions take a reply_userdata parameter. This API function
1073  * tells all requests with the matching reply_userdata value to try to return
1074  * as soon as possible. If there are multiple requests with matching ID, it
1075  * aborts all of them.
1076  *
1077  * This API function is mostly asynchronous itself. It will not wait until the
1078  * command is aborted. Instead, the command will terminate as usual, but with
1079  * some work not done. How this is signaled depends on the specific command (for
1080  * example, the "subprocess" command will indicate it by "killed_by_us" set to
1081  * true in the result). How long it takes also depends on the situation. The
1082  * aborting process is completely asynchronous.
1083  *
1084  * Not all commands may support this functionality. In this case, this function
1085  * will have no effect. The same is true if the request using the passed
1086  * reply_userdata has already terminated, has not been started yet, or was
1087  * never in use at all.
1088  *
1089  * You have to be careful of race conditions: the time during which the abort
1090  * request will be effective is _after_ e.g. mpv_command_async() has returned,
1091  * and before the command has signaled completion with MPV_EVENT_COMMAND_REPLY.
1092  *
1093  * @param reply_userdata ID of the request to be aborted (see above)
1094  */
1095 void mpv_abort_async_command(mpv_handle *ctx, uint64_t reply_userdata);
1096 
1097 /**
1098  * Set a property to a given value. Properties are essentially variables which
1099  * can be queried or set at runtime. For example, writing to the pause property
1100  * will actually pause or unpause playback.
1101  *
1102  * If the format doesn't match with the internal format of the property, access
1103  * usually will fail with MPV_ERROR_PROPERTY_FORMAT. In some cases, the data
1104  * is automatically converted and access succeeds. For example, MPV_FORMAT_INT64
1105  * is always converted to MPV_FORMAT_DOUBLE, and access using MPV_FORMAT_STRING
1106  * usually invokes a string parser. The same happens when calling this function
1107  * with MPV_FORMAT_NODE: the underlying format may be converted to another
1108  * type if possible.
1109  *
1110  * Using a format other than MPV_FORMAT_NODE is equivalent to constructing a
1111  * mpv_node with the given format and data, and passing the mpv_node to this
1112  * function. (Before API version 1.21, this was different.)
1113  *
1114  * Note: starting with mpv 0.21.0 (client API version 1.23), this can be used to
1115  * set options in general. It even can be used before mpv_initialize()
1116  * has been called. If called before mpv_initialize(), setting properties
1117  * not backed by options will result in MPV_ERROR_PROPERTY_UNAVAILABLE.
1118  * In some cases, properties and options still conflict. In these cases,
1119  * mpv_set_property() accesses the options before mpv_initialize(), and
1120  * the properties after mpv_initialize(). These conflicts will be removed
1121  * in mpv 0.23.0. See mpv_set_option() for further remarks.
1122  *
1123  * @param name The property name. See input.rst for a list of properties.
1124  * @param format see enum mpv_format.
1125  * @param[in] data Option value.
1126  * @return error code
1127  */
1128 int mpv_set_property(mpv_handle *ctx, const char *name, mpv_format format,
1129  void *data);
1130 
1131 /**
1132  * Convenience function to set a property to a string value.
1133  *
1134  * This is like calling mpv_set_property() with MPV_FORMAT_STRING.
1135  */
1136 int mpv_set_property_string(mpv_handle *ctx, const char *name, const char *data);
1137 
1138 /**
1139  * Set a property asynchronously. You will receive the result of the operation
1140  * as MPV_EVENT_SET_PROPERTY_REPLY event. The mpv_event.error field will contain
1141  * the result status of the operation. Otherwise, this function is similar to
1142  * mpv_set_property().
1143  *
1144  * Safe to be called from mpv render API threads.
1145  *
1146  * @param reply_userdata see section about asynchronous calls
1147  * @param name The property name.
1148  * @param format see enum mpv_format.
1149  * @param[in] data Option value. The value will be copied by the function. It
1150  * will never be modified by the client API.
1151  * @return error code if sending the request failed
1152  */
1153 int mpv_set_property_async(mpv_handle *ctx, uint64_t reply_userdata,
1154  const char *name, mpv_format format, void *data);
1155 
1156 /**
1157  * Read the value of the given property.
1158  *
1159  * If the format doesn't match with the internal format of the property, access
1160  * usually will fail with MPV_ERROR_PROPERTY_FORMAT. In some cases, the data
1161  * is automatically converted and access succeeds. For example, MPV_FORMAT_INT64
1162  * is always converted to MPV_FORMAT_DOUBLE, and access using MPV_FORMAT_STRING
1163  * usually invokes a string formatter.
1164  *
1165  * @param name The property name.
1166  * @param format see enum mpv_format.
1167  * @param[out] data Pointer to the variable holding the option value. On
1168  * success, the variable will be set to a copy of the option
1169  * value. For formats that require dynamic memory allocation,
1170  * you can free the value with mpv_free() (strings) or
1171  * mpv_free_node_contents() (MPV_FORMAT_NODE).
1172  * @return error code
1173  */
1174 int mpv_get_property(mpv_handle *ctx, const char *name, mpv_format format,
1175  void *data);
1176 
1177 /**
1178  * Return the value of the property with the given name as string. This is
1179  * equivalent to mpv_get_property() with MPV_FORMAT_STRING.
1180  *
1181  * See MPV_FORMAT_STRING for character encoding issues.
1182  *
1183  * On error, NULL is returned. Use mpv_get_property() if you want fine-grained
1184  * error reporting.
1185  *
1186  * @param name The property name.
1187  * @return Property value, or NULL if the property can't be retrieved. Free
1188  * the string with mpv_free().
1189  */
1190 char *mpv_get_property_string(mpv_handle *ctx, const char *name);
1191 
1192 /**
1193  * Return the property as "OSD" formatted string. This is the same as
1194  * mpv_get_property_string, but using MPV_FORMAT_OSD_STRING.
1195  *
1196  * @return Property value, or NULL if the property can't be retrieved. Free
1197  * the string with mpv_free().
1198  */
1199 char *mpv_get_property_osd_string(mpv_handle *ctx, const char *name);
1200 
1201 /**
1202  * Get a property asynchronously. You will receive the result of the operation
1203  * as well as the property data with the MPV_EVENT_GET_PROPERTY_REPLY event.
1204  * You should check the mpv_event.error field on the reply event.
1205  *
1206  * Safe to be called from mpv render API threads.
1207  *
1208  * @param reply_userdata see section about asynchronous calls
1209  * @param name The property name.
1210  * @param format see enum mpv_format.
1211  * @return error code if sending the request failed
1212  */
1213 int mpv_get_property_async(mpv_handle *ctx, uint64_t reply_userdata,
1214  const char *name, mpv_format format);
1215 
1216 /**
1217  * Get a notification whenever the given property changes. You will receive
1218  * updates as MPV_EVENT_PROPERTY_CHANGE. Note that this is not very precise:
1219  * for some properties, it may not send updates even if the property changed.
1220  * This depends on the property, and it's a valid feature request to ask for
1221  * better update handling of a specific property. (For some properties, like
1222  * ``clock``, which shows the wall clock, this mechanism doesn't make too
1223  * much sense anyway.)
1224  *
1225  * Property changes are coalesced: the change events are returned only once the
1226  * event queue becomes empty (e.g. mpv_wait_event() would block or return
1227  * MPV_EVENT_NONE), and then only one event per changed property is returned.
1228  *
1229  * You always get an initial change notification. This is meant to initialize
1230  * the user's state to the current value of the property.
1231  *
1232  * Normally, change events are sent only if the property value changes according
1233  * to the requested format. mpv_event_property will contain the property value
1234  * as data member.
1235  *
1236  * Warning: if a property is unavailable or retrieving it caused an error,
1237  * MPV_FORMAT_NONE will be set in mpv_event_property, even if the
1238  * format parameter was set to a different value. In this case, the
1239  * mpv_event_property.data field is invalid.
1240  *
1241  * If the property is observed with the format parameter set to MPV_FORMAT_NONE,
1242  * you get low-level notifications whether the property _may_ have changed, and
1243  * the data member in mpv_event_property will be unset. With this mode, you
1244  * will have to determine yourself whether the property really changed. On the
1245  * other hand, this mechanism can be faster and uses less resources.
1246  *
1247  * Observing a property that doesn't exist is allowed. (Although it may still
1248  * cause some sporadic change events.)
1249  *
1250  * Keep in mind that you will get change notifications even if you change a
1251  * property yourself. Try to avoid endless feedback loops, which could happen
1252  * if you react to the change notifications triggered by your own change.
1253  *
1254  * Only the mpv_handle on which this was called will receive the property
1255  * change events, or can unobserve them.
1256  *
1257  * Safe to be called from mpv render API threads.
1258  *
1259  * @param reply_userdata This will be used for the mpv_event.reply_userdata
1260  * field for the received MPV_EVENT_PROPERTY_CHANGE
1261  * events. (Also see section about asynchronous calls,
1262  * although this function is somewhat different from
1263  * actual asynchronous calls.)
1264  * If you have no use for this, pass 0.
1265  * Also see mpv_unobserve_property().
1266  * @param name The property name.
1267  * @param format see enum mpv_format. Can be MPV_FORMAT_NONE to omit values
1268  * from the change events.
1269  * @return error code (usually fails only on OOM or unsupported format)
1270  */
1271 int mpv_observe_property(mpv_handle *mpv, uint64_t reply_userdata,
1272  const char *name, mpv_format format);
1273 
1274 /**
1275  * Undo mpv_observe_property(). This will remove all observed properties for
1276  * which the given number was passed as reply_userdata to mpv_observe_property.
1277  *
1278  * Safe to be called from mpv render API threads.
1279  *
1280  * @param registered_reply_userdata ID that was passed to mpv_observe_property
1281  * @return negative value is an error code, >=0 is number of removed properties
1282  * on success (includes the case when 0 were removed)
1283  */
1284 int mpv_unobserve_property(mpv_handle *mpv, uint64_t registered_reply_userdata);
1285 
1286 typedef enum mpv_event_id {
1287  /**
1288  * Nothing happened. Happens on timeouts or sporadic wakeups.
1289  */
1291  /**
1292  * Happens when the player quits. The player enters a state where it tries
1293  * to disconnect all clients. Most requests to the player will fail, and
1294  * the client should react to this and quit with mpv_destroy() as soon as
1295  * possible.
1296  */
1298  /**
1299  * See mpv_request_log_messages().
1300  */
1302  /**
1303  * Reply to a mpv_get_property_async() request.
1304  * See also mpv_event and mpv_event_property.
1305  */
1307  /**
1308  * Reply to a mpv_set_property_async() request.
1309  * (Unlike MPV_EVENT_GET_PROPERTY, mpv_event_property is not used.)
1310  */
1312  /**
1313  * Reply to a mpv_command_async() or mpv_command_node_async() request.
1314  * See also mpv_event and mpv_event_command.
1315  */
1317  /**
1318  * Notification before playback start of a file (before the file is loaded).
1319  * See also mpv_event and mpv_event_start_file.
1320  */
1322  /**
1323  * Notification after playback end (after the file was unloaded).
1324  * See also mpv_event and mpv_event_end_file.
1325  */
1327  /**
1328  * Notification when the file has been loaded (headers were read etc.), and
1329  * decoding starts.
1330  */
1332 #if MPV_ENABLE_DEPRECATED
1333  /**
1334  * The list of video/audio/subtitle tracks was changed. (E.g. a new track
1335  * was found. This doesn't necessarily indicate a track switch; for this,
1336  * MPV_EVENT_TRACK_SWITCHED is used.)
1337  *
1338  * @deprecated This is equivalent to using mpv_observe_property() on the
1339  * "track-list" property. The event is redundant, and might
1340  * be removed in the far future.
1341  */
1343  /**
1344  * A video/audio/subtitle track was switched on or off.
1345  *
1346  * @deprecated This is equivalent to using mpv_observe_property() on the
1347  * "vid", "aid", and "sid" properties. The event is redundant,
1348  * and might be removed in the far future.
1349  */
1351  /**
1352  * Idle mode was entered. In this mode, no file is played, and the playback
1353  * core waits for new commands. (The command line player normally quits
1354  * instead of entering idle mode, unless --idle was specified. If mpv
1355  * was started with mpv_create(), idle mode is enabled by default.)
1356  *
1357  * @deprecated This is equivalent to using mpv_observe_property() on the
1358  * "idle-active" property. The event is redundant, and might be
1359  * removed in the far future. As a further warning, this event
1360  * is not necessarily sent at the right point anymore (at the
1361  * start of the program), while the property behaves correctly.
1362  */
1364  /**
1365  * Playback was paused. This indicates the user pause state.
1366  *
1367  * The user pause state is the state the user requested (changed with the
1368  * "pause" property). There is an internal pause state too, which is entered
1369  * if e.g. the network is too slow (the "core-idle" property generally
1370  * indicates whether the core is playing or waiting).
1371  *
1372  * This event is sent whenever any pause states change, not only the user
1373  * state. You might get multiple events in a row while these states change
1374  * independently. But the event ID sent always indicates the user pause
1375  * state.
1376  *
1377  * If you don't want to deal with this, use mpv_observe_property() on the
1378  * "pause" property and ignore MPV_EVENT_PAUSE/UNPAUSE. Likewise, the
1379  * "core-idle" property tells you whether video is actually playing or not.
1380  *
1381  * @deprecated The event is redundant with mpv_observe_property() as
1382  * mentioned above, and might be removed in the far future.
1383  */
1385  /**
1386  * Playback was unpaused. See MPV_EVENT_PAUSE for not so obvious details.
1387  *
1388  * @deprecated The event is redundant with mpv_observe_property() as
1389  * explained in the MPV_EVENT_PAUSE comments, and might be
1390  * removed in the far future.
1391  */
1393  /**
1394  * Sent every time after a video frame is displayed. Note that currently,
1395  * this will be sent in lower frequency if there is no video, or playback
1396  * is paused - but that will be removed in the future, and it will be
1397  * restricted to video frames only.
1398  *
1399  * @deprecated Use mpv_observe_property() with relevant properties instead
1400  * (such as "playback-time").
1401  */
1403  /**
1404  * @deprecated This was used internally with the internal "script_dispatch"
1405  * command to dispatch keyboard and mouse input for the OSC.
1406  * It was never useful in general and has been completely
1407  * replaced with "script-binding".
1408  * This event never happens anymore, and is included in this
1409  * header only for compatibility.
1410  */
1412 #endif
1413  /**
1414  * Triggered by the script-message input command. The command uses the
1415  * first argument of the command as client name (see mpv_client_name()) to
1416  * dispatch the message, and passes along all arguments starting from the
1417  * second argument as strings.
1418  * See also mpv_event and mpv_event_client_message.
1419  */
1421  /**
1422  * Happens after video changed in some way. This can happen on resolution
1423  * changes, pixel format changes, or video filter changes. The event is
1424  * sent after the video filters and the VO are reconfigured. Applications
1425  * embedding a mpv window should listen to this event in order to resize
1426  * the window if needed.
1427  * Note that this event can happen sporadically, and you should check
1428  * yourself whether the video parameters really changed before doing
1429  * something expensive.
1430  */
1432  /**
1433  * Similar to MPV_EVENT_VIDEO_RECONFIG. This is relatively uninteresting,
1434  * because there is no such thing as audio output embedding.
1435  */
1437 #if MPV_ENABLE_DEPRECATED
1438  /**
1439  * Happens when metadata (like file tags) is possibly updated. (It's left
1440  * unspecified whether this happens on file start or only when it changes
1441  * within a file.)
1442  *
1443  * @deprecated This is equivalent to using mpv_observe_property() on the
1444  * "metadata" property. The event is redundant, and might
1445  * be removed in the far future.
1446  */
1448 #endif
1449  /**
1450  * Happens when a seek was initiated. Playback stops. Usually it will
1451  * resume with MPV_EVENT_PLAYBACK_RESTART as soon as the seek is finished.
1452  */
1454  /**
1455  * There was a discontinuity of some sort (like a seek), and playback
1456  * was reinitialized. Usually happens on start of playback and after
1457  * seeking. The main purpose is allowing the client to detect when a seek
1458  * request is finished.
1459  */
1461  /**
1462  * Event sent due to mpv_observe_property().
1463  * See also mpv_event and mpv_event_property.
1464  */
1466 #if MPV_ENABLE_DEPRECATED
1467  /**
1468  * Happens when the current chapter changes.
1469  *
1470  * @deprecated This is equivalent to using mpv_observe_property() on the
1471  * "chapter" property. The event is redundant, and might
1472  * be removed in the far future.
1473  */
1475 #endif
1476  /**
1477  * Happens if the internal per-mpv_handle ringbuffer overflows, and at
1478  * least 1 event had to be dropped. This can happen if the client doesn't
1479  * read the event queue quickly enough with mpv_wait_event(), or if the
1480  * client makes a very large number of asynchronous calls at once.
1481  *
1482  * Event delivery will continue normally once this event was returned
1483  * (this forces the client to empty the queue completely).
1484  */
1486  /**
1487  * Triggered if a hook handler was registered with mpv_hook_add(), and the
1488  * hook is invoked. If you receive this, you must handle it, and continue
1489  * the hook with mpv_hook_continue().
1490  * See also mpv_event and mpv_event_hook.
1491  */
1493  // Internal note: adjust INTERNAL_EVENT_BASE when adding new events.
1494 } mpv_event_id;
1495 
1496 /**
1497  * Return a string describing the event. For unknown events, NULL is returned.
1498  *
1499  * Note that all events actually returned by the API will also yield a non-NULL
1500  * string with this function.
1501  *
1502  * @param event event ID, see see enum mpv_event_id
1503  * @return A static string giving a short symbolic name of the event. It
1504  * consists of lower-case alphanumeric characters and can include "-"
1505  * characters. This string is suitable for use in e.g. scripting
1506  * interfaces.
1507  * The string is completely static, i.e. doesn't need to be deallocated,
1508  * and is valid forever.
1509  */
1510 const char *mpv_event_name(mpv_event_id event);
1511 
1512 typedef struct mpv_event_property {
1513  /**
1514  * Name of the property.
1515  */
1516  const char *name;
1517  /**
1518  * Format of the data field in the same struct. See enum mpv_format.
1519  * This is always the same format as the requested format, except when
1520  * the property could not be retrieved (unavailable, or an error happened),
1521  * in which case the format is MPV_FORMAT_NONE.
1522  */
1524  /**
1525  * Received property value. Depends on the format. This is like the
1526  * pointer argument passed to mpv_get_property().
1527  *
1528  * For example, for MPV_FORMAT_STRING you get the string with:
1529  *
1530  * char *value = *(char **)(event_property->data);
1531  *
1532  * Note that this is set to NULL if retrieving the property failed (the
1533  * format will be MPV_FORMAT_NONE).
1534  */
1535  void *data;
1537 
1538 /**
1539  * Numeric log levels. The lower the number, the more important the message is.
1540  * MPV_LOG_LEVEL_NONE is never used when receiving messages. The string in
1541  * the comment after the value is the name of the log level as used for the
1542  * mpv_request_log_messages() function.
1543  * Unused numeric values are unused, but reserved for future use.
1544  */
1545 typedef enum mpv_log_level {
1546  MPV_LOG_LEVEL_NONE = 0, /// "no" - disable absolutely all messages
1547  MPV_LOG_LEVEL_FATAL = 10, /// "fatal" - critical/aborting errors
1548  MPV_LOG_LEVEL_ERROR = 20, /// "error" - simple errors
1549  MPV_LOG_LEVEL_WARN = 30, /// "warn" - possible problems
1550  MPV_LOG_LEVEL_INFO = 40, /// "info" - informational message
1551  MPV_LOG_LEVEL_V = 50, /// "v" - noisy informational message
1552  MPV_LOG_LEVEL_DEBUG = 60, /// "debug" - very noisy technical information
1553  MPV_LOG_LEVEL_TRACE = 70, /// "trace" - extremely noisy
1554 } mpv_log_level;
1555 
1556 typedef struct mpv_event_log_message {
1557  /**
1558  * The module prefix, identifies the sender of the message. As a special
1559  * case, if the message buffer overflows, this will be set to the string
1560  * "overflow" (which doesn't appear as prefix otherwise), and the text
1561  * field will contain an informative message.
1562  */
1563  const char *prefix;
1564  /**
1565  * The log level as string. See mpv_request_log_messages() for possible
1566  * values. The level "no" is never used here.
1567  */
1568  const char *level;
1569  /**
1570  * The log message. It consists of 1 line of text, and is terminated with
1571  * a newline character. (Before API version 1.6, it could contain multiple
1572  * or partial lines.)
1573  */
1574  const char *text;
1575  /**
1576  * The same contents as the level field, but as a numeric ID.
1577  * Since API version 1.6.
1578  */
1581 
1582 /// Since API version 1.9.
1583 typedef enum mpv_end_file_reason {
1584  /**
1585  * The end of file was reached. Sometimes this may also happen on
1586  * incomplete or corrupted files, or if the network connection was
1587  * interrupted when playing a remote file. It also happens if the
1588  * playback range was restricted with --end or --frames or similar.
1589  */
1591  /**
1592  * Playback was stopped by an external action (e.g. playlist controls).
1593  */
1595  /**
1596  * Playback was stopped by the quit command or player shutdown.
1597  */
1599  /**
1600  * Some kind of error happened that lead to playback abort. Does not
1601  * necessarily happen on incomplete or broken files (in these cases, both
1602  * MPV_END_FILE_REASON_ERROR or MPV_END_FILE_REASON_EOF are possible).
1603  *
1604  * mpv_event_end_file.error will be set.
1605  */
1607  /**
1608  * The file was a playlist or similar. When the playlist is read, its
1609  * entries will be appended to the playlist after the entry of the current
1610  * file, the entry of the current file is removed, and a MPV_EVENT_END_FILE
1611  * event is sent with reason set to MPV_END_FILE_REASON_REDIRECT. Then
1612  * playback continues with the playlist contents.
1613  * Since API version 1.18.
1614  */
1617 
1618 /// Since API version 1.108.
1619 typedef struct mpv_event_start_file {
1620  /**
1621  * Playlist entry ID of the file being loaded now.
1622  */
1625 
1626 typedef struct mpv_event_end_file {
1627  /**
1628  * Corresponds to the values in enum mpv_end_file_reason (the "int" type
1629  * will be replaced with mpv_end_file_reason on the next ABI bump).
1630  *
1631  * Unknown values should be treated as unknown.
1632  */
1633  int reason;
1634  /**
1635  * If reason==MPV_END_FILE_REASON_ERROR, this contains a mpv error code
1636  * (one of MPV_ERROR_...) giving an approximate reason why playback
1637  * failed. In other cases, this field is 0 (no error).
1638  * Since API version 1.9.
1639  */
1640  int error;
1641  /**
1642  * Playlist entry ID of the file that was being played or attempted to be
1643  * played. This has the same value as the playlist_entry_id field in the
1644  * corresponding mpv_event_start_file event.
1645  * Since API version 1.108.
1646  */
1648  /**
1649  * If loading ended, because the playlist entry to be played was for example
1650  * a playlist, and the current playlist entry is replaced with a number of
1651  * other entries. This may happen at least with MPV_END_FILE_REASON_REDIRECT
1652  * (other event types may use this for similar but different purposes in the
1653  * future). In this case, playlist_insert_id will be set to the playlist
1654  * entry ID of the first inserted entry, and playlist_insert_num_entries to
1655  * the total number of inserted playlist entries. Note this in this specific
1656  * case, the ID of the last inserted entry is playlist_insert_id+num-1.
1657  * Beware that depending on circumstances, you may observe the new playlist
1658  * entries before seeing the event (e.g. reading the "playlist" property or
1659  * getting a property change notification before receiving the event).
1660  * Since API version 1.108.
1661  */
1663  /**
1664  * See playlist_insert_id. Only non-0 if playlist_insert_id is valid. Never
1665  * negative.
1666  * Since API version 1.108.
1667  */
1670 
1671 #if MPV_ENABLE_DEPRECATED
1672 /** @deprecated see MPV_EVENT_SCRIPT_INPUT_DISPATCH for remarks
1673  */
1675  int arg0;
1676  const char *type;
1678 #endif
1679 
1681  /**
1682  * Arbitrary arguments chosen by the sender of the message. If num_args > 0,
1683  * you can access args[0] through args[num_args - 1] (inclusive). What
1684  * these arguments mean is up to the sender and receiver.
1685  * None of the valid items are NULL.
1686  */
1688  const char **args;
1690 
1691 typedef struct mpv_event_hook {
1692  /**
1693  * The hook name as passed to mpv_hook_add().
1694  */
1695  const char *name;
1696  /**
1697  * Internal ID that must be passed to mpv_hook_continue().
1698  */
1699  uint64_t id;
1700 } mpv_event_hook;
1701 
1702 // Since API version 1.102.
1703 typedef struct mpv_event_command {
1704  /**
1705  * Result data of the command. Note that success/failure is signaled
1706  * separately via mpv_event.error. This field is only for result data
1707  * in case of success. Most commands leave it at MPV_FORMAT_NONE. Set
1708  * to MPV_FORMAT_NONE on failure.
1709  */
1712 
1713 typedef struct mpv_event {
1714  /**
1715  * One of mpv_event. Keep in mind that later ABI compatible releases might
1716  * add new event types. These should be ignored by the API user.
1717  */
1719  /**
1720  * This is mainly used for events that are replies to (asynchronous)
1721  * requests. It contains a status code, which is >= 0 on success, or < 0
1722  * on error (a mpv_error value). Usually, this will be set if an
1723  * asynchronous request fails.
1724  * Used for:
1725  * MPV_EVENT_GET_PROPERTY_REPLY
1726  * MPV_EVENT_SET_PROPERTY_REPLY
1727  * MPV_EVENT_COMMAND_REPLY
1728  */
1729  int error;
1730  /**
1731  * If the event is in reply to a request (made with this API and this
1732  * API handle), this is set to the reply_userdata parameter of the request
1733  * call. Otherwise, this field is 0.
1734  * Used for:
1735  * MPV_EVENT_GET_PROPERTY_REPLY
1736  * MPV_EVENT_SET_PROPERTY_REPLY
1737  * MPV_EVENT_COMMAND_REPLY
1738  * MPV_EVENT_PROPERTY_CHANGE
1739  * MPV_EVENT_HOOK
1740  */
1741  uint64_t reply_userdata;
1742  /**
1743  * The meaning and contents of the data member depend on the event_id:
1744  * MPV_EVENT_GET_PROPERTY_REPLY: mpv_event_property*
1745  * MPV_EVENT_PROPERTY_CHANGE: mpv_event_property*
1746  * MPV_EVENT_LOG_MESSAGE: mpv_event_log_message*
1747  * MPV_EVENT_CLIENT_MESSAGE: mpv_event_client_message*
1748  * MPV_EVENT_START_FILE: mpv_event_start_file* (since v1.108)
1749  * MPV_EVENT_END_FILE: mpv_event_end_file*
1750  * MPV_EVENT_HOOK: mpv_event_hook*
1751  * MPV_EVENT_COMMAND_REPLY* mpv_event_command*
1752  * other: NULL
1753  *
1754  * Note: future enhancements might add new event structs for existing or new
1755  * event types.
1756  */
1757  void *data;
1758 } mpv_event;
1759 
1760 /**
1761  * Convert the given src event to a mpv_node, and set *dst to the result. *dst
1762  * is set to a MPV_FORMAT_NODE_MAP, with fields for corresponding mpv_event and
1763  * mpv_event.data/mpv_event_* fields.
1764  *
1765  * The exact details are not completely documented out of laziness. A start
1766  * is located in the "Events" section of the manpage.
1767  *
1768  * *dst may point to newly allocated memory, or pointers in mpv_event. You must
1769  * copy the entire mpv_node if you want to reference it after mpv_event becomes
1770  * invalid (such as making a new mpv_wait_event() call, or destroying the
1771  * mpv_handle from which it was returned). Call mpv_free_node_contents() to free
1772  * any memory allocations made by this API function.
1773  *
1774  * Safe to be called from mpv render API threads.
1775  *
1776  * @param dst Target. This is not read and fully overwritten. Must be released
1777  * with mpv_free_node_contents(). Do not write to pointers returned
1778  * by it. (On error, this may be left as an empty node.)
1779  * @param src The source event. Not modified (it's not const due to the author's
1780  * prejudice of the C version of const).
1781  * @return error code (MPV_ERROR_NOMEM only, if at all)
1782  */
1783 int mpv_event_to_node(mpv_node *dst, mpv_event *src);
1784 
1785 /**
1786  * Enable or disable the given event.
1787  *
1788  * Some events are enabled by default. Some events can't be disabled.
1789  *
1790  * (Informational note: currently, all events are enabled by default, except
1791  * MPV_EVENT_TICK.)
1792  *
1793  * Safe to be called from mpv render API threads.
1794  *
1795  * @param event See enum mpv_event_id.
1796  * @param enable 1 to enable receiving this event, 0 to disable it.
1797  * @return error code
1798  */
1799 int mpv_request_event(mpv_handle *ctx, mpv_event_id event, int enable);
1800 
1801 /**
1802  * Enable or disable receiving of log messages. These are the messages the
1803  * command line player prints to the terminal. This call sets the minimum
1804  * required log level for a message to be received with MPV_EVENT_LOG_MESSAGE.
1805  *
1806  * @param min_level Minimal log level as string. Valid log levels:
1807  * no fatal error warn info v debug trace
1808  * The value "no" disables all messages. This is the default.
1809  * An exception is the value "terminal-default", which uses the
1810  * log level as set by the "--msg-level" option. This works
1811  * even if the terminal is disabled. (Since API version 1.19.)
1812  * Also see mpv_log_level.
1813  * @return error code
1814  */
1815 int mpv_request_log_messages(mpv_handle *ctx, const char *min_level);
1816 
1817 /**
1818  * Wait for the next event, or until the timeout expires, or if another thread
1819  * makes a call to mpv_wakeup(). Passing 0 as timeout will never wait, and
1820  * is suitable for polling.
1821  *
1822  * The internal event queue has a limited size (per client handle). If you
1823  * don't empty the event queue quickly enough with mpv_wait_event(), it will
1824  * overflow and silently discard further events. If this happens, making
1825  * asynchronous requests will fail as well (with MPV_ERROR_EVENT_QUEUE_FULL).
1826  *
1827  * Only one thread is allowed to call this on the same mpv_handle at a time.
1828  * The API won't complain if more than one thread calls this, but it will cause
1829  * race conditions in the client when accessing the shared mpv_event struct.
1830  * Note that most other API functions are not restricted by this, and no API
1831  * function internally calls mpv_wait_event(). Additionally, concurrent calls
1832  * to different mpv_handles are always safe.
1833  *
1834  * As long as the timeout is 0, this is safe to be called from mpv render API
1835  * threads.
1836  *
1837  * @param timeout Timeout in seconds, after which the function returns even if
1838  * no event was received. A MPV_EVENT_NONE is returned on
1839  * timeout. A value of 0 will disable waiting. Negative values
1840  * will wait with an infinite timeout.
1841  * @return A struct containing the event ID and other data. The pointer (and
1842  * fields in the struct) stay valid until the next mpv_wait_event()
1843  * call, or until the mpv_handle is destroyed. You must not write to
1844  * the struct, and all memory referenced by it will be automatically
1845  * released by the API on the next mpv_wait_event() call, or when the
1846  * context is destroyed. The return value is never NULL.
1847  */
1848 mpv_event *mpv_wait_event(mpv_handle *ctx, double timeout);
1849 
1850 /**
1851  * Interrupt the current mpv_wait_event() call. This will wake up the thread
1852  * currently waiting in mpv_wait_event(). If no thread is waiting, the next
1853  * mpv_wait_event() call will return immediately (this is to avoid lost
1854  * wakeups).
1855  *
1856  * mpv_wait_event() will receive a MPV_EVENT_NONE if it's woken up due to
1857  * this call. But note that this dummy event might be skipped if there are
1858  * already other events queued. All what counts is that the waiting thread
1859  * is woken up at all.
1860  *
1861  * Safe to be called from mpv render API threads.
1862  */
1863 void mpv_wakeup(mpv_handle *ctx);
1864 
1865 /**
1866  * Set a custom function that should be called when there are new events. Use
1867  * this if blocking in mpv_wait_event() to wait for new events is not feasible.
1868  *
1869  * Keep in mind that the callback will be called from foreign threads. You
1870  * must not make any assumptions of the environment, and you must return as
1871  * soon as possible (i.e. no long blocking waits). Exiting the callback through
1872  * any other means than a normal return is forbidden (no throwing exceptions,
1873  * no longjmp() calls). You must not change any local thread state (such as
1874  * the C floating point environment).
1875  *
1876  * You are not allowed to call any client API functions inside of the callback.
1877  * In particular, you should not do any processing in the callback, but wake up
1878  * another thread that does all the work. The callback is meant strictly for
1879  * notification only, and is called from arbitrary core parts of the player,
1880  * that make no considerations for reentrant API use or allowing the callee to
1881  * spend a lot of time doing other things. Keep in mind that it's also possible
1882  * that the callback is called from a thread while a mpv API function is called
1883  * (i.e. it can be reentrant).
1884  *
1885  * In general, the client API expects you to call mpv_wait_event() to receive
1886  * notifications, and the wakeup callback is merely a helper utility to make
1887  * this easier in certain situations. Note that it's possible that there's
1888  * only one wakeup callback invocation for multiple events. You should call
1889  * mpv_wait_event() with no timeout until MPV_EVENT_NONE is reached, at which
1890  * point the event queue is empty.
1891  *
1892  * If you actually want to do processing in a callback, spawn a thread that
1893  * does nothing but call mpv_wait_event() in a loop and dispatches the result
1894  * to a callback.
1895  *
1896  * Only one wakeup callback can be set.
1897  *
1898  * @param cb function that should be called if a wakeup is required
1899  * @param d arbitrary userdata passed to cb
1900  */
1901 void mpv_set_wakeup_callback(mpv_handle *ctx, void (*cb)(void *d), void *d);
1902 
1903 /**
1904  * Block until all asynchronous requests are done. This affects functions like
1905  * mpv_command_async(), which return immediately and return their result as
1906  * events.
1907  *
1908  * This is a helper, and somewhat equivalent to calling mpv_wait_event() in a
1909  * loop until all known asynchronous requests have sent their reply as event,
1910  * except that the event queue is not emptied.
1911  *
1912  * In case you called mpv_suspend() before, this will also forcibly reset the
1913  * suspend counter of the given handle.
1914  */
1916 
1917 /**
1918  * A hook is like a synchronous event that blocks the player. You register
1919  * a hook handler with this function. You will get an event, which you need
1920  * to handle, and once things are ready, you can let the player continue with
1921  * mpv_hook_continue().
1922  *
1923  * Currently, hooks can't be removed explicitly. But they will be implicitly
1924  * removed if the mpv_handle it was registered with is destroyed. This also
1925  * continues the hook if it was being handled by the destroyed mpv_handle (but
1926  * this should be avoided, as it might mess up order of hook execution).
1927  *
1928  * Hook handlers are ordered globally by priority and order of registration.
1929  * Handlers for the same hook with same priority are invoked in order of
1930  * registration (the handler registered first is run first). Handlers with
1931  * lower priority are run first (which seems backward).
1932  *
1933  * See the "Hooks" section in the manpage to see which hooks are currently
1934  * defined.
1935  *
1936  * Some hooks might be reentrant (so you get multiple MPV_EVENT_HOOK for the
1937  * same hook). If this can happen for a specific hook type, it will be
1938  * explicitly documented in the manpage.
1939  *
1940  * Only the mpv_handle on which this was called will receive the hook events,
1941  * or can "continue" them.
1942  *
1943  * @param reply_userdata This will be used for the mpv_event.reply_userdata
1944  * field for the received MPV_EVENT_HOOK events.
1945  * If you have no use for this, pass 0.
1946  * @param name The hook name. This should be one of the documented names. But
1947  * if the name is unknown, the hook event will simply be never
1948  * raised.
1949  * @param priority See remarks above. Use 0 as a neutral default.
1950  * @return error code (usually fails only on OOM)
1951  */
1952 int mpv_hook_add(mpv_handle *ctx, uint64_t reply_userdata,
1953  const char *name, int priority);
1954 
1955 /**
1956  * Respond to a MPV_EVENT_HOOK event. You must call this after you have handled
1957  * the event. There is no way to "cancel" or "stop" the hook.
1958  *
1959  * Calling this will will typically unblock the player for whatever the hook
1960  * is responsible for (e.g. for the "on_load" hook it lets it continue
1961  * playback).
1962  *
1963  * It is explicitly undefined behavior to call this more than once for each
1964  * MPV_EVENT_HOOK, to pass an incorrect ID, or to call this on a mpv_handle
1965  * different from the one that registered the handler and received the event.
1966  *
1967  * @param id This must be the value of the mpv_event_hook.id field for the
1968  * corresponding MPV_EVENT_HOOK.
1969  * @return error code
1970  */
1971 int mpv_hook_continue(mpv_handle *ctx, uint64_t id);
1972 
1973 #if MPV_ENABLE_DEPRECATED
1974 
1975 /**
1976  * Return a UNIX file descriptor referring to the read end of a pipe. This
1977  * pipe can be used to wake up a poll() based processing loop. The purpose of
1978  * this function is very similar to mpv_set_wakeup_callback(), and provides
1979  * a primitive mechanism to handle coordinating a foreign event loop and the
1980  * libmpv event loop. The pipe is non-blocking. It's closed when the mpv_handle
1981  * is destroyed. This function always returns the same value (on success).
1982  *
1983  * This is in fact implemented using the same underlying code as for
1984  * mpv_set_wakeup_callback() (though they don't conflict), and it is as if each
1985  * callback invocation writes a single 0 byte to the pipe. When the pipe
1986  * becomes readable, the code calling poll() (or select()) on the pipe should
1987  * read all contents of the pipe and then call mpv_wait_event(c, 0) until
1988  * no new events are returned. The pipe contents do not matter and can just
1989  * be discarded. There is not necessarily one byte per readable event in the
1990  * pipe. For example, the pipes are non-blocking, and mpv won't block if the
1991  * pipe is full. Pipes are normally limited to 4096 bytes, so if there are
1992  * more than 4096 events, the number of readable bytes can not equal the number
1993  * of events queued. Also, it's possible that mpv does not write to the pipe
1994  * once it's guaranteed that the client was already signaled. See the example
1995  * below how to do it correctly.
1996  *
1997  * Example:
1998  *
1999  * int pipefd = mpv_get_wakeup_pipe(mpv);
2000  * if (pipefd < 0)
2001  * error();
2002  * while (1) {
2003  * struct pollfd pfds[1] = {
2004  * { .fd = pipefd, .events = POLLIN },
2005  * };
2006  * // Wait until there are possibly new mpv events.
2007  * poll(pfds, 1, -1);
2008  * if (pfds[0].revents & POLLIN) {
2009  * // Empty the pipe. Doing this before calling mpv_wait_event()
2010  * // ensures that no wakeups are missed. It's not so important to
2011  * // make sure the pipe is really empty (it will just cause some
2012  * // additional wakeups in unlikely corner cases).
2013  * char unused[256];
2014  * read(pipefd, unused, sizeof(unused));
2015  * while (1) {
2016  * mpv_event *ev = mpv_wait_event(mpv, 0);
2017  * // If MPV_EVENT_NONE is received, the event queue is empty.
2018  * if (ev->event_id == MPV_EVENT_NONE)
2019  * break;
2020  * // Process the event.
2021  * ...
2022  * }
2023  * }
2024  * }
2025  *
2026  * @deprecated this function will be removed in the future. If you need this
2027  * functionality, use mpv_set_wakeup_callback(), create a pipe
2028  * manually, and call write() on your pipe in the callback.
2029  *
2030  * @return A UNIX FD of the read end of the wakeup pipe, or -1 on error.
2031  * On MS Windows/MinGW, this will always return -1.
2032  */
2034 
2035 /**
2036  * @deprecated use render.h
2037  */
2038 typedef enum mpv_sub_api {
2039  /**
2040  * For using mpv's OpenGL renderer on an external OpenGL context.
2041  * mpv_get_sub_api(MPV_SUB_API_OPENGL_CB) returns mpv_opengl_cb_context*.
2042  * This context can be used with mpv_opengl_cb_* functions.
2043  * Will return NULL if unavailable (if OpenGL support was not compiled in).
2044  * See opengl_cb.h for details.
2045  *
2046  * @deprecated use render.h
2047  */
2049 } mpv_sub_api;
2050 
2051 /**
2052  * This is used for additional APIs that are not strictly part of the core API.
2053  * See the individual mpv_sub_api member values.
2054  *
2055  * @deprecated use render.h
2056  */
2057 void *mpv_get_sub_api(mpv_handle *ctx, mpv_sub_api sub_api);
2058 
2059 #endif
2060 
2061 #ifdef __cplusplus
2062 }
2063 #endif
2064 
2065 #endif
MPV_EVENT_END_FILE
@ MPV_EVENT_END_FILE
Notification after playback end (after the file was unloaded).
Definition: client.h:1326
MPV_LOG_LEVEL_INFO
@ MPV_LOG_LEVEL_INFO
"warn" - possible problems
Definition: client.h:1550
mpv_get_property_async
int mpv_get_property_async(mpv_handle *ctx, uint64_t reply_userdata, const char *name, mpv_format format)
Get a property asynchronously.
MPV_FORMAT_STRING
@ MPV_FORMAT_STRING
The basic type is char*.
Definition: client.h:709
mpv_client_name
const char * mpv_client_name(mpv_handle *ctx)
Return the name of this client handle.
mpv_event_end_file
struct mpv_event_end_file mpv_event_end_file
MPV_END_FILE_REASON_QUIT
@ MPV_END_FILE_REASON_QUIT
Playback was stopped by the quit command or player shutdown.
Definition: client.h:1598
MPV_ERROR_EVENT_QUEUE_FULL
@ MPV_ERROR_EVENT_QUEUE_FULL
The event ringbuffer is full.
Definition: client.h:278
mpv_event_hook
struct mpv_event_hook mpv_event_hook
mpv_event_client_message::num_args
int num_args
Arbitrary arguments chosen by the sender of the message.
Definition: client.h:1687
mpv_unobserve_property
int mpv_unobserve_property(mpv_handle *mpv, uint64_t registered_reply_userdata)
Undo mpv_observe_property().
MPV_EVENT_SHUTDOWN
@ MPV_EVENT_SHUTDOWN
Happens when the player quits.
Definition: client.h:1297
MPV_ERROR_NOTHING_TO_PLAY
@ MPV_ERROR_NOTHING_TO_PLAY
There was no audio or video data to play.
Definition: client.h:345
mpv_event_end_file::playlist_insert_num_entries
int playlist_insert_num_entries
See playlist_insert_id.
Definition: client.h:1668
mpv_event
struct mpv_event mpv_event
mpv_node::flag
int flag
valid if format==MPV_FORMAT_STRING
Definition: client.h:804
mpv_node_list::keys
char ** keys
MPV_FORMAT_NODE_ARRAY: unused (typically NULL), access is not allowed.
Definition: client.h:866
mpv_node_list::num
int num
Number of entries.
Definition: client.h:844
MPV_LOG_LEVEL_NONE
@ MPV_LOG_LEVEL_NONE
Definition: client.h:1546
mpv_event_script_input_dispatch::arg0
int arg0
Definition: client.h:1675
MPV_ERROR_UNINITIALIZED
@ MPV_ERROR_UNINITIALIZED
The mpv core wasn't configured and initialized yet.
Definition: client.h:287
mpv_suspend
void mpv_suspend(mpv_handle *ctx)
This does nothing since mpv 0.23.0 (API version 1.24).
MPV_LOG_LEVEL_ERROR
@ MPV_LOG_LEVEL_ERROR
"fatal" - critical/aborting errors
Definition: client.h:1548
mpv_client_api_version
unsigned long mpv_client_api_version(void)
Return the MPV_CLIENT_API_VERSION the mpv source has been compiled with.
mpv_wakeup
void mpv_wakeup(mpv_handle *ctx)
Interrupt the current mpv_wait_event() call.
MPV_EVENT_METADATA_UPDATE
@ MPV_EVENT_METADATA_UPDATE
Happens when metadata (like file tags) is possibly updated.
Definition: client.h:1447
mpv_event_log_message::level
const char * level
The log level as string.
Definition: client.h:1568
mpv_command_string
int mpv_command_string(mpv_handle *ctx, const char *args)
Same as mpv_command, but use input.conf parsing for splitting arguments.
MPV_EVENT_GET_PROPERTY_REPLY
@ MPV_EVENT_GET_PROPERTY_REPLY
Reply to a mpv_get_property_async() request.
Definition: client.h:1306
MPV_ERROR_OPTION_FORMAT
@ MPV_ERROR_OPTION_FORMAT
Trying to set an option using an unsupported MPV_FORMAT.
Definition: client.h:300
mpv_get_property_string
char * mpv_get_property_string(mpv_handle *ctx, const char *name)
Return the value of the property with the given name as string.
mpv_byte_array::data
void * data
Pointer to the data.
Definition: client.h:877
mpv_request_log_messages
int mpv_request_log_messages(mpv_handle *ctx, const char *min_level)
Enable or disable receiving of log messages.
MPV_END_FILE_REASON_REDIRECT
@ MPV_END_FILE_REASON_REDIRECT
The file was a playlist or similar.
Definition: client.h:1615
mpv_get_property_osd_string
char * mpv_get_property_osd_string(mpv_handle *ctx, const char *name)
Return the property as "OSD" formatted string.
MPV_FORMAT_DOUBLE
@ MPV_FORMAT_DOUBLE
The basic type is double.
Definition: client.h:744
mpv_client_id
int64_t mpv_client_id(mpv_handle *ctx)
Return the ID of this client handle.
mpv_event_property::data
void * data
Received property value.
Definition: client.h:1535
MPV_ERROR_GENERIC
@ MPV_ERROR_GENERIC
Unspecified error.
Definition: client.h:363
MPV_EVENT_IDLE
@ MPV_EVENT_IDLE
Idle mode was entered.
Definition: client.h:1363
mpv_event_log_message
struct mpv_event_log_message mpv_event_log_message
mpv_load_config_file
int mpv_load_config_file(mpv_handle *ctx, const char *filename)
Load a config file.
mpv_initialize
int mpv_initialize(mpv_handle *ctx)
Initialize an uninitialized mpv instance.
mpv_event::reply_userdata
uint64_t reply_userdata
If the event is in reply to a request (made with this API and this API handle), this is set to the re...
Definition: client.h:1741
mpv_event
Definition: client.h:1713
mpv_event::event_id
mpv_event_id event_id
One of mpv_event.
Definition: client.h:1718
MPV_EVENT_CLIENT_MESSAGE
@ MPV_EVENT_CLIENT_MESSAGE
Triggered by the script-message input command.
Definition: client.h:1420
MPV_ERROR_UNSUPPORTED
@ MPV_ERROR_UNSUPPORTED
Generic error for signaling that certain system requirements are not fulfilled.
Definition: client.h:355
MPV_ERROR_NOMEM
@ MPV_ERROR_NOMEM
Memory allocation failed.
Definition: client.h:282
mpv_error_string
const char * mpv_error_string(int error)
Return a string describing the error.
MPV_EVENT_COMMAND_REPLY
@ MPV_EVENT_COMMAND_REPLY
Reply to a mpv_command_async() or mpv_command_node_async() request.
Definition: client.h:1316
MPV_EVENT_QUEUE_OVERFLOW
@ MPV_EVENT_QUEUE_OVERFLOW
Happens if the internal per-mpv_handle ringbuffer overflows, and at least 1 event had to be dropped.
Definition: client.h:1485
mpv_format
mpv_format
Data format for options and properties.
Definition: client.h:667
MPV_EVENT_AUDIO_RECONFIG
@ MPV_EVENT_AUDIO_RECONFIG
Similar to MPV_EVENT_VIDEO_RECONFIG.
Definition: client.h:1436
MPV_FORMAT_OSD_STRING
@ MPV_FORMAT_OSD_STRING
The basic type is char*.
Definition: client.h:719
mpv_event_end_file
Definition: client.h:1626
mpv_command_node_async
int mpv_command_node_async(mpv_handle *ctx, uint64_t reply_userdata, mpv_node *args)
Same as mpv_command_node(), but run it asynchronously.
MPV_EVENT_START_FILE
@ MPV_EVENT_START_FILE
Notification before playback start of a file (before the file is loaded).
Definition: client.h:1321
MPV_ERROR_INVALID_PARAMETER
@ MPV_ERROR_INVALID_PARAMETER
Generic catch-all error if a parameter is set to an invalid or unsupported value.
Definition: client.h:292
MPV_END_FILE_REASON_STOP
@ MPV_END_FILE_REASON_STOP
Playback was stopped by an external action (e.g.
Definition: client.h:1594
MPV_ERROR_NOT_IMPLEMENTED
@ MPV_ERROR_NOT_IMPLEMENTED
The API function which was called is a stub only.
Definition: client.h:359
mpv_resume
void mpv_resume(mpv_handle *ctx)
See mpv_suspend().
MPV_EVENT_TRACKS_CHANGED
@ MPV_EVENT_TRACKS_CHANGED
The list of video/audio/subtitle tracks was changed.
Definition: client.h:1342
MPV_EVENT_SEEK
@ MPV_EVENT_SEEK
Happens when a seek was initiated.
Definition: client.h:1453
MPV_FORMAT_NODE_MAP
@ MPV_FORMAT_NODE_MAP
See MPV_FORMAT_NODE_ARRAY.
Definition: client.h:785
mpv_event_script_input_dispatch
Definition: client.h:1674
mpv_destroy
void mpv_destroy(mpv_handle *ctx)
Disconnect and destroy the mpv_handle.
mpv_event_hook::name
const char * name
The hook name as passed to mpv_hook_add().
Definition: client.h:1695
MPV_EVENT_TRACK_SWITCHED
@ MPV_EVENT_TRACK_SWITCHED
A video/audio/subtitle track was switched on or off.
Definition: client.h:1350
mpv_get_property
int mpv_get_property(mpv_handle *ctx, const char *name, mpv_format format, void *data)
Read the value of the given property.
mpv_event_script_input_dispatch::type
const char * type
Definition: client.h:1676
mpv_command_node
int mpv_command_node(mpv_handle *ctx, mpv_node *args, mpv_node *result)
Same as mpv_command(), but allows passing structured data in any format.
MPV_LOG_LEVEL_DEBUG
@ MPV_LOG_LEVEL_DEBUG
"v" - noisy informational message
Definition: client.h:1552
mpv_request_event
int mpv_request_event(mpv_handle *ctx, mpv_event_id event, int enable)
Enable or disable the given event.
MPV_END_FILE_REASON_EOF
@ MPV_END_FILE_REASON_EOF
The end of file was reached.
Definition: client.h:1590
mpv_event_client_message
Definition: client.h:1680
mpv_command_async
int mpv_command_async(mpv_handle *ctx, uint64_t reply_userdata, const char **args)
Same as mpv_command, but run the command asynchronously.
mpv_create_client
mpv_handle * mpv_create_client(mpv_handle *ctx, const char *name)
Create a new client handle connected to the same player core as ctx.
mpv_get_sub_api
void * mpv_get_sub_api(mpv_handle *ctx, mpv_sub_api sub_api)
This is used for additional APIs that are not strictly part of the core API.
mpv_event_name
const char * mpv_event_name(mpv_event_id event)
Return a string describing the event.
mpv_event::error
int error
This is mainly used for events that are replies to (asynchronous) requests.
Definition: client.h:1729
MPV_ERROR_SUCCESS
@ MPV_ERROR_SUCCESS
No error happened (used to signal successful operation).
Definition: client.h:269
mpv_event_command
Definition: client.h:1703
mpv_set_option_string
int mpv_set_option_string(mpv_handle *ctx, const char *name, const char *data)
Convenience function to set an option to a string value.
mpv_sub_api
mpv_sub_api
Definition: client.h:2038
mpv_wait_event
mpv_event * mpv_wait_event(mpv_handle *ctx, double timeout)
Wait for the next event, or until the timeout expires, or if another thread makes a call to mpv_wakeu...
mpv_byte_array
(see mpv_node)
Definition: client.h:872
MPV_EVENT_LOG_MESSAGE
@ MPV_EVENT_LOG_MESSAGE
See mpv_request_log_messages().
Definition: client.h:1301
MPV_ERROR_UNKNOWN_FORMAT
@ MPV_ERROR_UNKNOWN_FORMAT
When trying to load the file, the file format could not be determined, or the file was too broken to ...
Definition: client.h:350
mpv_event_property::format
mpv_format format
Format of the data field in the same struct.
Definition: client.h:1523
mpv_event_log_message::prefix
const char * prefix
The module prefix, identifies the sender of the message.
Definition: client.h:1563
MPV_EVENT_UNPAUSE
@ MPV_EVENT_UNPAUSE
Playback was unpaused.
Definition: client.h:1392
MPV_FORMAT_NODE_ARRAY
@ MPV_FORMAT_NODE_ARRAY
Used with mpv_node only.
Definition: client.h:781
MPV_FORMAT_INT64
@ MPV_FORMAT_INT64
The basic type is int64_t.
Definition: client.h:740
mpv_node::ba
struct mpv_byte_array * ba
valid if format==MPV_FORMAT_BYTE_ARRAY
Definition: client.h:815
MPV_EVENT_PAUSE
@ MPV_EVENT_PAUSE
Playback was paused.
Definition: client.h:1384
MPV_EVENT_CHAPTER_CHANGE
@ MPV_EVENT_CHAPTER_CHANGE
Happens when the current chapter changes.
Definition: client.h:1474
MPV_LOG_LEVEL_WARN
@ MPV_LOG_LEVEL_WARN
"error" - simple errors
Definition: client.h:1549
mpv_event_command::result
mpv_node result
Result data of the command.
Definition: client.h:1710
mpv_get_time_us
int64_t mpv_get_time_us(mpv_handle *ctx)
Return the internal time in microseconds.
mpv_terminate_destroy
void mpv_terminate_destroy(mpv_handle *ctx)
Similar to mpv_destroy(), but brings the player and all clients down as well, and waits until all of ...
MPV_ERROR_PROPERTY_FORMAT
@ MPV_ERROR_PROPERTY_FORMAT
Trying to set or get a property using an unsupported MPV_FORMAT.
Definition: client.h:313
mpv_create
mpv_handle * mpv_create(void)
Create a new mpv instance and an associated client API handle to control the mpv instance.
mpv_free
void mpv_free(void *data)
General function to deallocate memory returned by some of the API functions.
mpv_set_wakeup_callback
void mpv_set_wakeup_callback(mpv_handle *ctx, void(*cb)(void *d), void *d)
Set a custom function that should be called when there are new events.
MPV_LOG_LEVEL_TRACE
@ MPV_LOG_LEVEL_TRACE
"debug" - very noisy technical information
Definition: client.h:1553
mpv_event_client_message::args
const char ** args
Definition: client.h:1688
mpv_set_property
int mpv_set_property(mpv_handle *ctx, const char *name, mpv_format format, void *data)
Set a property to a given value.
mpv_command
int mpv_command(mpv_handle *ctx, const char **args)
Send a command to the player.
mpv_abort_async_command
void mpv_abort_async_command(mpv_handle *ctx, uint64_t reply_userdata)
Signal to all async requests with the matching ID to abort.
mpv_set_property_string
int mpv_set_property_string(mpv_handle *ctx, const char *name, const char *data)
Convenience function to set a property to a string value.
mpv_event_to_node
int mpv_event_to_node(mpv_node *dst, mpv_event *src)
Convert the given src event to a mpv_node, and set dst to the result.
MPV_ERROR_COMMAND
@ MPV_ERROR_COMMAND
General error when running a command with mpv_command and similar.
Definition: client.h:327
mpv_node::string
char * string
Definition: client.h:803
mpv_command_ret
int mpv_command_ret(mpv_handle *ctx, const char **args, mpv_node *result)
This is essentially identical to mpv_command() but it also returns a result.
MPV_FORMAT_BYTE_ARRAY
@ MPV_FORMAT_BYTE_ARRAY
A raw, untyped byte array.
Definition: client.h:790
MPV_END_FILE_REASON_ERROR
@ MPV_END_FILE_REASON_ERROR
Some kind of error happened that lead to playback abort.
Definition: client.h:1606
MPV_ERROR_PROPERTY_NOT_FOUND
@ MPV_ERROR_PROPERTY_NOT_FOUND
The accessed property doesn't exist.
Definition: client.h:309
mpv_event_hook
Definition: client.h:1691
mpv_handle
struct mpv_handle mpv_handle
Client context used by the client API.
Definition: client.h:256
MPV_FORMAT_NODE
@ MPV_FORMAT_NODE
The type is mpv_node.
Definition: client.h:777
MPV_FORMAT_NONE
@ MPV_FORMAT_NONE
Invalid.
Definition: client.h:673
mpv_event_log_message::log_level
mpv_log_level log_level
The same contents as the level field, but as a numeric ID.
Definition: client.h:1579
mpv_event::data
void * data
The meaning and contents of the data member depend on the event_id: MPV_EVENT_GET_PROPERTY_REPLY: mpv...
Definition: client.h:1757
mpv_error
mpv_error
List of error codes than can be returned by API functions.
Definition: client.h:262
mpv_free_node_contents
void mpv_free_node_contents(mpv_node *node)
Frees any data referenced by the node.
mpv_log_level
mpv_log_level
Numeric log levels.
Definition: client.h:1545
MPV_EVENT_PROPERTY_CHANGE
@ MPV_EVENT_PROPERTY_CHANGE
Event sent due to mpv_observe_property().
Definition: client.h:1465
mpv_node::format
mpv_format format
Type of the data stored in this struct.
Definition: client.h:834
MPV_EVENT_FILE_LOADED
@ MPV_EVENT_FILE_LOADED
Notification when the file has been loaded (headers were read etc.), and decoding starts.
Definition: client.h:1331
MPV_ERROR_PROPERTY_UNAVAILABLE
@ MPV_ERROR_PROPERTY_UNAVAILABLE
The property exists, but is not available.
Definition: client.h:319
mpv_event_id
mpv_event_id
Definition: client.h:1286
MPV_ERROR_PROPERTY_ERROR
@ MPV_ERROR_PROPERTY_ERROR
Error setting or getting a property.
Definition: client.h:323
MPV_FORMAT_FLAG
@ MPV_FORMAT_FLAG
The basic type is int.
Definition: client.h:736
mpv_event_client_message
struct mpv_event_client_message mpv_event_client_message
MPV_EVENT_HOOK
@ MPV_EVENT_HOOK
Triggered if a hook handler was registered with mpv_hook_add(), and the hook is invoked.
Definition: client.h:1492
mpv_event_log_message::text
const char * text
The log message.
Definition: client.h:1574
mpv_hook_continue
int mpv_hook_continue(mpv_handle *ctx, uint64_t id)
Respond to a MPV_EVENT_HOOK event.
MPV_EVENT_VIDEO_RECONFIG
@ MPV_EVENT_VIDEO_RECONFIG
Happens after video changed in some way.
Definition: client.h:1431
mpv_event_end_file::error
int error
If reason==MPV_END_FILE_REASON_ERROR, this contains a mpv error code (one of MPV_ERROR_....
Definition: client.h:1640
mpv_event_property
Definition: client.h:1512
mpv_end_file_reason
mpv_end_file_reason
Since API version 1.9.
Definition: client.h:1583
MPV_ERROR_OPTION_ERROR
@ MPV_ERROR_OPTION_ERROR
Setting the option failed.
Definition: client.h:305
mpv_node::u
union mpv_node::@0 u
mpv_event_command
struct mpv_event_command mpv_event_command
mpv_hook_add
int mpv_hook_add(mpv_handle *ctx, uint64_t reply_userdata, const char *name, int priority)
A hook is like a synchronous event that blocks the player.
mpv_set_property_async
int mpv_set_property_async(mpv_handle *ctx, uint64_t reply_userdata, const char *name, mpv_format format, void *data)
Set a property asynchronously.
MPV_LOG_LEVEL_V
@ MPV_LOG_LEVEL_V
"info" - informational message
Definition: client.h:1551
mpv_node::list
struct mpv_node_list * list
valid if format==MPV_FORMAT_DOUBLE
Definition: client.h:811
mpv_node::int64
int64_t int64
valid if format==MPV_FORMAT_FLAG
Definition: client.h:805
MPV_EVENT_SCRIPT_INPUT_DISPATCH
@ MPV_EVENT_SCRIPT_INPUT_DISPATCH
Definition: client.h:1411
mpv_create_weak_client
mpv_handle * mpv_create_weak_client(mpv_handle *ctx, const char *name)
This is the same as mpv_create_client(), but the created mpv_handle is treated as a weak reference.
mpv_event_start_file::playlist_entry_id
int64_t playlist_entry_id
Playlist entry ID of the file being loaded now.
Definition: client.h:1623
mpv_event_start_file
struct mpv_event_start_file mpv_event_start_file
Since API version 1.108.
mpv_event_end_file::playlist_entry_id
int64_t playlist_entry_id
Playlist entry ID of the file that was being played or attempted to be played.
Definition: client.h:1647
MPV_ERROR_VO_INIT_FAILED
@ MPV_ERROR_VO_INIT_FAILED
Initializing the video output failed.
Definition: client.h:339
mpv_node_list::values
mpv_node * values
MPV_FORMAT_NODE_ARRAY: values[N] refers to value of the Nth item.
Definition: client.h:855
mpv_detach_destroy
void mpv_detach_destroy(mpv_handle *ctx)
mpv_event_start_file
Since API version 1.108.
Definition: client.h:1619
mpv_get_wakeup_pipe
int mpv_get_wakeup_pipe(mpv_handle *ctx)
Return a UNIX file descriptor referring to the read end of a pipe.
mpv_node
struct mpv_node mpv_node
Generic data storage.
mpv_node_list
struct mpv_node_list mpv_node_list
(see mpv_node)
MPV_ERROR_OPTION_NOT_FOUND
@ MPV_ERROR_OPTION_NOT_FOUND
Trying to set an option that doesn't exist.
Definition: client.h:296
mpv_event_property
struct mpv_event_property mpv_event_property
MPV_EVENT_SET_PROPERTY_REPLY
@ MPV_EVENT_SET_PROPERTY_REPLY
Reply to a mpv_set_property_async() request.
Definition: client.h:1311
MPV_EVENT_PLAYBACK_RESTART
@ MPV_EVENT_PLAYBACK_RESTART
There was a discontinuity of some sort (like a seek), and playback was reinitialized.
Definition: client.h:1460
MPV_SUB_API_OPENGL_CB
@ MPV_SUB_API_OPENGL_CB
For using mpv's OpenGL renderer on an external OpenGL context.
Definition: client.h:2048
mpv_event_hook::id
uint64_t id
Internal ID that must be passed to mpv_hook_continue().
Definition: client.h:1699
mpv_node::double_
double double_
valid if format==MPV_FORMAT_INT64
Definition: client.h:806
mpv_node_list
(see mpv_node)
Definition: client.h:840
mpv_node
Generic data storage.
Definition: client.h:801
mpv_byte_array
struct mpv_byte_array mpv_byte_array
(see mpv_node)
mpv_event_script_input_dispatch
struct mpv_event_script_input_dispatch mpv_event_script_input_dispatch
mpv_event_log_message
Definition: client.h:1556
MPV_ERROR_LOADING_FAILED
@ MPV_ERROR_LOADING_FAILED
Generic error on loading (usually used with mpv_event_end_file.error).
Definition: client.h:331
mpv_wait_async_requests
void mpv_wait_async_requests(mpv_handle *ctx)
Block until all asynchronous requests are done.
mpv_event_end_file::reason
int reason
Corresponds to the values in enum mpv_end_file_reason (the "int" type will be replaced with mpv_end_f...
Definition: client.h:1633
mpv_event_end_file::playlist_insert_id
int64_t playlist_insert_id
If loading ended, because the playlist entry to be played was for example a playlist,...
Definition: client.h:1662
MPV_EVENT_NONE
@ MPV_EVENT_NONE
Nothing happened.
Definition: client.h:1290
mpv_observe_property
int mpv_observe_property(mpv_handle *mpv, uint64_t reply_userdata, const char *name, mpv_format format)
Get a notification whenever the given property changes.
mpv_set_option
int mpv_set_option(mpv_handle *ctx, const char *name, mpv_format format, void *data)
Set an option.
MPV_ERROR_AO_INIT_FAILED
@ MPV_ERROR_AO_INIT_FAILED
Initializing the audio output failed.
Definition: client.h:335
MPV_EVENT_TICK
@ MPV_EVENT_TICK
Sent every time after a video frame is displayed.
Definition: client.h:1402
mpv_event_property::name
const char * name
Name of the property.
Definition: client.h:1516
mpv_byte_array::size
size_t size
Size of the data pointed to by ptr.
Definition: client.h:881
MPV_LOG_LEVEL_FATAL
@ MPV_LOG_LEVEL_FATAL
"no" - disable absolutely all messages
Definition: client.h:1547