diff options
Diffstat (limited to 'doc/demuxers.texi')
-rw-r--r-- | doc/demuxers.texi | 613 |
1 files changed, 558 insertions, 55 deletions
diff --git a/doc/demuxers.texi b/doc/demuxers.texi index 2f2f464404..29a23d48b2 100644 --- a/doc/demuxers.texi +++ b/doc/demuxers.texi @@ -1,30 +1,339 @@ @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 -enabled demuxers. +The option @code{-demuxers} of the ff* tools will display the list of +enabled demuxers. Use @code{-formats} to view a combined list of +enabled demuxers and muxers. The description of some of the currently available demuxers follows. +@section aa + +Audible Format 2, 3, and 4 demuxer. + +This demuxer is used to demux Audible Format 2, 3, and 4 (.aa) files. + +@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 packets 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 -1. + +To make FFmpeg recognize the format automatically, this directive must +appear 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{inpoint @var{timestamp}} +In point of the file. When the demuxer opens the file it instantly seeks to the +specified timestamp. Seeking is done so that all streams can be presented +successfully at In point. + +This directive works best with intra frame codecs, because for non-intra frame +ones you will usually get extra packets before the actual In point and the +decoded content will most likely contain frames before In point too. + +For each file, packets before the file In point will have timestamps less than +the calculated start timestamp of the file (negative in case of the first +file), and the duration of the files (if not specified by the @code{duration} +directive) will be reduced based on their specified In point. + +Because of potential packets before the specified In point, packet timestamps +may overlap between two concatenated files. + +@item @code{outpoint @var{timestamp}} +Out point of the file. When the demuxer reaches the specified decoding +timestamp in any of the streams, it handles it as an end of file condition and +skips the current and all the remaining packets from all streams. + +Out point is exclusive, which means that the demuxer will not output packets +with a decoding timestamp greater or equal to Out point. + +This directive works best with intra frame codecs and formats where all streams +are tightly interleaved. For non-intra frame codecs you will usually get +additional packets with presentation timestamp after Out point therefore the +decoded content will most likely contain frames after Out point too. If your +streams are not tightly interleaved you may not get all the packets from all +streams before Out point and you may only will be able to decode the earliest +stream until Out point. + +The duration of the files (if not specified by the @code{duration} +directive) will be reduced based on their specified Out point. + +@item @code{file_packet_metadata @var{key=value}} +Metadata of the packets of the file. The specified metadata will be set for +each file packet. You can specify this directive multiple times to add multiple +metadata entries. + +@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. + +-1 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. +The default is 1. + +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. + +@item segment_time_metadata +If set to 1, every packet will contain the @var{lavf.concat.start_time} and the +@var{lavf.concat.duration} packet metadata values which are the start_time and +the duration of the respective file segments in the concatenated output +expressed in microseconds. The duration metadata is only set if it is known +based on the concat file. +The default is 0. + +@end table + +@subsection Examples + +@itemize +@item +Use absolute filenames and include some comments: +@example +# my first filename +file /mnt/share/file-1.wav +# my second filename including whitespace +file '/mnt/share/file 2.wav' +# my third filename including whitespace plus single quote +file '/mnt/share/file 3'\''.wav' +@end example + +@item +Allow for input format auto-probing, use safe filenames and set the duration of +the first file: +@example +ffconcat version 1.0 + +file file-1.wav +duration 20.0 + +file subdir/file-2.wav +@end example +@end itemize + +@section flv, live_flv + +Adobe Flash Video Format demuxer. + +This demuxer is used to demux FLV files and RTMP network streams. In case of live network streams, if you force format, you may use live_flv option instead of flv to survive timestamp discontinuities. + +@example +ffmpeg -f flv -i myfile.flv ... +ffmpeg -f live_flv -i rtmp://<any.server>/anything/key .... +@end example + + +@table @option +@item -flv_metadata @var{bool} +Allocate the streams according to the onMetaData array content. +@end table + +@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 max_gif_delay +Set the maximum valid delay between frames in hundredth of seconds. +Range is 0 to 65535. Default value is 65535 (nearly eleven minutes), +the maximum value allowed by the specification. + +@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 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 none +Disable pattern matching, therefore the video will only contain the specified +image. You should use this option if you do not want to create sequences from +multiple images and your filenames may contain special pattern characters. +@item sequence +Select a sequence pattern type, used to specify a sequence of files +indexed by sequential numbers. -The pattern may contain the string "%d" or "%0@var{N}d", which +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 +341,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 +353,264 @@ 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. -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: +@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 + +@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 -avconv -i img.jpeg img.png +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 +ffmpeg -framerate 10 -pattern_type glob -i "*.png" out.mkv +@end example +@end itemize + +@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 libopenmpt + +libopenmpt based module demuxer + +See @url{https://lib.openmpt.org/libopenmpt/} for more information. + +Some files have multiple subsongs (tracks) this can be set with the @option{subsong} +option. + +It accepts the following options: + @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 subsong +Set the subsong index. This can be either 'all', 'auto', or the index of the +subsong. Subsong indexes start at 0. The default is 'auto'. + +The default value is to let libopenmpt choose. + +@item layout +Set the channel layout. Valid values are 1, 2, and 4 channel layouts. +The default value is STEREO. + +@item sample_rate +Set the sample rate for libopenmpt to output. +Range is from 1000 to INT_MAX. The value default is 48000. @end table -@section applehttp +@section mov/mp4/3gp/QuickTime -Apple HTTP Live Streaming demuxer. +QuickTime / MP4 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 accepts the following options: +@table @option +@item enable_drefs +Enable loading of external tracks, disabled by default. +Enabling this can theoretically leak information in some use cases. -@section flv +@item use_absolute_path +Allows loading of external tracks via absolute paths, disabled by default. +Enabling this poses a security risk. It should only be enabled if the source +is known to be non malicious. -Adobe Flash Video Format demuxer. +@end table -This demuxer is used to demux FLV files and RTMP network streams. +@section mpegts +MPEG-2 transport stream demuxer. + +This demuxer accepts the following options: @table @option -@item -flv_metadata @var{bool} -Allocate the streams according to the onMetaData array content. +@item resync_size +Set size limit for looking up a new synchronization. Default value is +65536. + +@item fix_teletext_pts +Override 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. + +@item ts_packetsize +Output option carrying the raw packet size in bytes. +Show the detected raw packet size, cannot be set by the user. + +@item scan_all_pmts +Scan and combine all PMTs. The value is an integer with value from -1 +to 1 (-1 means automatic setting, 1 means enabled, 0 means +disabled). Default value is -1. @end table -@section asf +@section mpjpeg -Advanced Systems Format demuxer. +MJPEG encapsulated in multi-part MIME demuxer. -This demuxer is used to demux ASF files and MMS network streams. +This demuxer allows reading of MJPEG, where each frame is represented as a part of +multipart/x-mixed-replace stream. +@table @option + +@item strict_mime_boundary +Default implementation applies a relaxed standard to multi-part MIME boundary detection, +to prevent regression with numerous existing endpoints not generating a proper MIME +MJPEG stream. Turning this option on by setting it to 1 will result in a stricter check +of the boundary value. +@end table + +@section rawvideo +Raw video demuxer. + +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. + +This demuxer accepts the following options: @table @option -@item -no_resync_search @var{bool} -Do not try to resynchronize by looking for a certain optional start code. + +@item framerate +Set input video frame rate. Default value is 25. + +@item pixel_format +Set the input video pixel format. Default value is @code{yuv420p}. + +@item video_size +Set the input video size. This value must be specified explicitly. @end table -@c man end INPUT DEVICES +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 + +@section sbg + +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 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 + +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 |