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