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