| 1 | @chapter Demuxers |
| 2 | @c man begin DEMUXERS |
| 3 | |
| 4 | Demuxers are configured elements in FFmpeg that can read the |
| 5 | multimedia streams from a particular type of file. |
| 6 | |
| 7 | When you configure your FFmpeg build, all the supported demuxers |
| 8 | are enabled by default. You can list all available ones using the |
| 9 | configure option @code{--list-demuxers}. |
| 10 | |
| 11 | You can disable all the demuxers using the configure option |
| 12 | @code{--disable-demuxers}, and selectively enable a single demuxer with |
| 13 | the option @code{--enable-demuxer=@var{DEMUXER}}, or disable it |
| 14 | with the option @code{--disable-demuxer=@var{DEMUXER}}. |
| 15 | |
| 16 | The option @code{-formats} of the ff* tools will display the list of |
| 17 | enabled demuxers. |
| 18 | |
| 19 | The description of some of the currently available demuxers follows. |
| 20 | |
| 21 | @section applehttp |
| 22 | |
| 23 | Apple HTTP Live Streaming demuxer. |
| 24 | |
| 25 | This demuxer presents all AVStreams from all variant streams. |
| 26 | The id field is set to the bitrate variant index number. By setting |
| 27 | the discard flags on AVStreams (by pressing 'a' or 'v' in ffplay), |
| 28 | the caller can decide which variant streams to actually receive. |
| 29 | The total bitrate of the variant that the stream belongs to is |
| 30 | available in a metadata key named "variant_bitrate". |
| 31 | |
| 32 | @section apng |
| 33 | |
| 34 | Animated Portable Network Graphics demuxer. |
| 35 | |
| 36 | This demuxer is used to demux APNG files. |
| 37 | All headers, but the PNG signature, up to (but not including) the first |
| 38 | fcTL chunk are transmitted as extradata. |
| 39 | Frames are then split as being all the chunks between two fcTL ones, or |
| 40 | between the last fcTL and IEND chunks. |
| 41 | |
| 42 | @table @option |
| 43 | @item -ignore_loop @var{bool} |
| 44 | Ignore the loop variable in the file if set. |
| 45 | @item -max_fps @var{int} |
| 46 | Maximum framerate in frames per second (0 for no limit). |
| 47 | @item -default_fps @var{int} |
| 48 | Default framerate in frames per second when none is specified in the file |
| 49 | (0 meaning as fast as possible). |
| 50 | @end table |
| 51 | |
| 52 | @section asf |
| 53 | |
| 54 | Advanced Systems Format demuxer. |
| 55 | |
| 56 | This demuxer is used to demux ASF files and MMS network streams. |
| 57 | |
| 58 | @table @option |
| 59 | @item -no_resync_search @var{bool} |
| 60 | Do not try to resynchronize by looking for a certain optional start code. |
| 61 | @end table |
| 62 | |
| 63 | @anchor{concat} |
| 64 | @section concat |
| 65 | |
| 66 | Virtual concatenation script demuxer. |
| 67 | |
| 68 | This demuxer reads a list of files and other directives from a text file and |
| 69 | demuxes them one after the other, as if all their packet had been muxed |
| 70 | together. |
| 71 | |
| 72 | The timestamps in the files are adjusted so that the first file starts at 0 |
| 73 | and each next file starts where the previous one finishes. Note that it is |
| 74 | done globally and may cause gaps if all streams do not have exactly the same |
| 75 | length. |
| 76 | |
| 77 | All files must have the same streams (same codecs, same time base, etc.). |
| 78 | |
| 79 | The duration of each file is used to adjust the timestamps of the next file: |
| 80 | if the duration is incorrect (because it was computed using the bit-rate or |
| 81 | because the file is truncated, for example), it can cause artifacts. The |
| 82 | @code{duration} directive can be used to override the duration stored in |
| 83 | each file. |
| 84 | |
| 85 | @subsection Syntax |
| 86 | |
| 87 | The script is a text file in extended-ASCII, with one directive per line. |
| 88 | Empty lines, leading spaces and lines starting with '#' are ignored. The |
| 89 | following directive is recognized: |
| 90 | |
| 91 | @table @option |
| 92 | |
| 93 | @item @code{file @var{path}} |
| 94 | Path to a file to read; special characters and spaces must be escaped with |
| 95 | backslash or single quotes. |
| 96 | |
| 97 | All subsequent file-related directives apply to that file. |
| 98 | |
| 99 | @item @code{ffconcat version 1.0} |
| 100 | Identify the script type and version. It also sets the @option{safe} option |
| 101 | to 1 if it was to its default -1. |
| 102 | |
| 103 | To make FFmpeg recognize the format automatically, this directive must |
| 104 | appears exactly as is (no extra space or byte-order-mark) on the very first |
| 105 | line of the script. |
| 106 | |
| 107 | @item @code{duration @var{dur}} |
| 108 | Duration of the file. This information can be specified from the file; |
| 109 | specifying it here may be more efficient or help if the information from the |
| 110 | file is not available or accurate. |
| 111 | |
| 112 | If the duration is set for all files, then it is possible to seek in the |
| 113 | whole concatenated video. |
| 114 | |
| 115 | @item @code{stream} |
| 116 | Introduce a stream in the virtual file. |
| 117 | All subsequent stream-related directives apply to the last introduced |
| 118 | stream. |
| 119 | Some streams properties must be set in order to allow identifying the |
| 120 | matching streams in the subfiles. |
| 121 | If no streams are defined in the script, the streams from the first file are |
| 122 | copied. |
| 123 | |
| 124 | @item @code{exact_stream_id @var{id}} |
| 125 | Set the id of the stream. |
| 126 | If this directive is given, the string with the corresponding id in the |
| 127 | subfiles will be used. |
| 128 | This is especially useful for MPEG-PS (VOB) files, where the order of the |
| 129 | streams is not reliable. |
| 130 | |
| 131 | @end table |
| 132 | |
| 133 | @subsection Options |
| 134 | |
| 135 | This demuxer accepts the following option: |
| 136 | |
| 137 | @table @option |
| 138 | |
| 139 | @item safe |
| 140 | If set to 1, reject unsafe file paths. A file path is considered safe if it |
| 141 | does not contain a protocol specification and is relative and all components |
| 142 | only contain characters from the portable character set (letters, digits, |
| 143 | period, underscore and hyphen) and have no period at the beginning of a |
| 144 | component. |
| 145 | |
| 146 | If set to 0, any file name is accepted. |
| 147 | |
| 148 | The default is -1, it is equivalent to 1 if the format was automatically |
| 149 | probed and 0 otherwise. |
| 150 | |
| 151 | @item auto_convert |
| 152 | If set to 1, try to perform automatic conversions on packet data to make the |
| 153 | streams concatenable. |
| 154 | |
| 155 | Currently, the only conversion is adding the h264_mp4toannexb bitstream |
| 156 | filter to H.264 streams in MP4 format. This is necessary in particular if |
| 157 | there are resolution changes. |
| 158 | |
| 159 | @end table |
| 160 | |
| 161 | @section flv |
| 162 | |
| 163 | Adobe Flash Video Format demuxer. |
| 164 | |
| 165 | This demuxer is used to demux FLV files and RTMP network streams. |
| 166 | |
| 167 | @table @option |
| 168 | @item -flv_metadata @var{bool} |
| 169 | Allocate the streams according to the onMetaData array content. |
| 170 | @end table |
| 171 | |
| 172 | @section libgme |
| 173 | |
| 174 | The Game Music Emu library is a collection of video game music file emulators. |
| 175 | |
| 176 | See @url{http://code.google.com/p/game-music-emu/} for more information. |
| 177 | |
| 178 | Some files have multiple tracks. The demuxer will pick the first track by |
| 179 | default. The @option{track_index} option can be used to select a different |
| 180 | track. Track indexes start at 0. The demuxer exports the number of tracks as |
| 181 | @var{tracks} meta data entry. |
| 182 | |
| 183 | For very large files, the @option{max_size} option may have to be adjusted. |
| 184 | |
| 185 | @section libquvi |
| 186 | |
| 187 | Play media from Internet services using the quvi project. |
| 188 | |
| 189 | The demuxer accepts a @option{format} option to request a specific quality. It |
| 190 | is by default set to @var{best}. |
| 191 | |
| 192 | See @url{http://quvi.sourceforge.net/} for more information. |
| 193 | |
| 194 | FFmpeg needs to be built with @code{--enable-libquvi} for this demuxer to be |
| 195 | enabled. |
| 196 | |
| 197 | @section gif |
| 198 | |
| 199 | Animated GIF demuxer. |
| 200 | |
| 201 | It accepts the following options: |
| 202 | |
| 203 | @table @option |
| 204 | @item min_delay |
| 205 | Set the minimum valid delay between frames in hundredths of seconds. |
| 206 | Range is 0 to 6000. Default value is 2. |
| 207 | |
| 208 | @item default_delay |
| 209 | Set the default delay between frames in hundredths of seconds. |
| 210 | Range is 0 to 6000. Default value is 10. |
| 211 | |
| 212 | @item ignore_loop |
| 213 | GIF files can contain information to loop a certain number of times (or |
| 214 | infinitely). If @option{ignore_loop} is set to 1, then the loop setting |
| 215 | from the input will be ignored and looping will not occur. If set to 0, |
| 216 | then looping will occur and will cycle the number of times according to |
| 217 | the GIF. Default value is 1. |
| 218 | @end table |
| 219 | |
| 220 | For example, with the overlay filter, place an infinitely looping GIF |
| 221 | over another video: |
| 222 | @example |
| 223 | ffmpeg -i input.mp4 -ignore_loop 0 -i input.gif -filter_complex overlay=shortest=1 out.mkv |
| 224 | @end example |
| 225 | |
| 226 | Note that in the above example the shortest option for overlay filter is |
| 227 | used to end the output video at the length of the shortest input file, |
| 228 | which in this case is @file{input.mp4} as the GIF in this example loops |
| 229 | infinitely. |
| 230 | |
| 231 | @section image2 |
| 232 | |
| 233 | Image file demuxer. |
| 234 | |
| 235 | This demuxer reads from a list of image files specified by a pattern. |
| 236 | The syntax and meaning of the pattern is specified by the |
| 237 | option @var{pattern_type}. |
| 238 | |
| 239 | The pattern may contain a suffix which is used to automatically |
| 240 | determine the format of the images contained in the files. |
| 241 | |
| 242 | The size, the pixel format, and the format of each image must be the |
| 243 | same for all the files in the sequence. |
| 244 | |
| 245 | This demuxer accepts the following options: |
| 246 | @table @option |
| 247 | @item framerate |
| 248 | Set the frame rate for the video stream. It defaults to 25. |
| 249 | @item loop |
| 250 | If set to 1, loop over the input. Default value is 0. |
| 251 | @item pattern_type |
| 252 | Select the pattern type used to interpret the provided filename. |
| 253 | |
| 254 | @var{pattern_type} accepts one of the following values. |
| 255 | @table @option |
| 256 | @item sequence |
| 257 | Select a sequence pattern type, used to specify a sequence of files |
| 258 | indexed by sequential numbers. |
| 259 | |
| 260 | A sequence pattern may contain the string "%d" or "%0@var{N}d", which |
| 261 | specifies the position of the characters representing a sequential |
| 262 | number in each filename matched by the pattern. If the form |
| 263 | "%d0@var{N}d" is used, the string representing the number in each |
| 264 | filename is 0-padded and @var{N} is the total number of 0-padded |
| 265 | digits representing the number. The literal character '%' can be |
| 266 | specified in the pattern with the string "%%". |
| 267 | |
| 268 | If the sequence pattern contains "%d" or "%0@var{N}d", the first filename of |
| 269 | the file list specified by the pattern must contain a number |
| 270 | inclusively contained between @var{start_number} and |
| 271 | @var{start_number}+@var{start_number_range}-1, and all the following |
| 272 | numbers must be sequential. |
| 273 | |
| 274 | For example the pattern "img-%03d.bmp" will match a sequence of |
| 275 | filenames of the form @file{img-001.bmp}, @file{img-002.bmp}, ..., |
| 276 | @file{img-010.bmp}, etc.; the pattern "i%%m%%g-%d.jpg" will match a |
| 277 | sequence of filenames of the form @file{i%m%g-1.jpg}, |
| 278 | @file{i%m%g-2.jpg}, ..., @file{i%m%g-10.jpg}, etc. |
| 279 | |
| 280 | Note that the pattern must not necessarily contain "%d" or |
| 281 | "%0@var{N}d", for example to convert a single image file |
| 282 | @file{img.jpeg} you can employ the command: |
| 283 | @example |
| 284 | ffmpeg -i img.jpeg img.png |
| 285 | @end example |
| 286 | |
| 287 | @item glob |
| 288 | Select a glob wildcard pattern type. |
| 289 | |
| 290 | The pattern is interpreted like a @code{glob()} pattern. This is only |
| 291 | selectable if libavformat was compiled with globbing support. |
| 292 | |
| 293 | @item glob_sequence @emph{(deprecated, will be removed)} |
| 294 | Select a mixed glob wildcard/sequence pattern. |
| 295 | |
| 296 | If your version of libavformat was compiled with globbing support, and |
| 297 | the provided pattern contains at least one glob meta character among |
| 298 | @code{%*?[]@{@}} that is preceded by an unescaped "%", the pattern is |
| 299 | interpreted like a @code{glob()} pattern, otherwise it is interpreted |
| 300 | like a sequence pattern. |
| 301 | |
| 302 | All glob special characters @code{%*?[]@{@}} must be prefixed |
| 303 | with "%". To escape a literal "%" you shall use "%%". |
| 304 | |
| 305 | For example the pattern @code{foo-%*.jpeg} will match all the |
| 306 | filenames prefixed by "foo-" and terminating with ".jpeg", and |
| 307 | @code{foo-%?%?%?.jpeg} will match all the filenames prefixed with |
| 308 | "foo-", followed by a sequence of three characters, and terminating |
| 309 | with ".jpeg". |
| 310 | |
| 311 | This pattern type is deprecated in favor of @var{glob} and |
| 312 | @var{sequence}. |
| 313 | @end table |
| 314 | |
| 315 | Default value is @var{glob_sequence}. |
| 316 | @item pixel_format |
| 317 | Set the pixel format of the images to read. If not specified the pixel |
| 318 | format is guessed from the first image file in the sequence. |
| 319 | @item start_number |
| 320 | Set the index of the file matched by the image file pattern to start |
| 321 | to read from. Default value is 0. |
| 322 | @item start_number_range |
| 323 | Set the index interval range to check when looking for the first image |
| 324 | file in the sequence, starting from @var{start_number}. Default value |
| 325 | is 5. |
| 326 | @item ts_from_file |
| 327 | If set to 1, will set frame timestamp to modification time of image file. Note |
| 328 | that monotonity of timestamps is not provided: images go in the same order as |
| 329 | without this option. Default value is 0. |
| 330 | If set to 2, will set frame timestamp to the modification time of the image file in |
| 331 | nanosecond precision. |
| 332 | @item video_size |
| 333 | Set the video size of the images to read. If not specified the video |
| 334 | size is guessed from the first image file in the sequence. |
| 335 | @end table |
| 336 | |
| 337 | @subsection Examples |
| 338 | |
| 339 | @itemize |
| 340 | @item |
| 341 | Use @command{ffmpeg} for creating a video from the images in the file |
| 342 | sequence @file{img-001.jpeg}, @file{img-002.jpeg}, ..., assuming an |
| 343 | input frame rate of 10 frames per second: |
| 344 | @example |
| 345 | ffmpeg -framerate 10 -i 'img-%03d.jpeg' out.mkv |
| 346 | @end example |
| 347 | |
| 348 | @item |
| 349 | As above, but start by reading from a file with index 100 in the sequence: |
| 350 | @example |
| 351 | ffmpeg -framerate 10 -start_number 100 -i 'img-%03d.jpeg' out.mkv |
| 352 | @end example |
| 353 | |
| 354 | @item |
| 355 | Read images matching the "*.png" glob pattern , that is all the files |
| 356 | terminating with the ".png" suffix: |
| 357 | @example |
| 358 | ffmpeg -framerate 10 -pattern_type glob -i "*.png" out.mkv |
| 359 | @end example |
| 360 | @end itemize |
| 361 | |
| 362 | @section mpegts |
| 363 | |
| 364 | MPEG-2 transport stream demuxer. |
| 365 | |
| 366 | @table @option |
| 367 | |
| 368 | @item fix_teletext_pts |
| 369 | Overrides teletext packet PTS and DTS values with the timestamps calculated |
| 370 | from the PCR of the first program which the teletext stream is part of and is |
| 371 | not discarded. Default value is 1, set this option to 0 if you want your |
| 372 | teletext packet PTS and DTS values untouched. |
| 373 | @end table |
| 374 | |
| 375 | @section rawvideo |
| 376 | |
| 377 | Raw video demuxer. |
| 378 | |
| 379 | This demuxer allows one to read raw video data. Since there is no header |
| 380 | specifying the assumed video parameters, the user must specify them |
| 381 | in order to be able to decode the data correctly. |
| 382 | |
| 383 | This demuxer accepts the following options: |
| 384 | @table @option |
| 385 | |
| 386 | @item framerate |
| 387 | Set input video frame rate. Default value is 25. |
| 388 | |
| 389 | @item pixel_format |
| 390 | Set the input video pixel format. Default value is @code{yuv420p}. |
| 391 | |
| 392 | @item video_size |
| 393 | Set the input video size. This value must be specified explicitly. |
| 394 | @end table |
| 395 | |
| 396 | For example to read a rawvideo file @file{input.raw} with |
| 397 | @command{ffplay}, assuming a pixel format of @code{rgb24}, a video |
| 398 | size of @code{320x240}, and a frame rate of 10 images per second, use |
| 399 | the command: |
| 400 | @example |
| 401 | ffplay -f rawvideo -pixel_format rgb24 -video_size 320x240 -framerate 10 input.raw |
| 402 | @end example |
| 403 | |
| 404 | @section sbg |
| 405 | |
| 406 | SBaGen script demuxer. |
| 407 | |
| 408 | This demuxer reads the script language used by SBaGen |
| 409 | @url{http://uazu.net/sbagen/} to generate binaural beats sessions. A SBG |
| 410 | script looks like that: |
| 411 | @example |
| 412 | -SE |
| 413 | a: 300-2.5/3 440+4.5/0 |
| 414 | b: 300-2.5/0 440+4.5/3 |
| 415 | off: - |
| 416 | NOW == a |
| 417 | +0:07:00 == b |
| 418 | +0:14:00 == a |
| 419 | +0:21:00 == b |
| 420 | +0:30:00 off |
| 421 | @end example |
| 422 | |
| 423 | A SBG script can mix absolute and relative timestamps. If the script uses |
| 424 | either only absolute timestamps (including the script start time) or only |
| 425 | relative ones, then its layout is fixed, and the conversion is |
| 426 | straightforward. On the other hand, if the script mixes both kind of |
| 427 | timestamps, then the @var{NOW} reference for relative timestamps will be |
| 428 | taken from the current time of day at the time the script is read, and the |
| 429 | script layout will be frozen according to that reference. That means that if |
| 430 | the script is directly played, the actual times will match the absolute |
| 431 | timestamps up to the sound controller's clock accuracy, but if the user |
| 432 | somehow pauses the playback or seeks, all times will be shifted accordingly. |
| 433 | |
| 434 | @section tedcaptions |
| 435 | |
| 436 | JSON captions used for @url{http://www.ted.com/, TED Talks}. |
| 437 | |
| 438 | TED does not provide links to the captions, but they can be guessed from the |
| 439 | page. The file @file{tools/bookmarklets.html} from the FFmpeg source tree |
| 440 | contains a bookmarklet to expose them. |
| 441 | |
| 442 | This demuxer accepts the following option: |
| 443 | @table @option |
| 444 | @item start_time |
| 445 | Set the start time of the TED talk, in milliseconds. The default is 15000 |
| 446 | (15s). It is used to sync the captions with the downloadable videos, because |
| 447 | they include a 15s intro. |
| 448 | @end table |
| 449 | |
| 450 | Example: convert the captions to a format most players understand: |
| 451 | @example |
| 452 | ffmpeg -i http://www.ted.com/talks/subtitles/id/1/lang/en talk1-en.srt |
| 453 | @end example |
| 454 | |
| 455 | @c man end DEMUXERS |