configure: remove support for -n flag in print_enabled()
[ffmpeg.git] / doc / muxers.texi
index e7cfc4a..4bb6d56 100644 (file)
@@ -1,10 +1,10 @@
 @chapter Muxers
 @c man begin MUXERS
 
-Muxers are configured elements in FFmpeg which allow writing
+Muxers are configured elements in Libav which allow writing
 multimedia streams to a particular type of file.
 
-When you configure your FFmpeg build, all the supported muxers
+When you configure your Libav build, all the supported muxers
 are enabled by default. You can list all available muxers using the
 configure option @code{--list-muxers}.
 
@@ -35,23 +35,23 @@ CRC=0x@var{CRC}, where @var{CRC} is a hexadecimal number 0-padded to
 For example to compute the CRC of the input, and store it in the file
 @file{out.crc}:
 @example
-ffmpeg -i INPUT -f crc out.crc
+avconv -i INPUT -f crc out.crc
 @end example
 
 You can print the CRC to stdout with the command:
 @example
-ffmpeg -i INPUT -f crc -
+avconv -i INPUT -f crc -
 @end example
 
-You can select the output format of each frame with @file{ffmpeg} by
+You can select the output format of each frame with @command{avconv} by
 specifying the audio and video codec and format. For example to
 compute the CRC of the input audio converted to PCM unsigned 8-bit
 and the input video converted to MPEG-2 video, use the command:
 @example
-ffmpeg -i INPUT -acodec pcm_u8 -vcodec mpeg2video -f crc -
+avconv -i INPUT -c:a pcm_u8 -c:v mpeg2video -f crc -
 @end example
 
-See also the @code{framecrc} muxer (@pxref{framecrc}).
+See also the @ref{framecrc} muxer.
 
 @anchor{framecrc}
 @section framecrc
@@ -71,25 +71,26 @@ number 0-padded to 8 digits containing the CRC of the decoded frame.
 For example to compute the CRC of each decoded frame in the input, and
 store it in the file @file{out.crc}:
 @example
-ffmpeg -i INPUT -f framecrc out.crc
+avconv -i INPUT -f framecrc out.crc
 @end example
 
 You can print the CRC of each decoded frame to stdout with the command:
 @example
-ffmpeg -i INPUT -f framecrc -
+avconv -i INPUT -f framecrc -
 @end example
 
-You can select the output format of each frame with @file{ffmpeg} by
+You can select the output format of each frame with @command{avconv} by
 specifying the audio and video codec and format. For example, to
 compute the CRC of each decoded input audio frame converted to PCM
 unsigned 8-bit and of each decoded input video frame converted to
 MPEG-2 video, use the command:
 @example
-ffmpeg -i INPUT -acodec pcm_u8 -vcodec mpeg2video -f framecrc -
+avconv -i INPUT -c:a pcm_u8 -c:v mpeg2video -f framecrc -
 @end example
 
-See also the @code{crc} muxer (@pxref{crc}).
+See also the @ref{crc} muxer.
 
+@anchor{image2}
 @section image2
 
 Image file muxer.
@@ -119,26 +120,94 @@ The pattern "img%%-%d.jpg" will specify a sequence of filenames of the
 form @file{img%-1.jpg}, @file{img%-2.jpg}, ..., @file{img%-10.jpg},
 etc.
 
-The following example shows how to use @file{ffmpeg} for creating a
+The following example shows how to use @command{avconv} for creating a
 sequence of files @file{img-001.jpeg}, @file{img-002.jpeg}, ...,
 taking one image every second from the input video:
 @example
-ffmpeg -i in.avi -r 1 -f image2 'img-%03d.jpeg'
+avconv -i in.avi -vsync 1 -r 1 -f image2 'img-%03d.jpeg'
 @end example
 
-Note that with @file{ffmpeg}, if the format is not specified with the
+Note that with @command{avconv}, if the format is not specified with the
 @code{-f} option and the output filename specifies an image file
 format, the image2 muxer is automatically selected, so the previous
 command can be written as:
 @example
-ffmpeg -i in.avi -r 1 'img-%03d.jpeg'
+avconv -i in.avi -vsync 1 -r 1 'img-%03d.jpeg'
 @end example
 
 Note also that the pattern must not necessarily contain "%d" or
 "%0@var{N}d", for example to create a single image file
 @file{img.jpeg} from the input video you can employ the command:
 @example
