History

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.

Soma Lucz committed 2 years ago

Commit 153a6dc1 parent ae0ab5b1 file · +44 −14Browse files

Unified · Split

doc/ffmpeg.texi+44−14
@@ -921,24 +921,25 @@ ffmpeg -i INPUT -metadata:s:a:0 language=eng OUTPUT · 920 unmodified lines
921921 @end example
922922
923923 @item -disposition[:stream_specifier] @var{value} (@emph{output,per-stream})
924−Sets the disposition for a stream.
924+Sets the disposition flags for a stream.
925925
926−By default, the disposition is copied from the input stream, unless the output
927−stream this option applies to is fed by a complex filtergraph - in that case the
928−disposition is unset by default.
926+Default value: by default, all disposition flags are copied from the input stream,
927+unless the output stream this option applies to is fed by a complex filtergraph
928+- in that case no disposition flags are set by default.
929929
930−@var{value} is a sequence of items separated by '+' or '-'. The first item may
931−also be prefixed with '+' or '-', in which case this option modifies the default
932−value. Otherwise (the first item is not prefixed) this options overrides the
933−default value. A '+' prefix adds the given disposition, '-' removes it. It is
934−also possible to clear the disposition by setting it to 0.
930+@var{value} is a sequence of disposition flags separated by '+' or '-'. A '+'
931+prefix adds the given disposition, '-' removes it. If the first flag is also
932+prefixed with '+' or '-', the resulting disposition is the default value
933+updated by @var{value}. If the first flag is not prefixed, the resulting
934+disposition is @var{value}. It is also possible to clear the disposition by
935+setting it to 0.
935936
936937 If no @code{-disposition} options were specified for an output file, ffmpeg will
937−automatically set the 'default' disposition on the first stream of each type,
938+automatically set the 'default' disposition flag on the first stream of each type,
938939 when there are multiple streams of this type in the output file and no stream of
939940 that type is already marked as default.
940941
941−The @code{-dispositions} option lists the known dispositions.
942+The @code{-dispositions} option lists the known disposition flags.
942943
943944 For example, to make the second audio stream the default stream:
944945 @example
@@ -956,6 +957,29 @@ To add an embedded cover/thumbnail: · 11 unmodified lines
956957 ffmpeg -i in.mp4 -i IMAGE -map 0 -map 1 -c copy -c:v:1 png -disposition:v:1 attached_pic out.mp4
957958 @end example
958959
960+To add the 'original' and remove the 'comment' disposition flag from the first
961+audio stream without removing its other disposition flags:
962+@example
963+ffmpeg -i in.mkv -c copy -disposition:a:0 +original-comment out.mkv
964+@end example
965+
966+To remove the 'original' and add the 'comment' disposition flag to the first
967+audio stream without removing its other disposition flags:
968+@example
969+ffmpeg -i in.mkv -c copy -disposition:a:0 -original+comment out.mkv
970+@end example
971+
972+To set only the 'original' and 'comment' disposition flags on the first audio
973+stream (and remove its other disposition flags):
974+@example
975+ffmpeg -i in.mkv -c copy -disposition:a:0 original+comment out.mkv
976+@end example
977+
978+To remove all disposition flags from the first audio stream:
979+@example
980+ffmpeg -i in.mkv -c copy -disposition:a:0 0 out.mkv
981+@end example
982+
959983 Not all muxers support embedded thumbnails, and those who do, only support a few formats, like JPEG or PNG.
960984
961985 @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. · 396 unmodified lines
13581382 Specify the preset for matching stream(s).
13591383
13601384 @item -stats (@emph{global})
1361−Print encoding progress/statistics. It is on by default, to explicitly
1362−disable it you need to specify @code{-nostats}.
1385+Log encoding progress/statistics as "info"-level log (see @code{-loglevel}).
1386+It is on by default, to explicitly disable it you need to specify @code{-nostats}.
13631387
13641388 @item -stats_period @var{time} (@emph{global})
13651389 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}. · 4 unmodified lines
13701394 Progress information is written periodically and at the end of
13711395 the encoding process. It is made of "@var{key}=@var{value}" lines. @var{key}
13721396 consists of only alphanumeric characters. The last key of a sequence of
1373−progress information is always "progress".
1397+progress information is always "progress" with the value "continue" or "end".
13741398
13751399 The update period is set using @code{-stats_period}.
13761400
1401+For example, log progress information to stdout:
1402+
1403+@example
1404+ffmpeg -progress pipe:1 -i in.mkv out.mkv
1405+@end example
1406+
13771407 @anchor{stdin option}
13781408 @item -stdin
13791409 Enable interaction on standard input. On by default unless standard input is

Keyboard shortcuts

General

Show keyboard shortcuts
?
Focus the current search
/

Issues and pull requests

Open filters
f

Issues, pull requests and Inbox

Select next item
j↓
Select previous item
k↑
Open selected item
Enter
Dismiss filters or clear selection
Esc

Repository code

Go to file
t