options: rename --fps to --container-fps-override

This better reflects what it actually does. As a bonus, script writers
won't be misled into thinking that fps displays the actual video or
display fps.

DOCS/interface-changes.rst

@@ -101,6 +101,7 @@ Interface changes
     - change `video-codec` to show description or name, not both
     - deprecate `--cdda-toc-bias` option, offsets are always checked now
     - disable `--allow-delayed-peak-detect` by default
+    - rename `--fps` to `--container-fps-override`
  --- mpv 0.36.0 ---
     - add `--target-contrast`
     - Target luminance value is now also applied when ICC profile is used.

DOCS/man/mpv.rst

@@ -1094,7 +1094,8 @@ this with ``--untimed``, but it will likely break, unless the stream has no
 audio, and the input feeds data to the player at a constant rate.
 
 Another common problem is with MJPEG streams. These do not signal the correct
-framerate. Using ``--untimed`` or ``--no-correct-pts --fps=60`` might help.
+framerate. Using ``--untimed`` or ``--no-correct-pts --container-fps-override=60``
+might help.
 
 For livestreams, data can build up due to pausing the stream, due to slightly
 lower playback rate, or "buffering" pauses. If the demuxer cache is enabled,

DOCS/man/options.rst

@@ -1625,13 +1625,13 @@ Video
 
 ``--correct-pts``, ``--no-correct-pts``
     ``--no-correct-pts`` switches mpv to a mode where video timing is
-    determined using a fixed framerate value (either using the ``--fps``
-    option, or using file information). Sometimes, files with very broken
-    timestamps can be played somewhat well in this mode. Note that video
-    filters, subtitle rendering, seeking (including hr-seeks and backstepping),
-    and audio synchronization can be completely broken in this mode.
+    determined using a fixed framerate value (either using the
+    ``--container-fps-override`` option, or using file information). Sometimes,
+    files with very broken timestamps can be played somewhat well in this mode.
+    Note that video filters, subtitle rendering, seeking (including hr-seeks and
+    backstepping), and audio synchronization can be completely broken in this mode.
 
-``--fps=<float>``
+``--container-fps-override=<float>``
     Override video framerate. Useful if the original value is wrong or missing.
 
     .. note::

DOCS/man/vf.rst

@@ -574,7 +574,7 @@ Available mpv-only filters are:
         completely broken (e.g. 0 or NaN). Even if the value is correct,
         if another filter changes the real FPS (by dropping or inserting
         frames), the value of this variable will not be useful. Note that
-        the ``--fps`` command line option overrides this value.
+        the ``--container-fps-override`` command line option overrides this value.
 
         Useful for some filters which insist on having a FPS.
 

demux/demux_lavf.c

@@ -1174,7 +1174,7 @@ static int demux_open_lavf(demuxer_t *demuxer, enum demux_check check)
                 "This format is marked by FFmpeg as having no timestamps!\n"
                 "FFmpeg will likely make up its own broken timestamps. For\n"
                 "video streams you can correct this with:\n"
-                "    --no-correct-pts --fps=VALUE\n"
+                "    --no-correct-pts --container-fps-override=VALUE\n"
                 "with VALUE being the real framerate of the stream. You can\n"
                 "expect seeking and buffering estimation to be generally\n"
                 "broken as well.\n");

filters/f_decoder_wrapper.c

@@ -95,7 +95,7 @@ static const struct m_sub_options adec_queue_conf = {
 struct dec_wrapper_opts {
     double movie_aspect;
     int aspect_method;
-    double force_fps;
+    double fps_override;
     bool correct_pts;
     int video_rotate;
     char *audio_decoders;
@@ -113,7 +113,7 @@ static int decoder_list_help(struct mp_log *log, const m_option_t *opt,
 const struct m_sub_options dec_wrapper_conf = {
     .opts = (const struct m_option[]){
         {"correct-pts", OPT_BOOL(correct_pts)},
-        {"fps", OPT_DOUBLE(force_fps), M_RANGE(0, DBL_MAX)},
+        {"container-fps-override", OPT_DOUBLE(fps_override), M_RANGE(0, DBL_MAX)},
         {"ad", OPT_STRING(audio_decoders),
             .help = decoder_list_help},
         {"vd", OPT_STRING(video_decoders),
@@ -132,7 +132,8 @@ const struct m_sub_options dec_wrapper_conf = {
         {"video-reversal-buffer", OPT_BYTE_SIZE(video_reverse_size),
             M_RANGE(0, M_MAX_MEM_BYTES)},
         {"audio-reversal-buffer", OPT_BYTE_SIZE(audio_reverse_size),
-            M_RANGE(0, M_MAX_MEM_BYTES)} ,
+            M_RANGE(0, M_MAX_MEM_BYTES)},
+        {"fps", OPT_REPLACED("container-fps-override")},
         {0}
     },
     .size = sizeof(struct dec_wrapper_opts),
@@ -1208,9 +1209,9 @@ struct mp_decoder_wrapper *mp_decoder_wrapper_create(struct mp_filter *parent,
 
         MP_VERBOSE(p, "Container reported FPS: %f\n", p->fps);
 
-        if (p->opts->force_fps) {
-            p->fps = p->opts->force_fps;
-            MP_INFO(p, "FPS forced to %5.3f.\n", p->fps);
+        if (p->opts->fps_override) {
+            p->fps = p->opts->fps_override;
+            MP_INFO(p, "Container FPS forced to %5.3f.\n", p->fps);
             MP_INFO(p, "Use --no-correct-pts to force FPS based timing.\n");
         }