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