diff options
Diffstat (limited to 'libmpv/client.h')
| -rw-r--r-- | libmpv/client.h | 575 |
1 files changed, 318 insertions, 257 deletions
diff --git a/libmpv/client.h b/libmpv/client.h index 2d108ca8d3..8eb5e05a04 100644 --- a/libmpv/client.h +++ b/libmpv/client.h @@ -17,7 +17,7 @@ * Note: the client API is licensed under ISC (see above) to enable * other wrappers outside of mpv. But keep in mind that the * mpv core is by default still GPLv2+ - unless built with - * --enable-lgpl, which makes it LGPLv2+. + * -Dgpl=false, which makes it LGPLv2+. */ #ifndef MPV_CLIENT_API_H_ @@ -26,6 +26,23 @@ #include <stddef.h> #include <stdint.h> +#ifdef _WIN32 +#define MPV_EXPORT __declspec(dllexport) +#define MPV_SELECTANY __declspec(selectany) +#elif defined(__GNUC__) || defined(__clang__) +#define MPV_EXPORT __attribute__((visibility("default"))) +#define MPV_SELECTANY +#else +#define MPV_EXPORT +#define MPV_SELECTANY +#endif + +#ifdef __cpp_decltype +#define MPV_DECLTYPE decltype +#else +#define MPV_DECLTYPE __typeof__ +#endif + #ifdef __cplusplus extern "C" { #endif @@ -141,9 +158,13 @@ extern "C" { * - In certain cases, mpv may start sub processes (such as with the ytdl * wrapper script). * - Using UNIX IPC (off by default) will override the SIGPIPE signal handler, - * and set it to SIG_IGN. - * - mpv will reseed the legacy C random number generator by calling srand() at - * some random point once. + * and set it to SIG_IGN. Some invocations of the "subprocess" command will + * also do that. + * - mpv may start sub processes, so overriding SIGCHLD, or waiting on all PIDs + * (such as calling wait()) by the parent process or any other library within + * the process must be avoided. libmpv itself only waits for its own PIDs. + * - If anything in the process registers signal handlers, they must set the + * SA_RESTART flag. Otherwise you WILL get random failures on signals. * * Encoding of filenames * --------------------- @@ -160,7 +181,7 @@ extern "C" { * filenames in the local 8 bit encoding. It does not use fopen() either; * it uses _wfopen(). * - * On OS X, filenames and other strings taken/returned by libmpv can have + * On macOS, filenames and other strings taken/returned by libmpv can have * inconsistent unicode normalization. This can sometimes lead to problems. * You have to hope for the best. * @@ -169,14 +190,14 @@ extern "C" { * Embedding the video window * -------------------------- * - * Using the render API (in render_cb.h) is recommended. This API requires + * Using the render API (in render.h) is recommended. This API requires * you to create and maintain an OpenGL context, to which you can render * video using a specific API call. This API does not include keyboard or mouse * input directly. * * There is an older way to embed the native mpv window into your own. You have * to get the raw window handle, and set it as "wid" option. This works on X11, - * win32, and OSX only. It's much easier to use than the render API, but + * win32, and macOS only. It's much easier to use than the render API, but * also has various problems. * * Also see client API examples and the mpv manpage. There is an extensive @@ -209,10 +230,8 @@ extern "C" { * This are the planned changes that will most likely be done on the next major * bump of the library: * - * - remove all symbols and include files that are marked as deprecated + * - remove all symbols that are marked as deprecated * - reassign enum numerical values to remove gaps - * - remove the mpv_opengl_init_params.extra_exts field - * - change the type of mpv_event_end_file.reason * - disabling all events by default */ @@ -229,7 +248,7 @@ extern "C" { * relational operators (<, >, <=, >=). */ #define MPV_MAKE_VERSION(major, minor) (((major) << 16) | (minor) | 0UL) -#define MPV_CLIENT_API_VERSION MPV_MAKE_VERSION(1, 107) +#define MPV_CLIENT_API_VERSION MPV_MAKE_VERSION(2, 3) /** * The API user is allowed to "#define MPV_ENABLE_DEPRECATED 0" before @@ -244,7 +263,7 @@ extern "C" { /** * Return the MPV_CLIENT_API_VERSION the mpv source has been compiled with. */ -unsigned long mpv_client_api_version(void); +MPV_EXPORT unsigned long mpv_client_api_version(void); /** * Client context used by the client API. Every client has its own private @@ -368,7 +387,7 @@ typedef enum mpv_error { * @return A static string describing the error. The string is completely * static, i.e. doesn't need to be deallocated, and is valid forever. */ -const char *mpv_error_string(int error); +MPV_EXPORT const char *mpv_error_string(int error); /** * General function to deallocate memory returned by some of the API functions. @@ -377,7 +396,7 @@ const char *mpv_error_string(int error); * * @param data A valid pointer returned by the API, or NULL. */ -void mpv_free(void *data); +MPV_EXPORT void mpv_free(void *data); /** * Return the name of this client handle. Every client has its own unique @@ -386,7 +405,24 @@ void mpv_free(void *data); * @return The client name. The string is read-only and is valid until the * mpv_handle is destroyed. */ -const char *mpv_client_name(mpv_handle *ctx); +MPV_EXPORT const char *mpv_client_name(mpv_handle *ctx); + +/** + * Return the ID of this client handle. Every client has its own unique ID. This + * ID is never reused by the core, even if the mpv_handle at hand gets destroyed + * and new handles get allocated. + * + * IDs are never 0 or negative. + * + * Some mpv APIs (not necessarily all) accept a name in the form "@<id>" in + * addition of the proper mpv_client_name(), where "<id>" is the ID in decimal + * form (e.g. "@123"). For example, the "script-message-to" command takes the + * client name as first argument, but also accepts the client ID formatted in + * this manner. + * + * @return The client ID. + */ +MPV_EXPORT int64_t mpv_client_id(mpv_handle *ctx); /** * Create a new mpv instance and an associated client API handle to control @@ -442,7 +478,7 @@ const char *mpv_client_name(mpv_handle *ctx); * - out of memory * - LC_NUMERIC is not set to "C" (see general remarks) */ -mpv_handle *mpv_create(void); +MPV_EXPORT mpv_handle *mpv_create(void); /** * Initialize an uninitialized mpv instance. If the mpv instance is already @@ -459,12 +495,12 @@ mpv_handle *mpv_create(void); * - load-scripts * - script * - player-operation-mode - * - input-app-events (OSX) + * - input-app-events (macOS) * - all encoding mode options * * @return error code */ -int mpv_initialize(mpv_handle *ctx); +MPV_EXPORT int mpv_initialize(mpv_handle *ctx); /** * Disconnect and destroy the mpv_handle. ctx will be deallocated with this @@ -476,27 +512,7 @@ int mpv_initialize(mpv_handle *ctx); * be sent MPV_EVENT_SHUTDOWN. This function may block until these clients * have responded to the shutdown event, and the core is finally destroyed. */ -void mpv_destroy(mpv_handle *ctx); - -#if MPV_ENABLE_DEPRECATED -/** - * @deprecated use mpv_destroy(), which has exactly the same semantics (the - * deprecation is a mere rename) - * - * Since mpv client API version 1.29: - * If the last mpv_handle is detached, the core player is destroyed. In - * addition, if there are only weak mpv_handles (such as created by - * mpv_create_weak_client() or internal scripts), these mpv_handles will - * be sent MPV_EVENT_SHUTDOWN. This function may block until these clients - * have responded to the shutdown event, and the core is finally destroyed. - * - * Before mpv client API version 1.29: - * This left the player running. If you want to be sure that the - * player is terminated, send a "quit" command, and wait until the - * MPV_EVENT_SHUTDOWN event is received, or use mpv_terminate_destroy(). - */ -void mpv_detach_destroy(mpv_handle *ctx); -#endif +MPV_EXPORT void mpv_destroy(mpv_handle *ctx); /** * Similar to mpv_destroy(), but brings the player and all clients down @@ -523,7 +539,7 @@ void mpv_detach_destroy(mpv_handle *ctx); * this function will merely send a quit command and then call * mpv_destroy(), without waiting for the actual shutdown. */ -void mpv_terminate_destroy(mpv_handle *ctx); +MPV_EXPORT void mpv_terminate_destroy(mpv_handle *ctx); /** * Create a new client handle connected to the same player core as ctx. This @@ -549,7 +565,7 @@ void mpv_terminate_destroy(mpv_handle *ctx); * If NULL, an arbitrary name is automatically chosen. * @return a new handle, or NULL on error */ -mpv_handle *mpv_create_client(mpv_handle *ctx, const char *name); +MPV_EXPORT mpv_handle *mpv_create_client(mpv_handle *ctx, const char *name); /** * This is the same as mpv_create_client(), but the created mpv_handle is @@ -563,7 +579,7 @@ mpv_handle *mpv_create_client(mpv_handle *ctx, const char *name); * mpv_terminate_destroy() _and_ mpv_destroy() for the last non-weak * mpv_handle will block until all weak mpv_handles are destroyed. */ -mpv_handle *mpv_create_weak_client(mpv_handle *ctx, const char *name); +MPV_EXPORT mpv_handle *mpv_create_weak_client(mpv_handle *ctx, const char *name); /** * Load a config file. This loads and parses the file, and sets every entry in @@ -583,47 +599,10 @@ mpv_handle *mpv_create_weak_client(mpv_handle *ctx, const char *name); * @param filename absolute path to the config file on the local filesystem * @return error code */ -int mpv_load_config_file(mpv_handle *ctx, const char *filename); - -#if MPV_ENABLE_DEPRECATED - -/** - * This does nothing since mpv 0.23.0 (API version 1.24). Below is the - * description of the old behavior. - * - * Stop the playback thread. This means the core will stop doing anything, and - * only run and answer to client API requests. This is sometimes useful; for - * example, no new frame will be queued to the video output, so doing requests - * which have to wait on the video output can run instantly. - * - * Suspension is reentrant and recursive for convenience. Any thread can call - * the suspend function multiple times, and the playback thread will remain - * suspended until the last thread resumes it. Note that during suspension, all - * clients still have concurrent access to the core, which is serialized through - * a single mutex. - * - * Call mpv_resume() to resume the playback thread. You must call mpv_resume() - * for each mpv_suspend() call. Calling mpv_resume() more often than - * mpv_suspend() is not allowed. - * - * Calling this on an uninitialized player (see mpv_create()) will deadlock. - * - * @deprecated This function, as well as mpv_resume(), are deprecated, and - * will stop doing anything soon. Their semantics were never - * well-defined, and their usefulness is extremely limited. The - * calls will remain stubs in order to keep ABI compatibility. - */ -void mpv_suspend(mpv_handle *ctx); - -/** - * See mpv_suspend(). - */ -void mpv_resume(mpv_handle *ctx); - -#endif +MPV_EXPORT int mpv_load_config_file(mpv_handle *ctx, const char *filename); /** - * Return the internal time in microseconds. This has an arbitrary start offset, + * Return the internal time in nanoseconds. This has an arbitrary start offset, * but will never wrap or go backwards. * * Note that this is always the real time, and doesn't necessarily have to do @@ -636,7 +615,12 @@ void mpv_resume(mpv_handle *ctx); * * Safe to be called from mpv render API threads. */ -int64_t mpv_get_time_us(mpv_handle *ctx); +MPV_EXPORT int64_t mpv_get_time_ns(mpv_handle *ctx); + +/** + * Same as mpv_get_time_ns but in microseconds. + */ +MPV_EXPORT int64_t mpv_get_time_us(mpv_handle *ctx); /** * Data format for options and properties. The API functions to get/set @@ -645,7 +629,9 @@ int64_t mpv_get_time_us(mpv_handle *ctx); */ typedef enum mpv_format { /** - * Invalid. Sometimes used for empty values. + * Invalid. Sometimes used for empty values. This is always defined to 0, + * so a normal 0-init of mpv_format (or e.g. mpv_node) is guaranteed to set + * this it to MPV_FORMAT_NONE (which makes some things saner as consequence). */ MPV_FORMAT_NONE = 0, /** @@ -762,8 +748,7 @@ typedef enum mpv_format { MPV_FORMAT_NODE_MAP = 8, /** * A raw, untyped byte array. Only used only with mpv_node, and only in - * some very special situations. (Currently, only for the screenshot-raw - * command.) + * some very specific situations. (Some commands use it.) */ MPV_FORMAT_BYTE_ARRAY = 9 } mpv_format; @@ -869,7 +854,7 @@ typedef struct mpv_byte_array { * be called. (This is just a clarification that there's no danger of anything * strange happening in these cases.) */ -void mpv_free_node_contents(mpv_node *node); +MPV_EXPORT void mpv_free_node_contents(mpv_node *node); /** * Set an option. Note that you can't normally set options during runtime. It @@ -884,36 +869,19 @@ void mpv_free_node_contents(mpv_node *node); * Starting with mpv version 0.21.0 (version 1.23) most options can be set * with mpv_set_property() (and related functions), and even before * mpv_initialize(). In some obscure corner cases, using this function - * to set options might still be required (see below, and also section - * "Inconsistencies between options and properties" on the manpage). Once + * to set options might still be required (see + * "Inconsistencies between options and properties" in the manpage). Once * these are resolved, the option setting functions might be fully * deprecated. * - * The following options still need to be set either _before_ - * mpv_initialize() with mpv_set_property() (or related functions), or - * with mpv_set_option() (or related functions) at any time: - * - options shadowed by deprecated properties: - * - demuxer (property deprecated in 0.21.0) - * - idle (property deprecated in 0.21.0) - * - fps (property deprecated in 0.21.0) - * - cache (property deprecated in 0.21.0) - * - length (property deprecated in 0.10.0) - * - audio-samplerate (property deprecated in 0.10.0) - * - audio-channels (property deprecated in 0.10.0) - * - audio-format (property deprecated in 0.10.0) - * - deprecated options shadowed by properties: - * - chapter (option deprecated in 0.21.0) - * - playlist-pos (option deprecated in 0.21.0) - * The deprecated properties were removed in mpv 0.23.0. - * * @param name Option name. This is the same as on the mpv command line, but * without the leading "--". * @param format see enum mpv_format. * @param[in] data Option value (according to the format). * @return error code */ -int mpv_set_option(mpv_handle *ctx, const char *name, mpv_format format, - void *data); +MPV_EXPORT int mpv_set_option(mpv_handle *ctx, const char *name, mpv_format format, + void *data); /** * Convenience function to set an option to a string value. This is like @@ -921,7 +889,7 @@ int mpv_set_option(mpv_handle *ctx, const char *name, mpv_format format, * * @return error code */ -int mpv_set_option_string(mpv_handle *ctx, const char *name, const char *data); +MPV_EXPORT int mpv_set_option_string(mpv_handle *ctx, const char *name, const char *data); /** * Send a command to the player. Commands are the same as those used in @@ -937,7 +905,7 @@ int mpv_set_option_string(mpv_handle *ctx, const char *name, const char *data); * is the command, and the following items are arguments. * @return error code */ -int mpv_command(mpv_handle *ctx, const char **args); +MPV_EXPORT int mpv_command(mpv_handle *ctx, const char **args); /** * Same as mpv_command(), but allows passing structured data in any format. @@ -973,7 +941,7 @@ int mpv_command(mpv_handle *ctx, const char **args); * Not many commands actually use this at all. * @return error code (the result parameter is not set on error) */ -int mpv_command_node(mpv_handle *ctx, mpv_node *args, mpv_node *result); +MPV_EXPORT int mpv_command_node(mpv_handle *ctx, mpv_node *args, mpv_node *result); /** * This is essentially identical to mpv_command() but it also returns a result. @@ -989,7 +957,7 @@ int mpv_command_node(mpv_handle *ctx, mpv_node *args, mpv_node *result); * Not many commands actually use this at all. * @return error code (the result parameter is not set on error) */ -int mpv_command_ret(mpv_handle *ctx, const char **args, mpv_node *result); +MPV_EXPORT int mpv_command_ret(mpv_handle *ctx, const char **args, mpv_node *result); /** * Same as mpv_command, but use input.conf parsing for splitting arguments. @@ -998,7 +966,7 @@ int mpv_command_ret(mpv_handle *ctx, const char **args, mpv_node *result); * * This also has OSD and string expansion enabled by default. */ -int mpv_command_string(mpv_handle *ctx, const char *args); +MPV_EXPORT int mpv_command_string(mpv_handle *ctx, const char *args); /** * Same as mpv_command, but run the command asynchronously. @@ -1008,6 +976,11 @@ int mpv_command_string(mpv_handle *ctx, const char *args); * error code set if running the command failed. For commands that * return data, the data is put into mpv_event_command.result. * + * The only case when you do not receive an event is when the function call + * itself fails. This happens only if parsing the command itself (or otherwise + * validating it) fails, i.e. the return code of the API call is not 0 or + * positive. + * * Safe to be called from mpv render API threads. * * @param reply_userdata the value mpv_event.reply_userdata of the reply will @@ -1015,8 +988,8 @@ int mpv_command_string(mpv_handle *ctx, const char *args); * @param args NULL-terminated list of strings (see mpv_command()) * @return error code (if parsing or queuing the command fails) */ -int mpv_command_async(mpv_handle *ctx, uint64_t reply_userdata, - const char **args); +MPV_EXPORT int mpv_command_async(mpv_handle *ctx, uint64_t reply_userdata, + const char **args); /** * Same as mpv_command_node(), but run it asynchronously. Basically, this @@ -1032,8 +1005,8 @@ int mpv_command_async(mpv_handle *ctx, uint64_t reply_userdata, * @param args as in mpv_command_node() * @return error code (if parsing or queuing the command fails) */ -int mpv_command_node_async(mpv_handle *ctx, uint64_t reply_userdata, - mpv_node *args); +MPV_EXPORT int mpv_command_node_async(mpv_handle *ctx, uint64_t reply_userdata, + mpv_node *args); /** * Signal to all async requests with the matching ID to abort. This affects @@ -1065,7 +1038,7 @@ int mpv_command_node_async(mpv_handle *ctx, uint64_t reply_userdata, * * @param reply_userdata ID of the request to be aborted (see above) */ -void mpv_abort_async_command(mpv_handle *ctx, uint64_t reply_userdata); +MPV_EXPORT void mpv_abort_async_command(mpv_handle *ctx, uint64_t reply_userdata); /** * Set a property to a given value. Properties are essentially variables which @@ -1098,15 +1071,25 @@ void mpv_abort_async_command(mpv_handle *ctx, uint64_t reply_userdata); * @param[in] data Option value. * @return error code */ -int mpv_set_property(mpv_handle *ctx, const char *name, mpv_format format, - void *data); +MPV_EXPORT int mpv_set_property(mpv_handle *ctx, const char *name, mpv_format format, + void *data); /** * Convenience function to set a property to a string value. * * This is like calling mpv_set_property() with MPV_FORMAT_STRING. */ -int mpv_set_property_string(mpv_handle *ctx, const char *name, const char *data); +MPV_EXPORT int mpv_set_property_string(mpv_handle *ctx, const char *name, const char *data); + +/** + * Convenience function to delete a property. + * + * This is equivalent to running the command "del [name]". + * + * @param name The property name. See input.rst for a list of properties. + * @return error code + */ +MPV_EXPORT int mpv_del_property(mpv_handle *ctx, const char *name); /** * Set a property asynchronously. You will receive the result of the operation @@ -1123,8 +1106,8 @@ int mpv_set_property_string(mpv_handle *ctx, const char *name, const char *data) * will never be modified by the client API. * @return error code if sending the request failed */ -int mpv_set_property_async(mpv_handle *ctx, uint64_t reply_userdata, - const char *name, mpv_format format, void *data); +MPV_EXPORT int mpv_set_property_async(mpv_handle *ctx, uint64_t reply_userdata, + const char *name, mpv_format format, void *data); /** * Read the value of the given property. @@ -1144,8 +1127,8 @@ int mpv_set_property_async(mpv_handle *ctx, uint64_t reply_userdata, * mpv_free_node_contents() (MPV_FORMAT_NODE). * @return error code */ -int mpv_get_property(mpv_handle *ctx, const char *name, mpv_format format, - void *data); +MPV_EXPORT int mpv_get_property(mpv_handle *ctx, const char *name, mpv_format format, + void *data); /** * Return the value of the property with the given name as string. This is @@ -1160,7 +1143,7 @@ int mpv_get_property(mpv_handle *ctx, const char *name, mpv_format format, * @return Property value, or NULL if the property can't be retrieved. Free * the string with mpv_free(). */ -char *mpv_get_property_string(mpv_handle *ctx, const char *name); +MPV_EXPORT char *mpv_get_property_string(mpv_handle *ctx, const char *name); /** * Return the property as "OSD" formatted string. This is the same as @@ -1169,7 +1152,7 @@ char *mpv_get_property_string(mpv_handle *ctx, const char *name); * @return Property value, or NULL if the property can't be retrieved. Free * the string with mpv_free(). */ -char *mpv_get_property_osd_string(mpv_handle *ctx, const char *name); +MPV_EXPORT char *mpv_get_property_osd_string(mpv_handle *ctx, const char *name); /** * Get a property asynchronously. You will receive the result of the operation @@ -1183,8 +1166,8 @@ char *mpv_get_property_osd_string(mpv_handle *ctx, const char *name); * @param format see enum mpv_format. * @return error code if sending the request failed */ -int mpv_get_property_async(mpv_handle *ctx, uint64_t reply_userdata, - const char *name, mpv_format format); +MPV_EXPORT int mpv_get_property_async(mpv_handle *ctx, uint64_t reply_userdata, + const char *name, mpv_format format); /** * Get a notification whenever the given property changes. You will receive @@ -1241,8 +1224,8 @@ int mpv_get_property_async(mpv_handle *ctx, uint64_t reply_userdata, * from the change events. * @return error code (usually fails only on OOM or unsupported format) */ -int mpv_observe_property(mpv_handle *mpv, uint64_t reply_userdata, - const char *name, mpv_format format); +MPV_EXPORT int mpv_observe_property(mpv_handle *mpv, uint64_t reply_userdata, + const char *name, mpv_format format); /** * Undo mpv_observe_property(). This will remove all observed properties for @@ -1254,7 +1237,7 @@ int mpv_observe_property(mpv_handle *mpv, uint64_t reply_userdata, * @return negative value is an error code, >=0 is number of removed properties * on success (includes the case when 0 were removed) */ -int mpv_unobserve_property(mpv_handle *mpv, uint64_t registered_reply_userdata); +MPV_EXPORT int mpv_unobserve_property(mpv_handle *mpv, uint64_t registered_reply_userdata); typedef enum mpv_event_id { /** @@ -1289,6 +1272,7 @@ typedef enum mpv_event_id { MPV_EVENT_COMMAND_REPLY = 5, /** * Notification before playback start of a file (before the file is loaded). + * See also mpv_event and mpv_event_start_file. */ MPV_EVENT_START_FILE = 6, /** @@ -1303,61 +1287,18 @@ typedef enum mpv_event_id { MPV_EVENT_FILE_LOADED = 8, #if MPV_ENABLE_DEPRECATED /** - * The list of video/audio/subtitle tracks was changed. (E.g. a new track - * was found. This doesn't necessarily indicate a track switch; for this, - * MPV_EVENT_TRACK_SWITCHED is used.) - * - * @deprecated This is equivalent to using mpv_observe_property() on the - * "track-list" property. The event is redundant, and might - * be removed in the far future. - */ - MPV_EVENT_TRACKS_CHANGED = 9, - /** - * A video/audio/subtitle track was switched on or off. - * - * @deprecated This is equivalent to using mpv_observe_property() on the - * "vid", "aid", and "sid" properties. The event is redundant, - * and might be removed in the far future. - */ - MPV_EVENT_TRACK_SWITCHED = 10, -#endif - /** * Idle mode was entered. In this mode, no file is played, and the playback * core waits for new commands. (The command line player normally quits * instead of entering idle mode, unless --idle was specified. If mpv * was started with mpv_create(), idle mode is enabled by default.) - */ - MPV_EVENT_IDLE = 11, -#if MPV_ENABLE_DEPRECATED - /** - * Playback was paused. This indicates the user pause state. - * - * The user pause state is the state the user requested (changed with the - * "pause" property). There is an internal pause state too, which is entered - * if e.g. the network is too slow (the "core-idle" property generally - * indicates whether the core is playing or waiting). - * - * This event is sent whenever any pause states change, not only the user - * state. You might get multiple events in a row while these states change - * independently. But the event ID sent always indicates the user pause - * state. - * - * If you don't want to deal with this, use mpv_observe_property() on the - * "pause" property and ignore MPV_EVENT_PAUSE/UNPAUSE. Likewise, the - * "core-idle" property tells you whether video is actually playing or not. * - * @deprecated The event is redundant with mpv_observe_property() as - * mentioned above, and might be removed in the far future. - */ - MPV_EVENT_PAUSE = 12, - /** - * Playback was unpaused. See MPV_EVENT_PAUSE for not so obvious details. - * - * @deprecated The event is redundant with mpv_observe_property() as - * explained in the MPV_EVENT_PAUSE comments, and might be - * removed in the far future. + * @deprecated This is equivalent to using mpv_observe_property() on the + * "idle-active" property. The event is redundant, and might be + * removed in the far future. As a further warning, this event + * is not necessarily sent at the right point anymore (at the + * start of the program), while the property behaves correctly. */ - MPV_EVENT_UNPAUSE = 13, + MPV_EVENT_IDLE = 11, /** * Sent every time after a video frame is displayed. Note that currently, * this will be sent in lower frequency if there is no video, or playback @@ -1368,15 +1309,6 @@ typedef enum mpv_event_id { * (such as "playback-time"). */ MPV_EVENT_TICK = 14, - /** - * @deprecated This was used internally with the internal "script_dispatch" - * command to dispatch keyboard and mouse input for the OSC. - * It was never useful in general and has been completely - * replaced with "script-binding". - * This event never happens anymore, and is included in this - * header only for compatibility. - */ - MPV_EVENT_SCRIPT_INPUT_DISPATCH = 15, #endif /** * Triggered by the script-message input command. The command uses the @@ -1402,18 +1334,6 @@ typedef enum mpv_event_id { * because there is no such thing as audio output embedding. */ MPV_EVENT_AUDIO_RECONFIG = 18, -#if MPV_ENABLE_DEPRECATED - /** - * Happens when metadata (like file tags) is possibly updated. (It's left - * unspecified whether this happens on file start or only when it changes - * within a file.) - * - * @deprecated This is equivalent to using mpv_observe_property() on the - * "metadata" property. The event is redundant, and might - * be removed in the far future. - */ - MPV_EVENT_METADATA_UPDATE = 19, -#endif /** * Happens when a seek was initiated. Playback stops. Usually it will * resume with MPV_EVENT_PLAYBACK_RESTART as soon as the seek is finished. @@ -1421,9 +1341,9 @@ typedef enum mpv_event_id { MPV_EVENT_SEEK = 20, /** * There was a discontinuity of some sort (like a seek), and playback - * was reinitialized. Usually happens after seeking, or ordered chapter - * segment switches. The main purpose is allowing the client to detect - * when a seek request is finished. + * was reinitialized. Usually happens on start of playback and after + * seeking. The main purpose is allowing the client to detect when a seek + * request is finished. */ MPV_EVENT_PLAYBACK_RESTART = 21, /** @@ -1431,16 +1351,6 @@ typedef enum mpv_event_id { * See also mpv_event and mpv_event_property. */ MPV_EVENT_PROPERTY_CHANGE = 22, -#if MPV_ENABLE_DEPRECATED - /** - * Happens when the current chapter changes. - * - * @deprecated This is equivalent to using mpv_observe_property() on the - * "chapter" property. The event is redundant, and might - * be removed in the far future. - */ - MPV_EVENT_CHAPTER_CHANGE = 23, -#endif /** * Happens if the internal per-mpv_handle ringbuffer overflows, and at * least 1 event had to be dropped. This can happen if the client doesn't @@ -1475,7 +1385,7 @@ typedef enum mpv_event_id { * The string is completely static, i.e. doesn't need to be deallocated, * and is valid forever. */ -const char *mpv_event_name(mpv_event_id event); +MPV_EXPORT const char *mpv_event_name(mpv_event_id event); typedef struct mpv_event_property { /** @@ -1583,14 +1493,21 @@ typedef enum mpv_end_file_reason { MPV_END_FILE_REASON_REDIRECT = 5, } mpv_end_file_reason; +/// Since API version 1.108. +typedef struct mpv_event_start_file { + /** + * Playlist entry ID of the file being loaded now. + */ + int64_t playlist_entry_id; +} mpv_event_start_file; + typedef struct mpv_event_end_file { /** - * Corresponds to the values in enum mpv_end_file_reason (the "int" type - * will be replaced with mpv_end_file_reason on the next ABI bump). + * Corresponds to the values in enum mpv_end_file_reason. * * Unknown values should be treated as unknown. */ - int reason; + mpv_end_file_reason reason; /** * If reason==MPV_END_FILE_REASON_ERROR, this contains a mpv error code * (one of MPV_ERROR_...) giving an approximate reason why playback @@ -1598,17 +1515,36 @@ typedef struct mpv_event_end_file { * Since API version 1.9. */ int error; + /** + * Playlist entry ID of the file that was being played or attempted to be + * played. This has the same value as the playlist_entry_id field in the + * corresponding mpv_event_start_file event. + * Since API version 1.108. + */ + int64_t playlist_entry_id; + /** + * If loading ended, because the playlist entry to be played was for example + * a playlist, and the current playlist entry is replaced with a number of + * other entries. This may happen at least with MPV_END_FILE_REASON_REDIRECT + * (other event types may use this for similar but different purposes in the + * future). In this case, playlist_insert_id will be set to the playlist + * entry ID of the first inserted entry, and playlist_insert_num_entries to + * the total number of inserted playlist entries. Note this in this specific + * case, the ID of the last inserted entry is playlist_insert_id+num-1. + * Beware that depending on circumstances, you may observe the new playlist + * entries before seeing the event (e.g. reading the "playlist" property or + * getting a property change notification before receiving the event). + * Since API version 1.108. + */ + int64_t playlist_insert_id; + /** + * See playlist_insert_id. Only non-0 if playlist_insert_id is valid. Never + * negative. + * Since API version 1.108. + */ + int playlist_insert_num_entries; } mpv_event_end_file; -#if MPV_ENABLE_DEPRECATED -/** @deprecated see MPV_EVENT_SCRIPT_INPUT_DISPATCH for remarks - */ -typedef struct mpv_event_script_input_dispatch { - int arg0; - const char *type; -} mpv_event_script_input_dispatch; -#endif - typedef struct mpv_event_client_message { /** * Arbitrary arguments chosen by the sender of the message. If num_args > 0, @@ -1677,6 +1613,7 @@ typedef struct mpv_event { * MPV_EVENT_PROPERTY_CHANGE: mpv_event_property* * MPV_EVENT_LOG_MESSAGE: mpv_event_log_message* * MPV_EVENT_CLIENT_MESSAGE: mpv_event_client_message* + * MPV_EVENT_START_FILE: mpv_event_start_file* (since v1.108) * MPV_EVENT_END_FILE: mpv_event_end_file* * MPV_EVENT_HOOK: mpv_event_hook* * MPV_EVENT_COMMAND_REPLY* mpv_event_command* @@ -1689,6 +1626,31 @@ typedef struct mpv_event { } mpv_event; /** + * Convert the given src event to a mpv_node, and set *dst to the result. *dst + * is set to a MPV_FORMAT_NODE_MAP, with fields for corresponding mpv_event and + * mpv_event.data/mpv_event_* fields. + * + * The exact details are not completely documented out of laziness. A start + * is located in the "Events" section of the manpage. + * + * *dst may point to newly allocated memory, or pointers in mpv_event. You must + * copy the entire mpv_node if you want to reference it after mpv_event becomes + * invalid (such as making a new mpv_wait_event() call, or destroying the + * mpv_handle from which it was returned). Call mpv_free_node_contents() to free + * any memory allocations made by this API function. + * + * Safe to be called from mpv render API threads. + * + * @param dst Target. This is not read and fully overwritten. Must be released + * with mpv_free_node_contents(). Do not write to pointers returned + * by it. (On error, this may be left as an empty node.) + * @param src The source event. Not modified (it's not const due to the author's + * prejudice of the C version of const). + * @return error code (MPV_ERROR_NOMEM only, if at all) + */ +MPV_EXPORT int mpv_event_to_node(mpv_node *dst, mpv_event *src); + +/** * Enable or disable the given event. * * Some events are enabled by default. Some events can't be disabled. @@ -1702,7 +1664,7 @@ typedef struct mpv_event { * @param enable 1 to enable receiving this event, 0 to disable it. * @return error code */ -int mpv_request_event(mpv_handle *ctx, mpv_event_id event, int enable); +MPV_EXPORT int mpv_request_event(mpv_handle *ctx, mpv_event_id event, int enable); /** * Enable or disable receiving of log messages. These are the messages the @@ -1718,7 +1680,7 @@ int mpv_request_event(mpv_handle *ctx, mpv_event_id event, int enable); * Also see mpv_log_level. * @return error code */ -int mpv_request_log_messages(mpv_handle *ctx, const char *min_level); +MPV_EXPORT int mpv_request_log_messages(mpv_handle *ctx, const char *min_level); /** * Wait for the next event, or until the timeout expires, or if another thread @@ -1751,7 +1713,7 @@ int mpv_request_log_messages(mpv_handle *ctx, const char *min_level); * released by the API on the next mpv_wait_event() call, or when the * context is destroyed. The return value is never NULL. */ -mpv_event *mpv_wait_event(mpv_handle *ctx, double timeout); +MPV_EXPORT mpv_event *mpv_wait_event(mpv_handle *ctx, double timeout); /** * Interrupt the current mpv_wait_event() call. This will wake up the thread @@ -1766,7 +1728,7 @@ mpv_event *mpv_wait_event(mpv_handle *ctx, double timeout); * * Safe to be called from mpv render API threads. */ -void mpv_wakeup(mpv_handle *ctx); +MPV_EXPORT void mpv_wakeup(mpv_handle *ctx); /** * Set a custom function that should be called when there are new events. Use @@ -1804,7 +1766,7 @@ void mpv_wakeup(mpv_handle *ctx); * @param cb function that should be called if a wakeup is required * @param d arbitrary userdata passed to cb */ -void mpv_set_wakeup_callback(mpv_handle *ctx, void (*cb)(void *d), void *d); +MPV_EXPORT void mpv_set_wakeup_callback(mpv_handle *ctx, void (*cb)(void *d), void *d); /** * Block until all asynchronous requests are done. This affects functions like @@ -1818,7 +1780,7 @@ void mpv_set_wakeup_callback(mpv_handle *ctx, void (*cb)(void *d), void *d); * In case you called mpv_suspend() before, this will also forcibly reset the * suspend counter of the given handle. */ -void mpv_wait_async_requests(mpv_handle *ctx); +MPV_EXPORT void mpv_wait_async_requests(mpv_handle *ctx); /** * A hook is like a synchronous event that blocks the player. You register @@ -1855,8 +1817,8 @@ void mpv_wait_async_requests(mpv_handle *ctx); * @param priority See remarks above. Use 0 as a neutral default. * @return error code (usually fails only on OOM) */ -int mpv_hook_add(mpv_handle *ctx, uint64_t reply_userdata, - const char *name, int priority); +MPV_EXPORT int mpv_hook_add(mpv_handle *ctx, uint64_t reply_userdata, + const char *name, int priority); /** * Respond to a MPV_EVENT_HOOK event. You must call this after you have handled @@ -1874,7 +1836,7 @@ int mpv_hook_add(mpv_handle *ctx, uint64_t reply_userdata, * corresponding MPV_EVENT_HOOK. * @return error code */ -int mpv_hook_continue(mpv_handle *ctx, uint64_t id); +MPV_EXPORT int mpv_hook_continue(mpv_handle *ctx, uint64_t id); #if MPV_ENABLE_DEPRECATED @@ -1936,31 +1898,130 @@ int mpv_hook_continue(mpv_handle *ctx, uint64_t id); * @return A UNIX FD of the read end of the wakeup pipe, or -1 on error. |