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