diff options
Diffstat (limited to 'doc/demuxers.texi')
| -rw-r--r-- | doc/demuxers.texi | 398 |
1 files changed, 343 insertions, 55 deletions
diff --git a/doc/demuxers.texi b/doc/demuxers.texi index 2f2f464..d51b9d0 100644 --- a/doc/demuxers.texi +++ b/doc/demuxers.texi @@ -1,30 +1,209 @@ @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 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 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 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. -The pattern may contain the string "%d" or "%0@var{N}d", which +@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 +211,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 +223,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". -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: +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 + +@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 |
