blob: 29a23d48b258ca5b637ed0b42d15f15c7dda5055
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{-demuxers} of the ff* tools will display the list of |
17 | enabled demuxers. Use @code{-formats} to view a combined list of |
18 | enabled demuxers and muxers. |
19 | |
20 | The description of some of the currently available demuxers follows. |
21 | |
22 | @section aa |
23 | |
24 | Audible Format 2, 3, and 4 demuxer. |
25 | |
26 | This demuxer is used to demux Audible Format 2, 3, and 4 (.aa) files. |
27 | |
28 | @section applehttp |
29 | |
30 | Apple HTTP Live Streaming demuxer. |
31 | |
32 | This demuxer presents all AVStreams from all variant streams. |
33 | The id field is set to the bitrate variant index number. By setting |
34 | the discard flags on AVStreams (by pressing 'a' or 'v' in ffplay), |
35 | the caller can decide which variant streams to actually receive. |
36 | The total bitrate of the variant that the stream belongs to is |
37 | available in a metadata key named "variant_bitrate". |
38 | |
39 | @section apng |
40 | |
41 | Animated Portable Network Graphics demuxer. |
42 | |
43 | This demuxer is used to demux APNG files. |
44 | All headers, but the PNG signature, up to (but not including) the first |
45 | fcTL chunk are transmitted as extradata. |
46 | Frames are then split as being all the chunks between two fcTL ones, or |
47 | between the last fcTL and IEND chunks. |
48 | |
49 | @table @option |
50 | @item -ignore_loop @var{bool} |
51 | Ignore the loop variable in the file if set. |
52 | @item -max_fps @var{int} |
53 | Maximum framerate in frames per second (0 for no limit). |
54 | @item -default_fps @var{int} |
55 | Default framerate in frames per second when none is specified in the file |
56 | (0 meaning as fast as possible). |
57 | @end table |
58 | |
59 | @section asf |
60 | |
61 | Advanced Systems Format demuxer. |
62 | |
63 | This demuxer is used to demux ASF files and MMS network streams. |
64 | |
65 | @table @option |
66 | @item -no_resync_search @var{bool} |
67 | Do not try to resynchronize by looking for a certain optional start code. |
68 | @end table |
69 | |
70 | @anchor{concat} |
71 | @section concat |
72 | |
73 | Virtual concatenation script demuxer. |
74 | |
75 | This demuxer reads a list of files and other directives from a text file and |
76 | demuxes them one after the other, as if all their packets had been muxed |
77 | together. |
78 | |
79 | The timestamps in the files are adjusted so that the first file starts at 0 |
80 | and each next file starts where the previous one finishes. Note that it is |
81 | done globally and may cause gaps if all streams do not have exactly the same |
82 | length. |
83 | |
84 | All files must have the same streams (same codecs, same time base, etc.). |
85 | |
86 | The duration of each file is used to adjust the timestamps of the next file: |
87 | if the duration is incorrect (because it was computed using the bit-rate or |
88 | because the file is truncated, for example), it can cause artifacts. The |
89 | @code{duration} directive can be used to override the duration stored in |
90 | each file. |
91 | |
92 | @subsection Syntax |
93 | |
94 | The script is a text file in extended-ASCII, with one directive per line. |
95 | Empty lines, leading spaces and lines starting with '#' are ignored. The |
96 | following directive is recognized: |
97 | |
98 | @table @option |
99 | |
100 | @item @code{file @var{path}} |
101 | Path to a file to read; special characters and spaces must be escaped with |
102 | backslash or single quotes. |
103 | |
104 | All subsequent file-related directives apply to that file. |
105 | |
106 | @item @code{ffconcat version 1.0} |
107 | Identify the script type and version. It also sets the @option{safe} option |
108 | to 1 if it was -1. |
109 | |
110 | To make FFmpeg recognize the format automatically, this directive must |
111 | appear exactly as is (no extra space or byte-order-mark) on the very first |
112 | line of the script. |
113 | |
114 | @item @code{duration @var{dur}} |
115 | Duration of the file. This information can be specified from the file; |
116 | specifying it here may be more efficient or help if the information from the |
117 | file is not available or accurate. |
118 | |
119 | If the duration is set for all files, then it is possible to seek in the |
120 | whole concatenated video. |
121 | |
122 | @item @code{inpoint @var{timestamp}} |
123 | In point of the file. When the demuxer opens the file it instantly seeks to the |
124 | specified timestamp. Seeking is done so that all streams can be presented |
125 | successfully at In point. |
126 | |
127 | This directive works best with intra frame codecs, because for non-intra frame |
128 | ones you will usually get extra packets before the actual In point and the |
129 | decoded content will most likely contain frames before In point too. |
130 | |
131 | For each file, packets before the file In point will have timestamps less than |
132 | the calculated start timestamp of the file (negative in case of the first |
133 | file), and the duration of the files (if not specified by the @code{duration} |
134 | directive) will be reduced based on their specified In point. |
135 | |
136 | Because of potential packets before the specified In point, packet timestamps |
137 | may overlap between two concatenated files. |
138 | |
139 | @item @code{outpoint @var{timestamp}} |
140 | Out point of the file. When the demuxer reaches the specified decoding |
141 | timestamp in any of the streams, it handles it as an end of file condition and |
142 | skips the current and all the remaining packets from all streams. |
143 | |
144 | Out point is exclusive, which means that the demuxer will not output packets |
145 | with a decoding timestamp greater or equal to Out point. |
146 | |
147 | This directive works best with intra frame codecs and formats where all streams |
148 | are tightly interleaved. For non-intra frame codecs you will usually get |
149 | additional packets with presentation timestamp after Out point therefore the |
150 | decoded content will most likely contain frames after Out point too. If your |
151 | streams are not tightly interleaved you may not get all the packets from all |
152 | streams before Out point and you may only will be able to decode the earliest |
153 | stream until Out point. |
154 | |
155 | The duration of the files (if not specified by the @code{duration} |
156 | directive) will be reduced based on their specified Out point. |
157 | |
158 | @item @code{file_packet_metadata @var{key=value}} |
159 | Metadata of the packets of the file. The specified metadata will be set for |
160 | each file packet. You can specify this directive multiple times to add multiple |
161 | metadata entries. |
162 | |
163 | @item @code{stream} |
164 | Introduce a stream in the virtual file. |
165 | All subsequent stream-related directives apply to the last introduced |
166 | stream. |
167 | Some streams properties must be set in order to allow identifying the |
168 | matching streams in the subfiles. |
169 | If no streams are defined in the script, the streams from the first file are |
170 | copied. |
171 | |
172 | @item @code{exact_stream_id @var{id}} |
173 | Set the id of the stream. |
174 | If this directive is given, the string with the corresponding id in the |
175 | subfiles will be used. |
176 | This is especially useful for MPEG-PS (VOB) files, where the order of the |
177 | streams is not reliable. |
178 | |
179 | @end table |
180 | |
181 | @subsection Options |
182 | |
183 | This demuxer accepts the following option: |
184 | |
185 | @table @option |
186 | |
187 | @item safe |
188 | If set to 1, reject unsafe file paths. A file path is considered safe if it |
189 | does not contain a protocol specification and is relative and all components |
190 | only contain characters from the portable character set (letters, digits, |
191 | period, underscore and hyphen) and have no period at the beginning of a |
192 | component. |
193 | |
194 | If set to 0, any file name is accepted. |
195 | |
196 | The default is 1. |
197 | |
198 | -1 is equivalent to 1 if the format was automatically |
199 | probed and 0 otherwise. |
200 | |
201 | @item auto_convert |
202 | If set to 1, try to perform automatic conversions on packet data to make the |
203 | streams concatenable. |
204 | The default is 1. |
205 | |
206 | Currently, the only conversion is adding the h264_mp4toannexb bitstream |
207 | filter to H.264 streams in MP4 format. This is necessary in particular if |
208 | there are resolution changes. |
209 | |
210 | @item segment_time_metadata |
211 | If set to 1, every packet will contain the @var{lavf.concat.start_time} and the |
212 | @var{lavf.concat.duration} packet metadata values which are the start_time and |
213 | the duration of the respective file segments in the concatenated output |
214 | expressed in microseconds. The duration metadata is only set if it is known |
215 | based on the concat file. |
216 | The default is 0. |
217 | |
218 | @end table |
219 | |
220 | @subsection Examples |
221 | |
222 | @itemize |
223 | @item |
224 | Use absolute filenames and include some comments: |
225 | @example |
226 | # my first filename |
227 | file /mnt/share/file-1.wav |
228 | # my second filename including whitespace |
229 | file '/mnt/share/file 2.wav' |
230 | # my third filename including whitespace plus single quote |
231 | file '/mnt/share/file 3'\''.wav' |
232 | @end example |
233 | |
234 | @item |
235 | Allow for input format auto-probing, use safe filenames and set the duration of |
236 | the first file: |
237 | @example |
238 | ffconcat version 1.0 |
239 | |
240 | file file-1.wav |
241 | duration 20.0 |
242 | |
243 | file subdir/file-2.wav |
244 | @end example |
245 | @end itemize |
246 | |
247 | @section flv, live_flv |
248 | |
249 | Adobe Flash Video Format demuxer. |
250 | |
251 | This demuxer is used to demux FLV files and RTMP network streams. In case of live network streams, if you force format, you may use live_flv option instead of flv to survive timestamp discontinuities. |
252 | |
253 | @example |
254 | ffmpeg -f flv -i myfile.flv ... |
255 | ffmpeg -f live_flv -i rtmp://<any.server>/anything/key .... |
256 | @end example |
257 | |
258 | |
259 | @table @option |
260 | @item -flv_metadata @var{bool} |
261 | Allocate the streams according to the onMetaData array content. |
262 | @end table |
263 | |
264 | @section gif |
265 | |
266 | Animated GIF demuxer. |
267 | |
268 | It accepts the following options: |
269 | |
270 | @table @option |
271 | @item min_delay |
272 | Set the minimum valid delay between frames in hundredths of seconds. |
273 | Range is 0 to 6000. Default value is 2. |
274 | |
275 | @item max_gif_delay |
276 | Set the maximum valid delay between frames in hundredth of seconds. |
277 | Range is 0 to 65535. Default value is 65535 (nearly eleven minutes), |
278 | the maximum value allowed by the specification. |
279 | |
280 | @item default_delay |
281 | Set the default delay between frames in hundredths of seconds. |
282 | Range is 0 to 6000. Default value is 10. |
283 | |
284 | @item ignore_loop |
285 | GIF files can contain information to loop a certain number of times (or |
286 | infinitely). If @option{ignore_loop} is set to 1, then the loop setting |
287 | from the input will be ignored and looping will not occur. If set to 0, |
288 | then looping will occur and will cycle the number of times according to |
289 | the GIF. Default value is 1. |
290 | @end table |
291 | |
292 | For example, with the overlay filter, place an infinitely looping GIF |
293 | over another video: |
294 | @example |
295 | ffmpeg -i input.mp4 -ignore_loop 0 -i input.gif -filter_complex overlay=shortest=1 out.mkv |
296 | @end example |
297 | |
298 | Note that in the above example the shortest option for overlay filter is |
299 | used to end the output video at the length of the shortest input file, |
300 | which in this case is @file{input.mp4} as the GIF in this example loops |
301 | infinitely. |
302 | |
303 | @section image2 |
304 | |
305 | Image file demuxer. |
306 | |
307 | This demuxer reads from a list of image files specified by a pattern. |
308 | The syntax and meaning of the pattern is specified by the |
309 | option @var{pattern_type}. |
310 | |
311 | The pattern may contain a suffix which is used to automatically |
312 | determine the format of the images contained in the files. |
313 | |
314 | The size, the pixel format, and the format of each image must be the |
315 | same for all the files in the sequence. |
316 | |
317 | This demuxer accepts the following options: |
318 | @table @option |
319 | @item framerate |
320 | Set the frame rate for the video stream. It defaults to 25. |
321 | @item loop |
322 | If set to 1, loop over the input. Default value is 0. |
323 | @item pattern_type |
324 | Select the pattern type used to interpret the provided filename. |
325 | |
326 | @var{pattern_type} accepts one of the following values. |
327 | @table @option |
328 | @item none |
329 | Disable pattern matching, therefore the video will only contain the specified |
330 | image. You should use this option if you do not want to create sequences from |
331 | multiple images and your filenames may contain special pattern characters. |
332 | @item sequence |
333 | Select a sequence pattern type, used to specify a sequence of files |
334 | indexed by sequential numbers. |
335 | |
336 | A sequence pattern may contain the string "%d" or "%0@var{N}d", which |
337 | specifies the position of the characters representing a sequential |
338 | number in each filename matched by the pattern. If the form |
339 | "%d0@var{N}d" is used, the string representing the number in each |
340 | filename is 0-padded and @var{N} is the total number of 0-padded |
341 | digits representing the number. The literal character '%' can be |
342 | specified in the pattern with the string "%%". |
343 | |
344 | If the sequence pattern contains "%d" or "%0@var{N}d", the first filename of |
345 | the file list specified by the pattern must contain a number |
346 | inclusively contained between @var{start_number} and |
347 | @var{start_number}+@var{start_number_range}-1, and all the following |
348 | numbers must be sequential. |
349 | |
350 | For example the pattern "img-%03d.bmp" will match a sequence of |
351 | filenames of the form @file{img-001.bmp}, @file{img-002.bmp}, ..., |
352 | @file{img-010.bmp}, etc.; the pattern "i%%m%%g-%d.jpg" will match a |
353 | sequence of filenames of the form @file{i%m%g-1.jpg}, |
354 | @file{i%m%g-2.jpg}, ..., @file{i%m%g-10.jpg}, etc. |
355 | |
356 | Note that the pattern must not necessarily contain "%d" or |
357 | "%0@var{N}d", for example to convert a single image file |
358 | @file{img.jpeg} you can employ the command: |
359 | @example |
360 | ffmpeg -i img.jpeg img.png |
361 | @end example |
362 | |
363 | @item glob |
364 | Select a glob wildcard pattern type. |
365 | |
366 | The pattern is interpreted like a @code{glob()} pattern. This is only |
367 | selectable if libavformat was compiled with globbing support. |
368 | |
369 | @item glob_sequence @emph{(deprecated, will be removed)} |
370 | Select a mixed glob wildcard/sequence pattern. |
371 | |
372 | If your version of libavformat was compiled with globbing support, and |
373 | the provided pattern contains at least one glob meta character among |
374 | @code{%*?[]@{@}} that is preceded by an unescaped "%", the pattern is |
375 | interpreted like a @code{glob()} pattern, otherwise it is interpreted |
376 | like a sequence pattern. |
377 | |
378 | All glob special characters @code{%*?[]@{@}} must be prefixed |
379 | with "%". To escape a literal "%" you shall use "%%". |
380 | |
381 | For example the pattern @code{foo-%*.jpeg} will match all the |
382 | filenames prefixed by "foo-" and terminating with ".jpeg", and |
383 | @code{foo-%?%?%?.jpeg} will match all the filenames prefixed with |
384 | "foo-", followed by a sequence of three characters, and terminating |
385 | with ".jpeg". |
386 | |
387 | This pattern type is deprecated in favor of @var{glob} and |
388 | @var{sequence}. |
389 | @end table |
390 | |
391 | Default value is @var{glob_sequence}. |
392 | @item pixel_format |
393 | Set the pixel format of the images to read. If not specified the pixel |
394 | format is guessed from the first image file in the sequence. |
395 | @item start_number |
396 | Set the index of the file matched by the image file pattern to start |
397 | to read from. Default value is 0. |
398 | @item start_number_range |
399 | Set the index interval range to check when looking for the first image |
400 | file in the sequence, starting from @var{start_number}. Default value |
401 | is 5. |
402 | @item ts_from_file |
403 | If set to 1, will set frame timestamp to modification time of image file. Note |
404 | that monotonity of timestamps is not provided: images go in the same order as |
405 | without this option. Default value is 0. |
406 | If set to 2, will set frame timestamp to the modification time of the image file in |
407 | nanosecond precision. |
408 | @item video_size |
409 | Set the video size of the images to read. If not specified the video |
410 | size is guessed from the first image file in the sequence. |
411 | @end table |
412 | |
413 | @subsection Examples |
414 | |
415 | @itemize |
416 | @item |
417 | Use @command{ffmpeg} for creating a video from the images in the file |
418 | sequence @file{img-001.jpeg}, @file{img-002.jpeg}, ..., assuming an |
419 | input frame rate of 10 frames per second: |
420 | @example |
421 | ffmpeg -framerate 10 -i 'img-%03d.jpeg' out.mkv |
422 | @end example |
423 | |
424 | @item |
425 | As above, but start by reading from a file with index 100 in the sequence: |
426 | @example |
427 | ffmpeg -framerate 10 -start_number 100 -i 'img-%03d.jpeg' out.mkv |
428 | @end example |
429 | |
430 | @item |
431 | Read images matching the "*.png" glob pattern , that is all the files |
432 | terminating with the ".png" suffix: |
433 | @example |
434 | ffmpeg -framerate 10 -pattern_type glob -i "*.png" out.mkv |
435 | @end example |
436 | @end itemize |
437 | |
438 | @section libgme |
439 | |
440 | The Game Music Emu library is a collection of video game music file emulators. |
441 | |
442 | See @url{http://code.google.com/p/game-music-emu/} for more information. |
443 | |
444 | Some files have multiple tracks. The demuxer will pick the first track by |
445 | default. The @option{track_index} option can be used to select a different |
446 | track. Track indexes start at 0. The demuxer exports the number of tracks as |
447 | @var{tracks} meta data entry. |
448 | |
449 | For very large files, the @option{max_size} option may have to be adjusted. |
450 | |
451 | @section libopenmpt |
452 | |
453 | libopenmpt based module demuxer |
454 | |
455 | See @url{https://lib.openmpt.org/libopenmpt/} for more information. |
456 | |
457 | Some files have multiple subsongs (tracks) this can be set with the @option{subsong} |
458 | option. |
459 | |
460 | It accepts the following options: |
461 | |
462 | @table @option |
463 | @item subsong |
464 | Set the subsong index. This can be either 'all', 'auto', or the index of the |
465 | subsong. Subsong indexes start at 0. The default is 'auto'. |
466 | |
467 | The default value is to let libopenmpt choose. |
468 | |
469 | @item layout |
470 | Set the channel layout. Valid values are 1, 2, and 4 channel layouts. |
471 | The default value is STEREO. |
472 | |
473 | @item sample_rate |
474 | Set the sample rate for libopenmpt to output. |
475 | Range is from 1000 to INT_MAX. The value default is 48000. |
476 | @end table |
477 | |
478 | @section mov/mp4/3gp/QuickTime |
479 | |
480 | QuickTime / MP4 demuxer. |
481 | |
482 | This demuxer accepts the following options: |
483 | @table @option |
484 | @item enable_drefs |
485 | Enable loading of external tracks, disabled by default. |
486 | Enabling this can theoretically leak information in some use cases. |
487 | |
488 | @item use_absolute_path |
489 | Allows loading of external tracks via absolute paths, disabled by default. |
490 | Enabling this poses a security risk. It should only be enabled if the source |
491 | is known to be non malicious. |
492 | |
493 | @end table |
494 | |
495 | @section mpegts |
496 | |
497 | MPEG-2 transport stream demuxer. |
498 | |
499 | This demuxer accepts the following options: |
500 | @table @option |
501 | @item resync_size |
502 | Set size limit for looking up a new synchronization. Default value is |
503 | 65536. |
504 | |
505 | @item fix_teletext_pts |
506 | Override teletext packet PTS and DTS values with the timestamps calculated |
507 | from the PCR of the first program which the teletext stream is part of and is |
508 | not discarded. Default value is 1, set this option to 0 if you want your |
509 | teletext packet PTS and DTS values untouched. |
510 | |
511 | @item ts_packetsize |
512 | Output option carrying the raw packet size in bytes. |
513 | Show the detected raw packet size, cannot be set by the user. |
514 | |
515 | @item scan_all_pmts |
516 | Scan and combine all PMTs. The value is an integer with value from -1 |
517 | to 1 (-1 means automatic setting, 1 means enabled, 0 means |
518 | disabled). Default value is -1. |
519 | @end table |
520 | |
521 | @section mpjpeg |
522 | |
523 | MJPEG encapsulated in multi-part MIME demuxer. |
524 | |
525 | This demuxer allows reading of MJPEG, where each frame is represented as a part of |
526 | multipart/x-mixed-replace stream. |
527 | @table @option |
528 | |
529 | @item strict_mime_boundary |
530 | Default implementation applies a relaxed standard to multi-part MIME boundary detection, |
531 | to prevent regression with numerous existing endpoints not generating a proper MIME |
532 | MJPEG stream. Turning this option on by setting it to 1 will result in a stricter check |
533 | of the boundary value. |
534 | @end table |
535 | |
536 | @section rawvideo |
537 | |
538 | Raw video demuxer. |
539 | |
540 | This demuxer allows one to read raw video data. Since there is no header |
541 | specifying the assumed video parameters, the user must specify them |
542 | in order to be able to decode the data correctly. |
543 | |
544 | This demuxer accepts the following options: |
545 | @table @option |
546 | |
547 | @item framerate |
548 | Set input video frame rate. Default value is 25. |
549 | |
550 | @item pixel_format |
551 | Set the input video pixel format. Default value is @code{yuv420p}. |
552 | |
553 | @item video_size |
554 | Set the input video size. This value must be specified explicitly. |
555 | @end table |
556 | |
557 | For example to read a rawvideo file @file{input.raw} with |
558 | @command{ffplay}, assuming a pixel format of @code{rgb24}, a video |
559 | size of @code{320x240}, and a frame rate of 10 images per second, use |
560 | the command: |
561 | @example |
562 | ffplay -f rawvideo -pixel_format rgb24 -video_size 320x240 -framerate 10 input.raw |
563 | @end example |
564 | |
565 | @section sbg |
566 | |
567 | SBaGen script demuxer. |
568 | |
569 | This demuxer reads the script language used by SBaGen |
570 | @url{http://uazu.net/sbagen/} to generate binaural beats sessions. A SBG |
571 | script looks like that: |
572 | @example |
573 | -SE |
574 | a: 300-2.5/3 440+4.5/0 |
575 | b: 300-2.5/0 440+4.5/3 |
576 | off: - |
577 | NOW == a |
578 | +0:07:00 == b |
579 | +0:14:00 == a |
580 | +0:21:00 == b |
581 | +0:30:00 off |
582 | @end example |
583 | |
584 | A SBG script can mix absolute and relative timestamps. If the script uses |
585 | either only absolute timestamps (including the script start time) or only |
586 | relative ones, then its layout is fixed, and the conversion is |
587 | straightforward. On the other hand, if the script mixes both kind of |
588 | timestamps, then the @var{NOW} reference for relative timestamps will be |
589 | taken from the current time of day at the time the script is read, and the |
590 | script layout will be frozen according to that reference. That means that if |
591 | the script is directly played, the actual times will match the absolute |
592 | timestamps up to the sound controller's clock accuracy, but if the user |
593 | somehow pauses the playback or seeks, all times will be shifted accordingly. |
594 | |
595 | @section tedcaptions |
596 | |
597 | JSON captions used for @url{http://www.ted.com/, TED Talks}. |
598 | |
599 | TED does not provide links to the captions, but they can be guessed from the |
600 | page. The file @file{tools/bookmarklets.html} from the FFmpeg source tree |
601 | contains a bookmarklet to expose them. |
602 | |
603 | This demuxer accepts the following option: |
604 | @table @option |
605 | @item start_time |
606 | Set the start time of the TED talk, in milliseconds. The default is 15000 |
607 | (15s). It is used to sync the captions with the downloadable videos, because |
608 | they include a 15s intro. |
609 | @end table |
610 | |
611 | Example: convert the captions to a format most players understand: |
612 | @example |
613 | ffmpeg -i http://www.ted.com/talks/subtitles/id/1/lang/en talk1-en.srt |
614 | @end example |
615 | |
616 | @c man end DEMUXERS |
617 |