error_resilience: guess_dc: check malloc failure
[ffmpeg.git] / doc / muxers.texi
index 7934fe2..83c21db 100644 (file)
@@ -129,6 +129,39 @@ ffmpeg -i INPUT -f framemd5 -
 
 See also the @ref{md5} muxer.
 
+@anchor{ico}
+@section ico
+
+ICO file muxer.
+
+Microsoft's icon file format (ICO) has some strict limitations that should be noted:
+
+@itemize
+@item
+Size cannot exceed 256 pixels in any dimension
+
+@item
+Only BMP and PNG images can be stored
+
+@item
+If a BMP image is used, it must be one of the following pixel formats:
+@example
+BMP Bit Depth      FFmpeg Pixel Format
+1bit               pal8
+4bit               pal8
+8bit               pal8
+16bit              rgb555le
+24bit              bgr24
+32bit              bgra
+@end example
+
+@item
+If a BMP image is used, it must use the BITMAPINFOHEADER DIB header
+
+@item
+If a PNG image is used, it must use the rgba pixel format
+@end itemize
+
 @anchor{image2}
 @section image2
 
@@ -433,8 +466,9 @@ time.
 
 The segment muxer works best with a single constant frame rate video.
 
-Optionally it can generate a flat list of the created segments, one segment
-per line, by setting the option @var{segment_list}.
+Optionally it can generate a list of the created segments, by setting
+the option @var{segment_list}. The list type is specified by the
+@var{segment_list_type} option.
 
 The segment muxer supports the following options:
 
@@ -445,9 +479,27 @@ extension.
 @item segment_list @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 @var
+@item cache
+Allow caching (only affects M3U8 list files).
+
+@item live
+Allow live-friendly file generation.
+
+This currently only affects M3U8 lists. In particular, write a fake
+EXT-X-TARGETDURATION duration field at the top of the file, based on
+the specified @var{segment_time}.
+@end table
+
+Default value is @code{cache}.
+
 @item segment_list_size @var{size}
 Overwrite the listfile once it reaches @var{size} entries. If 0
-the listfile is never overwritten. Default value is 5.
+the listfile is never overwritten. Default value is 0.
 @item segment_list type @var{type}
 Specify the format for the segment list file.
 
@@ -456,24 +508,57 @@ The following values are recognized:
 @item flat
 Generate a flat list for the created segments, one segment per line.
 
-@item ext
+@item csv, ext
 Generate a list for the created segments, one segment per line,
-each line matching the format:
+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, and should not contain the
-"," character for simplifying parsing operations.
+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.
+
+@code{ext} is deprecated in favor or @code{csv}.
+
+@item m3u8
+Generate an extended M3U8 file, version 4, compliant with
+@url{http://tools.ietf.org/id/draft-pantos-http-live-streaming-08.txt}.
+
+A list file with the suffix @code{".m3u8"} will auto-select this format.
 @end table
 
-Default value is "flat".
+If not specified the type is guessed from the list file name suffix.
 @item segment_time @var{time}
 Set segment duration to @var{time}. Default value is "2".
+@item segment_time_delta @var{delta}
+Specify the accuracy time when selecting the start time for a
+segment. 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.
@@ -496,8 +581,20 @@ ffmpeg -i in.mkv -codec copy -map 0 -f segment -segment_list out.list out%03d.nu
 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_type ext -segment_list out.list -segment_list_size 0 -segment_times 1,2,3,5,8,13,21 out%03d.nut
+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 @code{ffmpeg} @var{force_key_frames}
+option to force key frames in the input at the specified location, together
+with the segment option @var{segment_time_delta} to account for
+possible roundings operated when setting key frame times.
+@example
+ffmpeg -i in.mkv -force_key_frames 1,2,3,5,8,13,21 -vcodec mpeg4 -acodec 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
 To convert the @file{in.mkv} to TS segments using the @code{libx264}
@@ -505,6 +602,14 @@ 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 mp3