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