segment: introduce segmented chain muxer

[libav.git] / doc / muxers.texi

@chapter Muxers
@c man begin MUXERS

Muxers are configured elements in Libav which allow writing
multimedia streams to a particular type of file.

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}.

You can disable all the muxers with the configure option
@code{--disable-muxers} and selectively enable / disable single muxers
with the options @code{--enable-muxer=@var{MUXER}} /
@code{--disable-muxer=@var{MUXER}}.

The option @code{-formats} of the ff* tools will display the list of
enabled muxers.

A description of some of the currently available muxers follows.

@anchor{crc}
@section crc

CRC (Cyclic Redundancy Check) testing format.

This muxer computes and prints the Adler-32 CRC of all the input audio
and video frames. By default audio frames are converted to signed
16-bit raw audio and video frames to raw video before computing the
CRC.

The output of the muxer consists of a single line of the form:
CRC=0x@var{CRC}, where @var{CRC} is a hexadecimal number 0-padded to
8 digits containing the CRC for all the decoded input frames.

For example to compute the CRC of the input, and store it in the file
@file{out.crc}:
@example
avconv -i INPUT -f crc out.crc
@end example

You can print the CRC to stdout with the command:
@example
avconv -i INPUT -f crc -
@end example

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
avconv -i INPUT -c:a pcm_u8 -c:v mpeg2video -f crc -
@end example

See also the @ref{framecrc} muxer.

@anchor{framecrc}
@section framecrc

Per-frame CRC (Cyclic Redundancy Check) testing format.

This muxer computes and prints the Adler-32 CRC for each decoded audio
and video frame. By default audio frames are converted to signed
16-bit raw audio and video frames to raw video before computing the
CRC.

The output of the muxer consists of a line for each audio and video
frame of the form: @var{stream_index}, @var{frame_dts},
@var{frame_size}, 0x@var{CRC}, where @var{CRC} is a hexadecimal
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
avconv -i INPUT -f framecrc out.crc
@end example

You can print the CRC of each decoded frame to stdout with the command:
@example
avconv -i INPUT -f framecrc -
@end example

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
avconv -i INPUT -c:a pcm_u8 -c:v mpeg2video -f framecrc -
@end example

See also the @ref{crc} muxer.

@anchor{image2}
@section image2

Image file muxer.

The image file muxer writes video frames to image files.

The output filenames are specified by a pattern, which can be used to
produce sequentially numbered series of files.
The pattern may contain the string "%d" or "%0@var{N}d", this string
specifies the position of the characters representing a numbering in
the filenames. If the form "%0@var{N}d" is used, the string
representing the number in each filename is 0-padded to @var{N}
digits. 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
the file list specified will contain the number 1, all the following
numbers will be sequential.

The pattern may contain a suffix which is used to automatically
determine the format of the image files to write.

For example the pattern "img-%03d.bmp" will specify a sequence of
filenames of the form @file{img-001.bmp}, @file{img-002.bmp}, ...,
@file{img-010.bmp}, etc.
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 @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
avconv -i in.avi -vsync 1 -r 1 -f image2 'img-%03d.jpeg'
@end example

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
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
avconv -i in.avi -f image2 -frames:v 1 img.jpeg
@end example

@section mpegts

MPEG transport stream muxer.

This muxer implements ISO 13818-1 and part of ETSI EN 300 468.

The muxer options are:

@table @option
@item -mpegts_original_network_id @var{number}
Set the original_network_id (default 0x0001). This is unique identifier
of a network in DVB. Its main use is in the unique identification of a
service through the path Original_Network_ID, Transport_Stream_ID.
@item -mpegts_transport_stream_id @var{number}
Set the transport_stream_id (default 0x0001). This identifies a
transponder in DVB.
@item -mpegts_service_id @var{number}
Set the service_id (default 0x0001) also known as program in DVB.
@item -mpegts_pmt_start_pid @var{number}
Set the first PID for PMT (default 0x1000, max 0x1f00).
@item -mpegts_start_pid @var{number}
Set the first PID for data packets (default 0x0100, max 0x0f00).
@end table

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 "Libav" and the default for
@code{service_name} is "Service01".

@example
avconv -i file.mpg -c copy \
     -mpegts_original_network_id 0x1122 \
     -mpegts_transport_stream_id 0x3344 \
     -mpegts_service_id 0x5566 \
     -mpegts_pmt_start_pid 0x1500 \
     -mpegts_start_pid 0x150 \
     -metadata service_provider="Some provider" \
     -metadata service_name="Some Channel" \
     -y out.ts
@end example

@section null

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 @command{avconv} you can use the
command:
@example
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 @command{avconv}
syntax.

Alternatively you can write the command as:
@example
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.
@end table

@example
avconv -i in.mkv -c copy -map 0 -f segment -list out.list out%03d.nut
@end example


@c man end MUXERS