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
921@end example921@end example
922 922
923@item -disposition[:stream_specifier] @var{value} (@emph{output,per-stream})923@item -disposition[:stream_specifier] @var{value} (@emph{output,per-stream})
924Sets the disposition for a stream.924Sets the disposition flags for a stream.
925 925
926By default, the disposition is copied from the input stream, unless the output926Default value: by default, all disposition flags are copied from the input stream,
927stream this option applies to is fed by a complex filtergraph - in that case the927unless the output stream this option applies to is fed by a complex filtergraph
928disposition is unset by default.928- in that case no disposition flags are set by default.
929 929
930@var{value} is a sequence of items separated by '+' or '-'. The first item may930@var{value} is a sequence of disposition flags separated by '+' or '-'. A '+'
931also be prefixed with '+' or '-', in which case this option modifies the default931prefix adds the given disposition, '-' removes it. If the first flag is also
932value. Otherwise (the first item is not prefixed) this options overrides the932prefixed with '+' or '-', the resulting disposition is the default value
933default value. A '+' prefix adds the given disposition, '-' removes it. It is933updated by @var{value}. If the first flag is not prefixed, the resulting
934also possible to clear the disposition by setting it to 0.934disposition is @var{value}. It is also possible to clear the disposition by
935setting it to 0.
935 936
936If no @code{-disposition} options were specified for an output file, ffmpeg will937If no @code{-disposition} options were specified for an output file, ffmpeg will
937automatically set the 'default' disposition on the first stream of each type,938automatically set the 'default' disposition flag on the first stream of each type,
938when there are multiple streams of this type in the output file and no stream of939when there are multiple streams of this type in the output file and no stream of
939that type is already marked as default.940that type is already marked as default.
940 941
941The @code{-dispositions} option lists the known dispositions.942The @code{-dispositions} option lists the known disposition flags.
942 943
943For example, to make the second audio stream the default stream:944For example, to make the second audio stream the default stream:
944@example945@example
@@ -956,6 +957,29 @@ To add an embedded cover/thumbnail: · 11 unmodified lines
956ffmpeg -i in.mp4 -i IMAGE -map 0 -map 1 -c copy -c:v:1 png -disposition:v:1 attached_pic out.mp4957ffmpeg -i in.mp4 -i IMAGE -map 0 -map 1 -c copy -c:v:1 png -disposition:v:1 attached_pic out.mp4
957@end example958@end example
958 959
960To add the 'original' and remove the 'comment' disposition flag from the first
961audio stream without removing its other disposition flags:
962@example
963ffmpeg -i in.mkv -c copy -disposition:a:0 +original-comment out.mkv
964@end example
965
966To remove the 'original' and add the 'comment' disposition flag to the first
967audio stream without removing its other disposition flags:
968@example
969ffmpeg -i in.mkv -c copy -disposition:a:0 -original+comment out.mkv
970@end example
971
972To set only the 'original' and 'comment' disposition flags on the first audio
973stream (and remove its other disposition flags):
974@example
975ffmpeg -i in.mkv -c copy -disposition:a:0 original+comment out.mkv
976@end example
977
978To remove all disposition flags from the first audio stream:
979@example
980ffmpeg -i in.mkv -c copy -disposition:a:0 0 out.mkv
981@end example
982
959Not all muxers support embedded thumbnails, and those who do, only support a few formats, like JPEG or PNG.983Not all muxers support embedded thumbnails, and those who do, only support a few formats, like JPEG or PNG.
960 984
961@item -program [title=@var{title}:][program_num=@var{program_num}:]st=@var{stream}[:st=@var{stream}...] (@emph{output})985@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
1358Specify the preset for matching stream(s).1382Specify the preset for matching stream(s).
1359 1383
1360@item -stats (@emph{global})1384@item -stats (@emph{global})
1361Print encoding progress/statistics. It is on by default, to explicitly1385Log encoding progress/statistics as "info"-level log (see @code{-loglevel}).
1362disable it you need to specify @code{-nostats}.1386It is on by default, to explicitly disable it you need to specify @code{-nostats}.
1363 1387
1364@item -stats_period @var{time} (@emph{global})1388@item -stats_period @var{time} (@emph{global})
1365Set period at which encoding progress/statistics are updated. Default is 0.5 seconds.1389Set 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
1370Progress information is written periodically and at the end of1394Progress information is written periodically and at the end of
1371the encoding process. It is made of "@var{key}=@var{value}" lines. @var{key}1395the encoding process. It is made of "@var{key}=@var{value}" lines. @var{key}
1372consists of only alphanumeric characters. The last key of a sequence of1396consists of only alphanumeric characters. The last key of a sequence of
1373progress information is always "progress".1397progress information is always "progress" with the value "continue" or "end".
1374 1398
1375The update period is set using @code{-stats_period}.1399The update period is set using @code{-stats_period}.
1376 1400
1401For example, log progress information to stdout:
1402
1403@example
1404ffmpeg -progress pipe:1 -i in.mkv out.mkv
1405@end example
1406
1377@anchor{stdin option}1407@anchor{stdin option}
1378@item -stdin1408@item -stdin
1379Enable interaction on standard input. On by default unless standard input is1409Enable 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