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