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