| @chapter Demuxers |
| @c man begin DEMUXERS |
| |
| Demuxers are configured elements in FFmpeg that can read the |
| multimedia streams from a particular type of file. |
| |
| When you configure your FFmpeg build, all the supported demuxers |
| are enabled by default. You can list all available ones using the |
| configure option @code{--list-demuxers}. |
| |
| You can disable all the demuxers using the configure option |
| @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 @code{-formats} of the ff* tools will display the list of |
| enabled demuxers. |
| |
| 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 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 -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{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. |
| |
| @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 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. |
| |
| 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 |
| 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 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 @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}, ..., |
| @file{img-010.bmp}, etc.; the pattern "i%%m%%g-%d.jpg" will match a |
| 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. |
| |
| 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 |
| |
| @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 |
| ffmpeg -framerate 10 -i 'img-%03d.jpeg' out.mkv |
| @end example |
| |
| @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 |
| ffmpeg -framerate 10 -pattern_type glob -i "*.png" out.mkv |
| @end example |
| @end itemize |
| |
| @section mov/mp4/3gp/Quicktme |
| |
| Quicktime / MP4 demuxer. |
| |
| 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. |
| |
| @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. |
| |
| @end table |
| |
| @section mpegts |
| |
| MPEG-2 transport stream demuxer. |
| |
| This demuxer accepts the following options: |
| @table @option |
| @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 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 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 |
| |
| 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 |