444949c660b7d72f4a50078229aba9e3f3471722
[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 @math{DAR = HORIZONTAL_RESOLUTION / VERTICAL_RESOLUTION * SAR}
2346
2347 Keep in mind that the @code{setdar} filter does not modify the pixel
2348 dimensions of the video frame. Also the display aspect ratio set by
2349 this filter may be changed by later filters in the filterchain,
2350 e.g. in case of scaling or if another "setdar" or a "setsar" filter is
2351 applied.
2352
2353 The @code{setsar} filter sets the Sample (aka Pixel) Aspect Ratio for
2354 the filter output video.
2355
2356 Note that as a consequence of the application of this filter, the
2357 output display aspect ratio will change according to the equation
2358 above.
2359
2360 Keep in mind that the sample aspect ratio set by the @code{setsar}
2361 filter may be changed by later filters in the filterchain, e.g. if
2362 another "setsar" or a "setdar" filter is applied.
2363
2364 The @code{setdar} and @code{setsar} filters accept a parameter string
2365 which represents the wanted aspect ratio.  The parameter can
2366 be a floating point number string, an expression, or a string of the form
2367 @var{num}:@var{den}, where @var{num} and @var{den} are the numerator
2368 and denominator of the aspect ratio. If the parameter is not
2369 specified, it is assumed the value "0:1".
2370
2371 For example to change the display aspect ratio to 16:9, specify:
2372 @example
2373 setdar=16:9
2374 # the above is equivalent to
2375 setdar=1.77777
2376 @end example
2377
2378 To change the sample aspect ratio to 10:11, specify:
2379 @example
2380 setsar=10:11
2381 @end example
2382
2383 @section setpts
2384
2385 Change the PTS (presentation timestamp) of the input video frames.
2386
2387 Accept in input an expression evaluated through the eval API, which
2388 can contain the following constants:
2389
2390 @table @option
2391 @item PTS
2392 the presentation timestamp in input
2393
2394 @item N
2395 the count of the input frame, starting from 0.
2396
2397 @item STARTPTS
2398 the PTS of the first video frame
2399
2400 @item INTERLACED
2401 tell if the current frame is interlaced
2402
2403 @item POS
2404 original position in the file of the frame, or undefined if undefined
2405 for the current frame
2406
2407 @item PREV_INPTS
2408 previous input PTS
2409
2410 @item PREV_OUTPTS
2411 previous output PTS
2412
2413 @end table
2414
2415 Some examples follow:
2416
2417 @example
2418 # start counting PTS from zero
2419 setpts=PTS-STARTPTS
2420
2421 # fast motion
2422 setpts=0.5*PTS
2423
2424 # slow motion
2425 setpts=2.0*PTS
2426
2427 # fixed rate 25 fps
2428 setpts=N/(25*TB)
2429
2430 # fixed rate 25 fps with some jitter
2431 setpts='1/(25*TB) * (N + 0.05 * sin(N*2*PI/25))'
2432 @end example
2433
2434 @section settb
2435
2436 Set the timebase to use for the output frames timestamps.
2437 It is mainly useful for testing timebase configuration.
2438
2439 It accepts in input an arithmetic expression representing a rational.
2440 The expression can contain the constants "AVTB" (the
2441 default timebase), and "intb" (the input timebase).
2442
2443 The default value for the input is "intb".
2444
2445 Follow some examples.
2446
2447 @example
2448 # set the timebase to 1/25
2449 settb=1/25
2450
2451 # set the timebase to 1/10
2452 settb=0.1
2453
2454 #set the timebase to 1001/1000
2455 settb=1+0.001
2456
2457 #set the timebase to 2*intb
2458 settb=2*intb
2459
2460 #set the default timebase value
2461 settb=AVTB
2462 @end example
2463
2464 @section showinfo
2465
2466 Show a line containing various information for each input video frame.
2467 The input video is not modified.
2468
2469 The shown line contains a sequence of key/value pairs of the form
2470 @var{key}:@var{value}.
2471
2472 A description of each shown parameter follows:
2473
2474 @table @option
2475 @item n
2476 sequential number of the input frame, starting from 0
2477
2478 @item pts
2479 Presentation TimeStamp of the input frame, expressed as a number of
2480 time base units. The time base unit depends on the filter input pad.
2481
2482 @item pts_time
2483 Presentation TimeStamp of the input frame, expressed as a number of
2484 seconds
2485
2486 @item pos
2487 position of the frame in the input stream, -1 if this information in
2488 unavailable and/or meaningless (for example in case of synthetic video)
2489
2490 @item fmt
2491 pixel format name
2492
2493 @item sar
2494 sample aspect ratio of the input frame, expressed in the form
2495 @var{num}/@var{den}
2496
2497 @item s
2498 size of the input frame, expressed in the form
2499 @var{width}x@var{height}
2500
2501 @item i
2502 interlaced mode ("P" for "progressive", "T" for top field first, "B"
2503 for bottom field first)
2504
2505 @item iskey
2506 1 if the frame is a key frame, 0 otherwise
2507
2508 @item type
2509 picture type of the input frame ("I" for an I-frame, "P" for a
2510 P-frame, "B" for a B-frame, "?" for unknown type).
2511 Check also the documentation of the @code{AVPictureType} enum and of
2512 the @code{av_get_picture_type_char} function defined in
2513 @file{libavutil/avutil.h}.
2514
2515 @item checksum
2516 Adler-32 checksum (printed in hexadecimal) of all the planes of the input frame
2517
2518 @item plane_checksum
2519 Adler-32 checksum (printed in hexadecimal) of each plane of the input frame,
2520 expressed in the form "[@var{c0} @var{c1} @var{c2} @var{c3}]"
2521 @end table
2522
2523 @section slicify
2524
2525 Pass the images of input video on to next video filter as multiple
2526 slices.
2527
2528 @example
2529 ffmpeg -i in.avi -vf "slicify=32" out.avi
2530 @end example
2531
2532 The filter accepts the slice height as parameter. If the parameter is
2533 not specified it will use the default value of 16.
2534
2535 Adding this in the beginning of filter chains should make filtering
2536 faster due to better use of the memory cache.
2537
2538 @section split
2539
2540 Pass on the input video to two outputs. Both outputs are identical to
2541 the input video.
2542
2543 For example:
2544 @example
2545 [in] split [splitout1][splitout2];
2546 [splitout1] crop=100:100:0:0    [cropout];
2547 [splitout2] pad=200:200:100:100 [padout];
2548 @end example
2549
2550 will create two separate outputs from the same input, one cropped and
2551 one padded.
2552
2553 @section thumbnail
2554 Select the most representative frame in a given sequence of consecutive frames.
2555
2556 It accepts as argument the frames batch size to analyze (default @var{N}=100);
2557 in a set of @var{N} frames, the filter will pick one of them, and then handle
2558 the next batch of @var{N} frames until the end.
2559
2560 Since the filter keeps track of the whole frames sequence, a bigger @var{N}
2561 value will result in a higher memory usage, so a high value is not recommended.
2562
2563 The following example extract one picture each 50 frames:
2564 @example
2565 thumbnail=50
2566 @end example
2567
2568 Complete example of a thumbnail creation with @command{ffmpeg}:
2569 @example
2570 ffmpeg -i in.avi -vf thumbnail,scale=300:200 -frames:v 1 out.png
2571 @end example
2572
2573 @section tinterlace
2574
2575 Perform various types of temporal field interlacing.
2576
2577 Frames are counted starting from 1, so the first input frame is
2578 considered odd.
2579
2580 This filter accepts a single parameter specifying the mode. Available
2581 modes are:
2582
2583 @table @samp
2584 @item 0
2585 Move odd frames into the upper field, even into the lower field,
2586 generating a double height frame at half framerate.
2587
2588 @item 1
2589 Only output even frames, odd frames are dropped, generating a frame with
2590 unchanged height at half framerate.
2591
2592 @item 2
2593 Only output odd frames, even frames are dropped, generating a frame with
2594 unchanged height at half framerate.
2595
2596 @item 3
2597 Expand each frame to full height, but pad alternate lines with black,
2598 generating a frame with double height at the same input framerate.
2599
2600 @item 4
2601 Interleave the upper field from odd frames with the lower field from
2602 even frames, generating a frame with unchanged height at half framerate.
2603
2604 @item 5
2605 Interleave the lower field from odd frames with the upper field from
2606 even frames, generating a frame with unchanged height at half framerate.
2607 @end table
2608
2609 Default mode is 0.
2610
2611 @section transpose
2612
2613 Transpose rows with columns in the input video and optionally flip it.
2614
2615 It accepts a parameter representing an integer, which can assume the
2616 values:
2617
2618 @table @samp
2619 @item 0
2620 Rotate by 90 degrees counterclockwise and vertically flip (default), that is:
2621 @example
2622 L.R     L.l
2623 . . ->  . .
2624 l.r     R.r
2625 @end example
2626
2627 @item 1
2628 Rotate by 90 degrees clockwise, that is:
2629 @example
2630 L.R     l.L
2631 . . ->  . .
2632 l.r     r.R
2633 @end example
2634
2635 @item 2
2636 Rotate by 90 degrees counterclockwise, that is:
2637 @example
2638 L.R     R.r
2639 . . ->  . .
2640 l.r     L.l
2641 @end example
2642
2643 @item 3
2644 Rotate by 90 degrees clockwise and vertically flip, that is:
2645 @example
2646 L.R     r.R
2647 . . ->  . .
2648 l.r     l.L
2649 @end example
2650 @end table
2651
2652 @section unsharp
2653
2654 Sharpen or blur the input video.
2655
2656 It accepts the following parameters:
2657 @var{luma_msize_x}:@var{luma_msize_y}:@var{luma_amount}:@var{chroma_msize_x}:@var{chroma_msize_y}:@var{chroma_amount}
2658
2659 Negative values for the amount will blur the input video, while positive
2660 values will sharpen. All parameters are optional and default to the
2661 equivalent of the string '5:5:1.0:5:5:0.0'.
2662
2663 @table @option
2664
2665 @item luma_msize_x
2666 Set the luma matrix horizontal size. It can be an integer between 3
2667 and 13, default value is 5.
2668
2669 @item luma_msize_y
2670 Set the luma matrix vertical size. It can be an integer between 3
2671 and 13, default value is 5.
2672
2673 @item luma_amount
2674 Set the luma effect strength. It can be a float number between -2.0
2675 and 5.0, default value is 1.0.
2676
2677 @item chroma_msize_x
2678 Set the chroma matrix horizontal size. It can be an integer between 3
2679 and 13, default value is 5.
2680
2681 @item chroma_msize_y
2682 Set the chroma matrix vertical size. It can be an integer between 3
2683 and 13, default value is 5.
2684
2685 @item chroma_amount
2686 Set the chroma effect strength. It can be a float number between -2.0
2687 and 5.0, default value is 0.0.
2688
2689 @end table
2690
2691 @example
2692 # Strong luma sharpen effect parameters
2693 unsharp=7:7:2.5
2694
2695 # Strong blur of both luma and chroma parameters
2696 unsharp=7:7:-2:7:7:-2
2697
2698 # Use the default values with @command{ffmpeg}
2699 ffmpeg -i in.avi -vf "unsharp" out.mp4
2700 @end example
2701
2702 @section vflip
2703
2704 Flip the input video vertically.
2705
2706 @example
2707 ffmpeg -i in.avi -vf "vflip" out.avi
2708 @end example
2709
2710 @section yadif
2711
2712 Deinterlace the input video ("yadif" means "yet another deinterlacing
2713 filter").
2714
2715 It accepts the optional parameters: @var{mode}:@var{parity}:@var{auto}.
2716
2717 @var{mode} specifies the interlacing mode to adopt, accepts one of the
2718 following values:
2719
2720 @table @option
2721 @item 0
2722 output 1 frame for each frame
2723 @item 1
2724 output 1 frame for each field
2725 @item 2
2726 like 0 but skips spatial interlacing check
2727 @item 3
2728 like 1 but skips spatial interlacing check
2729 @end table
2730
2731 Default value is 0.
2732
2733 @var{parity} specifies the picture field parity assumed for the input
2734 interlaced video, accepts one of the following values:
2735
2736 @table @option
2737 @item 0
2738 assume top field first
2739 @item 1
2740 assume bottom field first
2741 @item -1
2742 enable automatic detection
2743 @end table
2744
2745 Default value is -1.
2746 If interlacing is unknown or decoder does not export this information,
2747 top field first will be assumed.
2748
2749 @var{auto} specifies if deinterlacer should trust the interlaced flag
2750 and only deinterlace frames marked as interlaced
2751
2752 @table @option
2753 @item 0
2754 deinterlace all frames
2755 @item 1
2756 only deinterlace frames marked as interlaced
2757 @end table
2758
2759 Default value is 0.
2760
2761 @c man end VIDEO FILTERS
2762
2763 @chapter Video Sources
2764 @c man begin VIDEO SOURCES
2765
2766 Below is a description of the currently available video sources.
2767
2768 @section buffer
2769
2770 Buffer video frames, and make them available to the filter chain.
2771
2772 This source is mainly intended for a programmatic use, in particular
2773 through the interface defined in @file{libavfilter/vsrc_buffer.h}.
2774
2775 It accepts the following parameters:
2776 @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}
2777
2778 All the parameters but @var{scale_params} need to be explicitly
2779 defined.
2780
2781 Follows the list of the accepted parameters.
2782
2783 @table @option
2784
2785 @item width, height
2786 Specify the width and height of the buffered video frames.
2787
2788 @item pix_fmt_string
2789 A string representing the pixel format of the buffered video frames.
2790 It may be a number corresponding to a pixel format, or a pixel format
2791 name.
2792
2793 @item timebase_num, timebase_den
2794 Specify numerator and denomitor of the timebase assumed by the
2795 timestamps of the buffered frames.
2796
2797 @item sample_aspect_ratio.num, sample_aspect_ratio.den
2798 Specify numerator and denominator of the sample aspect ratio assumed
2799 by the video frames.
2800
2801 @item scale_params
2802 Specify the optional parameters to be used for the scale filter which
2803 is automatically inserted when an input change is detected in the
2804 input size or format.
2805 @end table
2806
2807 For example:
2808 @example
2809 buffer=320:240:yuv410p:1:24:1:1
2810 @end example
2811
2812 will instruct the source to accept video frames with size 320x240 and
2813 with format "yuv410p", assuming 1/24 as the timestamps timebase and
2814 square pixels (1:1 sample aspect ratio).
2815 Since the pixel format with name "yuv410p" corresponds to the number 6
2816 (check the enum PixelFormat definition in @file{libavutil/pixfmt.h}),
2817 this example corresponds to:
2818 @example
2819 buffer=320:240:6:1:24:1:1
2820 @end example
2821
2822 @section cellauto
2823
2824 Create a pattern generated by an elementary cellular automaton.
2825
2826 The initial state of the cellular automaton can be defined through the
2827 @option{filename}, and @option{pattern} options. If such options are
2828 not specified an initial state is created randomly.
2829
2830 At each new frame a new row in the video is filled with the result of
2831 the cellular automaton next generation. The behavior when the whole
2832 frame is filled is defined by the @option{scroll} option.
2833
2834 This source accepts a list of options in the form of
2835 @var{key}=@var{value} pairs separated by ":". A description of the
2836 accepted options follows.
2837
2838 @table @option
2839 @item filename, f
2840 Read the initial cellular automaton state, i.e. the starting row, from
2841 the specified file.
2842 In the file, each non-whitespace character is considered an alive
2843 cell, a newline will terminate the row, and further characters in the
2844 file will be ignored.
2845
2846 @item pattern, p
2847 Read the initial cellular automaton state, i.e. the starting row, from
2848 the specified string.
2849
2850 Each non-whitespace character in the string is considered an alive
2851 cell, a newline will terminate the row, and further characters in the
2852 string will be ignored.
2853
2854 @item rate, r
2855 Set the video rate, that is the number of frames generated per second.
2856 Default is 25.
2857
2858 @item random_fill_ratio, ratio
2859 Set the random fill ratio for the initial cellular automaton row. It
2860 is a floating point number value ranging from 0 to 1, defaults to
2861 1/PHI.
2862
2863 This option is ignored when a file or a pattern is specified.
2864
2865 @item random_seed, seed
2866 Set the seed for filling randomly the initial row, must be an integer
2867 included between 0 and UINT32_MAX. If not specified, or if explicitly
2868 set to -1, the filter will try to use a good random seed on a best
2869 effort basis.
2870
2871 @item rule
2872 Set the cellular automaton rule, it is a number ranging from 0 to 255.
2873 Default value is 110.
2874
2875 @item size, s
2876 Set the size of the output video.
2877
2878 If @option{filename} or @option{pattern} is specified, the size is set
2879 by default to the width of the specified initial state row, and the
2880 height is set to @var{width} * PHI.
2881
2882 If @option{size} is set, it must contain the width of the specified
2883 pattern string, and the specified pattern will be centered in the
2884 larger row.
2885
2886 If a filename or a pattern string is not specified, the size value
2887 defaults to "320x518" (used for a randomly generated initial state).
2888
2889 @item scroll
2890 If set to 1, scroll the output upward when all the rows in the output
2891 have been already filled. If set to 0, the new generated row will be
2892 written over the top row just after the bottom row is filled.
2893 Defaults to 1.
2894
2895 @item start_full, full
2896 If set to 1, completely fill the output with generated rows before
2897 outputting the first frame.
2898 This is the default behavior, for disabling set the value to 0.
2899
2900 @item stitch
2901 If set to 1, stitch the left and right row edges together.
2902 This is the default behavior, for disabling set the value to 0.
2903 @end table
2904
2905 @subsection Examples
2906
2907 @itemize
2908 @item
2909 Read the initial state from @file{pattern}, and specify an output of
2910 size 200x400.
2911 @example
2912 cellauto=f=pattern:s=200x400
2913 @end example
2914
2915 @item
2916 Generate a random initial row with a width of 200 cells, with a fill
2917 ratio of 2/3:
2918 @example
2919 cellauto=ratio=2/3:s=200x200
2920 @end example
2921
2922 @item
2923 Create a pattern generated by rule 18 starting by a single alive cell
2924 centered on an initial row with width 100:
2925 @example
2926 cellauto=p=@@:s=100x400:full=0:rule=18
2927 @end example
2928
2929 @item
2930 Specify a more elaborated initial pattern:
2931 @example
2932 cellauto=p='@@@@ @@ @@@@':s=100x400:full=0:rule=18
2933 @end example
2934
2935 @end itemize
2936
2937 @section color
2938
2939 Provide an uniformly colored input.
2940
2941 It accepts the following parameters:
2942 @var{color}:@var{frame_size}:@var{frame_rate}
2943
2944 Follows the description of the accepted parameters.
2945
2946 @table @option
2947
2948 @item color
2949 Specify the color of the source. It can be the name of a color (case
2950 insensitive match) or a 0xRRGGBB[AA] sequence, possibly followed by an
2951 alpha specifier. The default value is "black".
2952
2953 @item frame_size
2954 Specify the size of the sourced video, it may be a string of the form
2955 @var{width}x@var{height}, or the name of a size abbreviation. The
2956 default value is "320x240".
2957
2958 @item frame_rate
2959 Specify the frame rate of the sourced video, as the number of frames
2960 generated per second. It has to be a string in the format
2961 @var{frame_rate_num}/@var{frame_rate_den}, an integer number, a float
2962 number or a valid video frame rate abbreviation. The default value is
2963 "25".
2964
2965 @end table
2966
2967 For example the following graph description will generate a red source
2968 with an opacity of 0.2, with size "qcif" and a frame rate of 10
2969 frames per second, which will be overlayed over the source connected
2970 to the pad with identifier "in".
2971
2972 @example
2973 "color=red@@0.2:qcif:10 [color]; [in][color] overlay [out]"
2974 @end example
2975
2976 @section movie
2977
2978 Read a video stream from a movie container.
2979
2980 It accepts the syntax: @var{movie_name}[:@var{options}] where
2981 @var{movie_name} is the name of the resource to read (not necessarily
2982 a file but also a device or a stream accessed through some protocol),
2983 and @var{options} is an optional sequence of @var{key}=@var{value}
2984 pairs, separated by ":".
2985
2986 The description of the accepted options follows.
2987
2988 @table @option
2989
2990 @item format_name, f
2991 Specifies the format assumed for the movie to read, and can be either
2992 the name of a container or an input device. If not specified the
2993 format is guessed from @var{movie_name} or by probing.
2994
2995 @item seek_point, sp
2996 Specifies the seek point in seconds, the frames will be output
2997 starting from this seek point, the parameter is evaluated with
2998 @code{av_strtod} so the numerical value may be suffixed by an IS
2999 postfix. Default value is "0".
3000
3001 @item stream_index, si
3002 Specifies the index of the video stream to read. If the value is -1,
3003 the best suited video stream will be automatically selected. Default
3004 value is "-1".
3005
3006 @end table
3007
3008 This filter allows to overlay a second video on top of main input of
3009 a filtergraph as shown in this graph:
3010 @example
3011 input -----------> deltapts0 --> overlay --> output
3012                                     ^
3013                                     |
3014 movie --> scale--> deltapts1 -------+
3015 @end example
3016
3017 Some examples follow:
3018 @example
3019 # skip 3.2 seconds from the start of the avi file in.avi, and overlay it
3020 # on top of the input labelled as "in".
3021 movie=in.avi:seek_point=3.2, scale=180:-1, setpts=PTS-STARTPTS [movie];
3022 [in] setpts=PTS-STARTPTS, [movie] overlay=16:16 [out]
3023
3024 # read from a video4linux2 device, and overlay it on top of the input
3025 # labelled as "in"
3026 movie=/dev/video0:f=video4linux2, scale=180:-1, setpts=PTS-STARTPTS [movie];
3027 [in] setpts=PTS-STARTPTS, [movie] overlay=16:16 [out]
3028
3029 @end example
3030
3031 @section mptestsrc
3032
3033 Generate various test patterns, as generated by the MPlayer test filter.
3034
3035 The size of the generated video is fixed, and is 256x256.
3036 This source is useful in particular for testing encoding features.
3037
3038 This source accepts an optional sequence of @var{key}=@var{value} pairs,
3039 separated by ":". The description of the accepted options follows.
3040
3041 @table @option
3042
3043 @item rate, r
3044 Specify the frame rate of the sourced video, as the number of frames
3045 generated per second. It has to be a string in the format
3046 @var{frame_rate_num}/@var{frame_rate_den}, an integer number, a float
3047 number or a valid video frame rate abbreviation. The default value is
3048 "25".
3049
3050 @item duration, d
3051 Set the video duration of the sourced video. The accepted syntax is:
3052 @example
3053 [-]HH[:MM[:SS[.m...]]]
3054 [-]S+[.m...]
3055 @end example
3056 See also the function @code{av_parse_time()}.
3057
3058 If not specified, or the expressed duration is negative, the video is
3059 supposed to be generated forever.
3060
3061 @item test, t
3062
3063 Set the number or the name of the test to perform. Supported tests are:
3064 @table @option
3065 @item dc_luma
3066 @item dc_chroma
3067 @item freq_luma
3068 @item freq_chroma
3069 @item amp_luma
3070 @item amp_chroma
3071 @item cbp
3072 @item mv
3073 @item ring1
3074 @item ring2
3075 @item all
3076 @end table
3077
3078 Default value is "all", which will cycle through the list of all tests.
3079 @end table
3080
3081 For example the following:
3082 @example
3083 testsrc=t=dc_luma
3084 @end example
3085
3086 will generate a "dc_luma" test pattern.
3087
3088 @section frei0r_src
3089
3090 Provide a frei0r source.
3091
3092 To enable compilation of this filter you need to install the frei0r
3093 header and configure FFmpeg with @code{--enable-frei0r}.
3094
3095 The source supports the syntax:
3096 @example
3097 @var{size}:@var{rate}:@var{src_name}[@{=|:@}@var{param1}:@var{param2}:...:@var{paramN}]
3098 @end example
3099
3100 @var{size} is the size of the video to generate, may be a string of the
3101 form @var{width}x@var{height} or a frame size abbreviation.
3102 @var{rate} is the rate of the video to generate, may be a string of
3103 the form @var{num}/@var{den} or a frame rate abbreviation.
3104 @var{src_name} is the name to the frei0r source to load. For more
3105 information regarding frei0r and how to set the parameters read the
3106 section @ref{frei0r} in the description of the video filters.
3107
3108 Some examples follow:
3109 @example
3110 # generate a frei0r partik0l source with size 200x200 and frame rate 10
3111 # which is overlayed on the overlay filter main input
3112 frei0r_src=200x200:10:partik0l=1234 [overlay]; [in][overlay] overlay
3113 @end example
3114
3115 @section life
3116
3117 Generate a life pattern.
3118
3119 This source is based on a generalization of John Conway's life game.
3120
3121 The sourced input represents a life grid, each pixel represents a cell
3122 which can be in one of two possible states, alive or dead. Every cell
3123 interacts with its eight neighbours, which are the cells that are
3124 horizontally, vertically, or diagonally adjacent.
3125
3126 At each interaction the grid evolves according to the adopted rule,
3127 which specifies the number of neighbor alive cells which will make a
3128 cell stay alive or born. The @option{rule} option allows to specify
3129 the rule to adopt.
3130
3131 This source accepts a list of options in the form of
3132 @var{key}=@var{value} pairs separated by ":". A description of the
3133 accepted options follows.
3134
3135 @table @option
3136 @item filename, f
3137 Set the file from which to read the initial grid state. In the file,
3138 each non-whitespace character is considered an alive cell, and newline
3139 is used to delimit the end of each row.
3140
3141 If this option is not specified, the initial grid is generated
3142 randomly.
3143
3144 @item rate, r
3145 Set the video rate, that is the number of frames generated per second.
3146 Default is 25.
3147
3148 @item random_fill_ratio, ratio
3149 Set the random fill ratio for the initial random grid. It is a
3150 floating point number value ranging from 0 to 1, defaults to 1/PHI.
3151 It is ignored when a file is specified.
3152
3153 @item random_seed, seed
3154 Set the seed for filling the initial random grid, must be an integer
3155 included between 0 and UINT32_MAX. If not specified, or if explicitly
3156 set to -1, the filter will try to use a good random seed on a best
3157 effort basis.
3158
3159 @item rule
3160 Set the life rule.
3161
3162 A rule can be specified with a code of the kind "S@var{NS}/B@var{NB}",
3163 where @var{NS} and @var{NB} are sequences of numbers in the range 0-8,
3164 @var{NS} specifies the number of alive neighbor cells which make a
3165 live cell stay alive, and @var{NB} the number of alive neighbor cells
3166 which make a dead cell to become alive (i.e. to "born").
3167 "s" and "b" can be used in place of "S" and "B", respectively.
3168
3169 Alternatively a rule can be specified by an 18-bits integer. The 9
3170 high order bits are used to encode the next cell state if it is alive
3171 for each number of neighbor alive cells, the low order bits specify
3172 the rule for "borning" new cells. Higher order bits encode for an
3173 higher number of neighbor cells.
3174 For example the number 6153 = @code{(12<<9)+9} specifies a stay alive
3175 rule of 12 and a born rule of 9, which corresponds to "S23/B03".
3176
3177 Default value is "S23/B3", which is the original Conway's game of life
3178 rule, and will keep a cell alive if it has 2 or 3 neighbor alive
3179 cells, and will born a new cell if there are three alive cells around
3180 a dead cell.
3181
3182 @item size, s
3183 Set the size of the output video.
3184
3185 If @option{filename} is specified, the size is set by default to the
3186 same size of the input file. If @option{size} is set, it must contain
3187 the size specified in the input file, and the initial grid defined in
3188 that file is centered in the larger resulting area.
3189
3190 If a filename is not specified, the size value defaults to "320x240"
3191 (used for a randomly generated initial grid).
3192
3193 @item stitch
3194 If set to 1, stitch the left and right grid edges together, and the
3195 top and bottom edges also. Defaults to 1.
3196
3197 @item mold
3198 Set cell mold speed. If set, a dead cell will go from @option{death_color} to
3199 @option{mold_color} with a step of @option{mold}. @option{mold} can have a
3200 value from 0 to 255.
3201
3202 @item life_color
3203 Set the color of living (or new born) cells.
3204
3205 @item death_color
3206 Set the color of dead cells. If @option{mold} is set, this is the first color
3207 used to represent a dead cell.
3208
3209 @item mold_color
3210 Set mold color, for definitely dead and moldy cells.
3211 @end table
3212
3213 @subsection Examples
3214
3215 @itemize
3216 @item
3217 Read a grid from @file{pattern}, and center it on a grid of size
3218 300x300 pixels:
3219 @example
3220 life=f=pattern:s=300x300
3221 @end example
3222
3223 @item
3224 Generate a random grid of size 200x200, with a fill ratio of 2/3:
3225 @example
3226 life=ratio=2/3:s=200x200
3227 @end example
3228
3229 @item
3230 Specify a custom rule for evolving a randomly generated grid:
3231 @example
3232 life=rule=S14/B34
3233 @end example
3234
3235 @item
3236 Full example with slow death effect (mold) using @command{ffplay}:
3237 @example
3238 ffplay -f lavfi life=s=300x200:mold=10:r=60:ratio=0.1:death_color=#C83232:life_color=#00ff00,scale=1200:800:flags=16
3239 @end example
3240 @end itemize
3241
3242 @section nullsrc, rgbtestsrc, testsrc
3243
3244 The @code{nullsrc} source returns unprocessed video frames. It is
3245 mainly useful to be employed in analysis / debugging tools, or as the
3246 source for filters which ignore the input data.
3247
3248 The @code{rgbtestsrc} source generates an RGB test pattern useful for
3249 detecting RGB vs BGR issues. You should see a red, green and blue
3250 stripe from top to bottom.
3251
3252 The @code{testsrc} source generates a test video pattern, showing a
3253 color pattern, a scrolling gradient and a timestamp. This is mainly
3254 intended for testing purposes.
3255
3256 These sources accept an optional sequence of @var{key}=@var{value} pairs,
3257 separated by ":". The description of the accepted options follows.
3258
3259 @table @option
3260
3261 @item size, s
3262 Specify the size of the sourced video, it may be a string of the form
3263 @var{width}x@var{height}, or the name of a size abbreviation. The
3264 default value is "320x240".
3265
3266 @item rate, r
3267 Specify the frame rate of the sourced video, as the number of frames
3268 generated per second. It has to be a string in the format
3269 @var{frame_rate_num}/@var{frame_rate_den}, an integer number, a float
3270 number or a valid video frame rate abbreviation. The default value is
3271 "25".
3272
3273 @item sar
3274 Set the sample aspect ratio of the sourced video.
3275
3276 @item duration, d
3277 Set the video duration of the sourced video. The accepted syntax is:
3278 @example
3279 [-]HH[:MM[:SS[.m...]]]
3280 [-]S+[.m...]
3281 @end example
3282 See also the function @code{av_parse_time()}.
3283
3284 If not specified, or the expressed duration is negative, the video is
3285 supposed to be generated forever.
3286
3287 @item decimals, n
3288 Set the number of decimals to show in the timestamp, only used in the
3289 @code{testsrc} source.
3290
3291 The displayed timestamp value will correspond to the original
3292 timestamp value multiplied by the power of 10 of the specified
3293 value. Default value is 0.
3294 @end table
3295
3296 For example the following:
3297 @example
3298 testsrc=duration=5.3:size=qcif:rate=10
3299 @end example
3300
3301 will generate a video with a duration of 5.3 seconds, with size
3302 176x144 and a frame rate of 10 frames per second.
3303
3304 If the input content is to be ignored, @code{nullsrc} can be used. The
3305 following command generates noise in the luminance plane by employing
3306 the @code{mp=geq} filter:
3307 @example
3308 nullsrc=s=256x256, mp=geq=random(1)*255:128:128
3309 @end example
3310
3311 @c man end VIDEO SOURCES
3312
3313 @chapter Video Sinks
3314 @c man begin VIDEO SINKS
3315
3316 Below is a description of the currently available video sinks.
3317
3318 @section buffersink
3319
3320 Buffer video frames, and make them available to the end of the filter
3321 graph.
3322
3323 This sink is mainly intended for a programmatic use, in particular
3324 through the interface defined in @file{libavfilter/buffersink.h}.
3325
3326 It does not require a string parameter in input, but you need to
3327 specify a pointer to a list of supported pixel formats terminated by
3328 -1 in the opaque parameter provided to @code{avfilter_init_filter}
3329 when initializing this sink.
3330
3331 @section nullsink
3332
3333 Null video sink, do absolutely nothing with the input video. It is
3334 mainly useful as a template and to be employed in analysis / debugging
3335 tools.
3336
3337 @c man end VIDEO SINKS
3338