client API: more or less deprecate mpv_set_option()

With the merging of options and properties, the mpv_set_option()
function is close to being useless, and mpv_set_property() can be used
for everything instead. There are certain conflicts remaining, which are
explained in depth in the docs. For now, none of this should affect
existing code using the client API.

Make mpv_set_property() redirect to mpv_set_option() before
initialization.

Remove some options marked as M_OPT_FIXED. The "pause" and "speed"
options cannot be written anymore without the playloop being notified by
it, so the M_OPT_FIXED does nothing. For "vo-mmcss-profile", the problem
was lack of synchronization, which has been added. I'm not sure what the
problem was with "frames" - I think it was only marked as M_OPT_FIXED
because changing it during playback will have no effect. Except for
pause/speed, these changes are needed to make them writable as
properties after mpv_initialize().

Also replace all remaining uses of CONF_GLOBAL with M_OPT_FIXED.

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.