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