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