player: redo how stream caching and pausing on low cache works

Add the --cache-secs option, which literally overrides the value of
--demuxer-readahead-secs if the stream cache is active. The default
value is very high (10 seconds), which means it can act as network
cache.

Remove the old behavior of trying to pause once the byte cache runs
low. Instead, do something similar wit the demuxer cache. The nice
thing is that we can guess how many seconds of video it has cached,
and we can make better decisions. But for now, apply a relatively
naive heuristic: if the cache is below 0.5 secs, pause, and wait
until at least 2 secs are available.

Note that due to timestamp reordering, the estimated cached duration
of video might be inaccurate, depending on the file format. If the
file format has DTS, it's easy, otherwise the duration will seemingly
jump back and forth.

1 files changed, 9 insertions, 14 deletions

diff --git a/DOCS/man/options.rst b/DOCS/man/options.rst
index caa2dbbb28..65e7673a1f 100644
--- a/DOCS/man/options.rst
+++ b/DOCS/man/options.rst
@@ -2751,20 +2751,6 @@ Cache
     will not automatically enable the cache e.g. when playing from a network
     stream. Note that using ``--cache`` will always override this option.
 
-``--cache-pause-below=<kBytes|no>``
-    If the cache size goes below the specified value (in KB), pause and wait
-    until the size set by ``--cache-pause-restart`` is reached, then  resume
-    playback (default: 50). If ``no`` is specified, this behavior is disabled.
-
-    When the player is paused this way, the status line shows ``Buffering``
-    instead of ``Paused``, and the OSD uses a clock symbol instead of the
-    normal paused symbol.
-
-``--cache-pause-restart=<kBytes>``
-    If the cache is paused due to the ``--cache-pause-below`` functionality,
-    then the player unpauses as soon as the cache has this much data (in KB).
-    (Default: 100)
-
 ``--cache-initial=<kBytes>``
     Playback will start when the cache has been filled up with this many
     kilobytes of data (default: 0).
@@ -2809,6 +2795,15 @@ Cache
 ``--no-cache``
     Turn off input stream caching. See ``--cache``.
 
+``--cache-secs=<seconds>``
+    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. (Default: 10.)
+
+``--cache-pause``, ``--no-cache-pause``
+    Whether the player should automatically pause when the cache runs low,
+    and unpause once more data is available ("buffering").
+
 
 Network
 -------