doc/filters.texi: prefer @example over the unsupported @math for showing equation
[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 @item the number of output channels is supported by libswresample (16 at the
388       moment)
389 @c if SWR_CH_MAX changes, fix the line above.
390 @end itemize
391
392 If all these conditions are satisfied, the filter will notify the user ("Pure
393 channel mapping detected"), and use an optimized and lossless method to do the
394 remapping.
395
396 For example, if you have a 5.1 source and want a stereo audio stream by
397 dropping the extra channels:
398 @example
399 pan="stereo: c0=FL : c1=FR"
400 @end example
401
402 Given the same source, you can also switch front left and front right channels
403 and keep the input channel layout:
404 @example
405 pan="5.1: c0=c1 : c1=c0 : c2=c2 : c3=c3 : c4=c4 : c5=c5"
406 @end example
407
408 If the input is a stereo audio stream, you can mute the front left channel (and
409 still keep the stereo channel layout) with:
410 @example
411 pan="stereo:c1=c1"
412 @end example
413
414 Still with a stereo audio stream input, you can copy the right channel in both
415 front left and right:
416 @example
417 pan="stereo: c0=FR : c1=FR"
418 @end example
419
420 @section silencedetect
421
422 Detect silence in an audio stream.
423
424 This filter logs a message when it detects that the input audio volume is less
425 or equal to a noise tolerance value for a duration greater or equal to the
426 minimum detected noise duration.
427
428 The printed times and duration are expressed in seconds.
429
430 @table @option
431 @item duration, d
432 Set silence duration until notification (default is 2 seconds).
433
434 @item noise, n
435 Set noise tolerance. Can be specified in dB (in case "dB" is appended to the
436 specified value) or amplitude ratio. Default is -60dB, or 0.001.
437 @end table
438
439 Detect 5 seconds of silence with -50dB noise tolerance:
440 @example
441 silencedetect=n=-50dB:d=5
442 @end example
443
444 Complete example with @command{ffmpeg} to detect silence with 0.0001 noise
445 tolerance in @file{silence.mp3}:
446 @example
447 ffmpeg -f lavfi -i amovie=silence.mp3,silencedetect=noise=0.0001 -f null -
448 @end example
449
450 @section volume
451
452 Adjust the input audio volume.
453
454 The filter accepts exactly one parameter @var{vol}, which expresses
455 how the audio volume will be increased or decreased.
456
457 Output values are clipped to the maximum value.
458
459 If @var{vol} is expressed as a decimal number, the output audio
460 volume is given by the relation:
461 @example
462 @var{output_volume} = @var{vol} * @var{input_volume}
463 @end example
464
465 If @var{vol} is expressed as a decimal number followed by the string
466 "dB", the value represents the requested change in decibels of the
467 input audio power, and the output audio volume is given by the
468 relation:
469 @example
470 @var{output_volume} = 10^(@var{vol}/20) * @var{input_volume}
471 @end example
472
473 Otherwise @var{vol} is considered an expression and its evaluated
474 value is used for computing the output audio volume according to the
475 first relation.
476
477 Default value for @var{vol} is 1.0.
478
479 @subsection Examples
480
481 @itemize
482 @item
483 Half the input audio volume:
484 @example
485 volume=0.5
486 @end example
487
488 The above example is equivalent to:
489 @example
490 volume=1/2
491 @end example
492
493 @item
494 Decrease input audio power by 12 decibels:
495 @example
496 volume=-12dB
497 @end example
498 @end itemize
499
500 @c man end AUDIO FILTERS
501
502 @chapter Audio Sources
503 @c man begin AUDIO SOURCES
504
505 Below is a description of the currently available audio sources.
506
507 @section abuffer
508
509 Buffer audio frames, and make them available to the filter chain.
510
511 This source is mainly intended for a programmatic use, in particular
512 through the interface defined in @file{libavfilter/asrc_abuffer.h}.
513
514 It accepts the following mandatory parameters:
515 @var{sample_rate}:@var{sample_fmt}:@var{channel_layout}:@var{packing}
516
517 @table @option
518
519 @item sample_rate
520 The sample rate of the incoming audio buffers.
521
522 @item sample_fmt
523 The sample format of the incoming audio buffers.
524 Either a sample format name or its corresponging integer representation from
525 the enum AVSampleFormat in @file{libavutil/samplefmt.h}
526
527 @item channel_layout
528 The channel layout of the incoming audio buffers.
529 Either a channel layout name from channel_layout_map in
530 @file{libavutil/audioconvert.c} or its corresponding integer representation
531 from the AV_CH_LAYOUT_* macros in @file{libavutil/audioconvert.h}
532
533 @item packing
534 Either "packed" or "planar", or their integer representation: 0 or 1
535 respectively.
536
537 @end table
538
539 For example:
540 @example
541 abuffer=44100:s16:stereo:planar
542 @end example
543
544 will instruct the source to accept planar 16bit signed stereo at 44100Hz.
545 Since the sample format with name "s16" corresponds to the number
546 1 and the "stereo" channel layout corresponds to the value 3, this is
547 equivalent to:
548 @example
549 abuffer=44100:1:3:1
550 @end example
551
552 @section aevalsrc
553
554 Generate an audio signal specified by an expression.
555
556 This source accepts in input one or more expressions (one for each
557 channel), which are evaluated and used to generate a corresponding
558 audio signal.
559
560 It accepts the syntax: @var{exprs}[::@var{options}].
561 @var{exprs} is a list of expressions separated by ":", one for each
562 separate channel. The output channel layout depends on the number of
563 provided expressions, up to 8 channels are supported.
564
565 @var{options} is an optional sequence of @var{key}=@var{value} pairs,
566 separated by ":".
567
568 The description of the accepted options follows.
569
570 @table @option
571
572 @item duration, d
573 Set the minimum duration of the sourced audio. See the function
574 @code{av_parse_time()} for the accepted format.
575 Note that the resulting duration may be greater than the specified
576 duration, as the generated audio is always cut at the end of a
577 complete frame.
578
579 If not specified, or the expressed duration is negative, the audio is
580 supposed to be generated forever.
581
582 @item nb_samples, n
583 Set the number of samples per channel per each output frame,
584 default to 1024.
585
586 @item sample_rate, s
587 Specify the sample rate, default to 44100.
588 @end table
589
590 Each expression in @var{exprs} can contain the following constants:
591
592 @table @option
593 @item n
594 number of the evaluated sample, starting from 0
595
596 @item t
597 time of the evaluated sample expressed in seconds, starting from 0
598
599 @item s
600 sample rate
601
602 @end table
603
604 @subsection Examples
605
606 @itemize
607
608 @item
609 Generate silence:
610 @example
611 aevalsrc=0
612 @end example
613
614 @item
615
616 Generate a sin signal with frequency of 440 Hz, set sample rate to
617 8000 Hz:
618 @example
619 aevalsrc="sin(440*2*PI*t)::s=8000"
620 @end example
621
622 @item
623 Generate white noise:
624 @example
625 aevalsrc="-2+random(0)"
626 @end example
627
628 @item
629 Generate an amplitude modulated signal:
630 @example
631 aevalsrc="sin(10*2*PI*t)*sin(880*2*PI*t)"
632 @end example
633
634 @item
635 Generate 2.5 Hz binaural beats on a 360 Hz carrier:
636 @example
637 aevalsrc="0.1*sin(2*PI*(360-2.5/2)*t) : 0.1*sin(2*PI*(360+2.5/2)*t)"
638 @end example
639
640 @end itemize
641
642 @section amovie
643
644 Read an audio stream from a movie container.
645
646 It accepts the syntax: @var{movie_name}[:@var{options}] where
647 @var{movie_name} is the name of the resource to read (not necessarily
648 a file but also a device or a stream accessed through some protocol),
649 and @var{options} is an optional sequence of @var{key}=@var{value}
650 pairs, separated by ":".
651
652 The description of the accepted options follows.
653
654 @table @option
655
656 @item format_name, f
657 Specify the format assumed for the movie to read, and can be either
658 the name of a container or an input device. If not specified the
659 format is guessed from @var{movie_name} or by probing.
660
661 @item seek_point, sp
662 Specify the seek point in seconds, the frames will be output
663 starting from this seek point, the parameter is evaluated with
664 @code{av_strtod} so the numerical value may be suffixed by an IS
665 postfix. Default value is "0".
666
667 @item stream_index, si
668 Specify the index of the audio stream to read. If the value is -1,
669 the best suited audio stream will be automatically selected. Default
670 value is "-1".
671
672 @end table
673
674 @section anullsrc
675
676 Null audio source, return unprocessed audio frames. It is mainly useful
677 as a template and to be employed in analysis / debugging tools, or as
678 the source for filters which ignore the input data (for example the sox
679 synth filter).
680
681 It accepts an optional sequence of @var{key}=@var{value} pairs,
682 separated by ":".
683
684 The description of the accepted options follows.
685
686 @table @option
687
688 @item sample_rate, s
689 Specify the sample rate, and defaults to 44100.
690
691 @item channel_layout, cl
692
693 Specify the channel layout, and can be either an integer or a string
694 representing a channel layout. The default value of @var{channel_layout}
695 is "stereo".
696
697 Check the channel_layout_map definition in
698 @file{libavcodec/audioconvert.c} for the mapping between strings and
699 channel layout values.
700
701 @item nb_samples, n
702 Set the number of samples per requested frames.
703
704 @end table
705
706 Follow some examples:
707 @example
708 #  set the sample rate to 48000 Hz and the channel layout to AV_CH_LAYOUT_MONO.
709 anullsrc=r=48000:cl=4
710
711 # same as
712 anullsrc=r=48000:cl=mono
713 @end example
714
715 @c man end AUDIO SOURCES
716
717 @chapter Audio Sinks
718 @c man begin AUDIO SINKS
719
720 Below is a description of the currently available audio sinks.
721
722 @section abuffersink
723
724 Buffer audio frames, and make them available to the end of filter chain.
725
726 This sink is mainly intended for programmatic use, in particular
727 through the interface defined in @file{libavfilter/buffersink.h}.
728
729 It requires a pointer to an AVABufferSinkContext structure, which
730 defines the incoming buffers' formats, to be passed as the opaque
731 parameter to @code{avfilter_init_filter} for initialization.
732
733 @section anullsink
734
735 Null audio sink, do absolutely nothing with the input audio. It is
736 mainly useful as a template and to be employed in analysis / debugging
737 tools.
738
739 @c man end AUDIO SINKS
740
741 @chapter Video Filters
742 @c man begin VIDEO FILTERS
743
744 When you configure your FFmpeg build, you can disable any of the
745 existing filters using @code{--disable-filters}.
746 The configure output will show the video filters included in your
747 build.
748
749 Below is a description of the currently available video filters.
750
751 @section ass
752
753 Draw ASS (Advanced Substation Alpha) subtitles on top of input video
754 using the libass library.
755
756 To enable compilation of this filter you need to configure FFmpeg with
757 @code{--enable-libass}.
758
759 This filter accepts in input the name of the ass file to render.
760
761 For example, to render the file @file{sub.ass} on top of the input
762 video, use the command:
763 @example
764 ass=sub.ass
765 @end example
766
767 @section blackframe
768
769 Detect frames that are (almost) completely black. Can be useful to
770 detect chapter transitions or commercials. Output lines consist of
771 the frame number of the detected frame, the percentage of blackness,
772 the position in the file if known or -1 and the timestamp in seconds.
773
774 In order to display the output lines, you need to set the loglevel at
775 least to the AV_LOG_INFO value.
776
777 The filter accepts the syntax:
778 @example
779 blackframe[=@var{amount}:[@var{threshold}]]
780 @end example
781
782 @var{amount} is the percentage of the pixels that have to be below the
783 threshold, and defaults to 98.
784
785 @var{threshold} is the threshold below which a pixel value is
786 considered black, and defaults to 32.
787
788 @section boxblur
789
790 Apply boxblur algorithm to the input video.
791
792 This filter accepts the parameters:
793 @var{luma_radius}:@var{luma_power}:@var{chroma_radius}:@var{chroma_power}:@var{alpha_radius}:@var{alpha_power}
794
795 Chroma and alpha parameters are optional, if not specified they default
796 to the corresponding values set for @var{luma_radius} and
797 @var{luma_power}.
798
799 @var{luma_radius}, @var{chroma_radius}, and @var{alpha_radius} represent
800 the radius in pixels of the box used for blurring the corresponding
801 input plane. They are expressions, and can contain the following
802 constants:
803 @table @option
804 @item w, h
805 the input width and height in pixels
806
807 @item cw, ch
808 the input chroma image width and height in pixels
809
810 @item hsub, vsub
811 horizontal and vertical chroma subsample values. For example for the
812 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
813 @end table
814
815 The radius must be a non-negative number, and must not be greater than
816 the value of the expression @code{min(w,h)/2} for the luma and alpha planes,
817 and of @code{min(cw,ch)/2} for the chroma planes.
818
819 @var{luma_power}, @var{chroma_power}, and @var{alpha_power} represent
820 how many times the boxblur filter is applied to the corresponding
821 plane.
822
823 Some examples follow:
824
825 @itemize
826
827 @item
828 Apply a boxblur filter with luma, chroma, and alpha radius
829 set to 2:
830 @example
831 boxblur=2:1
832 @end example
833
834 @item
835 Set luma radius to 2, alpha and chroma radius to 0
836 @example
837 boxblur=2:1:0:0:0:0
838 @end example
839
840 @item
841 Set luma and chroma radius to a fraction of the video dimension
842 @example
843 boxblur=min(h\,w)/10:1:min(cw\,ch)/10:1
844 @end example
845
846 @end itemize
847
848 @section copy
849
850 Copy the input source unchanged to the output. Mainly useful for
851 testing purposes.
852
853 @section crop
854
855 Crop the input video to @var{out_w}:@var{out_h}:@var{x}:@var{y}.
856
857 The parameters are expressions containing the following constants:
858
859 @table @option
860 @item x, y
861 the computed values for @var{x} and @var{y}. They are evaluated for
862 each new frame.
863
864 @item in_w, in_h
865 the input width and height
866
867 @item iw, ih
868 same as @var{in_w} and @var{in_h}
869
870 @item out_w, out_h
871 the output (cropped) width and height
872
873 @item ow, oh
874 same as @var{out_w} and @var{out_h}
875
876 @item a
877 same as @var{iw} / @var{ih}
878
879 @item sar
880 input sample aspect ratio
881
882 @item dar
883 input display aspect ratio, it is the same as (@var{iw} / @var{ih}) * @var{sar}
884
885 @item hsub, vsub
886 horizontal and vertical chroma subsample values. For example for the
887 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
888
889 @item n
890 the number of input frame, starting from 0
891
892 @item pos
893 the position in the file of the input frame, NAN if unknown
894
895 @item t
896 timestamp expressed in seconds, NAN if the input timestamp is unknown
897
898 @end table
899
900 The @var{out_w} and @var{out_h} parameters specify the expressions for
901 the width and height of the output (cropped) video. They are
902 evaluated just at the configuration of the filter.
903
904 The default value of @var{out_w} is "in_w", and the default value of
905 @var{out_h} is "in_h".
906
907 The expression for @var{out_w} may depend on the value of @var{out_h},
908 and the expression for @var{out_h} may depend on @var{out_w}, but they
909 cannot depend on @var{x} and @var{y}, as @var{x} and @var{y} are
910 evaluated after @var{out_w} and @var{out_h}.
911
912 The @var{x} and @var{y} parameters specify the expressions for the
913 position of the top-left corner of the output (non-cropped) area. They
914 are evaluated for each frame. If the evaluated value is not valid, it
915 is approximated to the nearest valid value.
916
917 The default value of @var{x} is "(in_w-out_w)/2", and the default
918 value for @var{y} is "(in_h-out_h)/2", which set the cropped area at
919 the center of the input image.
920
921 The expression for @var{x} may depend on @var{y}, and the expression
922 for @var{y} may depend on @var{x}.
923
924 Follow some examples:
925 @example
926 # crop the central input area with size 100x100
927 crop=100:100
928
929 # crop the central input area with size 2/3 of the input video
930 "crop=2/3*in_w:2/3*in_h"
931
932 # crop the input video central square
933 crop=in_h
934
935 # delimit the rectangle with the top-left corner placed at position
936 # 100:100 and the right-bottom corner corresponding to the right-bottom
937 # corner of the input image.
938 crop=in_w-100:in_h-100:100:100
939
940 # crop 10 pixels from the left and right borders, and 20 pixels from
941 # the top and bottom borders
942 "crop=in_w-2*10:in_h-2*20"
943
944 # keep only the bottom right quarter of the input image
945 "crop=in_w/2:in_h/2:in_w/2:in_h/2"
946
947 # crop height for getting Greek harmony
948 "crop=in_w:1/PHI*in_w"
949
950 # trembling effect
951 "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)"
952
953 # erratic camera effect depending on timestamp
954 "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)"
955
956 # set x depending on the value of y
957 "crop=in_w/2:in_h/2:y:10+10*sin(n/10)"
958 @end example
959
960 @section cropdetect
961
962 Auto-detect crop size.
963
964 Calculate necessary cropping parameters and prints the recommended
965 parameters through the logging system. The detected dimensions
966 correspond to the non-black area of the input video.
967
968 It accepts the syntax:
969 @example
970 cropdetect[=@var{limit}[:@var{round}[:@var{reset}]]]
971 @end example
972
973 @table @option
974
975 @item limit
976 Threshold, which can be optionally specified from nothing (0) to
977 everything (255), defaults to 24.
978
979 @item round
980 Value which the width/height should be divisible by, defaults to
981 16. The offset is automatically adjusted to center the video. Use 2 to
982 get only even dimensions (needed for 4:2:2 video). 16 is best when
983 encoding to most video codecs.
984
985 @item reset
986 Counter that determines after how many frames cropdetect will reset
987 the previously detected largest video area and start over to detect
988 the current optimal crop area. Defaults to 0.
989
990 This can be useful when channel logos distort the video area. 0
991 indicates never reset and return the largest area encountered during
992 playback.
993 @end table
994
995 @section delogo
996
997 Suppress a TV station logo by a simple interpolation of the surrounding
998 pixels. Just set a rectangle covering the logo and watch it disappear
999 (and sometimes something even uglier appear - your mileage may vary).
1000
1001 The filter accepts parameters as a string of the form
1002 "@var{x}:@var{y}:@var{w}:@var{h}:@var{band}", or as a list of
1003 @var{key}=@var{value} pairs, separated by ":".
1004
1005 The description of the accepted parameters follows.
1006
1007 @table @option
1008
1009 @item x, y
1010 Specify the top left corner coordinates of the logo. They must be
1011 specified.
1012
1013 @item w, h
1014 Specify the width and height of the logo to clear. They must be
1015 specified.
1016
1017 @item band, t
1018 Specify the thickness of the fuzzy edge of the rectangle (added to
1019 @var{w} and @var{h}). The default value is 4.
1020
1021 @item show
1022 When set to 1, a green rectangle is drawn on the screen to simplify
1023 finding the right @var{x}, @var{y}, @var{w}, @var{h} parameters, and
1024 @var{band} is set to 4. The default value is 0.
1025
1026 @end table
1027
1028 Some examples follow.
1029
1030 @itemize
1031
1032 @item
1033 Set a rectangle covering the area with top left corner coordinates 0,0
1034 and size 100x77, setting a band of size 10:
1035 @example
1036 delogo=0:0:100:77:10
1037 @end example
1038
1039 @item
1040 As the previous example, but use named options:
1041 @example
1042 delogo=x=0:y=0:w=100:h=77:band=10
1043 @end example
1044
1045 @end itemize
1046
1047 @section deshake
1048
1049 Attempt to fix small changes in horizontal and/or vertical shift. This
1050 filter helps remove camera shake from hand-holding a camera, bumping a
1051 tripod, moving on a vehicle, etc.
1052
1053 The filter accepts parameters as a string of the form
1054 "@var{x}:@var{y}:@var{w}:@var{h}:@var{rx}:@var{ry}:@var{edge}:@var{blocksize}:@var{contrast}:@var{search}:@var{filename}"
1055
1056 A description of the accepted parameters follows.
1057
1058 @table @option
1059
1060 @item x, y, w, h
1061 Specify a rectangular area where to limit the search for motion
1062 vectors.
1063 If desired the search for motion vectors can be limited to a
1064 rectangular area of the frame defined by its top left corner, width
1065 and height. These parameters have the same meaning as the drawbox
1066 filter which can be used to visualise the position of the bounding
1067 box.
1068
1069 This is useful when simultaneous movement of subjects within the frame
1070 might be confused for camera motion by the motion vector search.
1071
1072 If any or all of @var{x}, @var{y}, @var{w} and @var{h} are set to -1
1073 then the full frame is used. This allows later options to be set
1074 without specifying the bounding box for the motion vector search.
1075
1076 Default - search the whole frame.
1077
1078 @item rx, ry
1079 Specify the maximum extent of movement in x and y directions in the
1080 range 0-64 pixels. Default 16.
1081
1082 @item edge
1083 Specify how to generate pixels to fill blanks at the edge of the
1084 frame. An integer from 0 to 3 as follows:
1085 @table @option
1086 @item 0
1087 Fill zeroes at blank locations
1088 @item 1
1089 Original image at blank locations
1090 @item 2
1091 Extruded edge value at blank locations
1092 @item 3
1093 Mirrored edge at blank locations
1094 @end table
1095
1096 The default setting is mirror edge at blank locations.
1097
1098 @item blocksize
1099 Specify the blocksize to use for motion search. Range 4-128 pixels,
1100 default 8.
1101
1102 @item contrast
1103 Specify the contrast threshold for blocks. Only blocks with more than
1104 the specified contrast (difference between darkest and lightest
1105 pixels) will be considered. Range 1-255, default 125.
1106
1107 @item search
1108 Specify the search strategy 0 = exhaustive search, 1 = less exhaustive
1109 search. Default - exhaustive search.
1110
1111 @item filename
1112 If set then a detailed log of the motion search is written to the
1113 specified file.
1114
1115 @end table
1116
1117 @section drawbox
1118
1119 Draw a colored box on the input image.
1120
1121 It accepts the syntax:
1122 @example
1123 drawbox=@var{x}:@var{y}:@var{width}:@var{height}:@var{color}
1124 @end example
1125
1126 @table @option
1127
1128 @item x, y
1129 Specify the top left corner coordinates of the box. Default to 0.
1130
1131 @item width, height
1132 Specify the width and height of the box, if 0 they are interpreted as
1133 the input width and height. Default to 0.
1134
1135 @item color
1136 Specify the color of the box to write, it can be the name of a color
1137 (case insensitive match) or a 0xRRGGBB[AA] sequence.
1138 @end table
1139
1140 Follow some examples:
1141 @example
1142 # draw a black box around the edge of the input image
1143 drawbox
1144
1145 # draw a box with color red and an opacity of 50%
1146 drawbox=10:20:200:60:red@@0.5"
1147 @end example
1148
1149 @section drawtext
1150
1151 Draw text string or text from specified file on top of video using the
1152 libfreetype library.
1153
1154 To enable compilation of this filter you need to configure FFmpeg with
1155 @code{--enable-libfreetype}.
1156
1157 The filter also recognizes strftime() sequences in the provided text
1158 and expands them accordingly. Check the documentation of strftime().
1159
1160 The filter accepts parameters as a list of @var{key}=@var{value} pairs,
1161 separated by ":".
1162
1163 The description of the accepted parameters follows.
1164
1165 @table @option
1166
1167 @item fontfile
1168 The font file to be used for drawing text. Path must be included.
1169 This parameter is mandatory.
1170
1171 @item text
1172 The text string to be drawn. The text must be a sequence of UTF-8
1173 encoded characters.
1174 This parameter is mandatory if no file is specified with the parameter
1175 @var{textfile}.
1176
1177 @item textfile
1178 A text file containing text to be drawn. The text must be a sequence
1179 of UTF-8 encoded characters.
1180
1181 This parameter is mandatory if no text string is specified with the
1182 parameter @var{text}.
1183
1184 If both text and textfile are specified, an error is thrown.
1185
1186 @item x, y
1187 The expressions which specify the offsets where text will be drawn
1188 within the video frame. They are relative to the top/left border of the
1189 output image.
1190
1191 The default value of @var{x} and @var{y} is "0".
1192
1193 See below for the list of accepted constants.
1194
1195 @item fontsize
1196 The font size to be used for drawing text.
1197 The default value of @var{fontsize} is 16.
1198
1199 @item fontcolor
1200 The color to be used for drawing fonts.
1201 Either a string (e.g. "red") or in 0xRRGGBB[AA] format
1202 (e.g. "0xff000033"), possibly followed by an alpha specifier.
1203 The default value of @var{fontcolor} is "black".
1204
1205 @item boxcolor
1206 The color to be used for drawing box around text.
1207 Either a string (e.g. "yellow") or in 0xRRGGBB[AA] format
1208 (e.g. "0xff00ff"), possibly followed by an alpha specifier.
1209 The default value of @var{boxcolor} is "white".
1210
1211 @item box
1212 Used to draw a box around text using background color.
1213 Value should be either 1 (enable) or 0 (disable).
1214 The default value of @var{box} is 0.
1215
1216 @item shadowx, shadowy
1217 The x and y offsets for the text shadow position with respect to the
1218 position of the text. They can be either positive or negative
1219 values. Default value for both is "0".
1220
1221 @item shadowcolor
1222 The color to be used for drawing a shadow behind the drawn text.  It
1223 can be a color name (e.g. "yellow") or a string in the 0xRRGGBB[AA]
1224 form (e.g. "0xff00ff"), possibly followed by an alpha specifier.
1225 The default value of @var{shadowcolor} is "black".
1226
1227 @item ft_load_flags
1228 Flags to be used for loading the fonts.
1229
1230 The flags map the corresponding flags supported by libfreetype, and are
1231 a combination of the following values:
1232 @table @var
1233 @item default
1234 @item no_scale
1235 @item no_hinting
1236 @item render
1237 @item no_bitmap
1238 @item vertical_layout
1239 @item force_autohint
1240 @item crop_bitmap
1241 @item pedantic
1242 @item ignore_global_advance_width
1243 @item no_recurse
1244 @item ignore_transform
1245 @item monochrome
1246 @item linear_design
1247 @item no_autohint
1248 @item end table
1249 @end table
1250
1251 Default value is "render".
1252
1253 For more information consult the documentation for the FT_LOAD_*
1254 libfreetype flags.
1255
1256 @item tabsize
1257 The size in number of spaces to use for rendering the tab.
1258 Default value is 4.
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 # the above is equivalent to
2377 setdar=1.77777
2378 @end example
2379
2380 To change the sample aspect ratio to 10:11, specify:
2381 @example
2382 setsar=10:11
2383 @end example
2384
2385 @section setpts
2386
2387 Change the PTS (presentation timestamp) of the input video frames.
2388
2389 Accept in input an expression evaluated through the eval API, which
2390 can contain the following constants:
2391
2392 @table @option
2393 @item PTS
2394 the presentation timestamp in input
2395
2396 @item N
2397 the count of the input frame, starting from 0.
2398
2399 @item STARTPTS
2400 the PTS of the first video frame
2401
2402 @item INTERLACED
2403 tell if the current frame is interlaced
2404
2405 @item POS
2406 original position in the file of the frame, or undefined if undefined
2407 for the current frame
2408
2409 @item PREV_INPTS
2410 previous input PTS
2411
2412 @item PREV_OUTPTS
2413 previous output PTS
2414
2415 @end table
2416
2417 Some examples follow:
2418
2419 @example
2420 # start counting PTS from zero
2421 setpts=PTS-STARTPTS
2422
2423 # fast motion
2424 setpts=0.5*PTS
2425
2426 # slow motion
2427 setpts=2.0*PTS
2428
2429 # fixed rate 25 fps
2430 setpts=N/(25*TB)
2431
2432 # fixed rate 25 fps with some jitter
2433 setpts='1/(25*TB) * (N + 0.05 * sin(N*2*PI/25))'
2434 @end example
2435
2436 @section settb
2437
2438 Set the timebase to use for the output frames timestamps.
2439 It is mainly useful for testing timebase configuration.
2440
2441 It accepts in input an arithmetic expression representing a rational.
2442 The expression can contain the constants "AVTB" (the
2443 default timebase), and "intb" (the input timebase).
2444
2445 The default value for the input is "intb".
2446
2447 Follow some examples.
2448
2449 @example
2450 # set the timebase to 1/25
2451 settb=1/25
2452
2453 # set the timebase to 1/10
2454 settb=0.1
2455
2456 #set the timebase to 1001/1000
2457 settb=1+0.001
2458
2459 #set the timebase to 2*intb
2460 settb=2*intb
2461
2462 #set the default timebase value
2463 settb=AVTB
2464 @end example
2465
2466 @section showinfo
2467
2468 Show a line containing various information for each input video frame.
2469 The input video is not modified.
2470
2471 The shown line contains a sequence of key/value pairs of the form
2472 @var{key}:@var{value}.
2473
2474 A description of each shown parameter follows:
2475
2476 @table @option
2477 @item n
2478 sequential number of the input frame, starting from 0
2479
2480 @item pts
2481 Presentation TimeStamp of the input frame, expressed as a number of
2482 time base units. The time base unit depends on the filter input pad.
2483
2484 @item pts_time
2485 Presentation TimeStamp of the input frame, expressed as a number of
2486 seconds
2487
2488 @item pos
2489 position of the frame in the input stream, -1 if this information in
2490 unavailable and/or meaningless (for example in case of synthetic video)
2491
2492 @item fmt
2493 pixel format name
2494
2495 @item sar
2496 sample aspect ratio of the input frame, expressed in the form
2497 @var{num}/@var{den}
2498
2499 @item s
2500 size of the input frame, expressed in the form
2501 @var{width}x@var{height}
2502
2503 @item i
2504 interlaced mode ("P" for "progressive", "T" for top field first, "B"
2505 for bottom field first)
2506
2507 @item iskey
2508 1 if the frame is a key frame, 0 otherwise
2509
2510 @item type
2511 picture type of the input frame ("I" for an I-frame, "P" for a
2512 P-frame, "B" for a B-frame, "?" for unknown type).
2513 Check also the documentation of the @code{AVPictureType} enum and of
2514 the @code{av_get_picture_type_char} function defined in
2515 @file{libavutil/avutil.h}.
2516
2517 @item checksum
2518 Adler-32 checksum (printed in hexadecimal) of all the planes of the input frame
2519
2520 @item plane_checksum
2521 Adler-32 checksum (printed in hexadecimal) of each plane of the input frame,
2522 expressed in the form "[@var{c0} @var{c1} @var{c2} @var{c3}]"
2523 @end table
2524
2525 @section slicify
2526
2527 Pass the images of input video on to next video filter as multiple
2528 slices.
2529
2530 @example
2531 ffmpeg -i in.avi -vf "slicify=32" out.avi
2532 @end example
2533
2534 The filter accepts the slice height as parameter. If the parameter is
2535 not specified it will use the default value of 16.
2536
2537 Adding this in the beginning of filter chains should make filtering
2538 faster due to better use of the memory cache.
2539
2540 @section split
2541
2542 Pass on the input video to two outputs. Both outputs are identical to
2543 the input video.
2544
2545 For example:
2546 @example
2547 [in] split [splitout1][splitout2];
2548 [splitout1] crop=100:100:0:0    [cropout];
2549 [splitout2] pad=200:200:100:100 [padout];
2550 @end example
2551
2552 will create two separate outputs from the same input, one cropped and
2553 one padded.
2554
2555 @section thumbnail
2556 Select the most representative frame in a given sequence of consecutive frames.
2557
2558 It accepts as argument the frames batch size to analyze (default @var{N}=100);
2559 in a set of @var{N} frames, the filter will pick one of them, and then handle
2560 the next batch of @var{N} frames until the end.
2561
2562 Since the filter keeps track of the whole frames sequence, a bigger @var{N}
2563 value will result in a higher memory usage, so a high value is not recommended.
2564
2565 The following example extract one picture each 50 frames:
2566 @example
2567 thumbnail=50
2568 @end example
2569
2570 Complete example of a thumbnail creation with @command{ffmpeg}:
2571 @example
2572 ffmpeg -i in.avi -vf thumbnail,scale=300:200 -frames:v 1 out.png
2573 @end example
2574
2575 @section tinterlace
2576
2577 Perform various types of temporal field interlacing.
2578
2579 Frames are counted starting from 1, so the first input frame is
2580 considered odd.
2581
2582 This filter accepts a single parameter specifying the mode. Available
2583 modes are:
2584
2585 @table @samp
2586 @item 0
2587 Move odd frames into the upper field, even into the lower field,
2588 generating a double height frame at half framerate.
2589
2590 @item 1
2591 Only output even frames, odd frames are dropped, generating a frame with
2592 unchanged height at half framerate.
2593
2594 @item 2
2595 Only output odd frames, even frames are dropped, generating a frame with
2596 unchanged height at half framerate.
2597
2598 @item 3
2599 Expand each frame to full height, but pad alternate lines with black,
2600 generating a frame with double height at the same input framerate.
2601
2602 @item 4
2603 Interleave the upper field from odd frames with the lower field from
2604 even frames, generating a frame with unchanged height at half framerate.
2605
2606 @item 5
2607 Interleave the lower field from odd frames with the upper field from
2608 even frames, generating a frame with unchanged height at half framerate.
2609 @end table
2610
2611 Default mode is 0.
2612
2613 @section transpose
2614
2615 Transpose rows with columns in the input video and optionally flip it.
2616
2617 It accepts a parameter representing an integer, which can assume the
2618 values:
2619
2620 @table @samp
2621 @item 0
2622 Rotate by 90 degrees counterclockwise and vertically flip (default), that is:
2623 @example
2624 L.R     L.l
2625 . . ->  . .
2626 l.r     R.r
2627 @end example
2628
2629 @item 1
2630 Rotate by 90 degrees clockwise, that is:
2631 @example
2632 L.R     l.L
2633 . . ->  . .
2634 l.r     r.R
2635 @end example
2636
2637 @item 2
2638 Rotate by 90 degrees counterclockwise, that is:
2639 @example
2640 L.R     R.r
2641 . . ->  . .
2642 l.r     L.l
2643 @end example
2644
2645 @item 3
2646 Rotate by 90 degrees clockwise and vertically flip, that is:
2647 @example
2648 L.R     r.R
2649 . . ->  . .
2650 l.r     l.L
2651 @end example
2652 @end table
2653
2654 @section unsharp
2655
2656 Sharpen or blur the input video.
2657
2658 It accepts the following parameters:
2659 @var{luma_msize_x}:@var{luma_msize_y}:@var{luma_amount}:@var{chroma_msize_x}:@var{chroma_msize_y}:@var{chroma_amount}
2660
2661 Negative values for the amount will blur the input video, while positive
2662 values will sharpen. All parameters are optional and default to the
2663 equivalent of the string '5:5:1.0:5:5:0.0'.
2664
2665 @table @option
2666
2667 @item luma_msize_x
2668 Set the luma matrix horizontal size. It can be an integer between 3
2669 and 13, default value is 5.
2670
2671 @item luma_msize_y
2672 Set the luma matrix vertical size. It can be an integer between 3
2673 and 13, default value is 5.
2674
2675 @item luma_amount
2676 Set the luma effect strength. It can be a float number between -2.0
2677 and 5.0, default value is 1.0.
2678
2679 @item chroma_msize_x
2680 Set the chroma matrix horizontal size. It can be an integer between 3
2681 and 13, default value is 5.
2682
2683 @item chroma_msize_y
2684 Set the chroma matrix vertical size. It can be an integer between 3
2685 and 13, default value is 5.
2686
2687 @item chroma_amount
2688 Set the chroma effect strength. It can be a float number between -2.0
2689 and 5.0, default value is 0.0.
2690
2691 @end table
2692
2693 @example
2694 # Strong luma sharpen effect parameters
2695 unsharp=7:7:2.5
2696
2697 # Strong blur of both luma and chroma parameters
2698 unsharp=7:7:-2:7:7:-2
2699
2700 # Use the default values with @command{ffmpeg}
2701 ffmpeg -i in.avi -vf "unsharp" out.mp4
2702 @end example
2703
2704 @section vflip
2705
2706 Flip the input video vertically.
2707
2708 @example
2709 ffmpeg -i in.avi -vf "vflip" out.avi
2710 @end example
2711
2712 @section yadif
2713
2714 Deinterlace the input video ("yadif" means "yet another deinterlacing
2715 filter").
2716
2717 It accepts the optional parameters: @var{mode}:@var{parity}:@var{auto}.
2718
2719 @var{mode} specifies the interlacing mode to adopt, accepts one of the
2720 following values:
2721
2722 @table @option
2723 @item 0
2724 output 1 frame for each frame
2725 @item 1
2726 output 1 frame for each field
2727 @item 2
2728 like 0 but skips spatial interlacing check
2729 @item 3
2730 like 1 but skips spatial interlacing check
2731 @end table
2732
2733 Default value is 0.
2734
2735 @var{parity} specifies the picture field parity assumed for the input
2736 interlaced video, accepts one of the following values:
2737
2738 @table @option
2739 @item 0
2740 assume top field first
2741 @item 1
2742 assume bottom field first
2743 @item -1
2744 enable automatic detection
2745 @end table
2746
2747 Default value is -1.
2748 If interlacing is unknown or decoder does not export this information,
2749 top field first will be assumed.
2750
2751 @var{auto} specifies if deinterlacer should trust the interlaced flag
2752 and only deinterlace frames marked as interlaced
2753
2754 @table @option
2755 @item 0
2756 deinterlace all frames
2757 @item 1
2758 only deinterlace frames marked as interlaced
2759 @end table
2760
2761 Default value is 0.
2762
2763 @c man end VIDEO FILTERS
2764
2765 @chapter Video Sources
2766 @c man begin VIDEO SOURCES
2767
2768 Below is a description of the currently available video sources.
2769
2770 @section buffer
2771
2772 Buffer video frames, and make them available to the filter chain.
2773
2774 This source is mainly intended for a programmatic use, in particular
2775 through the interface defined in @file{libavfilter/vsrc_buffer.h}.
2776
2777 It accepts the following parameters:
2778 @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}
2779
2780 All the parameters but @var{scale_params} need to be explicitly
2781 defined.
2782
2783 Follows the list of the accepted parameters.
2784
2785 @table @option
2786
2787 @item width, height
2788 Specify the width and height of the buffered video frames.
2789
2790 @item pix_fmt_string
2791 A string representing the pixel format of the buffered video frames.
2792 It may be a number corresponding to a pixel format, or a pixel format
2793 name.
2794
2795 @item timebase_num, timebase_den
2796 Specify numerator and denomitor of the timebase assumed by the
2797 timestamps of the buffered frames.
2798
2799 @item sample_aspect_ratio.num, sample_aspect_ratio.den
2800 Specify numerator and denominator of the sample aspect ratio assumed
2801 by the video frames.
2802
2803 @item scale_params
2804 Specify the optional parameters to be used for the scale filter which
2805 is automatically inserted when an input change is detected in the
2806 input size or format.
2807 @end table
2808
2809 For example:
2810 @example
2811 buffer=320:240:yuv410p:1:24:1:1
2812 @end example
2813
2814 will instruct the source to accept video frames with size 320x240 and
2815 with format "yuv410p", assuming 1/24 as the timestamps timebase and
2816 square pixels (1:1 sample aspect ratio).
2817 Since the pixel format with name "yuv410p" corresponds to the number 6
2818 (check the enum PixelFormat definition in @file{libavutil/pixfmt.h}),
2819 this example corresponds to:
2820 @example
2821 buffer=320:240:6:1:24:1:1
2822 @end example
2823
2824 @section cellauto
2825
2826 Create a pattern generated by an elementary cellular automaton.
2827
2828 The initial state of the cellular automaton can be defined through the
2829 @option{filename}, and @option{pattern} options. If such options are
2830 not specified an initial state is created randomly.
2831
2832 At each new frame a new row in the video is filled with the result of
2833 the cellular automaton next generation. The behavior when the whole
2834 frame is filled is defined by the @option{scroll} option.
2835
2836 This source accepts a list of options in the form of
2837 @var{key}=@var{value} pairs separated by ":". A description of the
2838 accepted options follows.
2839
2840 @table @option
2841 @item filename, f
2842 Read the initial cellular automaton state, i.e. the starting row, from
2843 the specified file.
2844 In the file, each non-whitespace character is considered an alive
2845 cell, a newline will terminate the row, and further characters in the
2846 file will be ignored.
2847
2848 @item pattern, p
2849 Read the initial cellular automaton state, i.e. the starting row, from
2850 the specified string.
2851
2852 Each non-whitespace character in the string is considered an alive
2853 cell, a newline will terminate the row, and further characters in the
2854 string will be ignored.
2855
2856 @item rate, r
2857 Set the video rate, that is the number of frames generated per second.
2858 Default is 25.
2859
2860 @item random_fill_ratio, ratio
2861 Set the random fill ratio for the initial cellular automaton row. It
2862 is a floating point number value ranging from 0 to 1, defaults to
2863 1/PHI.
2864
2865 This option is ignored when a file or a pattern is specified.
2866
2867 @item random_seed, seed
2868 Set the seed for filling randomly the initial row, must be an integer
2869 included between 0 and UINT32_MAX. If not specified, or if explicitly
2870 set to -1, the filter will try to use a good random seed on a best
2871 effort basis.
2872
2873 @item rule
2874 Set the cellular automaton rule, it is a number ranging from 0 to 255.
2875 Default value is 110.
2876
2877 @item size, s
2878 Set the size of the output video.
2879
2880 If @option{filename} or @option{pattern} is specified, the size is set
2881 by default to the width of the specified initial state row, and the
2882 height is set to @var{width} * PHI.
2883
2884 If @option{size} is set, it must contain the width of the specified
2885 pattern string, and the specified pattern will be centered in the
2886 larger row.
2887
2888 If a filename or a pattern string is not specified, the size value
2889 defaults to "320x518" (used for a randomly generated initial state).
2890
2891 @item scroll
2892 If set to 1, scroll the output upward when all the rows in the output
2893 have been already filled. If set to 0, the new generated row will be
2894 written over the top row just after the bottom row is filled.
2895 Defaults to 1.
2896
2897 @item start_full, full
2898 If set to 1, completely fill the output with generated rows before
2899 outputting the first frame.
2900 This is the default behavior, for disabling set the value to 0.
2901
2902 @item stitch
2903 If set to 1, stitch the left and right row edges together.
2904 This is the default behavior, for disabling set the value to 0.
2905 @end table
2906
2907 @subsection Examples
2908
2909 @itemize
2910 @item
2911 Read the initial state from @file{pattern}, and specify an output of
2912 size 200x400.
2913 @example
2914 cellauto=f=pattern:s=200x400
2915 @end example
2916
2917 @item
2918 Generate a random initial row with a width of 200 cells, with a fill
2919 ratio of 2/3:
2920 @example
2921 cellauto=ratio=2/3:s=200x200
2922 @end example
2923
2924 @item
2925 Create a pattern generated by rule 18 starting by a single alive cell
2926 centered on an initial row with width 100:
2927 @example
2928 cellauto=p=@@:s=100x400:full=0:rule=18
2929 @end example
2930
2931 @item
2932 Specify a more elaborated initial pattern:
2933 @example
2934 cellauto=p='@@@@ @@ @@@@':s=100x400:full=0:rule=18
2935 @end example
2936
2937 @end itemize
2938
2939 @section color
2940
2941 Provide an uniformly colored input.
2942
2943 It accepts the following parameters:
2944 @var{color}:@var{frame_size}:@var{frame_rate}
2945
2946 Follows the description of the accepted parameters.
2947
2948 @table @option
2949
2950 @item color
2951 Specify the color of the source. It can be the name of a color (case
2952 insensitive match) or a 0xRRGGBB[AA] sequence, possibly followed by an
2953 alpha specifier. The default value is "black".
2954
2955 @item frame_size
2956 Specify the size of the sourced video, it may be a string of the form
2957 @var{width}x@var{height}, or the name of a size abbreviation. The
2958 default value is "320x240".
2959
2960 @item frame_rate
2961 Specify the frame rate of the sourced video, as the number of frames
2962 generated per second. It has to be a string in the format
2963 @var{frame_rate_num}/@var{frame_rate_den}, an integer number, a float
2964 number or a valid video frame rate abbreviation. The default value is
2965 "25".
2966
2967 @end table
2968
2969 For example the following graph description will generate a red source
2970 with an opacity of 0.2, with size "qcif" and a frame rate of 10
2971 frames per second, which will be overlayed over the source connected
2972 to the pad with identifier "in".
2973
2974 @example
2975 "color=red@@0.2:qcif:10 [color]; [in][color] overlay [out]"
2976 @end example
2977
2978 @section movie
2979
2980 Read a video stream from a movie container.
2981
2982 It accepts the syntax: @var{movie_name}[:@var{options}] where
2983 @var{movie_name} is the name of the resource to read (not necessarily
2984 a file but also a device or a stream accessed through some protocol),
2985 and @var{options} is an optional sequence of @var{key}=@var{value}
2986 pairs, separated by ":".
2987
2988 The description of the accepted options follows.
2989
2990 @table @option
2991
2992 @item format_name, f
2993 Specifies the format assumed for the movie to read, and can be either
2994 the name of a container or an input device. If not specified the
2995 format is guessed from @var{movie_name} or by probing.
2996
2997 @item seek_point, sp
2998 Specifies the seek point in seconds, the frames will be output
2999 starting from this seek point, the parameter is evaluated with
3000 @code{av_strtod} so the numerical value may be suffixed by an IS
3001 postfix. Default value is "0".
3002
3003 @item stream_index, si
3004 Specifies the index of the video stream to read. If the value is -1,
3005 the best suited video stream will be automatically selected. Default
3006 value is "-1".
3007
3008 @end table
3009
3010 This filter allows to overlay a second video on top of main input of
3011 a filtergraph as shown in this graph:
3012 @example
3013 input -----------> deltapts0 --> overlay --> output
3014                                     ^
3015                                     |
3016 movie --> scale--> deltapts1 -------+
3017 @end example
3018
3019 Some examples follow:
3020 @example
3021 # skip 3.2 seconds from the start of the avi file in.avi, and overlay it
3022 # on top of the input labelled as "in".
3023 movie=in.avi:seek_point=3.2, scale=180:-1, setpts=PTS-STARTPTS [movie];
3024 [in] setpts=PTS-STARTPTS, [movie] overlay=16:16 [out]
3025
3026 # read from a video4linux2 device, and overlay it on top of the input
3027 # labelled as "in"
3028 movie=/dev/video0:f=video4linux2, scale=180:-1, setpts=PTS-STARTPTS [movie];
3029 [in] setpts=PTS-STARTPTS, [movie] overlay=16:16 [out]
3030
3031 @end example
3032
3033 @section mptestsrc
3034
3035 Generate various test patterns, as generated by the MPlayer test filter.
3036
3037 The size of the generated video is fixed, and is 256x256.
3038 This source is useful in particular for testing encoding features.
3039
3040 This source accepts an optional sequence of @var{key}=@var{value} pairs,
3041 separated by ":". The description of the accepted options follows.
3042
3043 @table @option
3044
3045 @item rate, r
3046 Specify the frame rate of the sourced video, as the number of frames
3047 generated per second. It has to be a string in the format
3048 @var{frame_rate_num}/@var{frame_rate_den}, an integer number, a float
3049 number or a valid video frame rate abbreviation. The default value is
3050 "25".
3051
3052 @item duration, d
3053 Set the video duration of the sourced video. The accepted syntax is:
3054 @example
3055 [-]HH[:MM[:SS[.m...]]]
3056 [-]S+[.m...]
3057 @end example
3058 See also the function @code{av_parse_time()}.
3059
3060 If not specified, or the expressed duration is negative, the video is
3061 supposed to be generated forever.
3062
3063 @item test, t
3064
3065 Set the number or the name of the test to perform. Supported tests are:
3066 @table @option
3067 @item dc_luma
3068 @item dc_chroma
3069 @item freq_luma
3070 @item freq_chroma
3071 @item amp_luma
3072 @item amp_chroma
3073 @item cbp
3074 @item mv
3075 @item ring1
3076 @item ring2
3077 @item all
3078 @end table
3079
3080 Default value is "all", which will cycle through the list of all tests.
3081 @end table
3082
3083 For example the following:
3084 @example
3085 testsrc=t=dc_luma
3086 @end example
3087
3088 will generate a "dc_luma" test pattern.
3089
3090 @section frei0r_src
3091
3092 Provide a frei0r source.
3093
3094 To enable compilation of this filter you need to install the frei0r
3095 header and configure FFmpeg with @code{--enable-frei0r}.
3096
3097 The source supports the syntax:
3098 @example
3099 @var{size}:@var{rate}:@var{src_name}[@{=|:@}@var{param1}:@var{param2}:...:@var{paramN}]
3100 @end example
3101
3102 @var{size} is the size of the video to generate, may be a string of the
3103 form @var{width}x@var{height} or a frame size abbreviation.
3104 @var{rate} is the rate of the video to generate, may be a string of
3105 the form @var{num}/@var{den} or a frame rate abbreviation.
3106 @var{src_name} is the name to the frei0r source to load. For more
3107 information regarding frei0r and how to set the parameters read the
3108 section @ref{frei0r} in the description of the video filters.
3109
3110 Some examples follow:
3111 @example
3112 # generate a frei0r partik0l source with size 200x200 and frame rate 10
3113 # which is overlayed on the overlay filter main input
3114 frei0r_src=200x200:10:partik0l=1234 [overlay]; [in][overlay] overlay
3115 @end example
3116
3117 @section life
3118
3119 Generate a life pattern.
3120
3121 This source is based on a generalization of John Conway's life game.
3122
3123 The sourced input represents a life grid, each pixel represents a cell
3124 which can be in one of two possible states, alive or dead. Every cell
3125 interacts with its eight neighbours, which are the cells that are
3126 horizontally, vertically, or diagonally adjacent.
3127
3128 At each interaction the grid evolves according to the adopted rule,
3129 which specifies the number of neighbor alive cells which will make a
3130 cell stay alive or born. The @option{rule} option allows to specify
3131 the rule to adopt.
3132
3133 This source accepts a list of options in the form of
3134 @var{key}=@var{value} pairs separated by ":". A description of the
3135 accepted options follows.
3136
3137 @table @option
3138 @item filename, f
3139 Set the file from which to read the initial grid state. In the file,
3140 each non-whitespace character is considered an alive cell, and newline
3141 is used to delimit the end of each row.
3142
3143 If this option is not specified, the initial grid is generated
3144 randomly.
3145
3146 @item rate, r
3147 Set the video rate, that is the number of frames generated per second.
3148 Default is 25.
3149
3150 @item random_fill_ratio, ratio
3151 Set the random fill ratio for the initial random grid. It is a
3152 floating point number value ranging from 0 to 1, defaults to 1/PHI.
3153 It is ignored when a file is specified.
3154
3155 @item random_seed, seed
3156 Set the seed for filling the initial random grid, must be an integer
3157 included between 0 and UINT32_MAX. If not specified, or if explicitly
3158 set to -1, the filter will try to use a good random seed on a best
3159 effort basis.
3160
3161 @item rule
3162 Set the life rule.
3163
3164 A rule can be specified with a code of the kind "S@var{NS}/B@var{NB}",
3165 where @var{NS} and @var{NB} are sequences of numbers in the range 0-8,
3166 @var{NS} specifies the number of alive neighbor cells which make a
3167 live cell stay alive, and @var{NB} the number of alive neighbor cells
3168 which make a dead cell to become alive (i.e. to "born").
3169 "s" and "b" can be used in place of "S" and "B", respectively.
3170
3171 Alternatively a rule can be specified by an 18-bits integer. The 9
3172 high order bits are used to encode the next cell state if it is alive
3173 for each number of neighbor alive cells, the low order bits specify
3174 the rule for "borning" new cells. Higher order bits encode for an
3175 higher number of neighbor cells.
3176 For example the number 6153 = @code{(12<<9)+9} specifies a stay alive
3177 rule of 12 and a born rule of 9, which corresponds to "S23/B03".
3178
3179 Default value is "S23/B3", which is the original Conway's game of life
3180 rule, and will keep a cell alive if it has 2 or 3 neighbor alive
3181 cells, and will born a new cell if there are three alive cells around
3182 a dead cell.
3183
3184 @item size, s
3185 Set the size of the output video.
3186
3187 If @option{filename} is specified, the size is set by default to the
3188 same size of the input file. If @option{size} is set, it must contain
3189 the size specified in the input file, and the initial grid defined in
3190 that file is centered in the larger resulting area.
3191
3192 If a filename is not specified, the size value defaults to "320x240"
3193 (used for a randomly generated initial grid).
3194
3195 @item stitch
3196 If set to 1, stitch the left and right grid edges together, and the
3197 top and bottom edges also. Defaults to 1.
3198
3199 @item mold
3200 Set cell mold speed. If set, a dead cell will go from @option{death_color} to
3201 @option{mold_color} with a step of @option{mold}. @option{mold} can have a
3202 value from 0 to 255.
3203
3204 @item life_color
3205 Set the color of living (or new born) cells.
3206
3207 @item death_color
3208 Set the color of dead cells. If @option{mold} is set, this is the first color
3209 used to represent a dead cell.
3210
3211 @item mold_color
3212 Set mold color, for definitely dead and moldy cells.
3213 @end table
3214
3215 @subsection Examples
3216
3217 @itemize
3218 @item
3219 Read a grid from @file{pattern}, and center it on a grid of size
3220 300x300 pixels:
3221 @example
3222 life=f=pattern:s=300x300
3223 @end example
3224
3225 @item
3226 Generate a random grid of size 200x200, with a fill ratio of 2/3:
3227 @example
3228 life=ratio=2/3:s=200x200
3229 @end example
3230
3231 @item
3232 Specify a custom rule for evolving a randomly generated grid:
3233 @example
3234 life=rule=S14/B34
3235 @end example
3236
3237 @item
3238 Full example with slow death effect (mold) using @command{ffplay}:
3239 @example
3240 ffplay -f lavfi life=s=300x200:mold=10:r=60:ratio=0.1:death_color=#C83232:life_color=#00ff00,scale=1200:800:flags=16
3241 @end example
3242 @end itemize
3243
3244 @section nullsrc, rgbtestsrc, testsrc
3245
3246 The @code{nullsrc} source returns unprocessed video frames. It is
3247 mainly useful to be employed in analysis / debugging tools, or as the
3248 source for filters which ignore the input data.
3249
3250 The @code{rgbtestsrc} source generates an RGB test pattern useful for
3251 detecting RGB vs BGR issues. You should see a red, green and blue
3252 stripe from top to bottom.
3253
3254 The @code{testsrc} source generates a test video pattern, showing a
3255 color pattern, a scrolling gradient and a timestamp. This is mainly
3256 intended for testing purposes.
3257
3258 These sources accept an optional sequence of @var{key}=@var{value} pairs,
3259 separated by ":". The description of the accepted options follows.
3260
3261 @table @option
3262
3263 @item size, s
3264 Specify the size of the sourced video, it may be a string of the form
3265 @var{width}x@var{height}, or the name of a size abbreviation. The
3266 default value is "320x240".
3267
3268 @item rate, r
3269 Specify the frame rate of the sourced video, as the number of frames
3270 generated per second. It has to be a string in the format
3271 @var{frame_rate_num}/@var{frame_rate_den}, an integer number, a float
3272 number or a valid video frame rate abbreviation. The default value is
3273 "25".
3274
3275 @item sar
3276 Set the sample aspect ratio of the sourced video.
3277
3278 @item duration, d
3279 Set the video duration of the sourced video. The accepted syntax is:
3280 @example
3281 [-]HH[:MM[:SS[.m...]]]
3282 [-]S+[.m...]
3283 @end example
3284 See also the function @code{av_parse_time()}.
3285
3286 If not specified, or the expressed duration is negative, the video is
3287 supposed to be generated forever.
3288
3289 @item decimals, n
3290 Set the number of decimals to show in the timestamp, only used in the
3291 @code{testsrc} source.
3292
3293 The displayed timestamp value will correspond to the original
3294 timestamp value multiplied by the power of 10 of the specified
3295 value. Default value is 0.
3296 @end table
3297
3298 For example the following:
3299 @example
3300 testsrc=duration=5.3:size=qcif:rate=10
3301 @end example
3302
3303 will generate a video with a duration of 5.3 seconds, with size
3304 176x144 and a frame rate of 10 frames per second.
3305
3306 If the input content is to be ignored, @code{nullsrc} can be used. The
3307 following command generates noise in the luminance plane by employing
3308 the @code{mp=geq} filter:
3309 @example
3310 nullsrc=s=256x256, mp=geq=random(1)*255:128:128
3311 @end example
3312
3313 @c man end VIDEO SOURCES
3314
3315 @chapter Video Sinks
3316 @c man begin VIDEO SINKS
3317
3318 Below is a description of the currently available video sinks.
3319
3320 @section buffersink
3321
3322 Buffer video frames, and make them available to the end of the filter
3323 graph.
3324
3325 This sink is mainly intended for a programmatic use, in particular
3326 through the interface defined in @file{libavfilter/buffersink.h}.
3327
3328 It does not require a string parameter in input, but you need to
3329 specify a pointer to a list of supported pixel formats terminated by
3330 -1 in the opaque parameter provided to @code{avfilter_init_filter}
3331 when initializing this sink.
3332
3333 @section nullsink
3334
3335 Null video sink, do absolutely nothing with the input video. It is
3336 mainly useful as a template and to be employed in analysis / debugging
3337 tools.
3338
3339 @c man end VIDEO SINKS
3340