238401a0d29d830dc802264f283a1525e1f565cf
[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 blackframe
765
766 Detect frames that are (almost) completely black. Can be useful to
767 detect chapter transitions or commercials. Output lines consist of
768 the frame number of the detected frame, the percentage of blackness,
769 the position in the file if known or -1 and the timestamp 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 The filter accepts the syntax:
775 @example
776 blackframe[=@var{amount}:[@var{threshold}]]
777 @end example
778
779 @var{amount} is the percentage of the pixels that have to be below the
780 threshold, and defaults to 98.
781
782 @var{threshold} is the threshold below which a pixel value is
783 considered black, and defaults to 32.
784
785 @section boxblur
786
787 Apply boxblur algorithm to the input video.
788
789 This filter accepts the parameters:
790 @var{luma_radius}:@var{luma_power}:@var{chroma_radius}:@var{chroma_power}:@var{alpha_radius}:@var{alpha_power}
791
792 Chroma and alpha parameters are optional, if not specified they default
793 to the corresponding values set for @var{luma_radius} and
794 @var{luma_power}.
795
796 @var{luma_radius}, @var{chroma_radius}, and @var{alpha_radius} represent
797 the radius in pixels of the box used for blurring the corresponding
798 input plane. They are expressions, and can contain the following
799 constants:
800 @table @option
801 @item w, h
802 the input width and height in pixels
803
804 @item cw, ch
805 the input chroma image width and height in pixels
806
807 @item hsub, vsub
808 horizontal and vertical chroma subsample values. For example for the
809 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
810 @end table
811
812 The radius must be a non-negative number, and must not be greater than
813 the value of the expression @code{min(w,h)/2} for the luma and alpha planes,
814 and of @code{min(cw,ch)/2} for the chroma planes.
815
816 @var{luma_power}, @var{chroma_power}, and @var{alpha_power} represent
817 how many times the boxblur filter is applied to the corresponding
818 plane.
819
820 Some examples follow:
821
822 @itemize
823
824 @item
825 Apply a boxblur filter with luma, chroma, and alpha radius
826 set to 2:
827 @example
828 boxblur=2:1
829 @end example
830
831 @item
832 Set luma radius to 2, alpha and chroma radius to 0
833 @example
834 boxblur=2:1:0:0:0:0
835 @end example
836
837 @item
838 Set luma and chroma radius to a fraction of the video dimension
839 @example
840 boxblur=min(h\,w)/10:1:min(cw\,ch)/10:1
841 @end example
842
843 @end itemize
844
845 @section copy
846
847 Copy the input source unchanged to the output. Mainly useful for
848 testing purposes.
849
850 @section crop
851
852 Crop the input video to @var{out_w}:@var{out_h}:@var{x}:@var{y}.
853
854 The parameters are expressions containing the following constants:
855
856 @table @option
857 @item x, y
858 the computed values for @var{x} and @var{y}. They are evaluated for
859 each new frame.
860
861 @item in_w, in_h
862 the input width and height
863
864 @item iw, ih
865 same as @var{in_w} and @var{in_h}
866
867 @item out_w, out_h
868 the output (cropped) width and height
869
870 @item ow, oh
871 same as @var{out_w} and @var{out_h}
872
873 @item a
874 same as @var{iw} / @var{ih}
875
876 @item sar
877 input sample aspect ratio
878
879 @item dar
880 input display aspect ratio, it is the same as (@var{iw} / @var{ih}) * @var{sar}
881
882 @item hsub, vsub
883 horizontal and vertical chroma subsample values. For example for the
884 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
885
886 @item n
887 the number of input frame, starting from 0
888
889 @item pos
890 the position in the file of the input frame, NAN if unknown
891
892 @item t
893 timestamp expressed in seconds, NAN if the input timestamp is unknown
894
895 @end table
896
897 The @var{out_w} and @var{out_h} parameters specify the expressions for
898 the width and height of the output (cropped) video. They are
899 evaluated just at the configuration of the filter.
900
901 The default value of @var{out_w} is "in_w", and the default value of
902 @var{out_h} is "in_h".
903
904 The expression for @var{out_w} may depend on the value of @var{out_h},
905 and the expression for @var{out_h} may depend on @var{out_w}, but they
906 cannot depend on @var{x} and @var{y}, as @var{x} and @var{y} are
907 evaluated after @var{out_w} and @var{out_h}.
908
909 The @var{x} and @var{y} parameters specify the expressions for the
910 position of the top-left corner of the output (non-cropped) area. They
911 are evaluated for each frame. If the evaluated value is not valid, it
912 is approximated to the nearest valid value.
913
914 The default value of @var{x} is "(in_w-out_w)/2", and the default
915 value for @var{y} is "(in_h-out_h)/2", which set the cropped area at
916 the center of the input image.
917
918 The expression for @var{x} may depend on @var{y}, and the expression
919 for @var{y} may depend on @var{x}.
920
921 Follow some examples:
922 @example
923 # crop the central input area with size 100x100
924 crop=100:100
925
926 # crop the central input area with size 2/3 of the input video
927 "crop=2/3*in_w:2/3*in_h"
928
929 # crop the input video central square
930 crop=in_h
931
932 # delimit the rectangle with the top-left corner placed at position
933 # 100:100 and the right-bottom corner corresponding to the right-bottom
934 # corner of the input image.
935 crop=in_w-100:in_h-100:100:100
936
937 # crop 10 pixels from the left and right borders, and 20 pixels from
938 # the top and bottom borders
939 "crop=in_w-2*10:in_h-2*20"
940
941 # keep only the bottom right quarter of the input image
942 "crop=in_w/2:in_h/2:in_w/2:in_h/2"
943
944 # crop height for getting Greek harmony
945 "crop=in_w:1/PHI*in_w"
946
947 # trembling effect
948 "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)"
949
950 # erratic camera effect depending on timestamp
951 "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)"
952
953 # set x depending on the value of y
954 "crop=in_w/2:in_h/2:y:10+10*sin(n/10)"
955 @end example
956
957 @section cropdetect
958
959 Auto-detect crop size.
960
961 Calculate necessary cropping parameters and prints the recommended
962 parameters through the logging system. The detected dimensions
963 correspond to the non-black area of the input video.
964
965 It accepts the syntax:
966 @example
967 cropdetect[=@var{limit}[:@var{round}[:@var{reset}]]]
968 @end example
969
970 @table @option
971
972 @item limit
973 Threshold, which can be optionally specified from nothing (0) to
974 everything (255), defaults to 24.
975
976 @item round
977 Value which the width/height should be divisible by, defaults to
978 16. The offset is automatically adjusted to center the video. Use 2 to
979 get only even dimensions (needed for 4:2:2 video). 16 is best when
980 encoding to most video codecs.
981
982 @item reset
983 Counter that determines after how many frames cropdetect will reset
984 the previously detected largest video area and start over to detect
985 the current optimal crop area. Defaults to 0.
986
987 This can be useful when channel logos distort the video area. 0
988 indicates never reset and return the largest area encountered during
989 playback.
990 @end table
991
992 @section delogo
993
994 Suppress a TV station logo by a simple interpolation of the surrounding
995 pixels. Just set a rectangle covering the logo and watch it disappear
996 (and sometimes something even uglier appear - your mileage may vary).
997
998 The filter accepts parameters as a string of the form
999 "@var{x}:@var{y}:@var{w}:@var{h}:@var{band}", or as a list of
1000 @var{key}=@var{value} pairs, separated by ":".
1001
1002 The description of the accepted parameters follows.
1003
1004 @table @option
1005
1006 @item x, y
1007 Specify the top left corner coordinates of the logo. They must be
1008 specified.
1009
1010 @item w, h
1011 Specify the width and height of the logo to clear. They must be
1012 specified.
1013
1014 @item band, t
1015 Specify the thickness of the fuzzy edge of the rectangle (added to
1016 @var{w} and @var{h}). The default value is 4.
1017
1018 @item show
1019 When set to 1, a green rectangle is drawn on the screen to simplify
1020 finding the right @var{x}, @var{y}, @var{w}, @var{h} parameters, and
1021 @var{band} is set to 4. The default value is 0.
1022
1023 @end table
1024
1025 Some examples follow.
1026
1027 @itemize
1028
1029 @item
1030 Set a rectangle covering the area with top left corner coordinates 0,0
1031 and size 100x77, setting a band of size 10:
1032 @example
1033 delogo=0:0:100:77:10
1034 @end example
1035
1036 @item
1037 As the previous example, but use named options:
1038 @example
1039 delogo=x=0:y=0:w=100:h=77:band=10
1040 @end example
1041
1042 @end itemize
1043
1044 @section deshake
1045
1046 Attempt to fix small changes in horizontal and/or vertical shift. This
1047 filter helps remove camera shake from hand-holding a camera, bumping a
1048 tripod, moving on a vehicle, etc.
1049
1050 The filter accepts parameters as a string of the form
1051 "@var{x}:@var{y}:@var{w}:@var{h}:@var{rx}:@var{ry}:@var{edge}:@var{blocksize}:@var{contrast}:@var{search}:@var{filename}"
1052
1053 A description of the accepted parameters follows.
1054
1055 @table @option
1056
1057 @item x, y, w, h
1058 Specify a rectangular area where to limit the search for motion
1059 vectors.
1060 If desired the search for motion vectors can be limited to a
1061 rectangular area of the frame defined by its top left corner, width
1062 and height. These parameters have the same meaning as the drawbox
1063 filter which can be used to visualise the position of the bounding
1064 box.
1065
1066 This is useful when simultaneous movement of subjects within the frame
1067 might be confused for camera motion by the motion vector search.
1068
1069 If any or all of @var{x}, @var{y}, @var{w} and @var{h} are set to -1
1070 then the full frame is used. This allows later options to be set
1071 without specifying the bounding box for the motion vector search.
1072
1073 Default - search the whole frame.
1074
1075 @item rx, ry
1076 Specify the maximum extent of movement in x and y directions in the
1077 range 0-64 pixels. Default 16.
1078
1079 @item edge
1080 Specify how to generate pixels to fill blanks at the edge of the
1081 frame. An integer from 0 to 3 as follows:
1082 @table @option
1083 @item 0
1084 Fill zeroes at blank locations
1085 @item 1
1086 Original image at blank locations
1087 @item 2
1088 Extruded edge value at blank locations
1089 @item 3
1090 Mirrored edge at blank locations
1091 @end table
1092
1093 The default setting is mirror edge at blank locations.
1094
1095 @item blocksize
1096 Specify the blocksize to use for motion search. Range 4-128 pixels,
1097 default 8.
1098
1099 @item contrast
1100 Specify the contrast threshold for blocks. Only blocks with more than
1101 the specified contrast (difference between darkest and lightest
1102 pixels) will be considered. Range 1-255, default 125.
1103
1104 @item search
1105 Specify the search strategy 0 = exhaustive search, 1 = less exhaustive
1106 search. Default - exhaustive search.
1107
1108 @item filename
1109 If set then a detailed log of the motion search is written to the
1110 specified file.
1111
1112 @end table
1113
1114 @section drawbox
1115
1116 Draw a colored box on the input image.
1117
1118 It accepts the syntax:
1119 @example
1120 drawbox=@var{x}:@var{y}:@var{width}:@var{height}:@var{color}
1121 @end example
1122
1123 @table @option
1124
1125 @item x, y
1126 Specify the top left corner coordinates of the box. Default to 0.
1127
1128 @item width, height
1129 Specify the width and height of the box, if 0 they are interpreted as
1130 the input width and height. Default to 0.
1131
1132 @item color
1133 Specify the color of the box to write, it can be the name of a color
1134 (case insensitive match) or a 0xRRGGBB[AA] sequence.
1135 @end table
1136
1137 Follow some examples:
1138 @example
1139 # draw a black box around the edge of the input image
1140 drawbox
1141
1142 # draw a box with color red and an opacity of 50%
1143 drawbox=10:20:200:60:red@@0.5"
1144 @end example
1145
1146 @section drawtext
1147
1148 Draw text string or text from specified file on top of video using the
1149 libfreetype library.
1150
1151 To enable compilation of this filter you need to configure FFmpeg with
1152 @code{--enable-libfreetype}.
1153
1154 The filter also recognizes strftime() sequences in the provided text
1155 and expands them accordingly. Check the documentation of strftime().
1156
1157 The filter accepts parameters as a list of @var{key}=@var{value} pairs,
1158 separated by ":".
1159
1160 The description of the accepted parameters follows.
1161
1162 @table @option
1163
1164 @item fontfile
1165 The font file to be used for drawing text. Path must be included.
1166 This parameter is mandatory.
1167
1168 @item text
1169 The text string to be drawn. The text must be a sequence of UTF-8
1170 encoded characters.
1171 This parameter is mandatory if no file is specified with the parameter
1172 @var{textfile}.
1173
1174 @item textfile
1175 A text file containing text to be drawn. The text must be a sequence
1176 of UTF-8 encoded characters.
1177
1178 This parameter is mandatory if no text string is specified with the
1179 parameter @var{text}.
1180
1181 If both text and textfile are specified, an error is thrown.
1182
1183 @item x, y
1184 The expressions which specify the offsets where text will be drawn
1185 within the video frame. They are relative to the top/left border of the
1186 output image.
1187
1188 The default value of @var{x} and @var{y} is "0".
1189
1190 See below for the list of accepted constants.
1191
1192 @item fontsize
1193 The font size to be used for drawing text.
1194 The default value of @var{fontsize} is 16.
1195
1196 @item fontcolor
1197 The color to be used for drawing fonts.
1198 Either a string (e.g. "red") or in 0xRRGGBB[AA] format
1199 (e.g. "0xff000033"), possibly followed by an alpha specifier.
1200 The default value of @var{fontcolor} is "black".
1201
1202 @item boxcolor
1203 The color to be used for drawing box around text.
1204 Either a string (e.g. "yellow") or in 0xRRGGBB[AA] format
1205 (e.g. "0xff00ff"), possibly followed by an alpha specifier.
1206 The default value of @var{boxcolor} is "white".
1207
1208 @item box
1209 Used to draw a box around text using background color.
1210 Value should be either 1 (enable) or 0 (disable).
1211 The default value of @var{box} is 0.
1212
1213 @item shadowx, shadowy
1214 The x and y offsets for the text shadow position with respect to the
1215 position of the text. They can be either positive or negative
1216 values. Default value for both is "0".
1217
1218 @item shadowcolor
1219 The color to be used for drawing a shadow behind the drawn text.  It
1220 can be a color name (e.g. "yellow") or a string in the 0xRRGGBB[AA]
1221 form (e.g. "0xff00ff"), possibly followed by an alpha specifier.
1222 The default value of @var{shadowcolor} is "black".
1223
1224 @item ft_load_flags
1225 Flags to be used for loading the fonts.
1226
1227 The flags map the corresponding flags supported by libfreetype, and are
1228 a combination of the following values:
1229 @table @var
1230 @item default
1231 @item no_scale
1232 @item no_hinting
1233 @item render
1234 @item no_bitmap
1235 @item vertical_layout
1236 @item force_autohint
1237 @item crop_bitmap
1238 @item pedantic
1239 @item ignore_global_advance_width
1240 @item no_recurse
1241 @item ignore_transform
1242 @item monochrome
1243 @item linear_design
1244 @item no_autohint
1245 @item end table
1246 @end table
1247
1248 Default value is "render".
1249
1250 For more information consult the documentation for the FT_LOAD_*
1251 libfreetype flags.
1252
1253 @item tabsize
1254 The size in number of spaces to use for rendering the tab.
1255 Default value is 4.
1256
1257 @item fix_bounds
1258 If true, check and fix text coords to avoid clipping.
1259 @end table
1260
1261 The parameters for @var{x} and @var{y} are expressions containing the
1262 following constants:
1263
1264 @table @option
1265 @item W, H
1266 the input width and height
1267
1268 @item tw, text_w
1269 the width of the rendered text
1270
1271 @item th, text_h
1272 the height of the rendered text
1273
1274 @item lh, line_h
1275 the height of each text line
1276
1277 @item sar
1278 input sample aspect ratio
1279
1280 @item dar
1281 input display aspect ratio, it is the same as (@var{w} / @var{h}) * @var{sar}
1282
1283 @item hsub, vsub
1284 horizontal and vertical chroma subsample values. For example for the
1285 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
1286
1287 @item max_glyph_w
1288 maximum glyph width, that is the maximum width for all the glyphs
1289 contained in the rendered text
1290
1291 @item max_glyph_h
1292 maximum glyph height, that is the maximum height for all the glyphs
1293 contained in the rendered text, it is equivalent to @var{ascent} -
1294 @var{descent}.
1295
1296 @item max_glyph_a, ascent
1297
1298 the maximum distance from the baseline to the highest/upper grid
1299 coordinate used to place a glyph outline point, for all the rendered
1300 glyphs.
1301 It is a positive value, due to the grid's orientation with the Y axis
1302 upwards.
1303
1304 @item max_glyph_d, descent
1305 the maximum distance from the baseline to the lowest grid coordinate
1306 used to place a glyph outline point, for all the rendered glyphs.
1307 This is a negative value, due to the grid's orientation, with the Y axis
1308 upwards.
1309
1310 @item n
1311 the number of input frame, starting from 0
1312
1313 @item t
1314 timestamp expressed in seconds, NAN if the input timestamp is unknown
1315
1316 @item timecode
1317 initial timecode representation in "hh:mm:ss[:;.]ff" format. It can be used
1318 with or without text parameter. @var{rate} option must be specified.
1319
1320 @item r, rate
1321 frame rate (timecode only)
1322 @end table
1323
1324 Some examples follow.
1325
1326 @itemize
1327
1328 @item
1329 Draw "Test Text" with font FreeSerif, using the default values for the
1330 optional parameters.
1331
1332 @example
1333 drawtext="fontfile=/usr/share/fonts/truetype/freefont/FreeSerif.ttf: text='Test Text'"
1334 @end example
1335
1336 @item
1337 Draw 'Test Text' with font FreeSerif of size 24 at position x=100
1338 and y=50 (counting from the top-left corner of the screen), text is
1339 yellow with a red box around it. Both the text and the box have an
1340 opacity of 20%.
1341
1342 @example
1343 drawtext="fontfile=/usr/share/fonts/truetype/freefont/FreeSerif.ttf: text='Test Text':\
1344           x=100: y=50: fontsize=24: fontcolor=yellow@@0.2: box=1: boxcolor=red@@0.2"
1345 @end example
1346
1347 Note that the double quotes are not necessary if spaces are not used
1348 within the parameter list.
1349
1350 @item
1351 Show the text at the center of the video frame:
1352 @example
1353 drawtext=fontsize=30:fontfile=FreeSerif.ttf:text='hello world':x=(w-text_w)/2:y=(h-text_h-line_h)/2"
1354 @end example
1355
1356 @item
1357 Show a text line sliding from right to left in the last row of the video
1358 frame. The file @file{LONG_LINE} is assumed to contain a single line
1359 with no newlines.
1360 @example
1361 drawtext=fontsize=15:fontfile=FreeSerif.ttf:text=LONG_LINE:y=h-line_h:x=-50*t
1362 @end example
1363
1364 @item
1365 Show the content of file @file{CREDITS} off the bottom of the frame and scroll up.
1366 @example
1367 drawtext=fontsize=20:fontfile=FreeSerif.ttf:textfile=CREDITS:y=h-20*t"
1368 @end example
1369
1370 @item
1371 Draw a single green letter "g", at the center of the input video.
1372 The glyph baseline is placed at half screen height.
1373 @example
1374 drawtext=fontsize=60:fontfile=FreeSerif.ttf:fontcolor=green:text=g:x=(w-max_glyph_w)/2:y=h/2-ascent
1375 @end example
1376
1377 @end itemize
1378
1379 For more information about libfreetype, check:
1380 @url{http://www.freetype.org/}.
1381
1382 @section fade
1383
1384 Apply fade-in/out effect to input video.
1385
1386 It accepts the parameters:
1387 @var{type}:@var{start_frame}:@var{nb_frames}[:@var{options}]
1388
1389 @var{type} specifies if the effect type, can be either "in" for
1390 fade-in, or "out" for a fade-out effect.
1391
1392 @var{start_frame} specifies the number of the start frame for starting
1393 to apply the fade effect.
1394
1395 @var{nb_frames} specifies the number of frames for which the fade
1396 effect has to last. At the end of the fade-in effect the output video
1397 will have the same intensity as the input video, at the end of the
1398 fade-out transition the output video will be completely black.
1399
1400 @var{options} is an optional sequence of @var{key}=@var{value} pairs,
1401 separated by ":". The description of the accepted options follows.
1402
1403 @table @option
1404
1405 @item type, t
1406 See @var{type}.
1407
1408 @item start_frame, s
1409 See @var{start_frame}.
1410
1411 @item nb_frames, n
1412 See @var{nb_frames}.
1413
1414 @item alpha
1415 If set to 1, fade only alpha channel, if one exists on the input.
1416 Default value is 0.
1417 @end table
1418
1419 A few usage examples follow, usable too as test scenarios.
1420 @example
1421 # fade in first 30 frames of video
1422 fade=in:0:30
1423
1424 # fade out last 45 frames of a 200-frame video
1425 fade=out:155:45
1426
1427 # fade in first 25 frames and fade out last 25 frames of a 1000-frame video
1428 fade=in:0:25, fade=out:975:25
1429
1430 # make first 5 frames black, then fade in from frame 5-24
1431 fade=in:5:20
1432
1433 # fade in alpha over first 25 frames of video
1434 fade=in:0:25:alpha=1
1435 @end example
1436
1437 @section fieldorder
1438
1439 Transform the field order of the input video.
1440
1441 It accepts one parameter which specifies the required field order that
1442 the input interlaced video will be transformed to. The parameter can
1443 assume one of the following values:
1444
1445 @table @option
1446 @item 0 or bff
1447 output bottom field first
1448 @item 1 or tff
1449 output top field first
1450 @end table
1451
1452 Default value is "tff".
1453
1454 Transformation is achieved by shifting the picture content up or down
1455 by one line, and filling the remaining line with appropriate picture content.
1456 This method is consistent with most broadcast field order converters.
1457
1458 If the input video is not flagged as being interlaced, or it is already
1459 flagged as being of the required output field order then this filter does
1460 not alter the incoming video.
1461
1462 This filter is very useful when converting to or from PAL DV material,
1463 which is bottom field first.
1464
1465 For example:
1466 @example
1467 ffmpeg -i in.vob -vf "fieldorder=bff" out.dv
1468 @end example
1469
1470 @section fifo
1471
1472 Buffer input images and send them when they are requested.
1473
1474 This filter is mainly useful when auto-inserted by the libavfilter
1475 framework.
1476
1477 The filter does not take parameters.
1478
1479 @section format
1480
1481 Convert the input video to one of the specified pixel formats.
1482 Libavfilter will try to pick one that is supported for the input to
1483 the next filter.
1484
1485 The filter accepts a list of pixel format names, separated by ":",
1486 for example "yuv420p:monow:rgb24".
1487
1488 Some examples follow:
1489 @example
1490 # convert the input video to the format "yuv420p"
1491 format=yuv420p
1492
1493 # convert the input video to any of the formats in the list
1494 format=yuv420p:yuv444p:yuv410p
1495 @end example
1496
1497 @anchor{frei0r}
1498 @section frei0r
1499
1500 Apply a frei0r effect to the input video.
1501
1502 To enable compilation of this filter you need to install the frei0r
1503 header and configure FFmpeg with @code{--enable-frei0r}.
1504
1505 The filter supports the syntax:
1506 @example
1507 @var{filter_name}[@{:|=@}@var{param1}:@var{param2}:...:@var{paramN}]
1508 @end example
1509
1510 @var{filter_name} is the name to the frei0r effect to load. If the
1511 environment variable @env{FREI0R_PATH} is defined, the frei0r effect
1512 is searched in each one of the directories specified by the colon
1513 separated list in @env{FREIOR_PATH}, otherwise in the standard frei0r
1514 paths, which are in this order: @file{HOME/.frei0r-1/lib/},
1515 @file{/usr/local/lib/frei0r-1/}, @file{/usr/lib/frei0r-1/}.
1516
1517 @var{param1}, @var{param2}, ... , @var{paramN} specify the parameters
1518 for the frei0r effect.
1519
1520 A frei0r effect parameter can be a boolean (whose values are specified
1521 with "y" and "n"), a double, a color (specified by the syntax
1522 @var{R}/@var{G}/@var{B}, @var{R}, @var{G}, and @var{B} being float
1523 numbers from 0.0 to 1.0) or by an @code{av_parse_color()} color
1524 description), a position (specified by the syntax @var{X}/@var{Y},
1525 @var{X} and @var{Y} being float numbers) and a string.
1526
1527 The number and kind of parameters depend on the loaded effect. If an
1528 effect parameter is not specified the default value is set.
1529
1530 Some examples follow:
1531 @example
1532 # apply the distort0r effect, set the first two double parameters
1533 frei0r=distort0r:0.5:0.01
1534
1535 # apply the colordistance effect, takes a color as first parameter
1536 frei0r=colordistance:0.2/0.3/0.4
1537 frei0r=colordistance:violet
1538 frei0r=colordistance:0x112233
1539
1540 # apply the perspective effect, specify the top left and top right
1541 # image positions
1542 frei0r=perspective:0.2/0.2:0.8/0.2
1543 @end example
1544
1545 For more information see:
1546 @url{http://piksel.org/frei0r}
1547
1548 @section gradfun
1549
1550 Fix the banding artifacts that are sometimes introduced into nearly flat
1551 regions by truncation to 8bit color depth.
1552 Interpolate the gradients that should go where the bands are, and
1553 dither them.
1554
1555 This filter is designed for playback only.  Do not use it prior to
1556 lossy compression, because compression tends to lose the dither and
1557 bring back the bands.
1558
1559 The filter takes two optional parameters, separated by ':':
1560 @var{strength}:@var{radius}
1561
1562 @var{strength} is the maximum amount by which the filter will change
1563 any one pixel. Also the threshold for detecting nearly flat
1564 regions. Acceptable values range from .51 to 255, default value is
1565 1.2, out-of-range values will be clipped to the valid range.
1566
1567 @var{radius} is the neighborhood to fit the gradient to. A larger
1568 radius makes for smoother gradients, but also prevents the filter from
1569 modifying the pixels near detailed regions. Acceptable values are
1570 8-32, default value is 16, out-of-range values will be clipped to the
1571 valid range.
1572
1573 @example
1574 # default parameters
1575 gradfun=1.2:16
1576
1577 # omitting radius
1578 gradfun=1.2
1579 @end example
1580
1581 @section hflip
1582
1583 Flip the input video horizontally.
1584
1585 For example to horizontally flip the input video with @command{ffmpeg}:
1586 @example
1587 ffmpeg -i in.avi -vf "hflip" out.avi
1588 @end example
1589
1590 @section hqdn3d
1591
1592 High precision/quality 3d denoise filter. This filter aims to reduce
1593 image noise producing smooth images and making still images really
1594 still. It should enhance compressibility.
1595
1596 It accepts the following optional parameters:
1597 @var{luma_spatial}:@var{chroma_spatial}:@var{luma_tmp}:@var{chroma_tmp}
1598
1599 @table @option
1600 @item luma_spatial
1601 a non-negative float number which specifies spatial luma strength,
1602 defaults to 4.0
1603
1604 @item chroma_spatial
1605 a non-negative float number which specifies spatial chroma strength,
1606 defaults to 3.0*@var{luma_spatial}/4.0
1607
1608 @item luma_tmp
1609 a float number which specifies luma temporal strength, defaults to
1610 6.0*@var{luma_spatial}/4.0
1611
1612 @item chroma_tmp
1613 a float number which specifies chroma temporal strength, defaults to
1614 @var{luma_tmp}*@var{chroma_spatial}/@var{luma_spatial}
1615 @end table
1616
1617 @section lut, lutrgb, lutyuv
1618
1619 Compute a look-up table for binding each pixel component input value
1620 to an output value, and apply it to input video.
1621
1622 @var{lutyuv} applies a lookup table to a YUV input video, @var{lutrgb}
1623 to an RGB input video.
1624
1625 These filters accept in input a ":"-separated list of options, which
1626 specify the expressions used for computing the lookup table for the
1627 corresponding pixel component values.
1628
1629 The @var{lut} filter requires either YUV or RGB pixel formats in
1630 input, and accepts the options:
1631 @table @option
1632 @item c0
1633 first  pixel component
1634 @item c1
1635 second pixel component
1636 @item c2
1637 third  pixel component
1638 @item c3
1639 fourth pixel component, corresponds to the alpha component
1640 @end table
1641
1642 The exact component associated to each option depends on the format in
1643 input.
1644
1645 The @var{lutrgb} filter requires RGB pixel formats in input, and
1646 accepts the options:
1647 @table @option
1648 @item r
1649 red component
1650 @item g
1651 green component
1652 @item b
1653 blue component
1654 @item a
1655 alpha component
1656 @end table
1657
1658 The @var{lutyuv} filter requires YUV pixel formats in input, and
1659 accepts the options:
1660 @table @option
1661 @item y
1662 Y/luminance component
1663 @item u
1664 U/Cb component
1665 @item v
1666 V/Cr component
1667 @item a
1668 alpha component
1669 @end table
1670
1671 The expressions can contain the following constants and functions:
1672
1673 @table @option
1674 @item w, h
1675 the input width and height
1676
1677 @item val
1678 input value for the pixel component
1679
1680 @item clipval
1681 the input value clipped in the @var{minval}-@var{maxval} range
1682
1683 @item maxval
1684 maximum value for the pixel component
1685
1686 @item minval
1687 minimum value for the pixel component
1688
1689 @item negval
1690 the negated value for the pixel component value clipped in the
1691 @var{minval}-@var{maxval} range , it corresponds to the expression
1692 "maxval-clipval+minval"
1693
1694 @item clip(val)
1695 the computed value in @var{val} clipped in the
1696 @var{minval}-@var{maxval} range
1697
1698 @item gammaval(gamma)
1699 the computed gamma correction value of the pixel component value
1700 clipped in the @var{minval}-@var{maxval} range, corresponds to the
1701 expression
1702 "pow((clipval-minval)/(maxval-minval)\,@var{gamma})*(maxval-minval)+minval"
1703
1704 @end table
1705
1706 All expressions default to "val".
1707
1708 Some examples follow:
1709 @example
1710 # negate input video
1711 lutrgb="r=maxval+minval-val:g=maxval+minval-val:b=maxval+minval-val"
1712 lutyuv="y=maxval+minval-val:u=maxval+minval-val:v=maxval+minval-val"
1713
1714 # the above is the same as
1715 lutrgb="r=negval:g=negval:b=negval"
1716 lutyuv="y=negval:u=negval:v=negval"
1717
1718 # negate luminance
1719 lutyuv=y=negval
1720
1721 # remove chroma components, turns the video into a graytone image
1722 lutyuv="u=128:v=128"
1723
1724 # apply a luma burning effect
1725 lutyuv="y=2*val"
1726
1727 # remove green and blue components
1728 lutrgb="g=0:b=0"
1729
1730 # set a constant alpha channel value on input
1731 format=rgba,lutrgb=a="maxval-minval/2"
1732
1733 # correct luminance gamma by a 0.5 factor
1734 lutyuv=y=gammaval(0.5)
1735 @end example
1736
1737 @section mp
1738
1739 Apply an MPlayer filter to the input video.
1740
1741 This filter provides a wrapper around most of the filters of
1742 MPlayer/MEncoder.
1743
1744 This wrapper is considered experimental. Some of the wrapped filters
1745 may not work properly and we may drop support for them, as they will
1746 be implemented natively into FFmpeg. Thus you should avoid
1747 depending on them when writing portable scripts.
1748
1749 The filters accepts the parameters:
1750 @var{filter_name}[:=]@var{filter_params}
1751
1752 @var{filter_name} is the name of a supported MPlayer filter,
1753 @var{filter_params} is a string containing the parameters accepted by
1754 the named filter.
1755
1756 The list of the currently supported filters follows:
1757 @table @var
1758 @item 2xsai
1759 @item decimate
1760 @item denoise3d
1761 @item detc
1762 @item dint
1763 @item divtc
1764 @item down3dright
1765 @item dsize
1766 @item eq2
1767 @item eq
1768 @item field
1769 @item fil
1770 @item fixpts
1771 @item framestep
1772 @item fspp
1773 @item geq
1774 @item harddup
1775 @item hqdn3d
1776 @item hue
1777 @item il
1778 @item ilpack
1779 @item ivtc
1780 @item kerndeint
1781 @item mcdeint
1782 @item mirror
1783 @item noise
1784 @item ow
1785 @item palette
1786 @item perspective
1787 @item phase
1788 @item pp7
1789 @item pullup
1790 @item qp
1791 @item rectangle
1792 @item remove-logo
1793 @item rotate
1794 @item sab
1795 @item screenshot
1796 @item smartblur
1797 @item softpulldown
1798 @item softskip
1799 @item spp
1800 @item swapuv
1801 @item telecine
1802 @item tile
1803 @item tinterlace
1804 @item unsharp
1805 @item uspp
1806 @item yuvcsp
1807 @item yvu9
1808 @end table
1809
1810 The parameter syntax and behavior for the listed filters are the same
1811 of the corresponding MPlayer filters. For detailed instructions check
1812 the "VIDEO FILTERS" section in the MPlayer manual.
1813
1814 Some examples follow:
1815 @example
1816 # remove a logo by interpolating the surrounding pixels
1817 mp=delogo=200:200:80:20:1
1818
1819 # adjust gamma, brightness, contrast
1820 mp=eq2=1.0:2:0.5
1821
1822 # tweak hue and saturation
1823 mp=hue=100:-10
1824 @end example
1825
1826 See also mplayer(1), @url{http://www.mplayerhq.hu/}.
1827
1828 @section negate
1829
1830 Negate input video.
1831
1832 This filter accepts an integer in input, if non-zero it negates the
1833 alpha component (if available). The default value in input is 0.
1834
1835 @section noformat
1836
1837 Force libavfilter not to use any of the specified pixel formats for the
1838 input to the next filter.
1839
1840 The filter accepts a list of pixel format names, separated by ":",
1841 for example "yuv420p:monow:rgb24".
1842
1843 Some examples follow:
1844 @example
1845 # force libavfilter to use a format different from "yuv420p" for the
1846 # input to the vflip filter
1847 noformat=yuv420p,vflip
1848
1849 # convert the input video to any of the formats not contained in the list
1850 noformat=yuv420p:yuv444p:yuv410p
1851 @end example
1852
1853 @section null
1854
1855 Pass the video source unchanged to the output.
1856
1857 @section ocv
1858
1859 Apply video transform using libopencv.
1860
1861 To enable this filter install libopencv library and headers and
1862 configure FFmpeg with @code{--enable-libopencv}.
1863
1864 The filter takes the parameters: @var{filter_name}@{:=@}@var{filter_params}.
1865
1866 @var{filter_name} is the name of the libopencv filter to apply.
1867
1868 @var{filter_params} specifies the parameters to pass to the libopencv
1869 filter. If not specified the default values are assumed.
1870
1871 Refer to the official libopencv documentation for more precise
1872 information:
1873 @url{http://opencv.willowgarage.com/documentation/c/image_filtering.html}
1874
1875 Follows the list of supported libopencv filters.
1876
1877 @anchor{dilate}
1878 @subsection dilate
1879
1880 Dilate an image by using a specific structuring element.
1881 This filter corresponds to the libopencv function @code{cvDilate}.
1882
1883 It accepts the parameters: @var{struct_el}:@var{nb_iterations}.
1884
1885 @var{struct_el} represents a structuring element, and has the syntax:
1886 @var{cols}x@var{rows}+@var{anchor_x}x@var{anchor_y}/@var{shape}
1887
1888 @var{cols} and @var{rows} represent the number of columns and rows of
1889 the structuring element, @var{anchor_x} and @var{anchor_y} the anchor
1890 point, and @var{shape} the shape for the structuring element, and
1891 can be one of the values "rect", "cross", "ellipse", "custom".
1892
1893 If the value for @var{shape} is "custom", it must be followed by a
1894 string of the form "=@var{filename}". The file with name
1895 @var{filename} is assumed to represent a binary image, with each
1896 printable character corresponding to a bright pixel. When a custom
1897 @var{shape} is used, @var{cols} and @var{rows} are ignored, the number
1898 or columns and rows of the read file are assumed instead.
1899
1900 The default value for @var{struct_el} is "3x3+0x0/rect".
1901
1902 @var{nb_iterations} specifies the number of times the transform is
1903 applied to the image, and defaults to 1.
1904
1905 Follow some example:
1906 @example
1907 # use the default values
1908 ocv=dilate
1909
1910 # dilate using a structuring element with a 5x5 cross, iterate two times
1911 ocv=dilate=5x5+2x2/cross:2
1912
1913 # read the shape from the file diamond.shape, iterate two times
1914 # the file diamond.shape may contain a pattern of characters like this:
1915 #   *
1916 #  ***
1917 # *****
1918 #  ***
1919 #   *
1920 # the specified cols and rows are ignored (but not the anchor point coordinates)
1921 ocv=0x0+2x2/custom=diamond.shape:2
1922 @end example
1923
1924 @subsection erode
1925
1926 Erode an image by using a specific structuring element.
1927 This filter corresponds to the libopencv function @code{cvErode}.
1928
1929 The filter accepts the parameters: @var{struct_el}:@var{nb_iterations},
1930 with the same syntax and semantics as the @ref{dilate} filter.
1931
1932 @subsection smooth
1933
1934 Smooth the input video.
1935
1936 The filter takes the following parameters:
1937 @var{type}:@var{param1}:@var{param2}:@var{param3}:@var{param4}.
1938
1939 @var{type} is the type of smooth filter to apply, and can be one of
1940 the following values: "blur", "blur_no_scale", "median", "gaussian",
1941 "bilateral". The default value is "gaussian".
1942
1943 @var{param1}, @var{param2}, @var{param3}, and @var{param4} are
1944 parameters whose meanings depend on smooth type. @var{param1} and
1945 @var{param2} accept integer positive values or 0, @var{param3} and
1946 @var{param4} accept float values.
1947
1948 The default value for @var{param1} is 3, the default value for the
1949 other parameters is 0.
1950
1951 These parameters correspond to the parameters assigned to the
1952 libopencv function @code{cvSmooth}.
1953
1954 @anchor{overlay}
1955 @section overlay
1956
1957 Overlay one video on top of another.
1958
1959 It takes two inputs and one output, the first input is the "main"
1960 video on which the second input is overlayed.
1961
1962 It accepts the parameters: @var{x}:@var{y}[:@var{options}].
1963
1964 @var{x} is the x coordinate of the overlayed video on the main video,
1965 @var{y} is the y coordinate. @var{x} and @var{y} are expressions containing
1966 the following parameters:
1967
1968 @table @option
1969 @item main_w, main_h
1970 main input width and height
1971
1972 @item W, H
1973 same as @var{main_w} and @var{main_h}
1974
1975 @item overlay_w, overlay_h
1976 overlay input width and height
1977
1978 @item w, h
1979 same as @var{overlay_w} and @var{overlay_h}
1980 @end table
1981
1982 @var{options} is an optional list of @var{key}=@var{value} pairs,
1983 separated by ":".
1984
1985 The description of the accepted options follows.
1986
1987 @table @option
1988 @item rgb
1989 If set to 1, force the filter to accept inputs in the RGB
1990 color space. Default value is 0.
1991 @end table
1992
1993 Be aware that frames are taken from each input video in timestamp
1994 order, hence, if their initial timestamps differ, it is a a good idea
1995 to pass the two inputs through a @var{setpts=PTS-STARTPTS} filter to
1996 have them begin in the same zero timestamp, as it does the example for
1997 the @var{movie} filter.
1998
1999 Follow some examples:
2000 @example
2001 # draw the overlay at 10 pixels from the bottom right
2002 # corner of the main video.
2003 overlay=main_w-overlay_w-10:main_h-overlay_h-10
2004
2005 # insert a transparent PNG logo in the bottom left corner of the input
2006 movie=logo.png [logo];
2007 [in][logo] overlay=10:main_h-overlay_h-10 [out]
2008
2009 # insert 2 different transparent PNG logos (second logo on bottom
2010 # right corner):
2011 movie=logo1.png [logo1];
2012 movie=logo2.png [logo2];
2013 [in][logo1]       overlay=10:H-h-10 [in+logo1];
2014 [in+logo1][logo2] overlay=W-w-10:H-h-10 [out]
2015
2016 # add a transparent color layer on top of the main video,
2017 # WxH specifies the size of the main input to the overlay filter
2018 color=red@.3:WxH [over]; [in][over] overlay [out]
2019 @end example
2020
2021 You can chain together more overlays but the efficiency of such
2022 approach is yet to be tested.
2023
2024 @section pad
2025
2026 Add paddings to the input image, and places the original input at the
2027 given coordinates @var{x}, @var{y}.
2028
2029 It accepts the following parameters:
2030 @var{width}:@var{height}:@var{x}:@var{y}:@var{color}.
2031
2032 The parameters @var{width}, @var{height}, @var{x}, and @var{y} are
2033 expressions containing the following constants:
2034
2035 @table @option
2036 @item in_w, in_h
2037 the input video width and height
2038
2039 @item iw, ih
2040 same as @var{in_w} and @var{in_h}
2041
2042 @item out_w, out_h
2043 the output width and height, that is the size of the padded area as
2044 specified by the @var{width} and @var{height} expressions
2045
2046 @item ow, oh
2047 same as @var{out_w} and @var{out_h}
2048
2049 @item x, y
2050 x and y offsets as specified by the @var{x} and @var{y}
2051 expressions, or NAN if not yet specified
2052
2053 @item a
2054 same as @var{iw} / @var{ih}
2055
2056 @item sar
2057 input sample aspect ratio
2058
2059 @item dar
2060 input display aspect ratio, it is the same as (@var{iw} / @var{ih}) * @var{sar}
2061
2062 @item hsub, vsub
2063 horizontal and vertical chroma subsample values. For example for the
2064 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
2065 @end table
2066
2067 Follows the description of the accepted parameters.
2068
2069 @table @option
2070 @item width, height
2071
2072 Specify the size of the output image with the paddings added. If the
2073 value for @var{width} or @var{height} is 0, the corresponding input size
2074 is used for the output.
2075
2076 The @var{width} expression can reference the value set by the
2077 @var{height} expression, and vice versa.
2078
2079 The default value of @var{width} and @var{height} is 0.
2080
2081 @item x, y
2082
2083 Specify the offsets where to place the input image in the padded area
2084 with respect to the top/left border of the output image.
2085
2086 The @var{x} expression can reference the value set by the @var{y}
2087 expression, and vice versa.
2088
2089 The default value of @var{x} and @var{y} is 0.
2090
2091 @item color
2092
2093 Specify the color of the padded area, it can be the name of a color
2094 (case insensitive match) or a 0xRRGGBB[AA] sequence.
2095
2096 The default value of @var{color} is "black".
2097
2098 @end table
2099
2100 Some examples follow:
2101
2102 @example
2103 # Add paddings with color "violet" to the input video. Output video
2104 # size is 640x480, the top-left corner of the input video is placed at
2105 # column 0, row 40.
2106 pad=640:480:0:40:violet
2107
2108 # pad the input to get an output with dimensions increased bt 3/2,
2109 # and put the input video at the center of the padded area
2110 pad="3/2*iw:3/2*ih:(ow-iw)/2:(oh-ih)/2"
2111
2112 # pad the input to get a squared output with size equal to the maximum
2113 # value between the input width and height, and put the input video at
2114 # the center of the padded area
2115 pad="max(iw\,ih):ow:(ow-iw)/2:(oh-ih)/2"
2116
2117 # pad the input to get a final w/h ratio of 16:9
2118 pad="ih*16/9:ih:(ow-iw)/2:(oh-ih)/2"
2119
2120 # for anamorphic video, in order to set the output display aspect ratio,
2121 # it is necessary to use sar in the expression, according to the relation:
2122 # (ih * X / ih) * sar = output_dar
2123 # X = output_dar / sar
2124 pad="ih*16/9/sar:ih:(ow-iw)/2:(oh-ih)/2"
2125
2126 # double output size and put the input video in the bottom-right
2127 # corner of the output padded area
2128 pad="2*iw:2*ih:ow-iw:oh-ih"
2129 @end example
2130
2131 @section pixdesctest
2132
2133 Pixel format descriptor test filter, mainly useful for internal
2134 testing. The output video should be equal to the input video.
2135
2136 For example:
2137 @example
2138 format=monow, pixdesctest
2139 @end example
2140
2141 can be used to test the monowhite pixel format descriptor definition.
2142
2143 @section scale
2144
2145 Scale the input video to @var{width}:@var{height}[:@var{interl}=@{1|-1@}] and/or convert the image format.
2146
2147 The parameters @var{width} and @var{height} are expressions containing
2148 the following constants:
2149
2150 @table @option
2151 @item in_w, in_h
2152 the input width and height
2153
2154 @item iw, ih
2155 same as @var{in_w} and @var{in_h}
2156
2157 @item out_w, out_h
2158 the output (cropped) width and height
2159
2160 @item ow, oh
2161 same as @var{out_w} and @var{out_h}
2162
2163 @item a
2164 same as @var{iw} / @var{ih}
2165
2166 @item sar
2167 input sample aspect ratio
2168
2169 @item dar
2170 input display aspect ratio, it is the same as (@var{iw} / @var{ih}) * @var{sar}
2171
2172 @item hsub, vsub
2173 horizontal and vertical chroma subsample values. For example for the
2174 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
2175 @end table
2176
2177 If the input image format is different from the format requested by
2178 the next filter, the scale filter will convert the input to the
2179 requested format.
2180
2181 If the value for @var{width} or @var{height} is 0, the respective input
2182 size is used for the output.
2183
2184 If the value for @var{width} or @var{height} is -1, the scale filter will
2185 use, for the respective output size, a value that maintains the aspect
2186 ratio of the input image.
2187
2188 The default value of @var{width} and @var{height} is 0.
2189
2190 Valid values for the optional parameter @var{interl} are:
2191
2192 @table @option
2193 @item 1
2194 force interlaced aware scaling
2195
2196 @item -1
2197 select interlaced aware scaling depending on whether the source frames
2198 are flagged as interlaced or not
2199 @end table
2200
2201 Some examples follow:
2202 @example
2203 # scale the input video to a size of 200x100.
2204 scale=200:100
2205
2206 # scale the input to 2x
2207 scale=2*iw:2*ih
2208 # the above is the same as
2209 scale=2*in_w:2*in_h
2210
2211 # scale the input to half size
2212 scale=iw/2:ih/2
2213
2214 # increase the width, and set the height to the same size
2215 scale=3/2*iw:ow
2216
2217 # seek for Greek harmony
2218 scale=iw:1/PHI*iw
2219 scale=ih*PHI:ih
2220
2221 # increase the height, and set the width to 3/2 of the height
2222 scale=3/2*oh:3/5*ih
2223
2224 # increase the size, but make the size a multiple of the chroma
2225 scale="trunc(3/2*iw/hsub)*hsub:trunc(3/2*ih/vsub)*vsub"
2226
2227 # increase the width to a maximum of 500 pixels, keep the same input aspect ratio
2228 scale='min(500\, iw*3/2):-1'
2229 @end example
2230
2231 @section select
2232 Select frames to pass in output.
2233
2234 It accepts in input an expression, which is evaluated for each input
2235 frame. If the expression is evaluated to a non-zero value, the frame
2236 is selected and passed to the output, otherwise it is discarded.
2237
2238 The expression can contain the following constants:
2239
2240 @table @option
2241 @item n
2242 the sequential number of the filtered frame, starting from 0
2243
2244 @item selected_n
2245 the sequential number of the selected frame, starting from 0
2246
2247 @item prev_selected_n
2248 the sequential number of the last selected frame, NAN if undefined
2249
2250 @item TB
2251 timebase of the input timestamps
2252
2253 @item pts
2254 the PTS (Presentation TimeStamp) of the filtered video frame,
2255 expressed in @var{TB} units, NAN if undefined
2256
2257 @item t
2258 the PTS (Presentation TimeStamp) of the filtered video frame,
2259 expressed in seconds, NAN if undefined
2260
2261 @item prev_pts
2262 the PTS of the previously filtered video frame, NAN if undefined
2263
2264 @item prev_selected_pts
2265 the PTS of the last previously filtered video frame, NAN if undefined
2266
2267 @item prev_selected_t
2268 the PTS of the last previously selected video frame, NAN if undefined
2269
2270 @item start_pts
2271 the PTS of the first video frame in the video, NAN if undefined
2272
2273 @item start_t
2274 the time of the first video frame in the video, NAN if undefined
2275
2276 @item pict_type
2277 the type of the filtered frame, can assume one of the following
2278 values:
2279 @table @option
2280 @item I
2281 @item P
2282 @item B
2283 @item S
2284 @item SI
2285 @item SP
2286 @item BI
2287 @end table
2288
2289 @item interlace_type
2290 the frame interlace type, can assume one of the following values:
2291 @table @option
2292 @item PROGRESSIVE
2293 the frame is progressive (not interlaced)
2294 @item TOPFIRST
2295 the frame is top-field-first
2296 @item BOTTOMFIRST
2297 the frame is bottom-field-first
2298 @end table
2299
2300 @item key
2301 1 if the filtered frame is a key-frame, 0 otherwise
2302
2303 @item pos
2304 the position in the file of the filtered frame, -1 if the information
2305 is not available (e.g. for synthetic video)
2306 @end table
2307
2308 The default value of the select expression is "1".
2309
2310 Some examples follow:
2311
2312 @example
2313 # select all frames in input
2314 select
2315
2316 # the above is the same as:
2317 select=1
2318
2319 # skip all frames:
2320 select=0
2321
2322 # select only I-frames
2323 select='eq(pict_type\,I)'
2324
2325 # select one frame every 100
2326 select='not(mod(n\,100))'
2327
2328 # select only frames contained in the 10-20 time interval
2329 select='gte(t\,10)*lte(t\,20)'
2330
2331 # select only I frames contained in the 10-20 time interval
2332 select='gte(t\,10)*lte(t\,20)*eq(pict_type\,I)'
2333
2334 # select frames with a minimum distance of 10 seconds
2335 select='isnan(prev_selected_t)+gte(t-prev_selected_t\,10)'
2336 @end example
2337
2338 @section setdar, setsar
2339
2340 The @code{setdar} filter sets the Display Aspect Ratio for the filter
2341 output video.
2342
2343 This is done by changing the specified Sample (aka Pixel) Aspect
2344 Ratio, according to the following equation:
2345 @example
2346 @var{DAR} = @var{HORIZONTAL_RESOLUTION} / @var{VERTICAL_RESOLUTION} * @var{SAR}
2347 @end example
2348
2349 Keep in mind that the @code{setdar} filter does not modify the pixel
2350 dimensions of the video frame. Also the display aspect ratio set by
2351 this filter may be changed by later filters in the filterchain,
2352 e.g. in case of scaling or if another "setdar" or a "setsar" filter is
2353 applied.
2354
2355 The @code{setsar} filter sets the Sample (aka Pixel) Aspect Ratio for
2356 the filter output video.
2357
2358 Note that as a consequence of the application of this filter, the
2359 output display aspect ratio will change according to the equation
2360 above.
2361
2362 Keep in mind that the sample aspect ratio set by the @code{setsar}
2363 filter may be changed by later filters in the filterchain, e.g. if
2364 another "setsar" or a "setdar" filter is applied.
2365
2366 The @code{setdar} and @code{setsar} filters accept a parameter string
2367 which represents the wanted aspect ratio.  The parameter can
2368 be a floating point number string, an expression, or a string of the form
2369 @var{num}:@var{den}, where @var{num} and @var{den} are the numerator
2370 and denominator of the aspect ratio. If the parameter is not
2371 specified, it is assumed the value "0:1".
2372
2373 For example to change the display aspect ratio to 16:9, specify:
2374 @example
2375 setdar=16:9
2376 @end example
2377
2378 The example above is equivalent to:
2379 @example
2380 setdar=1.77777
2381 @end example
2382
2383 To change the sample aspect ratio to 10:11, specify:
2384 @example
2385 setsar=10:11
2386 @end example
2387
2388 @section setfield
2389
2390 Force field for the output video frame.
2391
2392 The @code{setfield} filter marks the interlace type field for the
2393 output frames. It does not change the input frame, but only sets the
2394 corresponding property, which affects how the frame is treated by
2395 followig filters (e.g. @code{fieldorder} or @code{yadif}).
2396
2397 It accepts a parameter representing an integer or a string, which can
2398 assume the following values:
2399 @table @samp
2400 @item -1, auto
2401 Keep the same field property.
2402
2403 @item 0, bff
2404 Mark the frame as bottom-field-first.
2405
2406 @item 1, tff
2407 Mark the frame as top-field-first.
2408 @end table
2409
2410 @section setpts
2411
2412 Change the PTS (presentation timestamp) of the input video frames.
2413
2414 Accept in input an expression evaluated through the eval API, which
2415 can contain the following constants:
2416
2417 @table @option
2418 @item PTS
2419 the presentation timestamp in input
2420
2421 @item N
2422 the count of the input frame, starting from 0.
2423
2424 @item STARTPTS
2425 the PTS of the first video frame
2426
2427 @item INTERLACED
2428 tell if the current frame is interlaced
2429
2430 @item POS
2431 original position in the file of the frame, or undefined if undefined
2432 for the current frame
2433
2434 @item PREV_INPTS
2435 previous input PTS
2436
2437 @item PREV_OUTPTS
2438 previous output PTS
2439
2440 @end table
2441
2442 Some examples follow:
2443
2444 @example
2445 # start counting PTS from zero
2446 setpts=PTS-STARTPTS
2447
2448 # fast motion
2449 setpts=0.5*PTS
2450
2451 # slow motion
2452 setpts=2.0*PTS
2453
2454 # fixed rate 25 fps
2455 setpts=N/(25*TB)
2456
2457 # fixed rate 25 fps with some jitter
2458 setpts='1/(25*TB) * (N + 0.05 * sin(N*2*PI/25))'
2459 @end example
2460
2461 @section settb
2462
2463 Set the timebase to use for the output frames timestamps.
2464 It is mainly useful for testing timebase configuration.
2465
2466 It accepts in input an arithmetic expression representing a rational.
2467 The expression can contain the constants "AVTB" (the
2468 default timebase), and "intb" (the input timebase).
2469
2470 The default value for the input is "intb".
2471
2472 Follow some examples.
2473
2474 @example
2475 # set the timebase to 1/25
2476 settb=1/25
2477
2478 # set the timebase to 1/10
2479 settb=0.1
2480
2481 #set the timebase to 1001/1000
2482 settb=1+0.001
2483
2484 #set the timebase to 2*intb
2485 settb=2*intb
2486
2487 #set the default timebase value
2488 settb=AVTB
2489 @end example
2490
2491 @section showinfo
2492
2493 Show a line containing various information for each input video frame.
2494 The input video is not modified.
2495
2496 The shown line contains a sequence of key/value pairs of the form
2497 @var{key}:@var{value}.
2498
2499 A description of each shown parameter follows:
2500
2501 @table @option
2502 @item n
2503 sequential number of the input frame, starting from 0
2504
2505 @item pts
2506 Presentation TimeStamp of the input frame, expressed as a number of
2507 time base units. The time base unit depends on the filter input pad.
2508
2509 @item pts_time
2510 Presentation TimeStamp of the input frame, expressed as a number of
2511 seconds
2512
2513 @item pos
2514 position of the frame in the input stream, -1 if this information in
2515 unavailable and/or meaningless (for example in case of synthetic video)
2516
2517 @item fmt
2518 pixel format name
2519
2520 @item sar
2521 sample aspect ratio of the input frame, expressed in the form
2522 @var{num}/@var{den}
2523
2524 @item s
2525 size of the input frame, expressed in the form
2526 @var{width}x@var{height}
2527
2528 @item i
2529 interlaced mode ("P" for "progressive", "T" for top field first, "B"
2530 for bottom field first)
2531
2532 @item iskey
2533 1 if the frame is a key frame, 0 otherwise
2534
2535 @item type
2536 picture type of the input frame ("I" for an I-frame, "P" for a
2537 P-frame, "B" for a B-frame, "?" for unknown type).
2538 Check also the documentation of the @code{AVPictureType} enum and of
2539 the @code{av_get_picture_type_char} function defined in
2540 @file{libavutil/avutil.h}.
2541
2542 @item checksum
2543 Adler-32 checksum (printed in hexadecimal) of all the planes of the input frame
2544
2545 @item plane_checksum
2546 Adler-32 checksum (printed in hexadecimal) of each plane of the input frame,
2547 expressed in the form "[@var{c0} @var{c1} @var{c2} @var{c3}]"
2548 @end table
2549
2550 @section slicify
2551
2552 Pass the images of input video on to next video filter as multiple
2553 slices.
2554
2555 @example
2556 ffmpeg -i in.avi -vf "slicify=32" out.avi
2557 @end example
2558
2559 The filter accepts the slice height as parameter. If the parameter is
2560 not specified it will use the default value of 16.
2561
2562 Adding this in the beginning of filter chains should make filtering
2563 faster due to better use of the memory cache.
2564
2565 @section split
2566
2567 Pass on the input video to two outputs. Both outputs are identical to
2568 the input video.
2569
2570 For example:
2571 @example
2572 [in] split [splitout1][splitout2];
2573 [splitout1] crop=100:100:0:0    [cropout];
2574 [splitout2] pad=200:200:100:100 [padout];
2575 @end example
2576
2577 will create two separate outputs from the same input, one cropped and
2578 one padded.
2579
2580 @section thumbnail
2581 Select the most representative frame in a given sequence of consecutive frames.
2582
2583 It accepts as argument the frames batch size to analyze (default @var{N}=100);
2584 in a set of @var{N} frames, the filter will pick one of them, and then handle
2585 the next batch of @var{N} frames until the end.
2586
2587 Since the filter keeps track of the whole frames sequence, a bigger @var{N}
2588 value will result in a higher memory usage, so a high value is not recommended.
2589
2590 The following example extract one picture each 50 frames:
2591 @example
2592 thumbnail=50
2593 @end example
2594
2595 Complete example of a thumbnail creation with @command{ffmpeg}:
2596 @example
2597 ffmpeg -i in.avi -vf thumbnail,scale=300:200 -frames:v 1 out.png
2598 @end example
2599
2600 @section tinterlace
2601
2602 Perform various types of temporal field interlacing.
2603
2604 Frames are counted starting from 1, so the first input frame is
2605 considered odd.
2606
2607 This filter accepts a single parameter specifying the mode. Available
2608 modes are:
2609
2610 @table @samp
2611 @item 0
2612 Move odd frames into the upper field, even into the lower field,
2613 generating a double height frame at half framerate.
2614
2615 @item 1
2616 Only output even frames, odd frames are dropped, generating a frame with
2617 unchanged height at half framerate.
2618
2619 @item 2
2620 Only output odd frames, even frames are dropped, generating a frame with
2621 unchanged height at half framerate.
2622
2623 @item 3
2624 Expand each frame to full height, but pad alternate lines with black,
2625 generating a frame with double height at the same input framerate.
2626
2627 @item 4
2628 Interleave the upper field from odd frames with the lower field from
2629 even frames, generating a frame with unchanged height at half framerate.
2630
2631 @item 5
2632 Interleave the lower field from odd frames with the upper field from
2633 even frames, generating a frame with unchanged height at half framerate.
2634 @end table
2635
2636 Default mode is 0.
2637
2638 @section transpose
2639
2640 Transpose rows with columns in the input video and optionally flip it.
2641
2642 It accepts a parameter representing an integer, which can assume the
2643 values:
2644
2645 @table @samp
2646 @item 0
2647 Rotate by 90 degrees counterclockwise and vertically flip (default), that is:
2648 @example
2649 L.R     L.l
2650 . . ->  . .
2651 l.r     R.r
2652 @end example
2653
2654 @item 1
2655 Rotate by 90 degrees clockwise, that is:
2656 @example
2657 L.R     l.L
2658 . . ->  . .
2659 l.r     r.R
2660 @end example
2661
2662 @item 2
2663 Rotate by 90 degrees counterclockwise, that is:
2664 @example
2665 L.R     R.r
2666 . . ->  . .
2667 l.r     L.l
2668 @end example
2669
2670 @item 3
2671 Rotate by 90 degrees clockwise and vertically flip, that is:
2672 @example
2673 L.R     r.R
2674 . . ->  . .
2675 l.r     l.L
2676 @end example
2677 @end table
2678
2679 @section unsharp
2680
2681 Sharpen or blur the input video.
2682
2683 It accepts the following parameters:
2684 @var{luma_msize_x}:@var{luma_msize_y}:@var{luma_amount}:@var{chroma_msize_x}:@var{chroma_msize_y}:@var{chroma_amount}
2685
2686 Negative values for the amount will blur the input video, while positive
2687 values will sharpen. All parameters are optional and default to the
2688 equivalent of the string '5:5:1.0:5:5:0.0'.
2689
2690 @table @option
2691
2692 @item luma_msize_x
2693 Set the luma matrix horizontal size. It can be an integer between 3
2694 and 13, default value is 5.
2695
2696 @item luma_msize_y
2697 Set the luma matrix vertical size. It can be an integer between 3
2698 and 13, default value is 5.
2699
2700 @item luma_amount
2701 Set the luma effect strength. It can be a float number between -2.0
2702 and 5.0, default value is 1.0.
2703
2704 @item chroma_msize_x
2705 Set the chroma matrix horizontal size. It can be an integer between 3
2706 and 13, default value is 5.
2707
2708 @item chroma_msize_y
2709 Set the chroma matrix vertical size. It can be an integer between 3
2710 and 13, default value is 5.
2711
2712 @item chroma_amount
2713 Set the chroma effect strength. It can be a float number between -2.0
2714 and 5.0, default value is 0.0.
2715
2716 @end table
2717
2718 @example
2719 # Strong luma sharpen effect parameters
2720 unsharp=7:7:2.5
2721
2722 # Strong blur of both luma and chroma parameters
2723 unsharp=7:7:-2:7:7:-2
2724
2725 # Use the default values with @command{ffmpeg}
2726 ffmpeg -i in.avi -vf "unsharp" out.mp4
2727 @end example
2728
2729 @section vflip
2730
2731 Flip the input video vertically.
2732
2733 @example
2734 ffmpeg -i in.avi -vf "vflip" out.avi
2735 @end example
2736
2737 @section yadif
2738
2739 Deinterlace the input video ("yadif" means "yet another deinterlacing
2740 filter").
2741
2742 It accepts the optional parameters: @var{mode}:@var{parity}:@var{auto}.
2743
2744 @var{mode} specifies the interlacing mode to adopt, accepts one of the
2745 following values:
2746
2747 @table @option
2748 @item 0
2749 output 1 frame for each frame
2750 @item 1
2751 output 1 frame for each field
2752 @item 2
2753 like 0 but skips spatial interlacing check
2754 @item 3
2755 like 1 but skips spatial interlacing check
2756 @end table
2757
2758 Default value is 0.
2759
2760 @var{parity} specifies the picture field parity assumed for the input
2761 interlaced video, accepts one of the following values:
2762
2763 @table @option
2764 @item 0
2765 assume top field first
2766 @item 1
2767 assume bottom field first
2768 @item -1
2769 enable automatic detection
2770 @end table
2771
2772 Default value is -1.
2773 If interlacing is unknown or decoder does not export this information,
2774 top field first will be assumed.
2775
2776 @var{auto} specifies if deinterlacer should trust the interlaced flag
2777 and only deinterlace frames marked as interlaced
2778
2779 @table @option
2780 @item 0
2781 deinterlace all frames
2782 @item 1
2783 only deinterlace frames marked as interlaced
2784 @end table
2785
2786 Default value is 0.
2787
2788 @c man end VIDEO FILTERS
2789
2790 @chapter Video Sources
2791 @c man begin VIDEO SOURCES
2792
2793 Below is a description of the currently available video sources.
2794
2795 @section buffer
2796
2797 Buffer video frames, and make them available to the filter chain.
2798
2799 This source is mainly intended for a programmatic use, in particular
2800 through the interface defined in @file{libavfilter/vsrc_buffer.h}.
2801
2802 It accepts the following parameters:
2803 @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}
2804
2805 All the parameters but @var{scale_params} need to be explicitly
2806 defined.
2807
2808 Follows the list of the accepted parameters.
2809
2810 @table @option
2811
2812 @item width, height
2813 Specify the width and height of the buffered video frames.
2814
2815 @item pix_fmt_string
2816 A string representing the pixel format of the buffered video frames.
2817 It may be a number corresponding to a pixel format, or a pixel format
2818 name.
2819
2820 @item timebase_num, timebase_den
2821 Specify numerator and denomitor of the timebase assumed by the
2822 timestamps of the buffered frames.
2823
2824 @item sample_aspect_ratio.num, sample_aspect_ratio.den
2825 Specify numerator and denominator of the sample aspect ratio assumed
2826 by the video frames.
2827
2828 @item scale_params
2829 Specify the optional parameters to be used for the scale filter which
2830 is automatically inserted when an input change is detected in the
2831 input size or format.
2832 @end table
2833
2834 For example:
2835 @example
2836 buffer=320:240:yuv410p:1:24:1:1
2837 @end example
2838
2839 will instruct the source to accept video frames with size 320x240 and
2840 with format "yuv410p", assuming 1/24 as the timestamps timebase and
2841 square pixels (1:1 sample aspect ratio).
2842 Since the pixel format with name "yuv410p" corresponds to the number 6
2843 (check the enum PixelFormat definition in @file{libavutil/pixfmt.h}),
2844 this example corresponds to:
2845 @example
2846 buffer=320:240:6:1:24:1:1
2847 @end example
2848
2849 @section cellauto
2850
2851 Create a pattern generated by an elementary cellular automaton.
2852
2853 The initial state of the cellular automaton can be defined through the
2854 @option{filename}, and @option{pattern} options. If such options are
2855 not specified an initial state is created randomly.
2856
2857 At each new frame a new row in the video is filled with the result of
2858 the cellular automaton next generation. The behavior when the whole
2859 frame is filled is defined by the @option{scroll} option.
2860
2861 This source accepts a list of options in the form of
2862 @var{key}=@var{value} pairs separated by ":". A description of the
2863 accepted options follows.
2864
2865 @table @option
2866 @item filename, f
2867 Read the initial cellular automaton state, i.e. the starting row, from
2868 the specified file.
2869 In the file, each non-whitespace character is considered an alive
2870 cell, a newline will terminate the row, and further characters in the
2871 file will be ignored.
2872
2873 @item pattern, p
2874 Read the initial cellular automaton state, i.e. the starting row, from
2875 the specified string.
2876
2877 Each non-whitespace character in the string is considered an alive
2878 cell, a newline will terminate the row, and further characters in the
2879 string will be ignored.
2880
2881 @item rate, r
2882 Set the video rate, that is the number of frames generated per second.
2883 Default is 25.
2884
2885 @item random_fill_ratio, ratio
2886 Set the random fill ratio for the initial cellular automaton row. It
2887 is a floating point number value ranging from 0 to 1, defaults to
2888 1/PHI.
2889
2890 This option is ignored when a file or a pattern is specified.
2891
2892 @item random_seed, seed
2893 Set the seed for filling randomly the initial row, must be an integer
2894 included between 0 and UINT32_MAX. If not specified, or if explicitly
2895 set to -1, the filter will try to use a good random seed on a best
2896 effort basis.
2897
2898 @item rule
2899 Set the cellular automaton rule, it is a number ranging from 0 to 255.
2900 Default value is 110.
2901
2902 @item size, s
2903 Set the size of the output video.
2904
2905 If @option{filename} or @option{pattern} is specified, the size is set
2906 by default to the width of the specified initial state row, and the
2907 height is set to @var{width} * PHI.
2908
2909 If @option{size} is set, it must contain the width of the specified
2910 pattern string, and the specified pattern will be centered in the
2911 larger row.
2912
2913 If a filename or a pattern string is not specified, the size value
2914 defaults to "320x518" (used for a randomly generated initial state).
2915
2916 @item scroll
2917 If set to 1, scroll the output upward when all the rows in the output
2918 have been already filled. If set to 0, the new generated row will be
2919 written over the top row just after the bottom row is filled.
2920 Defaults to 1.
2921
2922 @item start_full, full
2923 If set to 1, completely fill the output with generated rows before
2924 outputting the first frame.
2925 This is the default behavior, for disabling set the value to 0.
2926
2927 @item stitch
2928 If set to 1, stitch the left and right row edges together.
2929 This is the default behavior, for disabling set the value to 0.
2930 @end table
2931
2932 @subsection Examples
2933
2934 @itemize
2935 @item
2936 Read the initial state from @file{pattern}, and specify an output of
2937 size 200x400.
2938 @example
2939 cellauto=f=pattern:s=200x400
2940 @end example
2941
2942 @item
2943 Generate a random initial row with a width of 200 cells, with a fill
2944 ratio of 2/3:
2945 @example
2946 cellauto=ratio=2/3:s=200x200
2947 @end example
2948
2949 @item
2950 Create a pattern generated by rule 18 starting by a single alive cell
2951 centered on an initial row with width 100:
2952 @example
2953 cellauto=p=@@:s=100x400:full=0:rule=18
2954 @end example
2955
2956 @item
2957 Specify a more elaborated initial pattern:
2958 @example
2959 cellauto=p='@@@@ @@ @@@@':s=100x400:full=0:rule=18
2960 @end example
2961
2962 @end itemize
2963
2964 @section color
2965
2966 Provide an uniformly colored input.
2967
2968 It accepts the following parameters:
2969 @var{color}:@var{frame_size}:@var{frame_rate}
2970
2971 Follows the description of the accepted parameters.
2972
2973 @table @option
2974
2975 @item color
2976 Specify the color of the source. It can be the name of a color (case
2977 insensitive match) or a 0xRRGGBB[AA] sequence, possibly followed by an
2978 alpha specifier. The default value is "black".
2979
2980 @item frame_size
2981 Specify the size of the sourced video, it may be a string of the form
2982 @var{width}x@var{height}, or the name of a size abbreviation. The
2983 default value is "320x240".
2984
2985 @item frame_rate
2986 Specify the frame rate of the sourced video, as the number of frames
2987 generated per second. It has to be a string in the format
2988 @var{frame_rate_num}/@var{frame_rate_den}, an integer number, a float
2989 number or a valid video frame rate abbreviation. The default value is
2990 "25".
2991
2992 @end table
2993
2994 For example the following graph description will generate a red source
2995 with an opacity of 0.2, with size "qcif" and a frame rate of 10
2996 frames per second, which will be overlayed over the source connected
2997 to the pad with identifier "in".
2998
2999 @example
3000 "color=red@@0.2:qcif:10 [color]; [in][color] overlay [out]"
3001 @end example
3002
3003 @section movie
3004
3005 Read a video stream from a movie container.
3006
3007 It accepts the syntax: @var{movie_name}[:@var{options}] where
3008 @var{movie_name} is the name of the resource to read (not necessarily
3009 a file but also a device or a stream accessed through some protocol),
3010 and @var{options} is an optional sequence of @var{key}=@var{value}
3011 pairs, separated by ":".
3012
3013 The description of the accepted options follows.
3014
3015 @table @option
3016
3017 @item format_name, f
3018 Specifies the format assumed for the movie to read, and can be either
3019 the name of a container or an input device. If not specified the
3020 format is guessed from @var{movie_name} or by probing.
3021
3022 @item seek_point, sp
3023 Specifies the seek point in seconds, the frames will be output
3024 starting from this seek point, the parameter is evaluated with
3025 @code{av_strtod} so the numerical value may be suffixed by an IS
3026 postfix. Default value is "0".
3027
3028 @item stream_index, si
3029 Specifies the index of the video stream to read. If the value is -1,
3030 the best suited video stream will be automatically selected. Default
3031 value is "-1".
3032
3033 @end table
3034
3035 This filter allows to overlay a second video on top of main input of
3036 a filtergraph as shown in this graph:
3037 @example
3038 input -----------> deltapts0 --> overlay --> output
3039                                     ^
3040                                     |
3041 movie --> scale--> deltapts1 -------+
3042 @end example
3043
3044 Some examples follow:
3045 @example
3046 # skip 3.2 seconds from the start of the avi file in.avi, and overlay it
3047 # on top of the input labelled as "in".
3048 movie=in.avi:seek_point=3.2, scale=180:-1, setpts=PTS-STARTPTS [movie];
3049 [in] setpts=PTS-STARTPTS, [movie] overlay=16:16 [out]
3050
3051 # read from a video4linux2 device, and overlay it on top of the input
3052 # labelled as "in"
3053 movie=/dev/video0:f=video4linux2, scale=180:-1, setpts=PTS-STARTPTS [movie];
3054 [in] setpts=PTS-STARTPTS, [movie] overlay=16:16 [out]
3055
3056 @end example
3057
3058 @section mptestsrc
3059
3060 Generate various test patterns, as generated by the MPlayer test filter.
3061
3062 The size of the generated video is fixed, and is 256x256.
3063 This source is useful in particular for testing encoding features.
3064
3065 This source accepts an optional sequence of @var{key}=@var{value} pairs,
3066 separated by ":". The description of the accepted options follows.
3067
3068 @table @option
3069
3070 @item rate, r
3071 Specify the frame rate of the sourced video, as the number of frames
3072 generated per second. It has to be a string in the format
3073 @var{frame_rate_num}/@var{frame_rate_den}, an integer number, a float
3074 number or a valid video frame rate abbreviation. The default value is
3075 "25".
3076
3077 @item duration, d
3078 Set the video duration of the sourced video. The accepted syntax is:
3079 @example
3080 [-]HH[:MM[:SS[.m...]]]
3081 [-]S+[.m...]
3082 @end example
3083 See also the function @code{av_parse_time()}.
3084
3085 If not specified, or the expressed duration is negative, the video is
3086 supposed to be generated forever.
3087
3088 @item test, t
3089
3090 Set the number or the name of the test to perform. Supported tests are:
3091 @table @option
3092 @item dc_luma
3093 @item dc_chroma
3094 @item freq_luma
3095 @item freq_chroma
3096 @item amp_luma
3097 @item amp_chroma
3098 @item cbp
3099 @item mv
3100 @item ring1
3101 @item ring2
3102 @item all
3103 @end table
3104
3105 Default value is "all", which will cycle through the list of all tests.
3106 @end table
3107
3108 For example the following:
3109 @example
3110 testsrc=t=dc_luma
3111 @end example
3112
3113 will generate a "dc_luma" test pattern.
3114
3115 @section frei0r_src
3116
3117 Provide a frei0r source.
3118
3119 To enable compilation of this filter you need to install the frei0r
3120 header and configure FFmpeg with @code{--enable-frei0r}.
3121
3122 The source supports the syntax:
3123 @example
3124 @var{size}:@var{rate}:@var{src_name}[@{=|:@}@var{param1}:@var{param2}:...:@var{paramN}]
3125 @end example
3126
3127 @var{size} is the size of the video to generate, may be a string of the
3128 form @var{width}x@var{height} or a frame size abbreviation.
3129 @var{rate} is the rate of the video to generate, may be a string of
3130 the form @var{num}/@var{den} or a frame rate abbreviation.
3131 @var{src_name} is the name to the frei0r source to load. For more
3132 information regarding frei0r and how to set the parameters read the
3133 section @ref{frei0r} in the description of the video filters.
3134
3135 Some examples follow:
3136 @example
3137 # generate a frei0r partik0l source with size 200x200 and frame rate 10
3138 # which is overlayed on the overlay filter main input
3139 frei0r_src=200x200:10:partik0l=1234 [overlay]; [in][overlay] overlay
3140 @end example
3141
3142 @section life
3143
3144 Generate a life pattern.
3145
3146 This source is based on a generalization of John Conway's life game.
3147
3148 The sourced input represents a life grid, each pixel represents a cell
3149 which can be in one of two possible states, alive or dead. Every cell
3150 interacts with its eight neighbours, which are the cells that are
3151 horizontally, vertically, or diagonally adjacent.
3152
3153 At each interaction the grid evolves according to the adopted rule,
3154 which specifies the number of neighbor alive cells which will make a
3155 cell stay alive or born. The @option{rule} option allows to specify
3156 the rule to adopt.
3157
3158 This source accepts a list of options in the form of
3159 @var{key}=@var{value} pairs separated by ":". A description of the
3160 accepted options follows.
3161
3162 @table @option
3163 @item filename, f
3164 Set the file from which to read the initial grid state. In the file,
3165 each non-whitespace character is considered an alive cell, and newline
3166 is used to delimit the end of each row.
3167
3168 If this option is not specified, the initial grid is generated
3169 randomly.
3170
3171 @item rate, r
3172 Set the video rate, that is the number of frames generated per second.
3173 Default is 25.
3174
3175 @item random_fill_ratio, ratio
3176 Set the random fill ratio for the initial random grid. It is a
3177 floating point number value ranging from 0 to 1, defaults to 1/PHI.
3178 It is ignored when a file is specified.
3179
3180 @item random_seed, seed
3181 Set the seed for filling the initial random grid, must be an integer
3182 included between 0 and UINT32_MAX. If not specified, or if explicitly
3183 set to -1, the filter will try to use a good random seed on a best
3184 effort basis.
3185
3186 @item rule
3187 Set the life rule.
3188
3189 A rule can be specified with a code of the kind "S@var{NS}/B@var{NB}",
3190 where @var{NS} and @var{NB} are sequences of numbers in the range 0-8,
3191 @var{NS} specifies the number of alive neighbor cells which make a
3192 live cell stay alive, and @var{NB} the number of alive neighbor cells
3193 which make a dead cell to become alive (i.e. to "born").
3194 "s" and "b" can be used in place of "S" and "B", respectively.
3195
3196 Alternatively a rule can be specified by an 18-bits integer. The 9
3197 high order bits are used to encode the next cell state if it is alive
3198 for each number of neighbor alive cells, the low order bits specify
3199 the rule for "borning" new cells. Higher order bits encode for an
3200 higher number of neighbor cells.
3201 For example the number 6153 = @code{(12<<9)+9} specifies a stay alive
3202 rule of 12 and a born rule of 9, which corresponds to "S23/B03".
3203
3204 Default value is "S23/B3", which is the original Conway's game of life
3205 rule, and will keep a cell alive if it has 2 or 3 neighbor alive
3206 cells, and will born a new cell if there are three alive cells around
3207 a dead cell.
3208
3209 @item size, s
3210 Set the size of the output video.
3211
3212 If @option{filename} is specified, the size is set by default to the
3213 same size of the input file. If @option{size} is set, it must contain
3214 the size specified in the input file, and the initial grid defined in
3215 that file is centered in the larger resulting area.
3216
3217 If a filename is not specified, the size value defaults to "320x240"
3218 (used for a randomly generated initial grid).
3219
3220 @item stitch
3221 If set to 1, stitch the left and right grid edges together, and the
3222 top and bottom edges also. Defaults to 1.
3223
3224 @item mold
3225 Set cell mold speed. If set, a dead cell will go from @option{death_color} to
3226 @option{mold_color} with a step of @option{mold}. @option{mold} can have a
3227 value from 0 to 255.
3228
3229 @item life_color
3230 Set the color of living (or new born) cells.
3231
3232 @item death_color
3233 Set the color of dead cells. If @option{mold} is set, this is the first color
3234 used to represent a dead cell.
3235
3236 @item mold_color
3237 Set mold color, for definitely dead and moldy cells.
3238 @end table
3239
3240 @subsection Examples
3241
3242 @itemize
3243 @item
3244 Read a grid from @file{pattern}, and center it on a grid of size
3245 300x300 pixels:
3246 @example
3247 life=f=pattern:s=300x300
3248 @end example
3249
3250 @item
3251 Generate a random grid of size 200x200, with a fill ratio of 2/3:
3252 @example
3253 life=ratio=2/3:s=200x200
3254 @end example
3255
3256 @item
3257 Specify a custom rule for evolving a randomly generated grid:
3258 @example
3259 life=rule=S14/B34
3260 @end example
3261
3262 @item
3263 Full example with slow death effect (mold) using @command{ffplay}:
3264 @example
3265 ffplay -f lavfi life=s=300x200:mold=10:r=60:ratio=0.1:death_color=#C83232:life_color=#00ff00,scale=1200:800:flags=16
3266 @end example
3267 @end itemize
3268
3269 @section nullsrc, rgbtestsrc, testsrc
3270
3271 The @code{nullsrc} source returns unprocessed video frames. It is
3272 mainly useful to be employed in analysis / debugging tools, or as the
3273 source for filters which ignore the input data.
3274
3275 The @code{rgbtestsrc} source generates an RGB test pattern useful for
3276 detecting RGB vs BGR issues. You should see a red, green and blue
3277 stripe from top to bottom.
3278
3279 The @code{testsrc} source generates a test video pattern, showing a
3280 color pattern, a scrolling gradient and a timestamp. This is mainly
3281 intended for testing purposes.
3282
3283 These sources accept an optional sequence of @var{key}=@var{value} pairs,
3284 separated by ":". The description of the accepted options follows.
3285
3286 @table @option
3287
3288 @item size, s
3289 Specify the size of the sourced video, it may be a string of the form
3290 @var{width}x@var{height}, or the name of a size abbreviation. The
3291 default value is "320x240".
3292
3293 @item rate, r
3294 Specify the frame rate of the sourced video, as the number of frames
3295 generated per second. It has to be a string in the format
3296 @var{frame_rate_num}/@var{frame_rate_den}, an integer number, a float
3297 number or a valid video frame rate abbreviation. The default value is
3298 "25".
3299
3300 @item sar
3301 Set the sample aspect ratio of the sourced video.
3302
3303 @item duration, d
3304 Set the video duration of the sourced video. The accepted syntax is:
3305 @example
3306 [-]HH[:MM[:SS[.m...]]]
3307 [-]S+[.m...]
3308 @end example
3309 See also the function @code{av_parse_time()}.
3310
3311 If not specified, or the expressed duration is negative, the video is
3312 supposed to be generated forever.
3313
3314 @item decimals, n
3315 Set the number of decimals to show in the timestamp, only used in the
3316 @code{testsrc} source.
3317
3318 The displayed timestamp value will correspond to the original
3319 timestamp value multiplied by the power of 10 of the specified
3320 value. Default value is 0.
3321 @end table
3322
3323 For example the following:
3324 @example
3325 testsrc=duration=5.3:size=qcif:rate=10
3326 @end example
3327
3328 will generate a video with a duration of 5.3 seconds, with size
3329 176x144 and a frame rate of 10 frames per second.
3330
3331 If the input content is to be ignored, @code{nullsrc} can be used. The
3332 following command generates noise in the luminance plane by employing
3333 the @code{mp=geq} filter:
3334 @example
3335 nullsrc=s=256x256, mp=geq=random(1)*255:128:128
3336 @end example
3337
3338 @c man end VIDEO SOURCES
3339
3340 @chapter Video Sinks
3341 @c man begin VIDEO SINKS
3342
3343 Below is a description of the currently available video sinks.
3344
3345 @section buffersink
3346
3347 Buffer video frames, and make them available to the end of the filter
3348 graph.
3349
3350 This sink is mainly intended for a programmatic use, in particular
3351 through the interface defined in @file{libavfilter/buffersink.h}.
3352
3353 It does not require a string parameter in input, but you need to
3354 specify a pointer to a list of supported pixel formats terminated by
3355 -1 in the opaque parameter provided to @code{avfilter_init_filter}
3356 when initializing this sink.
3357
3358 @section nullsink
3359
3360 Null video sink, do absolutely nothing with the input video. It is
3361 mainly useful as a template and to be employed in analysis / debugging
3362 tools.
3363
3364 @c man end VIDEO SINKS