summaryrefslogtreecommitdiffstats
path: root/DOCS
diff options
context:
space:
mode:
authorwm4 <wm4@nowhere>2019-07-07 20:38:22 +0200
committerwm4 <wm4@nowhere>2019-09-19 20:37:05 +0200
commit023b5964b047d83772163195c322936968e7d47a (patch)
tree8236e49d39e364bab04439aded260603bb566b31 /DOCS
parent226e050b83b1c9946c52ae77b78a63e82a3ae628 (diff)
downloadmpv-023b5964b047d83772163195c322936968e7d47a.tar.bz2
mpv-023b5964b047d83772163195c322936968e7d47a.tar.xz
demux, command: add a third stream recording mechanism
That's right, and it's probably not the end of it. I'll just claim that I have no idea how to create a proper user interface for this, so I'm creating multiple partially-orthogonal, of which some may work better in each of its special use cases. Until now, there was --record-file. You get relatively good control about what is muxed, and it can use the cache. But it sucks that it's bound to playback. If you pause while it's set, muxing stops. If you seek while it's set, the output will be sort-of trashed, and that's by design. Then --stream-record was added. This is a bit better (especially for live streams), but you can't really control well when muxing stops or ends. In particular, it can't use the cache (it just dumps whatever the underlying demuxer returns). Today, the idea is that the user should just be able to select a time range to dump to a file, and it should not affected by the user seeking around in the cache. In addition, the stream may still be running, so there's some need to continue dumping, even if it's redundant to --stream-record. One notable thing is that it uses the async command shit. Not sure whether this is a good idea. Maybe not, but whatever. Also, a user can always use the "async" prefix to pretend it doesn't. Much of this was barely tested (especially the reinterleaving crap), let's just hope it mostly works. I'm sure you can tolerate the one or other crash?
Diffstat (limited to 'DOCS')
-rw-r--r--DOCS/man/input.rst57
-rw-r--r--DOCS/man/options.rst6
2 files changed, 58 insertions, 5 deletions
diff --git a/DOCS/man/input.rst b/DOCS/man/input.rst
index 4944c878ff..7c40a5cd43 100644
--- a/DOCS/man/input.rst
+++ b/DOCS/man/input.rst
@@ -920,6 +920,60 @@ Input Commands that are Possibly Subject to Change
equivalent is ``--glsl-shaders-append=file.glsl`` or alternatively
``--glsl-shader=file.glsl``.
+``dump-cache <start> <end> <filename>``
+ Dump the current cache to the given filename. The ``<filename>`` file is
+ overwritten if it already exists. ``<start>`` and ``<end>`` give the
+ time range of what to dump. If no data is cached at the given time range,
+ nothing may be dumped (creating a file with no packets).
+
+ Dumping a larger part of the cache will freeze the player. No effort was
+ made to fix this, as this feature was meant mostly for creating small
+ excerpts.
+
+ If ``<filename>`` is an empty string, an ongoing ``dump-cache`` is stopped.
+
+ If ``<end>`` is ``no``, then continuous dumping is enabled. Then, after
+ dumping the existing parts of the cache, anything read from network is
+ appended to the cache as well. This behaves similar to ``--stream-record``
+ (although it does not conflict with that option, and they can be both active
+ at the same time).
+
+ If the ``<end>`` time is after the cache, the command will _not_ wait and
+ write newly received data to it.
+
+ The end of the resulting file may be slightly damaged or incomplete at the
+ end. (Not enough effort was made to ensure that the end lines up properly.)
+
+ Note that this command will finish only once dumping ends. That means it
+ works similar to the ``screenshot`` command, just that it can block much
+ longer. If continuous dumping is used, the command will not finish until
+ playback is stopped, an error happens, another ``dump-cache`` command is
+ run, or an API like ``mp.abort_async_command`` was called to explicitly stop
+ the command. See `Synchronous vs. Asynchronous`_.
+
+ .. note::
+
+ This was mostly created for network streams. For local files, there may
+ be much better methods to create excerpts and such. There are tons of
+ much more user-friendly Lua scripts, that will reencode parts of a file
+ by spawning a separate instance of ``ffmpeg``. With network streams,
+ this is not that easily possible, as the stream would have to be
+ downloaded again. Even if ``--stream-record`` is used to record the
+ stream to the local filesystem, there may be problems, because the
+ recorded file is still written to.
+
+ This command is experimental, and all details about it may change in the
+ future.
+
+``ab-loop-dump-cache <filename>``
+ Essentially calls ``dump-cache`` with the current AB-loop points as
+ arguments. Like ``dump-cache``, this will overwrite the file at
+ ``<filename>``. Likewise, if the B point is set to ``no``, it will enter
+ continuous dumping after the existing cache was dumped.
+
+ The author reserves the right to remove this command if enough motivation
+ is found to move this functionality to a trivial Lua script.
+
Undocumented commands: ``ao-reload`` (experimental/internal).
@@ -1087,7 +1141,8 @@ default now, and ``async`` changes behavior only in the ways mentioned above.
Currently the following commands have different waiting characteristics with
sync vs. async: sub-add, audio-add, sub-reload, audio-reload,
-rescan-external-files, screenshot, screenshot-to-file.
+rescan-external-files, screenshot, screenshot-to-file, dump-cache,
+ab-loop-dump-cache.
Input Sections
--------------
diff --git a/DOCS/man/options.rst b/DOCS/man/options.rst
index ea47fc79b0..b590526f3e 100644
--- a/DOCS/man/options.rst
+++ b/DOCS/man/options.rst
@@ -5880,10 +5880,8 @@ Miscellaneous
If this is set at runtime, the old file is closed, and the new file is
opened. Note that this will write only data that is appended at the end of
- the cache, and the already cached data cannot be written. (A fix for that
- would be a command that dumps the cache using a given time range, possibly
- with the option to be open-ended, which would continue to write data
- appended to the cache. Such a command doesn't exist yet.)
+ the cache, and the already cached data cannot be written. You can try the
+ ``dump-cache`` command as an alternative.
``--lavfi-complex=<string>``
Set a "complex" libavfilter filter, which means a single filter graph can