doc: use @command{} for commands.
[ffmpeg.git] / doc / filters.texi
1 @chapter Filtergraph description
2 @c man begin FILTERGRAPH DESCRIPTION
3
4 A filtergraph is a directed graph of connected filters. It can contain
5 cycles, and there can be multiple links between a pair of
6 filters. Each link has one input pad on one side connecting it to one
7 filter from which it takes its input, and one output pad on the other
8 side connecting it to the one filter accepting its output.
9
10 Each filter in a filtergraph is an instance of a filter class
11 registered in the application, which defines the features and the
12 number of input and output pads of the filter.
13
14 A filter with no input pads is called a "source", a filter with no
15 output pads is called a "sink".
16
17 @section Filtergraph syntax
18
19 A filtergraph can be represented using a textual representation, which
20 is recognized by the @code{-vf} option of the ff*
21 tools, and by the @code{avfilter_graph_parse()} function defined in
22 @file{libavfilter/avfiltergraph.h}.
23
24 A filterchain consists of a sequence of connected filters, each one
25 connected to the previous one in the sequence. A filterchain is
26 represented by a list of ","-separated filter descriptions.
27
28 A filtergraph consists of a sequence of filterchains. A sequence of
29 filterchains is represented by a list of ";"-separated filterchain
30 descriptions.
31
32 A filter is represented by a string of the form:
33 [@var{in_link_1}]...[@var{in_link_N}]@var{filter_name}=@var{arguments}[@var{out_link_1}]...[@var{out_link_M}]
34
35 @var{filter_name} is the name of the filter class of which the
36 described filter is an instance of, and has to be the name of one of
37 the filter classes registered in the program.
38 The name of the filter class is optionally followed by a string
39 "=@var{arguments}".
40
41 @var{arguments} is a string which contains the parameters used to
42 initialize the filter instance, and are described in the filter
43 descriptions below.
44
45 The list of arguments can be quoted using the character "'" as initial
46 and ending mark, and the character '\' for escaping the characters
47 within the quoted text; otherwise the argument string is considered
48 terminated when the next special character (belonging to the set
49 "[]=;,") is encountered.
50
51 The name and arguments of the filter are optionally preceded and
52 followed by a list of link labels.
53 A link label allows to name a link and associate it to a filter output
54 or input pad. The preceding labels @var{in_link_1}
55 ... @var{in_link_N}, are associated to the filter input pads,
56 the following labels @var{out_link_1} ... @var{out_link_M}, are
57 associated to the output pads.
58
59 When two link labels with the same name are found in the
60 filtergraph, a link between the corresponding input and output pad is
61 created.
62
63 If an output pad is not labelled, it is linked by default to the first
64 unlabelled input pad of the next filter in the filterchain.
65 For example in the filterchain:
66 @example
67 nullsrc, split[L1], [L2]overlay, nullsink
68 @end example
69 the split filter instance has two output pads, and the overlay filter
70 instance two input pads. The first output pad of split is labelled
71 "L1", the first input pad of overlay is labelled "L2", and the second
72 output pad of split is linked to the second input pad of overlay,
73 which are both unlabelled.
74
75 In a complete filterchain all the unlabelled filter input and output
76 pads must be connected. A filtergraph is considered valid if all the
77 filter input and output pads of all the filterchains are connected.
78
79 Follows a BNF description for the filtergraph syntax:
80 @example
81 @var{NAME}             ::= sequence of alphanumeric characters and '_'
82 @var{LINKLABEL}        ::= "[" @var{NAME} "]"
83 @var{LINKLABELS}       ::= @var{LINKLABEL} [@var{LINKLABELS}]
84 @var{FILTER_ARGUMENTS} ::= sequence of chars (eventually quoted)
85 @var{FILTER}           ::= [@var{LINKNAMES}] @var{NAME} ["=" @var{ARGUMENTS}] [@var{LINKNAMES}]
86 @var{FILTERCHAIN}      ::= @var{FILTER} [,@var{FILTERCHAIN}]
87 @var{FILTERGRAPH}      ::= @var{FILTERCHAIN} [;@var{FILTERGRAPH}]
88 @end example
89
90 @c man end FILTERGRAPH DESCRIPTION
91
92 @chapter Audio Filters
93 @c man begin AUDIO FILTERS
94
95 When you configure your FFmpeg build, you can disable any of the
96 existing filters using @code{--disable-filters}.
97 The configure output will show the audio filters included in your
98 build.
99
100 Below is a description of the currently available audio filters.
101
102 @section aconvert
103
104 Convert the input audio format to the specified formats.
105
106 The filter accepts a string of the form:
107 "@var{sample_format}:@var{channel_layout}:@var{packing_format}".
108
109 @var{sample_format} specifies the sample format, and can be a string or
110 the corresponding numeric value defined in @file{libavutil/samplefmt.h}.
111
112 @var{channel_layout} specifies the channel layout, and can be a string
113 or the corresponding number value defined in @file{libavutil/audioconvert.h}.
114
115 @var{packing_format} specifies the type of packing in output, can be one
116 of "planar" or "packed", or the corresponding numeric values "0" or "1".
117
118 The special parameter "auto", signifies that the filter will
119 automatically select the output format depending on the output filter.
120
121 Some examples follow.
122
123 @itemize
124 @item
125 Convert input to unsigned 8-bit, stereo, packed:
126 @example
127 aconvert=u8:stereo:packed
128 @end example
129
130 @item
131 Convert input to unsigned 8-bit, automatically select out channel layout
132 and packing format:
133 @example
134 aconvert=u8:auto:auto
135 @end example
136 @end itemize
137
138 @section aformat
139
140 Convert the input audio to one of the specified formats. The framework will
141 negotiate the most appropriate format to minimize conversions.
142
143 The filter accepts three lists of formats, separated by ":", in the form:
144 "@var{sample_formats}:@var{channel_layouts}:@var{packing_formats}".
145
146 Elements in each list are separated by "," which has to be escaped in the
147 filtergraph specification.
148
149 The special parameter "all", in place of a list of elements, signifies all
150 supported formats.
151
152 Some examples follow:
153 @example
154 aformat=u8\\,s16:mono:packed
155
156 aformat=s16:mono\\,stereo:all
157 @end example
158
159 @section amerge
160
161 Merge two audio streams into a single multi-channel stream.
162
163 This filter does not need any argument.
164
165 If the channel layouts of the inputs are disjoint, and therefore compatible,
166 the channel layout of the output will be set accordingly and the channels
167 will be reordered as necessary. If the channel layouts of the inputs are not
168 disjoint, the output will have all the channels of the first input then all
169 the channels of the second input, in that order, and the channel layout of
170 the output will be the default value corresponding to the total number of
171 channels.
172
173 For example, if the first input is in 2.1 (FL+FR+LF) and the second input
174 is FC+BL+BR, then the output will be in 5.1, with the channels in the
175 following order: a1, a2, b1, a3, b2, b3 (a1 is the first channel of the
176 first input, b1 is the first channel of the second input).
177
178 On the other hand, if both input are in stereo, the output channels will be
179 in the default order: a1, a2, b1, b2, and the channel layout will be
180 arbitrarily set to 4.0, which may or may not be the expected value.
181
182 Both inputs must have the same sample rate, format and packing.
183
184 If inputs do not have the same duration, the output will stop with the
185 shortest.
186
187 Example: merge two mono files into a stereo stream:
188 @example
189 amovie=left.wav [l] ; amovie=right.mp3 [r] ; [l] [r] amerge
190 @end example
191
192 @section anull
193
194 Pass the audio source unchanged to the output.
195
196 @section aresample
197
198 Resample the input audio to the specified sample rate.
199
200 The filter accepts exactly one parameter, the output sample rate. If not
201 specified then the filter will automatically convert between its input
202 and output sample rates.
203
204 For example, to resample the input audio to 44100Hz:
205 @example
206 aresample=44100
207 @end example
208
209 @section ashowinfo
210
211 Show a line containing various information for each input audio frame.
212 The input audio is not modified.
213
214 The shown line contains a sequence of key/value pairs of the form
215 @var{key}:@var{value}.
216
217 A description of each shown parameter follows:
218
219 @table @option
220 @item n
221 sequential number of the input frame, starting from 0
222
223 @item pts
224 presentation TimeStamp of the input frame, expressed as a number of
225 time base units. The time base unit depends on the filter input pad, and
226 is usually 1/@var{sample_rate}.
227
228 @item pts_time
229 presentation TimeStamp of the input frame, expressed as a number of
230 seconds
231
232 @item pos
233 position of the frame in the input stream, -1 if this information in
234 unavailable and/or meaningless (for example in case of synthetic audio)
235
236 @item fmt
237 sample format name
238
239 @item chlayout
240 channel layout description
241
242 @item nb_samples
243 number of samples (per each channel) contained in the filtered frame
244
245 @item rate
246 sample rate for the audio frame
247
248 @item planar
249 if the packing format is planar, 0 if packed
250
251 @item checksum
252 Adler-32 checksum (printed in hexadecimal) of all the planes of the input frame
253
254 @item plane_checksum
255 Adler-32 checksum (printed in hexadecimal) for each input frame plane,
256 expressed in the form "[@var{c0} @var{c1} @var{c2} @var{c3} @var{c4} @var{c5}
257 @var{c6} @var{c7}]"
258 @end table
259
260 @section asplit
261
262 Pass on the input audio to two outputs. Both outputs are identical to
263 the input audio.
264
265 For example:
266 @example
267 [in] asplit[out0], showaudio[out1]
268 @end example
269
270 will create two separate outputs from the same input, one cropped and
271 one padded.
272
273 @section astreamsync
274
275 Forward two audio streams and control the order the buffers are forwarded.
276
277 The argument to the filter is an expression deciding which stream should be
278 forwarded next: if the result is negative, the first stream is forwarded; if
279 the result is positive or zero, the second stream is forwarded. It can use
280 the following variables:
281
282 @table @var
283 @item b1 b2
284 number of buffers forwarded so far on each stream
285 @item s1 s2
286 number of samples forwarded so far on each stream
287 @item t1 t2
288 current timestamp of each stream
289 @end table
290
291 The default value is @code{t1-t2}, which means to always forward the stream
292 that has a smaller timestamp.
293
294 Example: stress-test @code{amerge} by randomly sending buffers on the wrong
295 input, while avoiding too much of a desynchronization:
296 @example
297 amovie=file.ogg [a] ; amovie=file.mp3 [b] ;
298 [a] [b] astreamsync=(2*random(1))-1+tanh(5*(t1-t2)) [a2] [b2] ;
299 [a2] [b2] amerge
300 @end example
301
302 @section earwax
303
304 Make audio easier to listen to on headphones.
305
306 This filter adds `cues' to 44.1kHz stereo (i.e. audio CD format) audio
307 so that when listened to on headphones the stereo image is moved from
308 inside your head (standard for headphones) to outside and in front of
309 the listener (standard for speakers).
310
311 Ported from SoX.
312
313 @section pan
314
315 Mix channels with specific gain levels. The filter accepts the output
316 channel layout followed by a set of channels definitions.
317
318 The filter accepts parameters of the form:
319 "@var{l}:@var{outdef}:@var{outdef}:..."
320
321 @table @option
322 @item l
323 output channel layout or number of channels
324
325 @item outdef
326 output channel specification, of the form:
327 "@var{out_name}=[@var{gain}*]@var{in_name}[+[@var{gain}*]@var{in_name}...]"
328
329 @item out_name
330 output channel to define, either a channel name (FL, FR, etc.) or a channel
331 number (c0, c1, etc.)
332
333 @item gain
334 multiplicative coefficient for the channel, 1 leaving the volume unchanged
335
336 @item in_name
337 input channel to use, see out_name for details; it is not possible to mix
338 named and numbered input channels
339 @end table
340
341 If the `=' in a channel specification is replaced by `<', then the gains for
342 that specification will be renormalized so that the total is 1, thus
343 avoiding clipping noise.
344
345 For example, if you want to down-mix from stereo to mono, but with a bigger
346 factor for the left channel:
347 @example
348 pan=1:c0=0.9*c0+0.1*c1
349 @end example
350
351 A customized down-mix to stereo that works automatically for 3-, 4-, 5- and
352 7-channels surround:
353 @example
354 pan=stereo: FL < FL + 0.5*FC + 0.6*BL + 0.6*SL : FR < FR + 0.5*FC + 0.6*BR + 0.6*SR
355 @end example
356
357 Note that @command{ffmpeg} integrates a default down-mix (and up-mix) system
358 that should be preferred (see "-ac" option) unless you have very specific
359 needs.
360
361 @section 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 @code{--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 Note that timecode options are @emph{not} effective if FFmpeg is build with
1231 @code{--disable-avcodec}.
1232
1233 @item r, rate
1234 frame rate (timecode only)
1235 @end table
1236
1237 Some examples follow.
1238
1239 @itemize
1240
1241 @item
1242 Draw "Test Text" with font FreeSerif, using the default values for the
1243 optional parameters.
1244
1245 @example
1246 drawtext="fontfile=/usr/share/fonts/truetype/freefont/FreeSerif.ttf: text='Test Text'"
1247 @end example
1248
1249 @item
1250 Draw 'Test Text' with font FreeSerif of size 24 at position x=100
1251 and y=50 (counting from the top-left corner of the screen), text is
1252 yellow with a red box around it. Both the text and the box have an
1253 opacity of 20%.
1254
1255 @example
1256 drawtext="fontfile=/usr/share/fonts/truetype/freefont/FreeSerif.ttf: text='Test Text':\
1257           x=100: y=50: fontsize=24: fontcolor=yellow@@0.2: box=1: boxcolor=red@@0.2"
1258 @end example
1259
1260 Note that the double quotes are not necessary if spaces are not used
1261 within the parameter list.
1262
1263 @item
1264 Show the text at the center of the video frame:
1265 @example
1266 drawtext=fontsize=30:fontfile=FreeSerif.ttf:text='hello world':x=(w-text_w)/2:y=(h-text_h-line_h)/2"
1267 @end example
1268
1269 @item
1270 Show a text line sliding from right to left in the last row of the video
1271 frame. The file @file{LONG_LINE} is assumed to contain a single line
1272 with no newlines.
1273 @example
1274 drawtext=fontsize=15:fontfile=FreeSerif.ttf:text=LONG_LINE:y=h-line_h:x=-50*t
1275 @end example
1276
1277 @item
1278 Show the content of file @file{CREDITS} off the bottom of the frame and scroll up.
1279 @example
1280 drawtext=fontsize=20:fontfile=FreeSerif.ttf:textfile=CREDITS:y=h-20*t"
1281 @end example
1282
1283 @item
1284 Draw a single green letter "g", at the center of the input video.
1285 The glyph baseline is placed at half screen height.
1286 @example
1287 drawtext=fontsize=60:fontfile=FreeSerif.ttf:fontcolor=green:text=g:x=(w-max_glyph_w)/2:y=h/2-ascent
1288 @end example
1289
1290 @end itemize
1291
1292 For more information about libfreetype, check:
1293 @url{http://www.freetype.org/}.
1294
1295 @section fade
1296
1297 Apply fade-in/out effect to input video.
1298
1299 It accepts the parameters:
1300 @var{type}:@var{start_frame}:@var{nb_frames}[:@var{options}]
1301
1302 @var{type} specifies if the effect type, can be either "in" for
1303 fade-in, or "out" for a fade-out effect.
1304
1305 @var{start_frame} specifies the number of the start frame for starting
1306 to apply the fade effect.
1307
1308 @var{nb_frames} specifies the number of frames for which the fade
1309 effect has to last. At the end of the fade-in effect the output video
1310 will have the same intensity as the input video, at the end of the
1311 fade-out transition the output video will be completely black.
1312
1313 @var{options} is an optional sequence of @var{key}=@var{value} pairs,
1314 separated by ":". The description of the accepted options follows.
1315
1316 @table @option
1317
1318 @item type, t
1319 See @var{type}.
1320
1321 @item start_frame, s
1322 See @var{start_frame}.
1323
1324 @item nb_frames, n
1325 See @var{nb_frames}.
1326
1327 @item alpha
1328 If set to 1, fade only alpha channel, if one exists on the input.
1329 Default value is 0.
1330 @end table
1331
1332 A few usage examples follow, usable too as test scenarios.
1333 @example
1334 # fade in first 30 frames of video
1335 fade=in:0:30
1336
1337 # fade out last 45 frames of a 200-frame video
1338 fade=out:155:45
1339
1340 # fade in first 25 frames and fade out last 25 frames of a 1000-frame video
1341 fade=in:0:25, fade=out:975:25
1342
1343 # make first 5 frames black, then fade in from frame 5-24
1344 fade=in:5:20
1345
1346 # fade in alpha over first 25 frames of video
1347 fade=in:0:25:alpha=1
1348 @end example
1349
1350 @section fieldorder
1351
1352 Transform the field order of the input video.
1353
1354 It accepts one parameter which specifies the required field order that
1355 the input interlaced video will be transformed to. The parameter can
1356 assume one of the following values:
1357
1358 @table @option
1359 @item 0 or bff
1360 output bottom field first
1361 @item 1 or tff
1362 output top field first
1363 @end table
1364
1365 Default value is "tff".
1366
1367 Transformation is achieved by shifting the picture content up or down
1368 by one line, and filling the remaining line with appropriate picture content.
1369 This method is consistent with most broadcast field order converters.
1370
1371 If the input video is not flagged as being interlaced, or it is already
1372 flagged as being of the required output field order then this filter does
1373 not alter the incoming video.
1374
1375 This filter is very useful when converting to or from PAL DV material,
1376 which is bottom field first.
1377
1378 For example:
1379 @example
1380 ffmpeg -i in.vob -vf "fieldorder=bff" out.dv
1381 @end example
1382
1383 @section fifo
1384
1385 Buffer input images and send them when they are requested.
1386
1387 This filter is mainly useful when auto-inserted by the libavfilter
1388 framework.
1389
1390 The filter does not take parameters.
1391
1392 @section format
1393
1394 Convert the input video to one of the specified pixel formats.
1395 Libavfilter will try to pick one that is supported for the input to
1396 the next filter.
1397
1398 The filter accepts a list of pixel format names, separated by ":",
1399 for example "yuv420p:monow:rgb24".
1400
1401 Some examples follow:
1402 @example
1403 # convert the input video to the format "yuv420p"
1404 format=yuv420p
1405
1406 # convert the input video to any of the formats in the list
1407 format=yuv420p:yuv444p:yuv410p
1408 @end example
1409
1410 @anchor{frei0r}
1411 @section frei0r
1412
1413 Apply a frei0r effect to the input video.
1414
1415 To enable compilation of this filter you need to install the frei0r
1416 header and configure FFmpeg with @code{--enable-frei0r}.
1417
1418 The filter supports the syntax:
1419 @example
1420 @var{filter_name}[@{:|=@}@var{param1}:@var{param2}:...:@var{paramN}]
1421 @end example
1422
1423 @var{filter_name} is the name to the frei0r effect to load. If the
1424 environment variable @env{FREI0R_PATH} is defined, the frei0r effect
1425 is searched in each one of the directories specified by the colon
1426 separated list in @env{FREIOR_PATH}, otherwise in the standard frei0r
1427 paths, which are in this order: @file{HOME/.frei0r-1/lib/},
1428 @file{/usr/local/lib/frei0r-1/}, @file{/usr/lib/frei0r-1/}.
1429
1430 @var{param1}, @var{param2}, ... , @var{paramN} specify the parameters
1431 for the frei0r effect.
1432
1433 A frei0r effect parameter can be a boolean (whose values are specified
1434 with "y" and "n"), a double, a color (specified by the syntax
1435 @var{R}/@var{G}/@var{B}, @var{R}, @var{G}, and @var{B} being float
1436 numbers from 0.0 to 1.0) or by an @code{av_parse_color()} color
1437 description), a position (specified by the syntax @var{X}/@var{Y},
1438 @var{X} and @var{Y} being float numbers) and a string.
1439
1440 The number and kind of parameters depend on the loaded effect. If an
1441 effect parameter is not specified the default value is set.
1442
1443 Some examples follow:
1444 @example
1445 # apply the distort0r effect, set the first two double parameters
1446 frei0r=distort0r:0.5:0.01
1447
1448 # apply the colordistance effect, takes a color as first parameter
1449 frei0r=colordistance:0.2/0.3/0.4
1450 frei0r=colordistance:violet
1451 frei0r=colordistance:0x112233
1452
1453 # apply the perspective effect, specify the top left and top right
1454 # image positions
1455 frei0r=perspective:0.2/0.2:0.8/0.2
1456 @end example
1457
1458 For more information see:
1459 @url{http://piksel.org/frei0r}
1460
1461 @section gradfun
1462
1463 Fix the banding artifacts that are sometimes introduced into nearly flat
1464 regions by truncation to 8bit color depth.
1465 Interpolate the gradients that should go where the bands are, and
1466 dither them.
1467
1468 This filter is designed for playback only.  Do not use it prior to
1469 lossy compression, because compression tends to lose the dither and
1470 bring back the bands.
1471
1472 The filter takes two optional parameters, separated by ':':
1473 @var{strength}:@var{radius}
1474
1475 @var{strength} is the maximum amount by which the filter will change
1476 any one pixel. Also the threshold for detecting nearly flat
1477 regions. Acceptable values range from .51 to 255, default value is
1478 1.2, out-of-range values will be clipped to the valid range.
1479
1480 @var{radius} is the neighborhood to fit the gradient to. A larger
1481 radius makes for smoother gradients, but also prevents the filter from
1482 modifying the pixels near detailed regions. Acceptable values are
1483 8-32, default value is 16, out-of-range values will be clipped to the
1484 valid range.
1485
1486 @example
1487 # default parameters
1488 gradfun=1.2:16
1489
1490 # omitting radius
1491 gradfun=1.2
1492 @end example
1493
1494 @section hflip
1495
1496 Flip the input video horizontally.
1497
1498 For example to horizontally flip the input video with @command{ffmpeg}:
1499 @example
1500 ffmpeg -i in.avi -vf "hflip" out.avi
1501 @end example
1502
1503 @section hqdn3d
1504
1505 High precision/quality 3d denoise filter. This filter aims to reduce
1506 image noise producing smooth images and making still images really
1507 still. It should enhance compressibility.
1508
1509 It accepts the following optional parameters:
1510 @var{luma_spatial}:@var{chroma_spatial}:@var{luma_tmp}:@var{chroma_tmp}
1511
1512 @table @option
1513 @item luma_spatial
1514 a non-negative float number which specifies spatial luma strength,
1515 defaults to 4.0
1516
1517 @item chroma_spatial
1518 a non-negative float number which specifies spatial chroma strength,
1519 defaults to 3.0*@var{luma_spatial}/4.0
1520
1521 @item luma_tmp
1522 a float number which specifies luma temporal strength, defaults to
1523 6.0*@var{luma_spatial}/4.0
1524
1525 @item chroma_tmp
1526 a float number which specifies chroma temporal strength, defaults to
1527 @var{luma_tmp}*@var{chroma_spatial}/@var{luma_spatial}
1528 @end table
1529
1530 @section lut, lutrgb, lutyuv
1531
1532 Compute a look-up table for binding each pixel component input value
1533 to an output value, and apply it to input video.
1534
1535 @var{lutyuv} applies a lookup table to a YUV input video, @var{lutrgb}
1536 to an RGB input video.
1537
1538 These filters accept in input a ":"-separated list of options, which
1539 specify the expressions used for computing the lookup table for the
1540 corresponding pixel component values.
1541
1542 The @var{lut} filter requires either YUV or RGB pixel formats in
1543 input, and accepts the options:
1544 @table @option
1545 @item c0
1546 first  pixel component
1547 @item c1
1548 second pixel component
1549 @item c2
1550 third  pixel component
1551 @item c3
1552 fourth pixel component, corresponds to the alpha component
1553 @end table
1554
1555 The exact component associated to each option depends on the format in
1556 input.
1557
1558 The @var{lutrgb} filter requires RGB pixel formats in input, and
1559 accepts the options:
1560 @table @option
1561 @item r
1562 red component
1563 @item g
1564 green component
1565 @item b
1566 blue component
1567 @item a
1568 alpha component
1569 @end table
1570
1571 The @var{lutyuv} filter requires YUV pixel formats in input, and
1572 accepts the options:
1573 @table @option
1574 @item y
1575 Y/luminance component
1576 @item u
1577 U/Cb component
1578 @item v
1579 V/Cr component
1580 @item a
1581 alpha component
1582 @end table
1583
1584 The expressions can contain the following constants and functions:
1585
1586 @table @option
1587 @item w, h
1588 the input width and height
1589
1590 @item val
1591 input value for the pixel component
1592
1593 @item clipval
1594 the input value clipped in the @var{minval}-@var{maxval} range
1595
1596 @item maxval
1597 maximum value for the pixel component
1598
1599 @item minval
1600 minimum value for the pixel component
1601
1602 @item negval
1603 the negated value for the pixel component value clipped in the
1604 @var{minval}-@var{maxval} range , it corresponds to the expression
1605 "maxval-clipval+minval"
1606
1607 @item clip(val)
1608 the computed value in @var{val} clipped in the
1609 @var{minval}-@var{maxval} range
1610
1611 @item gammaval(gamma)
1612 the computed gamma correction value of the pixel component value
1613 clipped in the @var{minval}-@var{maxval} range, corresponds to the
1614 expression
1615 "pow((clipval-minval)/(maxval-minval)\,@var{gamma})*(maxval-minval)+minval"
1616
1617 @end table
1618
1619 All expressions default to "val".
1620
1621 Some examples follow:
1622 @example
1623 # negate input video
1624 lutrgb="r=maxval+minval-val:g=maxval+minval-val:b=maxval+minval-val"
1625 lutyuv="y=maxval+minval-val:u=maxval+minval-val:v=maxval+minval-val"
1626
1627 # the above is the same as
1628 lutrgb="r=negval:g=negval:b=negval"
1629 lutyuv="y=negval:u=negval:v=negval"
1630
1631 # negate luminance
1632 lutyuv=y=negval
1633
1634 # remove chroma components, turns the video into a graytone image
1635 lutyuv="u=128:v=128"
1636
1637 # apply a luma burning effect
1638 lutyuv="y=2*val"
1639
1640 # remove green and blue components
1641 lutrgb="g=0:b=0"
1642
1643 # set a constant alpha channel value on input
1644 format=rgba,lutrgb=a="maxval-minval/2"
1645
1646 # correct luminance gamma by a 0.5 factor
1647 lutyuv=y=gammaval(0.5)
1648 @end example
1649
1650 @section mp
1651
1652 Apply an MPlayer filter to the input video.
1653
1654 This filter provides a wrapper around most of the filters of
1655 MPlayer/MEncoder.
1656
1657 This wrapper is considered experimental. Some of the wrapped filters
1658 may not work properly and we may drop support for them, as they will
1659 be implemented natively into FFmpeg. Thus you should avoid
1660 depending on them when writing portable scripts.
1661
1662 The filters accepts the parameters:
1663 @var{filter_name}[:=]@var{filter_params}
1664
1665 @var{filter_name} is the name of a supported MPlayer filter,
1666 @var{filter_params} is a string containing the parameters accepted by
1667 the named filter.
1668
1669 The list of the currently supported filters follows:
1670 @table @var
1671 @item 2xsai
1672 @item decimate
1673 @item denoise3d
1674 @item detc
1675 @item dint
1676 @item divtc
1677 @item down3dright
1678 @item dsize
1679 @item eq2
1680 @item eq
1681 @item field
1682 @item fil
1683 @item fixpts
1684 @item framestep
1685 @item fspp
1686 @item geq
1687 @item harddup
1688 @item hqdn3d
1689 @item hue
1690 @item il
1691 @item ilpack
1692 @item ivtc
1693 @item kerndeint
1694 @item mcdeint
1695 @item mirror
1696 @item noise
1697 @item ow
1698 @item palette
1699 @item perspective
1700 @item phase
1701 @item pp7
1702 @item pullup
1703 @item qp
1704 @item rectangle
1705 @item remove-logo
1706 @item rotate
1707 @item sab
1708 @item screenshot
1709 @item smartblur
1710 @item softpulldown
1711 @item softskip
1712 @item spp
1713 @item swapuv
1714 @item telecine
1715 @item tile
1716 @item tinterlace
1717 @item unsharp
1718 @item uspp
1719 @item yuvcsp
1720 @item yvu9
1721 @end table
1722
1723 The parameter syntax and behavior for the listed filters are the same
1724 of the corresponding MPlayer filters. For detailed instructions check
1725 the "VIDEO FILTERS" section in the MPlayer manual.
1726
1727 Some examples follow:
1728 @example
1729 # remove a logo by interpolating the surrounding pixels
1730 mp=delogo=200:200:80:20:1
1731
1732 # adjust gamma, brightness, contrast
1733 mp=eq2=1.0:2:0.5
1734
1735 # tweak hue and saturation
1736 mp=hue=100:-10
1737 @end example
1738
1739 See also mplayer(1), @url{http://www.mplayerhq.hu/}.
1740
1741 @section negate
1742
1743 Negate input video.
1744
1745 This filter accepts an integer in input, if non-zero it negates the
1746 alpha component (if available). The default value in input is 0.
1747
1748 @section noformat
1749
1750 Force libavfilter not to use any of the specified pixel formats for the
1751 input to the next filter.
1752
1753 The filter accepts a list of pixel format names, separated by ":",
1754 for example "yuv420p:monow:rgb24".
1755
1756 Some examples follow:
1757 @example
1758 # force libavfilter to use a format different from "yuv420p" for the
1759 # input to the vflip filter
1760 noformat=yuv420p,vflip
1761
1762 # convert the input video to any of the formats not contained in the list
1763 noformat=yuv420p:yuv444p:yuv410p
1764 @end example
1765
1766 @section null
1767
1768 Pass the video source unchanged to the output.
1769
1770 @section ocv
1771
1772 Apply video transform using libopencv.
1773
1774 To enable this filter install libopencv library and headers and
1775 configure FFmpeg with @code{--enable-libopencv}.
1776
1777 The filter takes the parameters: @var{filter_name}@{:=@}@var{filter_params}.
1778
1779 @var{filter_name} is the name of the libopencv filter to apply.
1780
1781 @var{filter_params} specifies the parameters to pass to the libopencv
1782 filter. If not specified the default values are assumed.
1783
1784 Refer to the official libopencv documentation for more precise
1785 information:
1786 @url{http://opencv.willowgarage.com/documentation/c/image_filtering.html}
1787
1788 Follows the list of supported libopencv filters.
1789
1790 @anchor{dilate}
1791 @subsection dilate
1792
1793 Dilate an image by using a specific structuring element.
1794 This filter corresponds to the libopencv function @code{cvDilate}.
1795
1796 It accepts the parameters: @var{struct_el}:@var{nb_iterations}.
1797
1798 @var{struct_el} represents a structuring element, and has the syntax:
1799 @var{cols}x@var{rows}+@var{anchor_x}x@var{anchor_y}/@var{shape}
1800
1801 @var{cols} and @var{rows} represent the number of columns and rows of
1802 the structuring element, @var{anchor_x} and @var{anchor_y} the anchor
1803 point, and @var{shape} the shape for the structuring element, and
1804 can be one of the values "rect", "cross", "ellipse", "custom".
1805
1806 If the value for @var{shape} is "custom", it must be followed by a
1807 string of the form "=@var{filename}". The file with name
1808 @var{filename} is assumed to represent a binary image, with each
1809 printable character corresponding to a bright pixel. When a custom
1810 @var{shape} is used, @var{cols} and @var{rows} are ignored, the number
1811 or columns and rows of the read file are assumed instead.
1812
1813 The default value for @var{struct_el} is "3x3+0x0/rect".
1814
1815 @var{nb_iterations} specifies the number of times the transform is
1816 applied to the image, and defaults to 1.
1817
1818 Follow some example:
1819 @example
1820 # use the default values
1821 ocv=dilate
1822
1823 # dilate using a structuring element with a 5x5 cross, iterate two times
1824 ocv=dilate=5x5+2x2/cross:2
1825
1826 # read the shape from the file diamond.shape, iterate two times
1827 # the file diamond.shape may contain a pattern of characters like this:
1828 #   *
1829 #  ***
1830 # *****
1831 #  ***
1832 #   *
1833 # the specified cols and rows are ignored (but not the anchor point coordinates)
1834 ocv=0x0+2x2/custom=diamond.shape:2
1835 @end example
1836
1837 @subsection erode
1838
1839 Erode an image by using a specific structuring element.
1840 This filter corresponds to the libopencv function @code{cvErode}.
1841
1842 The filter accepts the parameters: @var{struct_el}:@var{nb_iterations},
1843 with the same syntax and semantics as the @ref{dilate} filter.
1844
1845 @subsection smooth
1846
1847 Smooth the input video.
1848
1849 The filter takes the following parameters:
1850 @var{type}:@var{param1}:@var{param2}:@var{param3}:@var{param4}.
1851
1852 @var{type} is the type of smooth filter to apply, and can be one of
1853 the following values: "blur", "blur_no_scale", "median", "gaussian",
1854 "bilateral". The default value is "gaussian".
1855
1856 @var{param1}, @var{param2}, @var{param3}, and @var{param4} are
1857 parameters whose meanings depend on smooth type. @var{param1} and
1858 @var{param2} accept integer positive values or 0, @var{param3} and
1859 @var{param4} accept float values.
1860
1861 The default value for @var{param1} is 3, the default value for the
1862 other parameters is 0.
1863
1864 These parameters correspond to the parameters assigned to the
1865 libopencv function @code{cvSmooth}.
1866
1867 @anchor{overlay}
1868 @section overlay
1869
1870 Overlay one video on top of another.
1871
1872 It takes two inputs and one output, the first input is the "main"
1873 video on which the second input is overlayed.
1874
1875 It accepts the parameters: @var{x}:@var{y}[:@var{options}].
1876
1877 @var{x} is the x coordinate of the overlayed video on the main video,
1878 @var{y} is the y coordinate. @var{x} and @var{y} are expressions containing
1879 the following parameters:
1880
1881 @table @option
1882 @item main_w, main_h
1883 main input width and height
1884
1885 @item W, H
1886 same as @var{main_w} and @var{main_h}
1887
1888 @item overlay_w, overlay_h
1889 overlay input width and height
1890
1891 @item w, h
1892 same as @var{overlay_w} and @var{overlay_h}
1893 @end table
1894
1895 @var{options} is an optional list of @var{key}=@var{value} pairs,
1896 separated by ":".
1897
1898 The description of the accepted options follows.
1899
1900 @table @option
1901 @item rgb
1902 If set to 1, force the filter to accept inputs in the RGB
1903 color space. Default value is 0.
1904 @end table
1905
1906 Be aware that frames are taken from each input video in timestamp
1907 order, hence, if their initial timestamps differ, it is a a good idea
1908 to pass the two inputs through a @var{setpts=PTS-STARTPTS} filter to
1909 have them begin in the same zero timestamp, as it does the example for
1910 the @var{movie} filter.
1911
1912 Follow some examples:
1913 @example
1914 # draw the overlay at 10 pixels from the bottom right
1915 # corner of the main video.
1916 overlay=main_w-overlay_w-10:main_h-overlay_h-10
1917
1918 # insert a transparent PNG logo in the bottom left corner of the input
1919 movie=logo.png [logo];
1920 [in][logo] overlay=10:main_h-overlay_h-10 [out]
1921
1922 # insert 2 different transparent PNG logos (second logo on bottom
1923 # right corner):
1924 movie=logo1.png [logo1];
1925 movie=logo2.png [logo2];
1926 [in][logo1]       overlay=10:H-h-10 [in+logo1];
1927 [in+logo1][logo2] overlay=W-w-10:H-h-10 [out]
1928
1929 # add a transparent color layer on top of the main video,
1930 # WxH specifies the size of the main input to the overlay filter
1931 color=red@.3:WxH [over]; [in][over] overlay [out]
1932 @end example
1933
1934 You can chain together more overlays but the efficiency of such
1935 approach is yet to be tested.
1936
1937 @section pad
1938
1939 Add paddings to the input image, and places the original input at the
1940 given coordinates @var{x}, @var{y}.
1941
1942 It accepts the following parameters:
1943 @var{width}:@var{height}:@var{x}:@var{y}:@var{color}.
1944
1945 The parameters @var{width}, @var{height}, @var{x}, and @var{y} are
1946 expressions containing the following constants:
1947
1948 @table @option
1949 @item in_w, in_h
1950 the input video width and height
1951
1952 @item iw, ih
1953 same as @var{in_w} and @var{in_h}
1954
1955 @item out_w, out_h
1956 the output width and height, that is the size of the padded area as
1957 specified by the @var{width} and @var{height} expressions
1958
1959 @item ow, oh
1960 same as @var{out_w} and @var{out_h}
1961
1962 @item x, y
1963 x and y offsets as specified by the @var{x} and @var{y}
1964 expressions, or NAN if not yet specified
1965
1966 @item a
1967 same as @var{iw} / @var{ih}
1968
1969 @item sar
1970 input sample aspect ratio
1971
1972 @item dar
1973 input display aspect ratio, it is the same as (@var{iw} / @var{ih}) * @var{sar}
1974
1975 @item hsub, vsub
1976 horizontal and vertical chroma subsample values. For example for the
1977 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
1978 @end table
1979
1980 Follows the description of the accepted parameters.
1981
1982 @table @option
1983 @item width, height
1984
1985 Specify the size of the output image with the paddings added. If the
1986 value for @var{width} or @var{height} is 0, the corresponding input size
1987 is used for the output.
1988
1989 The @var{width} expression can reference the value set by the
1990 @var{height} expression, and vice versa.
1991
1992 The default value of @var{width} and @var{height} is 0.
1993
1994 @item x, y
1995
1996 Specify the offsets where to place the input image in the padded area
1997 with respect to the top/left border of the output image.
1998
1999 The @var{x} expression can reference the value set by the @var{y}
2000 expression, and vice versa.
2001
2002 The default value of @var{x} and @var{y} is 0.
2003
2004 @item color
2005
2006 Specify the color of the padded area, it can be the name of a color
2007 (case insensitive match) or a 0xRRGGBB[AA] sequence.
2008
2009 The default value of @var{color} is "black".
2010
2011 @end table
2012
2013 Some examples follow:
2014
2015 @example
2016 # Add paddings with color "violet" to the input video. Output video
2017 # size is 640x480, the top-left corner of the input video is placed at
2018 # column 0, row 40.
2019 pad=640:480:0:40:violet
2020
2021 # pad the input to get an output with dimensions increased bt 3/2,
2022 # and put the input video at the center of the padded area
2023 pad="3/2*iw:3/2*ih:(ow-iw)/2:(oh-ih)/2"
2024
2025 # pad the input to get a squared output with size equal to the maximum
2026 # value between the input width and height, and put the input video at
2027 # the center of the padded area
2028 pad="max(iw\,ih):ow:(ow-iw)/2:(oh-ih)/2"
2029
2030 # pad the input to get a final w/h ratio of 16:9
2031 pad="ih*16/9:ih:(ow-iw)/2:(oh-ih)/2"
2032
2033 # for anamorphic video, in order to set the output display aspect ratio,
2034 # it is necessary to use sar in the expression, according to the relation:
2035 # (ih * X / ih) * sar = output_dar
2036 # X = output_dar / sar
2037 pad="ih*16/9/sar:ih:(ow-iw)/2:(oh-ih)/2"
2038
2039 # double output size and put the input video in the bottom-right
2040 # corner of the output padded area
2041 pad="2*iw:2*ih:ow-iw:oh-ih"
2042 @end example
2043
2044 @section pixdesctest
2045
2046 Pixel format descriptor test filter, mainly useful for internal
2047 testing. The output video should be equal to the input video.
2048
2049 For example:
2050 @example
2051 format=monow, pixdesctest
2052 @end example
2053
2054 can be used to test the monowhite pixel format descriptor definition.
2055
2056 @section scale
2057
2058 Scale the input video to @var{width}:@var{height}[:@var{interl}=@{1|-1@}] and/or convert the image format.
2059
2060 The parameters @var{width} and @var{height} are expressions containing
2061 the following constants:
2062
2063 @table @option
2064 @item in_w, in_h
2065 the input width and height
2066
2067 @item iw, ih
2068 same as @var{in_w} and @var{in_h}
2069
2070 @item out_w, out_h
2071 the output (cropped) width and height
2072
2073 @item ow, oh
2074 same as @var{out_w} and @var{out_h}
2075
2076 @item a
2077 same as @var{iw} / @var{ih}
2078
2079 @item sar
2080 input sample aspect ratio
2081
2082 @item dar
2083 input display aspect ratio, it is the same as (@var{iw} / @var{ih}) * @var{sar}
2084
2085 @item sar
2086 input sample aspect ratio
2087
2088 @item hsub, vsub
2089 horizontal and vertical chroma subsample values. For example for the
2090 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
2091 @end table
2092
2093 If the input image format is different from the format requested by
2094 the next filter, the scale filter will convert the input to the
2095 requested format.
2096
2097 If the value for @var{width} or @var{height} is 0, the respective input
2098 size is used for the output.
2099
2100 If the value for @var{width} or @var{height} is -1, the scale filter will
2101 use, for the respective output size, a value that maintains the aspect
2102 ratio of the input image.
2103
2104 The default value of @var{width} and @var{height} is 0.
2105
2106 Valid values for the optional parameter @var{interl} are:
2107
2108 @table @option
2109 @item 1
2110 force interlaced aware scaling
2111
2112 @item -1
2113 select interlaced aware scaling depending on whether the source frames
2114 are flagged as interlaced or not
2115 @end table
2116
2117 Some examples follow:
2118 @example
2119 # scale the input video to a size of 200x100.
2120 scale=200:100
2121
2122 # scale the input to 2x
2123 scale=2*iw:2*ih
2124 # the above is the same as
2125 scale=2*in_w:2*in_h
2126
2127 # scale the input to half size
2128 scale=iw/2:ih/2
2129
2130 # increase the width, and set the height to the same size
2131 scale=3/2*iw:ow
2132
2133 # seek for Greek harmony
2134 scale=iw:1/PHI*iw
2135 scale=ih*PHI:ih
2136
2137 # increase the height, and set the width to 3/2 of the height
2138 scale=3/2*oh:3/5*ih
2139
2140 # increase the size, but make the size a multiple of the chroma
2141 scale="trunc(3/2*iw/hsub)*hsub:trunc(3/2*ih/vsub)*vsub"
2142
2143 # increase the width to a maximum of 500 pixels, keep the same input aspect ratio
2144 scale='min(500\, iw*3/2):-1'
2145 @end example
2146
2147 @section select
2148 Select frames to pass in output.
2149
2150 It accepts in input an expression, which is evaluated for each input
2151 frame. If the expression is evaluated to a non-zero value, the frame
2152 is selected and passed to the output, otherwise it is discarded.
2153
2154 The expression can contain the following constants:
2155
2156 @table @option
2157 @item n
2158 the sequential number of the filtered frame, starting from 0
2159
2160 @item selected_n
2161 the sequential number of the selected frame, starting from 0
2162
2163 @item prev_selected_n
2164 the sequential number of the last selected frame, NAN if undefined
2165
2166 @item TB
2167 timebase of the input timestamps
2168
2169 @item pts
2170 the PTS (Presentation TimeStamp) of the filtered video frame,
2171 expressed in @var{TB} units, NAN if undefined
2172
2173 @item t
2174 the PTS (Presentation TimeStamp) of the filtered video frame,
2175 expressed in seconds, NAN if undefined
2176
2177 @item prev_pts
2178 the PTS of the previously filtered video frame, NAN if undefined
2179
2180 @item prev_selected_pts
2181 the PTS of the last previously filtered video frame, NAN if undefined
2182
2183 @item prev_selected_t
2184 the PTS of the last previously selected video frame, NAN if undefined
2185
2186 @item start_pts
2187 the PTS of the first video frame in the video, NAN if undefined
2188
2189 @item start_t
2190 the time of the first video frame in the video, NAN if undefined
2191
2192 @item pict_type
2193 the type of the filtered frame, can assume one of the following
2194 values:
2195 @table @option
2196 @item I
2197 @item P
2198 @item B
2199 @item S
2200 @item SI
2201 @item SP
2202 @item BI
2203 @end table
2204
2205 @item interlace_type
2206 the frame interlace type, can assume one of the following values:
2207 @table @option
2208 @item PROGRESSIVE
2209 the frame is progressive (not interlaced)
2210 @item TOPFIRST
2211 the frame is top-field-first
2212 @item BOTTOMFIRST
2213 the frame is bottom-field-first
2214 @end table
2215
2216 @item key
2217 1 if the filtered frame is a key-frame, 0 otherwise
2218
2219 @item pos
2220 the position in the file of the filtered frame, -1 if the information
2221 is not available (e.g. for synthetic video)
2222 @end table
2223
2224 The default value of the select expression is "1".
2225
2226 Some examples follow:
2227
2228 @example
2229 # select all frames in input
2230 select
2231
2232 # the above is the same as:
2233 select=1
2234
2235 # skip all frames:
2236 select=0
2237
2238 # select only I-frames
2239 select='eq(pict_type\,I)'
2240
2241 # select one frame every 100
2242 select='not(mod(n\,100))'
2243
2244 # select only frames contained in the 10-20 time interval
2245 select='gte(t\,10)*lte(t\,20)'
2246
2247 # select only I frames contained in the 10-20 time interval
2248 select='gte(t\,10)*lte(t\,20)*eq(pict_type\,I)'
2249
2250 # select frames with a minimum distance of 10 seconds
2251 select='isnan(prev_selected_t)+gte(t-prev_selected_t\,10)'
2252 @end example
2253
2254 @anchor{setdar}
2255 @section setdar
2256
2257 Set the Display Aspect Ratio for the filter output video.
2258
2259 This is done by changing the specified Sample (aka Pixel) Aspect
2260 Ratio, according to the following equation:
2261 @math{DAR = HORIZONTAL_RESOLUTION / VERTICAL_RESOLUTION * SAR}
2262
2263 Keep in mind that this filter does not modify the pixel dimensions of
2264 the video frame. Also the display aspect ratio set by this filter may
2265 be changed by later filters in the filterchain, e.g. in case of
2266 scaling or if another "setdar" or a "setsar" filter is applied.
2267
2268 The filter accepts a parameter string which represents the wanted
2269 display aspect ratio.
2270 The parameter can be a floating point number string, or an expression
2271 of the form @var{num}:@var{den}, where @var{num} and @var{den} are the
2272 numerator and denominator of the aspect ratio.
2273 If the parameter is not specified, it is assumed the value "0:1".
2274
2275 For example to change the display aspect ratio to 16:9, specify:
2276 @example
2277 setdar=16:9
2278 # the above is equivalent to
2279 setdar=1.77777
2280 @end example
2281
2282 See also the @ref{setsar} filter documentation.
2283
2284 @section setpts
2285
2286 Change the PTS (presentation timestamp) of the input video frames.
2287
2288 Accept in input an expression evaluated through the eval API, which
2289 can contain the following constants:
2290
2291 @table @option
2292 @item PTS
2293 the presentation timestamp in input
2294
2295 @item N
2296 the count of the input frame, starting from 0.
2297
2298 @item STARTPTS
2299 the PTS of the first video frame
2300
2301 @item INTERLACED
2302 tell if the current frame is interlaced
2303
2304 @item POS
2305 original position in the file of the frame, or undefined if undefined
2306 for the current frame
2307
2308 @item PREV_INPTS
2309 previous input PTS
2310
2311 @item PREV_OUTPTS
2312 previous output PTS
2313
2314 @end table
2315
2316 Some examples follow:
2317
2318 @example
2319 # start counting PTS from zero
2320 setpts=PTS-STARTPTS
2321
2322 # fast motion
2323 setpts=0.5*PTS
2324
2325 # slow motion
2326 setpts=2.0*PTS
2327
2328 # fixed rate 25 fps
2329 setpts=N/(25*TB)
2330
2331 # fixed rate 25 fps with some jitter
2332 setpts='1/(25*TB) * (N + 0.05 * sin(N*2*PI/25))'
2333 @end example
2334
2335 @anchor{setsar}
2336 @section setsar
2337
2338 Set the Sample (aka Pixel) Aspect Ratio for the filter output video.
2339
2340 Note that as a consequence of the application of this filter, the
2341 output display aspect ratio will change according to the following
2342 equation:
2343 @math{DAR = HORIZONTAL_RESOLUTION / VERTICAL_RESOLUTION * SAR}
2344
2345 Keep in mind that the sample aspect ratio set by this filter may be
2346 changed by later filters in the filterchain, e.g. if another "setsar"
2347 or a "setdar" filter is applied.
2348
2349 The filter accepts a parameter string which represents the wanted
2350 sample aspect ratio.
2351 The parameter can be a floating point number string, or an expression
2352 of the form @var{num}:@var{den}, where @var{num} and @var{den} are the
2353 numerator and denominator of the aspect ratio.
2354 If the parameter is not specified, it is assumed the value "0:1".
2355
2356 For example to change the sample aspect ratio to 10:11, specify:
2357 @example
2358 setsar=10:11
2359 @end example
2360
2361 @section settb
2362
2363 Set the timebase to use for the output frames timestamps.
2364 It is mainly useful for testing timebase configuration.
2365
2366 It accepts in input an arithmetic expression representing a rational.
2367 The expression can contain the constants "AVTB" (the
2368 default timebase), and "intb" (the input timebase).
2369
2370 The default value for the input is "intb".
2371
2372 Follow some examples.
2373
2374 @example
2375 # set the timebase to 1/25
2376 settb=1/25
2377
2378 # set the timebase to 1/10
2379 settb=0.1
2380
2381 #set the timebase to 1001/1000
2382 settb=1+0.001
2383
2384 #set the timebase to 2*intb
2385 settb=2*intb
2386
2387 #set the default timebase value
2388 settb=AVTB
2389 @end example
2390
2391 @section showinfo
2392
2393 Show a line containing various information for each input video frame.
2394 The input video is not modified.
2395
2396 The shown line contains a sequence of key/value pairs of the form
2397 @var{key}:@var{value}.
2398
2399 A description of each shown parameter follows:
2400
2401 @table @option
2402 @item n
2403 sequential number of the input frame, starting from 0
2404
2405 @item pts
2406 Presentation TimeStamp of the input frame, expressed as a number of
2407 time base units. The time base unit depends on the filter input pad.
2408
2409 @item pts_time
2410 Presentation TimeStamp of the input frame, expressed as a number of
2411 seconds
2412
2413 @item pos
2414 position of the frame in the input stream, -1 if this information in
2415 unavailable and/or meaningless (for example in case of synthetic video)
2416
2417 @item fmt
2418 pixel format name
2419
2420 @item sar
2421 sample aspect ratio of the input frame, expressed in the form
2422 @var{num}/@var{den}
2423
2424 @item s
2425 size of the input frame, expressed in the form
2426 @var{width}x@var{height}
2427
2428 @item i
2429 interlaced mode ("P" for "progressive", "T" for top field first, "B"
2430 for bottom field first)
2431
2432 @item iskey
2433 1 if the frame is a key frame, 0 otherwise
2434
2435 @item type
2436 picture type of the input frame ("I" for an I-frame, "P" for a
2437 P-frame, "B" for a B-frame, "?" for unknown type).
2438 Check also the documentation of the @code{AVPictureType} enum and of
2439 the @code{av_get_picture_type_char} function defined in
2440 @file{libavutil/avutil.h}.
2441
2442 @item checksum
2443 Adler-32 checksum (printed in hexadecimal) of all the planes of the input frame
2444
2445 @item plane_checksum
2446 Adler-32 checksum (printed in hexadecimal) of each plane of the input frame,
2447 expressed in the form "[@var{c0} @var{c1} @var{c2} @var{c3}]"
2448 @end table
2449
2450 @section slicify
2451
2452 Pass the images of input video on to next video filter as multiple
2453 slices.
2454
2455 @example
2456 ffmpeg -i in.avi -vf "slicify=32" out.avi
2457 @end example
2458
2459 The filter accepts the slice height as parameter. If the parameter is
2460 not specified it will use the default value of 16.
2461
2462 Adding this in the beginning of filter chains should make filtering
2463 faster due to better use of the memory cache.
2464
2465 @section split
2466
2467 Pass on the input video to two outputs. Both outputs are identical to
2468 the input video.
2469
2470 For example:
2471 @example
2472 [in] split [splitout1][splitout2];
2473 [splitout1] crop=100:100:0:0    [cropout];
2474 [splitout2] pad=200:200:100:100 [padout];
2475 @end example
2476
2477 will create two separate outputs from the same input, one cropped and
2478 one padded.
2479
2480 @section thumbnail
2481 Select the most representative frame in a given sequence of consecutive frames.
2482
2483 It accepts as argument the frames batch size to analyze (default @var{N}=100);
2484 in a set of @var{N} frames, the filter will pick one of them, and then handle
2485 the next batch of @var{N} frames until the end.
2486
2487 Since the filter keeps track of the whole frames sequence, a bigger @var{N}
2488 value will result in a higher memory usage, so a high value is not recommended.
2489
2490 The following example extract one picture each 50 frames:
2491 @example
2492 thumbnail=50
2493 @end example
2494
2495 Complete example of a thumbnail creation with @command{ffmpeg}:
2496 @example
2497 ffmpeg -i in.avi -vf thumbnail,scale=300:200 -frames:v 1 out.png
2498 @end example
2499
2500 @section tinterlace
2501
2502 Perform various types of temporal field interlacing.
2503
2504 Frames are counted starting from 1, so the first input frame is
2505 considered odd.
2506
2507 This filter accepts a single parameter specifying the mode. Available
2508 modes are:
2509
2510 @table @samp
2511 @item 0
2512 Move odd frames into the upper field, even into the lower field,
2513 generating a double height frame at half framerate.
2514
2515 @item 1
2516 Only output even frames, odd frames are dropped, generating a frame with
2517 unchanged height at half framerate.
2518
2519 @item 2
2520 Only output odd frames, even frames are dropped, generating a frame with
2521 unchanged height at half framerate.
2522
2523 @item 3
2524 Expand each frame to full height, but pad alternate lines with black,
2525 generating a frame with double height at the same input framerate.
2526
2527 @item 4
2528 Interleave the upper field from odd frames with the lower field from
2529 even frames, generating a frame with unchanged height at half framerate.
2530
2531 @item 5
2532 Interleave the lower field from odd frames with the upper field from
2533 even frames, generating a frame with unchanged height at half framerate.
2534 @end table
2535
2536 Default mode is 0.
2537
2538 @section transpose
2539
2540 Transpose rows with columns in the input video and optionally flip it.
2541
2542 It accepts a parameter representing an integer, which can assume the
2543 values:
2544
2545 @table @samp
2546 @item 0
2547 Rotate by 90 degrees counterclockwise and vertically flip (default), that is:
2548 @example
2549 L.R     L.l
2550 . . ->  . .
2551 l.r     R.r
2552 @end example
2553
2554 @item 1
2555 Rotate by 90 degrees clockwise, that is:
2556 @example
2557 L.R     l.L
2558 . . ->  . .
2559 l.r     r.R
2560 @end example
2561
2562 @item 2
2563 Rotate by 90 degrees counterclockwise, that is:
2564 @example
2565 L.R     R.r
2566 . . ->  . .
2567 l.r     L.l
2568 @end example
2569
2570 @item 3
2571 Rotate by 90 degrees clockwise and vertically flip, that is:
2572 @example
2573 L.R     r.R
2574 . . ->  . .
2575 l.r     l.L
2576 @end example
2577 @end table
2578
2579 @section unsharp
2580
2581 Sharpen or blur the input video.
2582
2583 It accepts the following parameters:
2584 @var{luma_msize_x}:@var{luma_msize_y}:@var{luma_amount}:@var{chroma_msize_x}:@var{chroma_msize_y}:@var{chroma_amount}
2585
2586 Negative values for the amount will blur the input video, while positive
2587 values will sharpen. All parameters are optional and default to the
2588 equivalent of the string '5:5:1.0:5:5:0.0'.
2589
2590 @table @option
2591
2592 @item luma_msize_x
2593 Set the luma matrix horizontal size. It can be an integer between 3
2594 and 13, default value is 5.
2595
2596 @item luma_msize_y
2597 Set the luma matrix vertical size. It can be an integer between 3
2598 and 13, default value is 5.
2599
2600 @item luma_amount
2601 Set the luma effect strength. It can be a float number between -2.0
2602 and 5.0, default value is 1.0.
2603
2604 @item chroma_msize_x
2605 Set the chroma matrix horizontal size. It can be an integer between 3
2606 and 13, default value is 5.
2607
2608 @item chroma_msize_y
2609 Set the chroma matrix vertical size. It can be an integer between 3
2610 and 13, default value is 5.
2611
2612 @item chroma_amount
2613 Set the chroma effect strength. It can be a float number between -2.0
2614 and 5.0, default value is 0.0.
2615
2616 @end table
2617
2618 @example
2619 # Strong luma sharpen effect parameters
2620 unsharp=7:7:2.5
2621
2622 # Strong blur of both luma and chroma parameters
2623 unsharp=7:7:-2:7:7:-2
2624
2625 # Use the default values with @command{ffmpeg}
2626 ffmpeg -i in.avi -vf "unsharp" out.mp4
2627 @end example
2628
2629 @section vflip
2630
2631 Flip the input video vertically.
2632
2633 @example
2634 ffmpeg -i in.avi -vf "vflip" out.avi
2635 @end example
2636
2637 @section yadif
2638
2639 Deinterlace the input video ("yadif" means "yet another deinterlacing
2640 filter").
2641
2642 It accepts the optional parameters: @var{mode}:@var{parity}:@var{auto}.
2643
2644 @var{mode} specifies the interlacing mode to adopt, accepts one of the
2645 following values:
2646
2647 @table @option
2648 @item 0
2649 output 1 frame for each frame
2650 @item 1
2651 output 1 frame for each field
2652 @item 2
2653 like 0 but skips spatial interlacing check
2654 @item 3
2655 like 1 but skips spatial interlacing check
2656 @end table
2657
2658 Default value is 0.
2659
2660 @var{parity} specifies the picture field parity assumed for the input
2661 interlaced video, accepts one of the following values:
2662
2663 @table @option
2664 @item 0
2665 assume top field first
2666 @item 1
2667 assume bottom field first
2668 @item -1
2669 enable automatic detection
2670 @end table
2671
2672 Default value is -1.
2673 If interlacing is unknown or decoder does not export this information,
2674 top field first will be assumed.
2675
2676 @var{auto} specifies if deinterlacer should trust the interlaced flag
2677 and only deinterlace frames marked as interlaced
2678
2679 @table @option
2680 @item 0
2681 deinterlace all frames
2682 @item 1
2683 only deinterlace frames marked as interlaced
2684 @end table
2685
2686 Default value is 0.
2687
2688 @c man end VIDEO FILTERS
2689
2690 @chapter Video Sources
2691 @c man begin VIDEO SOURCES
2692
2693 Below is a description of the currently available video sources.
2694
2695 @section buffer
2696
2697 Buffer video frames, and make them available to the filter chain.
2698
2699 This source is mainly intended for a programmatic use, in particular
2700 through the interface defined in @file{libavfilter/vsrc_buffer.h}.
2701
2702 It accepts the following parameters:
2703 @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}
2704
2705 All the parameters but @var{scale_params} need to be explicitly
2706 defined.
2707
2708 Follows the list of the accepted parameters.
2709
2710 @table @option
2711
2712 @item width, height
2713 Specify the width and height of the buffered video frames.
2714
2715 @item pix_fmt_string
2716 A string representing the pixel format of the buffered video frames.
2717 It may be a number corresponding to a pixel format, or a pixel format
2718 name.
2719
2720 @item timebase_num, timebase_den
2721 Specify numerator and denomitor of the timebase assumed by the
2722 timestamps of the buffered frames.
2723
2724 @item sample_aspect_ratio.num, sample_aspect_ratio.den
2725 Specify numerator and denominator of the sample aspect ratio assumed
2726 by the video frames.
2727
2728 @item scale_params
2729 Specify the optional parameters to be used for the scale filter which
2730 is automatically inserted when an input change is detected in the
2731 input size or format.
2732 @end table
2733
2734 For example:
2735 @example
2736 buffer=320:240:yuv410p:1:24:1:1
2737 @end example
2738
2739 will instruct the source to accept video frames with size 320x240 and
2740 with format "yuv410p", assuming 1/24 as the timestamps timebase and
2741 square pixels (1:1 sample aspect ratio).
2742 Since the pixel format with name "yuv410p" corresponds to the number 6
2743 (check the enum PixelFormat definition in @file{libavutil/pixfmt.h}),
2744 this example corresponds to:
2745 @example
2746 buffer=320:240:6:1:24:1:1
2747 @end example
2748
2749 @section cellauto
2750
2751 Create a pattern generated by an elementary cellular automaton.
2752
2753 The initial state of the cellular automaton can be defined through the
2754 @option{filename}, and @option{pattern} options. If such options are
2755 not specified an initial state is created randomly.
2756
2757 At each new frame a new row in the video is filled with the result of
2758 the cellular automaton next generation. The behavior when the whole
2759 frame is filled is defined by the @option{scroll} option.
2760
2761 This source accepts a list of options in the form of
2762 @var{key}=@var{value} pairs separated by ":". A description of the
2763 accepted options follows.
2764
2765 @table @option
2766 @item filename, f
2767 Read the initial cellular automaton state, i.e. the starting row, from
2768 the specified file.
2769 In the file, each non-whitespace character is considered an alive
2770 cell, a newline will terminate the row, and further characters in the
2771 file will be ignored.
2772
2773 @item pattern, p
2774 Read the initial cellular automaton state, i.e. the starting row, from
2775 the specified string.
2776
2777 Each non-whitespace character in the string is considered an alive
2778 cell, a newline will terminate the row, and further characters in the
2779 string will be ignored.
2780
2781 @item rate, r
2782 Set the video rate, that is the number of frames generated per second.
2783 Default is 25.
2784
2785 @item random_fill_ratio, ratio
2786 Set the random fill ratio for the initial cellular automaton row. It
2787 is a floating point number value ranging from 0 to 1, defaults to
2788 1/PHI.
2789
2790 This option is ignored when a file or a pattern is specified.
2791
2792 @item random_seed, seed
2793 Set the seed for filling randomly the initial row, must be an integer
2794 included between 0 and UINT32_MAX. If not specified, or if explicitly
2795 set to -1, the filter will try to use a good random seed on a best
2796 effort basis.
2797
2798 @item rule
2799 Set the cellular automaton rule, it is a number ranging from 0 to 255.
2800 Default value is 110.
2801
2802 @item size, s
2803 Set the size of the output video.
2804
2805 If @option{filename} or @option{pattern} is specified, the size is set
2806 by default to the width of the specified initial state row, and the
2807 height is set to @var{width} * PHI.
2808
2809 If @option{size} is set, it must contain the width of the specified
2810 pattern string, and the specified pattern will be centered in the
2811 larger row.
2812
2813 If a filename or a pattern string is not specified, the size value
2814 defaults to "320x518" (used for a randomly generated initial state).
2815
2816 @item scroll
2817 If set to 1, scroll the output upward when all the rows in the output
2818 have been already filled. If set to 0, the new generated row will be
2819 written over the top row just after the bottom row is filled.
2820 Defaults to 1.
2821
2822 @item start_full, full
2823 If set to 1, completely fill the output with generated rows before
2824 outputting the first frame.
2825 This is the default behavior, for disabling set the value to 0.
2826
2827 @item stitch
2828 If set to 1, stitch the left and right row edges together.
2829 This is the default behavior, for disabling set the value to 0.
2830 @end table
2831
2832 @subsection Examples
2833
2834 @itemize
2835 @item
2836 Read the initial state from @file{pattern}, and specify an output of
2837 size 200x400.
2838 @example
2839 cellauto=f=pattern:s=200x400
2840 @end example
2841
2842 @item
2843 Generate a random initial row with a width of 200 cells, with a fill
2844 ratio of 2/3:
2845 @example
2846 cellauto=ratio=2/3:s=200x200
2847 @end example
2848
2849 @item
2850 Create a pattern generated by rule 18 starting by a single alive cell
2851 centered on an initial row with width 100:
2852 @example
2853 cellauto=p=@@:s=100x400:full=0:rule=18
2854 @end example
2855
2856 @item
2857 Specify a more elaborated initial pattern:
2858 @example
2859 cellauto=p='@@@@ @@ @@@@':s=100x400:full=0:rule=18
2860 @end example
2861
2862 @end itemize
2863
2864 @section color
2865
2866 Provide an uniformly colored input.
2867
2868 It accepts the following parameters:
2869 @var{color}:@var{frame_size}:@var{frame_rate}
2870
2871 Follows the description of the accepted parameters.
2872
2873 @table @option
2874
2875 @item color
2876 Specify the color of the source. It can be the name of a color (case
2877 insensitive match) or a 0xRRGGBB[AA] sequence, possibly followed by an
2878 alpha specifier. The default value is "black".
2879
2880 @item frame_size
2881 Specify the size of the sourced video, it may be a string of the form
2882 @var{width}x@var{height}, or the name of a size abbreviation. The
2883 default value is "320x240".
2884
2885 @item frame_rate
2886 Specify the frame rate of the sourced video, as the number of frames
2887 generated per second. It has to be a string in the format
2888 @var{frame_rate_num}/@var{frame_rate_den}, an integer number, a float
2889 number or a valid video frame rate abbreviation. The default value is
2890 "25".
2891
2892 @end table
2893
2894 For example the following graph description will generate a red source
2895 with an opacity of 0.2, with size "qcif" and a frame rate of 10
2896 frames per second, which will be overlayed over the source connected
2897 to the pad with identifier "in".
2898
2899 @example
2900 "color=red@@0.2:qcif:10 [color]; [in][color] overlay [out]"
2901 @end example
2902
2903 @section movie
2904
2905 Read a video stream from a movie container.
2906
2907 It accepts the syntax: @var{movie_name}[:@var{options}] where
2908 @var{movie_name} is the name of the resource to read (not necessarily
2909 a file but also a device or a stream accessed through some protocol),
2910 and @var{options} is an optional sequence of @var{key}=@var{value}
2911 pairs, separated by ":".
2912
2913 The description of the accepted options follows.
2914
2915 @table @option
2916
2917 @item format_name, f
2918 Specifies the format assumed for the movie to read, and can be either
2919 the name of a container or an input device. If not specified the
2920 format is guessed from @var{movie_name} or by probing.
2921
2922 @item seek_point, sp
2923 Specifies the seek point in seconds, the frames will be output
2924 starting from this seek point, the parameter is evaluated with
2925 @code{av_strtod} so the numerical value may be suffixed by an IS
2926 postfix. Default value is "0".
2927
2928 @item stream_index, si
2929 Specifies the index of the video stream to read. If the value is -1,
2930 the best suited video stream will be automatically selected. Default
2931 value is "-1".
2932
2933 @end table
2934
2935 This filter allows to overlay a second video on top of main input of
2936 a filtergraph as shown in this graph:
2937 @example
2938 input -----------> deltapts0 --> overlay --> output
2939                                     ^
2940                                     |
2941 movie --> scale--> deltapts1 -------+
2942 @end example
2943
2944 Some examples follow:
2945 @example
2946 # skip 3.2 seconds from the start of the avi file in.avi, and overlay it
2947 # on top of the input labelled as "in".
2948 movie=in.avi:seek_point=3.2, scale=180:-1, setpts=PTS-STARTPTS [movie];
2949 [in] setpts=PTS-STARTPTS, [movie] overlay=16:16 [out]
2950
2951 # read from a video4linux2 device, and overlay it on top of the input
2952 # labelled as "in"
2953 movie=/dev/video0:f=video4linux2, scale=180:-1, setpts=PTS-STARTPTS [movie];
2954 [in] setpts=PTS-STARTPTS, [movie] overlay=16:16 [out]
2955
2956 @end example
2957
2958 @section mptestsrc
2959
2960 Generate various test patterns, as generated by the MPlayer test filter.
2961
2962 The size of the generated video is fixed, and is 256x256.
2963 This source is useful in particular for testing encoding features.
2964
2965 This source accepts an optional sequence of @var{key}=@var{value} pairs,
2966 separated by ":". The description of the accepted options follows.
2967
2968 @table @option
2969
2970 @item rate, r
2971 Specify the frame rate of the sourced video, as the number of frames
2972 generated per second. It has to be a string in the format
2973 @var{frame_rate_num}/@var{frame_rate_den}, an integer number, a float
2974 number or a valid video frame rate abbreviation. The default value is
2975 "25".
2976
2977 @item duration, d
2978 Set the video duration of the sourced video. The accepted syntax is:
2979 @example
2980 [-]HH[:MM[:SS[.m...]]]
2981 [-]S+[.m...]
2982 @end example
2983 See also the function @code{av_parse_time()}.
2984
2985 If not specified, or the expressed duration is negative, the video is
2986 supposed to be generated forever.
2987
2988 @item test, t
2989
2990 Set the number or the name of the test to perform. Supported tests are:
2991 @table @option
2992 @item dc_luma
2993 @item dc_chroma
2994 @item freq_luma
2995 @item freq_chroma
2996 @item amp_luma
2997 @item amp_chroma
2998 @item cbp
2999 @item mv
3000 @item ring1
3001 @item ring2
3002 @item all
3003 @end table
3004
3005 Default value is "all", which will cycle through the list of all tests.
3006 @end table
3007
3008 For example the following:
3009 @example
3010 testsrc=t=dc_luma
3011 @end example
3012
3013 will generate a "dc_luma" test pattern.
3014
3015 @section frei0r_src
3016
3017 Provide a frei0r source.
3018
3019 To enable compilation of this filter you need to install the frei0r
3020 header and configure FFmpeg with @code{--enable-frei0r}.
3021
3022 The source supports the syntax:
3023 @example
3024 @var{size}:@var{rate}:@var{src_name}[@{=|:@}@var{param1}:@var{param2}:...:@var{paramN}]
3025 @end example
3026
3027 @var{size} is the size of the video to generate, may be a string of the
3028 form @var{width}x@var{height} or a frame size abbreviation.
3029 @var{rate} is the rate of the video to generate, may be a string of
3030 the form @var{num}/@var{den} or a frame rate abbreviation.
3031 @var{src_name} is the name to the frei0r source to load. For more
3032 information regarding frei0r and how to set the parameters read the
3033 section @ref{frei0r} in the description of the video filters.
3034
3035 Some examples follow:
3036 @example
3037 # generate a frei0r partik0l source with size 200x200 and frame rate 10
3038 # which is overlayed on the overlay filter main input
3039 frei0r_src=200x200:10:partik0l=1234 [overlay]; [in][overlay] overlay
3040 @end example
3041
3042 @section life
3043
3044 Generate a life pattern.
3045
3046 This source is based on a generalization of John Conway's life game.
3047
3048 The sourced input represents a life grid, each pixel represents a cell
3049 which can be in one of two possible states, alive or dead. Every cell
3050 interacts with its eight neighbours, which are the cells that are
3051 horizontally, vertically, or diagonally adjacent.
3052
3053 At each interaction the grid evolves according to the adopted rule,
3054 which specifies the number of neighbor alive cells which will make a
3055 cell stay alive or born. The @option{rule} option allows to specify
3056 the rule to adopt.
3057
3058 This source accepts a list of options in the form of
3059 @var{key}=@var{value} pairs separated by ":". A description of the
3060 accepted options follows.
3061
3062 @table @option
3063 @item filename, f
3064 Set the file from which to read the initial grid state. In the file,
3065 each non-whitespace character is considered an alive cell, and newline
3066 is used to delimit the end of each row.
3067
3068 If this option is not specified, the initial grid is generated
3069 randomly.
3070
3071 @item rate, r
3072 Set the video rate, that is the number of frames generated per second.
3073 Default is 25.
3074
3075 @item random_fill_ratio, ratio
3076 Set the random fill ratio for the initial random grid. It is a
3077 floating point number value ranging from 0 to 1, defaults to 1/PHI.
3078 It is ignored when a file is specified.
3079
3080 @item random_seed, seed
3081 Set the seed for filling the initial random grid, must be an integer
3082 included between 0 and UINT32_MAX. If not specified, or if explicitly
3083 set to -1, the filter will try to use a good random seed on a best
3084 effort basis.
3085
3086 @item rule
3087 Set the life rule.
3088
3089 A rule can be specified with a code of the kind "S@var{NS}/B@var{NB}",
3090 where @var{NS} and @var{NB} are sequences of numbers in the range 0-8,
3091 @var{NS} specifies the number of alive neighbor cells which make a
3092 live cell stay alive, and @var{NB} the number of alive neighbor cells
3093 which make a dead cell to become alive (i.e. to "born").
3094 "s" and "b" can be used in place of "S" and "B", respectively.
3095
3096 Alternatively a rule can be specified by an 18-bits integer. The 9
3097 high order bits are used to encode the next cell state if it is alive
3098 for each number of neighbor alive cells, the low order bits specify
3099 the rule for "borning" new cells. Higher order bits encode for an
3100 higher number of neighbor cells.
3101 For example the number 6153 = @code{(12<<9)+9} specifies a stay alive
3102 rule of 12 and a born rule of 9, which corresponds to "S23/B03".
3103
3104 Default value is "S23/B3", which is the original Conway's game of life
3105 rule, and will keep a cell alive if it has 2 or 3 neighbor alive
3106 cells, and will born a new cell if there are three alive cells around
3107 a dead cell.
3108
3109 @item size, s
3110 Set the size of the output video.
3111
3112 If @option{filename} is specified, the size is set by default to the
3113 same size of the input file. If @option{size} is set, it must contain
3114 the size specified in the input file, and the initial grid defined in
3115 that file is centered in the larger resulting area.
3116
3117 If a filename is not specified, the size value defaults to "320x240"
3118 (used for a randomly generated initial grid).
3119
3120 @item stitch
3121 If set to 1, stitch the left and right grid edges together, and the
3122 top and bottom edges also. Defaults to 1.
3123
3124 @item mold
3125 Set cell mold speed. If set, a dead cell will go from @option{death_color} to
3126 @option{mold_color} with a step of @option{mold}. @option{mold} can have a
3127 value from 0 to 255.
3128
3129 @item life_color
3130 Set the color of living (or new born) cells.
3131
3132 @item death_color
3133 Set the color of dead cells. If @option{mold} is set, this is the first color
3134 used to represent a dead cell.
3135
3136 @item mold_color
3137 Set mold color, for definitely dead and moldy cells.
3138 @end table
3139
3140 @subsection Examples
3141
3142 @itemize
3143 @item
3144 Read a grid from @file{pattern}, and center it on a grid of size
3145 300x300 pixels:
3146 @example
3147 life=f=pattern:s=300x300
3148 @end example
3149
3150 @item
3151 Generate a random grid of size 200x200, with a fill ratio of 2/3:
3152 @example
3153 life=ratio=2/3:s=200x200
3154 @end example
3155
3156 @item
3157 Specify a custom rule for evolving a randomly generated grid:
3158 @example
3159 life=rule=S14/B34
3160 @end example
3161
3162 @item
3163 Full example with slow death effect (mold) using @command{ffplay}:
3164 @example
3165 ffplay -f lavfi life=s=300x200:mold=10:r=60:ratio=0.1:death_color=#C83232:life_color=#00ff00,scale=1200:800:flags=16
3166 @end example
3167 @end itemize
3168
3169 @section nullsrc, rgbtestsrc, testsrc
3170
3171 The @code{nullsrc} source returns unprocessed video frames. It is
3172 mainly useful to be employed in analysis / debugging tools, or as the
3173 source for filters which ignore the input data.
3174
3175 The @code{rgbtestsrc} source generates an RGB test pattern useful for
3176 detecting RGB vs BGR issues. You should see a red, green and blue
3177 stripe from top to bottom.
3178
3179 The @code{testsrc} source generates a test video pattern, showing a
3180 color pattern, a scrolling gradient and a timestamp. This is mainly
3181 intended for testing purposes.
3182
3183 These sources accept an optional sequence of @var{key}=@var{value} pairs,
3184 separated by ":". The description of the accepted options follows.
3185
3186 @table @option
3187
3188 @item size, s
3189 Specify the size of the sourced video, it may be a string of the form
3190 @var{width}x@var{height}, or the name of a size abbreviation. The
3191 default value is "320x240".
3192
3193 @item rate, r
3194 Specify the frame rate of the sourced video, as the number of frames
3195 generated per second. It has to be a string in the format
3196 @var{frame_rate_num}/@var{frame_rate_den}, an integer number, a float
3197 number or a valid video frame rate abbreviation. The default value is
3198 "25".
3199
3200 @item sar
3201 Set the sample aspect ratio of the sourced video.
3202
3203 @item duration
3204 Set the video duration of the sourced video. The accepted syntax is:
3205 @example
3206 [-]HH[:MM[:SS[.m...]]]
3207 [-]S+[.m...]
3208 @end example
3209 See also the function @code{av_parse_time()}.
3210
3211 If not specified, or the expressed duration is negative, the video is
3212 supposed to be generated forever.
3213 @end table
3214
3215 For example the following:
3216 @example
3217 testsrc=duration=5.3:size=qcif:rate=10
3218 @end example
3219
3220 will generate a video with a duration of 5.3 seconds, with size
3221 176x144 and a frame rate of 10 frames per second.
3222
3223 If the input content is to be ignored, @code{nullsrc} can be used. The
3224 following command generates noise in the luminance plane by employing
3225 the @code{mp=geq} filter:
3226 @example
3227 nullsrc=s=256x256, mp=geq=random(1)*255:128:128
3228 @end example
3229
3230 @c man end VIDEO SOURCES
3231
3232 @chapter Video Sinks
3233 @c man begin VIDEO SINKS
3234
3235 Below is a description of the currently available video sinks.
3236
3237 @section buffersink
3238
3239 Buffer video frames, and make them available to the end of the filter
3240 graph.
3241
3242 This sink is mainly intended for a programmatic use, in particular
3243 through the interface defined in @file{libavfilter/buffersink.h}.
3244
3245 It does not require a string parameter in input, but you need to
3246 specify a pointer to a list of supported pixel formats terminated by
3247 -1 in the opaque parameter provided to @code{avfilter_init_filter}
3248 when initializing this sink.
3249
3250 @section nullsink
3251
3252 Null video sink, do absolutely nothing with the input video. It is
3253 mainly useful as a template and to be employed in analysis / debugging
3254 tools.
3255
3256 @c man end VIDEO SINKS
3257