Commit | Line | Data |
---|---|---|
2ba45a60 DM |
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 | ||
f6fa7814 DM |
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 | ||
2ba45a60 DM |
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 |