demux: deprecate --cache-secs

Because it's confusing and useless. If nobody complains, we'll have one
weird cache configuration option less.

3 files changed, 17 insertions, 3 deletions

diff --git a/DOCS/interface-changes.rst b/DOCS/interface-changes.rst
index 857697bc4c..991ba6aca3 100644
--- a/DOCS/interface-changes.rst
+++ b/DOCS/interface-changes.rst
@@ -33,6 +33,8 @@ Interface changes
     - js modules: ~~/scripts/modules.js/ is no longer used, global paths can be
       set with custom init (see docs), dir-scripts first look at <dir>/modules/
     - the OSX bundle now logs to "~/Library/Logs/mpv.log" by default
+    - deprecate the --cache-secs option (once removed, the cache cannot be
+      limited by time anymore)
  --- mpv 0.32.0 ---
     - change behavior when using legacy option syntax with options that start
       with two dashes (``--`` instead of a ``-``). Now, using the recommended
diff --git a/DOCS/man/options.rst b/DOCS/man/options.rst
index 110fe7420d..09e06aa674 100644
--- a/DOCS/man/options.rst
+++ b/DOCS/man/options.rst
@@ -3578,8 +3578,13 @@ Demuxer
     a timestamp difference higher than the readahead amount relative to the
     last packet returned to the decoder, the demuxer keeps reading.
 
-    Note that the ``--cache-secs`` option will override this value if a cache
-    is enabled, and the value is larger.
+    Note that enabling the cache (such as ``--cache=yes``, or if the input
+    is considered a network stream, and ``--cache=auto`` is used), this option
+    is mostly ignored. (``--cache-secs`` will override this. Technically, the
+    maximum of both options is used.)
+
+    The main purpose of this option is to limit the readhead for local playback,
+    since a large readahead value is not overly useful in this case.
 
     (This value tends to be fuzzy, because many file formats don't store linear
     timestamps.)
@@ -4393,6 +4398,12 @@ Cache
     Turn off input stream caching. See ``--cache``.
 
 ``--cache-secs=<seconds>``
+    Deprecated. Once this option is removed, there will be no way to limit the
+    cache size by time (only by size with ``--demuxer-max-bytes``). This option
+    is considered useless, since there is no good reason to limit the cache by
+    time, and the default value of this ption is already something very high.
+    The interactions with the other cache options is also confusing.
+
     How many seconds of audio/video to prefetch if the cache is active. This
     overrides the ``--demuxer-readahead-secs`` option if and only if the cache
     is enabled and the value is larger. The default value is set to something
diff --git a/demux/demux.c b/demux/demux.c
index 86267695d0..98ad31dbe0 100644
--- a/demux/demux.c
+++ b/demux/demux.c
@@ -121,7 +121,8 @@ const struct m_sub_options demux_conf = {
         OPT_BYTE_SIZE("demuxer-max-back-bytes", max_bytes_bw, 0, 0, MAX_BYTES),
         OPT_FLAG("demuxer-donate-buffer", donate_fw, 0),
         OPT_FLAG("force-seekable", force_seekable, 0),
-        OPT_DOUBLE("cache-secs", min_secs_cache, M_OPT_MIN, .min = 0),
+        OPT_DOUBLE("cache-secs", min_secs_cache, M_OPT_MIN, .min = 0,
+                   .deprecation_message = "will use unlimited time"),
         OPT_FLAG("access-references", access_references, 0),
         OPT_CHOICE("demuxer-seekable-cache", seekable_cache, 0,
                    ({"auto", -1}, {"no", 0}, {"yes", 1})),