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.

8 files changed, 101 insertions, 56 deletions

diff --git a/DOCS/client-api-changes.rst b/DOCS/client-api-changes.rst
index c76881fbd4..2a9371055a 100644
--- a/DOCS/client-api-changes.rst
+++ b/DOCS/client-api-changes.rst
@@ -39,6 +39,15 @@ API changes
           workaround for the FFmpeg TLS code, which has been fixed long ago.
         - deprecate mpv_suspend() and mpv_resume(). They will be stubbed out
           in mpv 0.22.0.
+        - make mpv_set_property() work to some degree before mpv_initialize().
+          It can now be used instead of mpv_set_option().
+        - semi-deprecate mpv_set_option()/mpv_set_option_string(). You should
+          use mpv_set_property() instead. There are some deprecated properties
+          which conflict with some options (see client.h remarks on
+          mpv_set_option()), for which mpv_set_option() might still be required.
+          In future mpv releases, the conflicting deprecated options/properties
+          will be removed, and mpv_set_option() will internally translate API
+          calls to mpv_set_property().
  --- mpv 0.19.0 ---
  1.22   - add stream_cb API for custom protocols
  --- mpv 0.18.1 ---
diff --git a/DOCS/interface-changes.rst b/DOCS/interface-changes.rst
index ae0d23a884..d32203ccb5 100644
--- a/DOCS/interface-changes.rst
+++ b/DOCS/interface-changes.rst
@@ -58,7 +58,7 @@ Interface changes
         - "fps" -> "container-fps"
         - "idle" -> "idle-active"
         - "cache" -> "cache-percent"
-      the old names are deprecated
+      the old names are deprecated and will change behavior in mpv 0.22.0.
     - remove deprecated "hwdec-active" and "hwdec-detected" properties
     - deprecate the ao and vo auto-profiles (they never made any sense)
     - deprecate "--vo=direct3d_shaders" - use "--vo=direct3d" instead.
diff --git a/common/encode_lavc.c b/common/encode_lavc.c
index 78688545b5..d0523857ee 100644
--- a/common/encode_lavc.c
+++ b/common/encode_lavc.c
@@ -36,25 +36,25 @@
 #define OPT_BASE_STRUCT struct encode_opts
 const struct m_sub_options encode_config = {
     .opts = (const m_option_t[]) {
-        OPT_STRING("o", file, CONF_GLOBAL | CONF_NOCFG | CONF_PRE_PARSE),
-        OPT_STRING("of", format, CONF_GLOBAL),
-        OPT_STRINGLIST("ofopts*", fopts, CONF_GLOBAL),
-        OPT_FLOATRANGE("ofps", fps, CONF_GLOBAL, 0.0, 1000000.0),
-        OPT_FLOATRANGE("omaxfps", maxfps, CONF_GLOBAL, 0.0, 1000000.0),
-        OPT_STRING("ovc", vcodec, CONF_GLOBAL),
-        OPT_STRINGLIST("ovcopts*", vopts, CONF_GLOBAL),
-        OPT_STRING("oac", acodec, CONF_GLOBAL),
-        OPT_STRINGLIST("oacopts*", aopts, CONF_GLOBAL),
-        OPT_FLAG("oharddup", harddup, CONF_GLOBAL),
-        OPT_FLOATRANGE("ovoffset", voffset, CONF_GLOBAL, -1000000.0, 1000000.0),
-        OPT_FLOATRANGE("oaoffset", aoffset, CONF_GLOBAL, -1000000.0, 1000000.0),
-        OPT_FLAG("ocopyts", copyts, CONF_GLOBAL),
-        OPT_FLAG("orawts", rawts, CONF_GLOBAL),
-        OPT_FLAG("oautofps", autofps, CONF_GLOBAL),
-        OPT_FLAG("oneverdrop", neverdrop, CONF_GLOBAL),
-        OPT_FLAG("ovfirst", video_first, CONF_GLOBAL),
-        OPT_FLAG("oafirst", audio_first, CONF_GLOBAL),
-        OPT_FLAG("ometadata", metadata, CONF_GLOBAL),
+        OPT_STRING("o", file, M_OPT_FIXED | CONF_NOCFG | CONF_PRE_PARSE),
+        OPT_STRING("of", format, M_OPT_FIXED),
+        OPT_STRINGLIST("ofopts*", fopts, M_OPT_FIXED),
+        OPT_FLOATRANGE("ofps", fps, M_OPT_FIXED, 0.0, 1000000.0),
+        OPT_FLOATRANGE("omaxfps", maxfps, M_OPT_FIXED, 0.0, 1000000.0),
+        OPT_STRING("ovc", vcodec, M_OPT_FIXED),
+        OPT_STRINGLIST("ovcopts*", vopts, M_OPT_FIXED),
+        OPT_STRING("oac", acodec, M_OPT_FIXED),
+        OPT_STRINGLIST("oacopts*", aopts, M_OPT_FIXED),
+        OPT_FLAG("oharddup", harddup, M_OPT_FIXED),
+        OPT_FLOATRANGE("ovoffset", voffset, M_OPT_FIXED, -1000000.0, 1000000.0),
+        OPT_FLOATRANGE("oaoffset", aoffset, M_OPT_FIXED, -1000000.0, 1000000.0),
+        OPT_FLAG("ocopyts", copyts, M_OPT_FIXED),
+        OPT_FLAG("orawts", rawts, M_OPT_FIXED),
+        OPT_FLAG("oautofps", autofps, M_OPT_FIXED),
+        OPT_FLAG("oneverdrop", neverdrop, M_OPT_FIXED),
+        OPT_FLAG("ovfirst", video_first, M_OPT_FIXED),
+        OPT_FLAG("oafirst", audio_first, M_OPT_FIXED),
+        OPT_FLAG("ometadata", metadata, M_OPT_FIXED),
         {0}
     },
     .size = sizeof(struct encode_opts),
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.
diff --git a/options/m_config.c b/options/m_config.c
index 4659c9aa21..08465df97f 100644
--- a/options/m_config.c
+++ b/options/m_config.c
@@ -997,9 +997,11 @@ void m_config_print_option_list(const struct m_config *config, const char *name)
             talloc_free(def);
         }
         if (opt->flags & M_OPT_NOCFG)
