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