segment: introduce segmented chain muxer
[libav.git] / doc / muxers.texi
CommitLineData
85466e1e
SS
1@chapter Muxers
2@c man begin MUXERS
3
f8a45fa1 4Muxers are configured elements in Libav which allow writing
85466e1e
SS
5multimedia streams to a particular type of file.
6
f8a45fa1 7When you configure your Libav build, all the supported muxers
85466e1e
SS
8are enabled by default. You can list all available muxers using the
9configure option @code{--list-muxers}.
10
11You can disable all the muxers with the configure option
12@code{--disable-muxers} and selectively enable / disable single muxers
13with the options @code{--enable-muxer=@var{MUXER}} /
14@code{--disable-muxer=@var{MUXER}}.
15
16The option @code{-formats} of the ff* tools will display the list of
17enabled muxers.
18
19A description of some of the currently available muxers follows.
20
77d4ed7a 21@anchor{crc}
a4effe43
SS
22@section crc
23
24CRC (Cyclic Redundancy Check) testing format.
25
26This muxer computes and prints the Adler-32 CRC of all the input audio
27and video frames. By default audio frames are converted to signed
2816-bit raw audio and video frames to raw video before computing the
29CRC.
30
31The output of the muxer consists of a single line of the form:
32CRC=0x@var{CRC}, where @var{CRC} is a hexadecimal number 0-padded to
338 digits containing the CRC for all the decoded input frames.
34
35For example to compute the CRC of the input, and store it in the file
36@file{out.crc}:
37@example
d5837d7f 38avconv -i INPUT -f crc out.crc
a4effe43
SS
39@end example
40
41You can print the CRC to stdout with the command:
42@example
d5837d7f 43avconv -i INPUT -f crc -
a4effe43
SS
44@end example
45
d5837d7f 46You can select the output format of each frame with @command{avconv} by
a4effe43
SS
47specifying the audio and video codec and format. For example to
48compute the CRC of the input audio converted to PCM unsigned 8-bit
49and the input video converted to MPEG-2 video, use the command:
50@example
d5837d7f 51avconv -i INPUT -c:a pcm_u8 -c:v mpeg2video -f crc -
a4effe43
SS
52@end example
53
4c989761 54See also the @ref{framecrc} muxer.
77d4ed7a
SS
55
56@anchor{framecrc}
57@section framecrc
58
59Per-frame CRC (Cyclic Redundancy Check) testing format.
60
61This muxer computes and prints the Adler-32 CRC for each decoded audio
62and video frame. By default audio frames are converted to signed
6316-bit raw audio and video frames to raw video before computing the
64CRC.
65
66The output of the muxer consists of a line for each audio and video
67frame of the form: @var{stream_index}, @var{frame_dts},
68@var{frame_size}, 0x@var{CRC}, where @var{CRC} is a hexadecimal
69number 0-padded to 8 digits containing the CRC of the decoded frame.
70
71For example to compute the CRC of each decoded frame in the input, and
72store it in the file @file{out.crc}:
73@example
d5837d7f 74avconv -i INPUT -f framecrc out.crc
77d4ed7a
SS
75@end example
76
77You can print the CRC of each decoded frame to stdout with the command:
78@example
d5837d7f 79avconv -i INPUT -f framecrc -
77d4ed7a
SS
80@end example
81
d5837d7f 82You can select the output format of each frame with @command{avconv} by
77d4ed7a
SS
83specifying the audio and video codec and format. For example, to
84compute the CRC of each decoded input audio frame converted to PCM
85unsigned 8-bit and of each decoded input video frame converted to
86MPEG-2 video, use the command:
87@example
d5837d7f 88avconv -i INPUT -c:a pcm_u8 -c:v mpeg2video -f framecrc -
77d4ed7a
SS
89@end example
90
4c989761 91See also the @ref{crc} muxer.
77d4ed7a 92
02e8f032 93@anchor{image2}
e771d2e3
SS
94@section image2
95
96Image file muxer.
97
0cad24ce 98The image file muxer writes video frames to image files.
e771d2e3 99
0cad24ce
SS
100The output filenames are specified by a pattern, which can be used to
101produce sequentially numbered series of files.
102The pattern may contain the string "%d" or "%0@var{N}d", this string
e771d2e3 103specifies the position of the characters representing a numbering in
0cad24ce 104the filenames. If the form "%0@var{N}d" is used, the string
e771d2e3
SS
105representing the number in each filename is 0-padded to @var{N}
106digits. The literal character '%' can be specified in the pattern with
107the string "%%".
108
109If the pattern contains "%d" or "%0@var{N}d", the first filename of
110the file list specified will contain the number 1, all the following
111numbers will be sequential.
112
113The pattern may contain a suffix which is used to automatically
114determine the format of the image files to write.
115
116For example the pattern "img-%03d.bmp" will specify a sequence of
117filenames of the form @file{img-001.bmp}, @file{img-002.bmp}, ...,
118@file{img-010.bmp}, etc.
119The pattern "img%%-%d.jpg" will specify a sequence of filenames of the
120form @file{img%-1.jpg}, @file{img%-2.jpg}, ..., @file{img%-10.jpg},
121etc.
122
d5837d7f 123The following example shows how to use @command{avconv} for creating a
e771d2e3
SS
124sequence of files @file{img-001.jpeg}, @file{img-002.jpeg}, ...,
125taking one image every second from the input video:
126@example
d5837d7f 127avconv -i in.avi -vsync 1 -r 1 -f image2 'img-%03d.jpeg'
e771d2e3
SS
128@end example
129
d5837d7f 130Note that with @command{avconv}, if the format is not specified with the
e771d2e3
SS
131@code{-f} option and the output filename specifies an image file
132format, the image2 muxer is automatically selected, so the previous
133command can be written as:
134@example
d5837d7f 135avconv -i in.avi -vsync 1 -r 1 'img-%03d.jpeg'
e771d2e3
SS
136@end example
137
138Note also that the pattern must not necessarily contain "%d" or
139"%0@var{N}d", for example to create a single image file
140@file{img.jpeg} from the input video you can employ the command:
141@example
d5837d7f 142avconv -i in.avi -f image2 -frames:v 1 img.jpeg
e771d2e3
SS
143@end example
144
445996aa
GC
145@section mpegts
146
147MPEG transport stream muxer.
148
149This muxer implements ISO 13818-1 and part of ETSI EN 300 468.
150
151The muxer options are:
152
153@table @option
154@item -mpegts_original_network_id @var{number}
155Set the original_network_id (default 0x0001). This is unique identifier
156of a network in DVB. Its main use is in the unique identification of a
157service through the path Original_Network_ID, Transport_Stream_ID.
158@item -mpegts_transport_stream_id @var{number}
159Set the transport_stream_id (default 0x0001). This identifies a
160transponder in DVB.
161@item -mpegts_service_id @var{number}
162Set the service_id (default 0x0001) also known as program in DVB.
163@item -mpegts_pmt_start_pid @var{number}
164Set the first PID for PMT (default 0x1000, max 0x1f00).
165@item -mpegts_start_pid @var{number}
166Set the first PID for data packets (default 0x0100, max 0x0f00).
167@end table
168
169The recognized metadata settings in mpegts muxer are @code{service_provider}
170and @code{service_name}. If they are not set the default for
6001dad6 171@code{service_provider} is "Libav" and the default for
445996aa
GC
172@code{service_name} is "Service01".
173
174@example
d5837d7f 175avconv -i file.mpg -c copy \
445996aa
GC
176 -mpegts_original_network_id 0x1122 \
177 -mpegts_transport_stream_id 0x3344 \
178 -mpegts_service_id 0x5566 \
179 -mpegts_pmt_start_pid 0x1500 \
180 -mpegts_start_pid 0x150 \
181 -metadata service_provider="Some provider" \
182 -metadata service_name="Some Channel" \
183 -y out.ts
184@end example
185
f4acb837
SS
186@section null
187
188Null muxer.
189
190This muxer does not generate any output file, it is mainly useful for
191testing or benchmarking purposes.
192
d5837d7f 193For example to benchmark decoding with @command{avconv} you can use the
f4acb837
SS
194command:
195@example
d5837d7f 196avconv -benchmark -i INPUT -f null out.null
f4acb837
SS
197@end example
198
199Note that the above command does not read or write the @file{out.null}
d5837d7f 200file, but specifying the output file is required by the @command{avconv}
f4acb837
SS
201syntax.
202
203Alternatively you can write the command as:
204@example
d5837d7f 205avconv -benchmark -i INPUT -f null -
f4acb837
SS
206@end example
207
945dda41
AA
208@section matroska
209
210Matroska container muxer.
211
212This muxer implements the matroska and webm container specs.
213
214The recognized metadata settings in this muxer are:
215
216@table @option
217
218@item title=@var{title name}
219Name provided to a single track
220@end table
221
222@table @option
223
224@item language=@var{language name}
225Specifies the language of the track in the Matroska languages form
226@end table
227
228@table @option
229
230@item STEREO_MODE=@var{mode}
231Stereo 3D video layout of two views in a single video track
232@table @option
233@item mono
234video is not stereo
235@item left_right
236Both views are arranged side by side, Left-eye view is on the left
237@item bottom_top
238Both views are arranged in top-bottom orientation, Left-eye view is at bottom
239@item top_bottom
240Both views are arranged in top-bottom orientation, Left-eye view is on top
241@item checkerboard_rl
242Each view is arranged in a checkerboard interleaved pattern, Left-eye view being first
243@item checkerboard_lr
244Each view is arranged in a checkerboard interleaved pattern, Right-eye view being first
245@item row_interleaved_rl
246Each view is constituted by a row based interleaving, Right-eye view is first row
247@item row_interleaved_lr
248Each view is constituted by a row based interleaving, Left-eye view is first row
249@item col_interleaved_rl
250Both views are arranged in a column based interleaving manner, Right-eye view is first column
251@item col_interleaved_lr
252Both views are arranged in a column based interleaving manner, Left-eye view is first column
253@item anaglyph_cyan_red
254All frames are in anaglyph format viewable through red-cyan filters
255@item right_left
256Both views are arranged side by side, Right-eye view is on the left
257@item anaglyph_green_magenta
258All frames are in anaglyph format viewable through green-magenta filters
259@item block_lr
260Both eyes laced in one Block, Left-eye view is first
261@item block_rl
262Both eyes laced in one Block, Right-eye view is first
263@end table
264@end table
265
266For example a 3D WebM clip can be created using the following command line:
267@example
d5837d7f 268avconv -i sample_left_right_clip.mpg -an -c:v libvpx -metadata STEREO_MODE=left_right -y stereo_clip.webm
945dda41
AA
269@end example
270
02e8f032
LB
271@section segment
272
273Basic stream segmenter.
274
275The segmenter muxer outputs streams to a number of separate files of nearly
276fixed duration. Output filename pattern can be set in a fashion similar to
277@ref{image2}.
278
279Every segment starts with a video keyframe, if a video stream is present.
280The segment muxer works best with a single constant frame rate video.
281
282Optionally it can generate a flat list of the created segments, one segment
283per line.
284
285@table @option
286@item segment_format @var{format}
287Override the inner container format, by default it is guessed by the filename
288extension.
289@item segment_time @var{t}
290Set segment duration to @var{t} seconds.
291@item segment_list @var{name}
292Generate also a listfile named @var{name}.
293@item segment_list_size @var{size}
294Overwrite the listfile once it reaches @var{size} entries.
295@end table
296
297@example
298avconv -i in.mkv -c copy -map 0 -f segment -list out.list out%03d.nut
299@end example
300
301
85466e1e 302@c man end MUXERS