X-Git-Url: https://git.sesse.net/?a=blobdiff_plain;f=doc%2Fmuxers.texi;h=f18543e83d8424c02fca153cef4a347e6cbcacd8;hb=fbd8746efabe441469eb410d2ffa6af64987ca80;hp=cb75c261c55829564a7c072a557413e4c59d087b;hpb=0ac379863231dbf84a97a01845c6d00cc00610c1;p=ffmpeg diff --git a/doc/muxers.texi b/doc/muxers.texi index cb75c261c55..f18543e83d8 100644 --- a/doc/muxers.texi +++ b/doc/muxers.texi @@ -226,7 +226,12 @@ ffmpeg -re -i -map 0 -map 0 -c:a libfdk_aac -c:v libx264 @table @option @item -min_seg_duration @var{microseconds} -Set the segment length in microseconds. +This is a deprecated option to set the segment length in microseconds, use @var{seg_duration} instead. +@item -seg_duration @var{duration} +Set the segment length in seconds (fractional value can be set). The value is +treated as average segment duration when @var{use_template} is enabled and +@var{use_timeline} is disabled and as minimum segment duration for all the other +use cases. @item -window_size @var{size} Set the maximum number of segments kept in the manifest. @item -extra_window_size @var{size} @@ -247,6 +252,8 @@ DASH-templated name to used for the initialization segment. Default is "init-str DASH-templated name to used for the media segments. Default is "chunk-stream$RepresentationID$-$Number%05d$.m4s" @item -utc_timing_url @var{utc_url} URL of the page that will return the UTC timestamp in ISO format. Example: "https://time.akamai.com/?iso" +@item method @var{method} +Use the given HTTP method to create output files. Generally set to PUT or POST. @item -http_user_agent @var{user_agent} Override User-Agent field in HTTP header. Applicable only for HTTP output. @item -http_persistent @var{http_persistent} @@ -266,6 +273,30 @@ To map all video (or audio) streams to an AdaptationSet, "v" (or "a") can be use When no assignment is defined, this defaults to an AdaptationSet for each stream. @item -timeout @var{timeout} Set timeout for socket I/O operations. Applicable only for HTTP output. +@item -index_correction @var{index_correction} +Enable (1) or Disable (0) segment index correction logic. Applicable only when +@var{use_template} is enabled and @var{use_timeline} is disabled. + +When enabled, the logic monitors the flow of segment indexes. If a streams's +segment index value is not at the expected real time position, then the logic +corrects that index value. + +Typically this logic is needed in live streaming use cases. The network bandwidth +fluctuations are common during long run streaming. Each fluctuation can cause +the segment indexes fall behind the expected real time position. +@item -format_options @var{options_list} +Set container format (mp4/webm) options using a @code{:} separated list of +key=value parameters. Values containing @code{:} special characters must be +escaped. + +@item dash_segment_type @var{dash_segment_type} +Possible values: +@item mp4 +If this flag is set, the dash segment files will be in in ISOBMFF format. This is the default format. + +@item webm +If this flag is set, the dash segment files will be in in WebM format. + @end table @anchor{framecrc} @@ -513,6 +544,12 @@ Segment will be cut on the next key frame after this time has passed. Set the maximum number of playlist entries. If set to 0 the list file will contain all the segments. Default value is 5. +@item hls_delete_threshold @var{size} +Set the number of unreferenced segments to keep on disk before @code{hls_flags delete_segments} +deletes them. Increase this to allow continue clients to download segments which +were recently referenced in the playlist. Default value is 1, meaning segments older than +@code{hls_list_size+1} will be deleted. + @item hls_ts_options @var{options_list} Set output format options using a :-separated list of key=value parameters. Values containing @code{:} special characters must be @@ -580,7 +617,7 @@ This example will produce the playlist, @file{out.m3u8}, and segment files: but only the file name part without any path info will be contained in the m3u8 segment list. Should a relative path be specified, the path of the created segment files will be relative to the current working directory. -When use_localtime_mkdir is set, the whole expanded value of @var{filename} will be written into the m3u8 segment list. +When strftime_mkdir is set, the whole expanded value of @var{filename} will be written into the m3u8 segment list. When @code{var_stream_map} is set with two or more variant streams, the @var{filename} pattern must contain the string "%v", this string specifies @@ -609,34 +646,40 @@ This example will produce the playlists segment file sets: @file{vs1/file_000.ts}, @file{vs1/file_001.ts}, @file{vs1/file_002.ts}, etc. @item use_localtime +Same as strftime option, will be deprecated. + +@item strftime Use strftime() on @var{filename} to expand the segment filename with localtime. The segment number is also available in this mode, but to use it, you need to specify second_level_segment_index hls_flag and %%d will be the specifier. @example -ffmpeg -i in.nut -use_localtime 1 -hls_segment_filename 'file-%Y%m%d-%s.ts' out.m3u8 +ffmpeg -i in.nut -strftime 1 -hls_segment_filename 'file-%Y%m%d-%s.ts' out.m3u8 @end example This example will produce the playlist, @file{out.m3u8}, and segment files: @file{file-20160215-1455569023.ts}, @file{file-20160215-1455569024.ts}, etc. Note: On some systems/environments, the @code{%s} specifier is not available. See @code{strftime()} documentation. @example -ffmpeg -i in.nut -use_localtime 1 -hls_flags second_level_segment_index -hls_segment_filename 'file-%Y%m%d-%%04d.ts' out.m3u8 +ffmpeg -i in.nut -strftime 1 -hls_flags second_level_segment_index -hls_segment_filename 'file-%Y%m%d-%%04d.ts' out.m3u8 @end example This example will produce the playlist, @file{out.m3u8}, and segment files: @file{file-20160215-0001.ts}, @file{file-20160215-0002.ts}, etc. @item use_localtime_mkdir -Used together with -use_localtime, it will create all subdirectories which +Same as strftime_mkdir option, will be deprecated . + +@item strftime_mkdir +Used together with -strftime_mkdir, it will create all subdirectories which is expanded in @var{filename}. @example -ffmpeg -i in.nut -use_localtime 1 -use_localtime_mkdir 1 -hls_segment_filename '%Y%m%d/file-%Y%m%d-%s.ts' out.m3u8 +ffmpeg -i in.nut -strftime 1 -strftime_mkdir 1 -hls_segment_filename '%Y%m%d/file-%Y%m%d-%s.ts' out.m3u8 @end example This example will create a directory 201560215 (if it does not exist), and then produce the playlist, @file{out.m3u8}, and segment files: @file{20160215/file-20160215-1455569023.ts}, @file{20160215/file-20160215-1455569024.ts}, etc. @example -ffmpeg -i in.nut -use_localtime 1 -use_localtime_mkdir 1 -hls_segment_filename '%Y/%m/%d/file-%Y%m%d-%s.ts' out.m3u8 +ffmpeg -i in.nut -strftime 1 -strftime_mkdir 1 -hls_segment_filename '%Y/%m/%d/file-%Y%m%d-%s.ts' out.m3u8 @end example This example will create a directory hierarchy 2016/02/15 (if any of them do not exist), and then produce the playlist, @file{out.m3u8}, and segment files: @@ -796,24 +839,24 @@ Generate @code{EXT-X-PROGRAM-DATE-TIME} tags. @item second_level_segment_index Makes it possible to use segment indexes as %%d in hls_segment_filename expression -besides date/time values when use_localtime is on. +besides date/time values when strftime is on. To get fixed width numbers with trailing zeroes, %%0xd format is available where x is the required width. @item second_level_segment_size Makes it possible to use segment sizes (counted in bytes) as %%s in hls_segment_filename -expression besides date/time values when use_localtime is on. +expression besides date/time values when strftime is on. To get fixed width numbers with trailing zeroes, %%0xs format is available where x is the required width. @item second_level_segment_duration Makes it possible to use segment duration (calculated in microseconds) as %%t in hls_segment_filename -expression besides date/time values when use_localtime is on. +expression besides date/time values when strftime is on. To get fixed width numbers with trailing zeroes, %%0xt format is available where x is the required width. @example ffmpeg -i sample.mpeg \ -f hls -hls_time 3 -hls_list_size 5 \ -hls_flags second_level_segment_index+second_level_segment_size+second_level_segment_duration \ - -use_localtime 1 -use_localtime_mkdir 1 -hls_segment_filename "segment_%Y%m%d%H%M%S_%%04d_%%08s_%%013t.ts" stream.m3u8 + -strftime 1 -strftime_mkdir 1 -hls_segment_filename "segment_%Y%m%d%H%M%S_%%04d_%%08s_%%013t.ts" stream.m3u8 @end example This will produce segments like this: @file{segment_20170102194334_0003_00122200_0000003000000.ts}, @file{segment_20170102194334_0004_00120072_0000003000000.ts} etc. @@ -1307,6 +1350,18 @@ be negative. This enables the initial sample to have DTS/CTS of zero, and reduces the need for edit lists for some cases such as video tracks with B-frames. Additionally, eases conformance with the DASH-IF interoperability guidelines. + +This option is implicitly set when writing ismv (Smooth Streaming) files. +@item -write_prft +Write producer time reference box (PRFT) with a specified time source for the +NTP field in the PRFT box. Set value as @samp{wallclock} to specify timesource +as wallclock time and @samp{pts} to specify timesource as input packets' PTS +values. + +Setting value to @samp{pts} is applicable only for a live encoding use case, +where PTS values are set as as wallclock time at the source. For example, an +encoding use case with decklink capture source where @option{video_pts} and +@option{audio_pts} are set to @samp{abs_wallclock}. @end table @subsection Example @@ -2015,20 +2070,35 @@ ffmpeg -re -i ... -c:v libx264 -c:a aac -f fifo -fifo_format flv -map 0:v -map 0 @anchor{tee} @section tee -The tee muxer can be used to write the same data to several files or any -other kind of muxer. It can be used, for example, to both stream a video to -the network and save it to disk at the same time. +The tee muxer can be used to write the same data to several outputs, such as files or streams. +It can be used, for example, to stream a video over a network and save it to disk at the same time. It is different from specifying several outputs to the @command{ffmpeg} -command-line tool because the audio and video data will be encoded only once -with the tee muxer; encoding can be a very expensive process. It is not -useful when using the libavformat API directly because it is then possible -to feed the same packets to several muxers directly. +command-line tool. With the tee muxer, the audio and video data will be encoded only once. +With conventional multiple outputs, multiple encoding operations in parallel are initiated, +which can be a very expensive process. The tee muxer is not useful when using the libavformat API +directly because it is then possible to feed the same packets to several muxers directly. + +Since the tee muxer does not represent any particular output format, ffmpeg cannot auto-select +output streams. So all streams intended for output must be specified using @code{-map}. See +the examples below. + +Some encoders may need different options depending on the output format; +the auto-detection of this can not work with the tee muxer, so they need to be explicitly specified. +The main example is the @option{global_header} flag. + +The slave outputs are specified in the file name given to the muxer, +separated by '|'. If any of the slave name contains the '|' separator, +leading or trailing spaces or any special character, those must be +escaped (see @ref{quoting_and_escaping,,the "Quoting and escaping" +section in the ffmpeg-utils(1) manual,ffmpeg-utils}). + +@subsection Options @table @option @item use_fifo @var{bool} -If set to 1, slave outputs will be processed in separate thread using @ref{fifo} +If set to 1, slave outputs will be processed in separate threads using the @ref{fifo} muxer. This allows to compensate for different speed/latency/reliability of outputs and setup transparent recovery. By default this feature is turned off. @@ -2037,12 +2107,6 @@ Options to pass to fifo pseudo-muxer instances. See @ref{fifo}. @end table -The slave outputs are specified in the file name given to the muxer, -separated by '|'. If any of the slave name contains the '|' separator, -leading or trailing spaces or any special character, it must be -escaped (see @ref{quoting_and_escaping,,the "Quoting and escaping" -section in the ffmpeg-utils(1) manual,ffmpeg-utils}). - Muxer options can be specified for each slave by prepending them as a list of @var{key}=@var{value} pairs separated by ':', between square brackets. If the options values contain a special character or the ':' separator, they @@ -2051,13 +2115,27 @@ must be escaped; note that this is a second level escaping. The following special options are also recognized: @table @option @item f -Specify the format name. Useful if it cannot be guessed from the -output name suffix. +Specify the format name. Required if it cannot be guessed from the +output URL. @item bsfs[/@var{spec}] Specify a list of bitstream filters to apply to the specified output. +It is possible to specify to which streams a given bitstream filter +applies, by appending a stream specifier to the option separated by +@code{/}. @var{spec} must be a stream specifier (see @ref{Format +stream specifiers}). + +If the stream specifier is not specified, the bitstream filters will be +applied to all streams in the output. This will cause that output operation +to fail if the output contains streams to which the bitstream filter cannot +be applied e.g. @code{h264_mp4toannexb} being applied to an output containing an audio stream. + +Options for a bitstream filter must be specified in the form of @code{opt=value}. + +Several bitstream filters can be specified, separated by ",". + @item use_fifo @var{bool} This allows to override tee muxer use_fifo option for individual slave muxer. @@ -2065,19 +2143,13 @@ This allows to override tee muxer use_fifo option for individual slave muxer. This allows to override tee muxer fifo_options for individual slave muxer. See @ref{fifo}. -It is possible to specify to which streams a given bitstream filter -applies, by appending a stream specifier to the option separated by -@code{/}. @var{spec} must be a stream specifier (see @ref{Format -stream specifiers}). If the stream specifier is not specified, the -bitstream filters will be applied to all streams in the output. - -Several bitstream filters can be specified, separated by ",". - @item select Select the streams that should be mapped to the slave output, specified by a stream specifier. If not specified, this defaults to -all the input streams. You may use multiple stream specifiers -separated by commas (@code{,}) e.g.: @code{a:0,v} +all the mapped streams. This will cause that output operation to fail +if the output format does not accept all mapped streams. + +You may use multiple stream specifiers separated by commas (@code{,}) e.g.: @code{a:0,v} @item onfail Specify behaviour on output failure. This can be set to either @code{abort} (which is @@ -2091,7 +2163,7 @@ will continue without being affected. @itemize @item Encode something and both archive it in a WebM file and stream it -as MPEG-TS over UDP (the streams need to be explicitly mapped): +as MPEG-TS over UDP: @example ffmpeg -i ... -c:v libx264 -c:a mp2 -f tee -map 0:v -map 0:a "archive-20121107.mkv|[f=mpegts]udp://10.0.1.255:1234/" @@ -2114,23 +2186,19 @@ option is applied to @file{out.aac} in order to make it contain only audio packets. @example ffmpeg -i ... -map 0 -flags +global_header -c:v libx264 -c:a aac - -f tee "[bsfs/v=dump_extra]out.ts|[movflags=+faststart]out.mp4|[select=a]out.aac" + -f tee "[bsfs/v=dump_extra=freq=keyframe]out.ts|[movflags=+faststart]out.mp4|[select=a]out.aac" @end example @item -As below, but select only stream @code{a:1} for the audio output. Note +As above, but select only stream @code{a:1} for the audio output. Note that a second level escaping must be performed, as ":" is a special character used to separate options. @example ffmpeg -i ... -map 0 -flags +global_header -c:v libx264 -c:a aac - -f tee "[bsfs/v=dump_extra]out.ts|[movflags=+faststart]out.mp4|[select=\'a:1\']out.aac" + -f tee "[bsfs/v=dump_extra=freq=keyframe]out.ts|[movflags=+faststart]out.mp4|[select=\'a:1\']out.aac" @end example @end itemize -Note: some codecs may need different options depending on the output format; -the auto-detection of this can not work with the tee muxer. The main example -is the @option{global_header} flag. - @section webm_dash_manifest WebM DASH Manifest muxer.