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