diff options
Diffstat (limited to 'doc/demuxers.texi')
| -rw-r--r-- | doc/demuxers.texi | 452 |
1 files changed, 397 insertions, 55 deletions
diff --git a/doc/demuxers.texi b/doc/demuxers.texi index 2f2f464404..11dfe1b9c1 100644 --- a/doc/demuxers.texi +++ b/doc/demuxers.texi @@ -1,30 +1,263 @@ @chapter Demuxers @c man begin DEMUXERS -Demuxers are configured elements in Libav which allow to read the +Demuxers are configured elements in FFmpeg that can read the multimedia streams from a particular type of file. -When you configure your Libav build, all the supported demuxers +When you configure your FFmpeg build, all the supported demuxers are enabled by default. You can list all available ones using the -configure option "--list-demuxers". +configure option @code{--list-demuxers}. You can disable all the demuxers using the configure option -"--disable-demuxers", and selectively enable a single demuxer with -the option "--enable-demuxer=@var{DEMUXER}", or disable it -with the option "--disable-demuxer=@var{DEMUXER}". +@code{--disable-demuxers}, and selectively enable a single demuxer with +the option @code{--enable-demuxer=@var{DEMUXER}}, or disable it +with the option @code{--disable-demuxer=@var{DEMUXER}}. -The option "-formats" of the av* tools will display the list of +The option @code{-formats} of the ff* tools will display the list of enabled demuxers. The description of some of the currently available demuxers follows. +@section applehttp + +Apple HTTP Live Streaming demuxer. + +This demuxer presents all AVStreams from all variant streams. +The id field is set to the bitrate variant index number. By setting +the discard flags on AVStreams (by pressing 'a' or 'v' in ffplay), +the caller can decide which variant streams to actually receive. +The total bitrate of the variant that the stream belongs to is +available in a metadata key named "variant_bitrate". + +@section apng + +Animated Portable Network Graphics demuxer. + +This demuxer is used to demux APNG files. +All headers, but the PNG signature, up to (but not including) the first +fcTL chunk are transmitted as extradata. +Frames are then split as being all the chunks between two fcTL ones, or +between the last fcTL and IEND chunks. + +@table @option +@item -ignore_loop @var{bool} +Ignore the loop variable in the file if set. +@item -max_fps @var{int} +Maximum framerate in frames per second (0 for no limit). +@item -default_fps @var{int} +Default framerate in frames per second when none is specified in the file +(0 meaning as fast as possible). +@end table + +@section asf + +Advanced Systems Format demuxer. + +This demuxer is used to demux ASF files and MMS network streams. + +@table @option +@item -no_resync_search @var{bool} +Do not try to resynchronize by looking for a certain optional start code. +@end table + +@anchor{concat} +@section concat + +Virtual concatenation script demuxer. + +This demuxer reads a list of files and other directives from a text file and +demuxes them one after the other, as if all their packet had been muxed +together. + +The timestamps in the files are adjusted so that the first file starts at 0 +and each next file starts where the previous one finishes. Note that it is +done globally and may cause gaps if all streams do not have exactly the same +length. + +All files must have the same streams (same codecs, same time base, etc.). + +The duration of each file is used to adjust the timestamps of the next file: +if the duration is incorrect (because it was computed using the bit-rate or +because the file is truncated, for example), it can cause artifacts. The +@code{duration} directive can be used to override the duration stored in +each file. + +@subsection Syntax + +The script is a text file in extended-ASCII, with one directive per line. +Empty lines, leading spaces and lines starting with '#' are ignored. The +following directive is recognized: + +@table @option + +@item @code{file @var{path}} +Path to a file to read; special characters and spaces must be escaped with +backslash or single quotes. + +All subsequent file-related directives apply to that file. + +@item @code{ffconcat version 1.0} +Identify the script type and version. It also sets the @option{safe} option +to 1 if it was to its default -1. + +To make FFmpeg recognize the format automatically, this directive must +appears exactly as is (no extra space or byte-order-mark) on the very first +line of the script. + +@item @code{duration @var{dur}} +Duration of the file. This information can be specified from the file; +specifying it here may be more efficient or help if the information from the +file is not available or accurate. + +If the duration is set for all files, then it is possible to seek in the +whole concatenated video. + +@item @code{stream} +Introduce a stream in the virtual file. +All subsequent stream-related directives apply to the last introduced +stream. +Some streams properties must be set in order to allow identifying the +matching streams in the subfiles. +If no streams are defined in the script, the streams from the first file are +copied. + +@item @code{exact_stream_id @var{id}} +Set the id of the stream. +If this directive is given, the string with the corresponding id in the +subfiles will be used. +This is especially useful for MPEG-PS (VOB) files, where the order of the +streams is not reliable. + +@end table + +@subsection Options + +This demuxer accepts the following option: + +@table @option + +@item safe +If set to 1, reject unsafe file paths. A file path is considered safe if it +does not contain a protocol specification and is relative and all components +only contain characters from the portable character set (letters, digits, +period, underscore and hyphen) and have no period at the beginning of a +component. + +If set to 0, any file name is accepted. + +The default is -1, it is equivalent to 1 if the format was automatically +probed and 0 otherwise. + +@item auto_convert +If set to 1, try to perform automatic conversions on packet data to make the +streams concatenable. + +Currently, the only conversion is adding the h264_mp4toannexb bitstream +filter to H.264 streams in MP4 format. This is necessary in particular if +there are resolution changes. + +@end table + +@section flv + +Adobe Flash Video Format demuxer. + +This demuxer is used to demux FLV files and RTMP network streams. + +@table @option +@item -flv_metadata @var{bool} +Allocate the streams according to the onMetaData array content. +@end table + +@section libgme + +The Game Music Emu library is a collection of video game music file emulators. + +See @url{http://code.google.com/p/game-music-emu/} for more information. + +Some files have multiple tracks. The demuxer will pick the first track by +default. The @option{track_index} option can be used to select a different +track. Track indexes start at 0. The demuxer exports the number of tracks as +@var{tracks} meta data entry. + +For very large files, the @option{max_size} option may have to be adjusted. + +@section libquvi + +Play media from Internet services using the quvi project. + +The demuxer accepts a @option{format} option to request a specific quality. It +is by default set to @var{best}. + +See @url{http://quvi.sourceforge.net/} for more information. + +FFmpeg needs to be built with @code{--enable-libquvi} for this demuxer to be +enabled. + +@section gif + +Animated GIF demuxer. + +It accepts the following options: + +@table @option +@item min_delay +Set the minimum valid delay between frames in hundredths of seconds. +Range is 0 to 6000. Default value is 2. + +@item default_delay +Set the default delay between frames in hundredths of seconds. +Range is 0 to 6000. Default value is 10. + +@item ignore_loop +GIF files can contain information to loop a certain number of times (or +infinitely). If @option{ignore_loop} is set to 1, then the loop setting +from the input will be ignored and looping will not occur. If set to 0, +then looping will occur and will cycle the number of times according to +the GIF. Default value is 1. +@end table + +For example, with the overlay filter, place an infinitely looping GIF +over another video: +@example +ffmpeg -i input.mp4 -ignore_loop 0 -i input.gif -filter_complex overlay=shortest=1 out.mkv +@end example + +Note that in the above example the shortest option for overlay filter is +used to end the output video at the length of the shortest input file, +which in this case is @file{input.mp4} as the GIF in this example loops +infinitely. + @section image2 Image file demuxer. This demuxer reads from a list of image files specified by a pattern. +The syntax and meaning of the pattern is specified by the +option @var{pattern_type}. -The pattern may contain the string "%d" or "%0@var{N}d", which +The pattern may contain a suffix which is used to automatically +determine the format of the images contained in the files. + +The size, the pixel format, and the format of each image must be the +same for all the files in the sequence. + +This demuxer accepts the following options: +@table @option +@item framerate +Set the frame rate for the video stream. It defaults to 25. +@item loop +If set to 1, loop over the input. Default value is 0. +@item pattern_type +Select the pattern type used to interpret the provided filename. + +@var{pattern_type} accepts one of the following values. +@table @option +@item sequence +Select a sequence pattern type, used to specify a sequence of files +indexed by sequential numbers. + +A sequence pattern may contain the string "%d" or "%0@var{N}d", which specifies the position of the characters representing a sequential number in each filename matched by the pattern. If the form "%d0@var{N}d" is used, the string representing the number in each @@ -32,13 +265,11 @@ filename is 0-padded and @var{N} is the total number of 0-padded digits representing the number. The literal character '%' can be specified in the pattern with the string "%%". -If the pattern contains "%d" or "%0@var{N}d", the first filename of +If the sequence pattern contains "%d" or "%0@var{N}d", the first filename of the file list specified by the pattern must contain a number -inclusively contained between 0 and 4, all the following numbers must -be sequential. This limitation may be hopefully fixed. - -The pattern may contain a suffix which is used to automatically -determine the format of the images contained in the files. +inclusively contained between @var{start_number} and +@var{start_number}+@var{start_number_range}-1, and all the following +numbers must be sequential. For example the pattern "img-%03d.bmp" will match a sequence of filenames of the form @file{img-001.bmp}, @file{img-002.bmp}, ..., @@ -46,68 +277,179 @@ filenames of the form @file{img-001.bmp}, @file{img-002.bmp}, ..., sequence of filenames of the form @file{i%m%g-1.jpg}, @file{i%m%g-2.jpg}, ..., @file{i%m%g-10.jpg}, etc. -The size, the pixel format, and the format of each image must be the -same for all the files in the sequence. +Note that the pattern must not necessarily contain "%d" or +"%0@var{N}d", for example to convert a single image file +@file{img.jpeg} you can employ the command: +@example +ffmpeg -i img.jpeg img.png +@end example + +@item glob +Select a glob wildcard pattern type. + +The pattern is interpreted like a @code{glob()} pattern. This is only +selectable if libavformat was compiled with globbing support. + +@item glob_sequence @emph{(deprecated, will be removed)} +Select a mixed glob wildcard/sequence pattern. + +If your version of libavformat was compiled with globbing support, and +the provided pattern contains at least one glob meta character among +@code{%*?[]@{@}} that is preceded by an unescaped "%", the pattern is +interpreted like a @code{glob()} pattern, otherwise it is interpreted +like a sequence pattern. + +All glob special characters @code{%*?[]@{@}} must be prefixed +with "%". To escape a literal "%" you shall use "%%". + +For example the pattern @code{foo-%*.jpeg} will match all the +filenames prefixed by "foo-" and terminating with ".jpeg", and +@code{foo-%?%?%?.jpeg} will match all the filenames prefixed with +"foo-", followed by a sequence of three characters, and terminating +with ".jpeg". + +This pattern type is deprecated in favor of @var{glob} and +@var{sequence}. +@end table + +Default value is @var{glob_sequence}. +@item pixel_format +Set the pixel format of the images to read. If not specified the pixel +format is guessed from the first image file in the sequence. +@item start_number +Set the index of the file matched by the image file pattern to start +to read from. Default value is 0. +@item start_number_range +Set the index interval range to check when looking for the first image +file in the sequence, starting from @var{start_number}. Default value +is 5. +@item ts_from_file +If set to 1, will set frame timestamp to modification time of image file. Note +that monotonity of timestamps is not provided: images go in the same order as +without this option. Default value is 0. +If set to 2, will set frame timestamp to the modification time of the image file in +nanosecond precision. +@item video_size +Set the video size of the images to read. If not specified the video +size is guessed from the first image file in the sequence. +@end table + +@subsection Examples -The following example shows how to use @command{avconv} for creating a -video from the images in the file sequence @file{img-001.jpeg}, -@file{img-002.jpeg}, ..., assuming an input framerate of 10 frames per -second: +@itemize +@item +Use @command{ffmpeg} for creating a video from the images in the file +sequence @file{img-001.jpeg}, @file{img-002.jpeg}, ..., assuming an +input frame rate of 10 frames per second: @example -avconv -i 'img-%03d.jpeg' -r 10 out.mkv +ffmpeg -framerate 10 -i 'img-%03d.jpeg' out.mkv @end example -Note that the pattern must not necessarily contain "%d" or -"%0@var{N}d", for example to convert a single image file -@file{img.jpeg} you can employ the command: +@item +As above, but start by reading from a file with index 100 in the sequence: +@example +ffmpeg -framerate 10 -start_number 100 -i 'img-%03d.jpeg' out.mkv +@end example + +@item +Read images matching the "*.png" glob pattern , that is all the files +terminating with the ".png" suffix: @example -avconv -i img.jpeg img.png +ffmpeg -framerate 10 -pattern_type glob -i "*.png" out.mkv @end example +@end itemize + +@section mpegts + +MPEG-2 transport stream demuxer. @table @option -@item -pixel_format @var{format} -Set the pixel format (for raw image) -@item -video_size @var{size} -Set the frame size (for raw image) -@item -framerate @var{rate} -Set the frame rate -@item -loop @var{bool} -Loop over the images -@item -start_number @var{start} -Specify the first number in the sequence + +@item fix_teletext_pts +Overrides teletext packet PTS and DTS values with the timestamps calculated +from the PCR of the first program which the teletext stream is part of and is +not discarded. Default value is 1, set this option to 0 if you want your +teletext packet PTS and DTS values untouched. @end table -@section applehttp +@section rawvideo -Apple HTTP Live Streaming demuxer. +Raw video demuxer. -This demuxer presents all AVStreams from all variant streams. -The id field is set to the bitrate variant index number. By setting -the discard flags on AVStreams (by pressing 'a' or 'v' in avplay), -the caller can decide which variant streams to actually receive. -The total bitrate of the variant that the stream belongs to is -available in a metadata key named "variant_bitrate". +This demuxer allows one to read raw video data. Since there is no header +specifying the assumed video parameters, the user must specify them +in order to be able to decode the data correctly. -@section flv +This demuxer accepts the following options: +@table @option -Adobe Flash Video Format demuxer. +@item framerate +Set input video frame rate. Default value is 25. -This demuxer is used to demux FLV files and RTMP network streams. +@item pixel_format +Set the input video pixel format. Default value is @code{yuv420p}. -@table @option -@item -flv_metadata @var{bool} -Allocate the streams according to the onMetaData array content. +@item video_size +Set the input video size. This value must be specified explicitly. @end table -@section asf +For example to read a rawvideo file @file{input.raw} with +@command{ffplay}, assuming a pixel format of @code{rgb24}, a video +size of @code{320x240}, and a frame rate of 10 images per second, use +the command: +@example +ffplay -f rawvideo -pixel_format rgb24 -video_size 320x240 -framerate 10 input.raw +@end example -Advanced Systems Format demuxer. +@section sbg -This demuxer is used to demux ASF files and MMS network streams. +SBaGen script demuxer. + +This demuxer reads the script language used by SBaGen +@url{http://uazu.net/sbagen/} to generate binaural beats sessions. A SBG +script looks like that: +@example +-SE +a: 300-2.5/3 440+4.5/0 +b: 300-2.5/0 440+4.5/3 +off: - +NOW == a ++0:07:00 == b ++0:14:00 == a ++0:21:00 == b ++0:30:00 off +@end example + +A SBG script can mix absolute and relative timestamps. If the script uses +either only absolute timestamps (including the script start time) or only +relative ones, then its layout is fixed, and the conversion is +straightforward. On the other hand, if the script mixes both kind of +timestamps, then the @var{NOW} reference for relative timestamps will be +taken from the current time of day at the time the script is read, and the +script layout will be frozen according to that reference. That means that if +the script is directly played, the actual times will match the absolute +timestamps up to the sound controller's clock accuracy, but if the user +somehow pauses the playback or seeks, all times will be shifted accordingly. + +@section tedcaptions + +JSON captions used for @url{http://www.ted.com/, TED Talks}. + +TED does not provide links to the captions, but they can be guessed from the +page. The file @file{tools/bookmarklets.html} from the FFmpeg source tree +contains a bookmarklet to expose them. +This demuxer accepts the following option: @table @option -@item -no_resync_search @var{bool} -Do not try to resynchronize by looking for a certain optional start code. +@item start_time +Set the start time of the TED talk, in milliseconds. The default is 15000 +(15s). It is used to sync the captions with the downloadable videos, because +they include a 15s intro. @end table -@c man end INPUT DEVICES +Example: convert the captions to a format most players understand: +@example +ffmpeg -i http://www.ted.com/talks/subtitles/id/1/lang/en talk1-en.srt +@end example + +@c man end DEMUXERS |