-            MP_INFO(config, " [nocfg]");
+            MP_INFO(config, " [not in config files]");
         if (opt->flags & M_OPT_FILE)
             MP_INFO(config, " [file]");
+        if (opt->flags & M_OPT_FIXED)
+            MP_INFO(config, " [no runtime changes]");
         MP_INFO(config, "\n");
         count++;
     }
diff --git a/options/m_option.h b/options/m_option.h
index 1744023663..92d0575db8 100644
--- a/options/m_option.h
+++ b/options/m_option.h
@@ -399,7 +399,6 @@ struct m_option {
 #define CONF_MAX                M_OPT_MAX
 #define CONF_RANGE              M_OPT_RANGE
 #define CONF_NOCFG              M_OPT_NOCFG
-#define CONF_GLOBAL             M_OPT_FIXED
 #define CONF_PRE_PARSE          M_OPT_PRE_PARSE
 
 // These flags are used to describe special parser capabilities or behavior.
diff --git a/options/options.c b/options/options.c
index 3512ee15e8..8d45c21b8d 100644
--- a/options/options.c
+++ b/options/options.c
@@ -187,7 +187,7 @@ static const m_option_t mp_vo_opt_list[] = {
                ({"no", 0}, {"yes", 1}, {"fs-only", 2}, {"never", 3})),
 #endif
 #if HAVE_WIN32
-    OPT_STRING("vo-mmcss-profile", mmcss_profile, M_OPT_FIXED),
+    OPT_STRING("vo-mmcss-profile", mmcss_profile, 0),
 #endif
 
     {0}
@@ -236,7 +236,7 @@ const struct m_sub_options dvd_conf = {
 
 const m_option_t mp_opts[] = {
     // handled in command line pre-parser (parse_commandline.c)
-    {"v", CONF_TYPE_STORE, CONF_GLOBAL | CONF_NOCFG, .offset = -1},
+    {"v", CONF_TYPE_STORE, M_OPT_FIXED | CONF_NOCFG, .offset = -1},
     {"playlist", CONF_TYPE_STRING, CONF_NOCFG | M_OPT_MIN | M_OPT_FIXED | M_OPT_FILE,
      .min = 1, .offset = -1},
     {"{", CONF_TYPE_STORE, CONF_NOCFG | M_OPT_FIXED, .offset = -1},
@@ -255,7 +255,7 @@ const m_option_t mp_opts[] = {
 // ------------------------- common options --------------------
     OPT_FLAG("quiet", quiet, 0),
     OPT_FLAG_STORE("really-quiet", verbose,
-                   CONF_GLOBAL | CONF_PRE_PARSE | M_OPT_NOPROP, -10),
+                   M_OPT_FIXED | CONF_PRE_PARSE | M_OPT_NOPROP, -10),
     OPT_FLAG("terminal", use_terminal, CONF_PRE_PARSE | UPDATE_TERM),
     OPT_GENERAL(char**, "msg-level", msg_levels, CONF_PRE_PARSE | UPDATE_TERM,
                 .type = &m_option_type_msglevels),
@@ -265,7 +265,7 @@ const m_option_t mp_opts[] = {
     OPT_FLAG("msg-module", msg_module, UPDATE_TERM),
     OPT_FLAG("msg-time", msg_time, UPDATE_TERM),
 #ifdef _WIN32
-    OPT_CHOICE("priority", w32_priority, CONF_GLOBAL,
+    OPT_CHOICE("priority", w32_priority, M_OPT_FIXED,
                ({"no",          0},
                 {"realtime",    REALTIME_PRIORITY_CLASS},
                 {"high",        HIGH_PRIORITY_CLASS},
@@ -274,19 +274,19 @@ const m_option_t mp_opts[] = {
                 {"belownormal", BELOW_NORMAL_PRIORITY_CLASS},
                 {"idle",        IDLE_PRIORITY_CLASS})),
 #endif
-    OPT_FLAG("config", load_config, CONF_GLOBAL | CONF_PRE_PARSE),
+    OPT_FLAG("config", load_config, M_OPT_FIXED | CONF_PRE_PARSE),
     OPT_STRING("config-dir", force_configdir,
-               CONF_GLOBAL | CONF_NOCFG | CONF_PRE_PARSE),
+               M_OPT_FIXED | CONF_NOCFG | CONF_PRE_PARSE),
     OPT_STRINGLIST("reset-on-next-file", reset_options, 0),
 
 #if HAVE_LUA
-    OPT_STRINGLIST("script", script_files, CONF_GLOBAL | M_OPT_FILE),
+    OPT_STRINGLIST("script", script_files, M_OPT_FIXED | M_OPT_FILE),
     OPT_KEYVALUELIST("script-opts", script_opts, 0),
     OPT_FLAG("osc", lua_load_osc, UPDATE_BUILTIN_SCRIPTS),
     OPT_FLAG("ytdl", lua_load_ytdl, UPDATE_BUILTIN_SCRIPTS),
     OPT_STRING("ytdl-format", lua_ytdl_format, 0),
     OPT_KEYVALUELIST("ytdl-raw-options", lua_ytdl_raw_options, 0),
-    OPT_FLAG("load-scripts", auto_load_scripts, CONF_GLOBAL),
+    OPT_FLAG("load-scripts", auto_load_scripts, M_OPT_FIXED),
 #endif
 
 // ------------------------- stream options --------------------
@@ -306,8 +306,7 @@ const m_option_t mp_opts[] = {
 
 // ------------------------- demuxer options --------------------
 
-    OPT_CHOICE_OR_INT("frames", play_frames, M_OPT_FIXED, 0, INT_MAX,
-                      ({"all", -1})),
+    OPT_CHOICE_OR_INT("frames", play_frames, 0, 0, INT_MAX, ({"all", -1})),
 
     OPT_REL_TIME("start", play_start, 0),
     OPT_REL_TIME("end", play_end, 0),
@@ -321,7 +320,7 @@ const m_option_t mp_opts[] = {
     OPT_CHOICE_OR_INT("playlist-start", playlist_pos, 0, 0, INT_MAX,
                       ({"auto", -1}, {"no", -1})),
 
-    OPT_FLAG("pause", pause, M_OPT_FIXED),
+    OPT_FLAG("pause", pause, 0),
     OPT_CHOICE("keep-open", keep_open, 0,
                ({"no", 0},
                 {"yes", 1},
@@ -389,8 +388,7 @@ const m_option_t mp_opts[] = {
     OPT_CHANNELS("audio-channels", audio_output_channels, 0),
     OPT_AUDIOFORMAT("audio-format", audio_output_format, 0),
     OPT_FLAG("audio-normalize-downmix", audio_normalize, 0),
-    OPT_DOUBLE("speed", playback_speed, M_OPT_RANGE | M_OPT_FIXED,
-               .min = 0.01, .max = 100.0),
+    OPT_DOUBLE("speed", playback_speed, M_OPT_RANGE, .min = 0.01, .max = 100.0),
 
     OPT_FLAG("audio-pitch-correction", pitch_correction, 0),
 
diff --git a/player/client.c b/player/client.c
index 93db0bb3d2..774a4e05c0 100644
--- a/player/client.c
+++ b/player/client.c
@@ -1132,8 +1132,17 @@ static void setproperty_fn(void *arg)
 int mpv_set_property(mpv_handle *ctx, const char *name, mpv_format format,
                      void *data)
 {
-    if (!ctx->mpctx->initialized)
-        return MPV_ERROR_UNINITIALIZED;
+    if (!ctx->mpctx->initialized) {
+        int r = mpv_set_option(ctx, name, format, data);
+        if (r == MPV_ERROR_OPTION_NOT_FOUND &&
+            mp_get_property_id(ctx->mpctx, name) >= 0)
+            return MPV_ERROR_PROPERTY_UNAVAILABLE;
+        switch (r) {
+        case MPV_ERROR_OPTION_FORMAT:    return MPV_ERROR_PROPERTY_FORMAT;
+        case MPV_ERROR_OPTION_NOT_FOUND: return MPV_ERROR_PROPERTY_NOT_FOUND;
+        default:                         return MPV_ERROR_PROPERTY_ERROR;
+        }
+    }
     if (!get_mp_type(format))
         return MPV_ERROR_PROPERTY_FORMAT;