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