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