summaryrefslogtreecommitdiffstats
path: root/DOCS/man/options.rst
diff options
context:
space:
mode:
authorwm4 <wm4@nowhere>2019-06-13 19:10:32 +0200
committerwm4 <wm4@nowhere>2019-09-19 20:37:05 +0200
commit17da9071a4a524139e2ef945ed6cde17dd08c99c (patch)
tree66201f387ae33c5f6dbdb283d62066177b0cedf3 /DOCS/man/options.rst
parentef507ad50a0933581f39a0bb86dd85fce9d8f7bc (diff)
downloadmpv-17da9071a4a524139e2ef945ed6cde17dd08c99c.tar.bz2
mpv-17da9071a4a524139e2ef945ed6cde17dd08c99c.tar.xz
demux: add a on-disk cache
Somewhat similar to the old --cache-file, except for the demuxer cache. Instead of keeping packet data in memory, it's written to disk and read back when needed. The idea is to reduce main memory usage, while allowing fast seeking in large cached network streams (especially live streams). Keeping the packet metadata on disk would be rather hard (would use mmap or so, or rewrite the entire demux.c packet queue handling), and since it's relatively small, just keep it in memory. Also for simplicity, the disk cache is append-only. If you're watching really long livestreams, and need pruning, you're probably out of luck. This still could be improved by trying to free unused blocks with fallocate(), but since we're writing multiple streams in an interleaved manner, this is slightly hard. Some rather gross ugliness in packet.h: we want to store the file position of the cached data somewhere, but on 32 bit architectures, we don't have any usable 64 bit members for this, just the buf/len fields, which add up to 64 bit - so the shitty union aliases this memory. Error paths untested. Side data (the complicated part of trying to serialize ffmpeg packets) untested. Stream recording had to be adjusted. Some minor details change due to this, but probably nothing important. The change in attempt_range_joining() is because packets in cache have no valid len field. It was a useful check (heuristically finding broken cases), but not a necessary one. Various other approaches were tried. It would be interesting to list them and to mention the pros and cons, but I don't feel like it.
Diffstat (limited to 'DOCS/man/options.rst')
-rw-r--r--DOCS/man/options.rst46
1 files changed, 46 insertions, 0 deletions
diff --git a/DOCS/man/options.rst b/DOCS/man/options.rst
index ba9bac7e63..c70b26aa2c 100644
--- a/DOCS/man/options.rst
+++ b/DOCS/man/options.rst
@@ -3958,6 +3958,33 @@ Cache
very high, so the actually achieved readahead will usually be limited by
the value of the ``--demuxer-max-bytes`` option.
+``--cache-on-disk=<yes|no>``
+ Write packet data to a temporary file, instead of keeping them in memory.
+ This makes sense only with ``--cache``. If the normal cache is disabled,
+ this option is ignored.
+
+ You need to set ``--cache-dir`` to use this.
+
+ The cache file is append-only. Even if the player appears to prune data, the
+ file space freed by it is not reused. The cache file is deleted when
+ playback is closed.
+
+ Note that packet metadata is still kept in memory. ``--demuxer-max-bytes``
+ and related options are applied to metadata *only*. The size of this
+ metadata varies, but 50 MB per hour of media is typical. The cache
+ statistics will report this metadats size, instead of the size of the cache
+ file. If the metadata hits the size limits, the metadata is pruned (but not
+ the cache file).
+
+ When the media is closed, the cache file is deleted. A cache file is
+ generally worthless after the media is closed, and it's hard to retrieve
+ any media data from it (it's not supported by design).
+
+``--cache-dir=<path>``
+ Directory where to create temporary files (default: none).
+
+ Currently, this is used for ``--cache-on-disk`` only.
+
``--cache-pause=<yes|no>``
Whether the player should automatically pause when the cache runs out of
data and stalls decoding/playback (default: yes). If enabled, it will
@@ -3986,6 +4013,25 @@ Cache
This option also triggers when playback is restarted after seeking.
+``--cache-unlink-files=<immediate|whendone|no>``
+ Whether or when to unlink cache files (default: immediate). This affects
+ cache files which are inherently temporary, and which make no sense to
+ remain on disk after the player terminates. This is a debugging option.
+
+ ``immediate``
+ Unlink cache file after they were created. The cache files won't be
+ visible anymore, even though they're in use. This ensures they are
+ guaranteed to be removed from disk when the player terminates, even if
+ it crashes.
+
+ ``whendone``
+ Delete cache files after they are closed.
+
+ ``no``
+ Don't delete cache files. They will consume disk space without having a
+ use.
+
+ Currently, this is used for ``--cache-on-disk`` only.
Network
-------