diff options
Diffstat (limited to 'libmpv/client.h')
| -rw-r--r-- | libmpv/client.h | 66 |
1 files changed, 47 insertions, 19 deletions
diff --git a/libmpv/client.h b/libmpv/client.h index 6f50fd881c..c5847bc3db 100644 --- a/libmpv/client.h +++ b/libmpv/client.h @@ -367,8 +367,8 @@ const char *mpv_client_name(mpv_handle *ctx); * functions. * * Some API functions will return MPV_ERROR_UNINITIALIZED in the uninitialized - * state. You can call mpv_set_option() (or mpv_set_option_string() and other - * variants, and in mpv 0.21.0 or later mpv_set_property() etc.) to set initial + * state. You can call mpv_set_property() (or mpv_set_property_string() and + * other variants, and before mpv 0.21.0 mpv_set_option() etc.) to set initial * options. After this, call mpv_initialize() to start the player, and then use * e.g. mpv_command() to start playback of a file. * @@ -398,7 +398,7 @@ const char *mpv_client_name(mpv_handle *ctx); * options. * * The mpv command line parser is not available through this API, but you can - * set individual options with mpv_set_option(). Files for playback must be + * set individual options with mpv_set_property(). Files for playback must be * loaded with mpv_command() or others. * * Note that you should avoid doing concurrent accesses on the uninitialized @@ -419,6 +419,17 @@ mpv_handle *mpv_create(void); * This function needs to be called to make full use of the client API if the * client API handle was created with mpv_create(). * + * Only the following options require to be set _before_ mpv_initialize(): + * - options which are only read at initialization time: + * - config + * - config-dir + * - input-conf + * - load-scripts + * - script + * - priority (win32) + * - input-app-events (OSX) + * - all encoding mode options + * * @return error code */ int mpv_initialize(mpv_handle *ctx); @@ -489,10 +500,6 @@ mpv_handle *mpv_create_client(mpv_handle *ctx, const char *name); * possible that some options were successfully set even if any of these errors * happen. * - * The same restrictions as with mpv_set_option() apply: some options can't - * be set outside of idle or uninitialized state, and many options don't - * take effect immediately. - * * @param filename absolute path to the config file on the local filesystem * @return error code */ @@ -780,23 +787,35 @@ void mpv_free_node_contents(mpv_node *node); * works in uninitialized state (see mpv_create()), and in some cases in at * runtime. * - * Changing options at runtime does not always work. For some options, attempts - * to change them simply fails. Many other options may require reloading the - * file for changes to take effect. In general, you should prefer calling - * mpv_set_property() to change settings during playback, because the property - * mechanism guarantees that changes take effect immediately. - * * Using a format other than MPV_FORMAT_NODE is equivalent to constructing a * mpv_node with the given format and data, and passing the mpv_node to this * function. * - * Note: for most purposes, this is not needed anymore. 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 + * Note: this is semi-deprecated. For most purposes, this is not needed anymore. + * 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 section "Inconsistencies - * between options and properties" on the manpage). Once these are - * resolved, the option setting functions might be deprecated. + * to set options might still be required (see below, and also section + * "Inconsistencies between options and properties" on 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 will be removed in mpv 0.22.0. * * @param name Option name. This is the same as on the mpv command line, but * without the leading "--". @@ -903,6 +922,15 @@ int mpv_command_node_async(mpv_handle *ctx, uint64_t reply_userdata, * mpv_node with the given format and data, and passing the mpv_node to this * function. (Before API version 1.21, this was different.) * + * Note: starting with mpv 0.21.0 (client API version 1.23), this can be used to + * set options in general. It even can be used before mpv_initialize() + * has been called. If called before mpv_initialize(), setting properties + * not backed by options will result in MPV_ERROR_PROPERTY_UNAVAILABLE. + * In some cases, properties and options still conflict. In these cases, + * mpv_set_property() accesses the options before mpv_initialize(), and + * the properties after mpv_initialize(). These conflicts will be removed + * in mpv 0.22.0. See mpv_set_option() for further remarks. + * * @param name The property name. See input.rst for a list of properties. * @param format see enum mpv_format. * @param[in] data Option value. |