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