-ffmpeg -i in.avi -f image2 -vframes 1 img.jpeg
+avconv -i in.avi -f image2 -frames:v 1 img.jpeg
+@end example
+
+@section MOV/MP4/ISMV
+
+The mov/mp4/ismv muxer supports fragmentation. Normally, a MOV/MP4
+file has all the metadata about all packets stored in one location
+(written at the end of the file, it can be moved to the start for
+better playback using the @command{qt-faststart} tool). A fragmented
+file consists of a number of fragments, where packets and metadata
+about these packets are stored together. Writing a fragmented
+file has the advantage that the file is decodable even if the
+writing is interrupted (while a normal MOV/MP4 is undecodable if
+it is not properly finished), and it requires less memory when writing
+very long files (since writing normal MOV/MP4 files stores info about
+every single packet in memory until the file is closed). The downside
+is that it is less compatible with other applications.
+
+Fragmentation is enabled by setting one of the AVOptions that define
+how to cut the file into fragments:
+
+@table @option
+@item -movflags frag_keyframe
+Start a new fragment at each video keyframe.
+@item -frag_duration @var{duration}
+Create fragments that are @var{duration} microseconds long.
+@item -frag_size @var{size}
+Create fragments that contain up to @var{size} bytes of payload data.
+@item -movflags frag_custom
+Allow the caller to manually choose when to cut fragments, by
+calling @code{av_write_frame(ctx, NULL)} to write a fragment with
+the packets written so far. (This is only useful with other
+applications integrating libavformat, not from @command{avconv}.)
+@item -min_frag_duration @var{duration}
+Don't create fragments that are shorter than @var{duration} microseconds long.
+@end table
+
+If more than one condition is specified, fragments are cut when
+one of the specified conditions is fulfilled. The exception to this is
+@code{-min_frag_duration}, which has to be fulfilled for any of the other
+conditions to apply.
+
+Additionally, the way the output file is written can be adjusted
+through a few other options:
+
+@table @option
+@item -movflags empty_moov
+Write an initial moov atom directly at the start of the file, without
+describing any samples in it. Generally, an mdat/moov pair is written
+at the start of the file, as a normal MOV/MP4 file, containing only
+a short portion of the file. With this option set, there is no initial
+mdat atom, and the moov atom only describes the tracks but has
+a zero duration.
+
+Files written with this option set do not work in QuickTime.
+This option is implicitly set when writing ismv (Smooth Streaming) files.
+@item -movflags separate_moof
+Write a separate moof (movie fragment) atom for each track. Normally,
+packets for all tracks are written in a moof atom (which is slightly
+more efficient), but with this option set, the muxer writes one moof/mdat
+pair for each track, making it easier to separate tracks.
+
+This option is implicitly set when writing ismv (Smooth Streaming) files.
+@end table
+
+Smooth Streaming content can be pushed in real time to a publishing
+point on IIS with this muxer. Example:
+@example
+avconv -re @var{<normal input/transcoding options>} -movflags isml+frag_keyframe -f ismv http://server/publishingpoint.isml/Streams(Encoder1)
 @end example
 
 @section mpegts
@@ -167,11 +236,11 @@ Set the first PID for data packets (default 0x0100, max 0x0f00).
 
 The recognized metadata settings in mpegts muxer are @code{service_provider}
 and @code{service_name}. If they are not set the default for
-@code{service_provider} is "FFmpeg" and the default for
+@code{service_provider} is "Libav" and the default for
 @code{service_name} is "Service01".
 
 @example
-ffmpeg -i file.mpg -acodec copy -vcodec copy \
+avconv -i file.mpg -c copy \
      -mpegts_original_network_id 0x1122 \
      -mpegts_transport_stream_id 0x3344 \
      -mpegts_service_id 0x5566 \
@@ -189,19 +258,149 @@ Null muxer.
 This muxer does not generate any output file, it is mainly useful for
 testing or benchmarking purposes.
 
-For example to benchmark decoding with @file{ffmpeg} you can use the
+For example to benchmark decoding with @command{avconv} you can use the
 command:
 @example
-ffmpeg -benchmark -i INPUT -f null out.null
+avconv -benchmark -i INPUT -f null out.null
 @end example
 
 Note that the above command does not read or write the @file{out.null}
-file, but specifying the output file is required by the @file{ffmpeg}
+file, but specifying the output file is required by the @command{avconv}
 syntax.
 
 Alternatively you can write the command as:
 @example
