e202d383d9db70f9bca9367193ec685a07b4e6bf
[ffmpeg.git] / doc / filters.texi
1 @chapter Filtering Introduction
2 @c man begin FILTERING INTRODUCTION
3
4 Filtering in FFmpeg is enabled through the libavfilter library.
5
6 Libavfilter is the filtering API of FFmpeg. It is the substitute of
7 the now deprecated 'vhooks' and started as a Google Summer of Code
8 project.
9
10 Audio filtering integration into the main FFmpeg repository is a work in
11 progress, so audio API and ABI should not be considered stable yet.
12
13 In libavfilter, it is possible for filters to have multiple inputs and
14 multiple outputs.
15 To illustrate the sorts of things that are possible, we can
16 use a complex filter graph. For example, the following one:
17
18 @example
19 input --> split --> fifo -----------------------> overlay --> output
20             |                                        ^
21             |                                        |
22             +------> fifo --> crop --> vflip --------+
23 @end example
24
25 splits the stream in two streams, sends one stream through the crop filter
26 and the vflip filter before merging it back with the other stream by
27 overlaying it on top. You can use the following command to achieve this:
28
29 @example
30 ffmpeg -i input -vf "[in] split [T1], fifo, [T2] overlay=0:H/2 [out]; [T1] fifo, crop=iw:ih/2:0:ih/2, vflip [T2]" output
31 @end example
32
33 The result will be that in output the top half of the video is mirrored
34 onto the bottom half.
35
36 Filters are loaded using the @var{-vf} or @var{-af} option passed to
37 @command{ffmpeg} or to @command{ffplay}. Filters in the same linear
38 chain are separated by commas. In our example, @var{split, fifo,
39 overlay} are in one linear chain, and @var{fifo, crop, vflip} are in
40 another. The points where the linear chains join are labeled by names
41 enclosed in square brackets. In our example, that is @var{[T1]} and
42 @var{[T2]}. The special labels @var{[in]} and @var{[out]} are the points
43 where video is input and output.
44
45 Some filters take in input a list of parameters: they are specified
46 after the filter name and an equal sign, and are separated from each other
47 by a colon.
48
49 There exist so-called @var{source filters} that do not have an
50 audio/video input, and @var{sink filters} that will not have audio/video
51 output.
52
53 @c man end FILTERING INTRODUCTION
54
55 @chapter graph2dot
56 @c man begin GRAPH2DOT
57
58 The @file{graph2dot} program included in the FFmpeg @file{tools}
59 directory can be used to parse a filter graph description and issue a
60 corresponding textual representation in the dot language.
61
62 Invoke the command:
63 @example
64 graph2dot -h
65 @end example
66
67 to see how to use @file{graph2dot}.
68
69 You can then pass the dot description to the @file{dot} program (from
70 the graphviz suite of programs) and obtain a graphical representation
71 of the filter graph.
72
73 For example the sequence of commands:
74 @example
75 echo @var{GRAPH_DESCRIPTION} | \
76 tools/graph2dot -o graph.tmp && \
77 dot -Tpng graph.tmp -o graph.png && \
78 display graph.png
79 @end example
80
81 can be used to create and display an image representing the graph
82 described by the @var{GRAPH_DESCRIPTION} string. Note that this string must be
83 a complete self-contained graph, with its inputs and outputs explicitly defined.
84 For example if your command line is of the form:
85 @example
86 ffmpeg -i infile -vf scale=640:360 outfile
87 @end example
88 your @var{GRAPH_DESCRIPTION} string will need to be of the form:
89 @example
90 nullsrc,scale=640:360,nullsink
91 @end example
92 you may also need to set the @var{nullsrc} parameters and add a @var{format}
93 filter in order to simulate a specific input file.
94
95 @c man end GRAPH2DOT
96
97 @chapter Filtergraph description
98 @c man begin FILTERGRAPH DESCRIPTION
99
100 A filtergraph is a directed graph of connected filters. It can contain
101 cycles, and there can be multiple links between a pair of
102 filters. Each link has one input pad on one side connecting it to one
103 filter from which it takes its input, and one output pad on the other
104 side connecting it to the one filter accepting its output.
105
106 Each filter in a filtergraph is an instance of a filter class
107 registered in the application, which defines the features and the
108 number of input and output pads of the filter.
109
110 A filter with no input pads is called a "source", a filter with no
111 output pads is called a "sink".
112
113 @anchor{Filtergraph syntax}
114 @section Filtergraph syntax
115
116 A filtergraph can be represented using a textual representation, which is
117 recognized by the @option{-filter}/@option{-vf} and @option{-filter_complex}
118 options in @command{ffmpeg} and @option{-vf} in @command{ffplay}, and by the
119 @code{avfilter_graph_parse()}/@code{avfilter_graph_parse2()} function defined in
120 @file{libavfilter/avfiltergraph.h}.
121
122 A filterchain consists of a sequence of connected filters, each one
123 connected to the previous one in the sequence. A filterchain is
124 represented by a list of ","-separated filter descriptions.
125
126 A filtergraph consists of a sequence of filterchains. A sequence of
127 filterchains is represented by a list of ";"-separated filterchain
128 descriptions.
129
130 A filter is represented by a string of the form:
131 [@var{in_link_1}]...[@var{in_link_N}]@var{filter_name}=@var{arguments}[@var{out_link_1}]...[@var{out_link_M}]
132
133 @var{filter_name} is the name of the filter class of which the
134 described filter is an instance of, and has to be the name of one of
135 the filter classes registered in the program.
136 The name of the filter class is optionally followed by a string
137 "=@var{arguments}".
138
139 @var{arguments} is a string which contains the parameters used to
140 initialize the filter instance, and are described in the filter
141 descriptions below.
142
143 The list of arguments can be quoted using the character "'" as initial
144 and ending mark, and the character '\' for escaping the characters
145 within the quoted text; otherwise the argument string is considered
146 terminated when the next special character (belonging to the set
147 "[]=;,") is encountered.
148
149 The name and arguments of the filter are optionally preceded and
150 followed by a list of link labels.
151 A link label allows to name a link and associate it to a filter output
152 or input pad. The preceding labels @var{in_link_1}
153 ... @var{in_link_N}, are associated to the filter input pads,
154 the following labels @var{out_link_1} ... @var{out_link_M}, are
155 associated to the output pads.
156
157 When two link labels with the same name are found in the
158 filtergraph, a link between the corresponding input and output pad is
159 created.
160
161 If an output pad is not labelled, it is linked by default to the first
162 unlabelled input pad of the next filter in the filterchain.
163 For example in the filterchain:
164 @example
165 nullsrc, split[L1], [L2]overlay, nullsink
166 @end example
167 the split filter instance has two output pads, and the overlay filter
168 instance two input pads. The first output pad of split is labelled
169 "L1", the first input pad of overlay is labelled "L2", and the second
170 output pad of split is linked to the second input pad of overlay,
171 which are both unlabelled.
172
173 In a complete filterchain all the unlabelled filter input and output
174 pads must be connected. A filtergraph is considered valid if all the
175 filter input and output pads of all the filterchains are connected.
176
177 Libavfilter will automatically insert scale filters where format
178 conversion is required. It is possible to specify swscale flags
179 for those automatically inserted scalers by prepending
180 @code{sws_flags=@var{flags};}
181 to the filtergraph description.
182
183 Follows a BNF description for the filtergraph syntax:
184 @example
185 @var{NAME}             ::= sequence of alphanumeric characters and '_'
186 @var{LINKLABEL}        ::= "[" @var{NAME} "]"
187 @var{LINKLABELS}       ::= @var{LINKLABEL} [@var{LINKLABELS}]
188 @var{FILTER_ARGUMENTS} ::= sequence of chars (eventually quoted)
189 @var{FILTER}           ::= [@var{LINKNAMES}] @var{NAME} ["=" @var{ARGUMENTS}] [@var{LINKNAMES}]
190 @var{FILTERCHAIN}      ::= @var{FILTER} [,@var{FILTERCHAIN}]
191 @var{FILTERGRAPH}      ::= [sws_flags=@var{flags};] @var{FILTERCHAIN} [;@var{FILTERGRAPH}]
192 @end example
193
194 @c man end FILTERGRAPH DESCRIPTION
195
196 @chapter Audio Filters
197 @c man begin AUDIO FILTERS
198
199 When you configure your FFmpeg build, you can disable any of the
200 existing filters using @code{--disable-filters}.
201 The configure output will show the audio filters included in your
202 build.
203
204 Below is a description of the currently available audio filters.
205
206 @section aconvert
207
208 Convert the input audio format to the specified formats.
209
210 The filter accepts a string of the form:
211 "@var{sample_format}:@var{channel_layout}".
212
213 @var{sample_format} specifies the sample format, and can be a string or the
214 corresponding numeric value defined in @file{libavutil/samplefmt.h}. Use 'p'
215 suffix for a planar sample format.
216
217 @var{channel_layout} specifies the channel layout, and can be a string
218 or the corresponding number value defined in @file{libavutil/audioconvert.h}.
219
220 The special parameter "auto", signifies that the filter will
221 automatically select the output format depending on the output filter.
222
223 Some examples follow.
224
225 @itemize
226 @item
227 Convert input to float, planar, stereo:
228 @example
229 aconvert=fltp:stereo
230 @end example
231
232 @item
233 Convert input to unsigned 8-bit, automatically select out channel layout:
234 @example
235 aconvert=u8:auto
236 @end example
237 @end itemize
238
239 @section aformat
240
241 Convert the input audio to one of the specified formats. The framework will
242 negotiate the most appropriate format to minimize conversions.
243
244 The filter accepts the following named parameters:
245 @table @option
246
247 @item sample_fmts
248 A comma-separated list of requested sample formats.
249
250 @item sample_rates
251 A comma-separated list of requested sample rates.
252
253 @item channel_layouts
254 A comma-separated list of requested channel layouts.
255
256 @end table
257
258 If a parameter is omitted, all values are allowed.
259
260 For example to force the output to either unsigned 8-bit or signed 16-bit stereo:
261 @example
262 aformat=sample_fmts\=u8\,s16:channel_layouts\=stereo
263 @end example
264
265 @section amerge
266
267 Merge two or more audio streams into a single multi-channel stream.
268
269 The filter accepts the following named options:
270
271 @table @option
272
273 @item inputs
274 Set the number of inputs. Default is 2.
275
276 @end table
277
278 If the channel layouts of the inputs are disjoint, and therefore compatible,
279 the channel layout of the output will be set accordingly and the channels
280 will be reordered as necessary. If the channel layouts of the inputs are not
281 disjoint, the output will have all the channels of the first input then all
282 the channels of the second input, in that order, and the channel layout of
283 the output will be the default value corresponding to the total number of
284 channels.
285
286 For example, if the first input is in 2.1 (FL+FR+LF) and the second input
287 is FC+BL+BR, then the output will be in 5.1, with the channels in the
288 following order: a1, a2, b1, a3, b2, b3 (a1 is the first channel of the
289 first input, b1 is the first channel of the second input).
290
291 On the other hand, if both input are in stereo, the output channels will be
292 in the default order: a1, a2, b1, b2, and the channel layout will be
293 arbitrarily set to 4.0, which may or may not be the expected value.
294
295 All inputs must have the same sample rate, and format.
296
297 If inputs do not have the same duration, the output will stop with the
298 shortest.
299
300 Example: merge two mono files into a stereo stream:
301 @example
302 amovie=left.wav [l] ; amovie=right.mp3 [r] ; [l] [r] amerge
303 @end example
304
305 Example: multiple merges:
306 @example
307 ffmpeg -f lavfi -i "
308 amovie=input.mkv:si=0 [a0];
309 amovie=input.mkv:si=1 [a1];
310 amovie=input.mkv:si=2 [a2];
311 amovie=input.mkv:si=3 [a3];
312 amovie=input.mkv:si=4 [a4];
313 amovie=input.mkv:si=5 [a5];
314 [a0][a1][a2][a3][a4][a5] amerge=inputs=6" -c:a pcm_s16le output.mkv
315 @end example
316
317 @section amix
318
319 Mixes multiple audio inputs into a single output.
320
321 For example
322 @example
323 ffmpeg -i INPUT1 -i INPUT2 -i INPUT3 -filter_complex amix=inputs=3:duration=first:dropout_transition=3 OUTPUT
324 @end example
325 will mix 3 input audio streams to a single output with the same duration as the
326 first input and a dropout transition time of 3 seconds.
327
328 The filter accepts the following named parameters:
329 @table @option
330
331 @item inputs
332 Number of inputs. If unspecified, it defaults to 2.
333
334 @item duration
335 How to determine the end-of-stream.
336 @table @option
337
338 @item longest
339 Duration of longest input. (default)
340
341 @item shortest
342 Duration of shortest input.
343
344 @item first
345 Duration of first input.
346
347 @end table
348
349 @item dropout_transition
350 Transition time, in seconds, for volume renormalization when an input
351 stream ends. The default value is 2 seconds.
352
353 @end table
354
355 @section anull
356
357 Pass the audio source unchanged to the output.
358
359 @section aresample
360
361 Resample the input audio to the specified sample rate.
362
363 The filter accepts exactly one parameter, the output sample rate. If not
364 specified then the filter will automatically convert between its input
365 and output sample rates.
366
367 For example, to resample the input audio to 44100Hz:
368 @example
369 aresample=44100
370 @end example
371
372 @section asetnsamples
373
374 Set the number of samples per each output audio frame.
375
376 The last output packet may contain a different number of samples, as
377 the filter will flush all the remaining samples when the input audio
378 signal its end.
379
380 The filter accepts parameters as a list of @var{key}=@var{value} pairs,
381 separated by ":".
382
383 @table @option
384
385 @item nb_out_samples, n
386 Set the number of frames per each output audio frame. The number is
387 intended as the number of samples @emph{per each channel}.
388 Default value is 1024.
389
390 @item pad, p
391 If set to 1, the filter will pad the last audio frame with zeroes, so
392 that the last frame will contain the same number of samples as the
393 previous ones. Default value is 1.
394 @end table
395
396 For example, to set the number of per-frame samples to 1234 and
397 disable padding for the last frame, use:
398 @example
399 asetnsamples=n=1234:p=0
400 @end example
401
402 @section ashowinfo
403
404 Show a line containing various information for each input audio frame.
405 The input audio is not modified.
406
407 The shown line contains a sequence of key/value pairs of the form
408 @var{key}:@var{value}.
409
410 A description of each shown parameter follows:
411
412 @table @option
413 @item n
414 sequential number of the input frame, starting from 0
415
416 @item pts
417 presentation TimeStamp of the input frame, expressed as a number of
418 time base units. The time base unit depends on the filter input pad, and
419 is usually 1/@var{sample_rate}.
420
421 @item pts_time
422 presentation TimeStamp of the input frame, expressed as a number of
423 seconds
424
425 @item pos
426 position of the frame in the input stream, -1 if this information in
427 unavailable and/or meaningless (for example in case of synthetic audio)
428
429 @item fmt
430 sample format name
431
432 @item chlayout
433 channel layout description
434
435 @item nb_samples
436 number of samples (per each channel) contained in the filtered frame
437
438 @item rate
439 sample rate for the audio frame
440
441 @item checksum
442 Adler-32 checksum (printed in hexadecimal) of all the planes of the input frame
443
444 @item plane_checksum
445 Adler-32 checksum (printed in hexadecimal) for each input frame plane,
446 expressed in the form "[@var{c0} @var{c1} @var{c2} @var{c3} @var{c4} @var{c5}
447 @var{c6} @var{c7}]"
448 @end table
449
450 @section asplit
451
452 Split input audio into several identical outputs.
453
454 The filter accepts a single parameter which specifies the number of outputs. If
455 unspecified, it defaults to 2.
456
457 For example:
458 @example
459 [in] asplit [out0][out1]
460 @end example
461
462 will create two separate outputs from the same input.
463
464 To create 3 or more outputs, you need to specify the number of
465 outputs, like in:
466 @example
467 [in] asplit=3 [out0][out1][out2]
468 @end example
469
470 @example
471 ffmpeg -i INPUT -filter_complex asplit=5 OUTPUT
472 @end example
473 will create 5 copies of the input audio.
474
475
476 @section astreamsync
477
478 Forward two audio streams and control the order the buffers are forwarded.
479
480 The argument to the filter is an expression deciding which stream should be
481 forwarded next: if the result is negative, the first stream is forwarded; if
482 the result is positive or zero, the second stream is forwarded. It can use
483 the following variables:
484
485 @table @var
486 @item b1 b2
487 number of buffers forwarded so far on each stream
488 @item s1 s2
489 number of samples forwarded so far on each stream
490 @item t1 t2
491 current timestamp of each stream
492 @end table
493
494 The default value is @code{t1-t2}, which means to always forward the stream
495 that has a smaller timestamp.
496
497 Example: stress-test @code{amerge} by randomly sending buffers on the wrong
498 input, while avoiding too much of a desynchronization:
499 @example
500 amovie=file.ogg [a] ; amovie=file.mp3 [b] ;
501 [a] [b] astreamsync=(2*random(1))-1+tanh(5*(t1-t2)) [a2] [b2] ;
502 [a2] [b2] amerge
503 @end example
504
505 @section atempo
506
507 Adjust audio tempo.
508
509 The filter accepts exactly one parameter, the audio tempo. If not
510 specified then the filter will assume nominal 1.0 tempo. Tempo must
511 be in the [0.5, 2.0] range.
512
513 For example, to slow down audio to 80% tempo:
514 @example
515 atempo=0.8
516 @end example
517
518 For example, to speed up audio to 125% tempo:
519 @example
520 atempo=1.25
521 @end example
522
523 @section earwax
524
525 Make audio easier to listen to on headphones.
526
527 This filter adds `cues' to 44.1kHz stereo (i.e. audio CD format) audio
528 so that when listened to on headphones the stereo image is moved from
529 inside your head (standard for headphones) to outside and in front of
530 the listener (standard for speakers).
531
532 Ported from SoX.
533
534 @section pan
535
536 Mix channels with specific gain levels. The filter accepts the output
537 channel layout followed by a set of channels definitions.
538
539 This filter is also designed to remap efficiently the channels of an audio
540 stream.
541
542 The filter accepts parameters of the form:
543 "@var{l}:@var{outdef}:@var{outdef}:..."
544
545 @table @option
546 @item l
547 output channel layout or number of channels
548
549 @item outdef
550 output channel specification, of the form:
551 "@var{out_name}=[@var{gain}*]@var{in_name}[+[@var{gain}*]@var{in_name}...]"
552
553 @item out_name
554 output channel to define, either a channel name (FL, FR, etc.) or a channel
555 number (c0, c1, etc.)
556
557 @item gain
558 multiplicative coefficient for the channel, 1 leaving the volume unchanged
559
560 @item in_name
561 input channel to use, see out_name for details; it is not possible to mix
562 named and numbered input channels
563 @end table
564
565 If the `=' in a channel specification is replaced by `<', then the gains for
566 that specification will be renormalized so that the total is 1, thus
567 avoiding clipping noise.
568
569 @subsection Mixing examples
570
571 For example, if you want to down-mix from stereo to mono, but with a bigger
572 factor for the left channel:
573 @example
574 pan=1:c0=0.9*c0+0.1*c1
575 @end example
576
577 A customized down-mix to stereo that works automatically for 3-, 4-, 5- and
578 7-channels surround:
579 @example
580 pan=stereo: FL < FL + 0.5*FC + 0.6*BL + 0.6*SL : FR < FR + 0.5*FC + 0.6*BR + 0.6*SR
581 @end example
582
583 Note that @command{ffmpeg} integrates a default down-mix (and up-mix) system
584 that should be preferred (see "-ac" option) unless you have very specific
585 needs.
586
587 @subsection Remapping examples
588
589 The channel remapping will be effective if, and only if:
590
591 @itemize
592 @item gain coefficients are zeroes or ones,
593 @item only one input per channel output,
594 @end itemize
595
596 If all these conditions are satisfied, the filter will notify the user ("Pure
597 channel mapping detected"), and use an optimized and lossless method to do the
598 remapping.
599
600 For example, if you have a 5.1 source and want a stereo audio stream by
601 dropping the extra channels:
602 @example
603 pan="stereo: c0=FL : c1=FR"
604 @end example
605
606 Given the same source, you can also switch front left and front right channels
607 and keep the input channel layout:
608 @example
609 pan="5.1: c0=c1 : c1=c0 : c2=c2 : c3=c3 : c4=c4 : c5=c5"
610 @end example
611
612 If the input is a stereo audio stream, you can mute the front left channel (and
613 still keep the stereo channel layout) with:
614 @example
615 pan="stereo:c1=c1"
616 @end example
617
618 Still with a stereo audio stream input, you can copy the right channel in both
619 front left and right:
620 @example
621 pan="stereo: c0=FR : c1=FR"
622 @end example
623
624 @section silencedetect
625
626 Detect silence in an audio stream.
627
628 This filter logs a message when it detects that the input audio volume is less
629 or equal to a noise tolerance value for a duration greater or equal to the
630 minimum detected noise duration.
631
632 The printed times and duration are expressed in seconds.
633
634 @table @option
635 @item duration, d
636 Set silence duration until notification (default is 2 seconds).
637
638 @item noise, n
639 Set noise tolerance. Can be specified in dB (in case "dB" is appended to the
640 specified value) or amplitude ratio. Default is -60dB, or 0.001.
641 @end table
642
643 Detect 5 seconds of silence with -50dB noise tolerance:
644 @example
645 silencedetect=n=-50dB:d=5
646 @end example
647
648 Complete example with @command{ffmpeg} to detect silence with 0.0001 noise
649 tolerance in @file{silence.mp3}:
650 @example
651 ffmpeg -f lavfi -i amovie=silence.mp3,silencedetect=noise=0.0001 -f null -
652 @end example
653
654 @section volume
655
656 Adjust the input audio volume.
657
658 The filter accepts exactly one parameter @var{vol}, which expresses
659 how the audio volume will be increased or decreased.
660
661 Output values are clipped to the maximum value.
662
663 If @var{vol} is expressed as a decimal number, the output audio
664 volume is given by the relation:
665 @example
666 @var{output_volume} = @var{vol} * @var{input_volume}
667 @end example
668
669 If @var{vol} is expressed as a decimal number followed by the string
670 "dB", the value represents the requested change in decibels of the
671 input audio power, and the output audio volume is given by the
672 relation:
673 @example
674 @var{output_volume} = 10^(@var{vol}/20) * @var{input_volume}
675 @end example
676
677 Otherwise @var{vol} is considered an expression and its evaluated
678 value is used for computing the output audio volume according to the
679 first relation.
680
681 Default value for @var{vol} is 1.0.
682
683 @subsection Examples
684
685 @itemize
686 @item
687 Half the input audio volume:
688 @example
689 volume=0.5
690 @end example
691
692 The above example is equivalent to:
693 @example
694 volume=1/2
695 @end example
696
697 @item
698 Decrease input audio power by 12 decibels:
699 @example
700 volume=-12dB
701 @end example
702 @end itemize
703
704 @section volumedetect
705
706 Detect the volume of the input video.
707
708 The filter has no parameters. The input is not modified. Statistics about
709 the volume will be printed in the log when the input stream end is reached.
710
711 In particular it will show the mean volume (root mean square), maximum
712 volume (on a per-sample basis), and the beginning of an histogram of the
713 registered volume values (from the maximum value to a cumulated 1/1000 of
714 the samples).
715
716 All volumes are in decibels relative to the maximum PCM value.
717
718 Here is an excerpt of the output:
719 @example
720 [Parsed_volumedetect_0 @ 0xa23120] mean_volume: -27 dB
721 [Parsed_volumedetect_0 @ 0xa23120] max_volume: -4 dB
722 [Parsed_volumedetect_0 @ 0xa23120] histogram_4db: 6
723 [Parsed_volumedetect_0 @ 0xa23120] histogram_5db: 62
724 [Parsed_volumedetect_0 @ 0xa23120] histogram_6db: 286
725 [Parsed_volumedetect_0 @ 0xa23120] histogram_7db: 1042
726 [Parsed_volumedetect_0 @ 0xa23120] histogram_8db: 2551
727 [Parsed_volumedetect_0 @ 0xa23120] histogram_9db: 4609
728 [Parsed_volumedetect_0 @ 0xa23120] histogram_10db: 8409
729 @end example
730
731 It means that:
732 @itemize
733 @item
734 The mean square energy is approximately -27 dB, or 10^-2.7.
735 @item
736 The largest sample is at -4 dB, or more precisely between -4 dB and -5 dB.
737 @item
738 There are 6 samples at -4 dB, 62 at -5 dB, 286 at -6 dB, etc.
739 @end itemize
740
741 In other words, raising the volume by +4 dB does not cause any clipping,
742 raising it by +5 dB causes clipping for 6 samples, etc.
743
744 @section asyncts
745 Synchronize audio data with timestamps by squeezing/stretching it and/or
746 dropping samples/adding silence when needed.
747
748 The filter accepts the following named parameters:
749 @table @option
750
751 @item compensate
752 Enable stretching/squeezing the data to make it match the timestamps. Disabled
753 by default. When disabled, time gaps are covered with silence.
754
755 @item min_delta
756 Minimum difference between timestamps and audio data (in seconds) to trigger
757 adding/dropping samples. Default value is 0.1. If you get non-perfect sync with
758 this filter, try setting this parameter to 0.
759
760 @item max_comp
761 Maximum compensation in samples per second. Relevant only with compensate=1.
762 Default value 500.
763
764 @item first_pts
765 Assume the first pts should be this value.
766 This allows for padding/trimming at the start of stream. By default, no
767 assumption is made about the first frame's expected pts, so no padding or
768 trimming is done. For example, this could be set to 0 to pad the beginning with
769 silence if an audio stream starts after the video stream.
770
771 @end table
772
773 @section channelsplit
774 Split each channel in input audio stream into a separate output stream.
775
776 This filter accepts the following named parameters:
777 @table @option
778 @item channel_layout
779 Channel layout of the input stream. Default is "stereo".
780 @end table
781
782 For example, assuming a stereo input MP3 file
783 @example
784 ffmpeg -i in.mp3 -filter_complex channelsplit out.mkv
785 @end example
786 will create an output Matroska file with two audio streams, one containing only
787 the left channel and the other the right channel.
788
789 To split a 5.1 WAV file into per-channel files
790 @example
791 ffmpeg -i in.wav -filter_complex
792 'channelsplit=channel_layout=5.1[FL][FR][FC][LFE][SL][SR]'
793 -map '[FL]' front_left.wav -map '[FR]' front_right.wav -map '[FC]'
794 front_center.wav -map '[LFE]' lfe.wav -map '[SL]' side_left.wav -map '[SR]'
795 side_right.wav
796 @end example
797
798 @section channelmap
799 Remap input channels to new locations.
800
801 This filter accepts the following named parameters:
802 @table @option
803 @item channel_layout
804 Channel layout of the output stream.
805
806 @item map
807 Map channels from input to output. The argument is a comma-separated list of
808 mappings, each in the @code{@var{in_channel}-@var{out_channel}} or
809 @var{in_channel} form. @var{in_channel} can be either the name of the input
810 channel (e.g. FL for front left) or its index in the input channel layout.
811 @var{out_channel} is the name of the output channel or its index in the output
812 channel layout. If @var{out_channel} is not given then it is implicitly an
813 index, starting with zero and increasing by one for each mapping.
814 @end table
815
816 If no mapping is present, the filter will implicitly map input channels to
817 output channels preserving index.
818
819 For example, assuming a 5.1+downmix input MOV file
820 @example
821 ffmpeg -i in.mov -filter 'channelmap=map=DL-FL\,DR-FR' out.wav
822 @end example
823 will create an output WAV file tagged as stereo from the downmix channels of
824 the input.
825
826 To fix a 5.1 WAV improperly encoded in AAC's native channel order
827 @example
828 ffmpeg -i in.wav -filter 'channelmap=1\,2\,0\,5\,3\,4:channel_layout=5.1' out.wav
829 @end example
830
831 @section join
832 Join multiple input streams into one multi-channel stream.
833
834 The filter accepts the following named parameters:
835 @table @option
836
837 @item inputs
838 Number of input streams. Defaults to 2.
839
840 @item channel_layout
841 Desired output channel layout. Defaults to stereo.
842
843 @item map
844 Map channels from inputs to output. The argument is a comma-separated list of
845 mappings, each in the @code{@var{input_idx}.@var{in_channel}-@var{out_channel}}
846 form. @var{input_idx} is the 0-based index of the input stream. @var{in_channel}
847 can be either the name of the input channel (e.g. FL for front left) or its
848 index in the specified input stream. @var{out_channel} is the name of the output
849 channel.
850 @end table
851
852 The filter will attempt to guess the mappings when those are not specified
853 explicitly. It does so by first trying to find an unused matching input channel
854 and if that fails it picks the first unused input channel.
855
856 E.g. to join 3 inputs (with properly set channel layouts)
857 @example
858 ffmpeg -i INPUT1 -i INPUT2 -i INPUT3 -filter_complex join=inputs=3 OUTPUT
859 @end example
860
861 To build a 5.1 output from 6 single-channel streams:
862 @example
863 ffmpeg -i fl -i fr -i fc -i sl -i sr -i lfe -filter_complex
864 'join=inputs=6:channel_layout=5.1:map=0.0-FL\,1.0-FR\,2.0-FC\,3.0-SL\,4.0-SR\,5.0-LFE'
865 out
866 @end example
867
868 @section resample
869 Convert the audio sample format, sample rate and channel layout. This filter is
870 not meant to be used directly.
871
872 @c man end AUDIO FILTERS
873
874 @chapter Audio Sources
875 @c man begin AUDIO SOURCES
876
877 Below is a description of the currently available audio sources.
878
879 @section abuffer
880
881 Buffer audio frames, and make them available to the filter chain.
882
883 This source is mainly intended for a programmatic use, in particular
884 through the interface defined in @file{libavfilter/asrc_abuffer.h}.
885
886 It accepts the following mandatory parameters:
887 @var{sample_rate}:@var{sample_fmt}:@var{channel_layout}
888
889 @table @option
890
891 @item sample_rate
892 The sample rate of the incoming audio buffers.
893
894 @item sample_fmt
895 The sample format of the incoming audio buffers.
896 Either a sample format name or its corresponging integer representation from
897 the enum AVSampleFormat in @file{libavutil/samplefmt.h}
898
899 @item channel_layout
900 The channel layout of the incoming audio buffers.
901 Either a channel layout name from channel_layout_map in
902 @file{libavutil/audioconvert.c} or its corresponding integer representation
903 from the AV_CH_LAYOUT_* macros in @file{libavutil/audioconvert.h}
904
905 @end table
906
907 For example:
908 @example
909 abuffer=44100:s16p:stereo
910 @end example
911
912 will instruct the source to accept planar 16bit signed stereo at 44100Hz.
913 Since the sample format with name "s16p" corresponds to the number
914 6 and the "stereo" channel layout corresponds to the value 0x3, this is
915 equivalent to:
916 @example
917 abuffer=44100:6:0x3
918 @end example
919
920 @section aevalsrc
921
922 Generate an audio signal specified by an expression.
923
924 This source accepts in input one or more expressions (one for each
925 channel), which are evaluated and used to generate a corresponding
926 audio signal.
927
928 It accepts the syntax: @var{exprs}[::@var{options}].
929 @var{exprs} is a list of expressions separated by ":", one for each
930 separate channel. In case the @var{channel_layout} is not
931 specified, the selected channel layout depends on the number of
932 provided expressions.
933
934 @var{options} is an optional sequence of @var{key}=@var{value} pairs,
935 separated by ":".
936
937 The description of the accepted options follows.
938
939 @table @option
940
941 @item channel_layout, c
942 Set the channel layout. The number of channels in the specified layout
943 must be equal to the number of specified expressions.
944
945 @item duration, d
946 Set the minimum duration of the sourced audio. See the function
947 @code{av_parse_time()} for the accepted format.
948 Note that the resulting duration may be greater than the specified
949 duration, as the generated audio is always cut at the end of a
950 complete frame.
951
952 If not specified, or the expressed duration is negative, the audio is
953 supposed to be generated forever.
954
955 @item nb_samples, n
956 Set the number of samples per channel per each output frame,
957 default to 1024.
958
959 @item sample_rate, s
960 Specify the sample rate, default to 44100.
961 @end table
962
963 Each expression in @var{exprs} can contain the following constants:
964
965 @table @option
966 @item n
967 number of the evaluated sample, starting from 0
968
969 @item t
970 time of the evaluated sample expressed in seconds, starting from 0
971
972 @item s
973 sample rate
974
975 @end table
976
977 @subsection Examples
978
979 @itemize
980
981 @item
982 Generate silence:
983 @example
984 aevalsrc=0
985 @end example
986
987 @item
988
989 Generate a sin signal with frequency of 440 Hz, set sample rate to
990 8000 Hz:
991 @example
992 aevalsrc="sin(440*2*PI*t)::s=8000"
993 @end example
994
995 @item
996 Generate a two channels signal, specify the channel layout (Front
997 Center + Back Center) explicitly:
998 @example
999 aevalsrc="sin(420*2*PI*t):cos(430*2*PI*t)::c=FC|BC"
1000 @end example
1001
1002 @item
1003 Generate white noise:
1004 @example
1005 aevalsrc="-2+random(0)"
1006 @end example
1007
1008 @item
1009 Generate an amplitude modulated signal:
1010 @example
1011 aevalsrc="sin(10*2*PI*t)*sin(880*2*PI*t)"
1012 @end example
1013
1014 @item
1015 Generate 2.5 Hz binaural beats on a 360 Hz carrier:
1016 @example
1017 aevalsrc="0.1*sin(2*PI*(360-2.5/2)*t) : 0.1*sin(2*PI*(360+2.5/2)*t)"
1018 @end example
1019
1020 @end itemize
1021
1022 @section anullsrc
1023
1024 Null audio source, return unprocessed audio frames. It is mainly useful
1025 as a template and to be employed in analysis / debugging tools, or as
1026 the source for filters which ignore the input data (for example the sox
1027 synth filter).
1028
1029 It accepts an optional sequence of @var{key}=@var{value} pairs,
1030 separated by ":".
1031
1032 The description of the accepted options follows.
1033
1034 @table @option
1035
1036 @item sample_rate, s
1037 Specify the sample rate, and defaults to 44100.
1038
1039 @item channel_layout, cl
1040
1041 Specify the channel layout, and can be either an integer or a string
1042 representing a channel layout. The default value of @var{channel_layout}
1043 is "stereo".
1044
1045 Check the channel_layout_map definition in
1046 @file{libavcodec/audioconvert.c} for the mapping between strings and
1047 channel layout values.
1048
1049 @item nb_samples, n
1050 Set the number of samples per requested frames.
1051
1052 @end table
1053
1054 Follow some examples:
1055 @example
1056 #  set the sample rate to 48000 Hz and the channel layout to AV_CH_LAYOUT_MONO.
1057 anullsrc=r=48000:cl=4
1058
1059 # same as
1060 anullsrc=r=48000:cl=mono
1061 @end example
1062
1063 @section abuffer
1064 Buffer audio frames, and make them available to the filter chain.
1065
1066 This source is not intended to be part of user-supplied graph descriptions but
1067 for insertion by calling programs through the interface defined in
1068 @file{libavfilter/buffersrc.h}.
1069
1070 It accepts the following named parameters:
1071 @table @option
1072
1073 @item time_base
1074 Timebase which will be used for timestamps of submitted frames. It must be
1075 either a floating-point number or in @var{numerator}/@var{denominator} form.
1076
1077 @item sample_rate
1078 Audio sample rate.
1079
1080 @item sample_fmt
1081 Name of the sample format, as returned by @code{av_get_sample_fmt_name()}.
1082
1083 @item channel_layout
1084 Channel layout of the audio data, in the form that can be accepted by
1085 @code{av_get_channel_layout()}.
1086 @end table
1087
1088 All the parameters need to be explicitly defined.
1089
1090 @section flite
1091
1092 Synthesize a voice utterance using the libflite library.
1093
1094 To enable compilation of this filter you need to configure FFmpeg with
1095 @code{--enable-libflite}.
1096
1097 Note that the flite library is not thread-safe.
1098
1099 The source accepts parameters as a list of @var{key}=@var{value} pairs,
1100 separated by ":".
1101
1102 The description of the accepted parameters follows.
1103
1104 @table @option
1105
1106 @item list_voices
1107 If set to 1, list the names of the available voices and exit
1108 immediately. Default value is 0.
1109
1110 @item nb_samples, n
1111 Set the maximum number of samples per frame. Default value is 512.
1112
1113 @item textfile
1114 Set the filename containing the text to speak.
1115
1116 @item text
1117 Set the text to speak.
1118
1119 @item voice, v
1120 Set the voice to use for the speech synthesis. Default value is
1121 @code{kal}. See also the @var{list_voices} option.
1122 @end table
1123
1124 @subsection Examples
1125
1126 @itemize
1127 @item
1128 Read from file @file{speech.txt}, and synthetize the text using the
1129 standard flite voice:
1130 @example
1131 flite=textfile=speech.txt
1132 @end example
1133
1134 @item
1135 Read the specified text selecting the @code{slt} voice:
1136 @example
1137 flite=text='So fare thee well, poor devil of a Sub-Sub, whose commentator I am':voice=slt
1138 @end example
1139
1140 @item
1141 Make @file{ffplay} speech the specified text, using @code{flite} and
1142 the @code{lavfi} device:
1143 @example
1144 ffplay -f lavfi flite='No more be grieved for which that thou hast done.'
1145 @end example
1146 @end itemize
1147
1148 For more information about libflite, check:
1149 @url{http://www.speech.cs.cmu.edu/flite/}
1150
1151 @c man end AUDIO SOURCES
1152
1153 @chapter Audio Sinks
1154 @c man begin AUDIO SINKS
1155
1156 Below is a description of the currently available audio sinks.
1157
1158 @section abuffersink
1159
1160 Buffer audio frames, and make them available to the end of filter chain.
1161
1162 This sink is mainly intended for programmatic use, in particular
1163 through the interface defined in @file{libavfilter/buffersink.h}.
1164
1165 It requires a pointer to an AVABufferSinkContext structure, which
1166 defines the incoming buffers' formats, to be passed as the opaque
1167 parameter to @code{avfilter_init_filter} for initialization.
1168
1169 @section anullsink
1170
1171 Null audio sink, do absolutely nothing with the input audio. It is
1172 mainly useful as a template and to be employed in analysis / debugging
1173 tools.
1174
1175 @section abuffersink
1176 This sink is intended for programmatic use. Frames that arrive on this sink can
1177 be retrieved by the calling program using the interface defined in
1178 @file{libavfilter/buffersink.h}.
1179
1180 This filter accepts no parameters.
1181
1182 @c man end AUDIO SINKS
1183
1184 @chapter Video Filters
1185 @c man begin VIDEO FILTERS
1186
1187 When you configure your FFmpeg build, you can disable any of the
1188 existing filters using @code{--disable-filters}.
1189 The configure output will show the video filters included in your
1190 build.
1191
1192 Below is a description of the currently available video filters.
1193
1194 @section alphaextract
1195
1196 Extract the alpha component from the input as a grayscale video. This
1197 is especially useful with the @var{alphamerge} filter.
1198
1199 @section alphamerge
1200
1201 Add or replace the alpha component of the primary input with the
1202 grayscale value of a second input. This is intended for use with
1203 @var{alphaextract} to allow the transmission or storage of frame
1204 sequences that have alpha in a format that doesn't support an alpha
1205 channel.
1206
1207 For example, to reconstruct full frames from a normal YUV-encoded video
1208 and a separate video created with @var{alphaextract}, you might use:
1209 @example
1210 movie=in_alpha.mkv [alpha]; [in][alpha] alphamerge [out]
1211 @end example
1212
1213 Since this filter is designed for reconstruction, it operates on frame
1214 sequences without considering timestamps, and terminates when either
1215 input reaches end of stream. This will cause problems if your encoding
1216 pipeline drops frames. If you're trying to apply an image as an
1217 overlay to a video stream, consider the @var{overlay} filter instead.
1218
1219 @section ass
1220
1221 Draw ASS (Advanced Substation Alpha) subtitles on top of input video
1222 using the libass library.
1223
1224 To enable compilation of this filter you need to configure FFmpeg with
1225 @code{--enable-libass}.
1226
1227 This filter accepts the syntax: @var{ass_filename}[:@var{options}],
1228 where @var{ass_filename} is the filename of the ASS file to read, and
1229 @var{options} is an optional sequence of @var{key}=@var{value} pairs,
1230 separated by ":".
1231
1232 A description of the accepted options follows.
1233
1234 @table @option
1235 @item original_size
1236 Specifies the size of the original video, the video for which the ASS file
1237 was composed. Due to a misdesign in ASS aspect ratio arithmetic, this is
1238 necessary to correctly scale the fonts if the aspect ratio has been changed.
1239 @end table
1240
1241 For example, to render the file @file{sub.ass} on top of the input
1242 video, use the command:
1243 @example
1244 ass=sub.ass
1245 @end example
1246
1247 @section bbox
1248
1249 Compute the bounding box for the non-black pixels in the input frame
1250 luminance plane.
1251
1252 This filter computes the bounding box containing all the pixels with a
1253 luminance value greater than the minimum allowed value.
1254 The parameters describing the bounding box are printed on the filter
1255 log.
1256
1257 @section blackdetect
1258
1259 Detect video intervals that are (almost) completely black. Can be
1260 useful to detect chapter transitions, commercials, or invalid
1261 recordings. Output lines contains the time for the start, end and
1262 duration of the detected black interval expressed in seconds.
1263
1264 In order to display the output lines, you need to set the loglevel at
1265 least to the AV_LOG_INFO value.
1266
1267 This filter accepts a list of options in the form of
1268 @var{key}=@var{value} pairs separated by ":". A description of the
1269 accepted options follows.
1270
1271 @table @option
1272 @item black_min_duration, d
1273 Set the minimum detected black duration expressed in seconds. It must
1274 be a non-negative floating point number.
1275
1276 Default value is 2.0.
1277
1278 @item picture_black_ratio_th, pic_th
1279 Set the threshold for considering a picture "black".
1280 Express the minimum value for the ratio:
1281 @example
1282 @var{nb_black_pixels} / @var{nb_pixels}
1283 @end example
1284
1285 for which a picture is considered black.
1286 Default value is 0.98.
1287
1288 @item pixel_black_th, pix_th
1289 Set the threshold for considering a pixel "black".
1290
1291 The threshold expresses the maximum pixel luminance value for which a
1292 pixel is considered "black". The provided value is scaled according to
1293 the following equation:
1294 @example
1295 @var{absolute_threshold} = @var{luminance_minimum_value} + @var{pixel_black_th} * @var{luminance_range_size}
1296 @end example
1297
1298 @var{luminance_range_size} and @var{luminance_minimum_value} depend on
1299 the input video format, the range is [0-255] for YUV full-range
1300 formats and [16-235] for YUV non full-range formats.
1301
1302 Default value is 0.10.
1303 @end table
1304
1305 The following example sets the maximum pixel threshold to the minimum
1306 value, and detects only black intervals of 2 or more seconds:
1307 @example
1308 blackdetect=d=2:pix_th=0.00
1309 @end example
1310
1311 @section blackframe
1312
1313 Detect frames that are (almost) completely black. Can be useful to
1314 detect chapter transitions or commercials. Output lines consist of
1315 the frame number of the detected frame, the percentage of blackness,
1316 the position in the file if known or -1 and the timestamp in seconds.
1317
1318 In order to display the output lines, you need to set the loglevel at
1319 least to the AV_LOG_INFO value.
1320
1321 The filter accepts the syntax:
1322 @example
1323 blackframe[=@var{amount}:[@var{threshold}]]
1324 @end example
1325
1326 @var{amount} is the percentage of the pixels that have to be below the
1327 threshold, and defaults to 98.
1328
1329 @var{threshold} is the threshold below which a pixel value is
1330 considered black, and defaults to 32.
1331
1332 @section boxblur
1333
1334 Apply boxblur algorithm to the input video.
1335
1336 This filter accepts the parameters:
1337 @var{luma_radius}:@var{luma_power}:@var{chroma_radius}:@var{chroma_power}:@var{alpha_radius}:@var{alpha_power}
1338
1339 Chroma and alpha parameters are optional, if not specified they default
1340 to the corresponding values set for @var{luma_radius} and
1341 @var{luma_power}.
1342
1343 @var{luma_radius}, @var{chroma_radius}, and @var{alpha_radius} represent
1344 the radius in pixels of the box used for blurring the corresponding
1345 input plane. They are expressions, and can contain the following
1346 constants:
1347 @table @option
1348 @item w, h
1349 the input width and height in pixels
1350
1351 @item cw, ch
1352 the input chroma image width and height in pixels
1353
1354 @item hsub, vsub
1355 horizontal and vertical chroma subsample values. For example for the
1356 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
1357 @end table
1358
1359 The radius must be a non-negative number, and must not be greater than
1360 the value of the expression @code{min(w,h)/2} for the luma and alpha planes,
1361 and of @code{min(cw,ch)/2} for the chroma planes.
1362
1363 @var{luma_power}, @var{chroma_power}, and @var{alpha_power} represent
1364 how many times the boxblur filter is applied to the corresponding
1365 plane.
1366
1367 Some examples follow:
1368
1369 @itemize
1370
1371 @item
1372 Apply a boxblur filter with luma, chroma, and alpha radius
1373 set to 2:
1374 @example
1375 boxblur=2:1
1376 @end example
1377
1378 @item
1379 Set luma radius to 2, alpha and chroma radius to 0
1380 @example
1381 boxblur=2:1:0:0:0:0
1382 @end example
1383
1384 @item
1385 Set luma and chroma radius to a fraction of the video dimension
1386 @example
1387 boxblur=min(h\,w)/10:1:min(cw\,ch)/10:1
1388 @end example
1389
1390 @end itemize
1391
1392 @section colormatrix
1393
1394 The colormatrix filter allows conversion between any of the following color
1395 space: BT.709 (@var{bt709}), BT.601 (@var{bt601}), SMPTE-240M (@var{smpte240m})
1396 and FCC (@var{fcc}).
1397
1398 The syntax of the parameters is @var{source}:@var{destination}:
1399
1400 @example
1401 colormatrix=bt601:smpte240m
1402 @end example
1403
1404 @section copy
1405
1406 Copy the input source unchanged to the output. Mainly useful for
1407 testing purposes.
1408
1409 @section crop
1410
1411 Crop the input video to @var{out_w}:@var{out_h}:@var{x}:@var{y}:@var{keep_aspect}
1412
1413 The @var{keep_aspect} parameter is optional, if specified and set to a
1414 non-zero value will force the output display aspect ratio to be the
1415 same of the input, by changing the output sample aspect ratio.
1416
1417 The @var{out_w}, @var{out_h}, @var{x}, @var{y} parameters are
1418 expressions containing the following constants:
1419
1420 @table @option
1421 @item x, y
1422 the computed values for @var{x} and @var{y}. They are evaluated for
1423 each new frame.
1424
1425 @item in_w, in_h
1426 the input width and height
1427
1428 @item iw, ih
1429 same as @var{in_w} and @var{in_h}
1430
1431 @item out_w, out_h
1432 the output (cropped) width and height
1433
1434 @item ow, oh
1435 same as @var{out_w} and @var{out_h}
1436
1437 @item a
1438 same as @var{iw} / @var{ih}
1439
1440 @item sar
1441 input sample aspect ratio
1442
1443 @item dar
1444 input display aspect ratio, it is the same as (@var{iw} / @var{ih}) * @var{sar}
1445
1446 @item hsub, vsub
1447 horizontal and vertical chroma subsample values. For example for the
1448 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
1449
1450 @item n
1451 the number of input frame, starting from 0
1452
1453 @item pos
1454 the position in the file of the input frame, NAN if unknown
1455
1456 @item t
1457 timestamp expressed in seconds, NAN if the input timestamp is unknown
1458
1459 @end table
1460
1461 The @var{out_w} and @var{out_h} parameters specify the expressions for
1462 the width and height of the output (cropped) video. They are
1463 evaluated just at the configuration of the filter.
1464
1465 The default value of @var{out_w} is "in_w", and the default value of
1466 @var{out_h} is "in_h".
1467
1468 The expression for @var{out_w} may depend on the value of @var{out_h},
1469 and the expression for @var{out_h} may depend on @var{out_w}, but they
1470 cannot depend on @var{x} and @var{y}, as @var{x} and @var{y} are
1471 evaluated after @var{out_w} and @var{out_h}.
1472
1473 The @var{x} and @var{y} parameters specify the expressions for the
1474 position of the top-left corner of the output (non-cropped) area. They
1475 are evaluated for each frame. If the evaluated value is not valid, it
1476 is approximated to the nearest valid value.
1477
1478 The default value of @var{x} is "(in_w-out_w)/2", and the default
1479 value for @var{y} is "(in_h-out_h)/2", which set the cropped area at
1480 the center of the input image.
1481
1482 The expression for @var{x} may depend on @var{y}, and the expression
1483 for @var{y} may depend on @var{x}.
1484
1485 Follow some examples:
1486 @example
1487 # crop the central input area with size 100x100
1488 crop=100:100
1489
1490 # crop the central input area with size 2/3 of the input video
1491 "crop=2/3*in_w:2/3*in_h"
1492
1493 # crop the input video central square
1494 crop=in_h
1495
1496 # delimit the rectangle with the top-left corner placed at position
1497 # 100:100 and the right-bottom corner corresponding to the right-bottom
1498 # corner of the input image.
1499 crop=in_w-100:in_h-100:100:100
1500
1501 # crop 10 pixels from the left and right borders, and 20 pixels from
1502 # the top and bottom borders
1503 "crop=in_w-2*10:in_h-2*20"
1504
1505 # keep only the bottom right quarter of the input image
1506 "crop=in_w/2:in_h/2:in_w/2:in_h/2"
1507
1508 # crop height for getting Greek harmony
1509 "crop=in_w:1/PHI*in_w"
1510
1511 # trembling effect
1512 "crop=in_w/2:in_h/2:(in_w-out_w)/2+((in_w-out_w)/2)*sin(n/10):(in_h-out_h)/2 +((in_h-out_h)/2)*sin(n/7)"
1513
1514 # erratic camera effect depending on timestamp
1515 "crop=in_w/2:in_h/2:(in_w-out_w)/2+((in_w-out_w)/2)*sin(t*10):(in_h-out_h)/2 +((in_h-out_h)/2)*sin(t*13)"
1516
1517 # set x depending on the value of y
1518 "crop=in_w/2:in_h/2:y:10+10*sin(n/10)"
1519 @end example
1520
1521 @section cropdetect
1522
1523 Auto-detect crop size.
1524
1525 Calculate necessary cropping parameters and prints the recommended
1526 parameters through the logging system. The detected dimensions
1527 correspond to the non-black area of the input video.
1528
1529 It accepts the syntax:
1530 @example
1531 cropdetect[=@var{limit}[:@var{round}[:@var{reset}]]]
1532 @end example
1533
1534 @table @option
1535
1536 @item limit
1537 Threshold, which can be optionally specified from nothing (0) to
1538 everything (255), defaults to 24.
1539
1540 @item round
1541 Value which the width/height should be divisible by, defaults to
1542 16. The offset is automatically adjusted to center the video. Use 2 to
1543 get only even dimensions (needed for 4:2:2 video). 16 is best when
1544 encoding to most video codecs.
1545
1546 @item reset
1547 Counter that determines after how many frames cropdetect will reset
1548 the previously detected largest video area and start over to detect
1549 the current optimal crop area. Defaults to 0.
1550
1551 This can be useful when channel logos distort the video area. 0
1552 indicates never reset and return the largest area encountered during
1553 playback.
1554 @end table
1555
1556 @section decimate
1557
1558 This filter drops frames that do not differ greatly from the previous
1559 frame in order to reduce framerate.  The main use of this filter is
1560 for very-low-bitrate encoding (e.g. streaming over dialup modem), but
1561 it could in theory be used for fixing movies that were
1562 inverse-telecined incorrectly.
1563
1564 It accepts the following parameters:
1565 @var{max}:@var{hi}:@var{lo}:@var{frac}.
1566
1567 @table @option
1568
1569 @item max
1570 Set the maximum number of consecutive frames which can be dropped (if
1571 positive), or the minimum interval between dropped frames (if
1572 negative). If the value is 0, the frame is dropped unregarding the
1573 number of previous sequentially dropped frames.
1574
1575 Default value is 0.
1576
1577 @item hi, lo, frac
1578 Set the dropping threshold values.
1579
1580 Values for @var{hi} and @var{lo} are for 8x8 pixel blocks and
1581 represent actual pixel value differences, so a threshold of 64
1582 corresponds to 1 unit of difference for each pixel, or the same spread
1583 out differently over the block.
1584
1585 A frame is a candidate for dropping if no 8x8 blocks differ by more
1586 than a threshold of @var{hi}, and if no more than @var{frac} blocks (1
1587 meaning the whole image) differ by more than a threshold of @var{lo}.
1588
1589 Default value for @var{hi} is 64*12, default value for @var{lo} is
1590 64*5, and default value for @var{frac} is 0.33.
1591 @end table
1592
1593 @section delogo
1594
1595 Suppress a TV station logo by a simple interpolation of the surrounding
1596 pixels. Just set a rectangle covering the logo and watch it disappear
1597 (and sometimes something even uglier appear - your mileage may vary).
1598
1599 The filter accepts parameters as a string of the form
1600 "@var{x}:@var{y}:@var{w}:@var{h}:@var{band}", or as a list of
1601 @var{key}=@var{value} pairs, separated by ":".
1602
1603 The description of the accepted parameters follows.
1604
1605 @table @option
1606
1607 @item x, y
1608 Specify the top left corner coordinates of the logo. They must be
1609 specified.
1610
1611 @item w, h
1612 Specify the width and height of the logo to clear. They must be
1613 specified.
1614
1615 @item band, t
1616 Specify the thickness of the fuzzy edge of the rectangle (added to
1617 @var{w} and @var{h}). The default value is 4.
1618
1619 @item show
1620 When set to 1, a green rectangle is drawn on the screen to simplify
1621 finding the right @var{x}, @var{y}, @var{w}, @var{h} parameters, and
1622 @var{band} is set to 4. The default value is 0.
1623
1624 @end table
1625
1626 Some examples follow.
1627
1628 @itemize
1629
1630 @item
1631 Set a rectangle covering the area with top left corner coordinates 0,0
1632 and size 100x77, setting a band of size 10:
1633 @example
1634 delogo=0:0:100:77:10
1635 @end example
1636
1637 @item
1638 As the previous example, but use named options:
1639 @example
1640 delogo=x=0:y=0:w=100:h=77:band=10
1641 @end example
1642
1643 @end itemize
1644
1645 @section deshake
1646
1647 Attempt to fix small changes in horizontal and/or vertical shift. This
1648 filter helps remove camera shake from hand-holding a camera, bumping a
1649 tripod, moving on a vehicle, etc.
1650
1651 The filter accepts parameters as a string of the form
1652 "@var{x}:@var{y}:@var{w}:@var{h}:@var{rx}:@var{ry}:@var{edge}:@var{blocksize}:@var{contrast}:@var{search}:@var{filename}"
1653
1654 A description of the accepted parameters follows.
1655
1656 @table @option
1657
1658 @item x, y, w, h
1659 Specify a rectangular area where to limit the search for motion
1660 vectors.
1661 If desired the search for motion vectors can be limited to a
1662 rectangular area of the frame defined by its top left corner, width
1663 and height. These parameters have the same meaning as the drawbox
1664 filter which can be used to visualise the position of the bounding
1665 box.
1666
1667 This is useful when simultaneous movement of subjects within the frame
1668 might be confused for camera motion by the motion vector search.
1669
1670 If any or all of @var{x}, @var{y}, @var{w} and @var{h} are set to -1
1671 then the full frame is used. This allows later options to be set
1672 without specifying the bounding box for the motion vector search.
1673
1674 Default - search the whole frame.
1675
1676 @item rx, ry
1677 Specify the maximum extent of movement in x and y directions in the
1678 range 0-64 pixels. Default 16.
1679
1680 @item edge
1681 Specify how to generate pixels to fill blanks at the edge of the
1682 frame. An integer from 0 to 3 as follows:
1683 @table @option
1684 @item 0
1685 Fill zeroes at blank locations
1686 @item 1
1687 Original image at blank locations
1688 @item 2
1689 Extruded edge value at blank locations
1690 @item 3
1691 Mirrored edge at blank locations
1692 @end table
1693
1694 The default setting is mirror edge at blank locations.
1695
1696 @item blocksize
1697 Specify the blocksize to use for motion search. Range 4-128 pixels,
1698 default 8.
1699
1700 @item contrast
1701 Specify the contrast threshold for blocks. Only blocks with more than
1702 the specified contrast (difference between darkest and lightest
1703 pixels) will be considered. Range 1-255, default 125.
1704
1705 @item search
1706 Specify the search strategy 0 = exhaustive search, 1 = less exhaustive
1707 search. Default - exhaustive search.
1708
1709 @item filename
1710 If set then a detailed log of the motion search is written to the
1711 specified file.
1712
1713 @end table
1714
1715 @section drawbox
1716
1717 Draw a colored box on the input image.
1718
1719 It accepts the syntax:
1720 @example
1721 drawbox=@var{x}:@var{y}:@var{width}:@var{height}:@var{color}
1722 @end example
1723
1724 @table @option
1725
1726 @item x, y
1727 Specify the top left corner coordinates of the box. Default to 0.
1728
1729 @item width, height
1730 Specify the width and height of the box, if 0 they are interpreted as
1731 the input width and height. Default to 0.
1732
1733 @item color
1734 Specify the color of the box to write, it can be the name of a color
1735 (case insensitive match) or a 0xRRGGBB[AA] sequence.
1736 @end table
1737
1738 Follow some examples:
1739 @example
1740 # draw a black box around the edge of the input image
1741 drawbox
1742
1743 # draw a box with color red and an opacity of 50%
1744 drawbox=10:20:200:60:red@@0.5"
1745 @end example
1746
1747 @section drawtext
1748
1749 Draw text string or text from specified file on top of video using the
1750 libfreetype library.
1751
1752 To enable compilation of this filter you need to configure FFmpeg with
1753 @code{--enable-libfreetype}.
1754
1755 The filter also recognizes strftime() sequences in the provided text
1756 and expands them accordingly. Check the documentation of strftime().
1757
1758 The filter accepts parameters as a list of @var{key}=@var{value} pairs,
1759 separated by ":".
1760
1761 The description of the accepted parameters follows.
1762
1763 @table @option
1764
1765 @item box
1766 Used to draw a box around text using background color.
1767 Value should be either 1 (enable) or 0 (disable).
1768 The default value of @var{box} is 0.
1769
1770 @item boxcolor
1771 The color to be used for drawing box around text.
1772 Either a string (e.g. "yellow") or in 0xRRGGBB[AA] format
1773 (e.g. "0xff00ff"), possibly followed by an alpha specifier.
1774 The default value of @var{boxcolor} is "white".
1775
1776 @item draw
1777 Set an expression which specifies if the text should be drawn. If the
1778 expression evaluates to 0, the text is not drawn. This is useful for
1779 specifying that the text should be drawn only when specific conditions
1780 are met.
1781
1782 Default value is "1".
1783
1784 See below for the list of accepted constants and functions.
1785
1786 @item fix_bounds
1787 If true, check and fix text coords to avoid clipping.
1788
1789 @item fontcolor
1790 The color to be used for drawing fonts.
1791 Either a string (e.g. "red") or in 0xRRGGBB[AA] format
1792 (e.g. "0xff000033"), possibly followed by an alpha specifier.
1793 The default value of @var{fontcolor} is "black".
1794
1795 @item fontfile
1796 The font file to be used for drawing text. Path must be included.
1797 This parameter is mandatory.
1798
1799 @item fontsize
1800 The font size to be used for drawing text.
1801 The default value of @var{fontsize} is 16.
1802
1803 @item ft_load_flags
1804 Flags to be used for loading the fonts.
1805
1806 The flags map the corresponding flags supported by libfreetype, and are
1807 a combination of the following values:
1808 @table @var
1809 @item default
1810 @item no_scale
1811 @item no_hinting
1812 @item render
1813 @item no_bitmap
1814 @item vertical_layout
1815 @item force_autohint
1816 @item crop_bitmap
1817 @item pedantic
1818 @item ignore_global_advance_width
1819 @item no_recurse
1820 @item ignore_transform
1821 @item monochrome
1822 @item linear_design
1823 @item no_autohint
1824 @item end table
1825 @end table
1826
1827 Default value is "render".
1828
1829 For more information consult the documentation for the FT_LOAD_*
1830 libfreetype flags.
1831
1832 @item shadowcolor
1833 The color to be used for drawing a shadow behind the drawn text.  It
1834 can be a color name (e.g. "yellow") or a string in the 0xRRGGBB[AA]
1835 form (e.g. "0xff00ff"), possibly followed by an alpha specifier.
1836 The default value of @var{shadowcolor} is "black".
1837
1838 @item shadowx, shadowy
1839 The x and y offsets for the text shadow position with respect to the
1840 position of the text. They can be either positive or negative
1841 values. Default value for both is "0".
1842
1843 @item tabsize
1844 The size in number of spaces to use for rendering the tab.
1845 Default value is 4.
1846
1847 @item timecode
1848 Set the initial timecode representation in "hh:mm:ss[:;.]ff"
1849 format. It can be used with or without text parameter. @var{timecode_rate}
1850 option must be specified.
1851
1852 @item timecode_rate, rate, r
1853 Set the timecode frame rate (timecode only).
1854
1855 @item text
1856 The text string to be drawn. The text must be a sequence of UTF-8
1857 encoded characters.
1858 This parameter is mandatory if no file is specified with the parameter
1859 @var{textfile}.
1860
1861 @item textfile
1862 A text file containing text to be drawn. The text must be a sequence
1863 of UTF-8 encoded characters.
1864
1865 This parameter is mandatory if no text string is specified with the
1866 parameter @var{text}.
1867
1868 If both @var{text} and @var{textfile} are specified, an error is thrown.
1869
1870 @item x, y
1871 The expressions which specify the offsets where text will be drawn
1872 within the video frame. They are relative to the top/left border of the
1873 output image.
1874
1875 The default value of @var{x} and @var{y} is "0".
1876
1877 See below for the list of accepted constants and functions.
1878 @end table
1879
1880 The parameters for @var{x} and @var{y} are expressions containing the
1881 following constants and functions:
1882
1883 @table @option
1884 @item dar
1885 input display aspect ratio, it is the same as (@var{w} / @var{h}) * @var{sar}
1886
1887 @item hsub, vsub
1888 horizontal and vertical chroma subsample values. For example for the
1889 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
1890
1891 @item line_h, lh
1892 the height of each text line
1893
1894 @item main_h, h, H
1895 the input height
1896
1897 @item main_w, w, W
1898 the input width
1899
1900 @item max_glyph_a, ascent
1901 the maximum distance from the baseline to the highest/upper grid
1902 coordinate used to place a glyph outline point, for all the rendered
1903 glyphs.
1904 It is a positive value, due to the grid's orientation with the Y axis
1905 upwards.
1906
1907 @item max_glyph_d, descent
1908 the maximum distance from the baseline to the lowest grid coordinate
1909 used to place a glyph outline point, for all the rendered glyphs.
1910 This is a negative value, due to the grid's orientation, with the Y axis
1911 upwards.
1912
1913 @item max_glyph_h
1914 maximum glyph height, that is the maximum height for all the glyphs
1915 contained in the rendered text, it is equivalent to @var{ascent} -
1916 @var{descent}.
1917
1918 @item max_glyph_w
1919 maximum glyph width, that is the maximum width for all the glyphs
1920 contained in the rendered text
1921
1922 @item n
1923 the number of input frame, starting from 0
1924
1925 @item rand(min, max)
1926 return a random number included between @var{min} and @var{max}
1927
1928 @item sar
1929 input sample aspect ratio
1930
1931 @item t
1932 timestamp expressed in seconds, NAN if the input timestamp is unknown
1933
1934 @item text_h, th
1935 the height of the rendered text
1936
1937 @item text_w, tw
1938 the width of the rendered text
1939
1940 @item x, y
1941 the x and y offset coordinates where the text is drawn.
1942
1943 These parameters allow the @var{x} and @var{y} expressions to refer
1944 each other, so you can for example specify @code{y=x/dar}.
1945 @end table
1946
1947 If libavfilter was built with @code{--enable-fontconfig}, then
1948 @option{fontfile} can be a fontconfig pattern or omitted.
1949
1950 Some examples follow.
1951
1952 @itemize
1953
1954 @item
1955 Draw "Test Text" with font FreeSerif, using the default values for the
1956 optional parameters.
1957
1958 @example
1959 drawtext="fontfile=/usr/share/fonts/truetype/freefont/FreeSerif.ttf: text='Test Text'"
1960 @end example
1961
1962 @item
1963 Draw 'Test Text' with font FreeSerif of size 24 at position x=100
1964 and y=50 (counting from the top-left corner of the screen), text is
1965 yellow with a red box around it. Both the text and the box have an
1966 opacity of 20%.
1967
1968 @example
1969 drawtext="fontfile=/usr/share/fonts/truetype/freefont/FreeSerif.ttf: text='Test Text':\
1970           x=100: y=50: fontsize=24: fontcolor=yellow@@0.2: box=1: boxcolor=red@@0.2"
1971 @end example
1972
1973 Note that the double quotes are not necessary if spaces are not used
1974 within the parameter list.
1975
1976 @item
1977 Show the text at the center of the video frame:
1978 @example
1979 drawtext="fontsize=30:fontfile=FreeSerif.ttf:text='hello world':x=(w-text_w)/2:y=(h-text_h-line_h)/2"
1980 @end example
1981
1982 @item
1983 Show a text line sliding from right to left in the last row of the video
1984 frame. The file @file{LONG_LINE} is assumed to contain a single line
1985 with no newlines.
1986 @example
1987 drawtext="fontsize=15:fontfile=FreeSerif.ttf:text=LONG_LINE:y=h-line_h:x=-50*t"
1988 @end example
1989
1990 @item
1991 Show the content of file @file{CREDITS} off the bottom of the frame and scroll up.
1992 @example
1993 drawtext="fontsize=20:fontfile=FreeSerif.ttf:textfile=CREDITS:y=h-20*t"
1994 @end example
1995
1996 @item
1997 Draw a single green letter "g", at the center of the input video.
1998 The glyph baseline is placed at half screen height.
1999 @example
2000 drawtext="fontsize=60:fontfile=FreeSerif.ttf:fontcolor=green:text=g:x=(w-max_glyph_w)/2:y=h/2-ascent"
2001 @end example
2002
2003 @item
2004 Show text for 1 second every 3 seconds:
2005 @example
2006 drawtext="fontfile=FreeSerif.ttf:fontcolor=white:x=100:y=x/dar:draw=lt(mod(t\\,3)\\,1):text='blink'"
2007 @end example
2008
2009 @item
2010 Use fontconfig to set the font. Note that the colons need to be escaped.
2011 @example
2012 drawtext='fontfile=Linux Libertine O-40\\:style=Semibold:text=FFmpeg'
2013 @end example
2014
2015 @end itemize
2016
2017 For more information about libfreetype, check:
2018 @url{http://www.freetype.org/}.
2019
2020 For more information about fontconfig, check:
2021 @url{http://freedesktop.org/software/fontconfig/fontconfig-user.html}.
2022
2023 @section edgedetect
2024
2025 Detect and draw edges. The filter uses the Canny Edge Detection algorithm.
2026
2027 This filter accepts the following optional named parameters:
2028
2029 @table @option
2030 @item low, high
2031 Set low and high threshold values used by the Canny thresholding
2032 algorithm.
2033
2034 The high threshold selects the "strong" edge pixels, which are then
2035 connected through 8-connectivity with the "weak" edge pixels selected
2036 by the low threshold.
2037
2038 @var{low} and @var{high} threshold values must be choosen in the range
2039 [0,1], and @var{low} should be lesser or equal to @var{high}.
2040
2041 Default value for @var{low} is @code{20/255}, and default value for @var{high}
2042 is @code{50/255}.
2043 @end table
2044
2045 Example:
2046 @example
2047 edgedetect=low=0.1:high=0.4
2048 @end example
2049
2050 @section fade
2051
2052 Apply fade-in/out effect to input video.
2053
2054 It accepts the parameters:
2055 @var{type}:@var{start_frame}:@var{nb_frames}[:@var{options}]
2056
2057 @var{type} specifies if the effect type, can be either "in" for
2058 fade-in, or "out" for a fade-out effect.
2059
2060 @var{start_frame} specifies the number of the start frame for starting
2061 to apply the fade effect.
2062
2063 @var{nb_frames} specifies the number of frames for which the fade
2064 effect has to last. At the end of the fade-in effect the output video
2065 will have the same intensity as the input video, at the end of the
2066 fade-out transition the output video will be completely black.
2067
2068 @var{options} is an optional sequence of @var{key}=@var{value} pairs,
2069 separated by ":". The description of the accepted options follows.
2070
2071 @table @option
2072
2073 @item type, t
2074 See @var{type}.
2075
2076 @item start_frame, s
2077 See @var{start_frame}.
2078
2079 @item nb_frames, n
2080 See @var{nb_frames}.
2081
2082 @item alpha
2083 If set to 1, fade only alpha channel, if one exists on the input.
2084 Default value is 0.
2085 @end table
2086
2087 A few usage examples follow, usable too as test scenarios.
2088 @example
2089 # fade in first 30 frames of video
2090 fade=in:0:30
2091
2092 # fade out last 45 frames of a 200-frame video
2093 fade=out:155:45
2094
2095 # fade in first 25 frames and fade out last 25 frames of a 1000-frame video
2096 fade=in:0:25, fade=out:975:25
2097
2098 # make first 5 frames black, then fade in from frame 5-24
2099 fade=in:5:20
2100
2101 # fade in alpha over first 25 frames of video
2102 fade=in:0:25:alpha=1
2103 @end example
2104
2105 @section fieldorder
2106
2107 Transform the field order of the input video.
2108
2109 It accepts one parameter which specifies the required field order that
2110 the input interlaced video will be transformed to. The parameter can
2111 assume one of the following values:
2112
2113 @table @option
2114 @item 0 or bff
2115 output bottom field first
2116 @item 1 or tff
2117 output top field first
2118 @end table
2119
2120 Default value is "tff".
2121
2122 Transformation is achieved by shifting the picture content up or down
2123 by one line, and filling the remaining line with appropriate picture content.
2124 This method is consistent with most broadcast field order converters.
2125
2126 If the input video is not flagged as being interlaced, or it is already
2127 flagged as being of the required output field order then this filter does
2128 not alter the incoming video.
2129
2130 This filter is very useful when converting to or from PAL DV material,
2131 which is bottom field first.
2132
2133 For example:
2134 @example
2135 ffmpeg -i in.vob -vf "fieldorder=bff" out.dv
2136 @end example
2137
2138 @section fifo
2139
2140 Buffer input images and send them when they are requested.
2141
2142 This filter is mainly useful when auto-inserted by the libavfilter
2143 framework.
2144
2145 The filter does not take parameters.
2146
2147 @section format
2148
2149 Convert the input video to one of the specified pixel formats.
2150 Libavfilter will try to pick one that is supported for the input to
2151 the next filter.
2152
2153 The filter accepts a list of pixel format names, separated by ":",
2154 for example "yuv420p:monow:rgb24".
2155
2156 Some examples follow:
2157 @example
2158 # convert the input video to the format "yuv420p"
2159 format=yuv420p
2160
2161 # convert the input video to any of the formats in the list
2162 format=yuv420p:yuv444p:yuv410p
2163 @end example
2164
2165 @section fps
2166
2167 Convert the video to specified constant framerate by duplicating or dropping
2168 frames as necessary.
2169
2170 This filter accepts the following named parameters:
2171 @table @option
2172
2173 @item fps
2174 Desired output framerate.
2175
2176 @end table
2177
2178 @section framestep
2179
2180 Select one frame every N.
2181
2182 This filter accepts in input a string representing a positive
2183 integer. Default argument is @code{1}.
2184
2185 @anchor{frei0r}
2186 @section frei0r
2187
2188 Apply a frei0r effect to the input video.
2189
2190 To enable compilation of this filter you need to install the frei0r
2191 header and configure FFmpeg with @code{--enable-frei0r}.
2192
2193 The filter supports the syntax:
2194 @example
2195 @var{filter_name}[@{:|=@}@var{param1}:@var{param2}:...:@var{paramN}]
2196 @end example
2197
2198 @var{filter_name} is the name to the frei0r effect to load. If the
2199 environment variable @env{FREI0R_PATH} is defined, the frei0r effect
2200 is searched in each one of the directories specified by the colon
2201 separated list in @env{FREIOR_PATH}, otherwise in the standard frei0r
2202 paths, which are in this order: @file{HOME/.frei0r-1/lib/},
2203 @file{/usr/local/lib/frei0r-1/}, @file{/usr/lib/frei0r-1/}.
2204
2205 @var{param1}, @var{param2}, ... , @var{paramN} specify the parameters
2206 for the frei0r effect.
2207
2208 A frei0r effect parameter can be a boolean (whose values are specified
2209 with "y" and "n"), a double, a color (specified by the syntax
2210 @var{R}/@var{G}/@var{B}, @var{R}, @var{G}, and @var{B} being float
2211 numbers from 0.0 to 1.0) or by an @code{av_parse_color()} color
2212 description), a position (specified by the syntax @var{X}/@var{Y},
2213 @var{X} and @var{Y} being float numbers) and a string.
2214
2215 The number and kind of parameters depend on the loaded effect. If an
2216 effect parameter is not specified the default value is set.
2217
2218 Some examples follow:
2219
2220 @itemize
2221 @item
2222 Apply the distort0r effect, set the first two double parameters:
2223 @example
2224 frei0r=distort0r:0.5:0.01
2225 @end example
2226
2227 @item
2228 Apply the colordistance effect, takes a color as first parameter:
2229 @example
2230 frei0r=colordistance:0.2/0.3/0.4
2231 frei0r=colordistance:violet
2232 frei0r=colordistance:0x112233
2233 @end example
2234
2235 @item
2236 Apply the perspective effect, specify the top left and top right image
2237 positions:
2238 @example
2239 frei0r=perspective:0.2/0.2:0.8/0.2
2240 @end example
2241 @end itemize
2242
2243 For more information see:
2244 @url{http://frei0r.dyne.org}
2245
2246 @section gradfun
2247
2248 Fix the banding artifacts that are sometimes introduced into nearly flat
2249 regions by truncation to 8bit color depth.
2250 Interpolate the gradients that should go where the bands are, and
2251 dither them.
2252
2253 This filter is designed for playback only.  Do not use it prior to
2254 lossy compression, because compression tends to lose the dither and
2255 bring back the bands.
2256
2257 The filter takes two optional parameters, separated by ':':
2258 @var{strength}:@var{radius}
2259
2260 @var{strength} is the maximum amount by which the filter will change
2261 any one pixel. Also the threshold for detecting nearly flat
2262 regions. Acceptable values range from .51 to 255, default value is
2263 1.2, out-of-range values will be clipped to the valid range.
2264
2265 @var{radius} is the neighborhood to fit the gradient to. A larger
2266 radius makes for smoother gradients, but also prevents the filter from
2267 modifying the pixels near detailed regions. Acceptable values are
2268 8-32, default value is 16, out-of-range values will be clipped to the
2269 valid range.
2270
2271 @example
2272 # default parameters
2273 gradfun=1.2:16
2274
2275 # omitting radius
2276 gradfun=1.2
2277 @end example
2278
2279 @section hflip
2280
2281 Flip the input video horizontally.
2282
2283 For example to horizontally flip the input video with @command{ffmpeg}:
2284 @example
2285 ffmpeg -i in.avi -vf "hflip" out.avi
2286 @end example
2287
2288 @section hqdn3d
2289
2290 High precision/quality 3d denoise filter. This filter aims to reduce
2291 image noise producing smooth images and making still images really
2292 still. It should enhance compressibility.
2293
2294 It accepts the following optional parameters:
2295 @var{luma_spatial}:@var{chroma_spatial}:@var{luma_tmp}:@var{chroma_tmp}
2296
2297 @table @option
2298 @item luma_spatial
2299 a non-negative float number which specifies spatial luma strength,
2300 defaults to 4.0
2301
2302 @item chroma_spatial
2303 a non-negative float number which specifies spatial chroma strength,
2304 defaults to 3.0*@var{luma_spatial}/4.0
2305
2306 @item luma_tmp
2307 a float number which specifies luma temporal strength, defaults to
2308 6.0*@var{luma_spatial}/4.0
2309
2310 @item chroma_tmp
2311 a float number which specifies chroma temporal strength, defaults to
2312 @var{luma_tmp}*@var{chroma_spatial}/@var{luma_spatial}
2313 @end table
2314
2315 @section hue
2316
2317 Modify the hue and/or the saturation of the input.
2318
2319 This filter accepts the following optional named options:
2320
2321 @table @option
2322 @item h
2323 Specify the hue angle as a number of degrees. It accepts a float
2324 number or an expression, and defaults to 0.0.
2325
2326 @item H
2327 Specify the hue angle as a number of degrees. It accepts a float
2328 number or an expression, and defaults to 0.0.
2329
2330 @item s
2331 Specify the saturation in the [-10,10] range. It accepts a float number and
2332 defaults to 1.0.
2333 @end table
2334
2335 The @var{h}, @var{H} and @var{s} parameters are expressions containing the
2336 following constants:
2337
2338 @table @option
2339 @item n
2340 frame count of the input frame starting from 0
2341
2342 @item pts
2343 presentation timestamp of the input frame expressed in time base units
2344
2345 @item r
2346 frame rate of the input video, NAN if the input frame rate is unknown
2347
2348 @item t
2349 timestamp expressed in seconds, NAN if the input timestamp is unknown
2350
2351 @item tb
2352 time base of the input video
2353 @end table
2354
2355 The options can also be set using the syntax: @var{hue}:@var{saturation}
2356
2357 In this case @var{hue} is expressed in degrees.
2358
2359 Some examples follow:
2360 @itemize
2361 @item
2362 Set the hue to 90 degrees and the saturation to 1.0:
2363 @example
2364 hue=h=90:s=1
2365 @end example
2366
2367 @item
2368 Same command but expressing the hue in radians:
2369 @example
2370 hue=H=PI/2:s=1
2371 @end example
2372
2373 @item
2374 Same command without named options, hue must be expressed in degrees:
2375 @example
2376 hue=90:1
2377 @end example
2378
2379 @item
2380 Note that "h:s" syntax does not support expressions for the values of
2381 h and s, so the following example will issue an error:
2382 @example
2383 hue=PI/2:1
2384 @end example
2385
2386 @item
2387 Rotate hue and make the saturation swing between 0
2388 and 2 over a period of 1 second:
2389 @example
2390 hue="H=2*PI*t: s=sin(2*PI*t)+1"
2391 @end example
2392
2393 @item
2394 Apply a 3 seconds saturation fade-in effect starting at 0:
2395 @example
2396 hue="s=min(t/3\,1)"
2397 @end example
2398
2399 The general fade-in expression can be written as:
2400 @example
2401 hue="s=min(0\, max((t-START)/DURATION\, 1))"
2402 @end example
2403
2404 @item
2405 Apply a 3 seconds saturation fade-out effect starting at 5 seconds:
2406 @example
2407 hue="s=max(0\, min(1\, (8-t)/3))"
2408 @end example
2409
2410 The general fade-out expression can be written as:
2411 @example
2412 hue="s=max(0\, min(1\, (START+DURATION-t)/DURATION))"
2413 @end example
2414
2415 @end itemize
2416
2417 @subsection Commands
2418
2419 This filter supports the following command:
2420 @table @option
2421 @item reinit
2422 Modify the hue and/or the saturation of the input video.
2423 The command accepts the same named options and syntax than when calling the
2424 filter from the command-line.
2425
2426 If a parameter is omitted, it is kept at its current value.
2427 @end table
2428
2429 @section idet
2430
2431 Interlaceing detect filter. This filter tries to detect if the input is
2432 interlaced or progressive. Top or bottom field first.
2433
2434 @section lut, lutrgb, lutyuv
2435
2436 Compute a look-up table for binding each pixel component input value
2437 to an output value, and apply it to input video.
2438
2439 @var{lutyuv} applies a lookup table to a YUV input video, @var{lutrgb}
2440 to an RGB input video.
2441
2442 These filters accept in input a ":"-separated list of options, which
2443 specify the expressions used for computing the lookup table for the
2444 corresponding pixel component values.
2445
2446 The @var{lut} filter requires either YUV or RGB pixel formats in
2447 input, and accepts the options:
2448 @table @option
2449 @item c0
2450 first  pixel component
2451 @item c1
2452 second pixel component
2453 @item c2
2454 third  pixel component
2455 @item c3
2456 fourth pixel component, corresponds to the alpha component
2457 @end table
2458
2459 The exact component associated to each option depends on the format in
2460 input.
2461
2462 The @var{lutrgb} filter requires RGB pixel formats in input, and
2463 accepts the options:
2464 @table @option
2465 @item r
2466 red component
2467 @item g
2468 green component
2469 @item b
2470 blue component
2471 @item a
2472 alpha component
2473 @end table
2474
2475 The @var{lutyuv} filter requires YUV pixel formats in input, and
2476 accepts the options:
2477 @table @option
2478 @item y
2479 Y/luminance component
2480 @item u
2481 U/Cb component
2482 @item v
2483 V/Cr component
2484 @item a
2485 alpha component
2486 @end table
2487
2488 The expressions can contain the following constants and functions:
2489
2490 @table @option
2491 @item w, h
2492 the input width and height
2493
2494 @item val
2495 input value for the pixel component
2496
2497 @item clipval
2498 the input value clipped in the @var{minval}-@var{maxval} range
2499
2500 @item maxval
2501 maximum value for the pixel component
2502
2503 @item minval
2504 minimum value for the pixel component
2505
2506 @item negval
2507 the negated value for the pixel component value clipped in the
2508 @var{minval}-@var{maxval} range , it corresponds to the expression
2509 "maxval-clipval+minval"
2510
2511 @item clip(val)
2512 the computed value in @var{val} clipped in the
2513 @var{minval}-@var{maxval} range
2514
2515 @item gammaval(gamma)
2516 the computed gamma correction value of the pixel component value
2517 clipped in the @var{minval}-@var{maxval} range, corresponds to the
2518 expression
2519 "pow((clipval-minval)/(maxval-minval)\,@var{gamma})*(maxval-minval)+minval"
2520
2521 @end table
2522
2523 All expressions default to "val".
2524
2525 Some examples follow:
2526 @example
2527 # negate input video
2528 lutrgb="r=maxval+minval-val:g=maxval+minval-val:b=maxval+minval-val"
2529 lutyuv="y=maxval+minval-val:u=maxval+minval-val:v=maxval+minval-val"
2530
2531 # the above is the same as
2532 lutrgb="r=negval:g=negval:b=negval"
2533 lutyuv="y=negval:u=negval:v=negval"
2534
2535 # negate luminance
2536 lutyuv=y=negval
2537
2538 # remove chroma components, turns the video into a graytone image
2539 lutyuv="u=128:v=128"
2540
2541 # apply a luma burning effect
2542 lutyuv="y=2*val"
2543
2544 # remove green and blue components
2545 lutrgb="g=0:b=0"
2546
2547 # set a constant alpha channel value on input
2548 format=rgba,lutrgb=a="maxval-minval/2"
2549
2550 # correct luminance gamma by a 0.5 factor
2551 lutyuv=y=gammaval(0.5)
2552 @end example
2553
2554 @section mp
2555
2556 Apply an MPlayer filter to the input video.
2557
2558 This filter provides a wrapper around most of the filters of
2559 MPlayer/MEncoder.
2560
2561 This wrapper is considered experimental. Some of the wrapped filters
2562 may not work properly and we may drop support for them, as they will
2563 be implemented natively into FFmpeg. Thus you should avoid
2564 depending on them when writing portable scripts.
2565
2566 The filters accepts the parameters:
2567 @var{filter_name}[:=]@var{filter_params}
2568
2569 @var{filter_name} is the name of a supported MPlayer filter,
2570 @var{filter_params} is a string containing the parameters accepted by
2571 the named filter.
2572
2573 The list of the currently supported filters follows:
2574 @table @var
2575 @item denoise3d
2576 @item detc
2577 @item dint
2578 @item divtc
2579 @item down3dright
2580 @item dsize
2581 @item eq2
2582 @item eq
2583 @item field
2584 @item fil
2585 @item fixpts
2586 @item fspp
2587 @item geq
2588 @item harddup
2589 @item hqdn3d
2590 @item il
2591 @item ilpack
2592 @item ivtc
2593 @item kerndeint
2594 @item mcdeint
2595 @item noise
2596 @item ow
2597 @item palette
2598 @item perspective
2599 @item phase
2600 @item pp7
2601 @item pullup
2602 @item qp
2603 @item rectangle
2604 @item sab
2605 @item softpulldown
2606 @item softskip
2607 @item spp
2608 @item telecine
2609 @item tile
2610 @item tinterlace
2611 @item unsharp
2612 @item uspp
2613 @item yuvcsp
2614 @item yvu9
2615 @end table
2616
2617 The parameter syntax and behavior for the listed filters are the same
2618 of the corresponding MPlayer filters. For detailed instructions check
2619 the "VIDEO FILTERS" section in the MPlayer manual.
2620
2621 Some examples follow:
2622 @itemize
2623 @item
2624 Adjust gamma, brightness, contrast:
2625 @example
2626 mp=eq2=1.0:2:0.5
2627 @end example
2628
2629 @item
2630 Add temporal noise to input video:
2631 @example
2632 mp=noise=20t
2633 @end example
2634 @end itemize
2635
2636 See also mplayer(1), @url{http://www.mplayerhq.hu/}.
2637
2638 @section negate
2639
2640 Negate input video.
2641
2642 This filter accepts an integer in input, if non-zero it negates the
2643 alpha component (if available). The default value in input is 0.
2644
2645 @section noformat
2646
2647 Force libavfilter not to use any of the specified pixel formats for the
2648 input to the next filter.
2649
2650 The filter accepts a list of pixel format names, separated by ":",
2651 for example "yuv420p:monow:rgb24".
2652
2653 Some examples follow:
2654 @example
2655 # force libavfilter to use a format different from "yuv420p" for the
2656 # input to the vflip filter
2657 noformat=yuv420p,vflip
2658
2659 # convert the input video to any of the formats not contained in the list
2660 noformat=yuv420p:yuv444p:yuv410p
2661 @end example
2662
2663 @section null
2664
2665 Pass the video source unchanged to the output.
2666
2667 @section ocv
2668
2669 Apply video transform using libopencv.
2670
2671 To enable this filter install libopencv library and headers and
2672 configure FFmpeg with @code{--enable-libopencv}.
2673
2674 The filter takes the parameters: @var{filter_name}@{:=@}@var{filter_params}.
2675
2676 @var{filter_name} is the name of the libopencv filter to apply.
2677
2678 @var{filter_params} specifies the parameters to pass to the libopencv
2679 filter. If not specified the default values are assumed.
2680
2681 Refer to the official libopencv documentation for more precise
2682 information:
2683 @url{http://opencv.willowgarage.com/documentation/c/image_filtering.html}
2684
2685 Follows the list of supported libopencv filters.
2686
2687 @anchor{dilate}
2688 @subsection dilate
2689
2690 Dilate an image by using a specific structuring element.
2691 This filter corresponds to the libopencv function @code{cvDilate}.
2692
2693 It accepts the parameters: @var{struct_el}:@var{nb_iterations}.
2694
2695 @var{struct_el} represents a structuring element, and has the syntax:
2696 @var{cols}x@var{rows}+@var{anchor_x}x@var{anchor_y}/@var{shape}
2697
2698 @var{cols} and @var{rows} represent the number of columns and rows of
2699 the structuring element, @var{anchor_x} and @var{anchor_y} the anchor
2700 point, and @var{shape} the shape for the structuring element, and
2701 can be one of the values "rect", "cross", "ellipse", "custom".
2702
2703 If the value for @var{shape} is "custom", it must be followed by a
2704 string of the form "=@var{filename}". The file with name
2705 @var{filename} is assumed to represent a binary image, with each
2706 printable character corresponding to a bright pixel. When a custom
2707 @var{shape} is used, @var{cols} and @var{rows} are ignored, the number
2708 or columns and rows of the read file are assumed instead.
2709
2710 The default value for @var{struct_el} is "3x3+0x0/rect".
2711
2712 @var{nb_iterations} specifies the number of times the transform is
2713 applied to the image, and defaults to 1.
2714
2715 Follow some example:
2716 @example
2717 # use the default values
2718 ocv=dilate
2719
2720 # dilate using a structuring element with a 5x5 cross, iterate two times
2721 ocv=dilate=5x5+2x2/cross:2
2722
2723 # read the shape from the file diamond.shape, iterate two times
2724 # the file diamond.shape may contain a pattern of characters like this:
2725 #   *
2726 #  ***
2727 # *****
2728 #  ***
2729 #   *
2730 # the specified cols and rows are ignored (but not the anchor point coordinates)
2731 ocv=0x0+2x2/custom=diamond.shape:2
2732 @end example
2733
2734 @subsection erode
2735
2736 Erode an image by using a specific structuring element.
2737 This filter corresponds to the libopencv function @code{cvErode}.
2738
2739 The filter accepts the parameters: @var{struct_el}:@var{nb_iterations},
2740 with the same syntax and semantics as the @ref{dilate} filter.
2741
2742 @subsection smooth
2743
2744 Smooth the input video.
2745
2746 The filter takes the following parameters:
2747 @var{type}:@var{param1}:@var{param2}:@var{param3}:@var{param4}.
2748
2749 @var{type} is the type of smooth filter to apply, and can be one of
2750 the following values: "blur", "blur_no_scale", "median", "gaussian",
2751 "bilateral". The default value is "gaussian".
2752
2753 @var{param1}, @var{param2}, @var{param3}, and @var{param4} are
2754 parameters whose meanings depend on smooth type. @var{param1} and
2755 @var{param2} accept integer positive values or 0, @var{param3} and
2756 @var{param4} accept float values.
2757
2758 The default value for @var{param1} is 3, the default value for the
2759 other parameters is 0.
2760
2761 These parameters correspond to the parameters assigned to the
2762 libopencv function @code{cvSmooth}.
2763
2764 @anchor{overlay}
2765 @section overlay
2766
2767 Overlay one video on top of another.
2768
2769 It takes two inputs and one output, the first input is the "main"
2770 video on which the second input is overlayed.
2771
2772 It accepts the parameters: @var{x}:@var{y}[:@var{options}].
2773
2774 @var{x} is the x coordinate of the overlayed video on the main video,
2775 @var{y} is the y coordinate. @var{x} and @var{y} are expressions containing
2776 the following parameters:
2777
2778 @table @option
2779 @item main_w, main_h
2780 main input width and height
2781
2782 @item W, H
2783 same as @var{main_w} and @var{main_h}
2784
2785 @item overlay_w, overlay_h
2786 overlay input width and height
2787
2788 @item w, h
2789 same as @var{overlay_w} and @var{overlay_h}
2790 @end table
2791
2792 @var{options} is an optional list of @var{key}=@var{value} pairs,
2793 separated by ":".
2794
2795 The description of the accepted options follows.
2796
2797 @table @option
2798 @item rgb
2799 If set to 1, force the filter to accept inputs in the RGB
2800 color space. Default value is 0.
2801 @end table
2802
2803 Be aware that frames are taken from each input video in timestamp
2804 order, hence, if their initial timestamps differ, it is a a good idea
2805 to pass the two inputs through a @var{setpts=PTS-STARTPTS} filter to
2806 have them begin in the same zero timestamp, as it does the example for
2807 the @var{movie} filter.
2808
2809 Follow some examples:
2810 @example
2811 # draw the overlay at 10 pixels from the bottom right
2812 # corner of the main video.
2813 overlay=main_w-overlay_w-10:main_h-overlay_h-10
2814
2815 # insert a transparent PNG logo in the bottom left corner of the input
2816 ffmpeg -i input -i logo -filter_complex 'overlay=10:main_h-overlay_h-10' output
2817
2818 # insert 2 different transparent PNG logos (second logo on bottom
2819 # right corner):
2820 ffmpeg -i input -i logo1 -i logo2 -filter_complex
2821 'overlay=10:H-h-10,overlay=W-w-10:H-h-10' output
2822
2823 # add a transparent color layer on top of the main video,
2824 # WxH specifies the size of the main input to the overlay filter
2825 color=red@.3:WxH [over]; [in][over] overlay [out]
2826
2827 # play an original video and a filtered version (here with the deshake filter)
2828 # side by side
2829 ffplay input.avi -vf 'split[a][b]; [a]pad=iw*2:ih[src]; [b]deshake[filt]; [src][filt]overlay=w'
2830
2831 # the previous example is the same as:
2832 ffplay input.avi -vf 'split[b], pad=iw*2[src], [b]deshake, [src]overlay=w'
2833 @end example
2834
2835 You can chain together more overlays but the efficiency of such
2836 approach is yet to be tested.
2837
2838 @section pad
2839
2840 Add paddings to the input image, and places the original input at the
2841 given coordinates @var{x}, @var{y}.
2842
2843 It accepts the following parameters:
2844 @var{width}:@var{height}:@var{x}:@var{y}:@var{color}.
2845
2846 The parameters @var{width}, @var{height}, @var{x}, and @var{y} are
2847 expressions containing the following constants:
2848
2849 @table @option
2850 @item in_w, in_h
2851 the input video width and height
2852
2853 @item iw, ih
2854 same as @var{in_w} and @var{in_h}
2855
2856 @item out_w, out_h
2857 the output width and height, that is the size of the padded area as
2858 specified by the @var{width} and @var{height} expressions
2859
2860 @item ow, oh
2861 same as @var{out_w} and @var{out_h}
2862
2863 @item x, y
2864 x and y offsets as specified by the @var{x} and @var{y}
2865 expressions, or NAN if not yet specified
2866
2867 @item a
2868 same as @var{iw} / @var{ih}
2869
2870 @item sar
2871 input sample aspect ratio
2872
2873 @item dar
2874 input display aspect ratio, it is the same as (@var{iw} / @var{ih}) * @var{sar}
2875
2876 @item hsub, vsub
2877 horizontal and vertical chroma subsample values. For example for the
2878 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
2879 @end table
2880
2881 Follows the description of the accepted parameters.
2882
2883 @table @option
2884 @item width, height
2885
2886 Specify the size of the output image with the paddings added. If the
2887 value for @var{width} or @var{height} is 0, the corresponding input size
2888 is used for the output.
2889
2890 The @var{width} expression can reference the value set by the
2891 @var{height} expression, and vice versa.
2892
2893 The default value of @var{width} and @var{height} is 0.
2894
2895 @item x, y
2896
2897 Specify the offsets where to place the input image in the padded area
2898 with respect to the top/left border of the output image.
2899
2900 The @var{x} expression can reference the value set by the @var{y}
2901 expression, and vice versa.
2902
2903 The default value of @var{x} and @var{y} is 0.
2904
2905 @item color
2906
2907 Specify the color of the padded area, it can be the name of a color
2908 (case insensitive match) or a 0xRRGGBB[AA] sequence.
2909
2910 The default value of @var{color} is "black".
2911
2912 @end table
2913
2914 @section Examples
2915
2916 @itemize
2917 @item
2918 Add paddings with color "violet" to the input video. Output video
2919 size is 640x480, the top-left corner of the input video is placed at
2920 column 0, row 40:
2921 @example
2922 pad=640:480:0:40:violet
2923 @end example
2924
2925 @item
2926 Pad the input to get an output with dimensions increased by 3/2,
2927 and put the input video at the center of the padded area:
2928 @example
2929 pad="3/2*iw:3/2*ih:(ow-iw)/2:(oh-ih)/2"
2930 @end example
2931
2932 @item
2933 Pad the input to get a squared output with size equal to the maximum
2934 value between the input width and height, and put the input video at
2935 the center of the padded area:
2936 @example
2937 pad="max(iw\,ih):ow:(ow-iw)/2:(oh-ih)/2"
2938 @end example
2939
2940 @item
2941 Pad the input to get a final w/h ratio of 16:9:
2942 @example
2943 pad="ih*16/9:ih:(ow-iw)/2:(oh-ih)/2"
2944 @end example
2945
2946 @item
2947 In case of anamorphic video, in order to set the output display aspect
2948 correctly, it is necessary to use @var{sar} in the expression,
2949 according to the relation:
2950 @example
2951 (ih * X / ih) * sar = output_dar
2952 X = output_dar / sar
2953 @end example
2954
2955 Thus the previous example needs to be modified to:
2956 @example
2957 pad="ih*16/9/sar:ih:(ow-iw)/2:(oh-ih)/2"
2958 @end example
2959
2960 @item
2961 Double output size and put the input video in the bottom-right
2962 corner of the output padded area:
2963 @example
2964 pad="2*iw:2*ih:ow-iw:oh-ih"
2965 @end example
2966 @end itemize
2967
2968 @section pixdesctest
2969
2970 Pixel format descriptor test filter, mainly useful for internal
2971 testing. The output video should be equal to the input video.
2972
2973 For example:
2974 @example
2975 format=monow, pixdesctest
2976 @end example
2977
2978 can be used to test the monowhite pixel format descriptor definition.
2979
2980 @section removelogo
2981
2982 Suppress a TV station logo, using an image file to determine which
2983 pixels comprise the logo. It works by filling in the pixels that
2984 comprise the logo with neighboring pixels.
2985
2986 This filter requires one argument which specifies the filter bitmap
2987 file, which can be any image format supported by libavformat. The
2988 width and height of the image file must match those of the video
2989 stream being processed.
2990
2991 Pixels in the provided bitmap image with a value of zero are not
2992 considered part of the logo, non-zero pixels are considered part of
2993 the logo. If you use white (255) for the logo and black (0) for the
2994 rest, you will be safe. For making the filter bitmap, it is
2995 recommended to take a screen capture of a black frame with the logo
2996 visible, and then using a threshold filter followed by the erode
2997 filter once or twice.
2998
2999 If needed, little splotches can be fixed manually. Remember that if
3000 logo pixels are not covered, the filter quality will be much
3001 reduced. Marking too many pixels as part of the logo does not hurt as
3002 much, but it will increase the amount of blurring needed to cover over
3003 the image and will destroy more information than necessary, and extra
3004 pixels will slow things down on a large logo.
3005
3006 @section scale
3007
3008 Scale the input video to @var{width}:@var{height}[:@var{interl}=@{1|-1@}] and/or convert the image format.
3009
3010 The scale filter forces the output display aspect ratio to be the same
3011 of the input, by changing the output sample aspect ratio.
3012
3013 The parameters @var{width} and @var{height} are expressions containing
3014 the following constants:
3015
3016 @table @option
3017 @item in_w, in_h
3018 the input width and height
3019
3020 @item iw, ih
3021 same as @var{in_w} and @var{in_h}
3022
3023 @item out_w, out_h
3024 the output (cropped) width and height
3025
3026 @item ow, oh
3027 same as @var{out_w} and @var{out_h}
3028
3029 @item a
3030 same as @var{iw} / @var{ih}
3031
3032 @item sar
3033 input sample aspect ratio
3034
3035 @item dar
3036 input display aspect ratio, it is the same as (@var{iw} / @var{ih}) * @var{sar}
3037
3038 @item hsub, vsub
3039 horizontal and vertical chroma subsample values. For example for the
3040 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
3041 @end table
3042
3043 If the input image format is different from the format requested by
3044 the next filter, the scale filter will convert the input to the
3045 requested format.
3046
3047 If the value for @var{width} or @var{height} is 0, the respective input
3048 size is used for the output.
3049
3050 If the value for @var{width} or @var{height} is -1, the scale filter will
3051 use, for the respective output size, a value that maintains the aspect
3052 ratio of the input image.
3053
3054 The default value of @var{width} and @var{height} is 0.
3055
3056 Valid values for the optional parameter @var{interl} are:
3057
3058 @table @option
3059 @item 1
3060 force interlaced aware scaling
3061
3062 @item -1
3063 select interlaced aware scaling depending on whether the source frames
3064 are flagged as interlaced or not
3065 @end table
3066
3067 Unless @var{interl} is set to one of the above options, interlaced scaling will not be used.
3068
3069 Some examples follow:
3070 @example
3071 # scale the input video to a size of 200x100.
3072 scale=200:100
3073
3074 # scale the input to 2x
3075 scale=2*iw:2*ih
3076 # the above is the same as
3077 scale=2*in_w:2*in_h
3078
3079 # scale the input to 2x with forced interlaced scaling
3080 scale=2*iw:2*ih:interl=1
3081
3082 # scale the input to half size
3083 scale=iw/2:ih/2
3084
3085 # increase the width, and set the height to the same size
3086 scale=3/2*iw:ow
3087
3088 # seek for Greek harmony
3089 scale=iw:1/PHI*iw
3090 scale=ih*PHI:ih
3091
3092 # increase the height, and set the width to 3/2 of the height
3093 scale=3/2*oh:3/5*ih
3094
3095 # increase the size, but make the size a multiple of the chroma
3096 scale="trunc(3/2*iw/hsub)*hsub:trunc(3/2*ih/vsub)*vsub"
3097
3098 # increase the width to a maximum of 500 pixels, keep the same input aspect ratio
3099 scale='min(500\, iw*3/2):-1'
3100 @end example
3101
3102 @section select
3103 Select frames to pass in output.
3104
3105 It accepts in input an expression, which is evaluated for each input
3106 frame. If the expression is evaluated to a non-zero value, the frame
3107 is selected and passed to the output, otherwise it is discarded.
3108
3109 The expression can contain the following constants:
3110
3111 @table @option
3112 @item n
3113 the sequential number of the filtered frame, starting from 0
3114
3115 @item selected_n
3116 the sequential number of the selected frame, starting from 0
3117
3118 @item prev_selected_n
3119 the sequential number of the last selected frame, NAN if undefined
3120
3121 @item TB
3122 timebase of the input timestamps
3123
3124 @item pts
3125 the PTS (Presentation TimeStamp) of the filtered video frame,
3126 expressed in @var{TB} units, NAN if undefined
3127
3128 @item t
3129 the PTS (Presentation TimeStamp) of the filtered video frame,
3130 expressed in seconds, NAN if undefined
3131
3132 @item prev_pts
3133 the PTS of the previously filtered video frame, NAN if undefined
3134
3135 @item prev_selected_pts
3136 the PTS of the last previously filtered video frame, NAN if undefined
3137
3138 @item prev_selected_t
3139 the PTS of the last previously selected video frame, NAN if undefined
3140
3141 @item start_pts
3142 the PTS of the first video frame in the video, NAN if undefined
3143
3144 @item start_t
3145 the time of the first video frame in the video, NAN if undefined
3146
3147 @item pict_type
3148 the type of the filtered frame, can assume one of the following
3149 values:
3150 @table @option
3151 @item I
3152 @item P
3153 @item B
3154 @item S
3155 @item SI
3156 @item SP
3157 @item BI
3158 @end table
3159
3160 @item interlace_type
3161 the frame interlace type, can assume one of the following values:
3162 @table @option
3163 @item PROGRESSIVE
3164 the frame is progressive (not interlaced)
3165 @item TOPFIRST
3166 the frame is top-field-first
3167 @item BOTTOMFIRST
3168 the frame is bottom-field-first
3169 @end table
3170
3171 @item key
3172 1 if the filtered frame is a key-frame, 0 otherwise
3173
3174 @item pos
3175 the position in the file of the filtered frame, -1 if the information
3176 is not available (e.g. for synthetic video)
3177
3178 @item scene
3179 value between 0 and 1 to indicate a new scene; a low value reflects a low
3180 probability for the current frame to introduce a new scene, while a higher
3181 value means the current frame is more likely to be one (see the example below)
3182
3183 @end table
3184
3185 The default value of the select expression is "1".
3186
3187 Some examples follow:
3188
3189 @example
3190 # select all frames in input
3191 select
3192
3193 # the above is the same as:
3194 select=1
3195
3196 # skip all frames:
3197 select=0
3198
3199 # select only I-frames
3200 select='eq(pict_type\,I)'
3201
3202 # select one frame every 100
3203 select='not(mod(n\,100))'
3204
3205 # select only frames contained in the 10-20 time interval
3206 select='gte(t\,10)*lte(t\,20)'
3207
3208 # select only I frames contained in the 10-20 time interval
3209 select='gte(t\,10)*lte(t\,20)*eq(pict_type\,I)'
3210
3211 # select frames with a minimum distance of 10 seconds
3212 select='isnan(prev_selected_t)+gte(t-prev_selected_t\,10)'
3213 @end example
3214
3215 Complete example to create a mosaic of the first scenes:
3216
3217 @example
3218 ffmpeg -i video.avi -vf select='gt(scene\,0.4)',scale=160:120,tile -frames:v 1 preview.png
3219 @end example
3220
3221 Comparing @var{scene} against a value between 0.3 and 0.5 is generally a sane
3222 choice.
3223
3224 @section setdar, setsar
3225
3226 The @code{setdar} filter sets the Display Aspect Ratio for the filter
3227 output video.
3228
3229 This is done by changing the specified Sample (aka Pixel) Aspect
3230 Ratio, according to the following equation:
3231 @example
3232 @var{DAR} = @var{HORIZONTAL_RESOLUTION} / @var{VERTICAL_RESOLUTION} * @var{SAR}
3233 @end example
3234
3235 Keep in mind that the @code{setdar} filter does not modify the pixel
3236 dimensions of the video frame. Also the display aspect ratio set by
3237 this filter may be changed by later filters in the filterchain,
3238 e.g. in case of scaling or if another "setdar" or a "setsar" filter is
3239 applied.
3240
3241 The @code{setsar} filter sets the Sample (aka Pixel) Aspect Ratio for
3242 the filter output video.
3243
3244 Note that as a consequence of the application of this filter, the
3245 output display aspect ratio will change according to the equation
3246 above.
3247
3248 Keep in mind that the sample aspect ratio set by the @code{setsar}
3249 filter may be changed by later filters in the filterchain, e.g. if
3250 another "setsar" or a "setdar" filter is applied.
3251
3252 The @code{setdar} and @code{setsar} filters accept a parameter string
3253 which represents the wanted aspect ratio.  The parameter can
3254 be a floating point number string, an expression, or a string of the form
3255 @var{num}:@var{den}, where @var{num} and @var{den} are the numerator
3256 and denominator of the aspect ratio. If the parameter is not
3257 specified, it is assumed the value "0:1".
3258
3259 For example to change the display aspect ratio to 16:9, specify:
3260 @example
3261 setdar=16:9
3262 @end example
3263
3264 The example above is equivalent to:
3265 @example
3266 setdar=1.77777
3267 @end example
3268
3269 To change the sample aspect ratio to 10:11, specify:
3270 @example
3271 setsar=10:11
3272 @end example
3273
3274 @section setfield
3275
3276 Force field for the output video frame.
3277
3278 The @code{setfield} filter marks the interlace type field for the
3279 output frames. It does not change the input frame, but only sets the
3280 corresponding property, which affects how the frame is treated by
3281 following filters (e.g. @code{fieldorder} or @code{yadif}).
3282
3283 It accepts a string parameter, which can assume the following values:
3284 @table @samp
3285 @item auto
3286 Keep the same field property.
3287
3288 @item bff
3289 Mark the frame as bottom-field-first.
3290
3291 @item tff
3292 Mark the frame as top-field-first.
3293
3294 @item prog
3295 Mark the frame as progressive.
3296 @end table
3297
3298 @section showinfo
3299
3300 Show a line containing various information for each input video frame.
3301 The input video is not modified.
3302
3303 The shown line contains a sequence of key/value pairs of the form
3304 @var{key}:@var{value}.
3305
3306 A description of each shown parameter follows:
3307
3308 @table @option
3309 @item n
3310 sequential number of the input frame, starting from 0
3311
3312 @item pts
3313 Presentation TimeStamp of the input frame, expressed as a number of
3314 time base units. The time base unit depends on the filter input pad.
3315
3316 @item pts_time
3317 Presentation TimeStamp of the input frame, expressed as a number of
3318 seconds
3319
3320 @item pos
3321 position of the frame in the input stream, -1 if this information in
3322 unavailable and/or meaningless (for example in case of synthetic video)
3323
3324 @item fmt
3325 pixel format name
3326
3327 @item sar
3328 sample aspect ratio of the input frame, expressed in the form
3329 @var{num}/@var{den}
3330
3331 @item s
3332 size of the input frame, expressed in the form
3333 @var{width}x@var{height}
3334
3335 @item i
3336 interlaced mode ("P" for "progressive", "T" for top field first, "B"
3337 for bottom field first)
3338
3339 @item iskey
3340 1 if the frame is a key frame, 0 otherwise
3341
3342 @item type
3343 picture type of the input frame ("I" for an I-frame, "P" for a
3344 P-frame, "B" for a B-frame, "?" for unknown type).
3345 Check also the documentation of the @code{AVPictureType} enum and of
3346 the @code{av_get_picture_type_char} function defined in
3347 @file{libavutil/avutil.h}.
3348
3349 @item checksum
3350 Adler-32 checksum (printed in hexadecimal) of all the planes of the input frame
3351
3352 @item plane_checksum
3353 Adler-32 checksum (printed in hexadecimal) of each plane of the input frame,
3354 expressed in the form "[@var{c0} @var{c1} @var{c2} @var{c3}]"
3355 @end table
3356
3357 @section slicify
3358
3359 Pass the images of input video on to next video filter as multiple
3360 slices.
3361
3362 @example
3363 ffmpeg -i in.avi -vf "slicify=32" out.avi
3364 @end example
3365
3366 The filter accepts the slice height as parameter. If the parameter is
3367 not specified it will use the default value of 16.
3368
3369 Adding this in the beginning of filter chains should make filtering
3370 faster due to better use of the memory cache.
3371
3372 @section smartblur
3373
3374 Blur the input video without impacting the outlines.
3375
3376 The filter accepts the following parameters:
3377 @var{luma_radius}:@var{luma_strength}:@var{luma_threshold}[:@var{chroma_radius}:@var{chroma_strength}:@var{chroma_threshold}]
3378
3379 Parameters prefixed by @var{luma} indicate that they work on the
3380 luminance of the pixels whereas parameters prefixed by @var{chroma}
3381 refer to the chrominance of the pixels.
3382
3383 If the chroma parameters are not set, the luma parameters are used for
3384 either the luminance and the chrominance of the pixels.
3385
3386 @var{luma_radius} or @var{chroma_radius} must be a float number in the
3387 range [0.1,5.0] that specifies the variance of the gaussian filter
3388 used to blur the image (slower if larger).
3389
3390 @var{luma_strength} or @var{chroma_strength} must be a float number in
3391 the range [-1.0,1.0] that configures the blurring. A value included in
3392 [0.0,1.0] will blur the image whereas a value included in [-1.0,0.0]
3393 will sharpen the image.
3394
3395 @var{luma_threshold} or @var{chroma_threshold} must be an integer in
3396 the range [-30,30] that is used as a coefficient to determine whether
3397 a pixel should be blurred or not. A value of 0 will filter all the
3398 image, a value included in [0,30] will filter flat areas and a value
3399 included in [-30,0] will filter edges.
3400
3401 @section split
3402
3403 Split input video into several identical outputs.
3404
3405 The filter accepts a single parameter which specifies the number of outputs. If
3406 unspecified, it defaults to 2.
3407
3408 For example
3409 @example
3410 ffmpeg -i INPUT -filter_complex split=5 OUTPUT
3411 @end example
3412 will create 5 copies of the input video.
3413
3414 For example:
3415 @example
3416 [in] split [splitout1][splitout2];
3417 [splitout1] crop=100:100:0:0    [cropout];
3418 [splitout2] pad=200:200:100:100 [padout];
3419 @end example
3420
3421 will create two separate outputs from the same input, one cropped and
3422 one padded.
3423
3424 @section super2xsai
3425
3426 Scale the input by 2x and smooth using the Super2xSaI (Scale and
3427 Interpolate) pixel art scaling algorithm.
3428
3429 Useful for enlarging pixel art images without reducing sharpness.
3430
3431 @section swapuv
3432 Swap U & V plane.
3433
3434 @section thumbnail
3435 Select the most representative frame in a given sequence of consecutive frames.
3436
3437 It accepts as argument the frames batch size to analyze (default @var{N}=100);
3438 in a set of @var{N} frames, the filter will pick one of them, and then handle
3439 the next batch of @var{N} frames until the end.
3440
3441 Since the filter keeps track of the whole frames sequence, a bigger @var{N}
3442 value will result in a higher memory usage, so a high value is not recommended.
3443
3444 The following example extract one picture each 50 frames:
3445 @example
3446 thumbnail=50
3447 @end example
3448
3449 Complete example of a thumbnail creation with @command{ffmpeg}:
3450 @example
3451 ffmpeg -i in.avi -vf thumbnail,scale=300:200 -frames:v 1 out.png
3452 @end example
3453
3454 @section tile
3455
3456 Tile several successive frames together.
3457
3458 It accepts as argument the tile size (i.e. the number of lines and columns)
3459 in the form "@var{w}x@var{h}".
3460
3461 For example, produce 8×8 PNG tiles of all keyframes (@option{-skip_frame
3462 nokey}) in a movie:
3463 @example
3464 ffmpeg -skip_frame nokey -i file.avi -vf 'scale=128:72,tile=8x8' -an -vsync 0 keyframes%03d.png
3465 @end example
3466 The @option{-vsync 0} is necessary to prevent @command{ffmpeg} from
3467 duplicating each output frame to accomodate the originally detected frame
3468 rate.
3469
3470 @section tinterlace
3471
3472 Perform various types of temporal field interlacing.
3473
3474 Frames are counted starting from 1, so the first input frame is
3475 considered odd.
3476
3477 This filter accepts a single parameter specifying the mode. Available
3478 modes are:
3479
3480 @table @samp
3481 @item merge, 0
3482 Move odd frames into the upper field, even into the lower field,
3483 generating a double height frame at half framerate.
3484
3485 @item drop_odd, 1
3486 Only output even frames, odd frames are dropped, generating a frame with
3487 unchanged height at half framerate.
3488
3489 @item drop_even, 2
3490 Only output odd frames, even frames are dropped, generating a frame with
3491 unchanged height at half framerate.
3492
3493 @item pad, 3
3494 Expand each frame to full height, but pad alternate lines with black,
3495 generating a frame with double height at the same input framerate.
3496
3497 @item interleave_top, 4
3498 Interleave the upper field from odd frames with the lower field from
3499 even frames, generating a frame with unchanged height at half framerate.
3500
3501 @item interleave_bottom, 5
3502 Interleave the lower field from odd frames with the upper field from
3503 even frames, generating a frame with unchanged height at half framerate.
3504
3505 @item interlacex2, 6
3506 Double frame rate with unchanged height. Frames are inserted each
3507 containing the second temporal field from the previous input frame and
3508 the first temporal field from the next input frame. This mode relies on
3509 the top_field_first flag. Useful for interlaced video displays with no
3510 field synchronisation.
3511 @end table
3512
3513 Numeric values are deprecated but are accepted for backward
3514 compatibility reasons.
3515
3516 Default mode is @code{merge}.
3517
3518 @section transpose
3519
3520 Transpose rows with columns in the input video and optionally flip it.
3521
3522 It accepts a parameter representing an integer, which can assume the
3523 values:
3524
3525 @table @samp
3526 @item 0, 4
3527 Rotate by 90 degrees counterclockwise and vertically flip (default), that is:
3528 @example
3529 L.R     L.l
3530 . . ->  . .
3531 l.r     R.r
3532 @end example
3533
3534 @item 1, 5
3535 Rotate by 90 degrees clockwise, that is:
3536 @example
3537 L.R     l.L
3538 . . ->  . .
3539 l.r     r.R
3540 @end example
3541
3542 @item 2, 6
3543 Rotate by 90 degrees counterclockwise, that is:
3544 @example
3545 L.R     R.r
3546 . . ->  . .
3547 l.r     L.l
3548 @end example
3549
3550 @item 3, 7
3551 Rotate by 90 degrees clockwise and vertically flip, that is:
3552 @example
3553 L.R     r.R
3554 . . ->  . .
3555 l.r     l.L
3556 @end example
3557 @end table
3558
3559 For values between 4-7 transposition is only done if the input video
3560 geometry is portrait and not landscape.
3561
3562 @section unsharp
3563
3564 Sharpen or blur the input video.
3565
3566 It accepts the following parameters:
3567 @var{luma_msize_x}:@var{luma_msize_y}:@var{luma_amount}:@var{chroma_msize_x}:@var{chroma_msize_y}:@var{chroma_amount}
3568
3569 Negative values for the amount will blur the input video, while positive
3570 values will sharpen. All parameters are optional and default to the
3571 equivalent of the string '5:5:1.0:5:5:0.0'.
3572
3573 @table @option
3574
3575 @item luma_msize_x
3576 Set the luma matrix horizontal size. It can be an integer between 3
3577 and 13, default value is 5.
3578
3579 @item luma_msize_y
3580 Set the luma matrix vertical size. It can be an integer between 3
3581 and 13, default value is 5.
3582
3583 @item luma_amount
3584 Set the luma effect strength. It can be a float number between -2.0
3585 and 5.0, default value is 1.0.
3586
3587 @item chroma_msize_x
3588 Set the chroma matrix horizontal size. It can be an integer between 3
3589 and 13, default value is 5.
3590
3591 @item chroma_msize_y
3592 Set the chroma matrix vertical size. It can be an integer between 3
3593 and 13, default value is 5.
3594
3595 @item chroma_amount
3596 Set the chroma effect strength. It can be a float number between -2.0
3597 and 5.0, default value is 0.0.
3598
3599 @end table
3600
3601 @example
3602 # Strong luma sharpen effect parameters
3603 unsharp=7:7:2.5
3604
3605 # Strong blur of both luma and chroma parameters
3606 unsharp=7:7:-2:7:7:-2
3607
3608 # Use the default values with @command{ffmpeg}
3609 ffmpeg -i in.avi -vf "unsharp" out.mp4
3610 @end example
3611
3612 @section vflip
3613
3614 Flip the input video vertically.
3615
3616 @example
3617 ffmpeg -i in.avi -vf "vflip" out.avi
3618 @end example
3619
3620 @section yadif
3621
3622 Deinterlace the input video ("yadif" means "yet another deinterlacing
3623 filter").
3624
3625 It accepts the optional parameters: @var{mode}:@var{parity}:@var{auto}.
3626
3627 @var{mode} specifies the interlacing mode to adopt, accepts one of the
3628 following values:
3629
3630 @table @option
3631 @item 0
3632 output 1 frame for each frame
3633 @item 1
3634 output 1 frame for each field
3635 @item 2
3636 like 0 but skips spatial interlacing check
3637 @item 3
3638 like 1 but skips spatial interlacing check
3639 @end table
3640
3641 Default value is 0.
3642
3643 @var{parity} specifies the picture field parity assumed for the input
3644 interlaced video, accepts one of the following values:
3645
3646 @table @option
3647 @item 0
3648 assume top field first
3649 @item 1
3650 assume bottom field first
3651 @item -1
3652 enable automatic detection
3653 @end table
3654
3655 Default value is -1.
3656 If interlacing is unknown or decoder does not export this information,
3657 top field first will be assumed.
3658
3659 @var{auto} specifies if deinterlacer should trust the interlaced flag
3660 and only deinterlace frames marked as interlaced
3661
3662 @table @option
3663 @item 0
3664 deinterlace all frames
3665 @item 1
3666 only deinterlace frames marked as interlaced
3667 @end table
3668
3669 Default value is 0.
3670
3671 @c man end VIDEO FILTERS
3672
3673 @chapter Video Sources
3674 @c man begin VIDEO SOURCES
3675
3676 Below is a description of the currently available video sources.
3677
3678 @section buffer
3679
3680 Buffer video frames, and make them available to the filter chain.
3681
3682 This source is mainly intended for a programmatic use, in particular
3683 through the interface defined in @file{libavfilter/vsrc_buffer.h}.
3684
3685 It accepts a list of options in the form of @var{key}=@var{value} pairs
3686 separated by ":". A descroption of the accepted options follows.
3687
3688 @table @option
3689
3690 @item video_size
3691 Specify the size (width and height) of the buffered video frames.
3692
3693 @item pix_fmt
3694 A string representing the pixel format of the buffered video frames.
3695 It may be a number corresponding to a pixel format, or a pixel format
3696 name.
3697
3698 @item time_base
3699 Specify the timebase assumed by the timestamps of the buffered frames.
3700
3701 @item time_base
3702 Specify the frame rate expected for the video stream.
3703
3704 @item pixel_aspect
3705 Specify the sample aspect ratio assumed by the video frames.
3706
3707 @item sws_param
3708 Specify the optional parameters to be used for the scale filter which
3709 is automatically inserted when an input change is detected in the
3710 input size or format.
3711 @end table
3712
3713 For example:
3714 @example
3715 buffer=size=320x240:pix_fmt=yuv410p:time_base=1/24:pixel_aspect=1/1
3716 @end example
3717
3718 will instruct the source to accept video frames with size 320x240 and
3719 with format "yuv410p", assuming 1/24 as the timestamps timebase and
3720 square pixels (1:1 sample aspect ratio).
3721 Since the pixel format with name "yuv410p" corresponds to the number 6
3722 (check the enum PixelFormat definition in @file{libavutil/pixfmt.h}),
3723 this example corresponds to:
3724 @example
3725 buffer=size=320x240:pixfmt=6:time_base=1/24:pixel_aspect=1/1
3726 @end example
3727
3728 Alternatively, the options can be specified as a flat string, but this
3729 syntax is deprecated:
3730
3731 @var{width}:@var{height}:@var{pix_fmt}:@var{time_base.num}:@var{time_base.den}:@var{pixel_aspect.num}:@var{pixel_aspect.den}[:@var{sws_param}]
3732
3733 @section cellauto
3734
3735 Create a pattern generated by an elementary cellular automaton.
3736
3737 The initial state of the cellular automaton can be defined through the
3738 @option{filename}, and @option{pattern} options. If such options are
3739 not specified an initial state is created randomly.
3740
3741 At each new frame a new row in the video is filled with the result of
3742 the cellular automaton next generation. The behavior when the whole
3743 frame is filled is defined by the @option{scroll} option.
3744
3745 This source accepts a list of options in the form of
3746 @var{key}=@var{value} pairs separated by ":". A description of the
3747 accepted options follows.
3748
3749 @table @option
3750 @item filename, f
3751 Read the initial cellular automaton state, i.e. the starting row, from
3752 the specified file.
3753 In the file, each non-whitespace character is considered an alive
3754 cell, a newline will terminate the row, and further characters in the
3755 file will be ignored.
3756
3757 @item pattern, p
3758 Read the initial cellular automaton state, i.e. the starting row, from
3759 the specified string.
3760
3761 Each non-whitespace character in the string is considered an alive
3762 cell, a newline will terminate the row, and further characters in the
3763 string will be ignored.
3764
3765 @item rate, r
3766 Set the video rate, that is the number of frames generated per second.
3767 Default is 25.
3768
3769 @item random_fill_ratio, ratio
3770 Set the random fill ratio for the initial cellular automaton row. It
3771 is a floating point number value ranging from 0 to 1, defaults to
3772 1/PHI.
3773
3774 This option is ignored when a file or a pattern is specified.
3775
3776 @item random_seed, seed
3777 Set the seed for filling randomly the initial row, must be an integer
3778 included between 0 and UINT32_MAX. If not specified, or if explicitly
3779 set to -1, the filter will try to use a good random seed on a best
3780 effort basis.
3781
3782 @item rule
3783 Set the cellular automaton rule, it is a number ranging from 0 to 255.
3784 Default value is 110.
3785
3786 @item size, s
3787 Set the size of the output video.
3788
3789 If @option{filename} or @option{pattern} is specified, the size is set
3790 by default to the width of the specified initial state row, and the
3791 height is set to @var{width} * PHI.
3792
3793 If @option{size} is set, it must contain the width of the specified
3794 pattern string, and the specified pattern will be centered in the
3795 larger row.
3796
3797 If a filename or a pattern string is not specified, the size value
3798 defaults to "320x518" (used for a randomly generated initial state).
3799
3800 @item scroll
3801 If set to 1, scroll the output upward when all the rows in the output
3802 have been already filled. If set to 0, the new generated row will be
3803 written over the top row just after the bottom row is filled.
3804 Defaults to 1.
3805
3806 @item start_full, full
3807 If set to 1, completely fill the output with generated rows before
3808 outputting the first frame.
3809 This is the default behavior, for disabling set the value to 0.
3810
3811 @item stitch
3812 If set to 1, stitch the left and right row edges together.
3813 This is the default behavior, for disabling set the value to 0.
3814 @end table
3815
3816 @subsection Examples
3817
3818 @itemize
3819 @item
3820 Read the initial state from @file{pattern}, and specify an output of
3821 size 200x400.
3822 @example
3823 cellauto=f=pattern:s=200x400
3824 @end example
3825
3826 @item
3827 Generate a random initial row with a width of 200 cells, with a fill
3828 ratio of 2/3:
3829 @example
3830 cellauto=ratio=2/3:s=200x200
3831 @end example
3832
3833 @item
3834 Create a pattern generated by rule 18 starting by a single alive cell
3835 centered on an initial row with width 100:
3836 @example
3837 cellauto=p=@@:s=100x400:full=0:rule=18
3838 @end example
3839
3840 @item
3841 Specify a more elaborated initial pattern:
3842 @example
3843 cellauto=p='@@@@ @@ @@@@':s=100x400:full=0:rule=18
3844 @end example
3845
3846 @end itemize
3847
3848 @section mandelbrot
3849
3850 Generate a Mandelbrot set fractal, and progressively zoom towards the
3851 point specified with @var{start_x} and @var{start_y}.
3852
3853 This source accepts a list of options in the form of
3854 @var{key}=@var{value} pairs separated by ":". A description of the
3855 accepted options follows.
3856
3857 @table @option
3858
3859 @item end_pts
3860 Set the terminal pts value. Default value is 400.
3861
3862 @item end_scale
3863 Set the terminal scale value.
3864 Must be a floating point value. Default value is 0.3.
3865
3866 @item inner
3867 Set the inner coloring mode, that is the algorithm used to draw the
3868 Mandelbrot fractal internal region.
3869
3870 It shall assume one of the following values:
3871 @table @option
3872 @item black
3873 Set black mode.
3874 @item convergence
3875 Show time until convergence.
3876 @item mincol
3877 Set color based on point closest to the origin of the iterations.
3878 @item period
3879 Set period mode.
3880 @end table
3881
3882 Default value is @var{mincol}.
3883
3884 @item bailout
3885 Set the bailout value. Default value is 10.0.
3886
3887 @item maxiter
3888 Set the maximum of iterations performed by the rendering
3889 algorithm. Default value is 7189.
3890
3891 @item outer
3892 Set outer coloring mode.
3893 It shall assume one of following values:
3894 @table @option
3895 @item iteration_count
3896 Set iteration cound mode.
3897 @item normalized_iteration_count
3898 set normalized iteration count mode.
3899 @end table
3900 Default value is @var{normalized_iteration_count}.
3901
3902 @item rate, r
3903 Set frame rate, expressed as number of frames per second. Default
3904 value is "25".
3905
3906 @item size, s
3907 Set frame size. Default value is "640x480".
3908
3909 @item start_scale
3910 Set the initial scale value. Default value is 3.0.
3911
3912 @item start_x
3913 Set the initial x position. Must be a floating point value between
3914 -100 and 100. Default value is -0.743643887037158704752191506114774.
3915
3916 @item start_y
3917 Set the initial y position. Must be a floating point value between
3918 -100 and 100. Default value is -0.131825904205311970493132056385139.
3919 @end table
3920
3921 @section mptestsrc
3922
3923 Generate various test patterns, as generated by the MPlayer test filter.
3924
3925 The size of the generated video is fixed, and is 256x256.
3926 This source is useful in particular for testing encoding features.
3927
3928 This source accepts an optional sequence of @var{key}=@var{value} pairs,
3929 separated by ":". The description of the accepted options follows.
3930
3931 @table @option
3932
3933 @item rate, r
3934 Specify the frame rate of the sourced video, as the number of frames
3935 generated per second. It has to be a string in the format
3936 @var{frame_rate_num}/@var{frame_rate_den}, an integer number, a float
3937 number or a valid video frame rate abbreviation. The default value is
3938 "25".
3939
3940 @item duration, d
3941 Set the video duration of the sourced video. The accepted syntax is:
3942 @example
3943 [-]HH:MM:SS[.m...]
3944 [-]S+[.m...]
3945 @end example
3946 See also the function @code{av_parse_time()}.
3947
3948 If not specified, or the expressed duration is negative, the video is
3949 supposed to be generated forever.
3950
3951 @item test, t
3952
3953 Set the number or the name of the test to perform. Supported tests are:
3954 @table @option
3955 @item dc_luma
3956 @item dc_chroma
3957 @item freq_luma
3958 @item freq_chroma
3959 @item amp_luma
3960 @item amp_chroma
3961 @item cbp
3962 @item mv
3963 @item ring1
3964 @item ring2
3965 @item all
3966 @end table
3967
3968 Default value is "all", which will cycle through the list of all tests.
3969 @end table
3970
3971 For example the following:
3972 @example
3973 testsrc=t=dc_luma
3974 @end example
3975
3976 will generate a "dc_luma" test pattern.
3977
3978 @section frei0r_src
3979
3980 Provide a frei0r source.
3981
3982 To enable compilation of this filter you need to install the frei0r
3983 header and configure FFmpeg with @code{--enable-frei0r}.
3984
3985 The source supports the syntax:
3986 @example
3987 @var{size}:@var{rate}:@var{src_name}[@{=|:@}@var{param1}:@var{param2}:...:@var{paramN}]
3988 @end example
3989
3990 @var{size} is the size of the video to generate, may be a string of the
3991 form @var{width}x@var{height} or a frame size abbreviation.
3992 @var{rate} is the rate of the video to generate, may be a string of
3993 the form @var{num}/@var{den} or a frame rate abbreviation.
3994 @var{src_name} is the name to the frei0r source to load. For more
3995 information regarding frei0r and how to set the parameters read the
3996 section @ref{frei0r} in the description of the video filters.
3997
3998 For example, to generate a frei0r partik0l source with size 200x200
3999 and frame rate 10 which is overlayed on the overlay filter main input:
4000 @example
4001 frei0r_src=200x200:10:partik0l=1234 [overlay]; [in][overlay] overlay
4002 @end example
4003
4004 @section life
4005
4006 Generate a life pattern.
4007
4008 This source is based on a generalization of John Conway's life game.
4009
4010 The sourced input represents a life grid, each pixel represents a cell
4011 which can be in one of two possible states, alive or dead. Every cell
4012 interacts with its eight neighbours, which are the cells that are
4013 horizontally, vertically, or diagonally adjacent.
4014
4015 At each interaction the grid evolves according to the adopted rule,
4016 which specifies the number of neighbor alive cells which will make a
4017 cell stay alive or born. The @option{rule} option allows to specify
4018 the rule to adopt.
4019
4020 This source accepts a list of options in the form of
4021 @var{key}=@var{value} pairs separated by ":". A description of the
4022 accepted options follows.
4023
4024 @table @option
4025 @item filename, f
4026 Set the file from which to read the initial grid state. In the file,
4027 each non-whitespace character is considered an alive cell, and newline
4028 is used to delimit the end of each row.
4029
4030 If this option is not specified, the initial grid is generated
4031 randomly.
4032
4033 @item rate, r
4034 Set the video rate, that is the number of frames generated per second.
4035 Default is 25.
4036
4037 @item random_fill_ratio, ratio
4038 Set the random fill ratio for the initial random grid. It is a
4039 floating point number value ranging from 0 to 1, defaults to 1/PHI.
4040 It is ignored when a file is specified.
4041
4042 @item random_seed, seed
4043 Set the seed for filling the initial random grid, must be an integer
4044 included between 0 and UINT32_MAX. If not specified, or if explicitly
4045 set to -1, the filter will try to use a good random seed on a best
4046 effort basis.
4047
4048 @item rule
4049 Set the life rule.
4050
4051 A rule can be specified with a code of the kind "S@var{NS}/B@var{NB}",
4052 where @var{NS} and @var{NB} are sequences of numbers in the range 0-8,
4053 @var{NS} specifies the number of alive neighbor cells which make a
4054 live cell stay alive, and @var{NB} the number of alive neighbor cells
4055 which make a dead cell to become alive (i.e. to "born").
4056 "s" and "b" can be used in place of "S" and "B", respectively.
4057
4058 Alternatively a rule can be specified by an 18-bits integer. The 9
4059 high order bits are used to encode the next cell state if it is alive
4060 for each number of neighbor alive cells, the low order bits specify
4061 the rule for "borning" new cells. Higher order bits encode for an
4062 higher number of neighbor cells.
4063 For example the number 6153 = @code{(12<<9)+9} specifies a stay alive
4064 rule of 12 and a born rule of 9, which corresponds to "S23/B03".
4065
4066 Default value is "S23/B3", which is the original Conway's game of life
4067 rule, and will keep a cell alive if it has 2 or 3 neighbor alive
4068 cells, and will born a new cell if there are three alive cells around
4069 a dead cell.
4070
4071 @item size, s
4072 Set the size of the output video.
4073
4074 If @option{filename} is specified, the size is set by default to the
4075 same size of the input file. If @option{size} is set, it must contain
4076 the size specified in the input file, and the initial grid defined in
4077 that file is centered in the larger resulting area.
4078
4079 If a filename is not specified, the size value defaults to "320x240"
4080 (used for a randomly generated initial grid).
4081
4082 @item stitch
4083 If set to 1, stitch the left and right grid edges together, and the
4084 top and bottom edges also. Defaults to 1.
4085
4086 @item mold
4087 Set cell mold speed. If set, a dead cell will go from @option{death_color} to
4088 @option{mold_color} with a step of @option{mold}. @option{mold} can have a
4089 value from 0 to 255.
4090
4091 @item life_color
4092 Set the color of living (or new born) cells.
4093
4094 @item death_color
4095 Set the color of dead cells. If @option{mold} is set, this is the first color
4096 used to represent a dead cell.
4097
4098 @item mold_color
4099 Set mold color, for definitely dead and moldy cells.
4100 @end table
4101
4102 @subsection Examples
4103
4104 @itemize
4105 @item
4106 Read a grid from @file{pattern}, and center it on a grid of size
4107 300x300 pixels:
4108 @example
4109 life=f=pattern:s=300x300
4110 @end example
4111
4112 @item
4113 Generate a random grid of size 200x200, with a fill ratio of 2/3:
4114 @example
4115 life=ratio=2/3:s=200x200
4116 @end example
4117
4118 @item
4119 Specify a custom rule for evolving a randomly generated grid:
4120 @example
4121 life=rule=S14/B34
4122 @end example
4123
4124 @item
4125 Full example with slow death effect (mold) using @command{ffplay}:
4126 @example
4127 ffplay -f lavfi life=s=300x200:mold=10:r=60:ratio=0.1:death_color=#C83232:life_color=#00ff00,scale=1200:800:flags=16
4128 @end example
4129 @end itemize
4130
4131 @section color, nullsrc, rgbtestsrc, smptebars, testsrc
4132
4133 The @code{color} source provides an uniformly colored input.
4134
4135 The @code{nullsrc} source returns unprocessed video frames. It is
4136 mainly useful to be employed in analysis / debugging tools, or as the
4137 source for filters which ignore the input data.
4138
4139 The @code{rgbtestsrc} source generates an RGB test pattern useful for
4140 detecting RGB vs BGR issues. You should see a red, green and blue
4141 stripe from top to bottom.
4142
4143 The @code{smptebars} source generates a color bars pattern, based on
4144 the SMPTE Engineering Guideline EG 1-1990.
4145
4146 The @code{testsrc} source generates a test video pattern, showing a
4147 color pattern, a scrolling gradient and a timestamp. This is mainly
4148 intended for testing purposes.
4149
4150 These sources accept an optional sequence of @var{key}=@var{value} pairs,
4151 separated by ":". The description of the accepted options follows.
4152
4153 @table @option
4154
4155 @item color, c
4156 Specify the color of the source, only used in the @code{color}
4157 source. It can be the name of a color (case insensitive match) or a
4158 0xRRGGBB[AA] sequence, possibly followed by an alpha specifier. The
4159 default value is "black".
4160
4161 @item size, s
4162 Specify the size of the sourced video, it may be a string of the form
4163 @var{width}x@var{height}, or the name of a size abbreviation. The
4164 default value is "320x240".
4165
4166 @item rate, r
4167 Specify the frame rate of the sourced video, as the number of frames
4168 generated per second. It has to be a string in the format
4169 @var{frame_rate_num}/@var{frame_rate_den}, an integer number, a float
4170 number or a valid video frame rate abbreviation. The default value is
4171 "25".
4172
4173 @item sar
4174 Set the sample aspect ratio of the sourced video.
4175
4176 @item duration, d
4177 Set the video duration of the sourced video. The accepted syntax is:
4178 @example
4179 [-]HH[:MM[:SS[.m...]]]
4180 [-]S+[.m...]
4181 @end example
4182 See also the function @code{av_parse_time()}.
4183
4184 If not specified, or the expressed duration is negative, the video is
4185 supposed to be generated forever.
4186
4187 @item decimals, n
4188 Set the number of decimals to show in the timestamp, only used in the
4189 @code{testsrc} source.
4190
4191 The displayed timestamp value will correspond to the original
4192 timestamp value multiplied by the power of 10 of the specified
4193 value. Default value is 0.
4194 @end table
4195
4196 For example the following:
4197 @example
4198 testsrc=duration=5.3:size=qcif:rate=10
4199 @end example
4200
4201 will generate a video with a duration of 5.3 seconds, with size
4202 176x144 and a frame rate of 10 frames per second.
4203
4204 The following graph description will generate a red source
4205 with an opacity of 0.2, with size "qcif" and a frame rate of 10
4206 frames per second.
4207 @example
4208 color=c=red@@0.2:s=qcif:r=10
4209 @end example
4210
4211 If the input content is to be ignored, @code{nullsrc} can be used. The
4212 following command generates noise in the luminance plane by employing
4213 the @code{mp=geq} filter:
4214 @example
4215 nullsrc=s=256x256, mp=geq=random(1)*255:128:128
4216 @end example
4217
4218 @c man end VIDEO SOURCES
4219
4220 @chapter Video Sinks
4221 @c man begin VIDEO SINKS
4222
4223 Below is a description of the currently available video sinks.
4224
4225 @section buffersink
4226
4227 Buffer video frames, and make them available to the end of the filter
4228 graph.
4229
4230 This sink is mainly intended for a programmatic use, in particular
4231 through the interface defined in @file{libavfilter/buffersink.h}.
4232
4233 It does not require a string parameter in input, but you need to
4234 specify a pointer to a list of supported pixel formats terminated by
4235 -1 in the opaque parameter provided to @code{avfilter_init_filter}
4236 when initializing this sink.
4237
4238 @section nullsink
4239
4240 Null video sink, do absolutely nothing with the input video. It is
4241 mainly useful as a template and to be employed in analysis / debugging
4242 tools.
4243
4244 @c man end VIDEO SINKS
4245
4246 @chapter Multimedia Filters
4247 @c man begin MULTIMEDIA FILTERS
4248
4249 Below is a description of the currently available multimedia filters.
4250
4251 @section asetpts, setpts
4252
4253 Change the PTS (presentation timestamp) of the input frames.
4254
4255 @code{asetpts} works on audio frames, @code{setpts} on video frames.
4256
4257 Accept in input an expression evaluated through the eval API, which
4258 can contain the following constants:
4259
4260 @table @option
4261 @item FRAME_RATE
4262 frame rate, only defined for constant frame-rate video
4263
4264 @item PTS
4265 the presentation timestamp in input
4266
4267 @item N
4268 the count of the input frame, starting from 0.
4269
4270 @item NB_CONSUMED_SAMPLES
4271 the number of consumed samples, not including the current frame (only
4272 audio)
4273
4274 @item NB_SAMPLES
4275 the number of samples in the current frame (only audio)
4276
4277 @item SAMPLE_RATE
4278 audio sample rate
4279
4280 @item STARTPTS
4281 the PTS of the first frame
4282
4283 @item STARTT
4284 the time in seconds of the first frame
4285
4286 @item INTERLACED
4287 tell if the current frame is interlaced
4288
4289 @item T
4290 the time in seconds of the current frame
4291
4292 @item TB
4293 the time base
4294
4295 @item POS
4296 original position in the file of the frame, or undefined if undefined
4297 for the current frame
4298
4299 @item PREV_INPTS
4300 previous input PTS
4301
4302 @item PREV_INT
4303 previous input time in seconds
4304
4305 @item PREV_OUTPTS
4306 previous output PTS
4307
4308 @item PREV_OUTT
4309 previous output time in seconds
4310 @end table
4311
4312 @subsection Examples
4313
4314 @itemize
4315 @item
4316 Start counting PTS from zero
4317 @example
4318 setpts=PTS-STARTPTS
4319 @end example
4320
4321 @item
4322 Apply fast motion effect:
4323 @example
4324 setpts=0.5*PTS
4325 @end example
4326
4327 @item
4328 Apply slow motion effect:
4329 @example
4330 setpts=2.0*PTS
4331 @end example
4332
4333 @item
4334 Set fixed rate of 25 frames per second:
4335 @example
4336 setpts=N/(25*TB)
4337 @end example
4338
4339 @item
4340 Set fixed rate 25 fps with some jitter:
4341 @example
4342 setpts='1/(25*TB) * (N + 0.05 * sin(N*2*PI/25))'
4343 @end example
4344
4345 @item
4346 Apply an offset of 10 seconds to the input PTS:
4347 @example
4348 setpts=PTS+10/TB
4349 @end example
4350 @end itemize
4351
4352 @section settb, asettb
4353
4354 Set the timebase to use for the output frames timestamps.
4355 It is mainly useful for testing timebase configuration.
4356
4357 It accepts in input an arithmetic expression representing a rational.
4358 The expression can contain the constants "AVTB" (the
4359 default timebase), "intb" (the input timebase) and "sr" (the sample rate,
4360 audio only).
4361
4362 The default value for the input is "intb".
4363
4364 @subsection Examples
4365
4366 @itemize
4367 @item
4368 Set the timebase to 1/25:
4369 @example
4370 settb=1/25
4371 @end example
4372
4373 @item
4374 Set the timebase to 1/10:
4375 @example
4376 settb=0.1
4377 @end example
4378
4379 @item
4380 Set the timebase to 1001/1000:
4381 @example
4382 settb=1+0.001
4383 @end example
4384
4385 @item
4386 Set the timebase to 2*intb:
4387 @example
4388 settb=2*intb
4389 @end example
4390
4391 @item
4392 Set the default timebase value:
4393 @example
4394 settb=AVTB
4395 @end example
4396 @end itemize
4397
4398 @section concat
4399
4400 Concatenate audio and video streams, joining them together one after the
4401 other.
4402
4403 The filter works on segments of synchronized video and audio streams. All
4404 segments must have the same number of streams of each type, and that will
4405 also be the number of streams at output.
4406
4407 The filter accepts the following named parameters:
4408 @table @option
4409
4410 @item n
4411 Set the number of segments. Default is 2.
4412
4413 @item v
4414 Set the number of output video streams, that is also the number of video
4415 streams in each segment. Default is 1.
4416
4417 @item a
4418 Set the number of output audio streams, that is also the number of video
4419 streams in each segment. Default is 0.
4420
4421 @end table
4422
4423 The filter has @var{v}+@var{a} outputs: first @var{v} video outputs, then
4424 @var{a} audio outputs.
4425
4426 There are @var{n}×(@var{v}+@var{a}) inputs: first the inputs for the first
4427 segment, in the same order as the outputs, then the inputs for the second
4428 segment, etc.
4429
4430 Related streams do not always have exactly the same duration, for various
4431 reasons including codec frame size or sloppy authoring. For that reason,
4432 related synchronized streams (e.g. a video and its audio track) should be
4433 concatenated at once. The concat filter will use the duration of the longest
4434 stream in each segment (except the last one), and if necessary pad shorter
4435 audio streams with silence.
4436
4437 For this filter to work correctly, all segments must start at timestamp 0.
4438
4439 All corresponding streams must have the same parameters in all segments; the
4440 filtering system will automatically select a common pixel format for video
4441 streams, and a common sample format, sample rate and channel layout for
4442 audio streams, but other settings, such as resolution, must be converted
4443 explicitly by the user.
4444
4445 Different frame rates are acceptable but will result in variable frame rate
4446 at output; be sure to configure the output file to handle it.
4447
4448 Examples:
4449 @itemize
4450 @item
4451 Concatenate an opening, an episode and an ending, all in bilingual version
4452 (video in stream 0, audio in streams 1 and 2):
4453 @example
4454 ffmpeg -i opening.mkv -i episode.mkv -i ending.mkv -filter_complex \
4455   '[0:0] [0:1] [0:2] [1:0] [1:1] [1:2] [2:0] [2:1] [2:2]
4456    concat=n=3:v=1:a=2 [v] [a1] [a2]' \
4457   -map '[v]' -map '[a1]' -map '[a2]' output.mkv
4458 @end example
4459
4460 @item
4461 Concatenate two parts, handling audio and video separately, using the
4462 (a)movie sources, and adjusting the resolution:
4463 @example
4464 movie=part1.mp4, scale=512:288 [v1] ; amovie=part1.mp4 [a1] ;
4465 movie=part2.mp4, scale=512:288 [v2] ; amovie=part2.mp4 [a2] ;
4466 [v1] [v2] concat [outv] ; [a1] [a2] concat=v=0:a=1 [outa]
4467 @end example
4468 Note that a desync will happen at the stitch if the audio and video streams
4469 do not have exactly the same duration in the first file.
4470
4471 @end itemize
4472
4473 @section showspectrum
4474
4475 Convert input audio to a video output, representing the audio frequency
4476 spectrum.
4477
4478 The filter accepts the following named parameters:
4479 @table @option
4480 @item size, s
4481 Specify the video size for the output. Default value is @code{640x480}.
4482 @end table
4483
4484 The usage is very similar to the showwaves filter; see the examples in that
4485 section.
4486
4487 @section showwaves
4488
4489 Convert input audio to a video output, representing the samples waves.
4490
4491 The filter accepts the following named parameters:
4492 @table @option
4493
4494 @item n
4495 Set the number of samples which are printed on the same column. A
4496 larger value will decrease the frame rate. Must be a positive
4497 integer. This option can be set only if the value for @var{rate}
4498 is not explicitly specified.
4499
4500 @item rate, r
4501 Set the (approximate) output frame rate. This is done by setting the
4502 option @var{n}. Default value is "25".
4503
4504 @item size, s
4505 Specify the video size for the output. Default value is "600x240".
4506 @end table
4507
4508 Some examples follow.
4509 @itemize
4510 @item
4511 Output the input file audio and the corresponding video representation
4512 at the same time:
4513 @example
4514 amovie=a.mp3,asplit[out0],showwaves[out1]
4515 @end example
4516
4517 @item
4518 Create a synthetic signal and show it with showwaves, forcing a
4519 framerate of 30 frames per second:
4520 @example
4521 aevalsrc=sin(1*2*PI*t)*sin(880*2*PI*t):cos(2*PI*200*t),asplit[out0],showwaves=r=30[out1]
4522 @end example
4523 @end itemize
4524
4525 @c man end MULTIMEDIA FILTERS
4526
4527 @chapter Multimedia Sources
4528 @c man begin MULTIMEDIA SOURCES
4529
4530 Below is a description of the currently available multimedia sources.
4531
4532 @section amovie
4533
4534 This is the same as @ref{src_movie} source, except it selects an audio
4535 stream by default.
4536
4537 @anchor{src_movie}
4538 @section movie
4539
4540 Read audio and/or video stream(s) from a movie container.
4541
4542 It accepts the syntax: @var{movie_name}[:@var{options}] where
4543 @var{movie_name} is the name of the resource to read (not necessarily
4544 a file but also a device or a stream accessed through some protocol),
4545 and @var{options} is an optional sequence of @var{key}=@var{value}
4546 pairs, separated by ":".
4547
4548 The description of the accepted options follows.
4549
4550 @table @option
4551
4552 @item format_name, f
4553 Specifies the format assumed for the movie to read, and can be either
4554 the name of a container or an input device. If not specified the
4555 format is guessed from @var{movie_name} or by probing.
4556
4557 @item seek_point, sp
4558 Specifies the seek point in seconds, the frames will be output
4559 starting from this seek point, the parameter is evaluated with
4560 @code{av_strtod} so the numerical value may be suffixed by an IS
4561 postfix. Default value is "0".
4562
4563 @item streams, s
4564 Specifies the streams to read. Several streams can be specified, separated
4565 by "+". The source will then have as many outputs, in the same order. The
4566 syntax is explained in the @ref{Stream specifiers} chapter. Two special
4567 names, "dv" and "da" specify respectively the default (best suited) video
4568 and audio stream. Default is "dv", or "da" if the filter is called as
4569 "amovie".
4570
4571 @item stream_index, si
4572 Specifies the index of the video stream to read. If the value is -1,
4573 the best suited video stream will be automatically selected. Default
4574 value is "-1". Deprecated. If the filter is called "amovie", it will select
4575 audio instead of video.
4576
4577 @item loop
4578 Specifies how many times to read the stream in sequence.
4579 If the value is less than 1, the stream will be read again and again.
4580 Default value is "1".
4581
4582 Note that when the movie is looped the source timestamps are not
4583 changed, so it will generate non monotonically increasing timestamps.
4584 @end table
4585
4586 This filter allows to overlay a second video on top of main input of
4587 a filtergraph as shown in this graph:
4588 @example
4589 input -----------> deltapts0 --> overlay --> output
4590                                     ^
4591                                     |
4592 movie --> scale--> deltapts1 -------+
4593 @end example
4594
4595 Some examples follow.
4596
4597 @itemize
4598 @item
4599 Skip 3.2 seconds from the start of the avi file in.avi, and overlay it
4600 on top of the input labelled as "in":
4601 @example
4602 movie=in.avi:seek_point=3.2, scale=180:-1, setpts=PTS-STARTPTS [movie];
4603 [in] setpts=PTS-STARTPTS, [movie] overlay=16:16 [out]
4604 @end example
4605
4606 @item
4607 Read from a video4linux2 device, and overlay it on top of the input
4608 labelled as "in":
4609 @example
4610 movie=/dev/video0:f=video4linux2, scale=180:-1, setpts=PTS-STARTPTS [movie];
4611 [in] setpts=PTS-STARTPTS, [movie] overlay=16:16 [out]
4612 @end example
4613
4614 @item
4615 Read the first video stream and the audio stream with id 0x81 from
4616 dvd.vob; the video is connected to the pad named "video" and the audio is
4617 connected to the pad named "audio":
4618 @example
4619 movie=dvd.vob:s=v:0+#0x81 [video] [audio]
4620 @end example
4621 @end itemize
4622
4623 @c man end MULTIMEDIA SOURCES