Merge commit '49a242687cf44f86570b706db3c5912ff06bc6c2'
authorMichael Niedermayer <michaelni@gmx.at>
Wed, 18 Jun 2014 21:09:35 +0000 (23:09 +0200)
committerMichael Niedermayer <michaelni@gmx.at>
Wed, 18 Jun 2014 21:13:31 +0000 (23:13 +0200)
* commit '49a242687cf44f86570b706db3c5912ff06bc6c2':
  doc: Document segment_list_type

Conflicts:
doc/muxers.texi

Merged-by: Michael Niedermayer <michaelni@gmx.at>
1  2 
doc/muxers.texi

diff --cc doc/muxers.texi
@@@ -797,293 -499,26 +797,297 @@@ reference stream. The default value is 
  @item segment_format @var{format}
  Override the inner container format, by default it is guessed by the filename
  extension.
 -@item segment_time @var{t}
 -Set segment duration to @var{t} seconds.
 +
  @item segment_list @var{name}
 -Generate also a listfile named @var{name}.
 +Generate also a listfile named @var{name}. If not specified no
 +listfile is generated.
 +
 +@item segment_list_flags @var{flags}
 +Set flags affecting the segment list generation.
 +
 +It currently supports the following flags:
 +@table @samp
 +@item cache
 +Allow caching (only affects M3U8 list files).
 +
 +@item live
 +Allow live-friendly file generation.
 +@end table
 +
+ @item segment_list_type @var{type}
+ Select the listing format.
+ @table @option
+ @item @var{flat} use a simple flat list of entries.
+ @item @var{hls} use a m3u8-like structure.
+ @end table
++
  @item segment_list_size @var{size}
 -Overwrite the listfile once it reaches @var{size} entries.
 +Update the list file so that it contains at most the last @var{size}
 +segments. If 0 the list file will contain all the segments. Default
 +value is 0.
 +
  @item segment_list_entry_prefix @var{prefix}
  Prepend @var{prefix} to each entry. Useful to generate absolute paths.