-ffmpeg -benchmark -i INPUT -f null -
+avconv -benchmark -i INPUT -f null -
+@end example
+
+@section matroska
+
+Matroska container muxer.
+
+This muxer implements the matroska and webm container specs.
+
+The recognized metadata settings in this muxer are:
+
+@table @option
+
+@item title=@var{title name}
+Name provided to a single track
+@end table
+
+@table @option
+
+@item language=@var{language name}
+Specifies the language of the track in the Matroska languages form
+@end table
+
+@table @option
+
+@item STEREO_MODE=@var{mode}
+Stereo 3D video layout of two views in a single video track
+@table @option
+@item mono
+video is not stereo
+@item left_right
+Both views are arranged side by side, Left-eye view is on the left
+@item bottom_top
+Both views are arranged in top-bottom orientation, Left-eye view is at bottom
+@item top_bottom
+Both views are arranged in top-bottom orientation, Left-eye view is on top
+@item checkerboard_rl
+Each view is arranged in a checkerboard interleaved pattern, Left-eye view being first
+@item checkerboard_lr
+Each view is arranged in a checkerboard interleaved pattern, Right-eye view being first
+@item row_interleaved_rl
+Each view is constituted by a row based interleaving, Right-eye view is first row
+@item row_interleaved_lr
+Each view is constituted by a row based interleaving, Left-eye view is first row
+@item col_interleaved_rl
+Both views are arranged in a column based interleaving manner, Right-eye view is first column
+@item col_interleaved_lr
+Both views are arranged in a column based interleaving manner, Left-eye view is first column
+@item anaglyph_cyan_red
+All frames are in anaglyph format viewable through red-cyan filters
+@item right_left
+Both views are arranged side by side, Right-eye view is on the left
+@item anaglyph_green_magenta
+All frames are in anaglyph format viewable through green-magenta filters
+@item block_lr
+Both eyes laced in one Block, Left-eye view is first
+@item block_rl
+Both eyes laced in one Block, Right-eye view is first
+@end table
+@end table
+
+For example a 3D WebM clip can be created using the following command line:
+@example
+avconv -i sample_left_right_clip.mpg -an -c:v libvpx -metadata STEREO_MODE=left_right -y stereo_clip.webm
+@end example
+
+@section segment
+
+Basic stream segmenter.
+
+The segmenter muxer outputs streams to a number of separate files of nearly
+fixed duration. Output filename pattern can be set in a fashion similar to
+@ref{image2}.
+
+Every segment starts with a video keyframe, if a video stream is present.
+The segment muxer works best with a single constant frame rate video.
+
+Optionally it can generate a flat list of the created segments, one segment
+per line.
+
+@table @option
+@item segment_format @var{format}
+Override the inner container format, by default it is guessed by the filename
+extension.
+@item segment_time @var{t}
+Set segment duration to @var{t} seconds.
+@item segment_list @var{name}
+Generate also a listfile named @var{name}.
+@item segment_list_size @var{size}
+Overwrite the listfile once it reaches @var{size} entries.
+@item segment_wrap @var{limit}
+Wrap around segment index once it reaches @var{limit}.
+@end table
+
+@example
+avconv -i in.mkv -c copy -map 0 -f segment -list out.list out%03d.nut
+@end example
+
+@section mp3
+
+The MP3 muxer writes a raw MP3 stream with an ID3v2 header at the beginning and
+optionally an ID3v1 tag at the end. ID3v2.3 and ID3v2.4 are supported, the
+@code{id3v2_version} option controls which one is used. The legacy ID3v1 tag is
+not written by default, but may be enabled with the @code{write_id3v1} option.
+
+For seekable output the muxer also writes a Xing frame at the beginning, which
+contains the number of frames in the file. It is useful for computing duration
+of VBR files.
+
+The muxer supports writing ID3v2 attached pictures (APIC frames). The pictures
+are supplied to the muxer in form of a video stream with a single packet. There
+can be any number of those streams, each will correspond to a single APIC frame.
+The stream metadata tags @var{title} and @var{comment} map to APIC
+@var{description} and @var{picture type} respectively. See
+@url{http://id3.org/id3v2.4.0-frames} for allowed picture types.
+
+Note that the APIC frames must be written at the beginning, so the muxer will
+buffer the audio frames until it gets all the pictures. It is therefore advised
+to provide the pictures as soon as possible to avoid excessive buffering.
+
+Examples:
+
+Write an mp3 with an ID3v2.3 header and an ID3v1 footer:
+@example
+avconv -i INPUT -id3v2_version 3 -write_id3v1 1 out.mp3
+@end example
+
+Attach a picture to an mp3:
+@example
+avconv -i input.mp3 -i cover.png -c copy -metadata:s:v title="Album cover"
+-metadata:s:v comment="Cover (Front)" out.mp3
 @end example
 
 @c man end MUXERS