options: rename --video-aspect to --video-aspect-override

The justification for this is the fact that the `video-aspect` property
doesn't work well with `cycle_values` commands that include the value
"-1".

The "video-aspect" property has effectively no change in behavior, but
we may want to make it read-only in the future. I think it's probably
fine to leave as-is, though.

Fixes #6068.

DOCS/interface-changes.rst

@@ -104,6 +104,8 @@ Interface changes
     - add `--demuxer-cue-codepage`
     - add ``track-list/N/demux-bitrate``, ``track-list/N/demux-rotation`` and
       ``track-list/N/demux-par`` property
+    - Deprecate ``--video-aspect`` and add ``--video-aspect-override`` to
+      replace it. (The `video-aspect` option remains unchanged.)
  --- mpv 0.29.0 ---
     - drop --opensles-sample-rate, as --audio-samplerate should be used if desired
     - drop deprecated --videotoolbox-format, --ff-aid, --ff-vid, --ff-sid,

DOCS/man/input.rst

@@ -1937,10 +1937,11 @@ Property list
     Estimated deviation factor of the vsync duration.
 
 ``video-aspect`` (RW)
-    Video aspect, see ``--video-aspect``.
+    Deprecated. This is tied to ``--video-aspect-override``, but always
+    reports the current video aspect if video is active.
 
-    If video is active, this reports the effective aspect value, instead of
-    the value of the ``--video-aspect`` option.
+    The read and write components of this option can be split up into
+    ``video-params/aspect`` and ``video-aspect-override`` respectively.
 
 ``osd-width``, ``osd-height``
     Last known OSD width (can be 0). This is needed if you want to use the
@@ -2537,12 +2538,6 @@ caveats with some properties (due to historical reasons):
 
     Option changes at runtime are affected by this as well.
 
-``video-aspect``
-    While video is active, always returns the effective aspect ratio. Setting
-    a special value (like ``no``, values ``<= 0``) will make the property
-    set this as option, and return whatever actual aspect was derived from the
-    option setting.
-
 ``display-fps``
     If a VO is created, this will return either the actual display FPS, or
     an invalid value, instead of the option value.

DOCS/man/options.rst

@@ -1173,9 +1173,9 @@ Video
 
     This option has no effect if ``--video-unscaled`` option is used.
 
-``--video-aspect=<ratio|no>``
+``--video-aspect-override=<ratio|no>``
     Override video aspect ratio, in case aspect information is incorrect or
-    missing in the file being played. See also ``--no-video-aspect``.
+    missing in the file being played.
 
     These values have special meaning:
 
@@ -1187,13 +1187,13 @@ Video
 
     .. admonition:: Examples
 
-        - ``--video-aspect=4:3``  or ``--video-aspect=1.3333``
-        - ``--video-aspect=16:9`` or ``--video-aspect=1.7777``
-        - ``--no-video-aspect`` or ``--video-aspect=no``
+        - ``--video-aspect-override=4:3``  or ``--video-aspect-override=1.3333``
+        - ``--video-aspect-override=16:9`` or ``--video-aspect-override=1.7777``
+        - ``--no-video-aspect-override`` or ``--video-aspect-override=no``
 
 ``--video-aspect-method=<bitstream|container>``
     This sets the default video aspect determination method (if the aspect is
-    _not_ overridden by the user with ``--video-aspect`` or others).
+    _not_ overridden by the user with ``--video-aspect-override`` or others).
 
     :container: Strictly prefer the container aspect ratio. This is apparently
                 the default behavior with VLC, at least with Matroska. Note that
@@ -2814,7 +2814,7 @@ Window
     previous setting (e.g. in the config file). Overrides the
     ``--monitorpixelaspect`` setting if enabled.
 
-    See also ``--monitorpixelaspect`` and ``--video-aspect``.
+    See also ``--monitorpixelaspect`` and ``--video-aspect-override``.
 
     .. admonition:: Examples
 
@@ -2835,7 +2835,7 @@ Window
 ``--monitorpixelaspect=<ratio>``
     Set the aspect of a single pixel of your monitor or TV screen (default:
     1). A value of 1 means square pixels (correct for (almost?) all LCDs). See
-    also ``--monitoraspect`` and ``--video-aspect``.
+    also ``--monitoraspect`` and ``--video-aspect-override``.
 
 ``--stop-screensaver``, ``--no-stop-screensaver``
     Turns off the screensaver (or screen blanker and similar mechanisms) at

etc/input.conf

@@ -141,7 +141,7 @@
 #W add panscan +0.1                     #      in
 #e add panscan +0.1                     # same as previous binding (discouraged)
 # cycle video aspect ratios; "-1" is the container aspect
