Merge remote-tracking branch 'qatar/master'
authorMichael Niedermayer <michaelni@gmx.at>
Wed, 28 Aug 2013 11:03:09 +0000 (13:03 +0200)
committerMichael Niedermayer <michaelni@gmx.at>
Wed, 28 Aug 2013 11:03:09 +0000 (13:03 +0200)
* qatar/master:
  doc: document the asf demuxer

Conflicts:
doc/demuxers.texi

Merged-by: Michael Niedermayer <michaelni@gmx.at>
1  2 
doc/demuxers.texi

diff --combined doc/demuxers.texi
  @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.
  
- @item -flv_demuxer @var{bool}
 +@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 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.
 +
 +@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.
 +
 +@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.
 +
 +@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.
  
 -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
@@@ -176,11 -32,13 +187,11 @@@ filename is 0-padded and @var{N} is th
  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}, ...,
  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
  
 -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:
 +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.
 +@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 -i 'img-%03d.jpeg' -r 10 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 -start_number 100 -i 'img-%03d.jpeg' -r 10 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 -pattern_type glob -i "*.png" -r 10 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 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