doc/muxers.texi

   1 @chapter Muxers
   2 @c man begin MUXERS
   3
   4 Muxers are configured elements in Libav which allow writing
   5 multimedia streams to a particular type of file.
   6
   7 When you configure your Libav build, all the supported muxers
   8 are enabled by default. You can list all available muxers using the
   9 configure option @code{--list-muxers}.
  10
  11 You can disable all the muxers with the configure option
  12 @code{--disable-muxers} and selectively enable / disable single muxers
  13 with the options @code{--enable-muxer=@var{MUXER}} /
  14 @code{--disable-muxer=@var{MUXER}}.
  15
  16 The option @code{-formats} of the ff* tools will display the list of
  17 enabled muxers.
  18
  19 A description of some of the currently available muxers follows.
  20
  21 @anchor{crc}
  22 @section crc
  23
  24 CRC (Cyclic Redundancy Check) testing format.
  25
  26 This muxer computes and prints the Adler-32 CRC of all the input audio
  27 and video frames. By default audio frames are converted to signed
  28 16-bit raw audio and video frames to raw video before computing the
  29 CRC.
  30
  31 The output of the muxer consists of a single line of the form:
  32 CRC=0x@var{CRC}, where @var{CRC} is a hexadecimal number 0-padded to
  33 8 digits containing the CRC for all the decoded input frames.
  34
  35 For example to compute the CRC of the input, and store it in the file
  36 @file{out.crc}:
  37 @example
  38 avconv -i INPUT -f crc out.crc
  39 @end example
  40
  41 You can print the CRC to stdout with the command:
  42 @example
  43 avconv -i INPUT -f crc -
  44 @end example
  45
  46 You can select the output format of each frame with @command{avconv} by
  47 specifying the audio and video codec and format. For example to
  48 compute the CRC of the input audio converted to PCM unsigned 8-bit
  49 and the input video converted to MPEG-2 video, use the command:
  50 @example
  51 avconv -i INPUT -c:a pcm_u8 -c:v mpeg2video -f crc -
  52 @end example
  53
  54 See also the @ref{framecrc} muxer.
  55
  56 @anchor{framecrc}
  57 @section framecrc
  58
  59 Per-frame CRC (Cyclic Redundancy Check) testing format.
  60
  61 This muxer computes and prints the Adler-32 CRC for each decoded audio
  62 and video frame. By default audio frames are converted to signed
  63 16-bit raw audio and video frames to raw video before computing the
  64 CRC.
  65
  66 The output of the muxer consists of a line for each audio and video
  67 frame of the form: @var{stream_index}, @var{frame_dts},
  68 @var{frame_size}, 0x@var{CRC}, where @var{CRC} is a hexadecimal
  69 number 0-padded to 8 digits containing the CRC of the decoded frame.
  70
  71 For example to compute the CRC of each decoded frame in the input, and
  72 store it in the file @file{out.crc}:
  73 @example
  74 avconv -i INPUT -f framecrc out.crc
  75 @end example
  76
  77 You can print the CRC of each decoded frame to stdout with the command:
  78 @example
  79 avconv -i INPUT -f framecrc -
  80 @end example
  81
  82 You can select the output format of each frame with @command{avconv} by
  83 specifying the audio and video codec and format. For example, to
  84 compute the CRC of each decoded input audio frame converted to PCM
  85 unsigned 8-bit and of each decoded input video frame converted to
  86 MPEG-2 video, use the command:
  87 @example
  88 avconv -i INPUT -c:a pcm_u8 -c:v mpeg2video -f framecrc -
  89 @end example
  90
  91 See also the @ref{crc} muxer.
  92
  93 @anchor{hls}
  94 @section hls
  95
  96 Apple HTTP Live Streaming muxer that segments MPEG-TS according to
  97 the HTTP Live Streaming specification.
  98
  99 It creates a playlist file and numbered segment files. The output
 100 filename specifies the playlist filename; the segment filenames
 101 receive the same basename as the playlist, a sequential number and
 102 a .ts extension.
 103
 104 @example
 105 avconv -i in.nut out.m3u8
 106 @end example
 107
 108 @table @option
 109 @item -hls_time segment length in seconds
 110 @item -hls_list_size maximum number of playlist entries
 111 @item -hls_wrap number after which index wraps
 112 @end table
 113
 114 @anchor{image2}
 115 @section image2
 116
 117 Image file muxer.
 118
 119 The image file muxer writes video frames to image files.
 120
 121 The output filenames are specified by a pattern, which can be used to
 122 produce sequentially numbered series of files.
 123 The pattern may contain the string "%d" or "%0@var{N}d", this string
 124 specifies the position of the characters representing a numbering in
 125 the filenames. If the form "%0@var{N}d" is used, the string
 126 representing the number in each filename is 0-padded to @var{N}
 127 digits. The literal character '%' can be specified in the pattern with
 128 the string "%%".
 129
 130 If the pattern contains "%d" or "%0@var{N}d", the first filename of
 131 the file list specified will contain the number 1, all the following
 132 numbers will be sequential.
 133
 134 The pattern may contain a suffix which is used to automatically
 135 determine the format of the image files to write.
 136
 137 For example the pattern "img-%03d.bmp" will specify a sequence of
 138 filenames of the form @file{img-001.bmp}, @file{img-002.bmp}, ...,
 139 @file{img-010.bmp}, etc.
 140 The pattern "img%%-%d.jpg" will specify a sequence of filenames of the
 141 form @file{img%-1.jpg}, @file{img%-2.jpg}, ..., @file{img%-10.jpg},
 142 etc.
 143
 144 The following example shows how to use @command{avconv} for creating a
 145 sequence of files @file{img-001.jpeg}, @file{img-002.jpeg}, ...,
 146 taking one image every second from the input video:
 147 @example
 148 avconv -i in.avi -vsync 1 -r 1 -f image2 'img-%03d.jpeg'
 149 @end example
 150
 151 Note that with @command{avconv}, if the format is not specified with the
 152 @code{-f} option and the output filename specifies an image file
 153 format, the image2 muxer is automatically selected, so the previous
 154 command can be written as:
 155 @example
 156 avconv -i in.avi -vsync 1 -r 1 'img-%03d.jpeg'
 157 @end example
 158
 159 Note also that the pattern must not necessarily contain "%d" or
 160 "%0@var{N}d", for example to create a single image file
 161 @file{img.jpeg} from the input video you can employ the command:
 162 @example
 163 avconv -i in.avi -f image2 -frames:v 1 img.jpeg
 164 @end example
 165
 166 @section MOV/MP4/ISMV
 167
 168 The mov/mp4/ismv muxer supports fragmentation. Normally, a MOV/MP4
 169 file has all the metadata about all packets stored in one location
 170 (written at the end of the file, it can be moved to the start for
 171 better playback using the @command{qt-faststart} tool). A fragmented
 172 file consists of a number of fragments, where packets and metadata
 173 about these packets are stored together. Writing a fragmented
 174 file has the advantage that the file is decodable even if the
 175 writing is interrupted (while a normal MOV/MP4 is undecodable if
 176 it is not properly finished), and it requires less memory when writing
 177 very long files (since writing normal MOV/MP4 files stores info about
 178 every single packet in memory until the file is closed). The downside
 179 is that it is less compatible with other applications.
 180
 181 Fragmentation is enabled by setting one of the AVOptions that define
 182 how to cut the file into fragments:
 183
 184 @table @option
 185 @item -movflags frag_keyframe
 186 Start a new fragment at each video keyframe.
 187 @item -frag_duration @var{duration}
 188 Create fragments that are @var{duration} microseconds long.
 189 @item -frag_size @var{size}
 190 Create fragments that contain up to @var{size} bytes of payload data.
 191 @item -movflags frag_custom
 192 Allow the caller to manually choose when to cut fragments, by
 193 calling @code{av_write_frame(ctx, NULL)} to write a fragment with
 194 the packets written so far. (This is only useful with other
 195 applications integrating libavformat, not from @command{avconv}.)
 196 @item -min_frag_duration @var{duration}
 197 Don't create fragments that are shorter than @var{duration} microseconds long.
 198 @end table
 199
 200 If more than one condition is specified, fragments are cut when
 201 one of the specified conditions is fulfilled. The exception to this is
 202 @code{-min_frag_duration}, which has to be fulfilled for any of the other
 203 conditions to apply.
 204
 205 Additionally, the way the output file is written can be adjusted
 206 through a few other options:
 207
 208 @table @option
 209 @item -movflags empty_moov
 210 Write an initial moov atom directly at the start of the file, without
 211 describing any samples in it. Generally, an mdat/moov pair is written
 212 at the start of the file, as a normal MOV/MP4 file, containing only
 213 a short portion of the file. With this option set, there is no initial
 214 mdat atom, and the moov atom only describes the tracks but has
 215 a zero duration.
 216
 217 Files written with this option set do not work in QuickTime.
 218 This option is implicitly set when writing ismv (Smooth Streaming) files.
 219 @item -movflags separate_moof
 220 Write a separate moof (movie fragment) atom for each track. Normally,
 221 packets for all tracks are written in a moof atom (which is slightly
 222 more efficient), but with this option set, the muxer writes one moof/mdat
 223 pair for each track, making it easier to separate tracks.
 224
 225 This option is implicitly set when writing ismv (Smooth Streaming) files.
 226 @end table
 227
 228 Smooth Streaming content can be pushed in real time to a publishing
 229 point on IIS with this muxer. Example:
 230 @example
 231 avconv -re @var{<normal input/transcoding options>} -movflags isml+frag_keyframe -f ismv http://server/publishingpoint.isml/Streams(Encoder1)
 232 @end example
 233
 234 @section mpegts
 235
 236 MPEG transport stream muxer.
 237
 238 This muxer implements ISO 13818-1 and part of ETSI EN 300 468.
 239
 240 The muxer options are:
 241
 242 @table @option
 243 @item -mpegts_original_network_id @var{number}
 244 Set the original_network_id (default 0x0001). This is unique identifier
 245 of a network in DVB. Its main use is in the unique identification of a
 246 service through the path Original_Network_ID, Transport_Stream_ID.
 247 @item -mpegts_transport_stream_id @var{number}
 248 Set the transport_stream_id (default 0x0001). This identifies a
 249 transponder in DVB.
 250 @item -mpegts_service_id @var{number}
 251 Set the service_id (default 0x0001) also known as program in DVB.
 252 @item -mpegts_pmt_start_pid @var{number}
 253 Set the first PID for PMT (default 0x1000, max 0x1f00).
 254 @item -mpegts_start_pid @var{number}
 255 Set the first PID for data packets (default 0x0100, max 0x0f00).
 256 @end table
 257
 258 The recognized metadata settings in mpegts muxer are @code{service_provider}
 259 and @code{service_name}. If they are not set the default for
 260 @code{service_provider} is "Libav" and the default for
 261 @code{service_name} is "Service01".
 262
 263 @example
 264 avconv -i file.mpg -c copy \
 265      -mpegts_original_network_id 0x1122 \
 266      -mpegts_transport_stream_id 0x3344 \
 267      -mpegts_service_id 0x5566 \
 268      -mpegts_pmt_start_pid 0x1500 \
 269      -mpegts_start_pid 0x150 \
 270      -metadata service_provider="Some provider" \
 271      -metadata service_name="Some Channel" \
 272      -y out.ts
 273 @end example
 274
 275 @section null
 276
 277 Null muxer.
 278
 279 This muxer does not generate any output file, it is mainly useful for
 280 testing or benchmarking purposes.
 281
 282 For example to benchmark decoding with @command{avconv} you can use the
 283 command:
 284 @example
 285 avconv -benchmark -i INPUT -f null out.null
 286 @end example
 287
 288 Note that the above command does not read or write the @file{out.null}
 289 file, but specifying the output file is required by the @command{avconv}
 290 syntax.
 291
 292 Alternatively you can write the command as:
 293 @example
 294 avconv -benchmark -i INPUT -f null -
 295 @end example
 296
 297 @section matroska
 298
 299 Matroska container muxer.
 300
 301 This muxer implements the matroska and webm container specs.
 302
 303 The recognized metadata settings in this muxer are:
 304
 305 @table @option
 306
 307 @item title=@var{title name}
 308 Name provided to a single track
 309 @end table
 310
 311 @table @option
 312
 313 @item language=@var{language name}
 314 Specifies the language of the track in the Matroska languages form
 315 @end table
 316
 317 @table @option
 318
 319 @item STEREO_MODE=@var{mode}
 320 Stereo 3D video layout of two views in a single video track
 321 @table @option
 322 @item mono
 323 video is not stereo
 324 @item left_right
 325 Both views are arranged side by side, Left-eye view is on the left
 326 @item bottom_top
 327 Both views are arranged in top-bottom orientation, Left-eye view is at bottom
 328 @item top_bottom
 329 Both views are arranged in top-bottom orientation, Left-eye view is on top
 330 @item checkerboard_rl
 331 Each view is arranged in a checkerboard interleaved pattern, Left-eye view being first
 332 @item checkerboard_lr
 333 Each view is arranged in a checkerboard interleaved pattern, Right-eye view being first
 334 @item row_interleaved_rl
 335 Each view is constituted by a row based interleaving, Right-eye view is first row
 336 @item row_interleaved_lr
 337 Each view is constituted by a row based interleaving, Left-eye view is first row
 338 @item col_interleaved_rl
 339 Both views are arranged in a column based interleaving manner, Right-eye view is first column
 340 @item col_interleaved_lr
 341 Both views are arranged in a column based interleaving manner, Left-eye view is first column
 342 @item anaglyph_cyan_red
 343 All frames are in anaglyph format viewable through red-cyan filters
 344 @item right_left
 345 Both views are arranged side by side, Right-eye view is on the left
 346 @item anaglyph_green_magenta
 347 All frames are in anaglyph format viewable through green-magenta filters
 348 @item block_lr
 349 Both eyes laced in one Block, Left-eye view is first
 350 @item block_rl
 351 Both eyes laced in one Block, Right-eye view is first
 352 @end table
 353 @end table
 354
 355 For example a 3D WebM clip can be created using the following command line:
 356 @example
 357 avconv -i sample_left_right_clip.mpg -an -c:v libvpx -metadata STEREO_MODE=left_right -y stereo_clip.webm
 358 @end example
 359
 360 @section segment
 361
 362 Basic stream segmenter.
 363
 364 The segmenter muxer outputs streams to a number of separate files of nearly
 365 fixed duration. Output filename pattern can be set in a fashion similar to
 366 @ref{image2}.
 367
 368 Every segment starts with a video keyframe, if a video stream is present.
 369 The segment muxer works best with a single constant frame rate video.
 370
 371 Optionally it can generate a flat list of the created segments, one segment
 372 per line.
 373
 374 @table @option
 375 @item segment_format @var{format}
 376 Override the inner container format, by default it is guessed by the filename
 377 extension.
 378 @item segment_time @var{t}
 379 Set segment duration to @var{t} seconds.
 380 @item segment_list @var{name}
 381 Generate also a listfile named @var{name}.
 382 @item segment_list_size @var{size}
 383 Overwrite the listfile once it reaches @var{size} entries.
 384 @item segment_wrap @var{limit}
 385 Wrap around segment index once it reaches @var{limit}.
 386 @end table
 387
 388 @example
 389 avconv -i in.mkv -c copy -map 0 -f segment -list out.list out%03d.nut
 390 @end example
 391
 392 @section mp3
 393
 394 The MP3 muxer writes a raw MP3 stream with an ID3v2 header at the beginning and
 395 optionally an ID3v1 tag at the end. ID3v2.3 and ID3v2.4 are supported, the
 396 @code{id3v2_version} option controls which one is used. The legacy ID3v1 tag is
 397 not written by default, but may be enabled with the @code{write_id3v1} option.
 398
 399 For seekable output the muxer also writes a Xing frame at the beginning, which
 400 contains the number of frames in the file. It is useful for computing duration
 401 of VBR files.
 402
 403 The muxer supports writing ID3v2 attached pictures (APIC frames). The pictures
 404 are supplied to the muxer in form of a video stream with a single packet. There
 405 can be any number of those streams, each will correspond to a single APIC frame.
 406 The stream metadata tags @var{title} and @var{comment} map to APIC
 407 @var{description} and @var{picture type} respectively. See
 408 @url{http://id3.org/id3v2.4.0-frames} for allowed picture types.
 409
 410 Note that the APIC frames must be written at the beginning, so the muxer will
 411 buffer the audio frames until it gets all the pictures. It is therefore advised
 412 to provide the pictures as soon as possible to avoid excessive buffering.
 413
 414 Examples:
 415
 416 Write an mp3 with an ID3v2.3 header and an ID3v1 footer:
 417 @example
 418 avconv -i INPUT -id3v2_version 3 -write_id3v1 1 out.mp3
 419 @end example
 420
 421 Attach a picture to an mp3:
 422 @example
 423 avconv -i input.mp3 -i cover.png -c copy -metadata:s:v title="Album cover"
 424 -metadata:s:v comment="Cover (Front)" out.mp3
 425 @end example
 426
 427 @c man end MUXERS