- @item segment_list_type @var{type}
- Specify the format for the segment list file.
 +By default no prefix is applied.
 +
 +The following values are recognized:
 +@table @samp
 +@item flat
 +Generate a flat list for the created segments, one segment per line.
 +
 +@item csv, ext
 +Generate a list for the created segments, one segment per line,
 +each line matching the format (comma-separated values):
 +@example
 +@var{segment_filename},@var{segment_start_time},@var{segment_end_time}
 +@end example
 +
 +@var{segment_filename} is the name of the output file generated by the
 +muxer according to the provided pattern. CSV escaping (according to
 +RFC4180) is applied if required.
 +
 +@var{segment_start_time} and @var{segment_end_time} specify
 +the segment start and end time expressed in seconds.
 +
 +A list file with the suffix @code{".csv"} or @code{".ext"} will
 +auto-select this format.
 +
 +@samp{ext} is deprecated in favor or @samp{csv}.
 +
 +@item ffconcat
 +Generate an ffconcat file for the created segments. The resulting file
 +can be read using the FFmpeg @ref{concat} demuxer.
 +
 +A list file with the suffix @code{".ffcat"} or @code{".ffconcat"} will
 +auto-select this format.
 +
 +@item m3u8
 +Generate an extended M3U8 file, version 3, compliant with
 +@url{http://tools.ietf.org/id/draft-pantos-http-live-streaming}.
 +
 +A list file with the suffix @code{".m3u8"} will auto-select this format.
 +@end table
 +
 +If not specified the type is guessed from the list file name suffix.
 +
 +@item segment_time @var{time}
 +Set segment duration to @var{time}, the value must be a duration
 +specification. Default value is "2". See also the
 +@option{segment_times} option.
 +
 +Note that splitting may not be accurate, unless you force the
 +reference stream key-frames at the given time. See the introductory
 +notice and the examples below.
 +
 +@item segment_time_delta @var{delta}
 +Specify the accuracy time when selecting the start time for a
 +segment, expressed as a duration specification. Default value is "0".
 +
 +When delta is specified a key-frame will start a new segment if its
 +PTS satisfies the relation:
 +@example
 +PTS >= start_time - time_delta
 +@end example
 +
 +This option is useful when splitting video content, which is always
 +split at GOP boundaries, in case a key frame is found just before the
 +specified split time.
 +
 +In particular may be used in combination with the @file{ffmpeg} option
 +@var{force_key_frames}. The key frame times specified by
 +@var{force_key_frames} may not be set accurately because of rounding
 +issues, with the consequence that a key frame time may result set just
 +before the specified time. For constant frame rate videos a value of
 +1/(2*@var{frame_rate}) should address the worst case mismatch between
 +the specified time and the time set by @var{force_key_frames}.
 +
 +@item segment_times @var{times}
 +Specify a list of split points. @var{times} contains a list of comma
 +separated duration specifications, in increasing order. See also
 +the @option{segment_time} option.
 +
 +@item segment_frames @var{frames}
 +Specify a list of split video frame numbers. @var{frames} contains a
 +list of comma separated integer numbers, in increasing order.
 +
 +This option specifies to start a new segment whenever a reference
 +stream key frame is found and the sequential number (starting from 0)
 +of the frame is greater or equal to the next value in the list.
 +
  @item segment_wrap @var{limit}
  Wrap around segment index once it reaches @var{limit}.
 +
 +@item segment_start_number @var{number}
 +Set the sequence number of the first segment. Defaults to @code{0}.
 +
 +@item reset_timestamps @var{1|0}
 +Reset timestamps at the begin of each segment, so that each segment
 +will start with near-zero timestamps. It is meant to ease the playback
 +of the generated segments. May not work with some combinations of
 +muxers/codecs. It is set to @code{0} by default.
 +
 +@item initial_offset @var{offset}
 +Specify timestamp offset to apply to the output packet timestamps. The
 +argument must be a time duration specification, and defaults to 0.
  @end table
  
 +@subsection Examples
 +
 +@itemize
 +@item
 +To remux the content of file @file{in.mkv} to a list of segments
 +@file{out-000.nut}, @file{out-001.nut}, etc., and write the list of
 +generated segments to @file{out.list}:
 +@example
 +ffmpeg -i in.mkv -codec copy -map 0 -f segment -segment_list out.list out%03d.nut
 +@end example
 +
 +@item
 +As the example above, but segment the input file according to the split
 +points specified by the @var{segment_times} option:
 +@example
 +ffmpeg -i in.mkv -codec copy -map 0 -f segment -segment_list out.csv -segment_times 1,2,3,5,8,13,21 out%03d.nut
 +@end example
 +
 +@item
 +As the example above, but use the @command{ffmpeg} @option{force_key_frames}
 +option to force key frames in the input at the specified location, together
 +with the segment option @option{segment_time_delta} to account for
 +possible roundings operated when setting key frame times.
  @example
 -avconv -i in.mkv -c copy -map 0 -f segment -list out.list out%03d.nut
 +ffmpeg -i in.mkv -force_key_frames 1,2,3,5,8,13,21 -codec:v mpeg4 -codec:a pcm_s16le -map 0 \
 +-f segment -segment_list out.csv -segment_times 1,2,3,5,8,13,21 -segment_time_delta 0.05 out%03d.nut
  @end example
 +In order to force key frames on the input file, transcoding is
 +required.
 +
 +@item
 +Segment the input file by splitting the input file according to the
 +frame numbers sequence specified with the @option{segment_frames} option:
 +@example
 +ffmpeg -i in.mkv -codec copy -map 0 -f segment -segment_list out.csv -segment_frames 100,200,300,500,800 out%03d.nut
 +@end example
 +
 +@item
 +To convert the @file{in.mkv} to TS segments using the @code{libx264}
 +and @code{libfaac} encoders:
 +@example
 +ffmpeg -i in.mkv -map 0 -codec:v libx264 -codec:a libfaac -f ssegment -segment_list out.list out%03d.ts
 +@end example
 +
 +@item
 +Segment the input file, and create an M3U8 live playlist (can be used
 +as live HLS source):
 +@example
 +ffmpeg -re -i in.mkv -codec copy -map 0 -f segment -segment_list playlist.m3u8 \
 +-segment_list_flags +live -segment_time 10 out%03d.mkv
 +@end example
 +@end itemize
 +
 +@section smoothstreaming
 +
 +Smooth Streaming muxer generates a set of files (Manifest, chunks) suitable for serving with conventional web server.
 +
 +@table @option
 +@item window_size
 +Specify the number of fragments kept in the manifest. Default 0 (keep all).
 +
 +@item extra_window_size
 +Specify the number of fragments kept outside of the manifest before removing from disk. Default 5.
 +
 +@item lookahead_count
 +Specify the number of lookahead fragments. Default 2.
 +
 +@item min_frag_duration
 +Specify the minimum fragment duration (in microseconds). Default 5000000.
 +
 +@item remove_at_exit
 +Specify whether to remove all fragments when finished. Default 0 (do not remove).
 +
 +@end table
 +
 +@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.
 +
 +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.
 +
 +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
 +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.
 +
 +@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.
 +
 +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.
 +@end table
 +
 +@subsection Examples
 +
 +@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):
 +@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/"
 +@end example
 +
 +@item
 +Use @command{ffmpeg} to encode the input, and send the output
 +to three different destinations. The @code{dump_extra} bitstream
 +filter is used to add extradata information to all the output video
 +keyframes packets, as requested by the MPEG-TS format. The select
 +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 -strict experimental
 +       -f tee "[bsfs/v=dump_extra]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
 +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 -strict experimental
 +       -f tee "[bsfs/v=dump_extra]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.
  
  @c man end MUXERS