-#A cycle-values video-aspect "16:9" "4:3" "2.35:1" "-1"
+#A cycle-values video-aspect-override "16:9" "4:3" "2.35:1" "-1"
 #POWER quit
 #PLAY cycle pause
 #PAUSE cycle pause

options/options.c

@@ -519,7 +519,7 @@ const m_option_t mp_opts[] = {
 
     // -1 means auto aspect (prefer container size until aspect change)
     //  0 means square pixels
-    OPT_ASPECT("video-aspect", movie_aspect, UPDATE_IMGPAR, -1.0, 10.0),
+    OPT_ASPECT("video-aspect-override", movie_aspect, UPDATE_IMGPAR, -1.0, 10.0),
     OPT_CHOICE("video-aspect-method", aspect_method, UPDATE_IMGPAR,
                ({"bitstream", 1}, {"container", 2})),
 
@@ -764,7 +764,7 @@ const m_option_t mp_opts[] = {
 
     OPT_REMOVED("a52drc", "use --ad-lavc-ac3drc=level"),
     OPT_REMOVED("afm", "use --ad=..."),
-    OPT_REPLACED("aspect", "video-aspect"),
+    OPT_REPLACED("aspect", "video-aspect-override"),
     OPT_REMOVED("ass-bottom-margin", "use --vf=sub=bottom:top"),
     OPT_REPLACED("ass", "sub-ass"),
     OPT_REPLACED("audiofile", "audio-file"),
@@ -875,6 +875,7 @@ const m_option_t mp_opts[] = {
     OPT_REMOVED("no-ometadata", "use --no-ocopy-metadata"),
     OPT_REMOVED("video-stereo-mode", "removed, try --vf=stereo3d"),
     OPT_REMOVED("chapter", "use '--start=#123' '--end=#124' (for chapter 123)"),
+    OPT_REPLACED("video-aspect", "video-aspect-override"),
 
     {0}
 };

player/command.c

@@ -2739,11 +2739,27 @@ static int mp_property_vf_fps(void *ctx, struct m_property *prop,
     return m_property_double_ro(action, arg, 1.0 / avg);
 }
 
-/// Video aspect (RO)
+/// Video aspect (RW) (deprecated)
+// FIXME: please delete this mess as soon as the deprecation period is over
 static int mp_property_aspect(void *ctx, struct m_property *prop,
                               int action, void *arg)
 {
     MPContext *mpctx = ctx;
+    struct m_config_option *opt;
+    opt = m_config_get_co_raw(mpctx->mconfig, bstr0("video-aspect-override"));
+
+    struct command_ctx *cmd = mpctx->command_ctx;
+    for (int n = 0; n < cmd->num_warned_deprecated; n++) {
+        if (strcmp(cmd->warned_deprecated[n], prop->name) == 0)
+            goto skip_warn;
+    }
+
+    MP_WARN(mpctx, "Warning: property 'video-aspect' is deprecated, refer to "
+            "'video-params/aspect' and 'video-aspect-override'.\n");
+    MP_TARRAY_APPEND(cmd, cmd->warned_deprecated, cmd->num_warned_deprecated,
+                     (char *)prop->name);
+
+skip_warn: ;
 
     float aspect = mpctx->opts->movie_aspect;
     if (mpctx->vo_chain && aspect <= 0) {
@@ -2762,6 +2778,9 @@ static int mp_property_aspect(void *ctx, struct m_property *prop,
     }
 
     switch (action) {
+    case M_PROPERTY_GET_TYPE:
+        *(struct m_option *)arg = *(opt->opt);
+        return M_PROPERTY_OK;
     case M_PROPERTY_PRINT: {
         if (mpctx->opts->movie_aspect < 0) {
             *(char **)arg = talloc_asprintf(NULL, "%.3f (original)", aspect);
@@ -2773,8 +2792,14 @@ static int mp_property_aspect(void *ctx, struct m_property *prop,
         *(float *)arg = aspect;
         return M_PROPERTY_OK;
     }
+    case M_PROPERTY_SET: {
+        int flags = M_SETOPT_RUNTIME;
+        if (m_config_set_option_raw_direct(mpctx->mconfig, opt, arg, flags) < 0)
+            return M_PROPERTY_ERROR;
+        return M_PROPERTY_OK;
     }
-    return mp_property_generic_option(mpctx, prop, action, arg);
+    }
+    return M_PROPERTY_NOT_IMPLEMENTED;
 }
 
 /// Selected subtitles (RW)