player: rename --sub-forced-only to --sub-forced-events-only

The old name is pretty bad and users mistakenly think it has something
to do with selecting forced subtitles (that would be
--subs-fallback-forced). Instead of giving it such a generic name, make
it clearer that this has to do specifically with forced sub events
which is only relevant for a small minority of subtitles.

DOCS/interface-changes.rst

@@ -49,6 +49,7 @@ Interface changes
     - add `always` option to `--subs-fallback-forced`
     - remove `auto` choice from `--sub-forced-only`
     - remove `auto-forced-only` property
+    - rename `--sub-forced-only` to `--sub-forced-events-only`
  --- mpv 0.36.0 ---
     - add `--target-contrast`
     - Target luminance value is now also applied when ICC profile is used.

DOCS/man/options.rst

@@ -2621,7 +2621,7 @@ Subtitles
     subtitles (if the difference is smaller than 210 ms, the gap or overlap
     is removed).
 
-``--sub-forced-only=<yes|no>``
+``--sub-forced-events-only=<yes|no>``
     Enabling this displays only forced events within subtitle streams. Only
     some bitmap subtitle formats (such as DVD or PGS) are capable of having a
     mixture of forced and unforced events within the stream. Enabling this on

DOCS/mplayer-changes.rst

@@ -229,7 +229,7 @@ Command Line Switches
     ``-endpos``                 ``--length``
     ``-fixed-vo``               (removed; always the default)
     ``-font``                   ``--osd-font``
-    ``-forcedsubsonly``         ``--sub-forced-only``
+    ``-forcedsubsonly``         ``--sub-forced-events-only``
     ``-forceidx``               ``--index``
     ``-format``                 ``--audio-format``
     ``-fsmode-dontuse``         (removed)

etc/input.conf

@@ -177,5 +177,5 @@
 # (not an exhaustive list of unbound commands)
 #
 
-# ? cycle sub-forced-only               # toggle DVD forced subs
+# ? cycle sub-forced-events-only        # display only DVD/PGS forced subtitle events
 # ? stop                                # stop playback (quit or enter idle mode)

etc/restore-old-bindings.conf

@@ -53,7 +53,7 @@ LEFT  seek -10
 - add audio-delay -0.100
 ( add balance -0.1
 ) add balance 0.1
-F cycle sub-forced-only
+F cycle sub-forced-events-only
 TAB cycle program
 A cycle angle
 U stop

options/options.c

@@ -262,7 +262,7 @@ const struct m_sub_options mp_subtitle_sub_opts = {
         {"sub-speed", OPT_FLOAT(sub_speed)},
         {"sub-visibility", OPT_BOOL(sub_visibility)},
         {"secondary-sub-visibility", OPT_BOOL(sec_sub_visibility)},
-        {"sub-forced-only", OPT_BOOL(forced_subs_only)},
+        {"sub-forced-events-only", OPT_BOOL(sub_forced_events_only)},
         {"stretch-dvd-subs", OPT_BOOL(stretch_dvd_subs)},
         {"stretch-image-subs-to-screen", OPT_BOOL(stretch_image_subs)},
         {"image-subs-video-resolution", OPT_BOOL(image_subs_video_res)},
@@ -879,6 +879,7 @@ static const m_option_t mp_opts[] = {
     {"dvdangle", OPT_REPLACED("dvd-angle")},
     {"endpos", OPT_REPLACED("length")},
     {"font", OPT_REPLACED("osd-font")},
+    {"sub-forced-only", OPT_REPLACED("sub-forced-events-only")},
     {"forcedsubsonly", OPT_REPLACED("sub-forced-only")},
     {"format", OPT_REPLACED("audio-format")},
     {"hardframedrop", OPT_REMOVED(NULL)},

options/options.h

@@ -83,7 +83,7 @@ struct mp_subtitle_opts {
     float sub_delay;
     float sub_fps;
     float sub_speed;
-    bool forced_subs_only;
+    bool sub_forced_events_only;
     bool stretch_dvd_subs;
     bool stretch_image_subs;
     bool image_subs_video_res;

player/command.c

@@ -3013,7 +3013,7 @@ static int mp_property_sub_forced_only_cur(void *ctx, struct m_property *prop,
                                            int action, void *arg)
 {
     MPContext *mpctx = ctx;
-    int ret = mpctx->opts->subs_rend->forced_subs_only;
+    int ret = mpctx->opts->subs_rend->sub_forced_events_only;
     return m_property_bool_ro(action, arg, ret);
 }
 
@@ -4296,7 +4296,7 @@ static const struct property_osd_display {
     {"secondary-sub-visibility",
      .msg = "Secondary Subtitles ${!secondary-sub-visibility==yes:hidden}"
       "${?secondary-sub-visibility==yes:visible${?secondary-sid==no: (but no secondary subtitles selected)}}"},
-    {"sub-forced-only", "Forced sub only"},
+    {"sub-forced-events-only", "Forced sub only"},
     {"sub-scale", "Sub Scale"},
     {"sub-ass-vsfilter-aspect-compat", "Subtitle VSFilter aspect compat"},
     {"sub-ass-override", "ASS subtitle style override"},

player/loadfile.c

@@ -260,7 +260,7 @@ static void print_stream(struct MPContext *mpctx, struct track *t)
     char b[2048] = {0};
     bool forced_only = false;
     if (t->type == STREAM_SUB) {
-        bool forced_opt = mpctx->opts->subs_rend->forced_subs_only;
+        bool forced_opt = mpctx->opts->subs_rend->sub_forced_events_only;
         if (forced_opt)
             forced_only = t->selected;
     }

sub/sd_ass.c

@@ -577,7 +577,7 @@ static struct sub_bitmaps *get_bitmaps(struct sd *sd, struct mp_osd_res dim,
     // Currently no supported text sub formats support a distinction between forced
     // and unforced lines, so we just assume everything's unforced and discard everything.
     // If we ever see a format that makes this distinction, we can add support here.
-    if (opts->forced_subs_only)
+    if (opts->sub_forced_events_only)
         goto done;
 
     double scale = dim.display_par;

sub/sd_lavc.c

@@ -195,7 +195,7 @@ static void read_sub_bitmaps(struct sd *sd, struct sub *sub)
             MP_ERR(sd, "unsupported subtitle type from libavcodec\n");
             continue;
         }
-        if (!(r->flags & AV_SUBTITLE_FLAG_FORCED) && opts->forced_subs_only)
+        if (!(r->flags & AV_SUBTITLE_FLAG_FORCED) && opts->sub_forced_events_only)
             continue;
         if (r->w <= 0 || r->h <= 0)
             continue;