58a690309aaccb7ebc1cc87893494bf74a6fdaec
[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 @anchor{Filtergraph syntax}
18 @section Filtergraph syntax
19
20 A filtergraph can be represented using a textual representation, which is
21 recognized by the @option{-filter}/@option{-vf} and @option{-filter_complex}
22 options in @command{avconv} and @option{-vf} in @command{avplay}, and by the
23 @code{avfilter_graph_parse()}/@code{avfilter_graph_parse2()} function defined in
24 @file{libavfilter/avfiltergraph.h}.
25
26 A filterchain consists of a sequence of connected filters, each one
27 connected to the previous one in the sequence. A filterchain is
28 represented by a list of ","-separated filter descriptions.
29
30 A filtergraph consists of a sequence of filterchains. A sequence of
31 filterchains is represented by a list of ";"-separated filterchain
32 descriptions.
33
34 A filter is represented by a string of the form:
35 [@var{in_link_1}]...[@var{in_link_N}]@var{filter_name}=@var{arguments}[@var{out_link_1}]...[@var{out_link_M}]
36
37 @var{filter_name} is the name of the filter class of which the
38 described filter is an instance of, and has to be the name of one of
39 the filter classes registered in the program.
40 The name of the filter class is optionally followed by a string
41 "=@var{arguments}".
42
43 @var{arguments} is a string which contains the parameters used to
44 initialize the filter instance, and are described in the filter
45 descriptions below.
46
47 The list of arguments can be quoted using the character "'" as initial
48 and ending mark, and the character '\' for escaping the characters
49 within the quoted text; otherwise the argument string is considered
50 terminated when the next special character (belonging to the set
51 "[]=;,") is encountered.
52
53 The name and arguments of the filter are optionally preceded and
54 followed by a list of link labels.
55 A link label allows to name a link and associate it to a filter output
56 or input pad. The preceding labels @var{in_link_1}
57 ... @var{in_link_N}, are associated to the filter input pads,
58 the following labels @var{out_link_1} ... @var{out_link_M}, are
59 associated to the output pads.
60
61 When two link labels with the same name are found in the
62 filtergraph, a link between the corresponding input and output pad is
63 created.
64
65 If an output pad is not labelled, it is linked by default to the first
66 unlabelled input pad of the next filter in the filterchain.
67 For example in the filterchain:
68 @example
69 nullsrc, split[L1], [L2]overlay, nullsink
70 @end example
71 the split filter instance has two output pads, and the overlay filter
72 instance two input pads. The first output pad of split is labelled
73 "L1", the first input pad of overlay is labelled "L2", and the second
74 output pad of split is linked to the second input pad of overlay,
75 which are both unlabelled.
76
77 In a complete filterchain all the unlabelled filter input and output
78 pads must be connected. A filtergraph is considered valid if all the
79 filter input and output pads of all the filterchains are connected.
80
81 Libavfilter will automatically insert scale filters where format
82 conversion is required. It is possible to specify swscale flags
83 for those automatically inserted scalers by prepending
84 @code{sws_flags=@var{flags};}
85 to the filtergraph description.
86
87 Follows a BNF description for the filtergraph syntax:
88 @example
89 @var{NAME}             ::= sequence of alphanumeric characters and '_'
90 @var{LINKLABEL}        ::= "[" @var{NAME} "]"
91 @var{LINKLABELS}       ::= @var{LINKLABEL} [@var{LINKLABELS}]
92 @var{FILTER_ARGUMENTS} ::= sequence of chars (eventually quoted)
93 @var{FILTER}           ::= [@var{LINKNAMES}] @var{NAME} ["=" @var{ARGUMENTS}] [@var{LINKNAMES}]
94 @var{FILTERCHAIN}      ::= @var{FILTER} [,@var{FILTERCHAIN}]
95 @var{FILTERGRAPH}      ::= [sws_flags=@var{flags};] @var{FILTERCHAIN} [;@var{FILTERGRAPH}]
96 @end example
97
98 @c man end FILTERGRAPH DESCRIPTION
99
100 @chapter Audio Filters
101 @c man begin AUDIO FILTERS
102
103 When you configure your Libav build, you can disable any of the
104 existing filters using --disable-filters.
105 The configure output will show the audio filters included in your
106 build.
107
108 Below is a description of the currently available audio filters.
109
110 @section aformat
111
112 Convert the input audio to one of the specified formats. The framework will
113 negotiate the most appropriate format to minimize conversions.
114
115 The filter accepts the following named parameters:
116 @table @option
117
118 @item sample_fmts
119 A comma-separated list of requested sample formats.
120
121 @item sample_rates
122 A comma-separated list of requested sample rates.
123
124 @item channel_layouts
125 A comma-separated list of requested channel layouts.
126
127 @end table
128
129 If a parameter is omitted, all values are allowed.
130
131 For example to force the output to either unsigned 8-bit or signed 16-bit stereo:
132 @example
133 aformat=sample_fmts\=u8\,s16:channel_layouts\=stereo
134 @end example
135
136 @section amix
137
138 Mixes multiple audio inputs into a single output.
139
140 For example
141 @example
142 avconv -i INPUT1 -i INPUT2 -i INPUT3 -filter_complex amix=inputs=3:duration=first:dropout_transition=3 OUTPUT
143 @end example
144 will mix 3 input audio streams to a single output with the same duration as the
145 first input and a dropout transition time of 3 seconds.
146
147 The filter accepts the following named parameters:
148 @table @option
149
150 @item inputs
151 Number of inputs. If unspecified, it defaults to 2.
152
153 @item duration
154 How to determine the end-of-stream.
155 @table @option
156
157 @item longest
158 Duration of longest input. (default)
159
160 @item shortest
161 Duration of shortest input.
162
163 @item first
164 Duration of first input.
165
166 @end table
167
168 @item dropout_transition
169 Transition time, in seconds, for volume renormalization when an input
170 stream ends. The default value is 2 seconds.
171
172 @end table
173
174 @section anull
175
176 Pass the audio source unchanged to the output.
177
178 @section asplit
179
180 Split input audio into several identical outputs.
181
182 The filter accepts a single parameter which specifies the number of outputs. If
183 unspecified, it defaults to 2.
184
185 For example
186 @example
187 avconv -i INPUT -filter_complex asplit=5 OUTPUT
188 @end example
189 will create 5 copies of the input audio.
190
191 @section asyncts
192 Synchronize audio data with timestamps by squeezing/stretching it and/or
193 dropping samples/adding silence when needed.
194
195 The filter accepts the following named parameters:
196 @table @option
197
198 @item compensate
199 Enable stretching/squeezing the data to make it match the timestamps.
200
201 @item min_delta
202 Minimum difference between timestamps and audio data (in seconds) to trigger
203 adding/dropping samples.
204
205 @item max_comp
206 Maximum compensation in samples per second.
207
208 @item first_pts
209 Assume the first pts should be this value.
210 This allows for padding/trimming at the start of stream. By default, no
211 assumption is made about the first frame's expected pts, so no padding or
212 trimming is done. For example, this could be set to 0 to pad the beginning with
213 silence if an audio stream starts after the video stream.
214
215 @end table
216
217 @section channelsplit
218 Split each channel in input audio stream into a separate output stream.
219
220 This filter accepts the following named parameters:
221 @table @option
222 @item channel_layout
223 Channel layout of the input stream. Default is "stereo".
224 @end table
225
226 For example, assuming a stereo input MP3 file
227 @example
228 avconv -i in.mp3 -filter_complex channelsplit out.mkv
229 @end example
230 will create an output Matroska file with two audio streams, one containing only
231 the left channel and the other the right channel.
232
233 To split a 5.1 WAV file into per-channel files
234 @example
235 avconv -i in.wav -filter_complex
236 'channelsplit=channel_layout=5.1[FL][FR][FC][LFE][SL][SR]'
237 -map '[FL]' front_left.wav -map '[FR]' front_right.wav -map '[FC]'
238 front_center.wav -map '[LFE]' lfe.wav -map '[SL]' side_left.wav -map '[SR]'
239 side_right.wav
240 @end example
241
242 @section channelmap
243 Remap input channels to new locations.
244
245 This filter accepts the following named parameters:
246 @table @option
247 @item channel_layout
248 Channel layout of the output stream.
249
250 @item map
251 Map channels from input to output. The argument is a comma-separated list of
252 mappings, each in the @code{@var{in_channel}-@var{out_channel}} or
253 @var{in_channel} form. @var{in_channel} can be either the name of the input
254 channel (e.g. FL for front left) or its index in the input channel layout.
255 @var{out_channel} is the name of the output channel or its index in the output
256 channel layout. If @var{out_channel} is not given then it is implicitly an
257 index, starting with zero and increasing by one for each mapping.
258 @end table
259
260 If no mapping is present, the filter will implicitly map input channels to
261 output channels preserving index.
262
263 For example, assuming a 5.1+downmix input MOV file
264 @example
265 avconv -i in.mov -filter 'channelmap=map=DL-FL\,DR-FR' out.wav
266 @end example
267 will create an output WAV file tagged as stereo from the downmix channels of
268 the input.
269
270 To fix a 5.1 WAV improperly encoded in AAC's native channel order
271 @example
272 avconv -i in.wav -filter 'channelmap=1\,2\,0\,5\,3\,4:channel_layout=5.1' out.wav
273 @end example
274
275 @section join
276 Join multiple input streams into one multi-channel stream.
277
278 The filter accepts the following named parameters:
279 @table @option
280
281 @item inputs
282 Number of input streams. Defaults to 2.
283
284 @item channel_layout
285 Desired output channel layout. Defaults to stereo.
286
287 @item map
288 Map channels from inputs to output. The argument is a comma-separated list of
289 mappings, each in the @code{@var{input_idx}.@var{in_channel}-@var{out_channel}}
290 form. @var{input_idx} is the 0-based index of the input stream. @var{in_channel}
291 can be either the name of the input channel (e.g. FL for front left) or its
292 index in the specified input stream. @var{out_channel} is the name of the output
293 channel.
294 @end table
295
296 The filter will attempt to guess the mappings when those are not specified
297 explicitly. It does so by first trying to find an unused matching input channel
298 and if that fails it picks the first unused input channel.
299
300 E.g. to join 3 inputs (with properly set channel layouts)
301 @example
302 avconv -i INPUT1 -i INPUT2 -i INPUT3 -filter_complex join=inputs=3 OUTPUT
303 @end example
304
305 To build a 5.1 output from 6 single-channel streams:
306 @example
307 avconv -i fl -i fr -i fc -i sl -i sr -i lfe -filter_complex
308 'join=inputs=6:channel_layout=5.1:map=0.0-FL\,1.0-FR\,2.0-FC\,3.0-SL\,4.0-SR\,5.0-LFE'
309 out
310 @end example
311
312 @section resample
313 Convert the audio sample format, sample rate and channel layout. This filter is
314 not meant to be used directly, it is inserted automatically by libavfilter
315 whenever conversion is needed. Use the @var{aformat} filter to force a specific
316 conversion.
317
318 @c man end AUDIO FILTERS
319
320 @chapter Audio Sources
321 @c man begin AUDIO SOURCES
322
323 Below is a description of the currently available audio sources.
324
325 @section anullsrc
326
327 Null audio source, never return audio frames. It is mainly useful as a
328 template and to be employed in analysis / debugging tools.
329
330 It accepts as optional parameter a string of the form
331 @var{sample_rate}:@var{channel_layout}.
332
333 @var{sample_rate} specify the sample rate, and defaults to 44100.
334
335 @var{channel_layout} specify the channel layout, and can be either an
336 integer or a string representing a channel layout. The default value
337 of @var{channel_layout} is 3, which corresponds to CH_LAYOUT_STEREO.
338
339 Check the channel_layout_map definition in
340 @file{libavcodec/audioconvert.c} for the mapping between strings and
341 channel layout values.
342
343 Follow some examples:
344 @example
345 #  set the sample rate to 48000 Hz and the channel layout to CH_LAYOUT_MONO.
346 anullsrc=48000:4
347
348 # same as
349 anullsrc=48000:mono
350 @end example
351
352 @section abuffer
353 Buffer audio frames, and make them available to the filter chain.
354
355 This source is not intended to be part of user-supplied graph descriptions but
356 for insertion by calling programs through the interface defined in
357 @file{libavfilter/buffersrc.h}.
358
359 It accepts the following named parameters:
360 @table @option
361
362 @item time_base
363 Timebase which will be used for timestamps of submitted frames. It must be
364 either a floating-point number or in @var{numerator}/@var{denominator} form.
365
366 @item sample_rate
367 Audio sample rate.
368
369 @item sample_fmt
370 Name of the sample format, as returned by @code{av_get_sample_fmt_name()}.
371
372 @item channel_layout
373 Channel layout of the audio data, in the form that can be accepted by
374 @code{av_get_channel_layout()}.
375 @end table
376
377 All the parameters need to be explicitly defined.
378
379 @c man end AUDIO SOURCES
380
381 @chapter Audio Sinks
382 @c man begin AUDIO SINKS
383
384 Below is a description of the currently available audio sinks.
385
386 @section anullsink
387
388 Null audio sink, do absolutely nothing with the input audio. It is
389 mainly useful as a template and to be employed in analysis / debugging
390 tools.
391
392 @section abuffersink
393 This sink is intended for programmatic use. Frames that arrive on this sink can
394 be retrieved by the calling program using the interface defined in
395 @file{libavfilter/buffersink.h}.
396
397 This filter accepts no parameters.
398
399 @c man end AUDIO SINKS
400
401 @chapter Video Filters
402 @c man begin VIDEO FILTERS
403
404 When you configure your Libav build, you can disable any of the
405 existing filters using --disable-filters.
406 The configure output will show the video filters included in your
407 build.
408
409 Below is a description of the currently available video filters.
410
411 @section blackframe
412
413 Detect frames that are (almost) completely black. Can be useful to
414 detect chapter transitions or commercials. Output lines consist of
415 the frame number of the detected frame, the percentage of blackness,
416 the position in the file if known or -1 and the timestamp in seconds.
417
418 In order to display the output lines, you need to set the loglevel at
419 least to the AV_LOG_INFO value.
420
421 The filter accepts the syntax:
422 @example
423 blackframe[=@var{amount}:[@var{threshold}]]
424 @end example
425
426 @var{amount} is the percentage of the pixels that have to be below the
427 threshold, and defaults to 98.
428
429 @var{threshold} is the threshold below which a pixel value is
430 considered black, and defaults to 32.
431
432 @section boxblur
433
434 Apply boxblur algorithm to the input video.
435
436 This filter accepts the parameters:
437 @var{luma_power}:@var{luma_radius}:@var{chroma_radius}:@var{chroma_power}:@var{alpha_radius}:@var{alpha_power}
438
439 Chroma and alpha parameters are optional, if not specified they default
440 to the corresponding values set for @var{luma_radius} and
441 @var{luma_power}.
442
443 @var{luma_radius}, @var{chroma_radius}, and @var{alpha_radius} represent
444 the radius in pixels of the box used for blurring the corresponding
445 input plane. They are expressions, and can contain the following
446 constants:
447 @table @option
448 @item w, h
449 the input width and height in pixels
450
451 @item cw, ch
452 the input chroma image width and height in pixels
453
454 @item hsub, vsub
455 horizontal and vertical chroma subsample values. For example for the
456 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
457 @end table
458
459 The radius must be a non-negative number, and must not be greater than
460 the value of the expression @code{min(w,h)/2} for the luma and alpha planes,
461 and of @code{min(cw,ch)/2} for the chroma planes.
462
463 @var{luma_power}, @var{chroma_power}, and @var{alpha_power} represent
464 how many times the boxblur filter is applied to the corresponding
465 plane.
466
467 Some examples follow:
468
469 @itemize
470
471 @item
472 Apply a boxblur filter with luma, chroma, and alpha radius
473 set to 2:
474 @example
475 boxblur=2:1
476 @end example
477
478 @item
479 Set luma radius to 2, alpha and chroma radius to 0
480 @example
481 boxblur=2:1:0:0:0:0
482 @end example
483
484 @item
485 Set luma and chroma radius to a fraction of the video dimension
486 @example
487 boxblur=min(h\,w)/10:1:min(cw\,ch)/10:1
488 @end example
489
490 @end itemize
491
492 @section copy
493
494 Copy the input source unchanged to the output. Mainly useful for
495 testing purposes.
496
497 @section crop
498
499 Crop the input video to @var{out_w}:@var{out_h}:@var{x}:@var{y}.
500
501 The parameters are expressions containing the following constants:
502
503 @table @option
504 @item E, PI, PHI
505 the corresponding mathematical approximated values for e
506 (euler number), pi (greek PI), PHI (golden ratio)
507
508 @item x, y
509 the computed values for @var{x} and @var{y}. They are evaluated for
510 each new frame.
511
512 @item in_w, in_h
513 the input width and height
514
515 @item iw, ih
516 same as @var{in_w} and @var{in_h}
517
518 @item out_w, out_h
519 the output (cropped) width and height
520
521 @item ow, oh
522 same as @var{out_w} and @var{out_h}
523
524 @item n
525 the number of input frame, starting from 0
526
527 @item pos
528 the position in the file of the input frame, NAN if unknown
529
530 @item t
531 timestamp expressed in seconds, NAN if the input timestamp is unknown
532
533 @end table
534
535 The @var{out_w} and @var{out_h} parameters specify the expressions for
536 the width and height of the output (cropped) video. They are
537 evaluated just at the configuration of the filter.
538
539 The default value of @var{out_w} is "in_w", and the default value of
540 @var{out_h} is "in_h".
541
542 The expression for @var{out_w} may depend on the value of @var{out_h},
543 and the expression for @var{out_h} may depend on @var{out_w}, but they
544 cannot depend on @var{x} and @var{y}, as @var{x} and @var{y} are
545 evaluated after @var{out_w} and @var{out_h}.
546
547 The @var{x} and @var{y} parameters specify the expressions for the
548 position of the top-left corner of the output (non-cropped) area. They
549 are evaluated for each frame. If the evaluated value is not valid, it
550 is approximated to the nearest valid value.
551
552 The default value of @var{x} is "(in_w-out_w)/2", and the default
553 value for @var{y} is "(in_h-out_h)/2", which set the cropped area at
554 the center of the input image.
555
556 The expression for @var{x} may depend on @var{y}, and the expression
557 for @var{y} may depend on @var{x}.
558
559 Follow some examples:
560 @example
561 # crop the central input area with size 100x100
562 crop=100:100
563
564 # crop the central input area with size 2/3 of the input video
565 "crop=2/3*in_w:2/3*in_h"
566
567 # crop the input video central square
568 crop=in_h
569
570 # delimit the rectangle with the top-left corner placed at position
571 # 100:100 and the right-bottom corner corresponding to the right-bottom
572 # corner of the input image.
573 crop=in_w-100:in_h-100:100:100
574
575 # crop 10 pixels from the left and right borders, and 20 pixels from
576 # the top and bottom borders
577 "crop=in_w-2*10:in_h-2*20"
578
579 # keep only the bottom right quarter of the input image
580 "crop=in_w/2:in_h/2:in_w/2:in_h/2"
581
582 # crop height for getting Greek harmony
583 "crop=in_w:1/PHI*in_w"
584
585 # trembling effect
586 "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)"
587
588 # erratic camera effect depending on timestamp
589 "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)"
590
591 # set x depending on the value of y
592 "crop=in_w/2:in_h/2:y:10+10*sin(n/10)"
593 @end example
594
595 @section cropdetect
596
597 Auto-detect crop size.
598
599 Calculate necessary cropping parameters and prints the recommended
600 parameters through the logging system. The detected dimensions
601 correspond to the non-black area of the input video.
602
603 It accepts the syntax:
604 @example
605 cropdetect[=@var{limit}[:@var{round}[:@var{reset}]]]
606 @end example
607
608 @table @option
609
610 @item limit
611 Threshold, which can be optionally specified from nothing (0) to
612 everything (255), defaults to 24.
613
614 @item round
615 Value which the width/height should be divisible by, defaults to
616 16. The offset is automatically adjusted to center the video. Use 2 to
617 get only even dimensions (needed for 4:2:2 video). 16 is best when
618 encoding to most video codecs.
619
620 @item reset
621 Counter that determines after how many frames cropdetect will reset
622 the previously detected largest video area and start over to detect
623 the current optimal crop area. Defaults to 0.
624
625 This can be useful when channel logos distort the video area. 0
626 indicates never reset and return the largest area encountered during
627 playback.
628 @end table
629
630 @section delogo
631
632 Suppress a TV station logo by a simple interpolation of the surrounding
633 pixels. Just set a rectangle covering the logo and watch it disappear
634 (and sometimes something even uglier appear - your mileage may vary).
635
636 The filter accepts parameters as a string of the form
637 "@var{x}:@var{y}:@var{w}:@var{h}:@var{band}", or as a list of
638 @var{key}=@var{value} pairs, separated by ":".
639
640 The description of the accepted parameters follows.
641
642 @table @option
643
644 @item x, y
645 Specify the top left corner coordinates of the logo. They must be
646 specified.
647
648 @item w, h
649 Specify the width and height of the logo to clear. They must be
650 specified.
651
652 @item band, t
653 Specify the thickness of the fuzzy edge of the rectangle (added to
654 @var{w} and @var{h}). The default value is 4.
655
656 @item show
657 When set to 1, a green rectangle is drawn on the screen to simplify
658 finding the right @var{x}, @var{y}, @var{w}, @var{h} parameters, and
659 @var{band} is set to 4. The default value is 0.
660
661 @end table
662
663 Some examples follow.
664
665 @itemize
666
667 @item
668 Set a rectangle covering the area with top left corner coordinates 0,0
669 and size 100x77, setting a band of size 10:
670 @example
671 delogo=0:0:100:77:10
672 @end example
673
674 @item
675 As the previous example, but use named options:
676 @example
677 delogo=x=0:y=0:w=100:h=77:band=10
678 @end example
679
680 @end itemize
681
682 @section drawbox
683
684 Draw a colored box on the input image.
685
686 It accepts the syntax:
687 @example
688 drawbox=@var{x}:@var{y}:@var{width}:@var{height}:@var{color}
689 @end example
690
691 @table @option
692
693 @item x, y
694 Specify the top left corner coordinates of the box. Default to 0.
695
696 @item width, height
697 Specify the width and height of the box, if 0 they are interpreted as
698 the input width and height. Default to 0.
699
700 @item color
701 Specify the color of the box to write, it can be the name of a color
702 (case insensitive match) or a 0xRRGGBB[AA] sequence.
703 @end table
704
705 Follow some examples:
706 @example
707 # draw a black box around the edge of the input image
708 drawbox
709
710 # draw a box with color red and an opacity of 50%
711 drawbox=10:20:200:60:red@@0.5"
712 @end example
713
714 @section drawtext
715
716 Draw text string or text from specified file on top of video using the
717 libfreetype library.
718
719 To enable compilation of this filter you need to configure Libav with
720 @code{--enable-libfreetype}.
721
722 The filter also recognizes strftime() sequences in the provided text
723 and expands them accordingly. Check the documentation of strftime().
724
725 The filter accepts parameters as a list of @var{key}=@var{value} pairs,
726 separated by ":".
727
728 The description of the accepted parameters follows.
729
730 @table @option
731
732 @item fontfile
733 The font file to be used for drawing text. Path must be included.
734 This parameter is mandatory.
735
736 @item text
737 The text string to be drawn. The text must be a sequence of UTF-8
738 encoded characters.
739 This parameter is mandatory if no file is specified with the parameter
740 @var{textfile}.
741
742 @item textfile
743 A text file containing text to be drawn. The text must be a sequence
744 of UTF-8 encoded characters.
745
746 This parameter is mandatory if no text string is specified with the
747 parameter @var{text}.
748
749 If both text and textfile are specified, an error is thrown.
750
751 @item x, y
752 The offsets where text will be drawn within the video frame.
753 Relative to the top/left border of the output image.
754 They accept expressions similar to the @ref{overlay} filter:
755 @table @option
756
757 @item x, y
758 the computed values for @var{x} and @var{y}. They are evaluated for
759 each new frame.
760
761 @item main_w, main_h
762 main input width and height
763
764 @item W, H
765 same as @var{main_w} and @var{main_h}
766
767 @item text_w, text_h
768 rendered text width and height
769
770 @item w, h
771 same as @var{text_w} and @var{text_h}
772
773 @item n
774 the number of frames processed, starting from 0
775
776 @item t
777 timestamp expressed in seconds, NAN if the input timestamp is unknown
778
779 @end table
780
781 The default value of @var{x} and @var{y} is 0.
782
783 @item fontsize
784 The font size to be used for drawing text.
785 The default value of @var{fontsize} is 16.
786
787 @item fontcolor
788 The color to be used for drawing fonts.
789 Either a string (e.g. "red") or in 0xRRGGBB[AA] format
790 (e.g. "0xff000033"), possibly followed by an alpha specifier.
791 The default value of @var{fontcolor} is "black".
792
793 @item boxcolor
794 The color to be used for drawing box around text.
795 Either a string (e.g. "yellow") or in 0xRRGGBB[AA] format
796 (e.g. "0xff00ff"), possibly followed by an alpha specifier.
797 The default value of @var{boxcolor} is "white".
798
799 @item box
800 Used to draw a box around text using background color.
801 Value should be either 1 (enable) or 0 (disable).
802 The default value of @var{box} is 0.
803
804 @item shadowx, shadowy
805 The x and y offsets for the text shadow position with respect to the
806 position of the text. They can be either positive or negative
807 values. Default value for both is "0".
808
809 @item shadowcolor
810 The color to be used for drawing a shadow behind the drawn text.  It
811 can be a color name (e.g. "yellow") or a string in the 0xRRGGBB[AA]
812 form (e.g. "0xff00ff"), possibly followed by an alpha specifier.
813 The default value of @var{shadowcolor} is "black".
814
815 @item ft_load_flags
816 Flags to be used for loading the fonts.
817
818 The flags map the corresponding flags supported by libfreetype, and are
819 a combination of the following values:
820 @table @var
821 @item default
822 @item no_scale
823 @item no_hinting
824 @item render
825 @item no_bitmap
826 @item vertical_layout
827 @item force_autohint
828 @item crop_bitmap
829 @item pedantic
830 @item ignore_global_advance_width
831 @item no_recurse
832 @item ignore_transform
833 @item monochrome
834 @item linear_design
835 @item no_autohint
836 @item end table
837 @end table
838
839 Default value is "render".
840
841 For more information consult the documentation for the FT_LOAD_*
842 libfreetype flags.
843
844 @item tabsize
845 The size in number of spaces to use for rendering the tab.
846 Default value is 4.
847
848 @item fix_bounds
849 If true, check and fix text coords to avoid clipping.
850 @end table
851
852 For example the command:
853 @example
854 drawtext="fontfile=/usr/share/fonts/truetype/freefont/FreeSerif.ttf: text='Test Text'"
855 @end example
856
857 will draw "Test Text" with font FreeSerif, using the default values
858 for the optional parameters.
859
860 The command:
861 @example
862 drawtext="fontfile=/usr/share/fonts/truetype/freefont/FreeSerif.ttf: text='Test Text':\
863           x=100: y=50: fontsize=24: fontcolor=yellow@@0.2: box=1: boxcolor=red@@0.2"
864 @end example
865
866 will draw 'Test Text' with font FreeSerif of size 24 at position x=100
867 and y=50 (counting from the top-left corner of the screen), text is
868 yellow with a red box around it. Both the text and the box have an
869 opacity of 20%.
870
871 Note that the double quotes are not necessary if spaces are not used
872 within the parameter list.
873
874 For more information about libfreetype, check:
875 @url{http://www.freetype.org/}.
876
877 @section fade
878
879 Apply fade-in/out effect to input video.
880
881 It accepts the parameters:
882 @var{type}:@var{start_frame}:@var{nb_frames}
883
884 @var{type} specifies if the effect type, can be either "in" for
885 fade-in, or "out" for a fade-out effect.
886
887 @var{start_frame} specifies the number of the start frame for starting
888 to apply the fade effect.
889
890 @var{nb_frames} specifies the number of frames for which the fade
891 effect has to last. At the end of the fade-in effect the output video
892 will have the same intensity as the input video, at the end of the
893 fade-out transition the output video will be completely black.
894
895 A few usage examples follow, usable too as test scenarios.
896 @example
897 # fade in first 30 frames of video
898 fade=in:0:30
899
900 # fade out last 45 frames of a 200-frame video
901 fade=out:155:45
902
903 # fade in first 25 frames and fade out last 25 frames of a 1000-frame video
904 fade=in:0:25, fade=out:975:25
905
906 # make first 5 frames black, then fade in from frame 5-24
907 fade=in:5:20
908 @end example
909
910 @section fieldorder
911
912 Transform the field order of the input video.
913
914 It accepts one parameter which specifies the required field order that
915 the input interlaced video will be transformed to. The parameter can
916 assume one of the following values:
917
918 @table @option
919 @item 0 or bff
920 output bottom field first
921 @item 1 or tff
922 output top field first
923 @end table
924
925 Default value is "tff".
926
927 Transformation is achieved by shifting the picture content up or down
928 by one line, and filling the remaining line with appropriate picture content.
929 This method is consistent with most broadcast field order converters.
930
931 If the input video is not flagged as being interlaced, or it is already
932 flagged as being of the required output field order then this filter does
933 not alter the incoming video.
934
935 This filter is very useful when converting to or from PAL DV material,
936 which is bottom field first.
937
938 For example:
939 @example
940 ./avconv -i in.vob -vf "fieldorder=bff" out.dv
941 @end example
942
943 @section fifo
944
945 Buffer input images and send them when they are requested.
946
947 This filter is mainly useful when auto-inserted by the libavfilter
948 framework.
949
950 The filter does not take parameters.
951
952 @section format
953
954 Convert the input video to one of the specified pixel formats.
955 Libavfilter will try to pick one that is supported for the input to
956 the next filter.
957
958 The filter accepts a list of pixel format names, separated by ":",
959 for example "yuv420p:monow:rgb24".
960
961 Some examples follow:
962 @example
963 # convert the input video to the format "yuv420p"
964 format=yuv420p
965
966 # convert the input video to any of the formats in the list
967 format=yuv420p:yuv444p:yuv410p
968 @end example
969
970 @section fps
971
972 Convert the video to specified constant framerate by duplicating or dropping
973 frames as necessary.
974
975 This filter accepts the following named parameters:
976 @table @option
977
978 @item fps
979 Desired output framerate.
980
981 @end table
982
983 @anchor{frei0r}
984 @section frei0r
985
986 Apply a frei0r effect to the input video.
987
988 To enable compilation of this filter you need to install the frei0r
989 header and configure Libav with --enable-frei0r.
990
991 The filter supports the syntax:
992 @example
993 @var{filter_name}[@{:|=@}@var{param1}:@var{param2}:...:@var{paramN}]
994 @end example
995
996 @var{filter_name} is the name to the frei0r effect to load. If the
997 environment variable @env{FREI0R_PATH} is defined, the frei0r effect
998 is searched in each one of the directories specified by the colon
999 separated list in @env{FREIOR_PATH}, otherwise in the standard frei0r
1000 paths, which are in this order: @file{HOME/.frei0r-1/lib/},
1001 @file{/usr/local/lib/frei0r-1/}, @file{/usr/lib/frei0r-1/}.
1002
1003 @var{param1}, @var{param2}, ... , @var{paramN} specify the parameters
1004 for the frei0r effect.
1005
1006 A frei0r effect parameter can be a boolean (whose values are specified
1007 with "y" and "n"), a double, a color (specified by the syntax
1008 @var{R}/@var{G}/@var{B}, @var{R}, @var{G}, and @var{B} being float
1009 numbers from 0.0 to 1.0) or by an @code{av_parse_color()} color
1010 description), a position (specified by the syntax @var{X}/@var{Y},
1011 @var{X} and @var{Y} being float numbers) and a string.
1012
1013 The number and kind of parameters depend on the loaded effect. If an
1014 effect parameter is not specified the default value is set.
1015
1016 Some examples follow:
1017 @example
1018 # apply the distort0r effect, set the first two double parameters
1019 frei0r=distort0r:0.5:0.01
1020
1021 # apply the colordistance effect, takes a color as first parameter
1022 frei0r=colordistance:0.2/0.3/0.4
1023 frei0r=colordistance:violet
1024 frei0r=colordistance:0x112233
1025
1026 # apply the perspective effect, specify the top left and top right
1027 # image positions
1028 frei0r=perspective:0.2/0.2:0.8/0.2
1029 @end example
1030
1031 For more information see:
1032 @url{http://piksel.org/frei0r}
1033
1034 @section gradfun
1035
1036 Fix the banding artifacts that are sometimes introduced into nearly flat
1037 regions by truncation to 8bit colordepth.
1038 Interpolate the gradients that should go where the bands are, and
1039 dither them.
1040
1041 This filter is designed for playback only.  Do not use it prior to
1042 lossy compression, because compression tends to lose the dither and
1043 bring back the bands.
1044
1045 The filter takes two optional parameters, separated by ':':
1046 @var{strength}:@var{radius}
1047
1048 @var{strength} is the maximum amount by which the filter will change
1049 any one pixel. Also the threshold for detecting nearly flat
1050 regions. Acceptable values range from .51 to 255, default value is
1051 1.2, out-of-range values will be clipped to the valid range.
1052
1053 @var{radius} is the neighborhood to fit the gradient to. A larger
1054 radius makes for smoother gradients, but also prevents the filter from
1055 modifying the pixels near detailed regions. Acceptable values are
1056 8-32, default value is 16, out-of-range values will be clipped to the
1057 valid range.
1058
1059 @example
1060 # default parameters
1061 gradfun=1.2:16
1062
1063 # omitting radius
1064 gradfun=1.2
1065 @end example
1066
1067 @section hflip
1068
1069 Flip the input video horizontally.
1070
1071 For example to horizontally flip the input video with @command{avconv}:
1072 @example
1073 avconv -i in.avi -vf "hflip" out.avi
1074 @end example
1075
1076 @section hqdn3d
1077
1078 High precision/quality 3d denoise filter. This filter aims to reduce
1079 image noise producing smooth images and making still images really
1080 still. It should enhance compressibility.
1081
1082 It accepts the following optional parameters:
1083 @var{luma_spatial}:@var{chroma_spatial}:@var{luma_tmp}:@var{chroma_tmp}
1084
1085 @table @option
1086 @item luma_spatial
1087 a non-negative float number which specifies spatial luma strength,
1088 defaults to 4.0
1089
1090 @item chroma_spatial
1091 a non-negative float number which specifies spatial chroma strength,
1092 defaults to 3.0*@var{luma_spatial}/4.0
1093
1094 @item luma_tmp
1095 a float number which specifies luma temporal strength, defaults to
1096 6.0*@var{luma_spatial}/4.0
1097
1098 @item chroma_tmp
1099 a float number which specifies chroma temporal strength, defaults to
1100 @var{luma_tmp}*@var{chroma_spatial}/@var{luma_spatial}
1101 @end table
1102
1103 @section lut, lutrgb, lutyuv
1104
1105 Compute a look-up table for binding each pixel component input value
1106 to an output value, and apply it to input video.
1107
1108 @var{lutyuv} applies a lookup table to a YUV input video, @var{lutrgb}
1109 to an RGB input video.
1110
1111 These filters accept in input a ":"-separated list of options, which
1112 specify the expressions used for computing the lookup table for the
1113 corresponding pixel component values.
1114
1115 The @var{lut} filter requires either YUV or RGB pixel formats in
1116 input, and accepts the options:
1117 @table @option
1118 @var{c0} (first  pixel component)
1119 @var{c1} (second pixel component)
1120 @var{c2} (third  pixel component)
1121 @var{c3} (fourth pixel component, corresponds to the alpha component)
1122 @end table
1123
1124 The exact component associated to each option depends on the format in
1125 input.
1126
1127 The @var{lutrgb} filter requires RGB pixel formats in input, and
1128 accepts the options:
1129 @table @option
1130 @var{r} (red component)
1131 @var{g} (green component)
1132 @var{b} (blue component)
1133 @var{a} (alpha component)
1134 @end table
1135
1136 The @var{lutyuv} filter requires YUV pixel formats in input, and
1137 accepts the options:
1138 @table @option
1139 @var{y} (Y/luminance component)
1140 @var{u} (U/Cb component)
1141 @var{v} (V/Cr component)
1142 @var{a} (alpha component)
1143 @end table
1144
1145 The expressions can contain the following constants and functions:
1146
1147 @table @option
1148 @item E, PI, PHI
1149 the corresponding mathematical approximated values for e
1150 (euler number), pi (greek PI), PHI (golden ratio)
1151
1152 @item w, h
1153 the input width and height
1154
1155 @item val
1156 input value for the pixel component
1157
1158 @item clipval
1159 the input value clipped in the @var{minval}-@var{maxval} range
1160
1161 @item maxval
1162 maximum value for the pixel component
1163
1164 @item minval
1165 minimum value for the pixel component
1166
1167 @item negval
1168 the negated value for the pixel component value clipped in the
1169 @var{minval}-@var{maxval} range , it corresponds to the expression
1170 "maxval-clipval+minval"
1171
1172 @item clip(val)
1173 the computed value in @var{val} clipped in the
1174 @var{minval}-@var{maxval} range
1175
1176 @item gammaval(gamma)
1177 the computed gamma correction value of the pixel component value
1178 clipped in the @var{minval}-@var{maxval} range, corresponds to the
1179 expression
1180 "pow((clipval-minval)/(maxval-minval)\,@var{gamma})*(maxval-minval)+minval"
1181
1182 @end table
1183
1184 All expressions default to "val".
1185
1186 Some examples follow:
1187 @example
1188 # negate input video
1189 lutrgb="r=maxval+minval-val:g=maxval+minval-val:b=maxval+minval-val"
1190 lutyuv="y=maxval+minval-val:u=maxval+minval-val:v=maxval+minval-val"
1191
1192 # the above is the same as
1193 lutrgb="r=negval:g=negval:b=negval"
1194 lutyuv="y=negval:u=negval:v=negval"
1195
1196 # negate luminance
1197 lutyuv=negval
1198
1199 # remove chroma components, turns the video into a graytone image
1200 lutyuv="u=128:v=128"
1201
1202 # apply a luma burning effect
1203 lutyuv="y=2*val"
1204
1205 # remove green and blue components
1206 lutrgb="g=0:b=0"
1207
1208 # set a constant alpha channel value on input
1209 format=rgba,lutrgb=a="maxval-minval/2"
1210
1211 # correct luminance gamma by a 0.5 factor
1212 lutyuv=y=gammaval(0.5)
1213 @end example
1214
1215 @section negate
1216
1217 Negate input video.
1218
1219 This filter accepts an integer in input, if non-zero it negates the
1220 alpha component (if available). The default value in input is 0.
1221
1222 Force libavfilter not to use any of the specified pixel formats for the
1223 input to the next filter.
1224
1225 The filter accepts a list of pixel format names, separated by ":",
1226 for example "yuv420p:monow:rgb24".
1227
1228 Some examples follow:
1229 @example
1230 # force libavfilter to use a format different from "yuv420p" for the
1231 # input to the vflip filter
1232 noformat=yuv420p,vflip
1233
1234 # convert the input video to any of the formats not contained in the list
1235 noformat=yuv420p:yuv444p:yuv410p
1236 @end example
1237
1238 @section null
1239
1240 Pass the video source unchanged to the output.
1241
1242 @section ocv
1243
1244 Apply video transform using libopencv.
1245
1246 To enable this filter install libopencv library and headers and
1247 configure Libav with --enable-libopencv.
1248
1249 The filter takes the parameters: @var{filter_name}@{:=@}@var{filter_params}.
1250
1251 @var{filter_name} is the name of the libopencv filter to apply.
1252
1253 @var{filter_params} specifies the parameters to pass to the libopencv
1254 filter. If not specified the default values are assumed.
1255
1256 Refer to the official libopencv documentation for more precise
1257 information:
1258 @url{http://opencv.willowgarage.com/documentation/c/image_filtering.html}
1259
1260 Follows the list of supported libopencv filters.
1261
1262 @anchor{dilate}
1263 @subsection dilate
1264
1265 Dilate an image by using a specific structuring element.
1266 This filter corresponds to the libopencv function @code{cvDilate}.
1267
1268 It accepts the parameters: @var{struct_el}:@var{nb_iterations}.
1269
1270 @var{struct_el} represents a structuring element, and has the syntax:
1271 @var{cols}x@var{rows}+@var{anchor_x}x@var{anchor_y}/@var{shape}
1272
1273 @var{cols} and @var{rows} represent the number of columns and rows of
1274 the structuring element, @var{anchor_x} and @var{anchor_y} the anchor
1275 point, and @var{shape} the shape for the structuring element, and
1276 can be one of the values "rect", "cross", "ellipse", "custom".
1277
1278 If the value for @var{shape} is "custom", it must be followed by a
1279 string of the form "=@var{filename}". The file with name
1280 @var{filename} is assumed to represent a binary image, with each
1281 printable character corresponding to a bright pixel. When a custom
1282 @var{shape} is used, @var{cols} and @var{rows} are ignored, the number
1283 or columns and rows of the read file are assumed instead.
1284
1285 The default value for @var{struct_el} is "3x3+0x0/rect".
1286
1287 @var{nb_iterations} specifies the number of times the transform is
1288 applied to the image, and defaults to 1.
1289
1290 Follow some example:
1291 @example
1292 # use the default values
1293 ocv=dilate
1294
1295 # dilate using a structuring element with a 5x5 cross, iterate two times
1296 ocv=dilate=5x5+2x2/cross:2
1297
1298 # read the shape from the file diamond.shape, iterate two times
1299 # the file diamond.shape may contain a pattern of characters like this:
1300 #   *
1301 #  ***
1302 # *****
1303 #  ***
1304 #   *
1305 # the specified cols and rows are ignored (but not the anchor point coordinates)
1306 ocv=0x0+2x2/custom=diamond.shape:2
1307 @end example
1308
1309 @subsection erode
1310
1311 Erode an image by using a specific structuring element.
1312 This filter corresponds to the libopencv function @code{cvErode}.
1313
1314 The filter accepts the parameters: @var{struct_el}:@var{nb_iterations},
1315 with the same syntax and semantics as the @ref{dilate} filter.
1316
1317 @subsection smooth
1318
1319 Smooth the input video.
1320
1321 The filter takes the following parameters:
1322 @var{type}:@var{param1}:@var{param2}:@var{param3}:@var{param4}.
1323
1324 @var{type} is the type of smooth filter to apply, and can be one of
1325 the following values: "blur", "blur_no_scale", "median", "gaussian",
1326 "bilateral". The default value is "gaussian".
1327
1328 @var{param1}, @var{param2}, @var{param3}, and @var{param4} are
1329 parameters whose meanings depend on smooth type. @var{param1} and
1330 @var{param2} accept integer positive values or 0, @var{param3} and
1331 @var{param4} accept float values.
1332
1333 The default value for @var{param1} is 3, the default value for the
1334 other parameters is 0.
1335
1336 These parameters correspond to the parameters assigned to the
1337 libopencv function @code{cvSmooth}.
1338
1339 @anchor{overlay}
1340 @section overlay
1341
1342 Overlay one video on top of another.
1343
1344 It takes two inputs and one output, the first input is the "main"
1345 video on which the second input is overlayed.
1346
1347 It accepts the parameters: @var{x}:@var{y}.
1348
1349 @var{x} is the x coordinate of the overlayed video on the main video,
1350 @var{y} is the y coordinate. The parameters are expressions containing
1351 the following parameters:
1352
1353 @table @option
1354 @item main_w, main_h
1355 main input width and height
1356
1357 @item W, H
1358 same as @var{main_w} and @var{main_h}
1359
1360 @item overlay_w, overlay_h
1361 overlay input width and height
1362
1363 @item w, h
1364 same as @var{overlay_w} and @var{overlay_h}
1365 @end table
1366
1367 Be aware that frames are taken from each input video in timestamp
1368 order, hence, if their initial timestamps differ, it is a a good idea
1369 to pass the two inputs through a @var{setpts=PTS-STARTPTS} filter to
1370 have them begin in the same zero timestamp, as it does the example for
1371 the @var{movie} filter.
1372
1373 Follow some examples:
1374 @example
1375 # draw the overlay at 10 pixels from the bottom right
1376 # corner of the main video.
1377 overlay=main_w-overlay_w-10:main_h-overlay_h-10
1378
1379 # insert a transparent PNG logo in the bottom left corner of the input
1380 avconv -i input -i logo -filter_complex 'overlay=10:main_h-overlay_h-10' output
1381
1382 # insert 2 different transparent PNG logos (second logo on bottom
1383 # right corner):
1384 avconv -i input -i logo1 -i logo2 -filter_complex
1385 'overlay=10:H-h-10,overlay=W-w-10:H-h-10' output
1386
1387 # add a transparent color layer on top of the main video,
1388 # WxH specifies the size of the main input to the overlay filter
1389 color=red@.3:WxH [over]; [in][over] overlay [out]
1390 @end example
1391
1392 You can chain together more overlays but the efficiency of such
1393 approach is yet to be tested.
1394
1395 @section pad
1396
1397 Add paddings to the input image, and places the original input at the
1398 given coordinates @var{x}, @var{y}.
1399
1400 It accepts the following parameters:
1401 @var{width}:@var{height}:@var{x}:@var{y}:@var{color}.
1402
1403 The parameters @var{width}, @var{height}, @var{x}, and @var{y} are
1404 expressions containing the following constants:
1405
1406 @table @option
1407 @item E, PI, PHI
1408 the corresponding mathematical approximated values for e
1409 (euler number), pi (greek PI), phi (golden ratio)
1410
1411 @item in_w, in_h
1412 the input video width and height
1413
1414 @item iw, ih
1415 same as @var{in_w} and @var{in_h}
1416
1417 @item out_w, out_h
1418 the output width and height, that is the size of the padded area as
1419 specified by the @var{width} and @var{height} expressions
1420
1421 @item ow, oh
1422 same as @var{out_w} and @var{out_h}
1423
1424 @item x, y
1425 x and y offsets as specified by the @var{x} and @var{y}
1426 expressions, or NAN if not yet specified
1427
1428 @item a
1429 input display aspect ratio, same as @var{iw} / @var{ih}
1430
1431 @item hsub, vsub
1432 horizontal and vertical chroma subsample values. For example for the
1433 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
1434 @end table
1435
1436 Follows the description of the accepted parameters.
1437
1438 @table @option
1439 @item width, height
1440
1441 Specify the size of the output image with the paddings added. If the
1442 value for @var{width} or @var{height} is 0, the corresponding input size
1443 is used for the output.
1444
1445 The @var{width} expression can reference the value set by the
1446 @var{height} expression, and vice versa.
1447
1448 The default value of @var{width} and @var{height} is 0.
1449
1450 @item x, y
1451
1452 Specify the offsets where to place the input image in the padded area
1453 with respect to the top/left border of the output image.
1454
1455 The @var{x} expression can reference the value set by the @var{y}
1456 expression, and vice versa.
1457
1458 The default value of @var{x} and @var{y} is 0.
1459
1460 @item color
1461
1462 Specify the color of the padded area, it can be the name of a color
1463 (case insensitive match) or a 0xRRGGBB[AA] sequence.
1464
1465 The default value of @var{color} is "black".
1466
1467 @end table
1468
1469 Some examples follow:
1470
1471 @example
1472 # Add paddings with color "violet" to the input video. Output video
1473 # size is 640x480, the top-left corner of the input video is placed at
1474 # column 0, row 40.
1475 pad=640:480:0:40:violet
1476
1477 # pad the input to get an output with dimensions increased bt 3/2,
1478 # and put the input video at the center of the padded area
1479 pad="3/2*iw:3/2*ih:(ow-iw)/2:(oh-ih)/2"
1480
1481 # pad the input to get a squared output with size equal to the maximum
1482 # value between the input width and height, and put the input video at
1483 # the center of the padded area
1484 pad="max(iw\,ih):ow:(ow-iw)/2:(oh-ih)/2"
1485
1486 # pad the input to get a final w/h ratio of 16:9
1487 pad="ih*16/9:ih:(ow-iw)/2:(oh-ih)/2"
1488
1489 # double output size and put the input video in the bottom-right
1490 # corner of the output padded area
1491 pad="2*iw:2*ih:ow-iw:oh-ih"
1492 @end example
1493
1494 @section pixdesctest
1495
1496 Pixel format descriptor test filter, mainly useful for internal
1497 testing. The output video should be equal to the input video.
1498
1499 For example:
1500 @example
1501 format=monow, pixdesctest
1502 @end example
1503
1504 can be used to test the monowhite pixel format descriptor definition.
1505
1506 @section scale
1507
1508 Scale the input video to @var{width}:@var{height} and/or convert the image format.
1509
1510 The parameters @var{width} and @var{height} are expressions containing
1511 the following constants:
1512
1513 @table @option
1514 @item E, PI, PHI
1515 the corresponding mathematical approximated values for e
1516 (euler number), pi (greek PI), phi (golden ratio)
1517
1518 @item in_w, in_h
1519 the input width and height
1520
1521 @item iw, ih
1522 same as @var{in_w} and @var{in_h}
1523
1524 @item out_w, out_h
1525 the output (cropped) width and height
1526
1527 @item ow, oh
1528 same as @var{out_w} and @var{out_h}
1529
1530 @item dar, a
1531 input display aspect ratio, same as @var{iw} / @var{ih}
1532
1533 @item sar
1534 input sample aspect ratio
1535
1536 @item hsub, vsub
1537 horizontal and vertical chroma subsample values. For example for the
1538 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
1539 @end table
1540
1541 If the input image format is different from the format requested by
1542 the next filter, the scale filter will convert the input to the
1543 requested format.
1544
1545 If the value for @var{width} or @var{height} is 0, the respective input
1546 size is used for the output.
1547
1548 If the value for @var{width} or @var{height} is -1, the scale filter will
1549 use, for the respective output size, a value that maintains the aspect
1550 ratio of the input image.
1551
1552 The default value of @var{width} and @var{height} is 0.
1553
1554 Some examples follow:
1555 @example
1556 # scale the input video to a size of 200x100.
1557 scale=200:100
1558
1559 # scale the input to 2x
1560 scale=2*iw:2*ih
1561 # the above is the same as
1562 scale=2*in_w:2*in_h
1563
1564 # scale the input to half size
1565 scale=iw/2:ih/2
1566
1567 # increase the width, and set the height to the same size
1568 scale=3/2*iw:ow
1569
1570 # seek for Greek harmony
1571 scale=iw:1/PHI*iw
1572 scale=ih*PHI:ih
1573
1574 # increase the height, and set the width to 3/2 of the height
1575 scale=3/2*oh:3/5*ih
1576
1577 # increase the size, but make the size a multiple of the chroma
1578 scale="trunc(3/2*iw/hsub)*hsub:trunc(3/2*ih/vsub)*vsub"
1579
1580 # increase the width to a maximum of 500 pixels, keep the same input aspect ratio
1581 scale='min(500\, iw*3/2):-1'
1582 @end example
1583
1584 @section select
1585 Select frames to pass in output.
1586
1587 It accepts in input an expression, which is evaluated for each input
1588 frame. If the expression is evaluated to a non-zero value, the frame
1589 is selected and passed to the output, otherwise it is discarded.
1590
1591 The expression can contain the following constants:
1592
1593 @table @option
1594 @item PI
1595 Greek PI
1596
1597 @item PHI
1598 golden ratio
1599
1600 @item E
1601 Euler number
1602
1603 @item n
1604 the sequential number of the filtered frame, starting from 0
1605
1606 @item selected_n
1607 the sequential number of the selected frame, starting from 0
1608
1609 @item prev_selected_n
1610 the sequential number of the last selected frame, NAN if undefined
1611
1612 @item TB
1613 timebase of the input timestamps
1614
1615 @item pts
1616 the PTS (Presentation TimeStamp) of the filtered video frame,
1617 expressed in @var{TB} units, NAN if undefined
1618
1619 @item t
1620 the PTS (Presentation TimeStamp) of the filtered video frame,
1621 expressed in seconds, NAN if undefined
1622
1623 @item prev_pts
1624 the PTS of the previously filtered video frame, NAN if undefined
1625
1626 @item prev_selected_pts
1627 the PTS of the last previously filtered video frame, NAN if undefined
1628
1629 @item prev_selected_t
1630 the PTS of the last previously selected video frame, NAN if undefined
1631
1632 @item start_pts
1633 the PTS of the first video frame in the video, NAN if undefined
1634
1635 @item start_t
1636 the time of the first video frame in the video, NAN if undefined
1637
1638 @item pict_type
1639 the type of the filtered frame, can assume one of the following
1640 values:
1641 @table @option
1642 @item I
1643 @item P
1644 @item B
1645 @item S
1646 @item SI
1647 @item SP
1648 @item BI
1649 @end table
1650
1651 @item interlace_type
1652 the frame interlace type, can assume one of the following values:
1653 @table @option
1654 @item PROGRESSIVE
1655 the frame is progressive (not interlaced)
1656 @item TOPFIRST
1657 the frame is top-field-first
1658 @item BOTTOMFIRST
1659 the frame is bottom-field-first
1660 @end table
1661
1662 @item key
1663 1 if the filtered frame is a key-frame, 0 otherwise
1664
1665 @item pos
1666 the position in the file of the filtered frame, -1 if the information
1667 is not available (e.g. for synthetic video)
1668 @end table
1669
1670 The default value of the select expression is "1".
1671
1672 Some examples follow:
1673
1674 @example
1675 # select all frames in input
1676 select
1677
1678 # the above is the same as:
1679 select=1
1680
1681 # skip all frames:
1682 select=0
1683
1684 # select only I-frames
1685 select='eq(pict_type\,I)'
1686
1687 # select one frame every 100
1688 select='not(mod(n\,100))'
1689
1690 # select only frames contained in the 10-20 time interval
1691 select='gte(t\,10)*lte(t\,20)'
1692
1693 # select only I frames contained in the 10-20 time interval
1694 select='gte(t\,10)*lte(t\,20)*eq(pict_type\,I)'
1695
1696 # select frames with a minimum distance of 10 seconds
1697 select='isnan(prev_selected_t)+gte(t-prev_selected_t\,10)'
1698 @end example
1699
1700 @anchor{setdar}
1701 @section setdar
1702
1703 Set the Display Aspect Ratio for the filter output video.
1704
1705 This is done by changing the specified Sample (aka Pixel) Aspect
1706 Ratio, according to the following equation:
1707 @math{DAR = HORIZONTAL_RESOLUTION / VERTICAL_RESOLUTION * SAR}
1708
1709 Keep in mind that this filter does not modify the pixel dimensions of
1710 the video frame. Also the display aspect ratio set by this filter may
1711 be changed by later filters in the filterchain, e.g. in case of
1712 scaling or if another "setdar" or a "setsar" filter is applied.
1713
1714 The filter accepts a parameter string which represents the wanted
1715 display aspect ratio.
1716 The parameter can be a floating point number string, or an expression
1717 of the form @var{num}:@var{den}, where @var{num} and @var{den} are the
1718 numerator and denominator of the aspect ratio.
1719 If the parameter is not specified, it is assumed the value "0:1".
1720
1721 For example to change the display aspect ratio to 16:9, specify:
1722 @example
1723 setdar=16:9
1724 # the above is equivalent to
1725 setdar=1.77777
1726 @end example
1727
1728 See also the @ref{setsar} filter documentation.
1729
1730 @section setpts
1731
1732 Change the PTS (presentation timestamp) of the input video frames.
1733
1734 Accept in input an expression evaluated through the eval API, which
1735 can contain the following constants:
1736
1737 @table @option
1738 @item PTS
1739 the presentation timestamp in input
1740
1741 @item PI
1742 Greek PI
1743
1744 @item PHI
1745 golden ratio
1746
1747 @item E
1748 Euler number
1749
1750 @item N
1751 the count of the input frame, starting from 0.
1752
1753 @item STARTPTS
1754 the PTS of the first video frame
1755
1756 @item INTERLACED
1757 tell if the current frame is interlaced
1758
1759 @item POS
1760 original position in the file of the frame, or undefined if undefined
1761 for the current frame
1762
1763 @item PREV_INPTS
1764 previous input PTS
1765
1766 @item PREV_OUTPTS
1767 previous output PTS
1768
1769 @end table
1770
1771 Some examples follow:
1772
1773 @example
1774 # start counting PTS from zero
1775 setpts=PTS-STARTPTS
1776
1777 # fast motion
1778 setpts=0.5*PTS
1779
1780 # slow motion
1781 setpts=2.0*PTS
1782
1783 # fixed rate 25 fps
1784 setpts=N/(25*TB)
1785
1786 # fixed rate 25 fps with some jitter
1787 setpts='1/(25*TB) * (N + 0.05 * sin(N*2*PI/25))'
1788 @end example
1789
1790 @anchor{setsar}
1791 @section setsar
1792
1793 Set the Sample (aka Pixel) Aspect Ratio for the filter output video.
1794
1795 Note that as a consequence of the application of this filter, the
1796 output display aspect ratio will change according to the following
1797 equation:
1798 @math{DAR = HORIZONTAL_RESOLUTION / VERTICAL_RESOLUTION * SAR}
1799
1800 Keep in mind that the sample aspect ratio set by this filter may be
1801 changed by later filters in the filterchain, e.g. if another "setsar"
1802 or a "setdar" filter is applied.
1803
1804 The filter accepts a parameter string which represents the wanted
1805 sample aspect ratio.
1806 The parameter can be a floating point number string, or an expression
1807 of the form @var{num}:@var{den}, where @var{num} and @var{den} are the
1808 numerator and denominator of the aspect ratio.
1809 If the parameter is not specified, it is assumed the value "0:1".
1810
1811 For example to change the sample aspect ratio to 10:11, specify:
1812 @example
1813 setsar=10:11
1814 @end example
1815
1816 @section settb
1817
1818 Set the timebase to use for the output frames timestamps.
1819 It is mainly useful for testing timebase configuration.
1820
1821 It accepts in input an arithmetic expression representing a rational.
1822 The expression can contain the constants "PI", "E", "PHI", "AVTB" (the
1823 default timebase), and "intb" (the input timebase).
1824
1825 The default value for the input is "intb".
1826
1827 Follow some examples.
1828
1829 @example
1830 # set the timebase to 1/25
1831 settb=1/25
1832
1833 # set the timebase to 1/10
1834 settb=0.1
1835
1836 #set the timebase to 1001/1000
1837 settb=1+0.001
1838
1839 #set the timebase to 2*intb
1840 settb=2*intb
1841
1842 #set the default timebase value
1843 settb=AVTB
1844 @end example
1845
1846 @section showinfo
1847
1848 Show a line containing various information for each input video frame.
1849 The input video is not modified.
1850
1851 The shown line contains a sequence of key/value pairs of the form
1852 @var{key}:@var{value}.
1853
1854 A description of each shown parameter follows:
1855
1856 @table @option
1857 @item n
1858 sequential number of the input frame, starting from 0
1859
1860 @item pts
1861 Presentation TimeStamp of the input frame, expressed as a number of
1862 time base units. The time base unit depends on the filter input pad.
1863
1864 @item pts_time
1865 Presentation TimeStamp of the input frame, expressed as a number of
1866 seconds
1867
1868 @item pos
1869 position of the frame in the input stream, -1 if this information in
1870 unavailable and/or meaningless (for example in case of synthetic video)
1871
1872 @item fmt
1873 pixel format name
1874
1875 @item sar
1876 sample aspect ratio of the input frame, expressed in the form
1877 @var{num}/@var{den}
1878
1879 @item s
1880 size of the input frame, expressed in the form
1881 @var{width}x@var{height}
1882
1883 @item i
1884 interlaced mode ("P" for "progressive", "T" for top field first, "B"
1885 for bottom field first)
1886
1887 @item iskey
1888 1 if the frame is a key frame, 0 otherwise
1889
1890 @item type
1891 picture type of the input frame ("I" for an I-frame, "P" for a
1892 P-frame, "B" for a B-frame, "?" for unknown type).
1893 Check also the documentation of the @code{AVPictureType} enum and of
1894 the @code{av_get_picture_type_char} function defined in
1895 @file{libavutil/avutil.h}.
1896
1897 @item checksum
1898 Adler-32 checksum of all the planes of the input frame
1899
1900 @item plane_checksum
1901 Adler-32 checksum of each plane of the input frame, expressed in the form
1902 "[@var{c0} @var{c1} @var{c2} @var{c3}]"
1903 @end table
1904
1905 @section slicify
1906
1907 Pass the images of input video on to next video filter as multiple
1908 slices.
1909
1910 @example
1911 ./avconv -i in.avi -vf "slicify=32" out.avi
1912 @end example
1913
1914 The filter accepts the slice height as parameter. If the parameter is
1915 not specified it will use the default value of 16.
1916
1917 Adding this in the beginning of filter chains should make filtering
1918 faster due to better use of the memory cache.
1919
1920 @section split
1921
1922 Split input video into several identical outputs.
1923
1924 The filter accepts a single parameter which specifies the number of outputs. If
1925 unspecified, it defaults to 2.
1926
1927 For example
1928 @example
1929 avconv -i INPUT -filter_complex split=5 OUTPUT
1930 @end example
1931 will create 5 copies of the input video.
1932
1933 @section transpose
1934
1935 Transpose rows with columns in the input video and optionally flip it.
1936
1937 It accepts a parameter representing an integer, which can assume the
1938 values:
1939
1940 @table @samp
1941 @item 0
1942 Rotate by 90 degrees counterclockwise and vertically flip (default), that is:
1943 @example
1944 L.R     L.l
1945 . . ->  . .
1946 l.r     R.r
1947 @end example
1948
1949 @item 1
1950 Rotate by 90 degrees clockwise, that is:
1951 @example
1952 L.R     l.L
1953 . . ->  . .
1954 l.r     r.R
1955 @end example
1956
1957 @item 2
1958 Rotate by 90 degrees counterclockwise, that is:
1959 @example
1960 L.R     R.r
1961 . . ->  . .
1962 l.r     L.l
1963 @end example
1964
1965 @item 3
1966 Rotate by 90 degrees clockwise and vertically flip, that is:
1967 @example
1968 L.R     r.R
1969 . . ->  . .
1970 l.r     l.L
1971 @end example
1972 @end table
1973
1974 @section unsharp
1975
1976 Sharpen or blur the input video.
1977
1978 It accepts the following parameters:
1979 @var{luma_msize_x}:@var{luma_msize_y}:@var{luma_amount}:@var{chroma_msize_x}:@var{chroma_msize_y}:@var{chroma_amount}
1980
1981 Negative values for the amount will blur the input video, while positive
1982 values will sharpen. All parameters are optional and default to the
1983 equivalent of the string '5:5:1.0:5:5:0.0'.
1984
1985 @table @option
1986
1987 @item luma_msize_x
1988 Set the luma matrix horizontal size. It can be an integer between 3
1989 and 13, default value is 5.
1990
1991 @item luma_msize_y
1992 Set the luma matrix vertical size. It can be an integer between 3
1993 and 13, default value is 5.
1994
1995 @item luma_amount
1996 Set the luma effect strength. It can be a float number between -2.0
1997 and 5.0, default value is 1.0.
1998
1999 @item chroma_msize_x
2000 Set the chroma matrix horizontal size. It can be an integer between 3
2001 and 13, default value is 5.
2002
2003 @item chroma_msize_y
2004 Set the chroma matrix vertical size. It can be an integer between 3
2005 and 13, default value is 5.
2006
2007 @item luma_amount
2008 Set the chroma effect strength. It can be a float number between -2.0
2009 and 5.0, default value is 0.0.
2010
2011 @end table
2012
2013 @example
2014 # Strong luma sharpen effect parameters
2015 unsharp=7:7:2.5
2016
2017 # Strong blur of both luma and chroma parameters
2018 unsharp=7:7:-2:7:7:-2
2019
2020 # Use the default values with @command{avconv}
2021 ./avconv -i in.avi -vf "unsharp" out.mp4
2022 @end example
2023
2024 @section vflip
2025
2026 Flip the input video vertically.
2027
2028 @example
2029 ./avconv -i in.avi -vf "vflip" out.avi
2030 @end example
2031
2032 @section yadif
2033
2034 Deinterlace the input video ("yadif" means "yet another deinterlacing
2035 filter").
2036
2037 It accepts the optional parameters: @var{mode}:@var{parity}:@var{auto}.
2038
2039 @var{mode} specifies the interlacing mode to adopt, accepts one of the
2040 following values:
2041
2042 @table @option
2043 @item 0
2044 output 1 frame for each frame
2045 @item 1
2046 output 1 frame for each field
2047 @item 2
2048 like 0 but skips spatial interlacing check
2049 @item 3
2050 like 1 but skips spatial interlacing check
2051 @end table
2052
2053 Default value is 0.
2054
2055 @var{parity} specifies the picture field parity assumed for the input
2056 interlaced video, accepts one of the following values:
2057
2058 @table @option
2059 @item 0
2060 assume top field first
2061 @item 1
2062 assume bottom field first
2063 @item -1
2064 enable automatic detection
2065 @end table
2066
2067 Default value is -1.
2068 If interlacing is unknown or decoder does not export this information,
2069 top field first will be assumed.
2070
2071 @var{auto} specifies if deinterlacer should trust the interlaced flag
2072 and only deinterlace frames marked as interlaced
2073
2074 @table @option
2075 @item 0
2076 deinterlace all frames
2077 @item 1
2078 only deinterlace frames marked as interlaced
2079 @end table
2080
2081 Default value is 0.
2082
2083 @c man end VIDEO FILTERS
2084
2085 @chapter Video Sources
2086 @c man begin VIDEO SOURCES
2087
2088 Below is a description of the currently available video sources.
2089
2090 @section buffer
2091
2092 Buffer video frames, and make them available to the filter chain.
2093
2094 This source is mainly intended for a programmatic use, in particular
2095 through the interface defined in @file{libavfilter/vsrc_buffer.h}.
2096
2097 It accepts the following parameters:
2098 @var{width}:@var{height}:@var{pix_fmt_string}:@var{timebase_num}:@var{timebase_den}:@var{sample_aspect_ratio_num}:@var{sample_aspect_ratio.den}
2099
2100 All the parameters need to be explicitly defined.
2101
2102 Follows the list of the accepted parameters.
2103
2104 @table @option
2105
2106 @item width, height
2107 Specify the width and height of the buffered video frames.
2108
2109 @item pix_fmt_string
2110 A string representing the pixel format of the buffered video frames.
2111 It may be a number corresponding to a pixel format, or a pixel format
2112 name.
2113
2114 @item timebase_num, timebase_den
2115 Specify numerator and denomitor of the timebase assumed by the
2116 timestamps of the buffered frames.
2117
2118 @item sample_aspect_ratio.num, sample_aspect_ratio.den
2119 Specify numerator and denominator of the sample aspect ratio assumed
2120 by the video frames.
2121 @end table
2122
2123 For example:
2124 @example
2125 buffer=320:240:yuv410p:1:24:1:1
2126 @end example
2127
2128 will instruct the source to accept video frames with size 320x240 and
2129 with format "yuv410p", assuming 1/24 as the timestamps timebase and
2130 square pixels (1:1 sample aspect ratio).
2131 Since the pixel format with name "yuv410p" corresponds to the number 6
2132 (check the enum PixelFormat definition in @file{libavutil/pixfmt.h}),
2133 this example corresponds to:
2134 @example
2135 buffer=320:240:6:1:24
2136 @end example
2137
2138 @section color
2139
2140 Provide an uniformly colored input.
2141
2142 It accepts the following parameters:
2143 @var{color}:@var{frame_size}:@var{frame_rate}
2144
2145 Follows the description of the accepted parameters.
2146
2147 @table @option
2148
2149 @item color
2150 Specify the color of the source. It can be the name of a color (case
2151 insensitive match) or a 0xRRGGBB[AA] sequence, possibly followed by an
2152 alpha specifier. The default value is "black".
2153
2154 @item frame_size
2155 Specify the size of the sourced video, it may be a string of the form
2156 @var{width}x@var{height}, or the name of a size abbreviation. The
2157 default value is "320x240".
2158
2159 @item frame_rate
2160 Specify the frame rate of the sourced video, as the number of frames
2161 generated per second. It has to be a string in the format
2162 @var{frame_rate_num}/@var{frame_rate_den}, an integer number, a float
2163 number or a valid video frame rate abbreviation. The default value is
2164 "25".
2165
2166 @end table
2167
2168 For example the following graph description will generate a red source
2169 with an opacity of 0.2, with size "qcif" and a frame rate of 10
2170 frames per second, which will be overlayed over the source connected
2171 to the pad with identifier "in".
2172
2173 @example
2174 "color=red@@0.2:qcif:10 [color]; [in][color] overlay [out]"
2175 @end example
2176
2177 @section movie
2178
2179 Read a video stream from a movie container.
2180
2181 It accepts the syntax: @var{movie_name}[:@var{options}] where
2182 @var{movie_name} is the name of the resource to read (not necessarily
2183 a file but also a device or a stream accessed through some protocol),
2184 and @var{options} is an optional sequence of @var{key}=@var{value}
2185 pairs, separated by ":".
2186
2187 The description of the accepted options follows.
2188
2189 @table @option
2190
2191 @item format_name, f
2192 Specifies the format assumed for the movie to read, and can be either
2193 the name of a container or an input device. If not specified the
2194 format is guessed from @var{movie_name} or by probing.
2195
2196 @item seek_point, sp
2197 Specifies the seek point in seconds, the frames will be output
2198 starting from this seek point, the parameter is evaluated with
2199 @code{av_strtod} so the numerical value may be suffixed by an IS
2200 postfix. Default value is "0".
2201
2202 @item stream_index, si
2203 Specifies the index of the video stream to read. If the value is -1,
2204 the best suited video stream will be automatically selected. Default
2205 value is "-1".
2206
2207 @end table
2208
2209 This filter allows to overlay a second video on top of main input of
2210 a filtergraph as shown in this graph:
2211 @example
2212 input -----------> deltapts0 --> overlay --> output
2213                                     ^
2214                                     |
2215 movie --> scale--> deltapts1 -------+
2216 @end example
2217
2218 Some examples follow:
2219 @example
2220 # skip 3.2 seconds from the start of the avi file in.avi, and overlay it
2221 # on top of the input labelled as "in".
2222 movie=in.avi:seek_point=3.2, scale=180:-1, setpts=PTS-STARTPTS [movie];
2223 [in] setpts=PTS-STARTPTS, [movie] overlay=16:16 [out]
2224
2225 # read from a video4linux2 device, and overlay it on top of the input
2226 # labelled as "in"
2227 movie=/dev/video0:f=video4linux2, scale=180:-1, setpts=PTS-STARTPTS [movie];
2228 [in] setpts=PTS-STARTPTS, [movie] overlay=16:16 [out]
2229
2230 @end example
2231
2232 @section nullsrc
2233
2234 Null video source, never return images. It is mainly useful as a
2235 template and to be employed in analysis / debugging tools.
2236
2237 It accepts as optional parameter a string of the form
2238 @var{width}:@var{height}:@var{timebase}.
2239
2240 @var{width} and @var{height} specify the size of the configured
2241 source. The default values of @var{width} and @var{height} are
2242 respectively 352 and 288 (corresponding to the CIF size format).
2243
2244 @var{timebase} specifies an arithmetic expression representing a
2245 timebase. The expression can contain the constants "PI", "E", "PHI",
2246 "AVTB" (the default timebase), and defaults to the value "AVTB".
2247
2248 @section frei0r_src
2249
2250 Provide a frei0r source.
2251
2252 To enable compilation of this filter you need to install the frei0r
2253 header and configure Libav with --enable-frei0r.
2254
2255 The source supports the syntax:
2256 @example
2257 @var{size}:@var{rate}:@var{src_name}[@{=|:@}@var{param1}:@var{param2}:...:@var{paramN}]
2258 @end example
2259
2260 @var{size} is the size of the video to generate, may be a string of the
2261 form @var{width}x@var{height} or a frame size abbreviation.
2262 @var{rate} is the rate of the video to generate, may be a string of
2263 the form @var{num}/@var{den} or a frame rate abbreviation.
2264 @var{src_name} is the name to the frei0r source to load. For more
2265 information regarding frei0r and how to set the parameters read the
2266 section @ref{frei0r} in the description of the video filters.
2267
2268 Some examples follow:
2269 @example
2270 # generate a frei0r partik0l source with size 200x200 and framerate 10
2271 # which is overlayed on the overlay filter main input
2272 frei0r_src=200x200:10:partik0l=1234 [overlay]; [in][overlay] overlay
2273 @end example
2274
2275 @section rgbtestsrc, testsrc
2276
2277 The @code{rgbtestsrc} source generates an RGB test pattern useful for
2278 detecting RGB vs BGR issues. You should see a red, green and blue
2279 stripe from top to bottom.
2280
2281 The @code{testsrc} source generates a test video pattern, showing a
2282 color pattern, a scrolling gradient and a timestamp. This is mainly
2283 intended for testing purposes.
2284
2285 Both sources accept an optional sequence of @var{key}=@var{value} pairs,
2286 separated by ":". The description of the accepted options follows.
2287
2288 @table @option
2289
2290 @item size, s
2291 Specify the size of the sourced video, it may be a string of the form
2292 @var{width}x@var{height}, or the name of a size abbreviation. The
2293 default value is "320x240".
2294
2295 @item rate, r
2296 Specify the frame rate of the sourced video, as the number of frames
2297 generated per second. It has to be a string in the format
2298 @var{frame_rate_num}/@var{frame_rate_den}, an integer number, a float
2299 number or a valid video frame rate abbreviation. The default value is
2300 "25".
2301
2302 @item sar
2303 Set the sample aspect ratio of the sourced video.
2304
2305 @item duration
2306 Set the video duration of the sourced video. The accepted syntax is:
2307 @example
2308 [-]HH[:MM[:SS[.m...]]]
2309 [-]S+[.m...]
2310 @end example
2311 See also the function @code{av_parse_time()}.
2312
2313 If not specified, or the expressed duration is negative, the video is
2314 supposed to be generated forever.
2315 @end table
2316
2317 For example the following:
2318 @example
2319 testsrc=duration=5.3:size=qcif:rate=10
2320 @end example
2321
2322 will generate a video with a duration of 5.3 seconds, with size
2323 176x144 and a framerate of 10 frames per second.
2324
2325 @c man end VIDEO SOURCES
2326
2327 @chapter Video Sinks
2328 @c man begin VIDEO SINKS
2329
2330 Below is a description of the currently available video sinks.
2331
2332 @section buffersink
2333
2334 Buffer video frames, and make them available to the end of the filter
2335 graph.
2336
2337 This sink is intended for a programmatic use through the interface defined in
2338 @file{libavfilter/buffersink.h}.
2339
2340 @section nullsink
2341
2342 Null video sink, do absolutely nothing with the input video. It is
2343 mainly useful as a template and to be employed in analysis / debugging
2344 tools.
2345
2346 @c man end VIDEO SINKS