[FFmpeg-cvslog] doc/ffmpeg: improve -disposition, -stats, and -progress documentation

[Soma Lucz]

ffmpeg | branch: master | Soma Lucz <luczsoma at gmail.com> | Thu Oct 17 20:53:36 2024 +0200| [153a6dc8faafc4de263a493484ffc1dc2b5b26b2] | committer: Anton Khirnov

doc/ffmpeg: improve -disposition, -stats, and -progress documentation

-disposition:
Clarify the meaning of the default value, and how the '+' and '-'
prefixes work. Add more examples.

-stats:
Clarify that it appears as an "info"-level log.

-progress:
Add info about the "progress" key's value being "continue" or "end".
Add an example of logging to stdout.

Signed-off-by: Soma Lucz <luczsoma at gmail.com>
Signed-off-by: Anton Khirnov <anton at khirnov.net>

> http://git.videolan.org/gitweb.cgi/ffmpeg.git/?a=commit;h=153a6dc8faafc4de263a493484ffc1dc2b5b26b2
---

 doc/ffmpeg.texi | 58 +++++++++++++++++++++++++++++++++++++++++++--------------
 1 file changed, 44 insertions(+), 14 deletions(-)

diff --git a/doc/ffmpeg.texi b/doc/ffmpeg.texi
index d11fe7c8f4..e4aa03a734 100644
--- a/doc/ffmpeg.texi
+++ b/doc/ffmpeg.texi
@@ -921,24 +921,25 @@ ffmpeg -i INPUT -metadata:s:a:0 language=eng OUTPUT
 @end example
 
 @item -disposition[:stream_specifier] @var{value} (@emph{output,per-stream})
-Sets the disposition for a stream.
+Sets the disposition flags for a stream.
 
-By default, the disposition is copied from the input stream, unless the output
-stream this option applies to is fed by a complex filtergraph - in that case the
-disposition is unset by default.
+Default value: by default, all disposition flags are copied from the input stream,
+unless the output stream this option applies to is fed by a complex filtergraph
+- in that case no disposition flags are set by default.
 
- at var{value} is a sequence of items separated by '+' or '-'. The first item may
-also be prefixed with '+' or '-', in which case this option modifies the default
-value. Otherwise (the first item is not prefixed) this options overrides the
-default value. A '+' prefix adds the given disposition, '-' removes it. It is
-also possible to clear the disposition by setting it to 0.
+ at var{value} is a sequence of disposition flags separated by '+' or '-'. A '+'
+prefix adds the given disposition, '-' removes it. If the first flag is also
+prefixed with '+' or '-', the resulting disposition is the default value
+updated by @var{value}. If the first flag is not prefixed, the resulting
+disposition is @var{value}. It is also possible to clear the disposition by
+setting it to 0.
 
 If no @code{-disposition} options were specified for an output file, ffmpeg will
-automatically set the 'default' disposition on the first stream of each type,
+automatically set the 'default' disposition flag on the first stream of each type,
 when there are multiple streams of this type in the output file and no stream of
 that type is already marked as default.
 
-The @code{-dispositions} option lists the known dispositions.
+The @code{-dispositions} option lists the known disposition flags.
 
 For example, to make the second audio stream the default stream:
 @example
@@ -956,6 +957,29 @@ To add an embedded cover/thumbnail:
 ffmpeg -i in.mp4 -i IMAGE -map 0 -map 1 -c copy -c:v:1 png -disposition:v:1 attached_pic out.mp4
 @end example
 
+To add the 'original' and remove the 'comment' disposition flag from the first
+audio stream without removing its other disposition flags:
+ at example
+ffmpeg -i in.mkv -c copy -disposition:a:0 +original-comment out.mkv
+ at end example
+
+To remove the 'original' and add the 'comment' disposition flag to the first
+audio stream without removing its other disposition flags:
+ at example
+ffmpeg -i in.mkv -c copy -disposition:a:0 -original+comment out.mkv
+ at end example
+
+To set only the 'original' and 'comment' disposition flags on the first audio
+stream (and remove its other disposition flags):
+ at example
+ffmpeg -i in.mkv -c copy -disposition:a:0 original+comment out.mkv
+ at end example
+
+To remove all disposition flags from the first audio stream:
+ at example
+ffmpeg -i in.mkv -c copy -disposition:a:0 0 out.mkv
+ at end example
+
 Not all muxers support embedded thumbnails, and those who do, only support a few formats, like JPEG or PNG.
 
 @item -program [title=@var{title}:][program_num=@var{program_num}:]st=@var{stream}[:st=@var{stream}...] (@emph{output})
@@ -1358,8 +1382,8 @@ The default is the number of available CPUs.
 Specify the preset for matching stream(s).
 
 @item -stats (@emph{global})
-Print encoding progress/statistics. It is on by default, to explicitly
-disable it you need to specify @code{-nostats}.
+Log encoding progress/statistics as "info"-level log (see @code{-loglevel}).
+It is on by default, to explicitly disable it you need to specify @code{-nostats}.
 
 @item -stats_period @var{time} (@emph{global})
 Set period at which encoding progress/statistics are updated. Default is 0.5 seconds.
@@ -1370,10 +1394,16 @@ Send program-friendly progress information to @var{url}.
 Progress information is written periodically and at the end of
 the encoding process. It is made of "@var{key}=@var{value}" lines. @var{key}
 consists of only alphanumeric characters. The last key of a sequence of
-progress information is always "progress".
+progress information is always "progress" with the value "continue" or "end".
 
 The update period is set using @code{-stats_period}.
 
+For example, log progress information to stdout:
+
+ at example
+ffmpeg -progress pipe:1 -i in.mkv out.mkv
+ at end example
+
 @anchor{stdin option}
 @item -stdin
 Enable interaction on standard input. On by default unless standard input is