1@chapter Filtering Introduction 2@c man begin FILTERING INTRODUCTION 3 4Filtering in FFmpeg is enabled through the libavfilter library. 5 6In libavfilter, a filter can have multiple inputs and multiple 7outputs. 8To illustrate the sorts of things that are possible, we consider the 9following filtergraph. 10 11@example 12 [main] 13input --> split ---------------------> overlay --> output 14 | ^ 15 |[tmp] [flip]| 16 +-----> crop --> vflip -------+ 17@end example 18 19This filtergraph splits the input stream in two streams, then sends one 20stream through the crop filter and the vflip filter, before merging it 21back with the other stream by overlaying it on top. You can use the 22following command to achieve this: 23 24@example 25ffmpeg -i INPUT -vf "split [main][tmp]; [tmp] crop=iw:ih/2:0:0, vflip [flip]; [main][flip] overlay=0:H/2" OUTPUT 26@end example 27 28The result will be that the top half of the video is mirrored 29onto the bottom half of the output video. 30 31Filters in the same linear chain are separated by commas, and distinct 32linear chains of filters are separated by semicolons. In our example, 33@var{crop,vflip} are in one linear chain, @var{split} and 34@var{overlay} are separately in another. The points where the linear 35chains join are labelled by names enclosed in square brackets. In the 36example, the split filter generates two outputs that are associated to 37the labels @var{[main]} and @var{[tmp]}. 38 39The stream sent to the second output of @var{split}, labelled as 40@var{[tmp]}, is processed through the @var{crop} filter, which crops 41away the lower half part of the video, and then vertically flipped. The 42@var{overlay} filter takes in input the first unchanged output of the 43split filter (which was labelled as @var{[main]}), and overlay on its 44lower half the output generated by the @var{crop,vflip} filterchain. 45 46Some filters take in input a list of parameters: they are specified 47after the filter name and an equal sign, and are separated from each other 48by a colon. 49 50There exist so-called @var{source filters} that do not have an 51audio/video input, and @var{sink filters} that will not have audio/video 52output. 53 54@c man end FILTERING INTRODUCTION 55 56@chapter graph2dot 57@c man begin GRAPH2DOT 58 59The @file{graph2dot} program included in the FFmpeg @file{tools} 60directory can be used to parse a filtergraph description and issue a 61corresponding textual representation in the dot language. 62 63Invoke the command: 64@example 65graph2dot -h 66@end example 67 68to see how to use @file{graph2dot}. 69 70You can then pass the dot description to the @file{dot} program (from 71the graphviz suite of programs) and obtain a graphical representation 72of the filtergraph. 73 74For example the sequence of commands: 75@example 76echo @var{GRAPH_DESCRIPTION} | \ 77tools/graph2dot -o graph.tmp && \ 78dot -Tpng graph.tmp -o graph.png && \ 79display graph.png 80@end example 81 82can be used to create and display an image representing the graph 83described by the @var{GRAPH_DESCRIPTION} string. Note that this string must be 84a complete self-contained graph, with its inputs and outputs explicitly defined. 85For example if your command line is of the form: 86@example 87ffmpeg -i infile -vf scale=640:360 outfile 88@end example 89your @var{GRAPH_DESCRIPTION} string will need to be of the form: 90@example 91nullsrc,scale=640:360,nullsink 92@end example 93you may also need to set the @var{nullsrc} parameters and add a @var{format} 94filter in order to simulate a specific input file. 95 96@c man end GRAPH2DOT 97 98@chapter Filtergraph description 99@c man begin FILTERGRAPH DESCRIPTION 100 101A filtergraph is a directed graph of connected filters. It can contain 102cycles, and there can be multiple links between a pair of 103filters. Each link has one input pad on one side connecting it to one 104filter from which it takes its input, and one output pad on the other 105side connecting it to one filter accepting its output. 106 107Each filter in a filtergraph is an instance of a filter class 108registered in the application, which defines the features and the 109number of input and output pads of the filter. 110 111A filter with no input pads is called a "source", and a filter with no 112output pads is called a "sink". 113 114@anchor{Filtergraph syntax} 115@section Filtergraph syntax 116 117A filtergraph has a textual representation, which is 118recognized by the @option{-filter}/@option{-vf} and @option{-filter_complex} 119options in @command{ffmpeg} and @option{-vf} in @command{ffplay}, and by the 120@code{avfilter_graph_parse()}/@code{avfilter_graph_parse2()} functions defined in 121@file{libavfilter/avfilter.h}. 122 123A filterchain consists of a sequence of connected filters, each one 124connected to the previous one in the sequence. A filterchain is 125represented by a list of ","-separated filter descriptions. 126 127A filtergraph consists of a sequence of filterchains. A sequence of 128filterchains is represented by a list of ";"-separated filterchain 129descriptions. 130 131A filter is represented by a string of the form: 132[@var{in_link_1}]...[@var{in_link_N}]@var{filter_name}=@var{arguments}[@var{out_link_1}]...[@var{out_link_M}] 133 134@var{filter_name} is the name of the filter class of which the 135described filter is an instance of, and has to be the name of one of 136the filter classes registered in the program. 137The name of the filter class is optionally followed by a string 138"=@var{arguments}". 139 140@var{arguments} is a string which contains the parameters used to 141initialize the filter instance. It may have one of two forms: 142@itemize 143 144@item 145A ':'-separated list of @var{key=value} pairs. 146 147@item 148A ':'-separated list of @var{value}. In this case, the keys are assumed to be 149the option names in the order they are declared. E.g. the @code{fade} filter 150declares three options in this order -- @option{type}, @option{start_frame} and 151@option{nb_frames}. Then the parameter list @var{in:0:30} means that the value 152@var{in} is assigned to the option @option{type}, @var{0} to 153@option{start_frame} and @var{30} to @option{nb_frames}. 154 155@item 156A ':'-separated list of mixed direct @var{value} and long @var{key=value} 157pairs. The direct @var{value} must precede the @var{key=value} pairs, and 158follow the same constraints order of the previous point. The following 159@var{key=value} pairs can be set in any preferred order. 160 161@end itemize 162 163If the option value itself is a list of items (e.g. the @code{format} filter 164takes a list of pixel formats), the items in the list are usually separated by 165'|'. 166 167The list of arguments can be quoted using the character "'" as initial 168and ending mark, and the character '\' for escaping the characters 169within the quoted text; otherwise the argument string is considered 170terminated when the next special character (belonging to the set 171"[]=;,") is encountered. 172 173The name and arguments of the filter are optionally preceded and 174followed by a list of link labels. 175A link label allows one to name a link and associate it to a filter output 176or input pad. The preceding labels @var{in_link_1} 177... @var{in_link_N}, are associated to the filter input pads, 178the following labels @var{out_link_1} ... @var{out_link_M}, are 179associated to the output pads. 180 181When two link labels with the same name are found in the 182filtergraph, a link between the corresponding input and output pad is 183created. 184 185If an output pad is not labelled, it is linked by default to the first 186unlabelled input pad of the next filter in the filterchain. 187For example in the filterchain 188@example 189nullsrc, split[L1], [L2]overlay, nullsink 190@end example 191the split filter instance has two output pads, and the overlay filter 192instance two input pads. The first output pad of split is labelled 193"L1", the first input pad of overlay is labelled "L2", and the second 194output pad of split is linked to the second input pad of overlay, 195which are both unlabelled. 196 197In a complete filterchain all the unlabelled filter input and output 198pads must be connected. A filtergraph is considered valid if all the 199filter input and output pads of all the filterchains are connected. 200 201Libavfilter will automatically insert @ref{scale} filters where format 202conversion is required. It is possible to specify swscale flags 203for those automatically inserted scalers by prepending 204@code{sws_flags=@var{flags};} 205to the filtergraph description. 206 207Here is a BNF description of the filtergraph syntax: 208@example 209@var{NAME} ::= sequence of alphanumeric characters and '_' 210@var{LINKLABEL} ::= "[" @var{NAME} "]" 211@var{LINKLABELS} ::= @var{LINKLABEL} [@var{LINKLABELS}] 212@var{FILTER_ARGUMENTS} ::= sequence of chars (possibly quoted) 213@var{FILTER} ::= [@var{LINKLABELS}] @var{NAME} ["=" @var{FILTER_ARGUMENTS}] [@var{LINKLABELS}] 214@var{FILTERCHAIN} ::= @var{FILTER} [,@var{FILTERCHAIN}] 215@var{FILTERGRAPH} ::= [sws_flags=@var{flags};] @var{FILTERCHAIN} [;@var{FILTERGRAPH}] 216@end example 217 218@section Notes on filtergraph escaping 219 220Filtergraph description composition entails several levels of 221escaping. See @ref{quoting_and_escaping,,the "Quoting and escaping" 222section in the ffmpeg-utils(1) manual,ffmpeg-utils} for more 223information about the employed escaping procedure. 224 225A first level escaping affects the content of each filter option 226value, which may contain the special character @code{:} used to 227separate values, or one of the escaping characters @code{\'}. 228 229A second level escaping affects the whole filter description, which 230may contain the escaping characters @code{\'} or the special 231characters @code{[],;} used by the filtergraph description. 232 233Finally, when you specify a filtergraph on a shell commandline, you 234need to perform a third level escaping for the shell special 235characters contained within it. 236 237For example, consider the following string to be embedded in 238the @ref{drawtext} filter description @option{text} value: 239@example 240this is a 'string': may contain one, or more, special characters 241@end example 242 243This string contains the @code{'} special escaping character, and the 244@code{:} special character, so it needs to be escaped in this way: 245@example 246text=this is a \'string\'\: may contain one, or more, special characters 247@end example 248 249A second level of escaping is required when embedding the filter 250description in a filtergraph description, in order to escape all the 251filtergraph special characters. Thus the example above becomes: 252@example 253drawtext=text=this is a \\\'string\\\'\\: may contain one\, or more\, special characters 254@end example 255(note that in addition to the @code{\'} escaping special characters, 256also @code{,} needs to be escaped). 257 258Finally an additional level of escaping is needed when writing the 259filtergraph description in a shell command, which depends on the 260escaping rules of the adopted shell. For example, assuming that 261@code{\} is special and needs to be escaped with another @code{\}, the 262previous string will finally result in: 263@example 264-vf "drawtext=text=this is a \\\\\\'string\\\\\\'\\\\: may contain one\\, or more\\, special characters" 265@end example 266 267@chapter Timeline editing 268 269Some filters support a generic @option{enable} option. For the filters 270supporting timeline editing, this option can be set to an expression which is 271evaluated before sending a frame to the filter. If the evaluation is non-zero, 272the filter will be enabled, otherwise the frame will be sent unchanged to the 273next filter in the filtergraph. 274 275The expression accepts the following values: 276@table @samp 277@item t 278timestamp expressed in seconds, NAN if the input timestamp is unknown 279 280@item n 281sequential number of the input frame, starting from 0 282 283@item pos 284the position in the file of the input frame, NAN if unknown 285@end table 286 287Additionally, these filters support an @option{enable} command that can be used 288to re-define the expression. 289 290Like any other filtering option, the @option{enable} option follows the same 291rules. 292 293For example, to enable a blur filter (@ref{smartblur}) from 10 seconds to 3 294minutes, and a @ref{curves} filter starting at 3 seconds: 295@example 296smartblur = enable='between(t,10,3*60)', 297curves = enable='gte(t,3)' : preset=cross_process 298@end example 299 300@c man end FILTERGRAPH DESCRIPTION 301 302@chapter Audio Filters 303@c man begin AUDIO FILTERS 304 305When you configure your FFmpeg build, you can disable any of the 306existing filters using @code{--disable-filters}. 307The configure output will show the audio filters included in your 308build. 309 310Below is a description of the currently available audio filters. 311 312@section aconvert 313 314Convert the input audio format to the specified formats. 315 316@emph{This filter is deprecated. Use @ref{aformat} instead.} 317 318The filter accepts a string of the form: 319"@var{sample_format}:@var{channel_layout}". 320 321@var{sample_format} specifies the sample format, and can be a string or the 322corresponding numeric value defined in @file{libavutil/samplefmt.h}. Use 'p' 323suffix for a planar sample format. 324 325@var{channel_layout} specifies the channel layout, and can be a string 326or the corresponding number value defined in @file{libavutil/channel_layout.h}. 327 328The special parameter "auto", signifies that the filter will 329automatically select the output format depending on the output filter. 330 331@subsection Examples 332 333@itemize 334@item 335Convert input to float, planar, stereo: 336@example 337aconvert=fltp:stereo 338@end example 339 340@item 341Convert input to unsigned 8-bit, automatically select out channel layout: 342@example 343aconvert=u8:auto 344@end example 345@end itemize 346 347@section adelay 348 349Delay one or more audio channels. 350 351Samples in delayed channel are filled with silence. 352 353The filter accepts the following option: 354 355@table @option 356@item delays 357Set list of delays in milliseconds for each channel separated by '|'. 358At least one delay greater than 0 should be provided. 359Unused delays will be silently ignored. If number of given delays is 360smaller than number of channels all remaining channels will not be delayed. 361@end table 362 363@subsection Examples 364 365@itemize 366@item 367Delay first channel by 1.5 seconds, the third channel by 0.5 seconds and leave 368the second channel (and any other channels that may be present) unchanged. 369@example 370adelay=1500|0|500 371@end example 372@end itemize 373 374@section aecho 375 376Apply echoing to the input audio. 377 378Echoes are reflected sound and can occur naturally amongst mountains 379(and sometimes large buildings) when talking or shouting; digital echo 380effects emulate this behaviour and are often used to help fill out the 381sound of a single instrument or vocal. The time difference between the 382original signal and the reflection is the @code{delay}, and the 383loudness of the reflected signal is the @code{decay}. 384Multiple echoes can have different delays and decays. 385 386A description of the accepted parameters follows. 387 388@table @option 389@item in_gain 390Set input gain of reflected signal. Default is @code{0.6}. 391 392@item out_gain 393Set output gain of reflected signal. Default is @code{0.3}. 394 395@item delays 396Set list of time intervals in milliseconds between original signal and reflections 397separated by '|'. Allowed range for each @code{delay} is @code{(0 - 90000.0]}. 398Default is @code{1000}. 399 400@item decays 401Set list of loudnesses of reflected signals separated by '|'. 402Allowed range for each @code{decay} is @code{(0 - 1.0]}. 403Default is @code{0.5}. 404@end table 405 406@subsection Examples 407 408@itemize 409@item 410Make it sound as if there are twice as many instruments as are actually playing: 411@example 412aecho=0.8:0.88:60:0.4 413@end example 414 415@item 416If delay is very short, then it sound like a (metallic) robot playing music: 417@example 418aecho=0.8:0.88:6:0.4 419@end example 420 421@item 422A longer delay will sound like an open air concert in the mountains: 423@example 424aecho=0.8:0.9:1000:0.3 425@end example 426 427@item 428Same as above but with one more mountain: 429@example 430aecho=0.8:0.9:1000|1800:0.3|0.25 431@end example 432@end itemize 433 434@section aeval 435 436Modify an audio signal according to the specified expressions. 437 438This filter accepts one or more expressions (one for each channel), 439which are evaluated and used to modify a corresponding audio signal. 440 441It accepts the following parameters: 442 443@table @option 444@item exprs 445Set the '|'-separated expressions list for each separate channel. If 446the number of input channels is greater than the number of 447expressions, the last specified expression is used for the remaining 448output channels. 449 450@item channel_layout, c 451Set output channel layout. If not specified, the channel layout is 452specified by the number of expressions. If set to @samp{same}, it will 453use by default the same input channel layout. 454@end table 455 456Each expression in @var{exprs} can contain the following constants and functions: 457 458@table @option 459@item ch 460channel number of the current expression 461 462@item n 463number of the evaluated sample, starting from 0 464 465@item s 466sample rate 467 468@item t 469time of the evaluated sample expressed in seconds 470 471@item nb_in_channels 472@item nb_out_channels 473input and output number of channels 474 475@item val(CH) 476the value of input channel with number @var{CH} 477@end table 478 479Note: this filter is slow. For faster processing you should use a 480dedicated filter. 481 482@subsection Examples 483 484@itemize 485@item 486Half volume: 487@example 488aeval=val(ch)/2:c=same 489@end example 490 491@item 492Invert phase of the second channel: 493@example 494aeval=val(0)|-val(1) 495@end example 496@end itemize 497 498@section afade 499 500Apply fade-in/out effect to input audio. 501 502A description of the accepted parameters follows. 503 504@table @option 505@item type, t 506Specify the effect type, can be either @code{in} for fade-in, or 507@code{out} for a fade-out effect. Default is @code{in}. 508 509@item start_sample, ss 510Specify the number of the start sample for starting to apply the fade 511effect. Default is 0. 512 513@item nb_samples, ns 514Specify the number of samples for which the fade effect has to last. At 515the end of the fade-in effect the output audio will have the same 516volume as the input audio, at the end of the fade-out transition 517the output audio will be silence. Default is 44100. 518 519@item start_time, st 520Specify time for starting to apply the fade effect. Default is 0. 521The accepted syntax is: 522@example 523[-]HH[:MM[:SS[.m...]]] 524[-]S+[.m...] 525@end example 526See also the function @code{av_parse_time()}. 527If set this option is used instead of @var{start_sample} one. 528 529@item duration, d 530Specify the duration for which the fade effect has to last. Default is 0. 531The accepted syntax is: 532@example 533[-]HH[:MM[:SS[.m...]]] 534[-]S+[.m...] 535@end example 536See also the function @code{av_parse_time()}. 537At the end of the fade-in effect the output audio will have the same 538volume as the input audio, at the end of the fade-out transition 539the output audio will be silence. 540If set this option is used instead of @var{nb_samples} one. 541 542@item curve 543Set curve for fade transition. 544 545It accepts the following values: 546@table @option 547@item tri 548select triangular, linear slope (default) 549@item qsin 550select quarter of sine wave 551@item hsin 552select half of sine wave 553@item esin 554select exponential sine wave 555@item log 556select logarithmic 557@item par 558select inverted parabola 559@item qua 560select quadratic 561@item cub 562select cubic 563@item squ 564select square root 565@item cbr 566select cubic root 567@end table 568@end table 569 570@subsection Examples 571 572@itemize 573@item 574Fade in first 15 seconds of audio: 575@example 576afade=t=in:ss=0:d=15 577@end example 578 579@item 580Fade out last 25 seconds of a 900 seconds audio: 581@example 582afade=t=out:st=875:d=25 583@end example 584@end itemize 585 586@anchor{aformat} 587@section aformat 588 589Set output format constraints for the input audio. The framework will 590negotiate the most appropriate format to minimize conversions. 591 592It accepts the following parameters: 593@table @option 594 595@item sample_fmts 596A '|'-separated list of requested sample formats. 597 598@item sample_rates 599A '|'-separated list of requested sample rates. 600 601@item channel_layouts 602A '|'-separated list of requested channel layouts. 603 604See @ref{channel layout syntax,,the Channel Layout section in the ffmpeg-utils(1) manual,ffmpeg-utils} 605for the required syntax. 606@end table 607 608If a parameter is omitted, all values are allowed. 609 610Force the output to either unsigned 8-bit or signed 16-bit stereo 611@example 612aformat=sample_fmts=u8|s16:channel_layouts=stereo 613@end example 614 615@section allpass 616 617Apply a two-pole all-pass filter with central frequency (in Hz) 618@var{frequency}, and filter-width @var{width}. 619An all-pass filter changes the audio's frequency to phase relationship 620without changing its frequency to amplitude relationship. 621 622The filter accepts the following options: 623 624@table @option 625@item frequency, f 626Set frequency in Hz. 627 628@item width_type 629Set method to specify band-width of filter. 630@table @option 631@item h 632Hz 633@item q 634Q-Factor 635@item o 636octave 637@item s 638slope 639@end table 640 641@item width, w 642Specify the band-width of a filter in width_type units. 643@end table 644 645@section amerge 646 647Merge two or more audio streams into a single multi-channel stream. 648 649The filter accepts the following options: 650 651@table @option 652 653@item inputs 654Set the number of inputs. Default is 2. 655 656@end table 657 658If the channel layouts of the inputs are disjoint, and therefore compatible, 659the channel layout of the output will be set accordingly and the channels 660will be reordered as necessary. If the channel layouts of the inputs are not 661disjoint, the output will have all the channels of the first input then all 662the channels of the second input, in that order, and the channel layout of 663the output will be the default value corresponding to the total number of 664channels. 665 666For example, if the first input is in 2.1 (FL+FR+LF) and the second input 667is FC+BL+BR, then the output will be in 5.1, with the channels in the 668following order: a1, a2, b1, a3, b2, b3 (a1 is the first channel of the 669first input, b1 is the first channel of the second input). 670 671On the other hand, if both input are in stereo, the output channels will be 672in the default order: a1, a2, b1, b2, and the channel layout will be 673arbitrarily set to 4.0, which may or may not be the expected value. 674 675All inputs must have the same sample rate, and format. 676 677If inputs do not have the same duration, the output will stop with the 678shortest. 679 680@subsection Examples 681 682@itemize 683@item 684Merge two mono files into a stereo stream: 685@example 686amovie=left.wav [l] ; amovie=right.mp3 [r] ; [l] [r] amerge 687@end example 688 689@item 690Multiple merges assuming 1 video stream and 6 audio streams in @file{input.mkv}: 691@example 692ffmpeg -i input.mkv -filter_complex "[0:1][0:2][0:3][0:4][0:5][0:6] amerge=inputs=6" -c:a pcm_s16le output.mkv 693@end example 694@end itemize 695 696@section amix 697 698Mixes multiple audio inputs into a single output. 699 700Note that this filter only supports float samples (the @var{amerge} 701and @var{pan} audio filters support many formats). If the @var{amix} 702input has integer samples then @ref{aresample} will be automatically 703inserted to perform the conversion to float samples. 704 705For example 706@example 707ffmpeg -i INPUT1 -i INPUT2 -i INPUT3 -filter_complex amix=inputs=3:duration=first:dropout_transition=3 OUTPUT 708@end example 709will mix 3 input audio streams to a single output with the same duration as the 710first input and a dropout transition time of 3 seconds. 711 712It accepts the following parameters: 713@table @option 714 715@item inputs 716The number of inputs. If unspecified, it defaults to 2. 717 718@item duration 719How to determine the end-of-stream. 720@table @option 721 722@item longest 723The duration of the longest input. (default) 724 725@item shortest 726The duration of the shortest input. 727 728@item first 729The duration of the first input. 730 731@end table 732 733@item dropout_transition 734The transition time, in seconds, for volume renormalization when an input 735stream ends. The default value is 2 seconds. 736 737@end table 738 739@section anull 740 741Pass the audio source unchanged to the output. 742 743@section apad 744 745Pad the end of a audio stream with silence, this can be used together with 746-shortest to extend audio streams to the same length as the video stream. 747 748@section aphaser 749Add a phasing effect to the input audio. 750 751A phaser filter creates series of peaks and troughs in the frequency spectrum. 752The position of the peaks and troughs are modulated so that they vary over time, creating a sweeping effect. 753 754A description of the accepted parameters follows. 755 756@table @option 757@item in_gain 758Set input gain. Default is 0.4. 759 760@item out_gain 761Set output gain. Default is 0.74 762 763@item delay 764Set delay in milliseconds. Default is 3.0. 765 766@item decay 767Set decay. Default is 0.4. 768 769@item speed 770Set modulation speed in Hz. Default is 0.5. 771 772@item type 773Set modulation type. Default is triangular. 774 775It accepts the following values: 776@table @samp 777@item triangular, t 778@item sinusoidal, s 779@end table 780@end table 781 782@anchor{aresample} 783@section aresample 784 785Resample the input audio to the specified parameters, using the 786libswresample library. If none are specified then the filter will 787automatically convert between its input and output. 788 789This filter is also able to stretch/squeeze the audio data to make it match 790the timestamps or to inject silence / cut out audio to make it match the 791timestamps, do a combination of both or do neither. 792 793The filter accepts the syntax 794[@var{sample_rate}:]@var{resampler_options}, where @var{sample_rate} 795expresses a sample rate and @var{resampler_options} is a list of 796@var{key}=@var{value} pairs, separated by ":". See the 797ffmpeg-resampler manual for the complete list of supported options. 798 799@subsection Examples 800 801@itemize 802@item 803Resample the input audio to 44100Hz: 804@example 805aresample=44100 806@end example 807 808@item 809Stretch/squeeze samples to the given timestamps, with a maximum of 1000 810samples per second compensation: 811@example 812aresample=async=1000 813@end example 814@end itemize 815 816@section asetnsamples 817 818Set the number of samples per each output audio frame. 819 820The last output packet may contain a different number of samples, as 821the filter will flush all the remaining samples when the input audio 822signal its end. 823 824The filter accepts the following options: 825 826@table @option 827 828@item nb_out_samples, n 829Set the number of frames per each output audio frame. The number is 830intended as the number of samples @emph{per each channel}. 831Default value is 1024. 832 833@item pad, p 834If set to 1, the filter will pad the last audio frame with zeroes, so 835that the last frame will contain the same number of samples as the 836previous ones. Default value is 1. 837@end table 838 839For example, to set the number of per-frame samples to 1234 and 840disable padding for the last frame, use: 841@example 842asetnsamples=n=1234:p=0 843@end example 844 845@section asetrate 846 847Set the sample rate without altering the PCM data. 848This will result in a change of speed and pitch. 849 850The filter accepts the following options: 851 852@table @option 853@item sample_rate, r 854Set the output sample rate. Default is 44100 Hz. 855@end table 856 857@section ashowinfo 858 859Show a line containing various information for each input audio frame. 860The input audio is not modified. 861 862The shown line contains a sequence of key/value pairs of the form 863@var{key}:@var{value}. 864 865It accepts the following parameters: 866 867@table @option 868@item n 869The (sequential) number of the input frame, starting from 0. 870 871@item pts 872The presentation timestamp of the input frame, in time base units; the time base 873depends on the filter input pad, and is usually 1/@var{sample_rate}. 874 875@item pts_time 876The presentation timestamp of the input frame in seconds. 877 878@item pos 879position of the frame in the input stream, -1 if this information in 880unavailable and/or meaningless (for example in case of synthetic audio) 881 882@item fmt 883The sample format. 884 885@item chlayout 886The channel layout. 887 888@item rate 889The sample rate for the audio frame. 890 891@item nb_samples 892The number of samples (per channel) in the frame. 893 894@item checksum 895The Adler-32 checksum (printed in hexadecimal) of the audio data. For planar 896audio, the data is treated as if all the planes were concatenated. 897 898@item plane_checksums 899A list of Adler-32 checksums for each data plane. 900@end table 901 902@section astats 903 904Display time domain statistical information about the audio channels. 905Statistics are calculated and displayed for each audio channel and, 906where applicable, an overall figure is also given. 907 908It accepts the following option: 909@table @option 910@item length 911Short window length in seconds, used for peak and trough RMS measurement. 912Default is @code{0.05} (50 miliseconds). Allowed range is @code{[0.1 - 10]}. 913@end table 914 915A description of each shown parameter follows: 916 917@table @option 918@item DC offset 919Mean amplitude displacement from zero. 920 921@item Min level 922Minimal sample level. 923 924@item Max level 925Maximal sample level. 926 927@item Peak level dB 928@item RMS level dB 929Standard peak and RMS level measured in dBFS. 930 931@item RMS peak dB 932@item RMS trough dB 933Peak and trough values for RMS level measured over a short window. 934 935@item Crest factor 936Standard ratio of peak to RMS level (note: not in dB). 937 938@item Flat factor 939Flatness (i.e. consecutive samples with the same value) of the signal at its peak levels 940(i.e. either @var{Min level} or @var{Max level}). 941 942@item Peak count 943Number of occasions (not the number of samples) that the signal attained either 944@var{Min level} or @var{Max level}. 945@end table 946 947@section astreamsync 948 949Forward two audio streams and control the order the buffers are forwarded. 950 951The filter accepts the following options: 952 953@table @option 954@item expr, e 955Set the expression deciding which stream should be 956forwarded next: if the result is negative, the first stream is forwarded; if 957the result is positive or zero, the second stream is forwarded. It can use 958the following variables: 959 960@table @var 961@item b1 b2 962number of buffers forwarded so far on each stream 963@item s1 s2 964number of samples forwarded so far on each stream 965@item t1 t2 966current timestamp of each stream 967@end table 968 969The default value is @code{t1-t2}, which means to always forward the stream 970that has a smaller timestamp. 971@end table 972 973@subsection Examples 974 975Stress-test @code{amerge} by randomly sending buffers on the wrong 976input, while avoiding too much of a desynchronization: 977@example 978amovie=file.ogg [a] ; amovie=file.mp3 [b] ; 979[a] [b] astreamsync=(2*random(1))-1+tanh(5*(t1-t2)) [a2] [b2] ; 980[a2] [b2] amerge 981@end example 982 983@section asyncts 984 985Synchronize audio data with timestamps by squeezing/stretching it and/or 986dropping samples/adding silence when needed. 987 988This filter is not built by default, please use @ref{aresample} to do squeezing/stretching. 989 990It accepts the following parameters: 991@table @option 992 993@item compensate 994Enable stretching/squeezing the data to make it match the timestamps. Disabled 995by default. When disabled, time gaps are covered with silence. 996 997@item min_delta 998The minimum difference between timestamps and audio data (in seconds) to trigger 999adding/dropping samples. The default value is 0.1. If you get an imperfect 1000sync with this filter, try setting this parameter to 0. 1001 1002@item max_comp 1003The maximum compensation in samples per second. Only relevant with compensate=1. 1004The default value is 500. 1005 1006@item first_pts 1007Assume that the first PTS should be this value. The time base is 1 / sample 1008rate. This allows for padding/trimming at the start of the stream. By default, 1009no assumption is made about the first frame's expected PTS, so no padding or 1010trimming is done. For example, this could be set to 0 to pad the beginning with 1011silence if an audio stream starts after the video stream or to trim any samples 1012with a negative PTS due to encoder delay. 1013 1014@end table 1015 1016@section atempo 1017 1018Adjust audio tempo. 1019 1020The filter accepts exactly one parameter, the audio tempo. If not 1021specified then the filter will assume nominal 1.0 tempo. Tempo must 1022be in the [0.5, 2.0] range. 1023 1024@subsection Examples 1025 1026@itemize 1027@item 1028Slow down audio to 80% tempo: 1029@example 1030atempo=0.8 1031@end example 1032 1033@item 1034To speed up audio to 125% tempo: 1035@example 1036atempo=1.25 1037@end example 1038@end itemize 1039 1040@section atrim 1041 1042Trim the input so that the output contains one continuous subpart of the input. 1043 1044It accepts the following parameters: 1045@table @option 1046@item start 1047Timestamp (in seconds) of the start of the section to keep. I.e. the audio 1048sample with the timestamp @var{start} will be the first sample in the output. 1049 1050@item end 1051Specify time of the first audio sample that will be dropped, i.e. the 1052audio sample immediately preceding the one with the timestamp @var{end} will be 1053the last sample in the output. 1054 1055@item start_pts 1056Same as @var{start}, except this option sets the start timestamp in samples 1057instead of seconds. 1058 1059@item end_pts 1060Same as @var{end}, except this option sets the end timestamp in samples instead 1061of seconds. 1062 1063@item duration 1064The maximum duration of the output in seconds. 1065 1066@item start_sample 1067The number of the first sample that should be output. 1068 1069@item end_sample 1070The number of the first sample that should be dropped. 1071@end table 1072 1073@option{start}, @option{end}, @option{duration} are expressed as time 1074duration specifications, check the "Time duration" section in the 1075ffmpeg-utils manual. 1076 1077Note that the first two sets of the start/end options and the @option{duration} 1078option look at the frame timestamp, while the _sample options simply count the 1079samples that pass through the filter. So start/end_pts and start/end_sample will 1080give different results when the timestamps are wrong, inexact or do not start at 1081zero. Also note that this filter does not modify the timestamps. If you wish 1082to have the output timestamps start at zero, insert the asetpts filter after the 1083atrim filter. 1084 1085If multiple start or end options are set, this filter tries to be greedy and 1086keep all samples that match at least one of the specified constraints. To keep 1087only the part that matches all the constraints at once, chain multiple atrim 1088filters. 1089 1090The defaults are such that all the input is kept. So it is possible to set e.g. 1091just the end values to keep everything before the specified time. 1092 1093Examples: 1094@itemize 1095@item 1096Drop everything except the second minute of input: 1097@example 1098ffmpeg -i INPUT -af atrim=60:120 1099@end example 1100 1101@item 1102Keep only the first 1000 samples: 1103@example 1104ffmpeg -i INPUT -af atrim=end_sample=1000 1105@end example 1106 1107@end itemize 1108 1109@section bandpass 1110 1111Apply a two-pole Butterworth band-pass filter with central 1112frequency @var{frequency}, and (3dB-point) band-width width. 1113The @var{csg} option selects a constant skirt gain (peak gain = Q) 1114instead of the default: constant 0dB peak gain. 1115The filter roll off at 6dB per octave (20dB per decade). 1116 1117The filter accepts the following options: 1118 1119@table @option 1120@item frequency, f 1121Set the filter's central frequency. Default is @code{3000}. 1122 1123@item csg 1124Constant skirt gain if set to 1. Defaults to 0. 1125 1126@item width_type 1127Set method to specify band-width of filter. 1128@table @option 1129@item h 1130Hz 1131@item q 1132Q-Factor 1133@item o 1134octave 1135@item s 1136slope 1137@end table 1138 1139@item width, w 1140Specify the band-width of a filter in width_type units. 1141@end table 1142 1143@section bandreject 1144 1145Apply a two-pole Butterworth band-reject filter with central 1146frequency @var{frequency}, and (3dB-point) band-width @var{width}. 1147The filter roll off at 6dB per octave (20dB per decade). 1148 1149The filter accepts the following options: 1150 1151@table @option 1152@item frequency, f 1153Set the filter's central frequency. Default is @code{3000}. 1154 1155@item width_type 1156Set method to specify band-width of filter. 1157@table @option 1158@item h 1159Hz 1160@item q 1161Q-Factor 1162@item o 1163octave 1164@item s 1165slope 1166@end table 1167 1168@item width, w 1169Specify the band-width of a filter in width_type units. 1170@end table 1171 1172@section bass 1173 1174Boost or cut the bass (lower) frequencies of the audio using a two-pole 1175shelving filter with a response similar to that of a standard 1176hi-fi's tone-controls. This is also known as shelving equalisation (EQ). 1177 1178The filter accepts the following options: 1179 1180@table @option 1181@item gain, g 1182Give the gain at 0 Hz. Its useful range is about -20 1183(for a large cut) to +20 (for a large boost). 1184Beware of clipping when using a positive gain. 1185 1186@item frequency, f 1187Set the filter's central frequency and so can be used 1188to extend or reduce the frequency range to be boosted or cut. 1189The default value is @code{100} Hz. 1190 1191@item width_type 1192Set method to specify band-width of filter. 1193@table @option 1194@item h 1195Hz 1196@item q 1197Q-Factor 1198@item o 1199octave 1200@item s 1201slope 1202@end table 1203 1204@item width, w 1205Determine how steep is the filter's shelf transition. 1206@end table 1207 1208@section biquad 1209 1210Apply a biquad IIR filter with the given coefficients. 1211Where @var{b0}, @var{b1}, @var{b2} and @var{a0}, @var{a1}, @var{a2} 1212are the numerator and denominator coefficients respectively. 1213 1214@section bs2b 1215Bauer stereo to binaural transformation, which improves headphone listening of 1216stereo audio records. 1217 1218It accepts the following parameters: 1219@table @option 1220 1221@item profile 1222Pre-defined crossfeed level. 1223@table @option 1224 1225@item default 1226Default level (fcut=700, feed=50). 1227 1228@item cmoy 1229Chu Moy circuit (fcut=700, feed=60). 1230 1231@item jmeier 1232Jan Meier circuit (fcut=650, feed=95). 1233 1234@end table 1235 1236@item fcut 1237Cut frequency (in Hz). 1238 1239@item feed 1240Feed level (in Hz). 1241 1242@end table 1243 1244@section channelmap 1245 1246Remap input channels to new locations. 1247 1248It accepts the following parameters: 1249@table @option 1250@item channel_layout 1251The channel layout of the output stream. 1252 1253@item map 1254Map channels from input to output. The argument is a '|'-separated list of 1255mappings, each in the @code{@var{in_channel}-@var{out_channel}} or 1256@var{in_channel} form. @var{in_channel} can be either the name of the input 1257channel (e.g. FL for front left) or its index in the input channel layout. 1258@var{out_channel} is the name of the output channel or its index in the output 1259channel layout. If @var{out_channel} is not given then it is implicitly an 1260index, starting with zero and increasing by one for each mapping. 1261@end table 1262 1263If no mapping is present, the filter will implicitly map input channels to 1264output channels, preserving indices. 1265 1266For example, assuming a 5.1+downmix input MOV file, 1267@example 1268ffmpeg -i in.mov -filter 'channelmap=map=DL-FL|DR-FR' out.wav 1269@end example 1270will create an output WAV file tagged as stereo from the downmix channels of 1271the input. 1272 1273To fix a 5.1 WAV improperly encoded in AAC's native channel order 1274@example 1275ffmpeg -i in.wav -filter 'channelmap=1|2|0|5|3|4:channel_layout=5.1' out.wav 1276@end example 1277 1278@section channelsplit 1279 1280Split each channel from an input audio stream into a separate output stream. 1281 1282It accepts the following parameters: 1283@table @option 1284@item channel_layout 1285The channel layout of the input stream. The default is "stereo". 1286@end table 1287 1288For example, assuming a stereo input MP3 file, 1289@example 1290ffmpeg -i in.mp3 -filter_complex channelsplit out.mkv 1291@end example 1292will create an output Matroska file with two audio streams, one containing only 1293the left channel and the other the right channel. 1294 1295Split a 5.1 WAV file into per-channel files: 1296@example 1297ffmpeg -i in.wav -filter_complex 1298'channelsplit=channel_layout=5.1[FL][FR][FC][LFE][SL][SR]' 1299-map '[FL]' front_left.wav -map '[FR]' front_right.wav -map '[FC]' 1300front_center.wav -map '[LFE]' lfe.wav -map '[SL]' side_left.wav -map '[SR]' 1301side_right.wav 1302@end example 1303 1304@section compand 1305Compress or expand the audio's dynamic range. 1306 1307It accepts the following parameters: 1308 1309@table @option 1310 1311@item attacks 1312@item decays 1313A list of times in seconds for each channel over which the instantaneous level 1314of the input signal is averaged to determine its volume. @var{attacks} refers to 1315increase of volume and @var{decays} refers to decrease of volume. For most 1316situations, the attack time (response to the audio getting louder) should be 1317shorter than the decay time, because the human ear is more sensitive to sudden 1318loud audio than sudden soft audio. A typical value for attack is 0.3 seconds and 1319a typical value for decay is 0.8 seconds. 1320 1321@item points 1322A list of points for the transfer function, specified in dB relative to the 1323maximum possible signal amplitude. Each key points list must be defined using 1324the following syntax: @code{x0/y0|x1/y1|x2/y2|....} or 1325@code{x0/y0 x1/y1 x2/y2 ....} 1326 1327The input values must be in strictly increasing order but the transfer function 1328does not have to be monotonically rising. The point @code{0/0} is assumed but 1329may be overridden (by @code{0/out-dBn}). Typical values for the transfer 1330function are @code{-70/-70|-60/-20}. 1331 1332@item soft-knee 1333Set the curve radius in dB for all joints. It defaults to 0.01. 1334 1335@item gain 1336Set the additional gain in dB to be applied at all points on the transfer 1337function. This allows for easy adjustment of the overall gain. 1338It defaults to 0. 1339 1340@item volume 1341Set an initial volume, in dB, to be assumed for each channel when filtering 1342starts. This permits the user to supply a nominal level initially, so that, for 1343example, a very large gain is not applied to initial signal levels before the 1344companding has begun to operate. A typical value for audio which is initially 1345quiet is -90 dB. It defaults to 0. 1346 1347@item delay 1348Set a delay, in seconds. The input audio is analyzed immediately, but audio is 1349delayed before being fed to the volume adjuster. Specifying a delay 1350approximately equal to the attack/decay times allows the filter to effectively 1351operate in predictive rather than reactive mode. It defaults to 0. 1352 1353@end table 1354 1355@subsection Examples 1356 1357@itemize 1358@item 1359Make music with both quiet and loud passages suitable for listening to in a 1360noisy environment: 1361@example 1362compand=.3|.3:1|1:-90/-60|-60/-40|-40/-30|-20/-20:6:0:-90:0.2 1363@end example 1364 1365@item 1366A noise gate for when the noise is at a lower level than the signal: 1367@example 1368compand=.1|.1:.2|.2:-900/-900|-50.1/-900|-50/-50:.01:0:-90:.1 1369@end example 1370 1371@item 1372Here is another noise gate, this time for when the noise is at a higher level 1373than the signal (making it, in some ways, similar to squelch): 1374@example 1375compand=.1|.1:.1|.1:-45.1/-45.1|-45/-900|0/-900:.01:45:-90:.1 1376@end example 1377@end itemize 1378 1379@section earwax 1380 1381Make audio easier to listen to on headphones. 1382 1383This filter adds `cues' to 44.1kHz stereo (i.e. audio CD format) audio 1384so that when listened to on headphones the stereo image is moved from 1385inside your head (standard for headphones) to outside and in front of 1386the listener (standard for speakers). 1387 1388Ported from SoX. 1389 1390@section equalizer 1391 1392Apply a two-pole peaking equalisation (EQ) filter. With this 1393filter, the signal-level at and around a selected frequency can 1394be increased or decreased, whilst (unlike bandpass and bandreject 1395filters) that at all other frequencies is unchanged. 1396 1397In order to produce complex equalisation curves, this filter can 1398be given several times, each with a different central frequency. 1399 1400The filter accepts the following options: 1401 1402@table @option 1403@item frequency, f 1404Set the filter's central frequency in Hz. 1405 1406@item width_type 1407Set method to specify band-width of filter. 1408@table @option 1409@item h 1410Hz 1411@item q 1412Q-Factor 1413@item o 1414octave 1415@item s 1416slope 1417@end table 1418 1419@item width, w 1420Specify the band-width of a filter in width_type units. 1421 1422@item gain, g 1423Set the required gain or attenuation in dB. 1424Beware of clipping when using a positive gain. 1425@end table 1426 1427@subsection Examples 1428@itemize 1429@item 1430Attenuate 10 dB at 1000 Hz, with a bandwidth of 200 Hz: 1431@example 1432equalizer=f=1000:width_type=h:width=200:g=-10 1433@end example 1434 1435@item 1436Apply 2 dB gain at 1000 Hz with Q 1 and attenuate 5 dB at 100 Hz with Q 2: 1437@example 1438equalizer=f=1000:width_type=q:width=1:g=2,equalizer=f=100:width_type=q:width=2:g=-5 1439@end example 1440@end itemize 1441 1442@section flanger 1443Apply a flanging effect to the audio. 1444 1445The filter accepts the following options: 1446 1447@table @option 1448@item delay 1449Set base delay in milliseconds. Range from 0 to 30. Default value is 0. 1450 1451@item depth 1452Set added swep delay in milliseconds. Range from 0 to 10. Default value is 2. 1453 1454@item regen 1455Set percentage regeneneration (delayed signal feedback). Range from -95 to 95. 1456Default value is 0. 1457 1458@item width 1459Set percentage of delayed signal mixed with original. Range from 0 to 100. 1460Default valu is 71. 1461 1462@item speed 1463Set sweeps per second (Hz). Range from 0.1 to 10. Default value is 0.5. 1464 1465@item shape 1466Set swept wave shape, can be @var{triangular} or @var{sinusoidal}. 1467Default value is @var{sinusoidal}. 1468 1469@item phase 1470Set swept wave percentage-shift for multi channel. Range from 0 to 100. 1471Default value is 25. 1472 1473@item interp 1474Set delay-line interpolation, @var{linear} or @var{quadratic}. 1475Default is @var{linear}. 1476@end table 1477 1478@section highpass 1479 1480Apply a high-pass filter with 3dB point frequency. 1481The filter can be either single-pole, or double-pole (the default). 1482The filter roll off at 6dB per pole per octave (20dB per pole per decade). 1483 1484The filter accepts the following options: 1485 1486@table @option 1487@item frequency, f 1488Set frequency in Hz. Default is 3000. 1489 1490@item poles, p 1491Set number of poles. Default is 2. 1492 1493@item width_type 1494Set method to specify band-width of filter. 1495@table @option 1496@item h 1497Hz 1498@item q 1499Q-Factor 1500@item o 1501octave 1502@item s 1503slope 1504@end table 1505 1506@item width, w 1507Specify the band-width of a filter in width_type units. 1508Applies only to double-pole filter. 1509The default is 0.707q and gives a Butterworth response. 1510@end table 1511 1512@section join 1513 1514Join multiple input streams into one multi-channel stream. 1515 1516It accepts the following parameters: 1517@table @option 1518 1519@item inputs 1520The number of input streams. It defaults to 2. 1521 1522@item channel_layout 1523The desired output channel layout. It defaults to stereo. 1524 1525@item map 1526Map channels from inputs to output. The argument is a '|'-separated list of 1527mappings, each in the @code{@var{input_idx}.@var{in_channel}-@var{out_channel}} 1528form. @var{input_idx} is the 0-based index of the input stream. @var{in_channel} 1529can be either the name of the input channel (e.g. FL for front left) or its 1530index in the specified input stream. @var{out_channel} is the name of the output 1531channel. 1532@end table 1533 1534The filter will attempt to guess the mappings when they are not specified 1535explicitly. It does so by first trying to find an unused matching input channel 1536and if that fails it picks the first unused input channel. 1537 1538Join 3 inputs (with properly set channel layouts): 1539@example 1540ffmpeg -i INPUT1 -i INPUT2 -i INPUT3 -filter_complex join=inputs=3 OUTPUT 1541@end example 1542 1543Build a 5.1 output from 6 single-channel streams: 1544@example 1545ffmpeg -i fl -i fr -i fc -i sl -i sr -i lfe -filter_complex 1546'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' 1547out 1548@end example 1549 1550@section ladspa 1551 1552Load a LADSPA (Linux Audio Developer's Simple Plugin API) plugin. 1553 1554To enable compilation of this filter you need to configure FFmpeg with 1555@code{--enable-ladspa}. 1556 1557@table @option 1558@item file, f 1559Specifies the name of LADSPA plugin library to load. If the environment 1560variable @env{LADSPA_PATH} is defined, the LADSPA plugin is searched in 1561each one of the directories specified by the colon separated list in 1562@env{LADSPA_PATH}, otherwise in the standard LADSPA paths, which are in 1563this order: @file{HOME/.ladspa/lib/}, @file{/usr/local/lib/ladspa/}, 1564@file{/usr/lib/ladspa/}. 1565 1566@item plugin, p 1567Specifies the plugin within the library. Some libraries contain only 1568one plugin, but others contain many of them. If this is not set filter 1569will list all available plugins within the specified library. 1570 1571@item controls, c 1572Set the '|' separated list of controls which are zero or more floating point 1573values that determine the behavior of the loaded plugin (for example delay, 1574threshold or gain). 1575Controls need to be defined using the following syntax: 1576c0=@var{value0}|c1=@var{value1}|c2=@var{value2}|..., where 1577@var{valuei} is the value set on the @var{i}-th control. 1578If @option{controls} is set to @code{help}, all available controls and 1579their valid ranges are printed. 1580 1581@item sample_rate, s 1582Specify the sample rate, default to 44100. Only used if plugin have 1583zero inputs. 1584 1585@item nb_samples, n 1586Set the number of samples per channel per each output frame, default 1587is 1024. Only used if plugin have zero inputs. 1588 1589@item duration, d 1590Set the minimum duration of the sourced audio. See the function 1591@code{av_parse_time()} for the accepted format, also check the "Time duration" 1592section in the ffmpeg-utils manual. 1593Note that the resulting duration may be greater than the specified duration, 1594as the generated audio is always cut at the end of a complete frame. 1595If not specified, or the expressed duration is negative, the audio is 1596supposed to be generated forever. 1597Only used if plugin have zero inputs. 1598 1599@end table 1600 1601@subsection Examples 1602 1603@itemize 1604@item 1605List all available plugins within amp (LADSPA example plugin) library: 1606@example 1607ladspa=file=amp 1608@end example 1609 1610@item 1611List all available controls and their valid ranges for @code{vcf_notch} 1612plugin from @code{VCF} library: 1613@example 1614ladspa=f=vcf:p=vcf_notch:c=help 1615@end example 1616 1617@item 1618Simulate low quality audio equipment using @code{Computer Music Toolkit} (CMT) 1619plugin library: 1620@example 1621ladspa=file=cmt:plugin=lofi:controls=c0=22|c1=12|c2=12 1622@end example 1623 1624@item 1625Add reverberation to the audio using TAP-plugins 1626(Tom's Audio Processing plugins): 1627@example 1628ladspa=file=tap_reverb:tap_reverb 1629@end example 1630 1631@item 1632Generate white noise, with 0.2 amplitude: 1633@example 1634ladspa=file=cmt:noise_source_white:c=c0=.2 1635@end example 1636 1637@item 1638Generate 20 bpm clicks using plugin @code{C* Click - Metronome} from the 1639@code{C* Audio Plugin Suite} (CAPS) library: 1640@example 1641ladspa=file=caps:Click:c=c1=20' 1642@end example 1643 1644@item 1645Apply @code{C* Eq10X2 - Stereo 10-band equaliser} effect: 1646@example 1647ladspa=caps:Eq10X2:c=c0=-48|c9=-24|c3=12|c4=2 1648@end example 1649@end itemize 1650 1651@subsection Commands 1652 1653This filter supports the following commands: 1654@table @option 1655@item cN 1656Modify the @var{N}-th control value. 1657 1658If the specified value is not valid, it is ignored and prior one is kept. 1659@end table 1660 1661@section lowpass 1662 1663Apply a low-pass filter with 3dB point frequency. 1664The filter can be either single-pole or double-pole (the default). 1665The filter roll off at 6dB per pole per octave (20dB per pole per decade). 1666 1667The filter accepts the following options: 1668 1669@table @option 1670@item frequency, f 1671Set frequency in Hz. Default is 500. 1672 1673@item poles, p 1674Set number of poles. Default is 2. 1675 1676@item width_type 1677Set method to specify band-width of filter. 1678@table @option 1679@item h 1680Hz 1681@item q 1682Q-Factor 1683@item o 1684octave 1685@item s 1686slope 1687@end table 1688 1689@item width, w 1690Specify the band-width of a filter in width_type units. 1691Applies only to double-pole filter. 1692The default is 0.707q and gives a Butterworth response. 1693@end table 1694 1695@section pan 1696 1697Mix channels with specific gain levels. The filter accepts the output 1698channel layout followed by a set of channels definitions. 1699 1700This filter is also designed to remap efficiently the channels of an audio 1701stream. 1702 1703The filter accepts parameters of the form: 1704"@var{l}:@var{outdef}:@var{outdef}:..." 1705 1706@table @option 1707@item l 1708output channel layout or number of channels 1709 1710@item outdef 1711output channel specification, of the form: 1712"@var{out_name}=[@var{gain}*]@var{in_name}[+[@var{gain}*]@var{in_name}...]" 1713 1714@item out_name 1715output channel to define, either a channel name (FL, FR, etc.) or a channel 1716number (c0, c1, etc.) 1717 1718@item gain 1719multiplicative coefficient for the channel, 1 leaving the volume unchanged 1720 1721@item in_name 1722input channel to use, see out_name for details; it is not possible to mix 1723named and numbered input channels 1724@end table 1725 1726If the `=' in a channel specification is replaced by `<', then the gains for 1727that specification will be renormalized so that the total is 1, thus 1728avoiding clipping noise. 1729 1730@subsection Mixing examples 1731 1732For example, if you want to down-mix from stereo to mono, but with a bigger 1733factor for the left channel: 1734@example 1735pan=1:c0=0.9*c0+0.1*c1 1736@end example 1737 1738A customized down-mix to stereo that works automatically for 3-, 4-, 5- and 17397-channels surround: 1740@example 1741pan=stereo: FL < FL + 0.5*FC + 0.6*BL + 0.6*SL : FR < FR + 0.5*FC + 0.6*BR + 0.6*SR 1742@end example 1743 1744Note that @command{ffmpeg} integrates a default down-mix (and up-mix) system 1745that should be preferred (see "-ac" option) unless you have very specific 1746needs. 1747 1748@subsection Remapping examples 1749 1750The channel remapping will be effective if, and only if: 1751 1752@itemize 1753@item gain coefficients are zeroes or ones, 1754@item only one input per channel output, 1755@end itemize 1756 1757If all these conditions are satisfied, the filter will notify the user ("Pure 1758channel mapping detected"), and use an optimized and lossless method to do the 1759remapping. 1760 1761For example, if you have a 5.1 source and want a stereo audio stream by 1762dropping the extra channels: 1763@example 1764pan="stereo: c0=FL : c1=FR" 1765@end example 1766 1767Given the same source, you can also switch front left and front right channels 1768and keep the input channel layout: 1769@example 1770pan="5.1: c0=c1 : c1=c0 : c2=c2 : c3=c3 : c4=c4 : c5=c5" 1771@end example 1772 1773If the input is a stereo audio stream, you can mute the front left channel (and 1774still keep the stereo channel layout) with: 1775@example 1776pan="stereo:c1=c1" 1777@end example 1778 1779Still with a stereo audio stream input, you can copy the right channel in both 1780front left and right: 1781@example 1782pan="stereo: c0=FR : c1=FR" 1783@end example 1784 1785@section replaygain 1786 1787ReplayGain scanner filter. This filter takes an audio stream as an input and 1788outputs it unchanged. 1789At end of filtering it displays @code{track_gain} and @code{track_peak}. 1790 1791@section resample 1792 1793Convert the audio sample format, sample rate and channel layout. It is 1794not meant to be used directly. 1795 1796@section silencedetect 1797 1798Detect silence in an audio stream. 1799 1800This filter logs a message when it detects that the input audio volume is less 1801or equal to a noise tolerance value for a duration greater or equal to the 1802minimum detected noise duration. 1803 1804The printed times and duration are expressed in seconds. 1805 1806The filter accepts the following options: 1807 1808@table @option 1809@item duration, d 1810Set silence duration until notification (default is 2 seconds). 1811 1812@item noise, n 1813Set noise tolerance. Can be specified in dB (in case "dB" is appended to the 1814specified value) or amplitude ratio. Default is -60dB, or 0.001. 1815@end table 1816 1817@subsection Examples 1818 1819@itemize 1820@item 1821Detect 5 seconds of silence with -50dB noise tolerance: 1822@example 1823silencedetect=n=-50dB:d=5 1824@end example 1825 1826@item 1827Complete example with @command{ffmpeg} to detect silence with 0.0001 noise 1828tolerance in @file{silence.mp3}: 1829@example 1830ffmpeg -i silence.mp3 -af silencedetect=noise=0.0001 -f null - 1831@end example 1832@end itemize 1833 1834@section treble 1835 1836Boost or cut treble (upper) frequencies of the audio using a two-pole 1837shelving filter with a response similar to that of a standard 1838hi-fi's tone-controls. This is also known as shelving equalisation (EQ). 1839 1840The filter accepts the following options: 1841 1842@table @option 1843@item gain, g 1844Give the gain at whichever is the lower of ~22 kHz and the 1845Nyquist frequency. Its useful range is about -20 (for a large cut) 1846to +20 (for a large boost). Beware of clipping when using a positive gain. 1847 1848@item frequency, f 1849Set the filter's central frequency and so can be used 1850to extend or reduce the frequency range to be boosted or cut. 1851The default value is @code{3000} Hz. 1852 1853@item width_type 1854Set method to specify band-width of filter. 1855@table @option 1856@item h 1857Hz 1858@item q 1859Q-Factor 1860@item o 1861octave 1862@item s 1863slope 1864@end table 1865 1866@item width, w 1867Determine how steep is the filter's shelf transition. 1868@end table 1869 1870@section volume 1871 1872Adjust the input audio volume. 1873 1874It accepts the following parameters: 1875@table @option 1876 1877@item volume 1878Set audio volume expression. 1879 1880Output values are clipped to the maximum value. 1881 1882The output audio volume is given by the relation: 1883@example 1884@var{output_volume} = @var{volume} * @var{input_volume} 1885@end example 1886 1887The default value for @var{volume} is "1.0". 1888 1889@item precision 1890This parameter represents the mathematical precision. 1891 1892It determines which input sample formats will be allowed, which affects the 1893precision of the volume scaling. 1894 1895@table @option 1896@item fixed 18978-bit fixed-point; this limits input sample format to U8, S16, and S32. 1898@item float 189932-bit floating-point; this limits input sample format to FLT. (default) 1900@item double 190164-bit floating-point; this limits input sample format to DBL. 1902@end table 1903 1904@item replaygain 1905Choose the behaviour on encountering ReplayGain side data in input frames. 1906 1907@table @option 1908@item drop 1909Remove ReplayGain side data, ignoring its contents (the default). 1910 1911@item ignore 1912Ignore ReplayGain side data, but leave it in the frame. 1913 1914@item track 1915Prefer the track gain, if present. 1916 1917@item album 1918Prefer the album gain, if present. 1919@end table 1920 1921@item replaygain_preamp 1922Pre-amplification gain in dB to apply to the selected replaygain gain. 1923 1924Default value for @var{replaygain_preamp} is 0.0. 1925 1926@item eval 1927Set when the volume expression is evaluated. 1928 1929It accepts the following values: 1930@table @samp 1931@item once 1932only evaluate expression once during the filter initialization, or 1933when the @samp{volume} command is sent 1934 1935@item frame 1936evaluate expression for each incoming frame 1937@end table 1938 1939Default value is @samp{once}. 1940@end table 1941 1942The volume expression can contain the following parameters. 1943 1944@table @option 1945@item n 1946frame number (starting at zero) 1947@item nb_channels 1948number of channels 1949@item nb_consumed_samples 1950number of samples consumed by the filter 1951@item nb_samples 1952number of samples in the current frame 1953@item pos 1954original frame position in the file 1955@item pts 1956frame PTS 1957@item sample_rate 1958sample rate 1959@item startpts 1960PTS at start of stream 1961@item startt 1962time at start of stream 1963@item t 1964frame time 1965@item tb 1966timestamp timebase 1967@item volume 1968last set volume value 1969@end table 1970 1971Note that when @option{eval} is set to @samp{once} only the 1972@var{sample_rate} and @var{tb} variables are available, all other 1973variables will evaluate to NAN. 1974 1975@subsection Commands 1976 1977This filter supports the following commands: 1978@table @option 1979@item volume 1980Modify the volume expression. 1981The command accepts the same syntax of the corresponding option. 1982 1983If the specified expression is not valid, it is kept at its current 1984value. 1985@item replaygain_noclip 1986Prevent clipping by limiting the gain applied. 1987 1988Default value for @var{replaygain_noclip} is 1. 1989 1990@end table 1991 1992@subsection Examples 1993 1994@itemize 1995@item 1996Halve the input audio volume: 1997@example 1998volume=volume=0.5 1999volume=volume=1/2 2000volume=volume=-6.0206dB 2001@end example 2002 2003In all the above example the named key for @option{volume} can be 2004omitted, for example like in: 2005@example 2006volume=0.5 2007@end example 2008 2009@item 2010Increase input audio power by 6 decibels using fixed-point precision: 2011@example 2012volume=volume=6dB:precision=fixed 2013@end example 2014 2015@item 2016Fade volume after time 10 with an annihilation period of 5 seconds: 2017@example 2018volume='if(lt(t,10),1,max(1-(t-10)/5,0))':eval=frame 2019@end example 2020@end itemize 2021 2022@section volumedetect 2023 2024Detect the volume of the input video. 2025 2026The filter has no parameters. The input is not modified. Statistics about 2027the volume will be printed in the log when the input stream end is reached. 2028 2029In particular it will show the mean volume (root mean square), maximum 2030volume (on a per-sample basis), and the beginning of a histogram of the 2031registered volume values (from the maximum value to a cumulated 1/1000 of 2032the samples). 2033 2034All volumes are in decibels relative to the maximum PCM value. 2035 2036@subsection Examples 2037 2038Here is an excerpt of the output: 2039@example 2040[Parsed_volumedetect_0 @ 0xa23120] mean_volume: -27 dB 2041[Parsed_volumedetect_0 @ 0xa23120] max_volume: -4 dB 2042[Parsed_volumedetect_0 @ 0xa23120] histogram_4db: 6 2043[Parsed_volumedetect_0 @ 0xa23120] histogram_5db: 62 2044[Parsed_volumedetect_0 @ 0xa23120] histogram_6db: 286 2045[Parsed_volumedetect_0 @ 0xa23120] histogram_7db: 1042 2046[Parsed_volumedetect_0 @ 0xa23120] histogram_8db: 2551 2047[Parsed_volumedetect_0 @ 0xa23120] histogram_9db: 4609 2048[Parsed_volumedetect_0 @ 0xa23120] histogram_10db: 8409 2049@end example 2050 2051It means that: 2052@itemize 2053@item 2054The mean square energy is approximately -27 dB, or 10^-2.7. 2055@item 2056The largest sample is at -4 dB, or more precisely between -4 dB and -5 dB. 2057@item 2058There are 6 samples at -4 dB, 62 at -5 dB, 286 at -6 dB, etc. 2059@end itemize 2060 2061In other words, raising the volume by +4 dB does not cause any clipping, 2062raising it by +5 dB causes clipping for 6 samples, etc. 2063 2064@c man end AUDIO FILTERS 2065 2066@chapter Audio Sources 2067@c man begin AUDIO SOURCES 2068 2069Below is a description of the currently available audio sources. 2070 2071@section abuffer 2072 2073Buffer audio frames, and make them available to the filter chain. 2074 2075This source is mainly intended for a programmatic use, in particular 2076through the interface defined in @file{libavfilter/asrc_abuffer.h}. 2077 2078It accepts the following parameters: 2079@table @option 2080 2081@item time_base 2082The timebase which will be used for timestamps of submitted frames. It must be 2083either a floating-point number or in @var{numerator}/@var{denominator} form. 2084 2085@item sample_rate 2086The sample rate of the incoming audio buffers. 2087 2088@item sample_fmt 2089The sample format of the incoming audio buffers. 2090Either a sample format name or its corresponging integer representation from 2091the enum AVSampleFormat in @file{libavutil/samplefmt.h} 2092 2093@item channel_layout 2094The channel layout of the incoming audio buffers. 2095Either a channel layout name from channel_layout_map in 2096@file{libavutil/channel_layout.c} or its corresponding integer representation 2097from the AV_CH_LAYOUT_* macros in @file{libavutil/channel_layout.h} 2098 2099@item channels 2100The number of channels of the incoming audio buffers. 2101If both @var{channels} and @var{channel_layout} are specified, then they 2102must be consistent. 2103 2104@end table 2105 2106@subsection Examples 2107 2108@example 2109abuffer=sample_rate=44100:sample_fmt=s16p:channel_layout=stereo 2110@end example 2111 2112will instruct the source to accept planar 16bit signed stereo at 44100Hz. 2113Since the sample format with name "s16p" corresponds to the number 21146 and the "stereo" channel layout corresponds to the value 0x3, this is 2115equivalent to: 2116@example 2117abuffer=sample_rate=44100:sample_fmt=6:channel_layout=0x3 2118@end example 2119 2120@section aevalsrc 2121 2122Generate an audio signal specified by an expression. 2123 2124This source accepts in input one or more expressions (one for each 2125channel), which are evaluated and used to generate a corresponding 2126audio signal. 2127 2128This source accepts the following options: 2129 2130@table @option 2131@item exprs 2132Set the '|'-separated expressions list for each separate channel. In case the 2133@option{channel_layout} option is not specified, the selected channel layout 2134depends on the number of provided expressions. Otherwise the last 2135specified expression is applied to the remaining output channels. 2136 2137@item channel_layout, c 2138Set the channel layout. The number of channels in the specified layout 2139must be equal to the number of specified expressions. 2140 2141@item duration, d 2142Set the minimum duration of the sourced audio. See the function 2143@code{av_parse_time()} for the accepted format. 2144Note that the resulting duration may be greater than the specified 2145duration, as the generated audio is always cut at the end of a 2146complete frame. 2147 2148If not specified, or the expressed duration is negative, the audio is 2149supposed to be generated forever. 2150 2151@item nb_samples, n 2152Set the number of samples per channel per each output frame, 2153default to 1024. 2154 2155@item sample_rate, s 2156Specify the sample rate, default to 44100. 2157@end table 2158 2159Each expression in @var{exprs} can contain the following constants: 2160 2161@table @option 2162@item n 2163number of the evaluated sample, starting from 0 2164 2165@item t 2166time of the evaluated sample expressed in seconds, starting from 0 2167 2168@item s 2169sample rate 2170 2171@end table 2172 2173@subsection Examples 2174 2175@itemize 2176@item 2177Generate silence: 2178@example 2179aevalsrc=0 2180@end example 2181 2182@item 2183Generate a sin signal with frequency of 440 Hz, set sample rate to 21848000 Hz: 2185@example 2186aevalsrc="sin(440*2*PI*t):s=8000" 2187@end example 2188 2189@item 2190Generate a two channels signal, specify the channel layout (Front 2191Center + Back Center) explicitly: 2192@example 2193aevalsrc="sin(420*2*PI*t)|cos(430*2*PI*t):c=FC|BC" 2194@end example 2195 2196@item 2197Generate white noise: 2198@example 2199aevalsrc="-2+random(0)" 2200@end example 2201 2202@item 2203Generate an amplitude modulated signal: 2204@example 2205aevalsrc="sin(10*2*PI*t)*sin(880*2*PI*t)" 2206@end example 2207 2208@item 2209Generate 2.5 Hz binaural beats on a 360 Hz carrier: 2210@example 2211aevalsrc="0.1*sin(2*PI*(360-2.5/2)*t) | 0.1*sin(2*PI*(360+2.5/2)*t)" 2212@end example 2213 2214@end itemize 2215 2216@section anullsrc 2217 2218The null audio source, return unprocessed audio frames. It is mainly useful 2219as a template and to be employed in analysis / debugging tools, or as 2220the source for filters which ignore the input data (for example the sox 2221synth filter). 2222 2223This source accepts the following options: 2224 2225@table @option 2226 2227@item channel_layout, cl 2228 2229Specifies the channel layout, and can be either an integer or a string 2230representing a channel layout. The default value of @var{channel_layout} 2231is "stereo". 2232 2233Check the channel_layout_map definition in 2234@file{libavutil/channel_layout.c} for the mapping between strings and 2235channel layout values. 2236 2237@item sample_rate, r 2238Specifies the sample rate, and defaults to 44100. 2239 2240@item nb_samples, n 2241Set the number of samples per requested frames. 2242 2243@end table 2244 2245@subsection Examples 2246 2247@itemize 2248@item 2249Set the sample rate to 48000 Hz and the channel layout to AV_CH_LAYOUT_MONO. 2250@example 2251anullsrc=r=48000:cl=4 2252@end example 2253 2254@item 2255Do the same operation with a more obvious syntax: 2256@example 2257anullsrc=r=48000:cl=mono 2258@end example 2259@end itemize 2260 2261All the parameters need to be explicitly defined. 2262 2263@section flite 2264 2265Synthesize a voice utterance using the libflite library. 2266 2267To enable compilation of this filter you need to configure FFmpeg with 2268@code{--enable-libflite}. 2269 2270Note that the flite library is not thread-safe. 2271 2272The filter accepts the following options: 2273 2274@table @option 2275 2276@item list_voices 2277If set to 1, list the names of the available voices and exit 2278immediately. Default value is 0. 2279 2280@item nb_samples, n 2281Set the maximum number of samples per frame. Default value is 512. 2282 2283@item textfile 2284Set the filename containing the text to speak. 2285 2286@item text 2287Set the text to speak. 2288 2289@item voice, v 2290Set the voice to use for the speech synthesis. Default value is 2291@code{kal}. See also the @var{list_voices} option. 2292@end table 2293 2294@subsection Examples 2295 2296@itemize 2297@item 2298Read from file @file{speech.txt}, and synthetize the text using the 2299standard flite voice: 2300@example 2301flite=textfile=speech.txt 2302@end example 2303 2304@item 2305Read the specified text selecting the @code{slt} voice: 2306@example 2307flite=text='So fare thee well, poor devil of a Sub-Sub, whose commentator I am':voice=slt 2308@end example 2309 2310@item 2311Input text to ffmpeg: 2312@example 2313ffmpeg -f lavfi -i flite=text='So fare thee well, poor devil of a Sub-Sub, whose commentator I am':voice=slt 2314@end example 2315 2316@item 2317Make @file{ffplay} speak the specified text, using @code{flite} and 2318the @code{lavfi} device: 2319@example 2320ffplay -f lavfi flite=text='No more be grieved for which that thou hast done.' 2321@end example 2322@end itemize 2323 2324For more information about libflite, check: 2325@url{http://www.speech.cs.cmu.edu/flite/} 2326 2327@section sine 2328 2329Generate an audio signal made of a sine wave with amplitude 1/8. 2330 2331The audio signal is bit-exact. 2332 2333The filter accepts the following options: 2334 2335@table @option 2336 2337@item frequency, f 2338Set the carrier frequency. Default is 440 Hz. 2339 2340@item beep_factor, b 2341Enable a periodic beep every second with frequency @var{beep_factor} times 2342the carrier frequency. Default is 0, meaning the beep is disabled. 2343 2344@item sample_rate, r 2345Specify the sample rate, default is 44100. 2346 2347@item duration, d 2348Specify the duration of the generated audio stream. 2349 2350@item samples_per_frame 2351Set the number of samples per output frame, default is 1024. 2352@end table 2353 2354@subsection Examples 2355 2356@itemize 2357 2358@item 2359Generate a simple 440 Hz sine wave: 2360@example 2361sine 2362@end example 2363 2364@item 2365Generate a 220 Hz sine wave with a 880 Hz beep each second, for 5 seconds: 2366@example 2367sine=220:4:d=5 2368sine=f=220:b=4:d=5 2369sine=frequency=220:beep_factor=4:duration=5 2370@end example 2371 2372@end itemize 2373 2374@c man end AUDIO SOURCES 2375 2376@chapter Audio Sinks 2377@c man begin AUDIO SINKS 2378 2379Below is a description of the currently available audio sinks. 2380 2381@section abuffersink 2382 2383Buffer audio frames, and make them available to the end of filter chain. 2384 2385This sink is mainly intended for programmatic use, in particular 2386through the interface defined in @file{libavfilter/buffersink.h} 2387or the options system. 2388 2389It accepts a pointer to an AVABufferSinkContext structure, which 2390defines the incoming buffers' formats, to be passed as the opaque 2391parameter to @code{avfilter_init_filter} for initialization. 2392@section anullsink 2393 2394Null audio sink; do absolutely nothing with the input audio. It is 2395mainly useful as a template and for use in analysis / debugging 2396tools. 2397 2398@c man end AUDIO SINKS 2399 2400@chapter Video Filters 2401@c man begin VIDEO FILTERS 2402 2403When you configure your FFmpeg build, you can disable any of the 2404existing filters using @code{--disable-filters}. 2405The configure output will show the video filters included in your 2406build. 2407 2408Below is a description of the currently available video filters. 2409 2410@section alphaextract 2411 2412Extract the alpha component from the input as a grayscale video. This 2413is especially useful with the @var{alphamerge} filter. 2414 2415@section alphamerge 2416 2417Add or replace the alpha component of the primary input with the 2418grayscale value of a second input. This is intended for use with 2419@var{alphaextract} to allow the transmission or storage of frame 2420sequences that have alpha in a format that doesn't support an alpha 2421channel. 2422 2423For example, to reconstruct full frames from a normal YUV-encoded video 2424and a separate video created with @var{alphaextract}, you might use: 2425@example 2426movie=in_alpha.mkv [alpha]; [in][alpha] alphamerge [out] 2427@end example 2428 2429Since this filter is designed for reconstruction, it operates on frame 2430sequences without considering timestamps, and terminates when either 2431input reaches end of stream. This will cause problems if your encoding 2432pipeline drops frames. If you're trying to apply an image as an 2433overlay to a video stream, consider the @var{overlay} filter instead. 2434 2435@section ass 2436 2437Same as the @ref{subtitles} filter, except that it doesn't require libavcodec 2438and libavformat to work. On the other hand, it is limited to ASS (Advanced 2439Substation Alpha) subtitles files. 2440 2441@section bbox 2442 2443Compute the bounding box for the non-black pixels in the input frame 2444luminance plane. 2445 2446This filter computes the bounding box containing all the pixels with a 2447luminance value greater than the minimum allowed value. 2448The parameters describing the bounding box are printed on the filter 2449log. 2450 2451The filter accepts the following option: 2452 2453@table @option 2454@item min_val 2455Set the minimal luminance value. Default is @code{16}. 2456@end table 2457 2458@section blackdetect 2459 2460Detect video intervals that are (almost) completely black. Can be 2461useful to detect chapter transitions, commercials, or invalid 2462recordings. Output lines contains the time for the start, end and 2463duration of the detected black interval expressed in seconds. 2464 2465In order to display the output lines, you need to set the loglevel at 2466least to the AV_LOG_INFO value. 2467 2468The filter accepts the following options: 2469 2470@table @option 2471@item black_min_duration, d 2472Set the minimum detected black duration expressed in seconds. It must 2473be a non-negative floating point number. 2474 2475Default value is 2.0. 2476 2477@item picture_black_ratio_th, pic_th 2478Set the threshold for considering a picture "black". 2479Express the minimum value for the ratio: 2480@example 2481@var{nb_black_pixels} / @var{nb_pixels} 2482@end example 2483 2484for which a picture is considered black. 2485Default value is 0.98. 2486 2487@item pixel_black_th, pix_th 2488Set the threshold for considering a pixel "black". 2489 2490The threshold expresses the maximum pixel luminance value for which a 2491pixel is considered "black". The provided value is scaled according to 2492the following equation: 2493@example 2494@var{absolute_threshold} = @var{luminance_minimum_value} + @var{pixel_black_th} * @var{luminance_range_size} 2495@end example 2496 2497@var{luminance_range_size} and @var{luminance_minimum_value} depend on 2498the input video format, the range is [0-255] for YUV full-range 2499formats and [16-235] for YUV non full-range formats. 2500 2501Default value is 0.10. 2502@end table 2503 2504The following example sets the maximum pixel threshold to the minimum 2505value, and detects only black intervals of 2 or more seconds: 2506@example 2507blackdetect=d=2:pix_th=0.00 2508@end example 2509 2510@section blackframe 2511 2512Detect frames that are (almost) completely black. Can be useful to 2513detect chapter transitions or commercials. Output lines consist of 2514the frame number of the detected frame, the percentage of blackness, 2515the position in the file if known or -1 and the timestamp in seconds. 2516 2517In order to display the output lines, you need to set the loglevel at 2518least to the AV_LOG_INFO value. 2519 2520It accepts the following parameters: 2521 2522@table @option 2523 2524@item amount 2525The percentage of the pixels that have to be below the threshold; it defaults to 2526@code{98}. 2527 2528@item threshold, thresh 2529The threshold below which a pixel value is considered black; it defaults to 2530@code{32}. 2531 2532@end table 2533 2534@section blend 2535 2536Blend two video frames into each other. 2537 2538It takes two input streams and outputs one stream, the first input is the 2539"top" layer and second input is "bottom" layer. 2540Output terminates when shortest input terminates. 2541 2542A description of the accepted options follows. 2543 2544@table @option 2545@item c0_mode 2546@item c1_mode 2547@item c2_mode 2548@item c3_mode 2549@item all_mode 2550Set blend mode for specific pixel component or all pixel components in case 2551of @var{all_mode}. Default value is @code{normal}. 2552 2553Available values for component modes are: 2554@table @samp 2555@item addition 2556@item and 2557@item average 2558@item burn 2559@item darken 2560@item difference 2561@item divide 2562@item dodge 2563@item exclusion 2564@item hardlight 2565@item lighten 2566@item multiply 2567@item negation 2568@item normal 2569@item or 2570@item overlay 2571@item phoenix 2572@item pinlight 2573@item reflect 2574@item screen 2575@item softlight 2576@item subtract 2577@item vividlight 2578@item xor 2579@end table 2580 2581@item c0_opacity 2582@item c1_opacity 2583@item c2_opacity 2584@item c3_opacity 2585@item all_opacity 2586Set blend opacity for specific pixel component or all pixel components in case 2587of @var{all_opacity}. Only used in combination with pixel component blend modes. 2588 2589@item c0_expr 2590@item c1_expr 2591@item c2_expr 2592@item c3_expr 2593@item all_expr 2594Set blend expression for specific pixel component or all pixel components in case 2595of @var{all_expr}. Note that related mode options will be ignored if those are set. 2596 2597The expressions can use the following variables: 2598 2599@table @option 2600@item N 2601The sequential number of the filtered frame, starting from @code{0}. 2602 2603@item X 2604@item Y 2605the coordinates of the current sample 2606 2607@item W 2608@item H 2609the width and height of currently filtered plane 2610 2611@item SW 2612@item SH 2613Width and height scale depending on the currently filtered plane. It is the 2614ratio between the corresponding luma plane number of pixels and the current 2615plane ones. E.g. for YUV4:2:0 the values are @code{1,1} for the luma plane, and 2616@code{0.5,0.5} for chroma planes. 2617 2618@item T 2619Time of the current frame, expressed in seconds. 2620 2621@item TOP, A 2622Value of pixel component at current location for first video frame (top layer). 2623 2624@item BOTTOM, B 2625Value of pixel component at current location for second video frame (bottom layer). 2626@end table 2627 2628@item shortest 2629Force termination when the shortest input terminates. Default is @code{0}. 2630@item repeatlast 2631Continue applying the last bottom frame after the end of the stream. A value of 2632@code{0} disable the filter after the last frame of the bottom layer is reached. 2633Default is @code{1}. 2634@end table 2635 2636@subsection Examples 2637 2638@itemize 2639@item 2640Apply transition from bottom layer to top layer in first 10 seconds: 2641@example 2642blend=all_expr='A*(if(gte(T,10),1,T/10))+B*(1-(if(gte(T,10),1,T/10)))' 2643@end example 2644 2645@item 2646Apply 1x1 checkerboard effect: 2647@example 2648blend=all_expr='if(eq(mod(X,2),mod(Y,2)),A,B)' 2649@end example 2650 2651@item 2652Apply uncover left effect: 2653@example 2654blend=all_expr='if(gte(N*SW+X,W),A,B)' 2655@end example 2656 2657@item 2658Apply uncover down effect: 2659@example 2660blend=all_expr='if(gte(Y-N*SH,0),A,B)' 2661@end example 2662 2663@item 2664Apply uncover up-left effect: 2665@example 2666blend=all_expr='if(gte(T*SH*40+Y,H)*gte((T*40*SW+X)*W/H,W),A,B)' 2667@end example 2668@end itemize 2669 2670@section boxblur 2671 2672Apply a boxblur algorithm to the input video. 2673 2674It accepts the following parameters: 2675 2676@table @option 2677 2678@item luma_radius, lr 2679@item luma_power, lp 2680@item chroma_radius, cr 2681@item chroma_power, cp 2682@item alpha_radius, ar 2683@item alpha_power, ap 2684 2685@end table 2686 2687A description of the accepted options follows. 2688 2689@table @option 2690@item luma_radius, lr 2691@item chroma_radius, cr 2692@item alpha_radius, ar 2693Set an expression for the box radius in pixels used for blurring the 2694corresponding input plane. 2695 2696The radius value must be a non-negative number, and must not be 2697greater than the value of the expression @code{min(w,h)/2} for the 2698luma and alpha planes, and of @code{min(cw,ch)/2} for the chroma 2699planes. 2700 2701Default value for @option{luma_radius} is "2". If not specified, 2702@option{chroma_radius} and @option{alpha_radius} default to the 2703corresponding value set for @option{luma_radius}. 2704 2705The expressions can contain the following constants: 2706@table @option 2707@item w 2708@item h 2709The input width and height in pixels. 2710 2711@item cw 2712@item ch 2713The input chroma image width and height in pixels. 2714 2715@item hsub 2716@item vsub 2717The horizontal and vertical chroma subsample values. For example, for the 2718pixel format "yuv422p", @var{hsub} is 2 and @var{vsub} is 1. 2719@end table 2720 2721@item luma_power, lp 2722@item chroma_power, cp 2723@item alpha_power, ap 2724Specify how many times the boxblur filter is applied to the 2725corresponding plane. 2726 2727Default value for @option{luma_power} is 2. If not specified, 2728@option{chroma_power} and @option{alpha_power} default to the 2729corresponding value set for @option{luma_power}. 2730 2731A value of 0 will disable the effect. 2732@end table 2733 2734@subsection Examples 2735 2736@itemize 2737@item 2738Apply a boxblur filter with the luma, chroma, and alpha radii 2739set to 2: 2740@example 2741boxblur=luma_radius=2:luma_power=1 2742boxblur=2:1 2743@end example 2744 2745@item 2746Set the luma radius to 2, and alpha and chroma radius to 0: 2747@example 2748boxblur=2:1:cr=0:ar=0 2749@end example 2750 2751@item 2752Set the luma and chroma radii to a fraction of the video dimension: 2753@example 2754boxblur=luma_radius=min(h\,w)/10:luma_power=1:chroma_radius=min(cw\,ch)/10:chroma_power=1 2755@end example 2756@end itemize 2757 2758@section colorbalance 2759Modify intensity of primary colors (red, green and blue) of input frames. 2760 2761The filter allows an input frame to be adjusted in the shadows, midtones or highlights 2762regions for the red-cyan, green-magenta or blue-yellow balance. 2763 2764A positive adjustment value shifts the balance towards the primary color, a negative 2765value towards the complementary color. 2766 2767The filter accepts the following options: 2768 2769@table @option 2770@item rs 2771@item gs 2772@item bs 2773Adjust red, green and blue shadows (darkest pixels). 2774 2775@item rm 2776@item gm 2777@item bm 2778Adjust red, green and blue midtones (medium pixels). 2779 2780@item rh 2781@item gh 2782@item bh 2783Adjust red, green and blue highlights (brightest pixels). 2784 2785Allowed ranges for options are @code{[-1.0, 1.0]}. Defaults are @code{0}. 2786@end table 2787 2788@subsection Examples 2789 2790@itemize 2791@item 2792Add red color cast to shadows: 2793@example 2794colorbalance=rs=.3 2795@end example 2796@end itemize 2797 2798@section colorchannelmixer 2799 2800Adjust video input frames by re-mixing color channels. 2801 2802This filter modifies a color channel by adding the values associated to 2803the other channels of the same pixels. For example if the value to 2804modify is red, the output value will be: 2805@example 2806@var{red}=@var{red}*@var{rr} + @var{blue}*@var{rb} + @var{green}*@var{rg} + @var{alpha}*@var{ra} 2807@end example 2808 2809The filter accepts the following options: 2810 2811@table @option 2812@item rr 2813@item rg 2814@item rb 2815@item ra 2816Adjust contribution of input red, green, blue and alpha channels for output red channel. 2817Default is @code{1} for @var{rr}, and @code{0} for @var{rg}, @var{rb} and @var{ra}. 2818 2819@item gr 2820@item gg 2821@item gb 2822@item ga 2823Adjust contribution of input red, green, blue and alpha channels for output green channel. 2824Default is @code{1} for @var{gg}, and @code{0} for @var{gr}, @var{gb} and @var{ga}. 2825 2826@item br 2827@item bg 2828@item bb 2829@item ba 2830Adjust contribution of input red, green, blue and alpha channels for output blue channel. 2831Default is @code{1} for @var{bb}, and @code{0} for @var{br}, @var{bg} and @var{ba}. 2832 2833@item ar 2834@item ag 2835@item ab 2836@item aa 2837Adjust contribution of input red, green, blue and alpha channels for output alpha channel. 2838Default is @code{1} for @var{aa}, and @code{0} for @var{ar}, @var{ag} and @var{ab}. 2839 2840Allowed ranges for options are @code{[-2.0, 2.0]}. 2841@end table 2842 2843@subsection Examples 2844 2845@itemize 2846@item 2847Convert source to grayscale: 2848@example 2849colorchannelmixer=.3:.4:.3:0:.3:.4:.3:0:.3:.4:.3 2850@end example 2851@item 2852Simulate sepia tones: 2853@example 2854colorchannelmixer=.393:.769:.189:0:.349:.686:.168:0:.272:.534:.131 2855@end example 2856@end itemize 2857 2858@section colormatrix 2859 2860Convert color matrix. 2861 2862The filter accepts the following options: 2863 2864@table @option 2865@item src 2866@item dst 2867Specify the source and destination color matrix. Both values must be 2868specified. 2869 2870The accepted values are: 2871@table @samp 2872@item bt709 2873BT.709 2874 2875@item bt601 2876BT.601 2877 2878@item smpte240m 2879SMPTE-240M 2880 2881@item fcc 2882FCC 2883@end table 2884@end table 2885 2886For example to convert from BT.601 to SMPTE-240M, use the command: 2887@example 2888colormatrix=bt601:smpte240m 2889@end example 2890 2891@section copy 2892 2893Copy the input source unchanged to the output. This is mainly useful for 2894testing purposes. 2895 2896@section crop 2897 2898Crop the input video to given dimensions. 2899 2900It accepts the following parameters: 2901 2902@table @option 2903@item w, out_w 2904The width of the output video. It defaults to @code{iw}. 2905This expression is evaluated only once during the filter 2906configuration. 2907 2908@item h, out_h 2909The height of the output video. It defaults to @code{ih}. 2910This expression is evaluated only once during the filter 2911configuration. 2912 2913@item x 2914The horizontal position, in the input video, of the left edge of the output 2915video. It defaults to @code{(in_w-out_w)/2}. 2916This expression is evaluated per-frame. 2917 2918@item y 2919The vertical position, in the input video, of the top edge of the output video. 2920It defaults to @code{(in_h-out_h)/2}. 2921This expression is evaluated per-frame. 2922 2923@item keep_aspect 2924If set to 1 will force the output display aspect ratio 2925to be the same of the input, by changing the output sample aspect 2926ratio. It defaults to 0. 2927@end table 2928 2929The @var{out_w}, @var{out_h}, @var{x}, @var{y} parameters are 2930expressions containing the following constants: 2931 2932@table @option 2933@item x 2934@item y 2935The computed values for @var{x} and @var{y}. They are evaluated for 2936each new frame. 2937 2938@item in_w 2939@item in_h 2940The input width and height. 2941 2942@item iw 2943@item ih 2944These are the same as @var{in_w} and @var{in_h}. 2945 2946@item out_w 2947@item out_h 2948The output (cropped) width and height. 2949 2950@item ow 2951@item oh 2952These are the same as @var{out_w} and @var{out_h}. 2953 2954@item a 2955same as @var{iw} / @var{ih} 2956 2957@item sar 2958input sample aspect ratio 2959 2960@item dar 2961input display aspect ratio, it is the same as (@var{iw} / @var{ih}) * @var{sar} 2962 2963@item hsub 2964@item vsub 2965horizontal and vertical chroma subsample values. For example for the 2966pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1. 2967 2968@item n 2969The number of the input frame, starting from 0. 2970 2971@item pos 2972the position in the file of the input frame, NAN if unknown 2973 2974@item t 2975The timestamp expressed in seconds. It's NAN if the input timestamp is unknown. 2976 2977@end table 2978 2979The expression for @var{out_w} may depend on the value of @var{out_h}, 2980and the expression for @var{out_h} may depend on @var{out_w}, but they 2981cannot depend on @var{x} and @var{y}, as @var{x} and @var{y} are 2982evaluated after @var{out_w} and @var{out_h}. 2983 2984The @var{x} and @var{y} parameters specify the expressions for the 2985position of the top-left corner of the output (non-cropped) area. They 2986are evaluated for each frame. If the evaluated value is not valid, it 2987is approximated to the nearest valid value. 2988 2989The expression for @var{x} may depend on @var{y}, and the expression 2990for @var{y} may depend on @var{x}. 2991 2992@subsection Examples 2993 2994@itemize 2995@item 2996Crop area with size 100x100 at position (12,34). 2997@example 2998crop=100:100:12:34 2999@end example 3000 3001Using named options, the example above becomes: 3002@example 3003crop=w=100:h=100:x=12:y=34 3004@end example 3005 3006@item 3007Crop the central input area with size 100x100: 3008@example 3009crop=100:100 3010@end example 3011 3012@item 3013Crop the central input area with size 2/3 of the input video: 3014@example 3015crop=2/3*in_w:2/3*in_h 3016@end example 3017 3018@item 3019Crop the input video central square: 3020@example 3021crop=out_w=in_h 3022crop=in_h 3023@end example 3024 3025@item 3026Delimit the rectangle with the top-left corner placed at position 3027100:100 and the right-bottom corner corresponding to the right-bottom 3028corner of the input image. 3029@example 3030crop=in_w-100:in_h-100:100:100 3031@end example 3032 3033@item 3034Crop 10 pixels from the left and right borders, and 20 pixels from 3035the top and bottom borders 3036@example 3037crop=in_w-2*10:in_h-2*20 3038@end example 3039 3040@item 3041Keep only the bottom right quarter of the input image: 3042@example 3043crop=in_w/2:in_h/2:in_w/2:in_h/2 3044@end example 3045 3046@item 3047Crop height for getting Greek harmony: 3048@example 3049crop=in_w:1/PHI*in_w 3050@end example 3051 3052@item 3053Appply trembling effect: 3054@example 3055crop=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) 3056@end example 3057 3058@item 3059Apply erratic camera effect depending on timestamp: 3060@example 3061crop=in_w/2:in_h/2:(in_w-out_w)/2+((in_w-out_w)/2)*sin(t*10):(in_h-out_h)/2 +((in_h-out_h)/2)*sin(t*13)" 3062@end example 3063 3064@item 3065Set x depending on the value of y: 3066@example 3067crop=in_w/2:in_h/2:y:10+10*sin(n/10) 3068@end example 3069@end itemize 3070 3071@section cropdetect 3072 3073Auto-detect the crop size. 3074 3075It calculates the necessary cropping parameters and prints the 3076recommended parameters via the logging system. The detected dimensions 3077correspond to the non-black area of the input video. 3078 3079It accepts the following parameters: 3080 3081@table @option 3082 3083@item limit 3084Set higher black value threshold, which can be optionally specified 3085from nothing (0) to everything (255). An intensity value greater 3086to the set value is considered non-black. It defaults to 24. 3087 3088@item round 3089The value which the width/height should be divisible by. It defaults to 309016. The offset is automatically adjusted to center the video. Use 2 to 3091get only even dimensions (needed for 4:2:2 video). 16 is best when 3092encoding to most video codecs. 3093 3094@item reset_count, reset 3095Set the counter that determines after how many frames cropdetect will 3096reset the previously detected largest video area and start over to 3097detect the current optimal crop area. Default value is 0. 3098 3099This can be useful when channel logos distort the video area. 0 3100indicates 'never reset', and returns the largest area encountered during 3101playback. 3102@end table 3103 3104@anchor{curves} 3105@section curves 3106 3107Apply color adjustments using curves. 3108 3109This filter is similar to the Adobe Photoshop and GIMP curves tools. Each 3110component (red, green and blue) has its values defined by @var{N} key points 3111tied from each other using a smooth curve. The x-axis represents the pixel 3112values from the input frame, and the y-axis the new pixel values to be set for 3113the output frame. 3114 3115By default, a component curve is defined by the two points @var{(0;0)} and 3116@var{(1;1)}. This creates a straight line where each original pixel value is 3117"adjusted" to its own value, which means no change to the image. 3118 3119The filter allows you to redefine these two points and add some more. A new 3120curve (using a natural cubic spline interpolation) will be define to pass 3121smoothly through all these new coordinates. The new defined points needs to be 3122strictly increasing over the x-axis, and their @var{x} and @var{y} values must 3123be in the @var{[0;1]} interval. If the computed curves happened to go outside 3124the vector spaces, the values will be clipped accordingly. 3125 3126If there is no key point defined in @code{x=0}, the filter will automatically 3127insert a @var{(0;0)} point. In the same way, if there is no key point defined 3128in @code{x=1}, the filter will automatically insert a @var{(1;1)} point. 3129 3130The filter accepts the following options: 3131 3132@table @option 3133@item preset 3134Select one of the available color presets. This option can be used in addition 3135to the @option{r}, @option{g}, @option{b} parameters; in this case, the later 3136options takes priority on the preset values. 3137Available presets are: 3138@table @samp 3139@item none 3140@item color_negative 3141@item cross_process 3142@item darker 3143@item increase_contrast 3144@item lighter 3145@item linear_contrast 3146@item medium_contrast 3147@item negative 3148@item strong_contrast 3149@item vintage 3150@end table 3151Default is @code{none}. 3152@item master, m 3153Set the master key points. These points will define a second pass mapping. It 3154is sometimes called a "luminance" or "value" mapping. It can be used with 3155@option{r}, @option{g}, @option{b} or @option{all} since it acts like a 3156post-processing LUT. 3157@item red, r 3158Set the key points for the red component. 3159@item green, g 3160Set the key points for the green component. 3161@item blue, b 3162Set the key points for the blue component. 3163@item all 3164Set the key points for all components (not including master). 3165Can be used in addition to the other key points component 3166options. In this case, the unset component(s) will fallback on this 3167@option{all} setting. 3168@item psfile 3169Specify a Photoshop curves file (@code{.asv}) to import the settings from. 3170@end table 3171 3172To avoid some filtergraph syntax conflicts, each key points list need to be 3173defined using the following syntax: @code{x0/y0 x1/y1 x2/y2 ...}. 3174 3175@subsection Examples 3176 3177@itemize 3178@item 3179Increase slightly the middle level of blue: 3180@example 3181curves=blue='0.5/0.58' 3182@end example 3183 3184@item 3185Vintage effect: 3186@example 3187curves=r='0/0.11 .42/.51 1/0.95':g='0.50/0.48':b='0/0.22 .49/.44 1/0.8' 3188@end example 3189Here we obtain the following coordinates for each components: 3190@table @var 3191@item red 3192@code{(0;0.11) (0.42;0.51) (1;0.95)} 3193@item green 3194@code{(0;0) (0.50;0.48) (1;1)} 3195@item blue 3196@code{(0;0.22) (0.49;0.44) (1;0.80)} 3197@end table 3198 3199@item 3200The previous example can also be achieved with the associated built-in preset: 3201@example 3202curves=preset=vintage 3203@end example 3204 3205@item 3206Or simply: 3207@example 3208curves=vintage 3209@end example 3210 3211@item 3212Use a Photoshop preset and redefine the points of the green component: 3213@example 3214curves=psfile='MyCurvesPresets/purple.asv':green='0.45/0.53' 3215@end example 3216@end itemize 3217 3218@section dctdnoiz 3219 3220Denoise frames using 2D DCT (frequency domain filtering). 3221 3222This filter is not designed for real time and can be extremely slow. 3223 3224The filter accepts the following options: 3225 3226@table @option 3227@item sigma, s 3228Set the noise sigma constant. 3229 3230This @var{sigma} defines a hard threshold of @code{3 * sigma}; every DCT 3231coefficient (absolute value) below this threshold with be dropped. 3232 3233If you need a more advanced filtering, see @option{expr}. 3234 3235Default is @code{0}. 3236 3237@item overlap 3238Set number overlapping pixels for each block. Each block is of size 3239@code{16x16}. Since the filter can be slow, you may want to reduce this value, 3240at the cost of a less effective filter and the risk of various artefacts. 3241 3242If the overlapping value doesn't allow to process the whole input width or 3243height, a warning will be displayed and according borders won't be denoised. 3244 3245Default value is @code{15}. 3246 3247@item expr, e 3248Set the coefficient factor expression. 3249 3250For each coefficient of a DCT block, this expression will be evaluated as a 3251multiplier value for the coefficient. 3252 3253If this is option is set, the @option{sigma} option will be ignored. 3254 3255The absolute value of the coefficient can be accessed through the @var{c} 3256variable. 3257@end table 3258 3259@subsection Examples 3260 3261Apply a denoise with a @option{sigma} of @code{4.5}: 3262@example 3263dctdnoiz=4.5 3264@end example 3265 3266The same operation can be achieved using the expression system: 3267@example 3268dctdnoiz=e='gte(c, 4.5*3)' 3269@end example 3270 3271@anchor{decimate} 3272@section decimate 3273 3274Drop duplicated frames at regular intervals. 3275 3276The filter accepts the following options: 3277 3278@table @option 3279@item cycle 3280Set the number of frames from which one will be dropped. Setting this to 3281@var{N} means one frame in every batch of @var{N} frames will be dropped. 3282Default is @code{5}. 3283 3284@item dupthresh 3285Set the threshold for duplicate detection. If the difference metric for a frame 3286is less than or equal to this value, then it is declared as duplicate. Default 3287is @code{1.1} 3288 3289@item scthresh 3290Set scene change threshold. Default is @code{15}. 3291 3292@item blockx 3293@item blocky 3294Set the size of the x and y-axis blocks used during metric calculations. 3295Larger blocks give better noise suppression, but also give worse detection of 3296small movements. Must be a power of two. Default is @code{32}. 3297 3298@item ppsrc 3299Mark main input as a pre-processed input and activate clean source input 3300stream. This allows the input to be pre-processed with various filters to help 3301the metrics calculation while keeping the frame selection lossless. When set to 3302@code{1}, the first stream is for the pre-processed input, and the second 3303stream is the clean source from where the kept frames are chosen. Default is 3304@code{0}. 3305 3306@item chroma 3307Set whether or not chroma is considered in the metric calculations. Default is 3308@code{1}. 3309@end table 3310 3311@section dejudder 3312 3313Remove judder produced by partially interlaced telecined content. 3314 3315Judder can be introduced, for instance, by @ref{pullup} filter. If the original 3316source was partially telecined content then the output of @code{pullup,dejudder} 3317will have a variable frame rate. May change the recorded frame rate of the 3318container. Aside from that change, this filter will not affect constant frame 3319rate video. 3320 3321The option available in this filter is: 3322@table @option 3323 3324@item cycle 3325Specify the length of the window over which the judder repeats. 3326 3327Accepts any integer greater than 1. Useful values are: 3328@table @samp 3329 3330@item 4 3331If the original was telecined from 24 to 30 fps (Film to NTSC). 3332 3333@item 5 3334If the original was telecined from 25 to 30 fps (PAL to NTSC). 3335 3336@item 20 3337If a mixture of the two. 3338@end table 3339 3340The default is @samp{4}. 3341@end table 3342 3343@section delogo 3344 3345Suppress a TV station logo by a simple interpolation of the surrounding 3346pixels. Just set a rectangle covering the logo and watch it disappear 3347(and sometimes something even uglier appear - your mileage may vary). 3348 3349It accepts the following parameters: 3350@table @option 3351 3352@item x 3353@item y 3354Specify the top left corner coordinates of the logo. They must be 3355specified. 3356 3357@item w 3358@item h 3359Specify the width and height of the logo to clear. They must be 3360specified. 3361 3362@item band, t 3363Specify the thickness of the fuzzy edge of the rectangle (added to 3364@var{w} and @var{h}). The default value is 4. 3365 3366@item show 3367When set to 1, a green rectangle is drawn on the screen to simplify 3368finding the right @var{x}, @var{y}, @var{w}, and @var{h} parameters. 3369The default value is 0. 3370 3371The rectangle is drawn on the outermost pixels which will be (partly) 3372replaced with interpolated values. The values of the next pixels 3373immediately outside this rectangle in each direction will be used to 3374compute the interpolated pixel values inside the rectangle. 3375 3376@end table 3377 3378@subsection Examples 3379 3380@itemize 3381@item 3382Set a rectangle covering the area with top left corner coordinates 0,0 3383and size 100x77, and a band of size 10: 3384@example 3385delogo=x=0:y=0:w=100:h=77:band=10 3386@end example 3387 3388@end itemize 3389 3390@section deshake 3391 3392Attempt to fix small changes in horizontal and/or vertical shift. This 3393filter helps remove camera shake from hand-holding a camera, bumping a 3394tripod, moving on a vehicle, etc. 3395 3396The filter accepts the following options: 3397 3398@table @option 3399 3400@item x 3401@item y 3402@item w 3403@item h 3404Specify a rectangular area where to limit the search for motion 3405vectors. 3406If desired the search for motion vectors can be limited to a 3407rectangular area of the frame defined by its top left corner, width 3408and height. These parameters have the same meaning as the drawbox 3409filter which can be used to visualise the position of the bounding 3410box. 3411 3412This is useful when simultaneous movement of subjects within the frame 3413might be confused for camera motion by the motion vector search. 3414 3415If any or all of @var{x}, @var{y}, @var{w} and @var{h} are set to -1 3416then the full frame is used. This allows later options to be set 3417without specifying the bounding box for the motion vector search. 3418 3419Default - search the whole frame. 3420 3421@item rx 3422@item ry 3423Specify the maximum extent of movement in x and y directions in the 3424range 0-64 pixels. Default 16. 3425 3426@item edge 3427Specify how to generate pixels to fill blanks at the edge of the 3428frame. Available values are: 3429@table @samp 3430@item blank, 0 3431Fill zeroes at blank locations 3432@item original, 1 3433Original image at blank locations 3434@item clamp, 2 3435Extruded edge value at blank locations 3436@item mirror, 3 3437Mirrored edge at blank locations 3438@end table 3439Default value is @samp{mirror}. 3440 3441@item blocksize 3442Specify the blocksize to use for motion search. Range 4-128 pixels, 3443default 8. 3444 3445@item contrast 3446Specify the contrast threshold for blocks. Only blocks with more than 3447the specified contrast (difference between darkest and lightest 3448pixels) will be considered. Range 1-255, default 125. 3449 3450@item search 3451Specify the search strategy. Available values are: 3452@table @samp 3453@item exhaustive, 0 3454Set exhaustive search 3455@item less, 1 3456Set less exhaustive search. 3457@end table 3458Default value is @samp{exhaustive}. 3459 3460@item filename 3461If set then a detailed log of the motion search is written to the 3462specified file. 3463 3464@item opencl 3465If set to 1, specify using OpenCL capabilities, only available if 3466FFmpeg was configured with @code{--enable-opencl}. Default value is 0. 3467 3468@end table 3469 3470@section drawbox 3471 3472Draw a colored box on the input image. 3473 3474It accepts the following parameters: 3475 3476@table @option 3477@item x 3478@item y 3479The expressions which specify the top left corner coordinates of the box. It defaults to 0. 3480 3481@item width, w 3482@item height, h 3483The expressions which specify the width and height of the box; if 0 they are interpreted as 3484the input width and height. It defaults to 0. 3485 3486@item color, c 3487Specify the color of the box to write. For the general syntax of this option, 3488check the "Color" section in the ffmpeg-utils manual. If the special 3489value @code{invert} is used, the box edge color is the same as the 3490video with inverted luma. 3491 3492@item thickness, t 3493The expression which sets the thickness of the box edge. Default value is @code{3}. 3494 3495See below for the list of accepted constants. 3496@end table 3497 3498The parameters for @var{x}, @var{y}, @var{w} and @var{h} and @var{t} are expressions containing the 3499following constants: 3500 3501@table @option 3502@item dar 3503The input display aspect ratio, it is the same as (@var{w} / @var{h}) * @var{sar}. 3504 3505@item hsub 3506@item vsub 3507horizontal and vertical chroma subsample values. For example for the 3508pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1. 3509 3510@item in_h, ih 3511@item in_w, iw 3512The input width and height. 3513 3514@item sar 3515The input sample aspect ratio. 3516 3517@item x 3518@item y 3519The x and y offset coordinates where the box is drawn. 3520 3521@item w 3522@item h 3523The width and height of the drawn box. 3524 3525@item t 3526The thickness of the drawn box. 3527 3528These constants allow the @var{x}, @var{y}, @var{w}, @var{h} and @var{t} expressions to refer to 3529each other, so you may for example specify @code{y=x/dar} or @code{h=w/dar}. 3530 3531@end table 3532 3533@subsection Examples 3534 3535@itemize 3536@item 3537Draw a black box around the edge of the input image: 3538@example 3539drawbox 3540@end example 3541 3542@item 3543Draw a box with color red and an opacity of 50%: 3544@example 3545drawbox=10:20:200:60:red@@0.5 3546@end example 3547 3548The previous example can be specified as: 3549@example 3550drawbox=x=10:y=20:w=200:h=60:color=red@@0.5 3551@end example 3552 3553@item 3554Fill the box with pink color: 3555@example 3556drawbox=x=10:y=10:w=100:h=100:color=pink@@0.5:t=max 3557@end example 3558 3559@item 3560Draw a 2-pixel red 2.40:1 mask: 3561@example 3562drawbox=x=-t:y=0.5*(ih-iw/2.4)-t:w=iw+t*2:h=iw/2.4+t*2:t=2:c=red 3563@end example 3564@end itemize 3565 3566@section drawgrid 3567 3568Draw a grid on the input image. 3569 3570It accepts the following parameters: 3571 3572@table @option 3573@item x 3574@item y 3575The expressions which specify the coordinates of some point of grid intersection (meant to configure offset). Both default to 0. 3576 3577@item width, w 3578@item height, h 3579The expressions which specify the width and height of the grid cell, if 0 they are interpreted as the 3580input width and height, respectively, minus @code{thickness}, so image gets 3581framed. Default to 0. 3582 3583@item color, c 3584Specify the color of the grid. For the general syntax of this option, 3585check the "Color" section in the ffmpeg-utils manual. If the special 3586value @code{invert} is used, the grid color is the same as the 3587video with inverted luma. 3588 3589@item thickness, t 3590The expression which sets the thickness of the grid line. Default value is @code{1}. 3591 3592See below for the list of accepted constants. 3593@end table 3594 3595The parameters for @var{x}, @var{y}, @var{w} and @var{h} and @var{t} are expressions containing the 3596following constants: 3597 3598@table @option 3599@item dar 3600The input display aspect ratio, it is the same as (@var{w} / @var{h}) * @var{sar}. 3601 3602@item hsub 3603@item vsub 3604horizontal and vertical chroma subsample values. For example for the 3605pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1. 3606 3607@item in_h, ih 3608@item in_w, iw 3609The input grid cell width and height. 3610 3611@item sar 3612The input sample aspect ratio. 3613 3614@item x 3615@item y 3616The x and y coordinates of some point of grid intersection (meant to configure offset). 3617 3618@item w 3619@item h 3620The width and height of the drawn cell. 3621 3622@item t 3623The thickness of the drawn cell. 3624 3625These constants allow the @var{x}, @var{y}, @var{w}, @var{h} and @var{t} expressions to refer to 3626each other, so you may for example specify @code{y=x/dar} or @code{h=w/dar}. 3627 3628@end table 3629 3630@subsection Examples 3631 3632@itemize 3633@item 3634Draw a grid with cell 100x100 pixels, thickness 2 pixels, with color red and an opacity of 50%: 3635@example 3636drawgrid=width=100:height=100:thickness=2:color=red@@0.5 3637@end example 3638 3639@item 3640Draw a white 3x3 grid with an opacity of 50%: 3641@example 3642drawgrid=w=iw/3:h=ih/3:t=2:c=white@@0.5 3643@end example 3644@end itemize 3645 3646@anchor{drawtext} 3647@section drawtext 3648 3649Draw a text string or text from a specified file on top of a video, using the 3650libfreetype library. 3651 3652To enable compilation of this filter, you need to configure FFmpeg with 3653@code{--enable-libfreetype}. 3654To enable default font fallback and the @var{font} option you need to 3655configure FFmpeg with @code{--enable-libfontconfig}. 3656To enable the @var{text_shaping} option, you need to configure FFmpeg with 3657@code{--enable-libfribidi}. 3658 3659@subsection Syntax 3660 3661It accepts the following parameters: 3662 3663@table @option 3664 3665@item box 3666Used to draw a box around text using the background color. 3667The value must be either 1 (enable) or 0 (disable). 3668The default value of @var{box} is 0. 3669 3670@item boxcolor 3671The color to be used for drawing box around text. For the syntax of this 3672option, check the "Color" section in the ffmpeg-utils manual. 3673 3674The default value of @var{boxcolor} is "white". 3675 3676@item borderw 3677Set the width of the border to be drawn around the text using @var{bordercolor}. 3678The default value of @var{borderw} is 0. 3679 3680@item bordercolor 3681Set the color to be used for drawing border around text. For the syntax of this 3682option, check the "Color" section in the ffmpeg-utils manual. 3683 3684The default value of @var{bordercolor} is "black". 3685 3686@item expansion 3687Select how the @var{text} is expanded. Can be either @code{none}, 3688@code{strftime} (deprecated) or 3689@code{normal} (default). See the @ref{drawtext_expansion, Text expansion} section 3690below for details. 3691 3692@item fix_bounds 3693If true, check and fix text coords to avoid clipping. 3694 3695@item fontcolor 3696The color to be used for drawing fonts. For the syntax of this option, check 3697the "Color" section in the ffmpeg-utils manual. 3698 3699The default value of @var{fontcolor} is "black". 3700 3701@item font 3702The font family to be used for drawing text. By default Sans. 3703 3704@item fontfile 3705The font file to be used for drawing text. The path must be included. 3706This parameter is mandatory if the fontconfig support is disabled. 3707 3708@item fontsize 3709The font size to be used for drawing text. 3710The default value of @var{fontsize} is 16. 3711 3712@item text_shaping 3713If set to 1, attempt to shape the text (for example, reverse the order of 3714right-to-left text and join Arabic characters) before drawing it. 3715Otherwise, just draw the text exactly as given. 3716By default 1 (if supported). 3717 3718@item ft_load_flags 3719The flags to be used for loading the fonts. 3720 3721The flags map the corresponding flags supported by libfreetype, and are 3722a combination of the following values: 3723@table @var 3724@item default 3725@item no_scale 3726@item no_hinting 3727@item render 3728@item no_bitmap 3729@item vertical_layout 3730@item force_autohint 3731@item crop_bitmap 3732@item pedantic 3733@item ignore_global_advance_width 3734@item no_recurse 3735@item ignore_transform 3736@item monochrome 3737@item linear_design 3738@item no_autohint 3739@end table 3740 3741Default value is "default". 3742 3743For more information consult the documentation for the FT_LOAD_* 3744libfreetype flags. 3745 3746@item shadowcolor 3747The color to be used for drawing a shadow behind the drawn text. For the 3748syntax of this option, check the "Color" section in the ffmpeg-utils manual. 3749 3750The default value of @var{shadowcolor} is "black". 3751 3752@item shadowx 3753@item shadowy 3754The x and y offsets for the text shadow position with respect to the 3755position of the text. They can be either positive or negative 3756values. The default value for both is "0". 3757 3758@item start_number 3759The starting frame number for the n/frame_num variable. The default value 3760is "0". 3761 3762@item tabsize 3763The size in number of spaces to use for rendering the tab. 3764Default value is 4. 3765 3766@item timecode 3767Set the initial timecode representation in "hh:mm:ss[:;.]ff" 3768format. It can be used with or without text parameter. @var{timecode_rate} 3769option must be specified. 3770 3771@item timecode_rate, rate, r 3772Set the timecode frame rate (timecode only). 3773 3774@item text 3775The text string to be drawn. The text must be a sequence of UTF-8 3776encoded characters. 3777This parameter is mandatory if no file is specified with the parameter 3778@var{textfile}. 3779 3780@item textfile 3781A text file containing text to be drawn. The text must be a sequence 3782of UTF-8 encoded characters. 3783 3784This parameter is mandatory if no text string is specified with the 3785parameter @var{text}. 3786 3787If both @var{text} and @var{textfile} are specified, an error is thrown. 3788 3789@item reload 3790If set to 1, the @var{textfile} will be reloaded before each frame. 3791Be sure to update it atomically, or it may be read partially, or even fail. 3792 3793@item x 3794@item y 3795The expressions which specify the offsets where text will be drawn 3796within the video frame. They are relative to the top/left border of the 3797output image. 3798 3799The default value of @var{x} and @var{y} is "0". 3800 3801See below for the list of accepted constants and functions. 3802@end table 3803 3804The parameters for @var{x} and @var{y} are expressions containing the 3805following constants and functions: 3806 3807@table @option 3808@item dar 3809input display aspect ratio, it is the same as (@var{w} / @var{h}) * @var{sar} 3810 3811@item hsub 3812@item vsub 3813horizontal and vertical chroma subsample values. For example for the 3814pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1. 3815 3816@item line_h, lh 3817the height of each text line 3818 3819@item main_h, h, H 3820the input height 3821 3822@item main_w, w, W 3823the input width 3824 3825@item max_glyph_a, ascent 3826the maximum distance from the baseline to the highest/upper grid 3827coordinate used to place a glyph outline point, for all the rendered 3828glyphs. 3829It is a positive value, due to the grid's orientation with the Y axis 3830upwards. 3831 3832@item max_glyph_d, descent 3833the maximum distance from the baseline to the lowest grid coordinate 3834used to place a glyph outline point, for all the rendered glyphs. 3835This is a negative value, due to the grid's orientation, with the Y axis 3836upwards. 3837 3838@item max_glyph_h 3839maximum glyph height, that is the maximum height for all the glyphs 3840contained in the rendered text, it is equivalent to @var{ascent} - 3841@var{descent}. 3842 3843@item max_glyph_w 3844maximum glyph width, that is the maximum width for all the glyphs 3845contained in the rendered text 3846 3847@item n 3848the number of input frame, starting from 0 3849 3850@item rand(min, max) 3851return a random number included between @var{min} and @var{max} 3852 3853@item sar 3854The input sample aspect ratio. 3855 3856@item t 3857timestamp expressed in seconds, NAN if the input timestamp is unknown 3858 3859@item text_h, th 3860the height of the rendered text 3861 3862@item text_w, tw 3863the width of the rendered text 3864 3865@item x 3866@item y 3867the x and y offset coordinates where the text is drawn. 3868 3869These parameters allow the @var{x} and @var{y} expressions to refer 3870each other, so you can for example specify @code{y=x/dar}. 3871@end table 3872 3873@anchor{drawtext_expansion} 3874@subsection Text expansion 3875 3876If @option{expansion} is set to @code{strftime}, 3877the filter recognizes strftime() sequences in the provided text and 3878expands them accordingly. Check the documentation of strftime(). This 3879feature is deprecated. 3880 3881If @option{expansion} is set to @code{none}, the text is printed verbatim. 3882 3883If @option{expansion} is set to @code{normal} (which is the default), 3884the following expansion mechanism is used. 3885 3886The backslash character '\', followed by any character, always expands to 3887the second character. 3888 3889Sequence of the form @code{%@{...@}} are expanded. The text between the 3890braces is a function name, possibly followed by arguments separated by ':'. 3891If the arguments contain special characters or delimiters (':' or '@}'), 3892they should be escaped. 3893 3894Note that they probably must also be escaped as the value for the 3895@option{text} option in the filter argument string and as the filter 3896argument in the filtergraph description, and possibly also for the shell, 3897that makes up to four levels of escaping; using a text file avoids these 3898problems. 3899 3900The following functions are available: 3901 3902@table @command 3903 3904@item expr, e 3905The expression evaluation result. 3906 3907It must take one argument specifying the expression to be evaluated, 3908which accepts the same constants and functions as the @var{x} and 3909@var{y} values. Note that not all constants should be used, for 3910example the text size is not known when evaluating the expression, so 3911the constants @var{text_w} and @var{text_h} will have an undefined 3912value. 3913 3914@item gmtime 3915The time at which the filter is running, expressed in UTC. 3916It can accept an argument: a strftime() format string. 3917 3918@item localtime 3919The time at which the filter is running, expressed in the local time zone. 3920It can accept an argument: a strftime() format string. 3921 3922@item metadata 3923Frame metadata. It must take one argument specifying metadata key. 3924 3925@item n, frame_num 3926The frame number, starting from 0. 3927 3928@item pict_type 3929A 1 character description of the current picture type. 3930 3931@item pts 3932The timestamp of the current frame. 3933It can take up to two arguments. 3934 3935The first argument is the format of the timestamp; it defaults to @code{flt} 3936for seconds as a decimal number with microsecond accuracy; @code{hms} stands 3937for a formatted @var{[-]HH:MM:SS.mmm} timestamp with millisecond accuracy. 3938 3939The second argument is an offset added to the timestamp. 3940 3941@end table 3942 3943@subsection Examples 3944 3945@itemize 3946@item 3947Draw "Test Text" with font FreeSerif, using the default values for the 3948optional parameters. 3949 3950@example 3951drawtext="fontfile=/usr/share/fonts/truetype/freefont/FreeSerif.ttf: text='Test Text'" 3952@end example 3953 3954@item 3955Draw 'Test Text' with font FreeSerif of size 24 at position x=100 3956and y=50 (counting from the top-left corner of the screen), text is 3957yellow with a red box around it. Both the text and the box have an 3958opacity of 20%. 3959 3960@example 3961drawtext="fontfile=/usr/share/fonts/truetype/freefont/FreeSerif.ttf: text='Test Text':\ 3962 x=100: y=50: fontsize=24: fontcolor=yellow@@0.2: box=1: boxcolor=red@@0.2" 3963@end example 3964 3965Note that the double quotes are not necessary if spaces are not used 3966within the parameter list. 3967 3968@item 3969Show the text at the center of the video frame: 3970@example 3971drawtext="fontsize=30:fontfile=FreeSerif.ttf:text='hello world':x=(w-text_w)/2:y=(h-text_h-line_h)/2" 3972@end example 3973 3974@item 3975Show a text line sliding from right to left in the last row of the video 3976frame. The file @file{LONG_LINE} is assumed to contain a single line 3977with no newlines. 3978@example 3979drawtext="fontsize=15:fontfile=FreeSerif.ttf:text=LONG_LINE:y=h-line_h:x=-50*t" 3980@end example 3981 3982@item 3983Show the content of file @file{CREDITS} off the bottom of the frame and scroll up. 3984@example 3985drawtext="fontsize=20:fontfile=FreeSerif.ttf:textfile=CREDITS:y=h-20*t" 3986@end example 3987 3988@item 3989Draw a single green letter "g", at the center of the input video. 3990The glyph baseline is placed at half screen height. 3991@example 3992drawtext="fontsize=60:fontfile=FreeSerif.ttf:fontcolor=green:text=g:x=(w-max_glyph_w)/2:y=h/2-ascent" 3993@end example 3994 3995@item 3996Show text for 1 second every 3 seconds: 3997@example 3998drawtext="fontfile=FreeSerif.ttf:fontcolor=white:x=100:y=x/dar:enable=lt(mod(t\,3)\,1):text='blink'" 3999@end example 4000 4001@item 4002Use fontconfig to set the font. Note that the colons need to be escaped. 4003@example 4004drawtext='fontfile=Linux Libertine O-40\:style=Semibold:text=FFmpeg' 4005@end example 4006 4007@item 4008Print the date of a real-time encoding (see strftime(3)): 4009@example 4010drawtext='fontfile=FreeSans.ttf:text=%@{localtime:%a %b %d %Y@}' 4011@end example 4012 4013@end itemize 4014 4015For more information about libfreetype, check: 4016@url{http://www.freetype.org/}. 4017 4018For more information about fontconfig, check: 4019@url{http://freedesktop.org/software/fontconfig/fontconfig-user.html}. 4020 4021For more information about libfribidi, check: 4022@url{http://fribidi.org/}. 4023 4024@section edgedetect 4025 4026Detect and draw edges. The filter uses the Canny Edge Detection algorithm. 4027 4028The filter accepts the following options: 4029 4030@table @option 4031@item low 4032@item high 4033Set low and high threshold values used by the Canny thresholding 4034algorithm. 4035 4036The high threshold selects the "strong" edge pixels, which are then 4037connected through 8-connectivity with the "weak" edge pixels selected 4038by the low threshold. 4039 4040@var{low} and @var{high} threshold values must be chosen in the range 4041[0,1], and @var{low} should be lesser or equal to @var{high}. 4042 4043Default value for @var{low} is @code{20/255}, and default value for @var{high} 4044is @code{50/255}. 4045 4046@item mode 4047Define the drawing mode. 4048 4049@table @samp 4050@item wires 4051Draw white/gray wires on black background. 4052 4053@item colormix 4054Mix the colors to create a paint/cartoon effect. 4055@end table 4056 4057Default value is @var{wires}. 4058@end table 4059 4060@subsection Examples 4061 4062@itemize 4063@item 4064Standard edge detection with custom values for the hysteresis thresholding: 4065@example 4066edgedetect=low=0.1:high=0.4 4067@end example 4068 4069@item 4070Painting effect without thresholding: 4071@example 4072edgedetect=mode=colormix:high=0 4073@end example 4074@end itemize 4075 4076@section extractplanes 4077 4078Extract color channel components from input video stream into 4079separate grayscale video streams. 4080 4081The filter accepts the following option: 4082 4083@table @option 4084@item planes 4085Set plane(s) to extract. 4086 4087Available values for planes are: 4088@table @samp 4089@item y 4090@item u 4091@item v 4092@item a 4093@item r 4094@item g 4095@item b 4096@end table 4097 4098Choosing planes not available in the input will result in an error. 4099That means you cannot select @code{r}, @code{g}, @code{b} planes 4100with @code{y}, @code{u}, @code{v} planes at same time. 4101@end table 4102 4103@subsection Examples 4104 4105@itemize 4106@item 4107Extract luma, u and v color channel component from input video frame 4108into 3 grayscale outputs: 4109@example 4110ffmpeg -i video.avi -filter_complex 'extractplanes=y+u+v[y][u][v]' -map '[y]' y.avi -map '[u]' u.avi -map '[v]' v.avi 4111@end example 4112@end itemize 4113 4114@section elbg 4115 4116Apply a posterize effect using the ELBG (Enhanced LBG) algorithm. 4117 4118For each input image, the filter will compute the optimal mapping from 4119the input to the output given the codebook length, that is the number 4120of distinct output colors. 4121 4122This filter accepts the following options. 4123 4124@table @option 4125@item codebook_length, l 4126Set codebook length. The value must be a positive integer, and 4127represents the number of distinct output colors. Default value is 256. 4128 4129@item nb_steps, n 4130Set the maximum number of iterations to apply for computing the optimal 4131mapping. The higher the value the better the result and the higher the 4132computation time. Default value is 1. 4133 4134@item seed, s 4135Set a random seed, must be an integer included between 0 and 4136UINT32_MAX. If not specified, or if explicitly set to -1, the filter 4137will try to use a good random seed on a best effort basis. 4138@end table 4139 4140@section fade 4141 4142Apply a fade-in/out effect to the input video. 4143 4144It accepts the following parameters: 4145 4146@table @option 4147@item type, t 4148The effect type can be either "in" for a fade-in, or "out" for a fade-out 4149effect. 4150Default is @code{in}. 4151 4152@item start_frame, s 4153Specify the number of the frame to start applying the fade 4154effect at. Default is 0. 4155 4156@item nb_frames, n 4157The number of frames that the fade effect lasts. At the end of the 4158fade-in effect, the output video will have the same intensity as the input video. 4159At the end of the fade-out transition, the output video will be filled with the 4160selected @option{color}. 4161Default is 25. 4162 4163@item alpha 4164If set to 1, fade only alpha channel, if one exists on the input. 4165Default value is 0. 4166 4167@item start_time, st 4168Specify the timestamp (in seconds) of the frame to start to apply the fade 4169effect. If both start_frame and start_time are specified, the fade will start at 4170whichever comes last. Default is 0. 4171 4172@item duration, d 4173The number of seconds for which the fade effect has to last. At the end of the 4174fade-in effect the output video will have the same intensity as the input video, 4175at the end of the fade-out transition the output video will be filled with the 4176selected @option{color}. 4177If both duration and nb_frames are specified, duration is used. Default is 0. 4178 4179@item color, c 4180Specify the color of the fade. Default is "black". 4181@end table 4182 4183@subsection Examples 4184 4185@itemize 4186@item 4187Fade in the first 30 frames of video: 4188@example 4189fade=in:0:30 4190@end example 4191 4192The command above is equivalent to: 4193@example 4194fade=t=in:s=0:n=30 4195@end example 4196 4197@item 4198Fade out the last 45 frames of a 200-frame video: 4199@example 4200fade=out:155:45 4201fade=type=out:start_frame=155:nb_frames=45 4202@end example 4203 4204@item 4205Fade in the first 25 frames and fade out the last 25 frames of a 1000-frame video: 4206@example 4207fade=in:0:25, fade=out:975:25 4208@end example 4209 4210@item 4211Make the first 5 frames yellow, then fade in from frame 5-24: 4212@example 4213fade=in:5:20:color=yellow 4214@end example 4215 4216@item 4217Fade in alpha over first 25 frames of video: 4218@example 4219fade=in:0:25:alpha=1 4220@end example 4221 4222@item 4223Make the first 5.5 seconds black, then fade in for 0.5 seconds: 4224@example 4225fade=t=in:st=5.5:d=0.5 4226@end example 4227 4228@end itemize 4229 4230@section field 4231 4232Extract a single field from an interlaced image using stride 4233arithmetic to avoid wasting CPU time. The output frames are marked as 4234non-interlaced. 4235 4236The filter accepts the following options: 4237 4238@table @option 4239@item type 4240Specify whether to extract the top (if the value is @code{0} or 4241@code{top}) or the bottom field (if the value is @code{1} or 4242@code{bottom}). 4243@end table 4244 4245@section fieldmatch 4246 4247Field matching filter for inverse telecine. It is meant to reconstruct the 4248progressive frames from a telecined stream. The filter does not drop duplicated 4249frames, so to achieve a complete inverse telecine @code{fieldmatch} needs to be 4250followed by a decimation filter such as @ref{decimate} in the filtergraph. 4251 4252The separation of the field matching and the decimation is notably motivated by 4253the possibility of inserting a de-interlacing filter fallback between the two. 4254If the source has mixed telecined and real interlaced content, 4255@code{fieldmatch} will not be able to match fields for the interlaced parts. 4256But these remaining combed frames will be marked as interlaced, and thus can be 4257de-interlaced by a later filter such as @ref{yadif} before decimation. 4258 4259In addition to the various configuration options, @code{fieldmatch} can take an 4260optional second stream, activated through the @option{ppsrc} option. If 4261enabled, the frames reconstruction will be based on the fields and frames from 4262this second stream. This allows the first input to be pre-processed in order to 4263help the various algorithms of the filter, while keeping the output lossless 4264(assuming the fields are matched properly). Typically, a field-aware denoiser, 4265or brightness/contrast adjustments can help. 4266 4267Note that this filter uses the same algorithms as TIVTC/TFM (AviSynth project) 4268and VIVTC/VFM (VapourSynth project). The later is a light clone of TFM from 4269which @code{fieldmatch} is based on. While the semantic and usage are very 4270close, some behaviour and options names can differ. 4271 4272The filter accepts the following options: 4273 4274@table @option 4275@item order 4276Specify the assumed field order of the input stream. Available values are: 4277 4278@table @samp 4279@item auto 4280Auto detect parity (use FFmpeg's internal parity value). 4281@item bff 4282Assume bottom field first. 4283@item tff 4284Assume top field first. 4285@end table 4286 4287Note that it is sometimes recommended not to trust the parity announced by the 4288stream. 4289 4290Default value is @var{auto}. 4291 4292@item mode 4293Set the matching mode or strategy to use. @option{pc} mode is the safest in the 4294sense that it won't risk creating jerkiness due to duplicate frames when 4295possible, but if there are bad edits or blended fields it will end up 4296outputting combed frames when a good match might actually exist. On the other 4297hand, @option{pcn_ub} mode is the most risky in terms of creating jerkiness, 4298but will almost always find a good frame if there is one. The other values are 4299all somewhere in between @option{pc} and @option{pcn_ub} in terms of risking 4300jerkiness and creating duplicate frames versus finding good matches in sections 4301with bad edits, orphaned fields, blended fields, etc. 4302 4303More details about p/c/n/u/b are available in @ref{p/c/n/u/b meaning} section. 4304 4305Available values are: 4306 4307@table @samp 4308@item pc 43092-way matching (p/c) 4310@item pc_n 43112-way matching, and trying 3rd match if still combed (p/c + n) 4312@item pc_u 43132-way matching, and trying 3rd match (same order) if still combed (p/c + u) 4314@item pc_n_ub 43152-way matching, trying 3rd match if still combed, and trying 4th/5th matches if 4316still combed (p/c + n + u/b) 4317@item pcn 43183-way matching (p/c/n) 4319@item pcn_ub 43203-way matching, and trying 4th/5th matches if all 3 of the original matches are 4321detected as combed (p/c/n + u/b) 4322@end table 4323 4324The parenthesis at the end indicate the matches that would be used for that 4325mode assuming @option{order}=@var{tff} (and @option{field} on @var{auto} or 4326@var{top}). 4327 4328In terms of speed @option{pc} mode is by far the fastest and @option{pcn_ub} is 4329the slowest. 4330 4331Default value is @var{pc_n}. 4332 4333@item ppsrc 4334Mark the main input stream as a pre-processed input, and enable the secondary 4335input stream as the clean source to pick the fields from. See the filter 4336introduction for more details. It is similar to the @option{clip2} feature from 4337VFM/TFM. 4338 4339Default value is @code{0} (disabled). 4340 4341@item field 4342Set the field to match from. It is recommended to set this to the same value as 4343@option{order} unless you experience matching failures with that setting. In 4344certain circumstances changing the field that is used to match from can have a 4345large impact on matching performance. Available values are: 4346 4347@table @samp 4348@item auto 4349Automatic (same value as @option{order}). 4350@item bottom 4351Match from the bottom field. 4352@item top 4353Match from the top field. 4354@end table 4355 4356Default value is @var{auto}. 4357 4358@item mchroma 4359Set whether or not chroma is included during the match comparisons. In most 4360cases it is recommended to leave this enabled. You should set this to @code{0} 4361only if your clip has bad chroma problems such as heavy rainbowing or other 4362artifacts. Setting this to @code{0} could also be used to speed things up at 4363the cost of some accuracy. 4364 4365Default value is @code{1}. 4366 4367@item y0 4368@item y1 4369These define an exclusion band which excludes the lines between @option{y0} and 4370@option{y1} from being included in the field matching decision. An exclusion 4371band can be used to ignore subtitles, a logo, or other things that may 4372interfere with the matching. @option{y0} sets the starting scan line and 4373@option{y1} sets the ending line; all lines in between @option{y0} and 4374@option{y1} (including @option{y0} and @option{y1}) will be ignored. Setting 4375@option{y0} and @option{y1} to the same value will disable the feature. 4376@option{y0} and @option{y1} defaults to @code{0}. 4377 4378@item scthresh 4379Set the scene change detection threshold as a percentage of maximum change on 4380the luma plane. Good values are in the @code{[8.0, 14.0]} range. Scene change 4381detection is only relevant in case @option{combmatch}=@var{sc}. The range for 4382@option{scthresh} is @code{[0.0, 100.0]}. 4383 4384Default value is @code{12.0}. 4385 4386@item combmatch 4387When @option{combatch} is not @var{none}, @code{fieldmatch} will take into 4388account the combed scores of matches when deciding what match to use as the 4389final match. Available values are: 4390 4391@table @samp 4392@item none 4393No final matching based on combed scores. 4394@item sc 4395Combed scores are only used when a scene change is detected. 4396@item full 4397Use combed scores all the time. 4398@end table 4399 4400Default is @var{sc}. 4401 4402@item combdbg 4403Force @code{fieldmatch} to calculate the combed metrics for certain matches and 4404print them. This setting is known as @option{micout} in TFM/VFM vocabulary. 4405Available values are: 4406 4407@table @samp 4408@item none 4409No forced calculation. 4410@item pcn 4411Force p/c/n calculations. 4412@item pcnub 4413Force p/c/n/u/b calculations. 4414@end table 4415 4416Default value is @var{none}. 4417 4418@item cthresh 4419This is the area combing threshold used for combed frame detection. This 4420essentially controls how "strong" or "visible" combing must be to be detected. 4421Larger values mean combing must be more visible and smaller values mean combing 4422can be less visible or strong and still be detected. Valid settings are from 4423@code{-1} (every pixel will be detected as combed) to @code{255} (no pixel will 4424be detected as combed). This is basically a pixel difference value. A good 4425range is @code{[8, 12]}. 4426 4427Default value is @code{9}. 4428 4429@item chroma 4430Sets whether or not chroma is considered in the combed frame decision. Only 4431disable this if your source has chroma problems (rainbowing, etc.) that are 4432causing problems for the combed frame detection with chroma enabled. Actually, 4433using @option{chroma}=@var{0} is usually more reliable, except for the case 4434where there is chroma only combing in the source. 4435 4436Default value is @code{0}. 4437 4438@item blockx 4439@item blocky 4440Respectively set the x-axis and y-axis size of the window used during combed 4441frame detection. This has to do with the size of the area in which 4442@option{combpel} pixels are required to be detected as combed for a frame to be 4443declared combed. See the @option{combpel} parameter description for more info. 4444Possible values are any number that is a power of 2 starting at 4 and going up 4445to 512. 4446 4447Default value is @code{16}. 4448 4449@item combpel 4450The number of combed pixels inside any of the @option{blocky} by 4451@option{blockx} size blocks on the frame for the frame to be detected as 4452combed. While @option{cthresh} controls how "visible" the combing must be, this 4453setting controls "how much" combing there must be in any localized area (a 4454window defined by the @option{blockx} and @option{blocky} settings) on the 4455frame. Minimum value is @code{0} and maximum is @code{blocky x blockx} (at 4456which point no frames will ever be detected as combed). This setting is known 4457as @option{MI} in TFM/VFM vocabulary. 4458 4459Default value is @code{80}. 4460@end table 4461 4462@anchor{p/c/n/u/b meaning} 4463@subsection p/c/n/u/b meaning 4464 4465@subsubsection p/c/n 4466 4467We assume the following telecined stream: 4468 4469@example 4470Top fields: 1 2 2 3 4 4471Bottom fields: 1 2 3 4 4 4472@end example 4473 4474The numbers correspond to the progressive frame the fields relate to. Here, the 4475first two frames are progressive, the 3rd and 4th are combed, and so on. 4476 4477When @code{fieldmatch} is configured to run a matching from bottom 4478(@option{field}=@var{bottom}) this is how this input stream get transformed: 4479 4480@example 4481Input stream: 4482 T 1 2 2 3 4 4483 B 1 2 3 4 4 <-- matching reference 4484 4485Matches: c c n n c 4486 4487Output stream: 4488 T 1 2 3 4 4 4489 B 1 2 3 4 4 4490@end example 4491 4492As a result of the field matching, we can see that some frames get duplicated. 4493To perform a complete inverse telecine, you need to rely on a decimation filter 4494after this operation. See for instance the @ref{decimate} filter. 4495 4496The same operation now matching from top fields (@option{field}=@var{top}) 4497looks like this: 4498 4499@example 4500Input stream: 4501 T 1 2 2 3 4 <-- matching reference 4502 B 1 2 3 4 4 4503 4504Matches: c c p p c 4505 4506Output stream: 4507 T 1 2 2 3 4 4508 B 1 2 2 3 4 4509@end example 4510 4511In these examples, we can see what @var{p}, @var{c} and @var{n} mean; 4512basically, they refer to the frame and field of the opposite parity: 4513 4514@itemize 4515@item @var{p} matches the field of the opposite parity in the previous frame 4516@item @var{c} matches the field of the opposite parity in the current frame 4517@item @var{n} matches the field of the opposite parity in the next frame 4518@end itemize 4519 4520@subsubsection u/b 4521 4522The @var{u} and @var{b} matching are a bit special in the sense that they match 4523from the opposite parity flag. In the following examples, we assume that we are 4524currently matching the 2nd frame (Top:2, bottom:2). According to the match, a 4525'x' is placed above and below each matched fields. 4526 4527With bottom matching (@option{field}=@var{bottom}): 4528@example 4529Match: c p n b u 4530 4531 x x x x x 4532 Top 1 2 2 1 2 2 1 2 2 1 2 2 1 2 2 4533 Bottom 1 2 3 1 2 3 1 2 3 1 2 3 1 2 3 4534 x x x x x 4535 4536Output frames: 4537 2 1 2 2 2 4538 2 2 2 1 3 4539@end example 4540 4541With top matching (@option{field}=@var{top}): 4542@example 4543Match: c p n b u 4544 4545 x x x x x 4546 Top 1 2 2 1 2 2 1 2 2 1 2 2 1 2 2 4547 Bottom 1 2 3 1 2 3 1 2 3 1 2 3 1 2 3 4548 x x x x x 4549 4550Output frames: 4551 2 2 2 1 2 4552 2 1 3 2 2 4553@end example 4554 4555@subsection Examples 4556 4557Simple IVTC of a top field first telecined stream: 4558@example 4559fieldmatch=order=tff:combmatch=none, decimate 4560@end example 4561 4562Advanced IVTC, with fallback on @ref{yadif} for still combed frames: 4563@example 4564fieldmatch=order=tff:combmatch=full, yadif=deint=interlaced, decimate 4565@end example 4566 4567@section fieldorder 4568 4569Transform the field order of the input video. 4570 4571It accepts the following parameters: 4572 4573@table @option 4574 4575@item order 4576The output field order. Valid values are @var{tff} for top field first or @var{bff} 4577for bottom field first. 4578@end table 4579 4580The default value is @samp{tff}. 4581 4582The transformation is done by shifting the picture content up or down 4583by one line, and filling the remaining line with appropriate picture content. 4584This method is consistent with most broadcast field order converters. 4585 4586If the input video is not flagged as being interlaced, or it is already 4587flagged as being of the required output field order, then this filter does 4588not alter the incoming video. 4589 4590It is very useful when converting to or from PAL DV material, 4591which is bottom field first. 4592 4593For example: 4594@example 4595ffmpeg -i in.vob -vf "fieldorder=bff" out.dv 4596@end example 4597 4598@section fifo 4599 4600Buffer input images and send them when they are requested. 4601 4602It is mainly useful when auto-inserted by the libavfilter 4603framework. 4604 4605It does not take parameters. 4606 4607@anchor{format} 4608@section format 4609 4610Convert the input video to one of the specified pixel formats. 4611Libavfilter will try to pick one that is suitable as input to 4612the next filter. 4613 4614It accepts the following parameters: 4615@table @option 4616 4617@item pix_fmts 4618A '|'-separated list of pixel format names, such as 4619"pix_fmts=yuv420p|monow|rgb24". 4620 4621@end table 4622 4623@subsection Examples 4624 4625@itemize 4626@item 4627Convert the input video to the @var{yuv420p} format 4628@example 4629format=pix_fmts=yuv420p 4630@end example 4631 4632Convert the input video to any of the formats in the list 4633@example 4634format=pix_fmts=yuv420p|yuv444p|yuv410p 4635@end example 4636@end itemize 4637 4638@anchor{fps} 4639@section fps 4640 4641Convert the video to specified constant frame rate by duplicating or dropping 4642frames as necessary. 4643 4644It accepts the following parameters: 4645@table @option 4646 4647@item fps 4648The desired output frame rate. The default is @code{25}. 4649 4650@item round 4651Rounding method. 4652 4653Possible values are: 4654@table @option 4655@item zero 4656zero round towards 0 4657@item inf 4658round away from 0 4659@item down 4660round towards -infinity 4661@item up 4662round towards +infinity 4663@item near 4664round to nearest 4665@end table 4666The default is @code{near}. 4667 4668@item start_time 4669Assume the first PTS should be the given value, in seconds. This allows for 4670padding/trimming at the start of stream. By default, no assumption is made 4671about the first frame's expected PTS, so no padding or trimming is done. 4672For example, this could be set to 0 to pad the beginning with duplicates of 4673the first frame if a video stream starts after the audio stream or to trim any 4674frames with a negative PTS. 4675 4676@end table 4677 4678Alternatively, the options can be specified as a flat string: 4679@var{fps}[:@var{round}]. 4680 4681See also the @ref{setpts} filter. 4682 4683@subsection Examples 4684 4685@itemize 4686@item 4687A typical usage in order to set the fps to 25: 4688@example 4689fps=fps=25 4690@end example 4691 4692@item 4693Sets the fps to 24, using abbreviation and rounding method to round to nearest: 4694@example 4695fps=fps=film:round=near 4696@end example 4697@end itemize 4698 4699@section framepack 4700 4701Pack two different video streams into a stereoscopic video, setting proper 4702metadata on supported codecs. The two views should have the same size and 4703framerate and processing will stop when the shorter video ends. Please note 4704that you may conveniently adjust view properties with the @ref{scale} and 4705@ref{fps} filters. 4706 4707It accepts the following parameters: 4708@table @option 4709 4710@item format 4711The desired packing format. Supported values are: 4712 4713@table @option 4714 4715@item sbs 4716The views are next to each other (default). 4717 4718@item tab 4719The views are on top of each other. 4720 4721@item lines 4722The views are packed by line. 4723 4724@item columns 4725The views are packed by column. 4726 4727@item frameseq 4728The views are temporally interleaved. 4729 4730@end table 4731 4732@end table 4733 4734Some examples: 4735 4736@example 4737# Convert left and right views into a frame-sequential video 4738ffmpeg -i LEFT -i RIGHT -filter_complex framepack=frameseq OUTPUT 4739 4740# Convert views into a side-by-side video with the same output resolution as the input 4741ffmpeg -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 4742@end example 4743 4744@section framestep 4745 4746Select one frame every N-th frame. 4747 4748This filter accepts the following option: 4749@table @option 4750@item step 4751Select frame after every @code{step} frames. 4752Allowed values are positive integers higher than 0. Default value is @code{1}. 4753@end table 4754 4755@anchor{frei0r} 4756@section frei0r 4757 4758Apply a frei0r effect to the input video. 4759 4760To enable the compilation of this filter, you need to install the frei0r 4761header and configure FFmpeg with @code{--enable-frei0r}. 4762 4763It accepts the following parameters: 4764 4765@table @option 4766 4767@item filter_name 4768The name of the frei0r effect to load. If the environment variable 4769@env{FREI0R_PATH} is defined, the frei0r effect is searched for in each of the 4770directories specified by the colon-separated list in @env{FREIOR_PATH}. 4771Otherwise, the standard frei0r paths are searched, in this order: 4772@file{HOME/.frei0r-1/lib/}, @file{/usr/local/lib/frei0r-1/}, 4773@file{/usr/lib/frei0r-1/}. 4774 4775@item filter_params 4776A '|'-separated list of parameters to pass to the frei0r effect. 4777 4778@end table 4779 4780A frei0r effect parameter can be a boolean (its value is either 4781"y" or "n"), a double, a color (specified as 4782@var{R}/@var{G}/@var{B}, where @var{R}, @var{G}, and @var{B} are floating point 4783numbers between 0.0 and 1.0, inclusive) or by a color description specified in the "Color" 4784section in the ffmpeg-utils manual), a position (specified as @var{X}/@var{Y}, where 4785@var{X} and @var{Y} are floating point numbers) and/or a string. 4786 4787The number and types of parameters depend on the loaded effect. If an 4788effect parameter is not specified, the default value is set. 4789 4790@subsection Examples 4791 4792@itemize 4793@item 4794Apply the distort0r effect, setting the first two double parameters: 4795@example 4796frei0r=filter_name=distort0r:filter_params=0.5|0.01 4797@end example 4798 4799@item 4800Apply the colordistance effect, taking a color as the first parameter: 4801@example 4802frei0r=colordistance:0.2/0.3/0.4 4803frei0r=colordistance:violet 4804frei0r=colordistance:0x112233 4805@end example 4806 4807@item 4808Apply the perspective effect, specifying the top left and top right image 4809positions: 4810@example 4811frei0r=perspective:0.2/0.2|0.8/0.2 4812@end example 4813@end itemize 4814 4815For more information, see 4816@url{http://frei0r.dyne.org} 4817 4818@section geq 4819 4820The filter accepts the following options: 4821 4822@table @option 4823@item lum_expr, lum 4824Set the luminance expression. 4825@item cb_expr, cb 4826Set the chrominance blue expression. 4827@item cr_expr, cr 4828Set the chrominance red expression. 4829@item alpha_expr, a 4830Set the alpha expression. 4831@item red_expr, r 4832Set the red expression. 4833@item green_expr, g 4834Set the green expression. 4835@item blue_expr, b 4836Set the blue expression. 4837@end table 4838 4839The colorspace is selected according to the specified options. If one 4840of the @option{lum_expr}, @option{cb_expr}, or @option{cr_expr} 4841options is specified, the filter will automatically select a YCbCr 4842colorspace. If one of the @option{red_expr}, @option{green_expr}, or 4843@option{blue_expr} options is specified, it will select an RGB 4844colorspace. 4845 4846If one of the chrominance expression is not defined, it falls back on the other 4847one. If no alpha expression is specified it will evaluate to opaque value. 4848If none of chrominance expressions are specified, they will evaluate 4849to the luminance expression. 4850 4851The expressions can use the following variables and functions: 4852 4853@table @option 4854@item N 4855The sequential number of the filtered frame, starting from @code{0}. 4856 4857@item X 4858@item Y 4859The coordinates of the current sample. 4860 4861@item W 4862@item H 4863The width and height of the image. 4864 4865@item SW 4866@item SH 4867Width and height scale depending on the currently filtered plane. It is the 4868ratio between the corresponding luma plane number of pixels and the current 4869plane ones. E.g. for YUV4:2:0 the values are @code{1,1} for the luma plane, and 4870@code{0.5,0.5} for chroma planes. 4871 4872@item T 4873Time of the current frame, expressed in seconds. 4874 4875@item p(x, y) 4876Return the value of the pixel at location (@var{x},@var{y}) of the current 4877plane. 4878 4879@item lum(x, y) 4880Return the value of the pixel at location (@var{x},@var{y}) of the luminance 4881plane. 4882 4883@item cb(x, y) 4884Return the value of the pixel at location (@var{x},@var{y}) of the 4885blue-difference chroma plane. Return 0 if there is no such plane. 4886 4887@item cr(x, y) 4888Return the value of the pixel at location (@var{x},@var{y}) of the 4889red-difference chroma plane. Return 0 if there is no such plane. 4890 4891@item r(x, y) 4892@item g(x, y) 4893@item b(x, y) 4894Return the value of the pixel at location (@var{x},@var{y}) of the 4895red/green/blue component. Return 0 if there is no such component. 4896 4897@item alpha(x, y) 4898Return the value of the pixel at location (@var{x},@var{y}) of the alpha 4899plane. Return 0 if there is no such plane. 4900@end table 4901 4902For functions, if @var{x} and @var{y} are outside the area, the value will be 4903automatically clipped to the closer edge. 4904 4905@subsection Examples 4906 4907@itemize 4908@item 4909Flip the image horizontally: 4910@example 4911geq=p(W-X\,Y) 4912@end example 4913 4914@item 4915Generate a bidimensional sine wave, with angle @code{PI/3} and a 4916wavelength of 100 pixels: 4917@example 4918geq=128 + 100*sin(2*(PI/100)*(cos(PI/3)*(X-50*T) + sin(PI/3)*Y)):128:128 4919@end example 4920 4921@item 4922Generate a fancy enigmatic moving light: 4923@example 4924nullsrc=s=256x256,geq=random(1)/hypot(X-cos(N*0.07)*W/2-W/2\,Y-sin(N*0.09)*H/2-H/2)^2*1000000*sin(N*0.02):128:128 4925@end example 4926 4927@item 4928Generate a quick emboss effect: 4929@example 4930format=gray,geq=lum_expr='(p(X,Y)+(256-p(X-4,Y-4)))/2' 4931@end example 4932 4933@item 4934Modify RGB components depending on pixel position: 4935@example 4936geq=r='X/W*r(X,Y)':g='(1-X/W)*g(X,Y)':b='(H-Y)/H*b(X,Y)' 4937@end example 4938@end itemize 4939 4940@section gradfun 4941 4942Fix the banding artifacts that are sometimes introduced into nearly flat 4943regions by truncation to 8bit color depth. 4944Interpolate the gradients that should go where the bands are, and 4945dither them. 4946 4947It is designed for playback only. Do not use it prior to 4948lossy compression, because compression tends to lose the dither and 4949bring back the bands. 4950 4951It accepts the following parameters: 4952 4953@table @option 4954 4955@item strength 4956The maximum amount by which the filter will change any one pixel. This is also 4957the threshold for detecting nearly flat regions. Acceptable values range from 4958.51 to 64; the default value is 1.2. Out-of-range values will be clipped to the 4959valid range. 4960 4961@item radius 4962The neighborhood to fit the gradient to. A larger radius makes for smoother 4963gradients, but also prevents the filter from modifying the pixels near detailed 4964regions. Acceptable values are 8-32; the default value is 16. Out-of-range 4965values will be clipped to the valid range. 4966 4967@end table 4968 4969Alternatively, the options can be specified as a flat string: 4970@var{strength}[:@var{radius}] 4971 4972@subsection Examples 4973 4974@itemize 4975@item 4976Apply the filter with a @code{3.5} strength and radius of @code{8}: 4977@example 4978gradfun=3.5:8 4979@end example 4980 4981@item 4982Specify radius, omitting the strength (which will fall-back to the default 4983value): 4984@example 4985gradfun=radius=8 4986@end example 4987 4988@end itemize 4989 4990@anchor{haldclut} 4991@section haldclut 4992 4993Apply a Hald CLUT to a video stream. 4994 4995First input is the video stream to process, and second one is the Hald CLUT. 4996The Hald CLUT input can be a simple picture or a complete video stream. 4997 4998The filter accepts the following options: 4999 5000@table @option 5001@item shortest 5002Force termination when the shortest input terminates. Default is @code{0}. 5003@item repeatlast 5004Continue applying the last CLUT after the end of the stream. A value of 5005@code{0} disable the filter after the last frame of the CLUT is reached. 5006Default is @code{1}. 5007@end table 5008 5009@code{haldclut} also has the same interpolation options as @ref{lut3d} (both 5010filters share the same internals). 5011 5012More information about the Hald CLUT can be found on Eskil Steenberg's website 5013(Hald CLUT author) at @url{http://www.quelsolaar.com/technology/clut.html}. 5014 5015@subsection Workflow examples 5016 5017@subsubsection Hald CLUT video stream 5018 5019Generate an identity Hald CLUT stream altered with various effects: 5020@example 5021ffmpeg -f lavfi -i @ref{haldclutsrc}=8 -vf "hue=H=2*PI*t:s=sin(2*PI*t)+1, curves=cross_process" -t 10 -c:v ffv1 clut.nut 5022@end example 5023 5024Note: make sure you use a lossless codec. 5025 5026Then use it with @code{haldclut} to apply it on some random stream: 5027@example 5028ffmpeg -f lavfi -i mandelbrot -i clut.nut -filter_complex '[0][1] haldclut' -t 20 mandelclut.mkv 5029@end example 5030 5031The Hald CLUT will be applied to the 10 first seconds (duration of 5032@file{clut.nut}), then the latest picture of that CLUT stream will be applied 5033to the remaining frames of the @code{mandelbrot} stream. 5034 5035@subsubsection Hald CLUT with preview 5036 5037A Hald CLUT is supposed to be a squared image of @code{Level*Level*Level} by 5038@code{Level*Level*Level} pixels. For a given Hald CLUT, FFmpeg will select the 5039biggest possible square starting at the top left of the picture. The remaining 5040padding pixels (bottom or right) will be ignored. This area can be used to add 5041a preview of the Hald CLUT. 5042 5043Typically, the following generated Hald CLUT will be supported by the 5044@code{haldclut} filter: 5045 5046@example 5047ffmpeg -f lavfi -i @ref{haldclutsrc}=8 -vf " 5048 pad=iw+320 [padded_clut]; 5049 smptebars=s=320x256, split [a][b]; 5050 [padded_clut][a] overlay=W-320:h, curves=color_negative [main]; 5051 [main][b] overlay=W-320" -frames:v 1 clut.png 5052@end example 5053 5054It contains the original and a preview of the effect of the CLUT: SMPTE color 5055bars are displayed on the right-top, and below the same color bars processed by 5056the color changes. 5057 5058Then, the effect of this Hald CLUT can be visualized with: 5059@example 5060ffplay input.mkv -vf "movie=clut.png, [in] haldclut" 5061@end example 5062 5063@section hflip 5064 5065Flip the input video horizontally. 5066 5067For example, to horizontally flip the input video with @command{ffmpeg}: 5068@example 5069ffmpeg -i in.avi -vf "hflip" out.avi 5070@end example 5071 5072@section histeq 5073This filter applies a global color histogram equalization on a 5074per-frame basis. 5075 5076It can be used to correct video that has a compressed range of pixel 5077intensities. The filter redistributes the pixel intensities to 5078equalize their distribution across the intensity range. It may be 5079viewed as an "automatically adjusting contrast filter". This filter is 5080useful only for correcting degraded or poorly captured source 5081video. 5082 5083The filter accepts the following options: 5084 5085@table @option 5086@item strength 5087Determine the amount of equalization to be applied. As the strength 5088is reduced, the distribution of pixel intensities more-and-more 5089approaches that of the input frame. The value must be a float number 5090in the range [0,1] and defaults to 0.200. 5091 5092@item intensity 5093Set the maximum intensity that can generated and scale the output 5094values appropriately. The strength should be set as desired and then 5095the intensity can be limited if needed to avoid washing-out. The value 5096must be a float number in the range [0,1] and defaults to 0.210. 5097 5098@item antibanding 5099Set the antibanding level. If enabled the filter will randomly vary 5100the luminance of output pixels by a small amount to avoid banding of 5101the histogram. Possible values are @code{none}, @code{weak} or 5102@code{strong}. It defaults to @code{none}. 5103@end table 5104 5105@section histogram 5106 5107Compute and draw a color distribution histogram for the input video. 5108 5109The computed histogram is a representation of the color component 5110distribution in an image. 5111 5112The filter accepts the following options: 5113 5114@table @option 5115@item mode 5116Set histogram mode. 5117 5118It accepts the following values: 5119@table @samp 5120@item levels 5121Standard histogram that displays the color components distribution in an 5122image. Displays color graph for each color component. Shows distribution of 5123the Y, U, V, A or R, G, B components, depending on input format, in the 5124current frame. Below each graph a color component scale meter is shown. 5125 5126@item color 5127Displays chroma values (U/V color placement) in a two dimensional 5128graph (which is called a vectorscope). The brighter a pixel in the 5129vectorscope, the more pixels of the input frame correspond to that pixel 5130(i.e., more pixels have this chroma value). The V component is displayed on 5131the horizontal (X) axis, with the leftmost side being V = 0 and the rightmost 5132side being V = 255. The U component is displayed on the vertical (Y) axis, 5133with the top representing U = 0 and the bottom representing U = 255. 5134 5135The position of a white pixel in the graph corresponds to the chroma value of 5136a pixel of the input clip. The graph can therefore be used to read the hue 5137(color flavor) and the saturation (the dominance of the hue in the color). As 5138the hue of a color changes, it moves around the square. At the center of the 5139square the saturation is zero, which means that the corresponding pixel has no 5140color. If the amount of a specific color is increased (while leaving the other 5141colors unchanged) the saturation increases, and the indicator moves towards 5142the edge of the square. 5143 5144@item color2 5145Chroma values in vectorscope, similar as @code{color} but actual chroma values 5146are displayed. 5147 5148@item waveform 5149Per row/column color component graph. In row mode, the graph on the left side 5150represents color component value 0 and the right side represents value = 255. 5151In column mode, the top side represents color component value = 0 and bottom 5152side represents value = 255. 5153@end table 5154Default value is @code{levels}. 5155 5156@item level_height 5157Set height of level in @code{levels}. Default value is @code{200}. 5158Allowed range is [50, 2048]. 5159 5160@item scale_height 5161Set height of color scale in @code{levels}. Default value is @code{12}. 5162Allowed range is [0, 40]. 5163 5164@item step 5165Set step for @code{waveform} mode. Smaller values are useful to find out how 5166many values of the same luminance are distributed across input rows/columns. 5167Default value is @code{10}. Allowed range is [1, 255]. 5168 5169@item waveform_mode 5170Set mode for @code{waveform}. Can be either @code{row}, or @code{column}. 5171Default is @code{row}. 5172 5173@item waveform_mirror 5174Set mirroring mode for @code{waveform}. @code{0} means unmirrored, @code{1} 5175means mirrored. In mirrored mode, higher values will be represented on the left 5176side for @code{row} mode and at the top for @code{column} mode. Default is 5177@code{0} (unmirrored). 5178 5179@item display_mode 5180Set display mode for @code{waveform} and @code{levels}. 5181It accepts the following values: 5182@table @samp 5183@item parade 5184Display separate graph for the color components side by side in 5185@code{row} waveform mode or one below the other in @code{column} waveform mode 5186for @code{waveform} histogram mode. For @code{levels} histogram mode, 5187per color component graphs are placed below each other. 5188 5189Using this display mode in @code{waveform} histogram mode makes it easy to 5190spot color casts in the highlights and shadows of an image, by comparing the 5191contours of the top and the bottom graphs of each waveform. Since whites, 5192grays, and blacks are characterized by exactly equal amounts of red, green, 5193and blue, neutral areas of the picture should display three waveforms of 5194roughly equal width/height. If not, the correction is easy to perform by 5195making level adjustments the three waveforms. 5196 5197@item overlay 5198Presents information identical to that in the @code{parade}, except 5199that the graphs representing color components are superimposed directly 5200over one another. 5201 5202This display mode in @code{waveform} histogram mode makes it easier to spot 5203relative differences or similarities in overlapping areas of the color 5204components that are supposed to be identical, such as neutral whites, grays, 5205or blacks. 5206@end table 5207Default is @code{parade}. 5208 5209@item levels_mode 5210Set mode for @code{levels}. Can be either @code{linear}, or @code{logarithmic}. 5211Default is @code{linear}. 5212@end table 5213 5214@subsection Examples 5215 5216@itemize 5217 5218@item 5219Calculate and draw histogram: 5220@example 5221ffplay -i input -vf histogram 5222@end example 5223 5224@end itemize 5225 5226@anchor{hqdn3d} 5227@section hqdn3d 5228 5229This is a high precision/quality 3d denoise filter. It aims to reduce 5230image noise, producing smooth images and making still images really 5231still. It should enhance compressibility. 5232 5233It accepts the following optional parameters: 5234 5235@table @option 5236@item luma_spatial 5237A non-negative floating point number which specifies spatial luma strength. 5238It defaults to 4.0. 5239 5240@item chroma_spatial 5241A non-negative floating point number which specifies spatial chroma strength. 5242It defaults to 3.0*@var{luma_spatial}/4.0. 5243 5244@item luma_tmp 5245A floating point number which specifies luma temporal strength. It defaults to 52466.0*@var{luma_spatial}/4.0. 5247 5248@item chroma_tmp 5249A floating point number which specifies chroma temporal strength. It defaults to 5250@var{luma_tmp}*@var{chroma_spatial}/@var{luma_spatial}. 5251@end table 5252 5253@section hqx 5254 5255Apply a high-quality magnification filter designed for pixel art. This filter 5256was originally created by Maxim Stepin. 5257 5258It accepts the following option: 5259 5260@table @option 5261@item n 5262Set the scaling dimension: @code{2} for @code{hq2x}, @code{3} for 5263@code{hq3x} and @code{4} for @code{hq4x}. 5264Default is @code{3}. 5265@end table 5266 5267@section hue 5268 5269Modify the hue and/or the saturation of the input. 5270 5271It accepts the following parameters: 5272 5273@table @option 5274@item h 5275Specify the hue angle as a number of degrees. It accepts an expression, 5276and defaults to "0". 5277 5278@item s 5279Specify the saturation in the [-10,10] range. It accepts an expression and 5280defaults to "1". 5281 5282@item H 5283Specify the hue angle as a number of radians. It accepts an 5284expression, and defaults to "0". 5285 5286@item b 5287Specify the brightness in the [-10,10] range. It accepts an expression and 5288defaults to "0". 5289@end table 5290 5291@option{h} and @option{H} are mutually exclusive, and can't be 5292specified at the same time. 5293 5294The @option{b}, @option{h}, @option{H} and @option{s} option values are 5295expressions containing the following constants: 5296 5297@table @option 5298@item n 5299frame count of the input frame starting from 0 5300 5301@item pts 5302presentation timestamp of the input frame expressed in time base units 5303 5304@item r 5305frame rate of the input video, NAN if the input frame rate is unknown 5306 5307@item t 5308timestamp expressed in seconds, NAN if the input timestamp is unknown 5309 5310@item tb 5311time base of the input video 5312@end table 5313 5314@subsection Examples 5315 5316@itemize 5317@item 5318Set the hue to 90 degrees and the saturation to 1.0: 5319@example 5320hue=h=90:s=1 5321@end example 5322 5323@item 5324Same command but expressing the hue in radians: 5325@example 5326hue=H=PI/2:s=1 5327@end example 5328 5329@item 5330Rotate hue and make the saturation swing between 0 5331and 2 over a period of 1 second: 5332@example 5333hue="H=2*PI*t: s=sin(2*PI*t)+1" 5334@end example 5335 5336@item 5337Apply a 3 seconds saturation fade-in effect starting at 0: 5338@example 5339hue="s=min(t/3\,1)" 5340@end example 5341 5342The general fade-in expression can be written as: 5343@example 5344hue="s=min(0\, max((t-START)/DURATION\, 1))" 5345@end example 5346 5347@item 5348Apply a 3 seconds saturation fade-out effect starting at 5 seconds: 5349@example 5350hue="s=max(0\, min(1\, (8-t)/3))" 5351@end example 5352 5353The general fade-out expression can be written as: 5354@example 5355hue="s=max(0\, min(1\, (START+DURATION-t)/DURATION))" 5356@end example 5357 5358@end itemize 5359 5360@subsection Commands 5361 5362This filter supports the following commands: 5363@table @option 5364@item b 5365@item s 5366@item h 5367@item H 5368Modify the hue and/or the saturation and/or brightness of the input video. 5369The command accepts the same syntax of the corresponding option. 5370 5371If the specified expression is not valid, it is kept at its current 5372value. 5373@end table 5374 5375@section idet 5376 5377Detect video interlacing type. 5378 5379This filter tries to detect if the input is interlaced or progressive, 5380top or bottom field first. 5381 5382The filter accepts the following options: 5383 5384@table @option 5385@item intl_thres 5386Set interlacing threshold. 5387@item prog_thres 5388Set progressive threshold. 5389@end table 5390 5391@section il 5392 5393Deinterleave or interleave fields. 5394 5395This filter allows one to process interlaced images fields without 5396deinterlacing them. Deinterleaving splits the input frame into 2 5397fields (so called half pictures). Odd lines are moved to the top 5398half of the output image, even lines to the bottom half. 5399You can process (filter) them independently and then re-interleave them. 5400 5401The filter accepts the following options: 5402 5403@table @option 5404@item luma_mode, l 5405@item chroma_mode, c 5406@item alpha_mode, a 5407Available values for @var{luma_mode}, @var{chroma_mode} and 5408@var{alpha_mode} are: 5409 5410@table @samp 5411@item none 5412Do nothing. 5413 5414@item deinterleave, d 5415Deinterleave fields, placing one above the other. 5416 5417@item interleave, i 5418Interleave fields. Reverse the effect of deinterleaving. 5419@end table 5420Default value is @code{none}. 5421 5422@item luma_swap, ls 5423@item chroma_swap, cs 5424@item alpha_swap, as 5425Swap luma/chroma/alpha fields. Exchange even & odd lines. Default value is @code{0}. 5426@end table 5427 5428@section interlace 5429 5430Simple interlacing filter from progressive contents. This interleaves upper (or 5431lower) lines from odd frames with lower (or upper) lines from even frames, 5432halving the frame rate and preserving image height. A vertical lowpass filter 5433is always applied in order to avoid twitter effects and reduce moir�� patterns. 5434 5435@example 5436 Original Original New Frame 5437 Frame 'j' Frame 'j+1' (tff) 5438 ========== =========== ================== 5439 Line 0 --------------------> Frame 'j' Line 0 5440 Line 1 Line 1 ----> Frame 'j+1' Line 1 5441 Line 2 ---------------------> Frame 'j' Line 2 5442 Line 3 Line 3 ----> Frame 'j+1' Line 3 5443 ... ... ... 5444New Frame + 1 will be generated by Frame 'j+2' and Frame 'j+3' and so on 5445@end example 5446 5447It accepts the following optional parameters: 5448 5449@table @option 5450@item scan 5451This determines whether the interlaced frame is taken from the even 5452(tff - default) or odd (bff) lines of the progressive frame. 5453@end table 5454 5455@section kerndeint 5456 5457Deinterlace input video by applying Donald Graft's adaptive kernel 5458deinterling. Work on interlaced parts of a video to produce 5459progressive frames. 5460 5461The description of the accepted parameters follows. 5462 5463@table @option 5464@item thresh 5465Set the threshold which affects the filter's tolerance when 5466determining if a pixel line must be processed. It must be an integer 5467in the range [0,255] and defaults to 10. A value of 0 will result in 5468applying the process on every pixels. 5469 5470@item map 5471Paint pixels exceeding the threshold value to white if set to 1. 5472Default is 0. 5473 5474@item order 5475Set the fields order. Swap fields if set to 1, leave fields alone if 54760. Default is 0. 5477 5478@item sharp 5479Enable additional sharpening if set to 1. Default is 0. 5480 5481@item twoway 5482Enable twoway sharpening if set to 1. Default is 0. 5483@end table 5484 5485@subsection Examples 5486 5487@itemize 5488@item 5489Apply default values: 5490@example 5491kerndeint=thresh=10:map=0:order=0:sharp=0:twoway=0 5492@end example 5493 5494@item 5495Enable additional sharpening: 5496@example 5497kerndeint=sharp=1 5498@end example 5499 5500@item 5501Paint processed pixels in white: 5502@example 5503kerndeint=map=1 5504@end example 5505@end itemize 5506 5507@anchor{lut3d} 5508@section lut3d 5509 5510Apply a 3D LUT to an input video. 5511 5512The filter accepts the following options: 5513 5514@table @option 5515@item file 5516Set the 3D LUT file name. 5517 5518Currently supported formats: 5519@table @samp 5520@item 3dl 5521AfterEffects 5522@item cube 5523Iridas 5524@item dat 5525DaVinci 5526@item m3d 5527Pandora 5528@end table 5529@item interp 5530Select interpolation mode. 5531 5532Available values are: 5533 5534@table @samp 5535@item nearest 5536Use values from the nearest defined point. 5537@item trilinear 5538Interpolate values using the 8 points defining a cube. 5539@item tetrahedral 5540Interpolate values using a tetrahedron. 5541@end table 5542@end table 5543 5544@section lut, lutrgb, lutyuv 5545 5546Compute a look-up table for binding each pixel component input value 5547to an output value, and apply it to the input video. 5548 5549@var{lutyuv} applies a lookup table to a YUV input video, @var{lutrgb} 5550to an RGB input video. 5551 5552These filters accept the following parameters: 5553@table @option 5554@item c0 5555set first pixel component expression 5556@item c1 5557set second pixel component expression 5558@item c2 5559set third pixel component expression 5560@item c3 5561set fourth pixel component expression, corresponds to the alpha component 5562 5563@item r 5564set red component expression 5565@item g 5566set green component expression 5567@item b 5568set blue component expression 5569@item a 5570alpha component expression 5571 5572@item y 5573set Y/luminance component expression 5574@item u 5575set U/Cb component expression 5576@item v 5577set V/Cr component expression 5578@end table 5579 5580Each of them specifies the expression to use for computing the lookup table for 5581the corresponding pixel component values. 5582 5583The exact component associated to each of the @var{c*} options depends on the 5584format in input. 5585 5586The @var{lut} filter requires either YUV or RGB pixel formats in input, 5587@var{lutrgb} requires RGB pixel formats in input, and @var{lutyuv} requires YUV. 5588 5589The expressions can contain the following constants and functions: 5590 5591@table @option 5592@item w 5593@item h 5594The input width and height. 5595 5596@item val 5597The input value for the pixel component. 5598 5599@item clipval 5600The input value, clipped to the @var{minval}-@var{maxval} range. 5601 5602@item maxval 5603The maximum value for the pixel component. 5604 5605@item minval 5606The minimum value for the pixel component. 5607 5608@item negval 5609The negated value for the pixel component value, clipped to the 5610@var{minval}-@var{maxval} range; it corresponds to the expression 5611"maxval-clipval+minval". 5612 5613@item clip(val) 5614The computed value in @var{val}, clipped to the 5615@var{minval}-@var{maxval} range. 5616 5617@item gammaval(gamma) 5618The computed gamma correction value of the pixel component value, 5619clipped to the @var{minval}-@var{maxval} range. It corresponds to the 5620expression 5621"pow((clipval-minval)/(maxval-minval)\,@var{gamma})*(maxval-minval)+minval" 5622 5623@end table 5624 5625All expressions default to "val". 5626 5627@subsection Examples 5628 5629@itemize 5630@item 5631Negate input video: 5632@example 5633lutrgb="r=maxval+minval-val:g=maxval+minval-val:b=maxval+minval-val" 5634lutyuv="y=maxval+minval-val:u=maxval+minval-val:v=maxval+minval-val" 5635@end example 5636 5637The above is the same as: 5638@example 5639lutrgb="r=negval:g=negval:b=negval" 5640lutyuv="y=negval:u=negval:v=negval" 5641@end example 5642 5643@item 5644Negate luminance: 5645@example 5646lutyuv=y=negval 5647@end example 5648 5649@item 5650Remove chroma components, turning the video into a graytone image: 5651@example 5652lutyuv="u=128:v=128" 5653@end example 5654 5655@item 5656Apply a luma burning effect: 5657@example 5658lutyuv="y=2*val" 5659@end example 5660 5661@item 5662Remove green and blue components: 5663@example 5664lutrgb="g=0:b=0" 5665@end example 5666 5667@item 5668Set a constant alpha channel value on input: 5669@example 5670format=rgba,lutrgb=a="maxval-minval/2" 5671@end example 5672 5673@item 5674Correct luminance gamma by a factor of 0.5: 5675@example 5676lutyuv=y=gammaval(0.5) 5677@end example 5678 5679@item 5680Discard least significant bits of luma: 5681@example 5682lutyuv=y='bitand(val, 128+64+32)' 5683@end example 5684@end itemize 5685 5686@section mergeplanes 5687 5688Merge color channel components from several video streams. 5689 5690The filter accepts up to 4 input streams, and merge selected input 5691planes to the output video. 5692 5693This filter accepts the following options: 5694@table @option 5695@item mapping 5696Set input to output plane mapping. Default is @code{0}. 5697 5698The mappings is specified as a bitmap. It should be specified as a 5699hexadecimal number in the form 0xAa[Bb[Cc[Dd]]]. 'Aa' describes the 5700mapping for the first plane of the output stream. 'A' sets the number of 5701the input stream to use (from 0 to 3), and 'a' the plane number of the 5702corresponding input to use (from 0 to 3). The rest of the mappings is 5703similar, 'Bb' describes the mapping for the output stream second 5704plane, 'Cc' describes the mapping for the output stream third plane and 5705'Dd' describes the mapping for the output stream fourth plane. 5706 5707@item format 5708Set output pixel format. Default is @code{yuva444p}. 5709@end table 5710 5711@subsection Examples 5712 5713@itemize 5714@item 5715Merge three gray video streams of same width and height into single video stream: 5716@example 5717[a0][a1][a2]mergeplanes=0x001020:yuv444p 5718@end example 5719 5720@item 5721Merge 1st yuv444p stream and 2nd gray video stream into yuva444p video stream: 5722@example 5723[a0][a1]mergeplanes=0x00010210:yuva444p 5724@end example 5725 5726@item 5727Swap Y and A plane in yuva444p stream: 5728@example 5729format=yuva444p,mergeplanes=0x03010200:yuva444p 5730@end example 5731 5732@item 5733Swap U and V plane in yuv420p stream: 5734@example 5735format=yuv420p,mergeplanes=0x000201:yuv420p 5736@end example 5737 5738@item 5739Cast a rgb24 clip to yuv444p: 5740@example 5741format=rgb24,mergeplanes=0x000102:yuv444p 5742@end example 5743@end itemize 5744 5745@section mcdeint 5746 5747Apply motion-compensation deinterlacing. 5748 5749It needs one field per frame as input and must thus be used together 5750with yadif=1/3 or equivalent. 5751 5752This filter accepts the following options: 5753@table @option 5754@item mode 5755Set the deinterlacing mode. 5756 5757It accepts one of the following values: 5758@table @samp 5759@item fast 5760@item medium 5761@item slow 5762use iterative motion estimation 5763@item extra_slow 5764like @samp{slow}, but use multiple reference frames. 5765@end table 5766Default value is @samp{fast}. 5767 5768@item parity 5769Set the picture field parity assumed for the input video. It must be 5770one of the following values: 5771 5772@table @samp 5773@item 0, tff 5774assume top field first 5775@item 1, bff 5776assume bottom field first 5777@end table 5778 5779Default value is @samp{bff}. 5780 5781@item qp 5782Set per-block quantization parameter (QP) used by the internal 5783encoder. 5784 5785Higher values should result in a smoother motion vector field but less 5786optimal individual vectors. Default value is 1. 5787@end table 5788 5789@section mp 5790 5791Apply an MPlayer filter to the input video. 5792 5793This filter provides a wrapper around some of the filters of 5794MPlayer/MEncoder. 5795 5796This wrapper is considered experimental. Some of the wrapped filters 5797may not work properly and we may drop support for them, as they will 5798be implemented natively into FFmpeg. Thus you should avoid 5799depending on them when writing portable scripts. 5800 5801The filter accepts the parameters: 5802@var{filter_name}[:=]@var{filter_params} 5803 5804@var{filter_name} is the name of a supported MPlayer filter, 5805@var{filter_params} is a string containing the parameters accepted by 5806the named filter. 5807 5808The list of the currently supported filters follows: 5809@table @var 5810@item eq2 5811@item eq 5812@item fspp 5813@item ilpack 5814@item pp7 5815@item softpulldown 5816@item uspp 5817@end table 5818 5819The parameter syntax and behavior for the listed filters are the same 5820of the corresponding MPlayer filters. For detailed instructions check 5821the "VIDEO FILTERS" section in the MPlayer manual. 5822 5823@subsection Examples 5824 5825@itemize 5826@item 5827Adjust gamma, brightness, contrast: 5828@example 5829mp=eq2=1.0:2:0.5 5830@end example 5831@end itemize 5832 5833See also mplayer(1), @url{http://www.mplayerhq.hu/}. 5834 5835@section mpdecimate 5836 5837Drop frames that do not differ greatly from the previous frame in 5838order to reduce frame rate. 5839 5840The main use of this filter is for very-low-bitrate encoding 5841(e.g. streaming over dialup modem), but it could in theory be used for 5842fixing movies that were inverse-telecined incorrectly. 5843 5844A description of the accepted options follows. 5845 5846@table @option 5847@item max 5848Set the maximum number of consecutive frames which can be dropped (if 5849positive), or the minimum interval between dropped frames (if 5850negative). If the value is 0, the frame is dropped unregarding the 5851number of previous sequentially dropped frames. 5852 5853Default value is 0. 5854 5855@item hi 5856@item lo 5857@item frac 5858Set the dropping threshold values. 5859 5860Values for @option{hi} and @option{lo} are for 8x8 pixel blocks and 5861represent actual pixel value differences, so a threshold of 64 5862corresponds to 1 unit of difference for each pixel, or the same spread 5863out differently over the block. 5864 5865A frame is a candidate for dropping if no 8x8 blocks differ by more 5866than a threshold of @option{hi}, and if no more than @option{frac} blocks (1 5867meaning the whole image) differ by more than a threshold of @option{lo}. 5868 5869Default value for @option{hi} is 64*12, default value for @option{lo} is 587064*5, and default value for @option{frac} is 0.33. 5871@end table 5872 5873 5874@section negate 5875 5876Negate input video. 5877 5878It accepts an integer in input; if non-zero it negates the 5879alpha component (if available). The default value in input is 0. 5880 5881@section noformat 5882 5883Force libavfilter not to use any of the specified pixel formats for the 5884input to the next filter. 5885 5886It accepts the following parameters: 5887@table @option 5888 5889@item pix_fmts 5890A '|'-separated list of pixel format names, such as 5891apix_fmts=yuv420p|monow|rgb24". 5892 5893@end table 5894 5895@subsection Examples 5896 5897@itemize 5898@item 5899Force libavfilter to use a format different from @var{yuv420p} for the 5900input to the vflip filter: 5901@example 5902noformat=pix_fmts=yuv420p,vflip 5903@end example 5904 5905@item 5906Convert the input video to any of the formats not contained in the list: 5907@example 5908noformat=yuv420p|yuv444p|yuv410p 5909@end example 5910@end itemize 5911 5912@section noise 5913 5914Add noise on video input frame. 5915 5916The filter accepts the following options: 5917 5918@table @option 5919@item all_seed 5920@item c0_seed 5921@item c1_seed 5922@item c2_seed 5923@item c3_seed 5924Set noise seed for specific pixel component or all pixel components in case 5925of @var{all_seed}. Default value is @code{123457}. 5926 5927@item all_strength, alls 5928@item c0_strength, c0s 5929@item c1_strength, c1s 5930@item c2_strength, c2s 5931@item c3_strength, c3s 5932Set noise strength for specific pixel component or all pixel components in case 5933@var{all_strength}. Default value is @code{0}. Allowed range is [0, 100]. 5934 5935@item all_flags, allf 5936@item c0_flags, c0f 5937@item c1_flags, c1f 5938@item c2_flags, c2f 5939@item c3_flags, c3f 5940Set pixel component flags or set flags for all components if @var{all_flags}. 5941Available values for component flags are: 5942@table @samp 5943@item a 5944averaged temporal noise (smoother) 5945@item p 5946mix random noise with a (semi)regular pattern 5947@item t 5948temporal noise (noise pattern changes between frames) 5949@item u 5950uniform noise (gaussian otherwise) 5951@end table 5952@end table 5953 5954@subsection Examples 5955 5956Add temporal and uniform noise to input video: 5957@example 5958noise=alls=20:allf=t+u 5959@end example 5960 5961@section null 5962 5963Pass the video source unchanged to the output. 5964 5965@section ocv 5966 5967Apply a video transform using libopencv. 5968 5969To enable this filter, install the libopencv library and headers and 5970configure FFmpeg with @code{--enable-libopencv}. 5971 5972It accepts the following parameters: 5973 5974@table @option 5975 5976@item filter_name 5977The name of the libopencv filter to apply. 5978 5979@item filter_params 5980The parameters to pass to the libopencv filter. If not specified, the default 5981values are assumed. 5982 5983@end table 5984 5985Refer to the official libopencv documentation for more precise 5986information: 5987@url{http://opencv.willowgarage.com/documentation/c/image_filtering.html} 5988 5989Several libopencv filters are supported; see the following subsections. 5990 5991@anchor{dilate} 5992@subsection dilate 5993 5994Dilate an image by using a specific structuring element. 5995It corresponds to the libopencv function @code{cvDilate}. 5996 5997It accepts the parameters: @var{struct_el}|@var{nb_iterations}. 5998 5999@var{struct_el} represents a structuring element, and has the syntax: 6000@var{cols}x@var{rows}+@var{anchor_x}x@var{anchor_y}/@var{shape} 6001 6002@var{cols} and @var{rows} represent the number of columns and rows of 6003the structuring element, @var{anchor_x} and @var{anchor_y} the anchor 6004point, and @var{shape} the shape for the structuring element. @var{shape} 6005must be "rect", "cross", "ellipse", or "custom". 6006 6007If the value for @var{shape} is "custom", it must be followed by a 6008string of the form "=@var{filename}". The file with name 6009@var{filename} is assumed to represent a binary image, with each 6010printable character corresponding to a bright pixel. When a custom 6011@var{shape} is used, @var{cols} and @var{rows} are ignored, the number 6012or columns and rows of the read file are assumed instead. 6013 6014The default value for @var{struct_el} is "3x3+0x0/rect". 6015 6016@var{nb_iterations} specifies the number of times the transform is 6017applied to the image, and defaults to 1. 6018 6019Some examples: 6020@example 6021# Use the default values 6022ocv=dilate 6023 6024# Dilate using a structuring element with a 5x5 cross, iterating two times 6025ocv=filter_name=dilate:filter_params=5x5+2x2/cross|2 6026 6027# Read the shape from the file diamond.shape, iterating two times. 6028# The file diamond.shape may contain a pattern of characters like this 6029# * 6030# *** 6031# ***** 6032# *** 6033# * 6034# The specified columns and rows are ignored 6035# but the anchor point coordinates are not 6036ocv=dilate:0x0+2x2/custom=diamond.shape|2 6037@end example 6038 6039@subsection erode 6040 6041Erode an image by using a specific structuring element. 6042It corresponds to the libopencv function @code{cvErode}. 6043 6044It accepts the parameters: @var{struct_el}:@var{nb_iterations}, 6045with the same syntax and semantics as the @ref{dilate} filter. 6046 6047@subsection smooth 6048 6049Smooth the input video. 6050 6051The filter takes the following parameters: 6052@var{type}|@var{param1}|@var{param2}|@var{param3}|@var{param4}. 6053 6054@var{type} is the type of smooth filter to apply, and must be one of 6055the following values: "blur", "blur_no_scale", "median", "gaussian", 6056or "bilateral". The default value is "gaussian". 6057 6058The meaning of @var{param1}, @var{param2}, @var{param3}, and @var{param4} 6059depend on the smooth type. @var{param1} and 6060@var{param2} accept integer positive values or 0. @var{param3} and 6061@var{param4} accept floating point values. 6062 6063The default value for @var{param1} is 3. The default value for the 6064other parameters is 0. 6065 6066These parameters correspond to the parameters assigned to the 6067libopencv function @code{cvSmooth}. 6068 6069@anchor{overlay} 6070@section overlay 6071 6072Overlay one video on top of another. 6073 6074It takes two inputs and has one output. The first input is the "main" 6075video on which the second input is overlayed. 6076 6077It accepts the following parameters: 6078 6079A description of the accepted options follows. 6080 6081@table @option 6082@item x 6083@item y 6084Set the expression for the x and y coordinates of the overlayed video 6085on the main video. Default value is "0" for both expressions. In case 6086the expression is invalid, it is set to a huge value (meaning that the 6087overlay will not be displayed within the output visible area). 6088 6089@item eof_action 6090The action to take when EOF is encountered on the secondary input; it accepts 6091one of the following values: 6092 6093@table @option 6094@item repeat 6095Repeat the last frame (the default). 6096@item endall 6097End both streams. 6098@item pass 6099Pass the main input through. 6100@end table 6101 6102@item eval 6103Set when the expressions for @option{x}, and @option{y} are evaluated. 6104 6105It accepts the following values: 6106@table @samp 6107@item init 6108only evaluate expressions once during the filter initialization or 6109when a command is processed 6110 6111@item frame 6112evaluate expressions for each incoming frame 6113@end table 6114 6115Default value is @samp{frame}. 6116 6117@item shortest 6118If set to 1, force the output to terminate when the shortest input 6119terminates. Default value is 0. 6120 6121@item format 6122Set the format for the output video. 6123 6124It accepts the following values: 6125@table @samp 6126@item yuv420 6127force YUV420 output 6128 6129@item yuv422 6130force YUV422 output 6131 6132@item yuv444 6133force YUV444 output 6134 6135@item rgb 6136force RGB output 6137@end table 6138 6139Default value is @samp{yuv420}. 6140 6141@item rgb @emph{(deprecated)} 6142If set to 1, force the filter to accept inputs in the RGB 6143color space. Default value is 0. This option is deprecated, use 6144@option{format} instead. 6145 6146@item repeatlast 6147If set to 1, force the filter to draw the last overlay frame over the 6148main input until the end of the stream. A value of 0 disables this 6149behavior. Default value is 1. 6150@end table 6151 6152The @option{x}, and @option{y} expressions can contain the following 6153parameters. 6154 6155@table @option 6156@item main_w, W 6157@item main_h, H 6158The main input width and height. 6159 6160@item overlay_w, w 6161@item overlay_h, h 6162The overlay input width and height. 6163 6164@item x 6165@item y 6166The computed values for @var{x} and @var{y}. They are evaluated for 6167each new frame. 6168 6169@item hsub 6170@item vsub 6171horizontal and vertical chroma subsample values of the output 6172format. For example for the pixel format "yuv422p" @var{hsub} is 2 and 6173@var{vsub} is 1. 6174 6175@item n 6176the number of input frame, starting from 0 6177 6178@item pos 6179the position in the file of the input frame, NAN if unknown 6180 6181@item t 6182The timestamp, expressed in seconds. It's NAN if the input timestamp is unknown. 6183 6184@end table 6185 6186Note that the @var{n}, @var{pos}, @var{t} variables are available only 6187when evaluation is done @emph{per frame}, and will evaluate to NAN 6188when @option{eval} is set to @samp{init}. 6189 6190Be aware that frames are taken from each input video in timestamp 6191order, hence, if their initial timestamps differ, it is a good idea 6192to pass the two inputs through a @var{setpts=PTS-STARTPTS} filter to 6193have them begin in the same zero timestamp, as the example for 6194the @var{movie} filter does. 6195 6196You can chain together more overlays but you should test the 6197efficiency of such approach. 6198 6199@subsection Commands 6200 6201This filter supports the following commands: 6202@table @option 6203@item x 6204@item y 6205Modify the x and y of the overlay input. 6206The command accepts the same syntax of the corresponding option. 6207 6208If the specified expression is not valid, it is kept at its current 6209value. 6210@end table 6211 6212@subsection Examples 6213 6214@itemize 6215@item 6216Draw the overlay at 10 pixels from the bottom right corner of the main 6217video: 6218@example 6219overlay=main_w-overlay_w-10:main_h-overlay_h-10 6220@end example 6221 6222Using named options the example above becomes: 6223@example 6224overlay=x=main_w-overlay_w-10:y=main_h-overlay_h-10 6225@end example 6226 6227@item 6228Insert a transparent PNG logo in the bottom left corner of the input, 6229using the @command{ffmpeg} tool with the @code{-filter_complex} option: 6230@example 6231ffmpeg -i input -i logo -filter_complex 'overlay=10:main_h-overlay_h-10' output 6232@end example 6233 6234@item 6235Insert 2 different transparent PNG logos (second logo on bottom 6236right corner) using the @command{ffmpeg} tool: 6237@example 6238ffmpeg -i input -i logo1 -i logo2 -filter_complex 'overlay=x=10:y=H-h-10,overlay=x=W-w-10:y=H-h-10' output 6239@end example 6240 6241@item 6242Add a transparent color layer on top of the main video; @code{WxH} 6243must specify the size of the main input to the overlay filter: 6244@example 6245color=color=red@@.3:size=WxH [over]; [in][over] overlay [out] 6246@end example 6247 6248@item 6249Play an original video and a filtered version (here with the deshake 6250filter) side by side using the @command{ffplay} tool: 6251@example 6252ffplay input.avi -vf 'split[a][b]; [a]pad=iw*2:ih[src]; [b]deshake[filt]; [src][filt]overlay=w' 6253@end example 6254 6255The above command is the same as: 6256@example 6257ffplay input.avi -vf 'split[b], pad=iw*2[src], [b]deshake, [src]overlay=w' 6258@end example 6259 6260@item 6261Make a sliding overlay appearing from the left to the right top part of the 6262screen starting since time 2: 6263@example 6264overlay=x='if(gte(t,2), -w+(t-2)*20, NAN)':y=0 6265@end example 6266 6267@item 6268Compose output by putting two input videos side to side: 6269@example 6270ffmpeg -i left.avi -i right.avi -filter_complex " 6271nullsrc=size=200x100 [background]; 6272[0:v] setpts=PTS-STARTPTS, scale=100x100 [left]; 6273[1:v] setpts=PTS-STARTPTS, scale=100x100 [right]; 6274[background][left] overlay=shortest=1 [background+left]; 6275[background+left][right] overlay=shortest=1:x=100 [left+right] 6276" 6277@end example 6278 6279@item 6280Mask 10-20 seconds of a video by applying the delogo filter to a section 6281@example 6282ffmpeg -i test.avi -codec:v:0 wmv2 -ar 11025 -b:v 9000k 6283-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]' 6284masked.avi 6285@end example 6286 6287@item 6288Chain several overlays in cascade: 6289@example 6290nullsrc=s=200x200 [bg]; 6291testsrc=s=100x100, split=4 [in0][in1][in2][in3]; 6292[in0] lutrgb=r=0, [bg] overlay=0:0 [mid0]; 6293[in1] lutrgb=g=0, [mid0] overlay=100:0 [mid1]; 6294[in2] lutrgb=b=0, [mid1] overlay=0:100 [mid2]; 6295[in3] null, [mid2] overlay=100:100 [out0] 6296@end example 6297 6298@end itemize 6299 6300@section owdenoise 6301 6302Apply Overcomplete Wavelet denoiser. 6303 6304The filter accepts the following options: 6305 6306@table @option 6307@item depth 6308Set depth. 6309 6310Larger depth values will denoise lower frequency components more, but 6311slow down filtering. 6312 6313Must be an int in the range 8-16, default is @code{8}. 6314 6315@item luma_strength, ls 6316Set luma strength. 6317 6318Must be a double value in the range 0-1000, default is @code{1.0}. 6319 6320@item chroma_strength, cs 6321Set chroma strength. 6322 6323Must be a double value in the range 0-1000, default is @code{1.0}. 6324@end table 6325 6326@section pad 6327 6328Add paddings to the input image, and place the original input at the 6329provided @var{x}, @var{y} coordinates. 6330 6331It accepts the following parameters: 6332 6333@table @option 6334@item width, w 6335@item height, h 6336Specify an expression for the size of the output image with the 6337paddings added. If the value for @var{width} or @var{height} is 0, the 6338corresponding input size is used for the output. 6339 6340The @var{width} expression can reference the value set by the 6341@var{height} expression, and vice versa. 6342 6343The default value of @var{width} and @var{height} is 0. 6344 6345@item x 6346@item y 6347Specify the offsets to place the input image at within the padded area, 6348with respect to the top/left border of the output image. 6349 6350The @var{x} expression can reference the value set by the @var{y} 6351expression, and vice versa. 6352 6353The default value of @var{x} and @var{y} is 0. 6354 6355@item color 6356Specify the color of the padded area. For the syntax of this option, 6357check the "Color" section in the ffmpeg-utils manual. 6358 6359The default value of @var{color} is "black". 6360@end table 6361 6362The value for the @var{width}, @var{height}, @var{x}, and @var{y} 6363options are expressions containing the following constants: 6364 6365@table @option 6366@item in_w 6367@item in_h 6368The input video width and height. 6369 6370@item iw 6371@item ih 6372These are the same as @var{in_w} and @var{in_h}. 6373 6374@item out_w 6375@item out_h 6376The output width and height (the size of the padded area), as 6377specified by the @var{width} and @var{height} expressions. 6378 6379@item ow 6380@item oh 6381These are the same as @var{out_w} and @var{out_h}. 6382 6383@item x 6384@item y 6385The x and y offsets as specified by the @var{x} and @var{y} 6386expressions, or NAN if not yet specified. 6387 6388@item a 6389same as @var{iw} / @var{ih} 6390 6391@item sar 6392input sample aspect ratio 6393 6394@item dar 6395input display aspect ratio, it is the same as (@var{iw} / @var{ih}) * @var{sar} 6396 6397@item hsub 6398@item vsub 6399The horizontal and vertical chroma subsample values. For example for the 6400pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1. 6401@end table 6402 6403@subsection Examples 6404 6405@itemize 6406@item 6407Add paddings with the color "violet" to the input video. The output video 6408size is 640x480, and the top-left corner of the input video is placed at 6409column 0, row 40 6410@example 6411pad=640:480:0:40:violet 6412@end example 6413 6414The example above is equivalent to the following command: 6415@example 6416pad=width=640:height=480:x=0:y=40:color=violet 6417@end example 6418 6419@item 6420Pad the input to get an output with dimensions increased by 3/2, 6421and put the input video at the center of the padded area: 6422@example 6423pad="3/2*iw:3/2*ih:(ow-iw)/2:(oh-ih)/2" 6424@end example 6425 6426@item 6427Pad the input to get a squared output with size equal to the maximum 6428value between the input width and height, and put the input video at 6429the center of the padded area: 6430@example 6431pad="max(iw\,ih):ow:(ow-iw)/2:(oh-ih)/2" 6432@end example 6433 6434@item 6435Pad the input to get a final w/h ratio of 16:9: 6436@example 6437pad="ih*16/9:ih:(ow-iw)/2:(oh-ih)/2" 6438@end example 6439 6440@item 6441In case of anamorphic video, in order to set the output display aspect 6442correctly, it is necessary to use @var{sar} in the expression, 6443according to the relation: 6444@example 6445(ih * X / ih) * sar = output_dar 6446X = output_dar / sar 6447@end example 6448 6449Thus the previous example needs to be modified to: 6450@example 6451pad="ih*16/9/sar:ih:(ow-iw)/2:(oh-ih)/2" 6452@end example 6453 6454@item 6455Double the output size and put the input video in the bottom-right 6456corner of the output padded area: 6457@example 6458pad="2*iw:2*ih:ow-iw:oh-ih" 6459@end example 6460@end itemize 6461 6462@section perspective 6463 6464Correct perspective of video not recorded perpendicular to the screen. 6465 6466A description of the accepted parameters follows. 6467 6468@table @option 6469@item x0 6470@item y0 6471@item x1 6472@item y1 6473@item x2 6474@item y2 6475@item x3 6476@item y3 6477Set coordinates expression for top left, top right, bottom left and bottom right corners. 6478Default values are @code{0:0:W:0:0:H:W:H} with which perspective will remain unchanged. 6479 6480The expressions can use the following variables: 6481 6482@table @option 6483@item W 6484@item H 6485the width and height of video frame. 6486@end table 6487 6488@item interpolation 6489Set interpolation for perspective correction. 6490 6491It accepts the following values: 6492@table @samp 6493@item linear 6494@item cubic 6495@end table 6496 6497Default value is @samp{linear}. 6498@end table 6499 6500@section phase 6501 6502Delay interlaced video by one field time so that the field order changes. 6503 6504The intended use is to fix PAL movies that have been captured with the 6505opposite field order to the film-to-video transfer. 6506 6507A description of the accepted parameters follows. 6508 6509@table @option 6510@item mode 6511Set phase mode. 6512 6513It accepts the following values: 6514@table @samp 6515@item t 6516Capture field order top-first, transfer bottom-first. 6517Filter will delay the bottom field. 6518 6519@item b 6520Capture field order bottom-first, transfer top-first. 6521Filter will delay the top field. 6522 6523@item p 6524Capture and transfer with the same field order. This mode only exists 6525for the documentation of the other options to refer to, but if you 6526actually select it, the filter will faithfully do nothing. 6527 6528@item a 6529Capture field order determined automatically by field flags, transfer 6530opposite. 6531Filter selects among @samp{t} and @samp{b} modes on a frame by frame 6532basis using field flags. If no field information is available, 6533then this works just like @samp{u}. 6534 6535@item u 6536Capture unknown or varying, transfer opposite. 6537Filter selects among @samp{t} and @samp{b} on a frame by frame basis by 6538analyzing the images and selecting the alternative that produces best 6539match between the fields. 6540 6541@item T 6542Capture top-first, transfer unknown or varying. 6543Filter selects among @samp{t} and @samp{p} using image analysis. 6544 6545@item B 6546Capture bottom-first, transfer unknown or varying. 6547Filter selects among @samp{b} and @samp{p} using image analysis. 6548 6549@item A 6550Capture determined by field flags, transfer unknown or varying. 6551Filter selects among @samp{t}, @samp{b} and @samp{p} using field flags and 6552image analysis. If no field information is available, then this works just 6553like @samp{U}. This is the default mode. 6554 6555@item U 6556Both capture and transfer unknown or varying. 6557Filter selects among @samp{t}, @samp{b} and @samp{p} using image analysis only. 6558@end table 6559@end table 6560 6561@section pixdesctest 6562 6563Pixel format descriptor test filter, mainly useful for internal 6564testing. The output video should be equal to the input video. 6565 6566For example: 6567@example 6568format=monow, pixdesctest 6569@end example 6570 6571can be used to test the monowhite pixel format descriptor definition. 6572 6573@section pp 6574 6575Enable the specified chain of postprocessing subfilters using libpostproc. This 6576library should be automatically selected with a GPL build (@code{--enable-gpl}). 6577Subfilters must be separated by '/' and can be disabled by prepending a '-'. 6578Each subfilter and some options have a short and a long name that can be used 6579interchangeably, i.e. dr/dering are the same. 6580 6581The filters accept the following options: 6582 6583@table @option 6584@item subfilters 6585Set postprocessing subfilters string. 6586@end table 6587 6588All subfilters share common options to determine their scope: 6589 6590@table @option 6591@item a/autoq 6592Honor the quality commands for this subfilter. 6593 6594@item c/chrom 6595Do chrominance filtering, too (default). 6596 6597@item y/nochrom 6598Do luminance filtering only (no chrominance). 6599 6600@item n/noluma 6601Do chrominance filtering only (no luminance). 6602@end table 6603 6604These options can be appended after the subfilter name, separated by a '|'. 6605 6606Available subfilters are: 6607 6608@table @option 6609@item hb/hdeblock[|difference[|flatness]] 6610Horizontal deblocking filter 6611@table @option 6612@item difference 6613Difference factor where higher values mean more deblocking (default: @code{32}). 6614@item flatness 6615Flatness threshold where lower values mean more deblocking (default: @code{39}). 6616@end table 6617 6618@item vb/vdeblock[|difference[|flatness]] 6619Vertical deblocking filter 6620@table @option 6621@item difference 6622Difference factor where higher values mean more deblocking (default: @code{32}). 6623@item flatness 6624Flatness threshold where lower values mean more deblocking (default: @code{39}). 6625@end table 6626 6627@item ha/hadeblock[|difference[|flatness]] 6628Accurate horizontal deblocking filter 6629@table @option 6630@item difference 6631Difference factor where higher values mean more deblocking (default: @code{32}). 6632@item flatness 6633Flatness threshold where lower values mean more deblocking (default: @code{39}). 6634@end table 6635 6636@item va/vadeblock[|difference[|flatness]] 6637Accurate vertical deblocking filter 6638@table @option 6639@item difference 6640Difference factor where higher values mean more deblocking (default: @code{32}). 6641@item flatness 6642Flatness threshold where lower values mean more deblocking (default: @code{39}). 6643@end table 6644@end table 6645 6646The horizontal and vertical deblocking filters share the difference and 6647flatness values so you cannot set different horizontal and vertical 6648thresholds. 6649 6650@table @option 6651@item h1/x1hdeblock 6652Experimental horizontal deblocking filter 6653 6654@item v1/x1vdeblock 6655Experimental vertical deblocking filter 6656 6657@item dr/dering 6658Deringing filter 6659 6660@item tn/tmpnoise[|threshold1[|threshold2[|threshold3]]], temporal noise reducer 6661@table @option 6662@item threshold1 6663larger -> stronger filtering 6664@item threshold2 6665larger -> stronger filtering 6666@item threshold3 6667larger -> stronger filtering 6668@end table 6669 6670@item al/autolevels[:f/fullyrange], automatic brightness / contrast correction 6671@table @option 6672@item f/fullyrange 6673Stretch luminance to @code{0-255}. 6674@end table 6675 6676@item lb/linblenddeint 6677Linear blend deinterlacing filter that deinterlaces the given block by 6678filtering all lines with a @code{(1 2 1)} filter. 6679 6680@item li/linipoldeint 6681Linear interpolating deinterlacing filter that deinterlaces the given block by 6682linearly interpolating every second line. 6683 6684@item ci/cubicipoldeint 6685Cubic interpolating deinterlacing filter deinterlaces the given block by 6686cubically interpolating every second line. 6687 6688@item md/mediandeint 6689Median deinterlacing filter that deinterlaces the given block by applying a 6690median filter to every second line. 6691 6692@item fd/ffmpegdeint 6693FFmpeg deinterlacing filter that deinterlaces the given block by filtering every 6694second line with a @code{(-1 4 2 4 -1)} filter. 6695 6696@item l5/lowpass5 6697Vertically applied FIR lowpass deinterlacing filter that deinterlaces the given 6698block by filtering all lines with a @code{(-1 2 6 2 -1)} filter. 6699 6700@item fq/forceQuant[|quantizer] 6701Overrides the quantizer table from the input with the constant quantizer you 6702specify. 6703@table @option 6704@item quantizer 6705Quantizer to use 6706@end table 6707 6708@item de/default 6709Default pp filter combination (@code{hb|a,vb|a,dr|a}) 6710 6711@item fa/fast 6712Fast pp filter combination (@code{h1|a,v1|a,dr|a}) 6713 6714@item ac 6715High quality pp filter combination (@code{ha|a|128|7,va|a,dr|a}) 6716@end table 6717 6718@subsection Examples 6719 6720@itemize 6721@item 6722Apply horizontal and vertical deblocking, deringing and automatic 6723brightness/contrast: 6724@example 6725pp=hb/vb/dr/al 6726@end example 6727 6728@item 6729Apply default filters without brightness/contrast correction: 6730@example 6731pp=de/-al 6732@end example 6733 6734@item 6735Apply default filters and temporal denoiser: 6736@example 6737pp=default/tmpnoise|1|2|3 6738@end example 6739 6740@item 6741Apply deblocking on luminance only, and switch vertical deblocking on or off 6742automatically depending on available CPU time: 6743@example 6744pp=hb|y/vb|a 6745@end example 6746@end itemize 6747 6748@section psnr 6749 6750Obtain the average, maximum and minimum PSNR (Peak Signal to Noise 6751Ratio) between two input videos. 6752 6753This filter takes in input two input videos, the first input is 6754considered the "main" source and is passed unchanged to the 6755output. The second input is used as a "reference" video for computing 6756the PSNR. 6757 6758Both video inputs must have the same resolution and pixel format for 6759this filter to work correctly. Also it assumes that both inputs 6760have the same number of frames, which are compared one by one. 6761 6762The obtained average PSNR is printed through the logging system. 6763 6764The filter stores the accumulated MSE (mean squared error) of each 6765frame, and at the end of the processing it is averaged across all frames 6766equally, and the following formula is applied to obtain the PSNR: 6767 6768@example 6769PSNR = 10*log10(MAX^2/MSE) 6770@end example 6771 6772Where MAX is the average of the maximum values of each component of the 6773image. 6774 6775The description of the accepted parameters follows. 6776 6777@table @option 6778@item stats_file, f 6779If specified the filter will use the named file to save the PSNR of 6780each individual frame. 6781@end table 6782 6783The file printed if @var{stats_file} is selected, contains a sequence of 6784key/value pairs of the form @var{key}:@var{value} for each compared 6785couple of frames. 6786 6787A description of each shown parameter follows: 6788 6789@table @option 6790@item n 6791sequential number of the input frame, starting from 1 6792 6793@item mse_avg 6794Mean Square Error pixel-by-pixel average difference of the compared 6795frames, averaged over all the image components. 6796 6797@item mse_y, mse_u, mse_v, mse_r, mse_g, mse_g, mse_a 6798Mean Square Error pixel-by-pixel average difference of the compared 6799frames for the component specified by the suffix. 6800 6801@item psnr_y, psnr_u, psnr_v, psnr_r, psnr_g, psnr_b, psnr_a 6802Peak Signal to Noise ratio of the compared frames for the component 6803specified by the suffix. 6804@end table 6805 6806For example: 6807@example 6808movie=ref_movie.mpg, setpts=PTS-STARTPTS [main]; 6809[main][ref] psnr="stats_file=stats.log" [out] 6810@end example 6811 6812On this example the input file being processed is compared with the 6813reference file @file{ref_movie.mpg}. The PSNR of each individual frame 6814is stored in @file{stats.log}. 6815 6816@anchor{pullup} 6817@section pullup 6818 6819Pulldown reversal (inverse telecine) filter, capable of handling mixed 6820hard-telecine, 24000/1001 fps progressive, and 30000/1001 fps progressive 6821content. 6822 6823The pullup filter is designed to take advantage of future context in making 6824its decisions. This filter is stateless in the sense that it does not lock 6825onto a pattern to follow, but it instead looks forward to the following 6826fields in order to identify matches and rebuild progressive frames. 6827 6828To produce content with an even framerate, insert the fps filter after 6829pullup, use @code{fps=24000/1001} if the input frame rate is 29.97fps, 6830@code{fps=24} for 30fps and the (rare) telecined 25fps input. 6831 6832The filter accepts the following options: 6833 6834@table @option 6835@item jl 6836@item jr 6837@item jt 6838@item jb 6839These options set the amount of "junk" to ignore at the left, right, top, and 6840bottom of the image, respectively. Left and right are in units of 8 pixels, 6841while top and bottom are in units of 2 lines. 6842The default is 8 pixels on each side. 6843 6844@item sb 6845Set the strict breaks. Setting this option to 1 will reduce the chances of 6846filter generating an occasional mismatched frame, but it may also cause an 6847excessive number of frames to be dropped during high motion sequences. 6848Conversely, setting it to -1 will make filter match fields more easily. 6849This may help processing of video where there is slight blurring between 6850the fields, but may also cause there to be interlaced frames in the output. 6851Default value is @code{0}. 6852 6853@item mp 6854Set the metric plane to use. It accepts the following values: 6855@table @samp 6856@item l 6857Use luma plane. 6858 6859@item u 6860Use chroma blue plane. 6861 6862@item v 6863Use chroma red plane. 6864@end table 6865 6866This option may be set to use chroma plane instead of the default luma plane 6867for doing filter's computations. This may improve accuracy on very clean 6868source material, but more likely will decrease accuracy, especially if there 6869is chroma noise (rainbow effect) or any grayscale video. 6870The main purpose of setting @option{mp} to a chroma plane is to reduce CPU 6871load and make pullup usable in realtime on slow machines. 6872@end table 6873 6874For best results (without duplicated frames in the output file) it is 6875necessary to change the output frame rate. For example, to inverse 6876telecine NTSC input: 6877@example 6878ffmpeg -i input -vf pullup -r 24000/1001 ... 6879@end example 6880 6881@section removelogo 6882 6883Suppress a TV station logo, using an image file to determine which 6884pixels comprise the logo. It works by filling in the pixels that 6885comprise the logo with neighboring pixels. 6886 6887The filter accepts the following options: 6888 6889@table @option 6890@item filename, f 6891Set the filter bitmap file, which can be any image format supported by 6892libavformat. The width and height of the image file must match those of the 6893video stream being processed. 6894@end table 6895 6896Pixels in the provided bitmap image with a value of zero are not 6897considered part of the logo, non-zero pixels are considered part of 6898the logo. If you use white (255) for the logo and black (0) for the 6899rest, you will be safe. For making the filter bitmap, it is 6900recommended to take a screen capture of a black frame with the logo 6901visible, and then using a threshold filter followed by the erode 6902filter once or twice. 6903 6904If needed, little splotches can be fixed manually. Remember that if 6905logo pixels are not covered, the filter quality will be much 6906reduced. Marking too many pixels as part of the logo does not hurt as 6907much, but it will increase the amount of blurring needed to cover over 6908the image and will destroy more information than necessary, and extra 6909pixels will slow things down on a large logo. 6910 6911@section rotate 6912 6913Rotate video by an arbitrary angle expressed in radians. 6914 6915The filter accepts the following options: 6916 6917A description of the optional parameters follows. 6918@table @option 6919@item angle, a 6920Set an expression for the angle by which to rotate the input video 6921clockwise, expressed as a number of radians. A negative value will 6922result in a counter-clockwise rotation. By default it is set to "0". 6923 6924This expression is evaluated for each frame. 6925 6926@item out_w, ow 6927Set the output width expression, default value is "iw". 6928This expression is evaluated just once during configuration. 6929 6930@item out_h, oh 6931Set the output height expression, default value is "ih". 6932This expression is evaluated just once during configuration. 6933 6934@item bilinear 6935Enable bilinear interpolation if set to 1, a value of 0 disables 6936it. Default value is 1. 6937 6938@item fillcolor, c 6939Set the color used to fill the output area not covered by the rotated 6940image. For the generalsyntax of this option, check the "Color" section in the 6941ffmpeg-utils manual. If the special value "none" is selected then no 6942background is printed (useful for example if the background is never shown). 6943 6944Default value is "black". 6945@end table 6946 6947The expressions for the angle and the output size can contain the 6948following constants and functions: 6949 6950@table @option 6951@item n 6952sequential number of the input frame, starting from 0. It is always NAN 6953before the first frame is filtered. 6954 6955@item t 6956time in seconds of the input frame, it is set to 0 when the filter is 6957configured. It is always NAN before the first frame is filtered. 6958 6959@item hsub 6960@item vsub 6961horizontal and vertical chroma subsample values. For example for the 6962pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1. 6963 6964@item in_w, iw 6965@item in_h, ih 6966the input video width and height 6967 6968@item out_w, ow 6969@item out_h, oh 6970the output width and height, that is the size of the padded area as 6971specified by the @var{width} and @var{height} expressions 6972 6973@item rotw(a) 6974@item roth(a) 6975the minimal width/height required for completely containing the input 6976video rotated by @var{a} radians. 6977 6978These are only available when computing the @option{out_w} and 6979@option{out_h} expressions. 6980@end table 6981 6982@subsection Examples 6983 6984@itemize 6985@item 6986Rotate the input by PI/6 radians clockwise: 6987@example 6988rotate=PI/6 6989@end example 6990 6991@item 6992Rotate the input by PI/6 radians counter-clockwise: 6993@example 6994rotate=-PI/6 6995@end example 6996 6997@item 6998Rotate the input by 45 degrees clockwise: 6999@example 7000rotate=45*PI/180 7001@end example 7002 7003@item 7004Apply a constant rotation with period T, starting from an angle of PI/3: 7005@example 7006rotate=PI/3+2*PI*t/T 7007@end example 7008 7009@item 7010Make the input video rotation oscillating with a period of T 7011seconds and an amplitude of A radians: 7012@example 7013rotate=A*sin(2*PI/T*t) 7014@end example 7015 7016@item 7017Rotate the video, output size is chosen so that the whole rotating 7018input video is always completely contained in the output: 7019@example 7020rotate='2*PI*t:ow=hypot(iw,ih):oh=ow' 7021@end example 7022 7023@item 7024Rotate the video, reduce the output size so that no background is ever 7025shown: 7026@example 7027rotate=2*PI*t:ow='min(iw,ih)/sqrt(2)':oh=ow:c=none 7028@end example 7029@end itemize 7030 7031@subsection Commands 7032 7033The filter supports the following commands: 7034 7035@table @option 7036@item a, angle 7037Set the angle expression. 7038The command accepts the same syntax of the corresponding option. 7039 7040If the specified expression is not valid, it is kept at its current 7041value. 7042@end table 7043 7044@section sab 7045 7046Apply Shape Adaptive Blur. 7047 7048The filter accepts the following options: 7049 7050@table @option 7051@item luma_radius, lr 7052Set luma blur filter strength, must be a value in range 0.1-4.0, default 7053value is 1.0. A greater value will result in a more blurred image, and 7054in slower processing. 7055 7056@item luma_pre_filter_radius, lpfr 7057Set luma pre-filter radius, must be a value in the 0.1-2.0 range, default 7058value is 1.0. 7059 7060@item luma_strength, ls 7061Set luma maximum difference between pixels to still be considered, must 7062be a value in the 0.1-100.0 range, default value is 1.0. 7063 7064@item chroma_radius, cr 7065Set chroma blur filter strength, must be a value in range 0.1-4.0. A 7066greater value will result in a more blurred image, and in slower 7067processing. 7068 7069@item chroma_pre_filter_radius, cpfr 7070Set chroma pre-filter radius, must be a value in the 0.1-2.0 range. 7071 7072@item chroma_strength, cs 7073Set chroma maximum difference between pixels to still be considered, 7074must be a value in the 0.1-100.0 range. 7075@end table 7076 7077Each chroma option value, if not explicitly specified, is set to the 7078corresponding luma option value. 7079 7080@anchor{scale} 7081@section scale 7082 7083Scale (resize) the input video, using the libswscale library. 7084 7085The scale filter forces the output display aspect ratio to be the same 7086of the input, by changing the output sample aspect ratio. 7087 7088If the input image format is different from the format requested by 7089the next filter, the scale filter will convert the input to the 7090requested format. 7091 7092@subsection Options 7093The filter accepts the following options, or any of the options 7094supported by the libswscale scaler. 7095 7096See @ref{scaler_options,,the ffmpeg-scaler manual,ffmpeg-scaler} for 7097the complete list of scaler options. 7098 7099@table @option 7100@item width, w 7101@item height, h 7102Set the output video dimension expression. Default value is the input 7103dimension. 7104 7105If the value is 0, the input width is used for the output. 7106 7107If one of the values is -1, the scale filter will use a value that 7108maintains the aspect ratio of the input image, calculated from the 7109other specified dimension. If both of them are -1, the input size is 7110used 7111 7112If one of the values is -n with n > 1, the scale filter will also use a value 7113that maintains the aspect ratio of the input image, calculated from the other 7114specified dimension. After that it will, however, make sure that the calculated 7115dimension is divisible by n and adjust the value if necessary. 7116 7117See below for the list of accepted constants for use in the dimension 7118expression. 7119 7120@item interl 7121Set the interlacing mode. It accepts the following values: 7122 7123@table @samp 7124@item 1 7125Force interlaced aware scaling. 7126 7127@item 0 7128Do not apply interlaced scaling. 7129 7130@item -1 7131Select interlaced aware scaling depending on whether the source frames 7132are flagged as interlaced or not. 7133@end table 7134 7135Default value is @samp{0}. 7136 7137@item flags 7138Set libswscale scaling flags. See 7139@ref{sws_flags,,the ffmpeg-scaler manual,ffmpeg-scaler} for the 7140complete list of values. If not explicitly specified the filter applies 7141the default flags. 7142 7143@item size, s 7144Set the video size. For the syntax of this option, check the "Video size" 7145section in the ffmpeg-utils manual. 7146 7147@item in_color_matrix 7148@item out_color_matrix 7149Set in/output YCbCr color space type. 7150 7151This allows the autodetected value to be overridden as well as allows forcing 7152a specific value used for the output and encoder. 7153 7154If not specified, the color space type depends on the pixel format. 7155 7156Possible values: 7157 7158@table @samp 7159@item auto 7160Choose automatically. 7161 7162@item bt709 7163Format conforming to International Telecommunication Union (ITU) 7164Recommendation BT.709. 7165 7166@item fcc 7167Set color space conforming to the United States Federal Communications 7168Commission (FCC) Code of Federal Regulations (CFR) Title 47 (2003) 73.682 (a). 7169 7170@item bt601 7171Set color space conforming to: 7172 7173@itemize 7174@item 7175ITU Radiocommunication Sector (ITU-R) Recommendation BT.601 7176 7177@item 7178ITU-R Rec. BT.470-6 (1998) Systems B, B1, and G 7179 7180@item 7181Society of Motion Picture and Television Engineers (SMPTE) ST 170:2004 7182 7183@end itemize 7184 7185@item smpte240m 7186Set color space conforming to SMPTE ST 240:1999. 7187@end table 7188 7189@item in_range 7190@item out_range 7191Set in/output YCbCr sample range. 7192 7193This allows the autodetected value to be overridden as well as allows forcing 7194a specific value used for the output and encoder. If not specified, the 7195range depends on the pixel format. Possible values: 7196 7197@table @samp 7198@item auto 7199Choose automatically. 7200 7201@item jpeg/full/pc 7202Set full range (0-255 in case of 8-bit luma). 7203 7204@item mpeg/tv 7205Set "MPEG" range (16-235 in case of 8-bit luma). 7206@end table 7207 7208@item force_original_aspect_ratio 7209Enable decreasing or increasing output video width or height if necessary to 7210keep the original aspect ratio. Possible values: 7211 7212@table @samp 7213@item disable 7214Scale the video as specified and disable this feature. 7215 7216@item decrease 7217The output video dimensions will automatically be decreased if needed. 7218 7219@item increase 7220The output video dimensions will automatically be increased if needed. 7221 7222@end table 7223 7224One useful instance of this option is that when you know a specific device's 7225maximum allowed resolution, you can use this to limit the output video to 7226that, while retaining the aspect ratio. For example, device A allows 72271280x720 playback, and your video is 1920x800. Using this option (set it to 7228decrease) and specifying 1280x720 to the command line makes the output 72291280x533. 7230 7231Please note that this is a different thing than specifying -1 for @option{w} 7232or @option{h}, you still need to specify the output resolution for this option 7233to work. 7234 7235@end table 7236 7237The values of the @option{w} and @option{h} options are expressions 7238containing the following constants: 7239 7240@table @var 7241@item in_w 7242@item in_h 7243The input width and height 7244 7245@item iw 7246@item ih 7247These are the same as @var{in_w} and @var{in_h}. 7248 7249@item out_w 7250@item out_h 7251The output (scaled) width and height 7252 7253@item ow 7254@item oh 7255These are the same as @var{out_w} and @var{out_h} 7256 7257@item a 7258The same as @var{iw} / @var{ih} 7259 7260@item sar 7261input sample aspect ratio 7262 7263@item dar 7264The input display aspect ratio. Calculated from @code{(iw / ih) * sar}. 7265 7266@item hsub 7267@item vsub 7268horizontal and vertical input chroma subsample values. For example for the 7269pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1. 7270 7271@item ohsub 7272@item ovsub 7273horizontal and vertical output chroma subsample values. For example for the 7274pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1. 7275@end table 7276 7277@subsection Examples 7278 7279@itemize 7280@item 7281Scale the input video to a size of 200x100 7282@example 7283scale=w=200:h=100 7284@end example 7285 7286This is equivalent to: 7287@example 7288scale=200:100 7289@end example 7290 7291or: 7292@example 7293scale=200x100 7294@end example 7295 7296@item 7297Specify a size abbreviation for the output size: 7298@example 7299scale=qcif 7300@end example 7301 7302which can also be written as: 7303@example 7304scale=size=qcif 7305@end example 7306 7307@item 7308Scale the input to 2x: 7309@example 7310scale=w=2*iw:h=2*ih 7311@end example 7312 7313@item 7314The above is the same as: 7315@example 7316scale=2*in_w:2*in_h 7317@end example 7318 7319@item 7320Scale the input to 2x with forced interlaced scaling: 7321@example 7322scale=2*iw:2*ih:interl=1 7323@end example 7324 7325@item 7326Scale the input to half size: 7327@example 7328scale=w=iw/2:h=ih/2 7329@end example 7330 7331@item 7332Increase the width, and set the height to the same size: 7333@example 7334scale=3/2*iw:ow 7335@end example 7336 7337@item 7338Seek Greek harmony: 7339@example 7340scale=iw:1/PHI*iw 7341scale=ih*PHI:ih 7342@end example 7343 7344@item 7345Increase the height, and set the width to 3/2 of the height: 7346@example 7347scale=w=3/2*oh:h=3/5*ih 7348@end example 7349 7350@item 7351Increase the size, making the size a multiple of the chroma 7352subsample values: 7353@example 7354scale="trunc(3/2*iw/hsub)*hsub:trunc(3/2*ih/vsub)*vsub" 7355@end example 7356 7357@item 7358Increase the width to a maximum of 500 pixels, 7359keeping the same aspect ratio as the input: 7360@example 7361scale=w='min(500\, iw*3/2):h=-1' 7362@end example 7363@end itemize 7364 7365@section separatefields 7366 7367The @code{separatefields} takes a frame-based video input and splits 7368each frame into its components fields, producing a new half height clip 7369with twice the frame rate and twice the frame count. 7370 7371This filter use field-dominance information in frame to decide which 7372of each pair of fields to place first in the output. 7373If it gets it wrong use @ref{setfield} filter before @code{separatefields} filter. 7374 7375@section setdar, setsar 7376 7377The @code{setdar} filter sets the Display Aspect Ratio for the filter 7378output video. 7379 7380This is done by changing the specified Sample (aka Pixel) Aspect 7381Ratio, according to the following equation: 7382@example 7383@var{DAR} = @var{HORIZONTAL_RESOLUTION} / @var{VERTICAL_RESOLUTION} * @var{SAR} 7384@end example 7385 7386Keep in mind that the @code{setdar} filter does not modify the pixel 7387dimensions of the video frame. Also, the display aspect ratio set by 7388this filter may be changed by later filters in the filterchain, 7389e.g. in case of scaling or if another "setdar" or a "setsar" filter is 7390applied. 7391 7392The @code{setsar} filter sets the Sample (aka Pixel) Aspect Ratio for 7393the filter output video. 7394 7395Note that as a consequence of the application of this filter, the 7396output display aspect ratio will change according to the equation 7397above. 7398 7399Keep in mind that the sample aspect ratio set by the @code{setsar} 7400filter may be changed by later filters in the filterchain, e.g. if 7401another "setsar" or a "setdar" filter is applied. 7402 7403It accepts the following parameters: 7404 7405@table @option 7406@item r, ratio, dar (@code{setdar} only), sar (@code{setsar} only) 7407Set the aspect ratio used by the filter. 7408 7409The parameter can be a floating point number string, an expression, or 7410a string of the form @var{num}:@var{den}, where @var{num} and 7411@var{den} are the numerator and denominator of the aspect ratio. If 7412the parameter is not specified, it is assumed the value "0". 7413In case the form "@var{num}:@var{den}" is used, the @code{:} character 7414should be escaped. 7415 7416@item max 7417Set the maximum integer value to use for expressing numerator and 7418denominator when reducing the expressed aspect ratio to a rational. 7419Default value is @code{100}. 7420 7421@end table 7422 7423The parameter @var{sar} is an expression containing 7424the following constants: 7425 7426@table @option 7427@item E, PI, PHI 7428These are approximated values for the mathematical constants e 7429(Euler's number), pi (Greek pi), and phi (the golden ratio). 7430 7431@item w, h 7432The input width and height. 7433 7434@item a 7435These are the same as @var{w} / @var{h}. 7436 7437@item sar 7438The input sample aspect ratio. 7439 7440@item dar 7441The input display aspect ratio. It is the same as 7442(@var{w} / @var{h}) * @var{sar}. 7443 7444@item hsub, vsub 7445Horizontal and vertical chroma subsample values. For example, for the 7446pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1. 7447@end table 7448 7449@subsection Examples 7450 7451@itemize 7452 7453@item 7454To change the display aspect ratio to 16:9, specify one of the following: 7455@example 7456setdar=dar=1.77777 7457setdar=dar=16/9 7458setdar=dar=1.77777 7459@end example 7460 7461@item 7462To change the sample aspect ratio to 10:11, specify: 7463@example 7464setsar=sar=10/11 7465@end example 7466 7467@item 7468To set a display aspect ratio of 16:9, and specify a maximum integer value of 74691000 in the aspect ratio reduction, use the command: 7470@example 7471setdar=ratio=16/9:max=1000 7472@end example 7473 7474@end itemize 7475 7476@anchor{setfield} 7477@section setfield 7478 7479Force field for the output video frame. 7480 7481The @code{setfield} filter marks the interlace type field for the 7482output frames. It does not change the input frame, but only sets the 7483corresponding property, which affects how the frame is treated by 7484following filters (e.g. @code{fieldorder} or @code{yadif}). 7485 7486The filter accepts the following options: 7487 7488@table @option 7489 7490@item mode 7491Available values are: 7492 7493@table @samp 7494@item auto 7495Keep the same field property. 7496 7497@item bff 7498Mark the frame as bottom-field-first. 7499 7500@item tff 7501Mark the frame as top-field-first. 7502 7503@item prog 7504Mark the frame as progressive. 7505@end table 7506@end table 7507 7508@section showinfo 7509 7510Show a line containing various information for each input video frame. 7511The input video is not modified. 7512 7513The shown line contains a sequence of key/value pairs of the form 7514@var{key}:@var{value}. 7515 7516It accepts the following parameters: 7517 7518@table @option 7519@item n 7520The (sequential) number of the input frame, starting from 0. 7521 7522@item pts 7523The Presentation TimeStamp of the input frame, expressed as a number of 7524time base units. The time base unit depends on the filter input pad. 7525 7526@item pts_time 7527The Presentation TimeStamp of the input frame, expressed as a number of 7528seconds. 7529 7530@item pos 7531The position of the frame in the input stream, or -1 if this information is 7532unavailable and/or meaningless (for example in case of synthetic video). 7533 7534@item fmt 7535The pixel format name. 7536 7537@item sar 7538The sample aspect ratio of the input frame, expressed in the form 7539@var{num}/@var{den}. 7540 7541@item s 7542The size of the input frame. For the syntax of this option, check the "Video size" 7543section in the ffmpeg-utils manual. 7544 7545@item i 7546The type of interlaced mode ("P" for "progressive", "T" for top field first, "B" 7547for bottom field first). 7548 7549@item iskey 7550This is 1 if the frame is a key frame, 0 otherwise. 7551 7552@item type 7553The picture type of the input frame ("I" for an I-frame, "P" for a 7554P-frame, "B" for a B-frame, or "?" for an unknown type). 7555Also refer to the documentation of the @code{AVPictureType} enum and of 7556the @code{av_get_picture_type_char} function defined in 7557@file{libavutil/avutil.h}. 7558 7559@item checksum 7560The Adler-32 checksum (printed in hexadecimal) of all the planes of the input frame. 7561 7562@item plane_checksum 7563The Adler-32 checksum (printed in hexadecimal) of each plane of the input frame, 7564expressed in the form "[@var{c0} @var{c1} @var{c2} @var{c3}]". 7565@end table 7566 7567@section shuffleplanes 7568 7569Reorder and/or duplicate video planes. 7570 7571It accepts the following parameters: 7572 7573@table @option 7574 7575@item map0 7576The index of the input plane to be used as the first output plane. 7577 7578@item map1 7579The index of the input plane to be used as the second output plane. 7580 7581@item map2 7582The index of the input plane to be used as the third output plane. 7583 7584@item map3 7585The index of the input plane to be used as the fourth output plane. 7586 7587@end table 7588 7589The first plane has the index 0. The default is to keep the input unchanged. 7590 7591Swap the second and third planes of the input: 7592@example 7593ffmpeg -i INPUT -vf shuffleplanes=0:2:1:3 OUTPUT 7594@end example 7595 7596@section signalstats 7597Evaluate various visual metrics that assist in determining issues associated 7598with the digitization of analog video media. 7599 7600By default the filter will log these metadata values: 7601 7602@table @option 7603@item YMIN 7604Display the minimal Y value contained within the input frame. Expressed in 7605range of [0-255]. 7606 7607@item YLOW 7608Display the Y value at the 10% percentile within the input frame. Expressed in 7609range of [0-255]. 7610 7611@item YAVG 7612Display the average Y value within the input frame. Expressed in range of 7613[0-255]. 7614 7615@item YHIGH 7616Display the Y value at the 90% percentile within the input frame. Expressed in 7617range of [0-255]. 7618 7619@item YMAX 7620Display the maximum Y value contained within the input frame. Expressed in 7621range of [0-255]. 7622 7623@item UMIN 7624Display the minimal U value contained within the input frame. Expressed in 7625range of [0-255]. 7626 7627@item ULOW 7628Display the U value at the 10% percentile within the input frame. Expressed in 7629range of [0-255]. 7630 7631@item UAVG 7632Display the average U value within the input frame. Expressed in range of 7633[0-255]. 7634 7635@item UHIGH 7636Display the U value at the 90% percentile within the input frame. Expressed in 7637range of [0-255]. 7638 7639@item UMAX 7640Display the maximum U value contained within the input frame. Expressed in 7641range of [0-255]. 7642 7643@item VMIN 7644Display the minimal V value contained within the input frame. Expressed in 7645range of [0-255]. 7646 7647@item VLOW 7648Display the V value at the 10% percentile within the input frame. Expressed in 7649range of [0-255]. 7650 7651@item VAVG 7652Display the average V value within the input frame. Expressed in range of 7653[0-255]. 7654 7655@item VHIGH 7656Display the V value at the 90% percentile within the input frame. Expressed in 7657range of [0-255]. 7658 7659@item VMAX 7660Display the maximum V value contained within the input frame. Expressed in 7661range of [0-255]. 7662 7663@item SATMIN 7664Display the minimal saturation value contained within the input frame. 7665Expressed in range of [0-~181.02]. 7666 7667@item SATLOW 7668Display the saturation value at the 10% percentile within the input frame. 7669Expressed in range of [0-~181.02]. 7670 7671@item SATAVG 7672Display the average saturation value within the input frame. Expressed in range 7673of [0-~181.02]. 7674 7675@item SATHIGH 7676Display the saturation value at the 90% percentile within the input frame. 7677Expressed in range of [0-~181.02]. 7678 7679@item SATMAX 7680Display the maximum saturation value contained within the input frame. 7681Expressed in range of [0-~181.02]. 7682 7683@item HUEMED 7684Display the median value for hue within the input frame. Expressed in range of 7685[0-360]. 7686 7687@item HUEAVG 7688Display the average value for hue within the input frame. Expressed in range of 7689[0-360]. 7690 7691@item YDIF 7692Display the average of sample value difference between all values of the Y 7693plane in the current frame and corresponding values of the previous input frame. 7694Expressed in range of [0-255]. 7695 7696@item UDIF 7697Display the average of sample value difference between all values of the U 7698plane in the current frame and corresponding values of the previous input frame. 7699Expressed in range of [0-255]. 7700 7701@item VDIF 7702Display the average of sample value difference between all values of the V 7703plane in the current frame and corresponding values of the previous input frame. 7704Expressed in range of [0-255]. 7705@end table 7706 7707The filter accepts the following options: 7708 7709@table @option 7710@item stat 7711@item out 7712 7713@option{stat} specify an additional form of image analysis. 7714@option{out} output video with the specified type of pixel highlighted. 7715 7716Both options accept the following values: 7717 7718@table @samp 7719@item tout 7720Identify @var{temporal outliers} pixels. A @var{temporal outlier} is a pixel 7721unlike the neighboring pixels of the same field. Examples of temporal outliers 7722include the results of video dropouts, head clogs, or tape tracking issues. 7723 7724@item vrep 7725Identify @var{vertical line repetition}. Vertical line repetition includes 7726similar rows of pixels within a frame. In born-digital video vertical line 7727repetition is common, but this pattern is uncommon in video digitized from an 7728analog source. When it occurs in video that results from the digitization of an 7729analog source it can indicate concealment from a dropout compensator. 7730 7731@item brng 7732Identify pixels that fall outside of legal broadcast range. 7733@end table 7734 7735@item color, c 7736Set the highlight color for the @option{out} option. The default color is 7737yellow. 7738@end table 7739 7740@subsection Examples 7741 7742@itemize 7743@item 7744Output data of various video metrics: 7745@example 7746ffprobe -f lavfi movie=example.mov,signalstats="stat=tout+vrep+brng" -show_frames 7747@end example 7748 7749@item 7750Output specific data about the minimum and maximum values of the Y plane per frame: 7751@example 7752ffprobe -f lavfi movie=example.mov,signalstats -show_entries frame_tags=lavfi.signalstats.YMAX,lavfi.signalstats.YMIN 7753@end example 7754 7755@item 7756Playback video while highlighting pixels that are outside of broadcast range in red. 7757@example 7758ffplay example.mov -vf signalstats="out=brng:color=red" 7759@end example 7760 7761@item 7762Playback video with signalstats metadata drawn over the frame. 7763@example 7764ffplay example.mov -vf signalstats=stat=brng+vrep+tout,drawtext=fontfile=FreeSerif.ttf:textfile=signalstat_drawtext.txt 7765@end example 7766 7767The contents of signalstat_drawtext.txt used in the command are: 7768@example 7769time %@{pts:hms@} 7770Y (%@{metadata:lavfi.signalstats.YMIN@}-%@{metadata:lavfi.signalstats.YMAX@}) 7771U (%@{metadata:lavfi.signalstats.UMIN@}-%@{metadata:lavfi.signalstats.UMAX@}) 7772V (%@{metadata:lavfi.signalstats.VMIN@}-%@{metadata:lavfi.signalstats.VMAX@}) 7773saturation maximum: %@{metadata:lavfi.signalstats.SATMAX@} 7774 7775@end example 7776@end itemize 7777 7778@anchor{smartblur} 7779@section smartblur 7780 7781Blur the input video without impacting the outlines. 7782 7783It accepts the following options: 7784 7785@table @option 7786@item luma_radius, lr 7787Set the luma radius. The option value must be a float number in 7788the range [0.1,5.0] that specifies the variance of the gaussian filter 7789used to blur the image (slower if larger). Default value is 1.0. 7790 7791@item luma_strength, ls 7792Set the luma strength. The option value must be a float number 7793in the range [-1.0,1.0] that configures the blurring. A value included 7794in [0.0,1.0] will blur the image whereas a value included in 7795[-1.0,0.0] will sharpen the image. Default value is 1.0. 7796 7797@item luma_threshold, lt 7798Set the luma threshold used as a coefficient to determine 7799whether a pixel should be blurred or not. The option value must be an 7800integer in the range [-30,30]. A value of 0 will filter all the image, 7801a value included in [0,30] will filter flat areas and a value included 7802in [-30,0] will filter edges. Default value is 0. 7803 7804@item chroma_radius, cr 7805Set the chroma radius. The option value must be a float number in 7806the range [0.1,5.0] that specifies the variance of the gaussian filter 7807used to blur the image (slower if larger). Default value is 1.0. 7808 7809@item chroma_strength, cs 7810Set the chroma strength. The option value must be a float number 7811in the range [-1.0,1.0] that configures the blurring. A value included 7812in [0.0,1.0] will blur the image whereas a value included in 7813[-1.0,0.0] will sharpen the image. Default value is 1.0. 7814 7815@item chroma_threshold, ct 7816Set the chroma threshold used as a coefficient to determine 7817whether a pixel should be blurred or not. The option value must be an 7818integer in the range [-30,30]. A value of 0 will filter all the image, 7819a value included in [0,30] will filter flat areas and a value included 7820in [-30,0] will filter edges. Default value is 0. 7821@end table 7822 7823If a chroma option is not explicitly set, the corresponding luma value 7824is set. 7825 7826@section stereo3d 7827 7828Convert between different stereoscopic image formats. 7829 7830The filters accept the following options: 7831 7832@table @option 7833@item in 7834Set stereoscopic image format of input. 7835 7836Available values for input image formats are: 7837@table @samp 7838@item sbsl 7839side by side parallel (left eye left, right eye right) 7840 7841@item sbsr 7842side by side crosseye (right eye left, left eye right) 7843 7844@item sbs2l 7845side by side parallel with half width resolution 7846(left eye left, right eye right) 7847 7848@item sbs2r 7849side by side crosseye with half width resolution 7850(right eye left, left eye right) 7851 7852@item abl 7853above-below (left eye above, right eye below) 7854 7855@item abr 7856above-below (right eye above, left eye below) 7857 7858@item ab2l 7859above-below with half height resolution 7860(left eye above, right eye below) 7861 7862@item ab2r 7863above-below with half height resolution 7864(right eye above, left eye below) 7865 7866@item al 7867alternating frames (left eye first, right eye second) 7868 7869@item ar 7870alternating frames (right eye first, left eye second) 7871 7872Default value is @samp{sbsl}. 7873@end table 7874 7875@item out 7876Set stereoscopic image format of output. 7877 7878Available values for output image formats are all the input formats as well as: 7879@table @samp 7880@item arbg 7881anaglyph red/blue gray 7882(red filter on left eye, blue filter on right eye) 7883 7884@item argg 7885anaglyph red/green gray 7886(red filter on left eye, green filter on right eye) 7887 7888@item arcg 7889anaglyph red/cyan gray 7890(red filter on left eye, cyan filter on right eye) 7891 7892@item arch 7893anaglyph red/cyan half colored 7894(red filter on left eye, cyan filter on right eye) 7895 7896@item arcc 7897anaglyph red/cyan color 7898(red filter on left eye, cyan filter on right eye) 7899 7900@item arcd 7901anaglyph red/cyan color optimized with the least squares projection of dubois 7902(red filter on left eye, cyan filter on right eye) 7903 7904@item agmg 7905anaglyph green/magenta gray 7906(green filter on left eye, magenta filter on right eye) 7907 7908@item agmh 7909anaglyph green/magenta half colored 7910(green filter on left eye, magenta filter on right eye) 7911 7912@item agmc 7913anaglyph green/magenta colored 7914(green filter on left eye, magenta filter on right eye) 7915 7916@item agmd 7917anaglyph green/magenta color optimized with the least squares projection of dubois 7918(green filter on left eye, magenta filter on right eye) 7919 7920@item aybg 7921anaglyph yellow/blue gray 7922(yellow filter on left eye, blue filter on right eye) 7923 7924@item aybh 7925anaglyph yellow/blue half colored 7926(yellow filter on left eye, blue filter on right eye) 7927 7928@item aybc 7929anaglyph yellow/blue colored 7930(yellow filter on left eye, blue filter on right eye) 7931 7932@item aybd 7933anaglyph yellow/blue color optimized with the least squares projection of dubois 7934(yellow filter on left eye, blue filter on right eye) 7935 7936@item irl 7937interleaved rows (left eye has top row, right eye starts on next row) 7938 7939@item irr 7940interleaved rows (right eye has top row, left eye starts on next row) 7941 7942@item ml 7943mono output (left eye only) 7944 7945@item mr 7946mono output (right eye only) 7947@end table 7948 7949Default value is @samp{arcd}. 7950@end table 7951 7952@subsection Examples 7953 7954@itemize 7955@item 7956Convert input video from side by side parallel to anaglyph yellow/blue dubois: 7957@example 7958stereo3d=sbsl:aybd 7959@end example 7960 7961@item 7962Convert input video from above bellow (left eye above, right eye below) to side by side crosseye. 7963@example 7964stereo3d=abl:sbsr 7965@end example 7966@end itemize 7967 7968@section spp 7969 7970Apply a simple postprocessing filter that compresses and decompresses the image 7971at several (or - in the case of @option{quality} level @code{6} - all) shifts 7972and average the results. 7973 7974The filter accepts the following options: 7975 7976@table @option 7977@item quality 7978Set quality. This option defines the number of levels for averaging. It accepts 7979an integer in the range 0-6. If set to @code{0}, the filter will have no 7980effect. A value of @code{6} means the higher quality. For each increment of 7981that value the speed drops by a factor of approximately 2. Default value is 7982@code{3}. 7983 7984@item qp 7985Force a constant quantization parameter. If not set, the filter will use the QP 7986from the video stream (if available). 7987 7988@item mode 7989Set thresholding mode. Available modes are: 7990 7991@table @samp 7992@item hard 7993Set hard thresholding (default). 7994@item soft 7995Set soft thresholding (better de-ringing effect, but likely blurrier). 7996@end table 7997 7998@item use_bframe_qp 7999Enable the use of the QP from the B-Frames if set to @code{1}. Using this 8000option may cause flicker since the B-Frames have often larger QP. Default is 8001@code{0} (not enabled). 8002@end table 8003 8004@anchor{subtitles} 8005@section subtitles 8006 8007Draw subtitles on top of input video using the libass library. 8008 8009To enable compilation of this filter you need to configure FFmpeg with 8010@code{--enable-libass}. This filter also requires a build with libavcodec and 8011libavformat to convert the passed subtitles file to ASS (Advanced Substation 8012Alpha) subtitles format. 8013 8014The filter accepts the following options: 8015 8016@table @option 8017@item filename, f 8018Set the filename of the subtitle file to read. It must be specified. 8019 8020@item original_size 8021Specify the size of the original video, the video for which the ASS file 8022was composed. For the syntax of this option, check the "Video size" section in 8023the ffmpeg-utils manual. Due to a misdesign in ASS aspect ratio arithmetic, 8024this is necessary to correctly scale the fonts if the aspect ratio has been 8025changed. 8026 8027@item charenc 8028Set subtitles input character encoding. @code{subtitles} filter only. Only 8029useful if not UTF-8. 8030 8031@item stream_index, si 8032Set subtitles stream index. @code{subtitles} filter only. 8033@end table 8034 8035If the first key is not specified, it is assumed that the first value 8036specifies the @option{filename}. 8037 8038For example, to render the file @file{sub.srt} on top of the input 8039video, use the command: 8040@example 8041subtitles=sub.srt 8042@end example 8043 8044which is equivalent to: 8045@example 8046subtitles=filename=sub.srt 8047@end example 8048 8049To render the default subtitles stream from file @file{video.mkv}, use: 8050@example 8051subtitles=video.mkv 8052@end example 8053 8054To render the second subtitles stream from that file, use: 8055@example 8056subtitles=video.mkv:si=1 8057@end example 8058 8059@section super2xsai 8060 8061Scale the input by 2x and smooth using the Super2xSaI (Scale and 8062Interpolate) pixel art scaling algorithm. 8063 8064Useful for enlarging pixel art images without reducing sharpness. 8065 8066@section swapuv 8067Swap U & V plane. 8068 8069@section telecine 8070 8071Apply telecine process to the video. 8072 8073This filter accepts the following options: 8074 8075@table @option 8076@item first_field 8077@table @samp 8078@item top, t 8079top field first 8080@item bottom, b 8081bottom field first 8082The default value is @code{top}. 8083@end table 8084 8085@item pattern 8086A string of numbers representing the pulldown pattern you wish to apply. 8087The default value is @code{23}. 8088@end table 8089 8090@example 8091Some typical patterns: 8092 8093NTSC output (30i): 809427.5p: 32222 809524p: 23 (classic) 809624p: 2332 (preferred) 809720p: 33 809818p: 334 809916p: 3444 8100 8101PAL output (25i): 810227.5p: 12222 810324p: 222222222223 ("Euro pulldown") 810416.67p: 33 810516p: 33333334 8106@end example 8107 8108@section thumbnail 8109Select the most representative frame in a given sequence of consecutive frames. 8110 8111The filter accepts the following options: 8112 8113@table @option 8114@item n 8115Set the frames batch size to analyze; in a set of @var{n} frames, the filter 8116will pick one of them, and then handle the next batch of @var{n} frames until 8117the end. Default is @code{100}. 8118@end table 8119 8120Since the filter keeps track of the whole frames sequence, a bigger @var{n} 8121value will result in a higher memory usage, so a high value is not recommended. 8122 8123@subsection Examples 8124 8125@itemize 8126@item 8127Extract one picture each 50 frames: 8128@example 8129thumbnail=50 8130@end example 8131 8132@item 8133Complete example of a thumbnail creation with @command{ffmpeg}: 8134@example 8135ffmpeg -i in.avi -vf thumbnail,scale=300:200 -frames:v 1 out.png 8136@end example 8137@end itemize 8138 8139@section tile 8140 8141Tile several successive frames together. 8142 8143The filter accepts the following options: 8144 8145@table @option 8146 8147@item layout 8148Set the grid size (i.e. the number of lines and columns). For the syntax of 8149this option, check the "Video size" section in the ffmpeg-utils manual. 8150 8151@item nb_frames 8152Set the maximum number of frames to render in the given area. It must be less 8153than or equal to @var{w}x@var{h}. The default value is @code{0}, meaning all 8154the area will be used. 8155 8156@item margin 8157Set the outer border margin in pixels. 8158 8159@item padding 8160Set the inner border thickness (i.e. the number of pixels between frames). For 8161more advanced padding options (such as having different values for the edges), 8162refer to the pad video filter. 8163 8164@item color 8165Specify the color of the unused areaFor the syntax of this option, check the 8166"Color" section in the ffmpeg-utils manual. The default value of @var{color} 8167is "black". 8168@end table 8169 8170@subsection Examples 8171 8172@itemize 8173@item 8174Produce 8x8 PNG tiles of all keyframes (@option{-skip_frame nokey}) in a movie: 8175@example 8176ffmpeg -skip_frame nokey -i file.avi -vf 'scale=128:72,tile=8x8' -an -vsync 0 keyframes%03d.png 8177@end example 8178The @option{-vsync 0} is necessary to prevent @command{ffmpeg} from 8179duplicating each output frame to accommodate the originally detected frame 8180rate. 8181 8182@item 8183Display @code{5} pictures in an area of @code{3x2} frames, 8184with @code{7} pixels between them, and @code{2} pixels of initial margin, using 8185mixed flat and named options: 8186@example 8187tile=3x2:nb_frames=5:padding=7:margin=2 8188@end example 8189@end itemize 8190 8191@section tinterlace 8192 8193Perform various types of temporal field interlacing. 8194 8195Frames are counted starting from 1, so the first input frame is 8196considered odd. 8197 8198The filter accepts the following options: 8199 8200@table @option 8201 8202@item mode 8203Specify the mode of the interlacing. This option can also be specified 8204as a value alone. See below for a list of values for this option. 8205 8206Available values are: 8207 8208@table @samp 8209@item merge, 0 8210Move odd frames into the upper field, even into the lower field, 8211generating a double height frame at half frame rate. 8212 8213@item drop_odd, 1 8214Only output even frames, odd frames are dropped, generating a frame with 8215unchanged height at half frame rate. 8216 8217@item drop_even, 2 8218Only output odd frames, even frames are dropped, generating a frame with 8219unchanged height at half frame rate. 8220 8221@item pad, 3 8222Expand each frame to full height, but pad alternate lines with black, 8223generating a frame with double height at the same input frame rate. 8224 8225@item interleave_top, 4 8226Interleave the upper field from odd frames with the lower field from 8227even frames, generating a frame with unchanged height at half frame rate. 8228 8229@item interleave_bottom, 5 8230Interleave the lower field from odd frames with the upper field from 8231even frames, generating a frame with unchanged height at half frame rate. 8232 8233@item interlacex2, 6 8234Double frame rate with unchanged height. Frames are inserted each 8235containing the second temporal field from the previous input frame and 8236the first temporal field from the next input frame. This mode relies on 8237the top_field_first flag. Useful for interlaced video displays with no 8238field synchronisation. 8239@end table 8240 8241Numeric values are deprecated but are accepted for backward 8242compatibility reasons. 8243 8244Default mode is @code{merge}. 8245 8246@item flags 8247Specify flags influencing the filter process. 8248 8249Available value for @var{flags} is: 8250 8251@table @option 8252@item low_pass_filter, vlfp 8253Enable vertical low-pass filtering in the filter. 8254Vertical low-pass filtering is required when creating an interlaced 8255destination from a progressive source which contains high-frequency 8256vertical detail. Filtering will reduce interlace 'twitter' and Moire 8257patterning. 8258 8259Vertical low-pass filtering can only be enabled for @option{mode} 8260@var{interleave_top} and @var{interleave_bottom}. 8261 8262@end table 8263@end table 8264 8265@section transpose 8266 8267Transpose rows with columns in the input video and optionally flip it. 8268 8269It accepts the following parameters: 8270 8271@table @option 8272 8273@item dir 8274Specify the transposition direction. 8275 8276Can assume the following values: 8277@table @samp 8278@item 0, 4, cclock_flip 8279Rotate by 90 degrees counterclockwise and vertically flip (default), that is: 8280@example 8281L.R L.l 8282. . -> . . 8283l.r R.r 8284@end example 8285 8286@item 1, 5, clock 8287Rotate by 90 degrees clockwise, that is: 8288@example 8289L.R l.L 8290. . -> . . 8291l.r r.R 8292@end example 8293 8294@item 2, 6, cclock 8295Rotate by 90 degrees counterclockwise, that is: 8296@example 8297L.R R.r 8298. . -> . . 8299l.r L.l 8300@end example 8301 8302@item 3, 7, clock_flip 8303Rotate by 90 degrees clockwise and vertically flip, that is: 8304@example 8305L.R r.R 8306. . -> . . 8307l.r l.L 8308@end example 8309@end table 8310 8311For values between 4-7, the transposition is only done if the input 8312video geometry is portrait and not landscape. These values are 8313deprecated, the @code{passthrough} option should be used instead. 8314 8315Numerical values are deprecated, and should be dropped in favor of 8316symbolic constants. 8317 8318@item passthrough 8319Do not apply the transposition if the input geometry matches the one 8320specified by the specified value. It accepts the following values: 8321@table @samp 8322@item none 8323Always apply transposition. 8324@item portrait 8325Preserve portrait geometry (when @var{height} >= @var{width}). 8326@item landscape 8327Preserve landscape geometry (when @var{width} >= @var{height}). 8328@end table 8329 8330Default value is @code{none}. 8331@end table 8332 8333For example to rotate by 90 degrees clockwise and preserve portrait 8334layout: 8335@example 8336transpose=dir=1:passthrough=portrait 8337@end example 8338 8339The command above can also be specified as: 8340@example 8341transpose=1:portrait 8342@end example 8343 8344@section trim 8345Trim the input so that the output contains one continuous subpart of the input. 8346 8347It accepts the following parameters: 8348@table @option 8349@item start 8350Specify the time of the start of the kept section, i.e. the frame with the 8351timestamp @var{start} will be the first frame in the output. 8352 8353@item end 8354Specify the time of the first frame that will be dropped, i.e. the frame 8355immediately preceding the one with the timestamp @var{end} will be the last 8356frame in the output. 8357 8358@item start_pts 8359This is the same as @var{start}, except this option sets the start timestamp 8360in timebase units instead of seconds. 8361 8362@item end_pts 8363This is the same as @var{end}, except this option sets the end timestamp 8364in timebase units instead of seconds. 8365 8366@item duration 8367The maximum duration of the output in seconds. 8368 8369@item start_frame 8370The number of the first frame that should be passed to the output. 8371 8372@item end_frame 8373The number of the first frame that should be dropped. 8374@end table 8375 8376@option{start}, @option{end}, @option{duration} are expressed as time 8377duration specifications, check the "Time duration" section in the 8378ffmpeg-utils manual. 8379 8380Note that the first two sets of the start/end options and the @option{duration} 8381option look at the frame timestamp, while the _frame variants simply count the 8382frames that pass through the filter. Also note that this filter does not modify 8383the timestamps. If you wish for the output timestamps to start at zero, insert a 8384setpts filter after the trim filter. 8385 8386If multiple start or end options are set, this filter tries to be greedy and 8387keep all the frames that match at least one of the specified constraints. To keep 8388only the part that matches all the constraints at once, chain multiple trim 8389filters. 8390 8391The defaults are such that all the input is kept. So it is possible to set e.g. 8392just the end values to keep everything before the specified time. 8393 8394Examples: 8395@itemize 8396@item 8397Drop everything except the second minute of input: 8398@example 8399ffmpeg -i INPUT -vf trim=60:120 8400@end example 8401 8402@item 8403Keep only the first second: 8404@example 8405ffmpeg -i INPUT -vf trim=duration=1 8406@end example 8407 8408@end itemize 8409 8410 8411@section unsharp 8412 8413Sharpen or blur the input video. 8414 8415It accepts the following parameters: 8416 8417@table @option 8418@item luma_msize_x, lx 8419Set the luma matrix horizontal size. It must be an odd integer between 84203 and 63. The default value is 5. 8421 8422@item luma_msize_y, ly 8423Set the luma matrix vertical size. It must be an odd integer between 3 8424and 63. The default value is 5. 8425 8426@item luma_amount, la 8427Set the luma effect strength. It must be a floating point number, reasonable 8428values lay between -1.5 and 1.5. 8429 8430Negative values will blur the input video, while positive values will 8431sharpen it, a value of zero will disable the effect. 8432 8433Default value is 1.0. 8434 8435@item chroma_msize_x, cx 8436Set the chroma matrix horizontal size. It must be an odd integer 8437between 3 and 63. The default value is 5. 8438 8439@item chroma_msize_y, cy 8440Set the chroma matrix vertical size. It must be an odd integer 8441between 3 and 63. The default value is 5. 8442 8443@item chroma_amount, ca 8444Set the chroma effect strength. It must be a floating point number, reasonable 8445values lay between -1.5 and 1.5. 8446 8447Negative values will blur the input video, while positive values will 8448sharpen it, a value of zero will disable the effect. 8449 8450Default value is 0.0. 8451 8452@item opencl 8453If set to 1, specify using OpenCL capabilities, only available if 8454FFmpeg was configured with @code{--enable-opencl}. Default value is 0. 8455 8456@end table 8457 8458All parameters are optional and default to the equivalent of the 8459string '5:5:1.0:5:5:0.0'. 8460 8461@subsection Examples 8462 8463@itemize 8464@item 8465Apply strong luma sharpen effect: 8466@example 8467unsharp=luma_msize_x=7:luma_msize_y=7:luma_amount=2.5 8468@end example 8469 8470@item 8471Apply a strong blur of both luma and chroma parameters: 8472@example 8473unsharp=7:7:-2:7:7:-2 8474@end example 8475@end itemize 8476 8477@anchor{vidstabdetect} 8478@section vidstabdetect 8479 8480Analyze video stabilization/deshaking. Perform pass 1 of 2, see 8481@ref{vidstabtransform} for pass 2. 8482 8483This filter generates a file with relative translation and rotation 8484transform information about subsequent frames, which is then used by 8485the @ref{vidstabtransform} filter. 8486 8487To enable compilation of this filter you need to configure FFmpeg with 8488@code{--enable-libvidstab}. 8489 8490This filter accepts the following options: 8491 8492@table @option 8493@item result 8494Set the path to the file used to write the transforms information. 8495Default value is @file{transforms.trf}. 8496 8497@item shakiness 8498Set how shaky the video is and how quick the camera is. It accepts an 8499integer in the range 1-10, a value of 1 means little shakiness, a 8500value of 10 means strong shakiness. Default value is 5. 8501 8502@item accuracy 8503Set the accuracy of the detection process. It must be a value in the 8504range 1-15. A value of 1 means low accuracy, a value of 15 means high 8505accuracy. Default value is 15. 8506 8507@item stepsize 8508Set stepsize of the search process. The region around minimum is 8509scanned with 1 pixel resolution. Default value is 6. 8510 8511@item mincontrast 8512Set minimum contrast. Below this value a local measurement field is 8513discarded. Must be a floating point value in the range 0-1. Default 8514value is 0.3. 8515 8516@item tripod 8517Set reference frame number for tripod mode. 8518 8519If enabled, the motion of the frames is compared to a reference frame 8520in the filtered stream, identified by the specified number. The idea 8521is to compensate all movements in a more-or-less static scene and keep 8522the camera view absolutely still. 8523 8524If set to 0, it is disabled. The frames are counted starting from 1. 8525 8526@item show 8527Show fields and transforms in the resulting frames. It accepts an 8528integer in the range 0-2. Default value is 0, which disables any 8529visualization. 8530@end table 8531 8532@subsection Examples 8533 8534@itemize 8535@item 8536Use default values: 8537@example 8538vidstabdetect 8539@end example 8540 8541@item 8542Analyze strongly shaky movie and put the results in file 8543@file{mytransforms.trf}: 8544@example 8545vidstabdetect=shakiness=10:accuracy=15:result="mytransforms.trf" 8546@end example 8547 8548@item 8549Visualize the result of internal transformations in the resulting 8550video: 8551@example 8552vidstabdetect=show=1 8553@end example 8554 8555@item 8556Analyze a video with medium shakiness using @command{ffmpeg}: 8557@example 8558ffmpeg -i input -vf vidstabdetect=shakiness=5:show=1 dummy.avi 8559@end example 8560@end itemize 8561 8562@anchor{vidstabtransform} 8563@section vidstabtransform 8564 8565Video stabilization/deshaking: pass 2 of 2, 8566see @ref{vidstabdetect} for pass 1. 8567 8568Read a file with transform information for each frame and 8569apply/compensate them. Together with the @ref{vidstabdetect} 8570filter this can be used to deshake videos. See also 8571@url{http://public.hronopik.de/vid.stab}. It is important to also use 8572the unsharp filter, see below. 8573 8574To enable compilation of this filter you need to configure FFmpeg with 8575@code{--enable-libvidstab}. 8576 8577@subsection Options 8578 8579@table @option 8580@item input 8581Set path to the file used to read the transforms. Default value is 8582@file{transforms.trf}). 8583 8584@item smoothing 8585Set the number of frames (value*2 + 1) used for lowpass filtering the 8586camera movements. Default value is 10. 8587 8588For example a number of 10 means that 21 frames are used (10 in the 8589past and 10 in the future) to smoothen the motion in the video. A 8590larger values leads to a smoother video, but limits the acceleration 8591of the camera (pan/tilt movements). 0 is a special case where a 8592static camera is simulated. 8593 8594@item optalgo 8595Set the camera path optimization algorithm. 8596 8597Accepted values are: 8598@table @samp 8599@item gauss 8600gaussian kernel low-pass filter on camera motion (default) 8601@item avg 8602averaging on transformations 8603@end table 8604 8605@item maxshift 8606Set maximal number of pixels to translate frames. Default value is -1, 8607meaning no limit. 8608 8609@item maxangle 8610Set maximal angle in radians (degree*PI/180) to rotate frames. Default 8611value is -1, meaning no limit. 8612 8613@item crop 8614Specify how to deal with borders that may be visible due to movement 8615compensation. 8616 8617Available values are: 8618@table @samp 8619@item keep 8620keep image information from previous frame (default) 8621@item black 8622fill the border black 8623@end table 8624 8625@item invert 8626Invert transforms if set to 1. Default value is 0. 8627 8628@item relative 8629Consider transforms as relative to previsou frame if set to 1, 8630absolute if set to 0. Default value is 0. 8631 8632@item zoom 8633Set percentage to zoom. A positive value will result in a zoom-in 8634effect, a negative value in a zoom-out effect. Default value is 0 (no 8635zoom). 8636 8637@item optzoom 8638Set optimal zooming to avoid borders. 8639 8640Accepted values are: 8641@table @samp 8642@item 0 8643disabled 8644@item 1 8645optimal static zoom value is determined (only very strong movements 8646will lead to visible borders) (default) 8647@item 2 8648optimal adaptive zoom value is determined (no borders will be 8649visible), see @option{zoomspeed} 8650@end table 8651 8652Note that the value given at zoom is added to the one calculated here. 8653 8654@item zoomspeed 8655Set percent to zoom maximally each frame (enabled when 8656@option{optzoom} is set to 2). Range is from 0 to 5, default value is 86570.25. 8658 8659@item interpol 8660Specify type of interpolation. 8661 8662Available values are: 8663@table @samp 8664@item no 8665no interpolation 8666@item linear 8667linear only horizontal 8668@item bilinear 8669linear in both directions (default) 8670@item bicubic 8671cubic in both directions (slow) 8672@end table 8673 8674@item tripod 8675Enable virtual tripod mode if set to 1, which is equivalent to 8676@code{relative=0:smoothing=0}. Default value is 0. 8677 8678Use also @code{tripod} option of @ref{vidstabdetect}. 8679 8680@item debug 8681Increase log verbosity if set to 1. Also the detected global motions 8682are written to the temporary file @file{global_motions.trf}. Default 8683value is 0. 8684@end table 8685 8686@subsection Examples 8687 8688@itemize 8689@item 8690Use @command{ffmpeg} for a typical stabilization with default values: 8691@example 8692ffmpeg -i inp.mpeg -vf vidstabtransform,unsharp=5:5:0.8:3:3:0.4 inp_stabilized.mpeg 8693@end example 8694 8695Note the use of the unsharp filter which is always recommended. 8696 8697@item 8698Zoom in a bit more and load transform data from a given file: 8699@example 8700vidstabtransform=zoom=5:input="mytransforms.trf" 8701@end example 8702 8703@item 8704Smoothen the video even more: 8705@example 8706vidstabtransform=smoothing=30 8707@end example 8708@end itemize 8709 8710@section vflip 8711 8712Flip the input video vertically. 8713 8714For example, to vertically flip a video with @command{ffmpeg}: 8715@example 8716ffmpeg -i in.avi -vf "vflip" out.avi 8717@end example 8718 8719@section vignette 8720 8721Make or reverse a natural vignetting effect. 8722 8723The filter accepts the following options: 8724 8725@table @option 8726@item angle, a 8727Set lens angle expression as a number of radians. 8728 8729The value is clipped in the @code{[0,PI/2]} range. 8730 8731Default value: @code{"PI/5"} 8732 8733@item x0 8734@item y0 8735Set center coordinates expressions. Respectively @code{"w/2"} and @code{"h/2"} 8736by default. 8737 8738@item mode 8739Set forward/backward mode. 8740 8741Available modes are: 8742@table @samp 8743@item forward 8744The larger the distance from the central point, the darker the image becomes. 8745 8746@item backward 8747The larger the distance from the central point, the brighter the image becomes. 8748This can be used to reverse a vignette effect, though there is no automatic 8749detection to extract the lens @option{angle} and other settings (yet). It can 8750also be used to create a burning effect. 8751@end table 8752 8753Default value is @samp{forward}. 8754 8755@item eval 8756Set evaluation mode for the expressions (@option{angle}, @option{x0}, @option{y0}). 8757 8758It accepts the following values: 8759@table @samp 8760@item init 8761Evaluate expressions only once during the filter initialization. 8762 8763@item frame 8764Evaluate expressions for each incoming frame. This is way slower than the 8765@samp{init} mode since it requires all the scalers to be re-computed, but it 8766allows advanced dynamic expressions. 8767@end table 8768 8769Default value is @samp{init}. 8770 8771@item dither 8772Set dithering to reduce the circular banding effects. Default is @code{1} 8773(enabled). 8774 8775@item aspect 8776Set vignette aspect. This setting allows one to adjust the shape of the vignette. 8777Setting this value to the SAR of the input will make a rectangular vignetting 8778following the dimensions of the video. 8779 8780Default is @code{1/1}. 8781@end table 8782 8783@subsection Expressions 8784 8785The @option{alpha}, @option{x0} and @option{y0} expressions can contain the 8786following parameters. 8787 8788@table @option 8789@item w 8790@item h 8791input width and height 8792 8793@item n 8794the number of input frame, starting from 0 8795 8796@item pts 8797the PTS (Presentation TimeStamp) time of the filtered video frame, expressed in 8798@var{TB} units, NAN if undefined 8799 8800@item r 8801frame rate of the input video, NAN if the input frame rate is unknown 8802 8803@item t 8804the PTS (Presentation TimeStamp) of the filtered video frame, 8805expressed in seconds, NAN if undefined 8806 8807@item tb 8808time base of the input video 8809@end table 8810 8811 8812@subsection Examples 8813 8814@itemize 8815@item 8816Apply simple strong vignetting effect: 8817@example 8818vignette=PI/4 8819@end example 8820 8821@item 8822Make a flickering vignetting: 8823@example 8824vignette='PI/4+random(1)*PI/50':eval=frame 8825@end example 8826 8827@end itemize 8828 8829@section w3fdif 8830 8831Deinterlace the input video ("w3fdif" stands for "Weston 3 Field 8832Deinterlacing Filter"). 8833 8834Based on the process described by Martin Weston for BBC R&D, and 8835implemented based on the de-interlace algorithm written by Jim 8836Easterbrook for BBC R&D, the Weston 3 field deinterlacing filter 8837uses filter coefficients calculated by BBC R&D. 8838 8839There are two sets of filter coefficients, so called "simple": 8840and "complex". Which set of filter coefficients is used can 8841be set by passing an optional parameter: 8842 8843@table @option 8844@item filter 8845Set the interlacing filter coefficients. Accepts one of the following values: 8846 8847@table @samp 8848@item simple 8849Simple filter coefficient set. 8850@item complex 8851More-complex filter coefficient set. 8852@end table 8853Default value is @samp{complex}. 8854 8855@item deint 8856Specify which frames to deinterlace. Accept one of the following values: 8857 8858@table @samp 8859@item all 8860Deinterlace all frames, 8861@item interlaced 8862Only deinterlace frames marked as interlaced. 8863@end table 8864 8865Default value is @samp{all}. 8866@end table 8867 8868@anchor{yadif} 8869@section yadif 8870 8871Deinterlace the input video ("yadif" means "yet another deinterlacing 8872filter"). 8873 8874It accepts the following parameters: 8875 8876 8877@table @option 8878 8879@item mode 8880The interlacing mode to adopt. It accepts one of the following values: 8881 8882@table @option 8883@item 0, send_frame 8884Output one frame for each frame. 8885@item 1, send_field 8886Output one frame for each field. 8887@item 2, send_frame_nospatial 8888Like @code{send_frame}, but it skips the spatial interlacing check. 8889@item 3, send_field_nospatial 8890Like @code{send_field}, but it skips the spatial interlacing check. 8891@end table 8892 8893The default value is @code{send_frame}. 8894 8895@item parity 8896The picture field parity assumed for the input interlaced video. It accepts one 8897of the following values: 8898 8899@table @option 8900@item 0, tff 8901Assume the top field is first. 8902@item 1, bff 8903Assume the bottom field is first. 8904@item -1, auto 8905Enable automatic detection of field parity. 8906@end table 8907 8908The default value is @code{auto}. 8909If the interlacing is unknown or the decoder does not export this information, 8910top field first will be assumed. 8911 8912@item deint 8913Specify which frames to deinterlace. Accept one of the following 8914values: 8915 8916@table @option 8917@item 0, all 8918Deinterlace all frames. 8919@item 1, interlaced 8920Only deinterlace frames marked as interlaced. 8921@end table 8922 8923The default value is @code{all}. 8924@end table 8925 8926@section zoompan 8927 8928Apply Zoom & Pan effect. 8929 8930This filter accepts the following options: 8931 8932@table @option 8933@item zoom, z 8934Set the zoom expression. Default is 1. 8935 8936@item x 8937@item y 8938Set the x and y expression. Default is 0. 8939 8940@item d 8941Set the duration expression in number of frames. 8942This sets for how many number of frames effect will last for 8943single input image. 8944 8945@item s 8946Set the output image size, default is 'hd720'. 8947@end table 8948 8949Each expression can contain the following constants: 8950 8951@table @option 8952@item in_w, iw 8953Input width. 8954 8955@item in_h, ih 8956Input height. 8957 8958@item out_w, ow 8959Output width. 8960 8961@item out_h, oh 8962Output height. 8963 8964@item in 8965Input frame count. 8966 8967@item on 8968Output frame count. 8969 8970@item x 8971@item y 8972Last calculated 'x' and 'y' position from 'x' and 'y' expression 8973for current input frame. 8974 8975@item px 8976@item py 8977'x' and 'y' of last output frame of previous input frame or 0 when there was 8978not yet such frame (first input frame). 8979 8980@item zoom 8981Last calculated zoom from 'z' expression for current input frame. 8982 8983@item pzoom 8984Last calculated zoom of last output frame of previous input frame. 8985 8986@item duration 8987Number of output frames for current input frame. Calculated from 'd' expression 8988for each input frame. 8989 8990@item pduration 8991number of output frames created for previous input frame 8992 8993@item a 8994Rational number: input width / input height 8995 8996@item sar 8997sample aspect ratio 8998 8999@item dar 9000display aspect ratio 9001 9002@end table 9003 9004@subsection Examples 9005 9006@itemize 9007@item 9008Zoom-in up to 1.5 and pan at same time to some spot near center of picture: 9009@example 9010zoompan=z='min(zoom+0.0015,1.5)':d=700:x='if(gte(zoom,1.5),x,x+1/a)':y='if(gte(zoom,1.5),y,y+1)':s=640x360 9011@end example 9012@end itemize 9013 9014@c man end VIDEO FILTERS 9015 9016@chapter Video Sources 9017@c man begin VIDEO SOURCES 9018 9019Below is a description of the currently available video sources. 9020 9021@section buffer 9022 9023Buffer video frames, and make them available to the filter chain. 9024 9025This source is mainly intended for a programmatic use, in particular 9026through the interface defined in @file{libavfilter/vsrc_buffer.h}. 9027 9028It accepts the following parameters: 9029 9030@table @option 9031 9032@item video_size 9033Specify the size (width and height) of the buffered video frames. For the 9034syntax of this option, check the "Video size" section in the ffmpeg-utils 9035manual. 9036 9037@item width 9038The input video width. 9039 9040@item height 9041The input video height. 9042 9043@item pix_fmt 9044A string representing the pixel format of the buffered video frames. 9045It may be a number corresponding to a pixel format, or a pixel format 9046name. 9047 9048@item time_base 9049Specify the timebase assumed by the timestamps of the buffered frames. 9050 9051@item frame_rate 9052Specify the frame rate expected for the video stream. 9053 9054@item pixel_aspect, sar 9055The sample (pixel) aspect ratio of the input video. 9056 9057@item sws_param 9058Specify the optional parameters to be used for the scale filter which 9059is automatically inserted when an input change is detected in the 9060input size or format. 9061@end table 9062 9063For example: 9064@example 9065buffer=width=320:height=240:pix_fmt=yuv410p:time_base=1/24:sar=1 9066@end example 9067 9068will instruct the source to accept video frames with size 320x240 and 9069with format "yuv410p", assuming 1/24 as the timestamps timebase and 9070square pixels (1:1 sample aspect ratio). 9071Since the pixel format with name "yuv410p" corresponds to the number 6 9072(check the enum AVPixelFormat definition in @file{libavutil/pixfmt.h}), 9073this example corresponds to: 9074@example 9075buffer=size=320x240:pixfmt=6:time_base=1/24:pixel_aspect=1/1 9076@end example 9077 9078Alternatively, the options can be specified as a flat string, but this 9079syntax is deprecated: 9080 9081@var{width}:@var{height}:@var{pix_fmt}:@var{time_base.num}:@var{time_base.den}:@var{pixel_aspect.num}:@var{pixel_aspect.den}[:@var{sws_param}] 9082 9083@section cellauto 9084 9085Create a pattern generated by an elementary cellular automaton. 9086 9087The initial state of the cellular automaton can be defined through the 9088@option{filename}, and @option{pattern} options. If such options are 9089not specified an initial state is created randomly. 9090 9091At each new frame a new row in the video is filled with the result of 9092the cellular automaton next generation. The behavior when the whole 9093frame is filled is defined by the @option{scroll} option. 9094 9095This source accepts the following options: 9096 9097@table @option 9098@item filename, f 9099Read the initial cellular automaton state, i.e. the starting row, from 9100the specified file. 9101In the file, each non-whitespace character is considered an alive 9102cell, a newline will terminate the row, and further characters in the 9103file will be ignored. 9104 9105@item pattern, p 9106Read the initial cellular automaton state, i.e. the starting row, from 9107the specified string. 9108 9109Each non-whitespace character in the string is considered an alive 9110cell, a newline will terminate the row, and further characters in the 9111string will be ignored. 9112 9113@item rate, r 9114Set the video rate, that is the number of frames generated per second. 9115Default is 25. 9116 9117@item random_fill_ratio, ratio 9118Set the random fill ratio for the initial cellular automaton row. It 9119is a floating point number value ranging from 0 to 1, defaults to 91201/PHI. 9121 9122This option is ignored when a file or a pattern is specified. 9123 9124@item random_seed, seed 9125Set the seed for filling randomly the initial row, must be an integer 9126included between 0 and UINT32_MAX. If not specified, or if explicitly 9127set to -1, the filter will try to use a good random seed on a best 9128effort basis. 9129 9130@item rule 9131Set the cellular automaton rule, it is a number ranging from 0 to 255. 9132Default value is 110. 9133 9134@item size, s 9135Set the size of the output video. For the syntax of this option, check 9136the "Video size" section in the ffmpeg-utils manual. 9137 9138If @option{filename} or @option{pattern} is specified, the size is set 9139by default to the width of the specified initial state row, and the 9140height is set to @var{width} * PHI. 9141 9142If @option{size} is set, it must contain the width of the specified 9143pattern string, and the specified pattern will be centered in the 9144larger row. 9145 9146If a filename or a pattern string is not specified, the size value 9147defaults to "320x518" (used for a randomly generated initial state). 9148 9149@item scroll 9150If set to 1, scroll the output upward when all the rows in the output 9151have been already filled. If set to 0, the new generated row will be 9152written over the top row just after the bottom row is filled. 9153Defaults to 1. 9154 9155@item start_full, full 9156If set to 1, completely fill the output with generated rows before 9157outputting the first frame. 9158This is the default behavior, for disabling set the value to 0. 9159 9160@item stitch 9161If set to 1, stitch the left and right row edges together. 9162This is the default behavior, for disabling set the value to 0. 9163@end table 9164 9165@subsection Examples 9166 9167@itemize 9168@item 9169Read the initial state from @file{pattern}, and specify an output of 9170size 200x400. 9171@example 9172cellauto=f=pattern:s=200x400 9173@end example 9174 9175@item 9176Generate a random initial row with a width of 200 cells, with a fill 9177ratio of 2/3: 9178@example 9179cellauto=ratio=2/3:s=200x200 9180@end example 9181 9182@item 9183Create a pattern generated by rule 18 starting by a single alive cell 9184centered on an initial row with width 100: 9185@example 9186cellauto=p=@@:s=100x400:full=0:rule=18 9187@end example 9188 9189@item 9190Specify a more elaborated initial pattern: 9191@example 9192cellauto=p='@@@@ @@ @@@@':s=100x400:full=0:rule=18 9193@end example 9194 9195@end itemize 9196 9197@section mandelbrot 9198 9199Generate a Mandelbrot set fractal, and progressively zoom towards the 9200point specified with @var{start_x} and @var{start_y}. 9201 9202This source accepts the following options: 9203 9204@table @option 9205 9206@item end_pts 9207Set the terminal pts value. Default value is 400. 9208 9209@item end_scale 9210Set the terminal scale value. 9211Must be a floating point value. Default value is 0.3. 9212 9213@item inner 9214Set the inner coloring mode, that is the algorithm used to draw the 9215Mandelbrot fractal internal region. 9216 9217It shall assume one of the following values: 9218@table @option 9219@item black 9220Set black mode. 9221@item convergence 9222Show time until convergence. 9223@item mincol 9224Set color based on point closest to the origin of the iterations. 9225@item period 9226Set period mode. 9227@end table 9228 9229Default value is @var{mincol}. 9230 9231@item bailout 9232Set the bailout value. Default value is 10.0. 9233 9234@item maxiter 9235Set the maximum of iterations performed by the rendering 9236algorithm. Default value is 7189. 9237 9238@item outer 9239Set outer coloring mode. 9240It shall assume one of following values: 9241@table @option 9242@item iteration_count 9243Set iteration cound mode. 9244@item normalized_iteration_count 9245set normalized iteration count mode. 9246@end table 9247Default value is @var{normalized_iteration_count}. 9248 9249@item rate, r 9250Set frame rate, expressed as number of frames per second. Default 9251value is "25". 9252 9253@item size, s 9254Set frame size. For the syntax of this option, check the "Video 9255size" section in the ffmpeg-utils manual. Default value is "640x480". 9256 9257@item start_scale 9258Set the initial scale value. Default value is 3.0. 9259 9260@item start_x 9261Set the initial x position. Must be a floating point value between 9262-100 and 100. Default value is -0.743643887037158704752191506114774. 9263 9264@item start_y 9265Set the initial y position. Must be a floating point value between 9266-100 and 100. Default value is -0.131825904205311970493132056385139. 9267@end table 9268 9269@section mptestsrc 9270 9271Generate various test patterns, as generated by the MPlayer test filter. 9272 9273The size of the generated video is fixed, and is 256x256. 9274This source is useful in particular for testing encoding features. 9275 9276This source accepts the following options: 9277 9278@table @option 9279 9280@item rate, r 9281Specify the frame rate of the sourced video, as the number of frames 9282generated per second. It has to be a string in the format 9283@var{frame_rate_num}/@var{frame_rate_den}, an integer number, a floating point 9284number or a valid video frame rate abbreviation. The default value is 9285"25". 9286 9287@item duration, d 9288Set the video duration of the sourced video. The accepted syntax is: 9289@example 9290[-]HH:MM:SS[.m...] 9291[-]S+[.m...] 9292@end example 9293See also the function @code{av_parse_time()}. 9294 9295If not specified, or the expressed duration is negative, the video is 9296supposed to be generated forever. 9297 9298@item test, t 9299 9300Set the number or the name of the test to perform. Supported tests are: 9301@table @option 9302@item dc_luma 9303@item dc_chroma 9304@item freq_luma 9305@item freq_chroma 9306@item amp_luma 9307@item amp_chroma 9308@item cbp 9309@item mv 9310@item ring1 9311@item ring2 9312@item all 9313 9314@end table 9315 9316Default value is "all", which will cycle through the list of all tests. 9317@end table 9318 9319Some examples: 9320@example 9321mptestsrc=t=dc_luma 9322@end example 9323 9324will generate a "dc_luma" test pattern. 9325 9326@section frei0r_src 9327 9328Provide a frei0r source. 9329 9330To enable compilation of this filter you need to install the frei0r 9331header and configure FFmpeg with @code{--enable-frei0r}. 9332 9333This source accepts the following parameters: 9334 9335@table @option 9336 9337@item size 9338The size of the video to generate. For the syntax of this option, check the 9339"Video size" section in the ffmpeg-utils manual. 9340 9341@item framerate 9342The framerate of the generated video. It may be a string of the form 9343@var{num}/@var{den} or a frame rate abbreviation. 9344 9345@item filter_name 9346The name to the frei0r source to load. For more information regarding frei0r and 9347how to set the parameters, read the @ref{frei0r} section in the video filters 9348documentation. 9349 9350@item filter_params 9351A '|'-separated list of parameters to pass to the frei0r source. 9352 9353@end table 9354 9355For example, to generate a frei0r partik0l source with size 200x200 9356and frame rate 10 which is overlayed on the overlay filter main input: 9357@example 9358frei0r_src=size=200x200:framerate=10:filter_name=partik0l:filter_params=1234 [overlay]; [in][overlay] overlay 9359@end example 9360 9361@section life 9362 9363Generate a life pattern. 9364 9365This source is based on a generalization of John Conway's life game. 9366 9367The sourced input represents a life grid, each pixel represents a cell 9368which can be in one of two possible states, alive or dead. Every cell 9369interacts with its eight neighbours, which are the cells that are 9370horizontally, vertically, or diagonally adjacent. 9371 9372At each interaction the grid evolves according to the adopted rule, 9373which specifies the number of neighbor alive cells which will make a 9374cell stay alive or born. The @option{rule} option allows one to specify 9375the rule to adopt. 9376 9377This source accepts the following options: 9378 9379@table @option 9380@item filename, f 9381Set the file from which to read the initial grid state. In the file, 9382each non-whitespace character is considered an alive cell, and newline 9383is used to delimit the end of each row. 9384 9385If this option is not specified, the initial grid is generated 9386randomly. 9387 9388@item rate, r 9389Set the video rate, that is the number of frames generated per second. 9390Default is 25. 9391 9392@item random_fill_ratio, ratio 9393Set the random fill ratio for the initial random grid. It is a 9394floating point number value ranging from 0 to 1, defaults to 1/PHI. 9395It is ignored when a file is specified. 9396 9397@item random_seed, seed 9398Set the seed for filling the initial random grid, must be an integer 9399included between 0 and UINT32_MAX. If not specified, or if explicitly 9400set to -1, the filter will try to use a good random seed on a best 9401effort basis. 9402 9403@item rule 9404Set the life rule. 9405 9406A rule can be specified with a code of the kind "S@var{NS}/B@var{NB}", 9407where @var{NS} and @var{NB} are sequences of numbers in the range 0-8, 9408@var{NS} specifies the number of alive neighbor cells which make a 9409live cell stay alive, and @var{NB} the number of alive neighbor cells 9410which make a dead cell to become alive (i.e. to "born"). 9411"s" and "b" can be used in place of "S" and "B", respectively. 9412 9413Alternatively a rule can be specified by an 18-bits integer. The 9 9414high order bits are used to encode the next cell state if it is alive 9415for each number of neighbor alive cells, the low order bits specify 9416the rule for "borning" new cells. Higher order bits encode for an 9417higher number of neighbor cells. 9418For example the number 6153 = @code{(12<<9)+9} specifies a stay alive 9419rule of 12 and a born rule of 9, which corresponds to "S23/B03". 9420 9421Default value is "S23/B3", which is the original Conway's game of life 9422rule, and will keep a cell alive if it has 2 or 3 neighbor alive 9423cells, and will born a new cell if there are three alive cells around 9424a dead cell. 9425 9426@item size, s 9427Set the size of the output video. For the syntax of this option, check the 9428"Video size" section in the ffmpeg-utils manual. 9429 9430If @option{filename} is specified, the size is set by default to the 9431same size of the input file. If @option{size} is set, it must contain 9432the size specified in the input file, and the initial grid defined in 9433that file is centered in the larger resulting area. 9434 9435If a filename is not specified, the size value defaults to "320x240" 9436(used for a randomly generated initial grid). 9437 9438@item stitch 9439If set to 1, stitch the left and right grid edges together, and the 9440top and bottom edges also. Defaults to 1. 9441 9442@item mold 9443Set cell mold speed. If set, a dead cell will go from @option{death_color} to 9444@option{mold_color} with a step of @option{mold}. @option{mold} can have a 9445value from 0 to 255. 9446 9447@item life_color 9448Set the color of living (or new born) cells. 9449 9450@item death_color 9451Set the color of dead cells. If @option{mold} is set, this is the first color 9452used to represent a dead cell. 9453 9454@item mold_color 9455Set mold color, for definitely dead and moldy cells. 9456 9457For the syntax of these 3 color options, check the "Color" section in the 9458ffmpeg-utils manual. 9459@end table 9460 9461@subsection Examples 9462 9463@itemize 9464@item 9465Read a grid from @file{pattern}, and center it on a grid of size 9466300x300 pixels: 9467@example 9468life=f=pattern:s=300x300 9469@end example 9470 9471@item 9472Generate a random grid of size 200x200, with a fill ratio of 2/3: 9473@example 9474life=ratio=2/3:s=200x200 9475@end example 9476 9477@item 9478Specify a custom rule for evolving a randomly generated grid: 9479@example 9480life=rule=S14/B34 9481@end example 9482 9483@item 9484Full example with slow death effect (mold) using @command{ffplay}: 9485@example 9486ffplay -f lavfi life=s=300x200:mold=10:r=60:ratio=0.1:death_color=#C83232:life_color=#00ff00,scale=1200:800:flags=16 9487@end example 9488@end itemize 9489 9490@anchor{color} 9491@anchor{haldclutsrc} 9492@anchor{nullsrc} 9493@anchor{rgbtestsrc} 9494@anchor{smptebars} 9495@anchor{smptehdbars} 9496@anchor{testsrc} 9497@section color, haldclutsrc, nullsrc, rgbtestsrc, smptebars, smptehdbars, testsrc 9498 9499The @code{color} source provides an uniformly colored input. 9500 9501The @code{haldclutsrc} source provides an identity Hald CLUT. See also 9502@ref{haldclut} filter. 9503 9504The @code{nullsrc} source returns unprocessed video frames. It is 9505mainly useful to be employed in analysis / debugging tools, or as the 9506source for filters which ignore the input data. 9507 9508The @code{rgbtestsrc} source generates an RGB test pattern useful for 9509detecting RGB vs BGR issues. You should see a red, green and blue 9510stripe from top to bottom. 9511 9512The @code{smptebars} source generates a color bars pattern, based on 9513the SMPTE Engineering Guideline EG 1-1990. 9514 9515The @code{smptehdbars} source generates a color bars pattern, based on 9516the SMPTE RP 219-2002. 9517 9518The @code{testsrc} source generates a test video pattern, showing a 9519color pattern, a scrolling gradient and a timestamp. This is mainly 9520intended for testing purposes. 9521 9522The sources accept the following parameters: 9523 9524@table @option 9525 9526@item color, c 9527Specify the color of the source, only available in the @code{color} 9528source. For the syntax of this option, check the "Color" section in the 9529ffmpeg-utils manual. 9530 9531@item level 9532Specify the level of the Hald CLUT, only available in the @code{haldclutsrc} 9533source. A level of @code{N} generates a picture of @code{N*N*N} by @code{N*N*N} 9534pixels to be used as identity matrix for 3D lookup tables. Each component is 9535coded on a @code{1/(N*N)} scale. 9536 9537@item size, s 9538Specify the size of the sourced video. For the syntax of this option, check the 9539"Video size" section in the ffmpeg-utils manual. The default value is 9540"320x240". 9541 9542This option is not available with the @code{haldclutsrc} filter. 9543 9544@item rate, r 9545Specify the frame rate of the sourced video, as the number of frames 9546generated per second. It has to be a string in the format 9547@var{frame_rate_num}/@var{frame_rate_den}, an integer number, a floating point 9548number or a valid video frame rate abbreviation. The default value is 9549"25". 9550 9551@item sar 9552Set the sample aspect ratio of the sourced video. 9553 9554@item duration, d 9555Set the video duration of the sourced video. The accepted syntax is: 9556@example 9557[-]HH[:MM[:SS[.m...]]] 9558[-]S+[.m...] 9559@end example 9560Also see the the @code{av_parse_time()} function. 9561 9562If not specified, or the expressed duration is negative, the video is 9563supposed to be generated forever. 9564 9565@item decimals, n 9566Set the number of decimals to show in the timestamp, only available in the 9567@code{testsrc} source. 9568 9569The displayed timestamp value will correspond to the original 9570timestamp value multiplied by the power of 10 of the specified 9571value. Default value is 0. 9572@end table 9573 9574For example the following: 9575@example 9576testsrc=duration=5.3:size=qcif:rate=10 9577@end example 9578 9579will generate a video with a duration of 5.3 seconds, with size 9580176x144 and a frame rate of 10 frames per second. 9581 9582The following graph description will generate a red source 9583with an opacity of 0.2, with size "qcif" and a frame rate of 10 9584frames per second. 9585@example 9586color=c=red@@0.2:s=qcif:r=10 9587@end example 9588 9589If the input content is to be ignored, @code{nullsrc} can be used. The 9590following command generates noise in the luminance plane by employing 9591the @code{geq} filter: 9592@example 9593nullsrc=s=256x256, geq=random(1)*255:128:128 9594@end example 9595 9596@subsection Commands 9597 9598The @code{color} source supports the following commands: 9599 9600@table @option 9601@item c, color 9602Set the color of the created image. Accepts the same syntax of the 9603corresponding @option{color} option. 9604@end table 9605 9606@c man end VIDEO SOURCES 9607 9608@chapter Video Sinks 9609@c man begin VIDEO SINKS 9610 9611Below is a description of the currently available video sinks. 9612 9613@section buffersink 9614 9615Buffer video frames, and make them available to the end of the filter 9616graph. 9617 9618This sink is mainly intended for programmatic use, in particular 9619through the interface defined in @file{libavfilter/buffersink.h} 9620or the options system. 9621 9622It accepts a pointer to an AVBufferSinkContext structure, which 9623defines the incoming buffers' formats, to be passed as the opaque 9624parameter to @code{avfilter_init_filter} for initialization. 9625 9626@section nullsink 9627 9628Null video sink: do absolutely nothing with the input video. It is 9629mainly useful as a template and for use in analysis / debugging 9630tools. 9631 9632@c man end VIDEO SINKS 9633 9634@chapter Multimedia Filters 9635@c man begin MULTIMEDIA FILTERS 9636 9637Below is a description of the currently available multimedia filters. 9638 9639@section avectorscope 9640 9641Convert input audio to a video output, representing the audio vector 9642scope. 9643 9644The filter is used to measure the difference between channels of stereo 9645audio stream. A monoaural signal, consisting of identical left and right 9646signal, results in straight vertical line. Any stereo separation is visible 9647as a deviation from this line, creating a Lissajous figure. 9648If the straight (or deviation from it) but horizontal line appears this 9649indicates that the left and right channels are out of phase. 9650 9651The filter accepts the following options: 9652 9653@table @option 9654@item mode, m 9655Set the vectorscope mode. 9656 9657Available values are: 9658@table @samp 9659@item lissajous 9660Lissajous rotated by 45 degrees. 9661 9662@item lissajous_xy 9663Same as above but not rotated. 9664@end table 9665 9666Default value is @samp{lissajous}. 9667 9668@item size, s 9669Set the video size for the output. For the syntax of this option, check the "Video size" 9670section in the ffmpeg-utils manual. Default value is @code{400x400}. 9671 9672@item rate, r 9673Set the output frame rate. Default value is @code{25}. 9674 9675@item rc 9676@item gc 9677@item bc 9678Specify the red, green and blue contrast. Default values are @code{40}, @code{160} and @code{80}. 9679Allowed range is @code{[0, 255]}. 9680 9681@item rf 9682@item gf 9683@item bf 9684Specify the red, green and blue fade. Default values are @code{15}, @code{10} and @code{5}. 9685Allowed range is @code{[0, 255]}. 9686 9687@item zoom 9688Set the zoom factor. Default value is @code{1}. Allowed range is @code{[1, 10]}. 9689@end table 9690 9691@subsection Examples 9692 9693@itemize 9694@item 9695Complete example using @command{ffplay}: 9696@example 9697ffplay -f lavfi 'amovie=input.mp3, asplit [a][out1]; 9698 [a] avectorscope=zoom=1.3:rc=2:gc=200:bc=10:rf=1:gf=8:bf=7 [out0]' 9699@end example 9700@end itemize 9701 9702@section concat 9703 9704Concatenate audio and video streams, joining them together one after the 9705other. 9706 9707The filter works on segments of synchronized video and audio streams. All 9708segments must have the same number of streams of each type, and that will 9709also be the number of streams at output. 9710 9711The filter accepts the following options: 9712 9713@table @option 9714 9715@item n 9716Set the number of segments. Default is 2. 9717 9718@item v 9719Set the number of output video streams, that is also the number of video 9720streams in each segment. Default is 1. 9721 9722@item a 9723Set the number of output audio streams, that is also the number of audio 9724streams in each segment. Default is 0. 9725 9726@item unsafe 9727Activate unsafe mode: do not fail if segments have a different format. 9728 9729@end table 9730 9731The filter has @var{v}+@var{a} outputs: first @var{v} video outputs, then 9732@var{a} audio outputs. 9733 9734There are @var{n}x(@var{v}+@var{a}) inputs: first the inputs for the first 9735segment, in the same order as the outputs, then the inputs for the second 9736segment, etc. 9737 9738Related streams do not always have exactly the same duration, for various 9739reasons including codec frame size or sloppy authoring. For that reason, 9740related synchronized streams (e.g. a video and its audio track) should be 9741concatenated at once. The concat filter will use the duration of the longest 9742stream in each segment (except the last one), and if necessary pad shorter 9743audio streams with silence. 9744 9745For this filter to work correctly, all segments must start at timestamp 0. 9746 9747All corresponding streams must have the same parameters in all segments; the 9748filtering system will automatically select a common pixel format for video 9749streams, and a common sample format, sample rate and channel layout for 9750audio streams, but other settings, such as resolution, must be converted 9751explicitly by the user. 9752 9753Different frame rates are acceptable but will result in variable frame rate 9754at output; be sure to configure the output file to handle it. 9755 9756@subsection Examples 9757 9758@itemize 9759@item 9760Concatenate an opening, an episode and an ending, all in bilingual version 9761(video in stream 0, audio in streams 1 and 2): 9762@example 9763ffmpeg -i opening.mkv -i episode.mkv -i ending.mkv -filter_complex \ 9764 '[0:0] [0:1] [0:2] [1:0] [1:1] [1:2] [2:0] [2:1] [2:2] 9765 concat=n=3:v=1:a=2 [v] [a1] [a2]' \ 9766 -map '[v]' -map '[a1]' -map '[a2]' output.mkv 9767@end example 9768 9769@item 9770Concatenate two parts, handling audio and video separately, using the 9771(a)movie sources, and adjusting the resolution: 9772@example 9773movie=part1.mp4, scale=512:288 [v1] ; amovie=part1.mp4 [a1] ; 9774movie=part2.mp4, scale=512:288 [v2] ; amovie=part2.mp4 [a2] ; 9775[v1] [v2] concat [outv] ; [a1] [a2] concat=v=0:a=1 [outa] 9776@end example 9777Note that a desync will happen at the stitch if the audio and video streams 9778do not have exactly the same duration in the first file. 9779 9780@end itemize 9781 9782@section ebur128 9783 9784EBU R128 scanner filter. This filter takes an audio stream as input and outputs 9785it unchanged. By default, it logs a message at a frequency of 10Hz with the 9786Momentary loudness (identified by @code{M}), Short-term loudness (@code{S}), 9787Integrated loudness (@code{I}) and Loudness Range (@code{LRA}). 9788 9789The filter also has a video output (see the @var{video} option) with a real 9790time graph to observe the loudness evolution. The graphic contains the logged 9791message mentioned above, so it is not printed anymore when this option is set, 9792unless the verbose logging is set. The main graphing area contains the 9793short-term loudness (3 seconds of analysis), and the gauge on the right is for 9794the momentary loudness (400 milliseconds). 9795 9796More information about the Loudness Recommendation EBU R128 on 9797@url{http://tech.ebu.ch/loudness}. 9798 9799The filter accepts the following options: 9800 9801@table @option 9802 9803@item video 9804Activate the video output. The audio stream is passed unchanged whether this 9805option is set or no. The video stream will be the first output stream if 9806activated. Default is @code{0}. 9807 9808@item size 9809Set the video size. This option is for video only. For the syntax of this 9810option, check the "Video size" section in the ffmpeg-utils manual. Default 9811and minimum resolution is @code{640x480}. 9812 9813@item meter 9814Set the EBU scale meter. Default is @code{9}. Common values are @code{9} and 9815@code{18}, respectively for EBU scale meter +9 and EBU scale meter +18. Any 9816other integer value between this range is allowed. 9817 9818@item metadata 9819Set metadata injection. If set to @code{1}, the audio input will be segmented 9820into 100ms output frames, each of them containing various loudness information 9821in metadata. All the metadata keys are prefixed with @code{lavfi.r128.}. 9822 9823Default is @code{0}. 9824 9825@item framelog 9826Force the frame logging level. 9827 9828Available values are: 9829@table @samp 9830@item info 9831information logging level 9832@item verbose 9833verbose logging level 9834@end table 9835 9836By default, the logging level is set to @var{info}. If the @option{video} or 9837the @option{metadata} options are set, it switches to @var{verbose}. 9838 9839@item peak 9840Set peak mode(s). 9841 9842Available modes can be cumulated (the option is a @code{flag} type). Possible 9843values are: 9844@table @samp 9845@item none 9846Disable any peak mode (default). 9847@item sample 9848Enable sample-peak mode. 9849 9850Simple peak mode looking for the higher sample value. It logs a message 9851for sample-peak (identified by @code{SPK}). 9852@item true 9853Enable true-peak mode. 9854 9855If enabled, the peak lookup is done on an over-sampled version of the input 9856stream for better peak accuracy. It logs a message for true-peak. 9857(identified by @code{TPK}) and true-peak per frame (identified by @code{FTPK}). 9858This mode requires a build with @code{libswresample}. 9859@end table 9860 9861@end table 9862 9863@subsection Examples 9864 9865@itemize 9866@item 9867Real-time graph using @command{ffplay}, with a EBU scale meter +18: 9868@example 9869ffplay -f lavfi -i "amovie=input.mp3,ebur128=video=1:meter=18 [out0][out1]" 9870@end example 9871 9872@item 9873Run an analysis with @command{ffmpeg}: 9874@example 9875ffmpeg -nostats -i input.mp3 -filter_complex ebur128 -f null - 9876@end example 9877@end itemize 9878 9879@section interleave, ainterleave 9880 9881Temporally interleave frames from several inputs. 9882 9883@code{interleave} works with video inputs, @code{ainterleave} with audio. 9884 9885These filters read frames from several inputs and send the oldest 9886queued frame to the output. 9887 9888Input streams must have a well defined, monotonically increasing frame 9889timestamp values. 9890 9891In order to submit one frame to output, these filters need to enqueue 9892at least one frame for each input, so they cannot work in case one 9893input is not yet terminated and will not receive incoming frames. 9894 9895For example consider the case when one input is a @code{select} filter 9896which always drop input frames. The @code{interleave} filter will keep 9897reading from that input, but it will never be able to send new frames 9898to output until the input will send an end-of-stream signal. 9899 9900Also, depending on inputs synchronization, the filters will drop 9901frames in case one input receives more frames than the other ones, and 9902the queue is already filled. 9903 9904These filters accept the following options: 9905 9906@table @option 9907@item nb_inputs, n 9908Set the number of different inputs, it is 2 by default. 9909@end table 9910 9911@subsection Examples 9912 9913@itemize 9914@item 9915Interleave frames belonging to different streams using @command{ffmpeg}: 9916@example 9917ffmpeg -i bambi.avi -i pr0n.mkv -filter_complex "[0:v][1:v] interleave" out.avi 9918@end example 9919 9920@item 9921Add flickering blur effect: 9922@example 9923select='if(gt(random(0), 0.2), 1, 2)':n=2 [tmp], boxblur=2:2, [tmp] interleave 9924@end example 9925@end itemize 9926 9927@section perms, aperms 9928 9929Set read/write permissions for the output frames. 9930 9931These filters are mainly aimed at developers to test direct path in the 9932following filter in the filtergraph. 9933 9934The filters accept the following options: 9935 9936@table @option 9937@item mode 9938Select the permissions mode. 9939 9940It accepts the following values: 9941@table @samp 9942@item none 9943Do nothing. This is the default. 9944@item ro 9945Set all the output frames read-only. 9946@item rw 9947Set all the output frames directly writable. 9948@item toggle 9949Make the frame read-only if writable, and writable if read-only. 9950@item random 9951Set each output frame read-only or writable randomly. 9952@end table 9953 9954@item seed 9955Set the seed for the @var{random} mode, must be an integer included between 9956@code{0} and @code{UINT32_MAX}. If not specified, or if explicitly set to 9957@code{-1}, the filter will try to use a good random seed on a best effort 9958basis. 9959@end table 9960 9961Note: in case of auto-inserted filter between the permission filter and the 9962following one, the permission might not be received as expected in that 9963following filter. Inserting a @ref{format} or @ref{aformat} filter before the 9964perms/aperms filter can avoid this problem. 9965 9966@section select, aselect 9967 9968Select frames to pass in output. 9969 9970This filter accepts the following options: 9971 9972@table @option 9973 9974@item expr, e 9975Set expression, which is evaluated for each input frame. 9976 9977If the expression is evaluated to zero, the frame is discarded. 9978 9979If the evaluation result is negative or NaN, the frame is sent to the 9980first output; otherwise it is sent to the output with index 9981@code{ceil(val)-1}, assuming that the input index starts from 0. 9982 9983For example a value of @code{1.2} corresponds to the output with index 9984@code{ceil(1.2)-1 = 2-1 = 1}, that is the second output. 9985 9986@item outputs, n 9987Set the number of outputs. The output to which to send the selected 9988frame is based on the result of the evaluation. Default value is 1. 9989@end table 9990 9991The expression can contain the following constants: 9992 9993@table @option 9994@item n 9995The (sequential) number of the filtered frame, starting from 0. 9996 9997@item selected_n 9998The (sequential) number of the selected frame, starting from 0. 9999 10000@item prev_selected_n 10001The sequential number of the last selected frame. It's NAN if undefined. 10002 10003@item TB 10004The timebase of the input timestamps. 10005 10006@item pts 10007The PTS (Presentation TimeStamp) of the filtered video frame, 10008expressed in @var{TB} units. It's NAN if undefined. 10009 10010@item t 10011The PTS of the filtered video frame, 10012expressed in seconds. It's NAN if undefined. 10013 10014@item prev_pts 10015The PTS of the previously filtered video frame. It's NAN if undefined. 10016 10017@item prev_selected_pts 10018The PTS of the last previously filtered video frame. It's NAN if undefined. 10019 10020@item prev_selected_t 10021The PTS of the last previously selected video frame. It's NAN if undefined. 10022 10023@item start_pts 10024The PTS of the first video frame in the video. It's NAN if undefined. 10025 10026@item start_t 10027The time of the first video frame in the video. It's NAN if undefined. 10028 10029@item pict_type @emph{(video only)} 10030The type of the filtered frame. It can assume one of the following 10031values: 10032@table @option 10033@item I 10034@item P 10035@item B 10036@item S 10037@item SI 10038@item SP 10039@item BI 10040@end table 10041 10042@item interlace_type @emph{(video only)} 10043The frame interlace type. It can assume one of the following values: 10044@table @option 10045@item PROGRESSIVE 10046The frame is progressive (not interlaced). 10047@item TOPFIRST 10048The frame is top-field-first. 10049@item BOTTOMFIRST 10050The frame is bottom-field-first. 10051@end table 10052 10053@item consumed_sample_n @emph{(audio only)} 10054the number of selected samples before the current frame 10055 10056@item samples_n @emph{(audio only)} 10057the number of samples in the current frame 10058 10059@item sample_rate @emph{(audio only)} 10060the input sample rate 10061 10062@item key 10063This is 1 if the filtered frame is a key-frame, 0 otherwise. 10064 10065@item pos 10066the position in the file of the filtered frame, -1 if the information 10067is not available (e.g. for synthetic video) 10068 10069@item scene @emph{(video only)} 10070value between 0 and 1 to indicate a new scene; a low value reflects a low 10071probability for the current frame to introduce a new scene, while a higher 10072value means the current frame is more likely to be one (see the example below) 10073 10074@end table 10075 10076The default value of the select expression is "1". 10077 10078@subsection Examples 10079 10080@itemize 10081@item 10082Select all frames in input: 10083@example 10084select 10085@end example 10086 10087The example above is the same as: 10088@example 10089select=1 10090@end example 10091 10092@item 10093Skip all frames: 10094@example 10095select=0 10096@end example 10097 10098@item 10099Select only I-frames: 10100@example 10101select='eq(pict_type\,I)' 10102@end example 10103 10104@item 10105Select one frame every 100: 10106@example 10107select='not(mod(n\,100))' 10108@end example 10109 10110@item 10111Select only frames contained in the 10-20 time interval: 10112@example 10113select=between(t\,10\,20) 10114@end example 10115 10116@item 10117Select only I frames contained in the 10-20 time interval: 10118@example 10119select=between(t\,10\,20)*eq(pict_type\,I) 10120@end example 10121 10122@item 10123Select frames with a minimum distance of 10 seconds: 10124@example 10125select='isnan(prev_selected_t)+gte(t-prev_selected_t\,10)' 10126@end example 10127 10128@item 10129Use aselect to select only audio frames with samples number > 100: 10130@example 10131aselect='gt(samples_n\,100)' 10132@end example 10133 10134@item 10135Create a mosaic of the first scenes: 10136@example 10137ffmpeg -i video.avi -vf select='gt(scene\,0.4)',scale=160:120,tile -frames:v 1 preview.png 10138@end example 10139 10140Comparing @var{scene} against a value between 0.3 and 0.5 is generally a sane 10141choice. 10142 10143@item 10144Send even and odd frames to separate outputs, and compose them: 10145@example 10146select=n=2:e='mod(n, 2)+1' [odd][even]; [odd] pad=h=2*ih [tmp]; [tmp][even] overlay=y=h 10147@end example 10148@end itemize 10149 10150@section sendcmd, asendcmd 10151 10152Send commands to filters in the filtergraph. 10153 10154These filters read commands to be sent to other filters in the 10155filtergraph. 10156 10157@code{sendcmd} must be inserted between two video filters, 10158@code{asendcmd} must be inserted between two audio filters, but apart 10159from that they act the same way. 10160 10161The specification of commands can be provided in the filter arguments 10162with the @var{commands} option, or in a file specified by the 10163@var{filename} option. 10164 10165These filters accept the following options: 10166@table @option 10167@item commands, c 10168Set the commands to be read and sent to the other filters. 10169@item filename, f 10170Set the filename of the commands to be read and sent to the other 10171filters. 10172@end table 10173 10174@subsection Commands syntax 10175 10176A commands description consists of a sequence of interval 10177specifications, comprising a list of commands to be executed when a 10178particular event related to that interval occurs. The occurring event 10179is typically the current frame time entering or leaving a given time 10180interval. 10181 10182An interval is specified by the following syntax: 10183@example 10184@var{START}[-@var{END}] @var{COMMANDS}; 10185@end example 10186 10187The time interval is specified by the @var{START} and @var{END} times. 10188@var{END} is optional and defaults to the maximum time. 10189 10190The current frame time is considered within the specified interval if 10191it is included in the interval [@var{START}, @var{END}), that is when 10192the time is greater or equal to @var{START} and is lesser than 10193@var{END}. 10194 10195@var{COMMANDS} consists of a sequence of one or more command 10196specifications, separated by ",", relating to that interval. The 10197syntax of a command specification is given by: 10198@example 10199[@var{FLAGS}] @var{TARGET} @var{COMMAND} @var{ARG} 10200@end example 10201 10202@var{FLAGS} is optional and specifies the type of events relating to 10203the time interval which enable sending the specified command, and must 10204be a non-null sequence of identifier flags separated by "+" or "|" and 10205enclosed between "[" and "]". 10206 10207The following flags are recognized: 10208@table @option 10209@item enter 10210The command is sent when the current frame timestamp enters the 10211specified interval. In other words, the command is sent when the 10212previous frame timestamp was not in the given interval, and the 10213current is. 10214 10215@item leave 10216The command is sent when the current frame timestamp leaves the 10217specified interval. In other words, the command is sent when the 10218previous frame timestamp was in the given interval, and the 10219current is not. 10220@end table 10221 10222If @var{FLAGS} is not specified, a default value of @code{[enter]} is 10223assumed. 10224 10225@var{TARGET} specifies the target of the command, usually the name of 10226the filter class or a specific filter instance name. 10227 10228@var{COMMAND} specifies the name of the command for the target filter. 10229 10230@var{ARG} is optional and specifies the optional list of argument for 10231the given @var{COMMAND}. 10232 10233Between one interval specification and another, whitespaces, or 10234sequences of characters starting with @code{#} until the end of line, 10235are ignored and can be used to annotate comments. 10236 10237A simplified BNF description of the commands specification syntax 10238follows: 10239@example 10240@var{COMMAND_FLAG} ::= "enter" | "leave" 10241@var{COMMAND_FLAGS} ::= @var{COMMAND_FLAG} [(+|"|")@var{COMMAND_FLAG}] 10242@var{COMMAND} ::= ["[" @var{COMMAND_FLAGS} "]"] @var{TARGET} @var{COMMAND} [@var{ARG}] 10243@var{COMMANDS} ::= @var{COMMAND} [,@var{COMMANDS}] 10244@var{INTERVAL} ::= @var{START}[-@var{END}] @var{COMMANDS} 10245@var{INTERVALS} ::= @var{INTERVAL}[;@var{INTERVALS}] 10246@end example 10247 10248@subsection Examples 10249 10250@itemize 10251@item 10252Specify audio tempo change at second 4: 10253@example 10254asendcmd=c='4.0 atempo tempo 1.5',atempo 10255@end example 10256 10257@item 10258Specify a list of drawtext and hue commands in a file. 10259@example 10260# show text in the interval 5-10 102615.0-10.0 [enter] drawtext reinit 'fontfile=FreeSerif.ttf:text=hello world', 10262 [leave] drawtext reinit 'fontfile=FreeSerif.ttf:text='; 10263 10264# desaturate the image in the interval 15-20 1026515.0-20.0 [enter] hue s 0, 10266 [enter] drawtext reinit 'fontfile=FreeSerif.ttf:text=nocolor', 10267 [leave] hue s 1, 10268 [leave] drawtext reinit 'fontfile=FreeSerif.ttf:text=color'; 10269 10270# apply an exponential saturation fade-out effect, starting from time 25 1027125 [enter] hue s exp(25-t) 10272@end example 10273 10274A filtergraph allowing to read and process the above command list 10275stored in a file @file{test.cmd}, can be specified with: 10276@example 10277sendcmd=f=test.cmd,drawtext=fontfile=FreeSerif.ttf:text='',hue 10278@end example 10279@end itemize 10280 10281@anchor{setpts} 10282@section setpts, asetpts 10283 10284Change the PTS (presentation timestamp) of the input frames. 10285 10286@code{setpts} works on video frames, @code{asetpts} on audio frames. 10287 10288This filter accepts the following options: 10289 10290@table @option 10291 10292@item expr 10293The expression which is evaluated for each frame to construct its timestamp. 10294 10295@end table 10296 10297The expression is evaluated through the eval API and can contain the following 10298constants: 10299 10300@table @option 10301@item FRAME_RATE 10302frame rate, only defined for constant frame-rate video 10303 10304@item PTS 10305The presentation timestamp in input 10306 10307@item N 10308The count of the input frame for video or the number of consumed samples, 10309not including the current frame for audio, starting from 0. 10310 10311@item NB_CONSUMED_SAMPLES 10312The number of consumed samples, not including the current frame (only 10313audio) 10314 10315@item NB_SAMPLES, S 10316The number of samples in the current frame (only audio) 10317 10318@item SAMPLE_RATE, SR 10319The audio sample rate. 10320 10321@item STARTPTS 10322The PTS of the first frame. 10323 10324@item STARTT 10325the time in seconds of the first frame 10326 10327@item INTERLACED 10328State whether the current frame is interlaced. 10329 10330@item T 10331the time in seconds of the current frame 10332 10333@item POS 10334original position in the file of the frame, or undefined if undefined 10335for the current frame 10336 10337@item PREV_INPTS 10338The previous input PTS. 10339 10340@item PREV_INT 10341previous input time in seconds 10342 10343@item PREV_OUTPTS 10344The previous output PTS. 10345 10346@item PREV_OUTT 10347previous output time in seconds 10348 10349@item RTCTIME 10350The wallclock (RTC) time in microseconds.. This is deprecated, use time(0) 10351instead. 10352 10353@item RTCSTART 10354The wallclock (RTC) time at the start of the movie in microseconds. 10355 10356@item TB 10357The timebase of the input timestamps. 10358 10359@end table 10360 10361@subsection Examples 10362 10363@itemize 10364@item 10365Start counting PTS from zero 10366@example 10367setpts=PTS-STARTPTS 10368@end example 10369 10370@item 10371Apply fast motion effect: 10372@example 10373setpts=0.5*PTS 10374@end example 10375 10376@item 10377Apply slow motion effect: 10378@example 10379setpts=2.0*PTS 10380@end example 10381 10382@item 10383Set fixed rate of 25 frames per second: 10384@example 10385setpts=N/(25*TB) 10386@end example 10387 10388@item 10389Set fixed rate 25 fps with some jitter: 10390@example 10391setpts='1/(25*TB) * (N + 0.05 * sin(N*2*PI/25))' 10392@end example 10393 10394@item 10395Apply an offset of 10 seconds to the input PTS: 10396@example 10397setpts=PTS+10/TB 10398@end example 10399 10400@item 10401Generate timestamps from a "live source" and rebase onto the current timebase: 10402@example 10403setpts='(RTCTIME - RTCSTART) / (TB * 1000000)' 10404@end example 10405 10406@item 10407Generate timestamps by counting samples: 10408@example 10409asetpts=N/SR/TB 10410@end example 10411 10412@end itemize 10413 10414@section settb, asettb 10415 10416Set the timebase to use for the output frames timestamps. 10417It is mainly useful for testing timebase configuration. 10418 10419It accepts the following parameters: 10420 10421@table @option 10422 10423@item expr, tb 10424The expression which is evaluated into the output timebase. 10425 10426@end table 10427 10428The value for @option{tb} is an arithmetic expression representing a 10429rational. The expression can contain the constants "AVTB" (the default 10430timebase), "intb" (the input timebase) and "sr" (the sample rate, 10431audio only). Default value is "intb". 10432 10433@subsection Examples 10434 10435@itemize 10436@item 10437Set the timebase to 1/25: 10438@example 10439settb=expr=1/25 10440@end example 10441 10442@item 10443Set the timebase to 1/10: 10444@example 10445settb=expr=0.1 10446@end example 10447 10448@item 10449Set the timebase to 1001/1000: 10450@example 10451settb=1+0.001 10452@end example 10453 10454@item 10455Set the timebase to 2*intb: 10456@example 10457settb=2*intb 10458@end example 10459 10460@item 10461Set the default timebase value: 10462@example 10463settb=AVTB 10464@end example 10465@end itemize 10466 10467@section showcqt 10468Convert input audio to a video output representing 10469frequency spectrum logarithmically (using constant Q transform with 10470Brown-Puckette algorithm), with musical tone scale, from E0 to D#10 (10 octaves). 10471 10472The filter accepts the following options: 10473 10474@table @option 10475@item volume 10476Specify the transform volume (multiplier). Acceptable value is [1.0, 100.0]. 10477Default value is @code{16.0}. 10478 10479@item timeclamp 10480Specify the transform timeclamp. At low frequency, there is trade-off between 10481accuracy in time domain and frequency domain. If timeclamp is lower, 10482event in time domain is represented more accurately (such as fast bass drum), 10483otherwise event in frequency domain is represented more accurately 10484(such as bass guitar). Acceptable value is [0.1, 1.0]. Default value is @code{0.17}. 10485 10486@item coeffclamp 10487Specify the transform coeffclamp. If coeffclamp is lower, transform is 10488more accurate, otherwise transform is faster. Acceptable value is [0.1, 10.0]. 10489Default value is @code{1.0}. 10490 10491@item gamma 10492Specify gamma. Lower gamma makes the spectrum more contrast, higher gamma 10493makes the spectrum having more range. Acceptable value is [1.0, 7.0]. 10494Default value is @code{3.0}. 10495 10496@item fontfile 10497Specify font file for use with freetype. If not specified, use embedded font. 10498 10499@item fullhd 10500If set to 1 (the default), the video size is 1920x1080 (full HD), 10501if set to 0, the video size is 960x540. Use this option to make CPU usage lower. 10502 10503@item fps 10504Specify video fps. Default value is @code{25}. 10505 10506@item count 10507Specify number of transform per frame, so there are fps*count transforms 10508per second. Note that audio data rate must be divisible by fps*count. 10509Default value is @code{6}. 10510 10511@end table 10512 10513@subsection Examples 10514 10515@itemize 10516@item 10517Playing audio while showing the spectrum: 10518@example 10519ffplay -f lavfi 'amovie=a.mp3, asplit [a][out1]; [a] showcqt [out0]' 10520@end example 10521 10522@item 10523Same as above, but with frame rate 30 fps: 10524@example 10525ffplay -f lavfi 'amovie=a.mp3, asplit [a][out1]; [a] showcqt=fps=30:count=5 [out0]' 10526@end example 10527 10528@item 10529Playing at 960x540 and lower CPU usage: 10530@example 10531ffplay -f lavfi 'amovie=a.mp3, asplit [a][out1]; [a] showcqt=fullhd=0:count=3 [out0]' 10532@end example 10533 10534@item 10535A1 and its harmonics: A1, A2, (near)E3, A3: 10536@example 10537ffplay -f lavfi 'aevalsrc=0.1*sin(2*PI*55*t)+0.1*sin(4*PI*55*t)+0.1*sin(6*PI*55*t)+0.1*sin(8*PI*55*t), 10538 asplit[a][out1]; [a] showcqt [out0]' 10539@end example 10540 10541@item 10542Same as above, but with more accuracy in frequency domain (and slower): 10543@example 10544ffplay -f lavfi 'aevalsrc=0.1*sin(2*PI*55*t)+0.1*sin(4*PI*55*t)+0.1*sin(6*PI*55*t)+0.1*sin(8*PI*55*t), 10545 asplit[a][out1]; [a] showcqt=timeclamp=0.5 [out0]' 10546@end example 10547 10548@end itemize 10549 10550@section showspectrum 10551 10552Convert input audio to a video output, representing the audio frequency 10553spectrum. 10554 10555The filter accepts the following options: 10556 10557@table @option 10558@item size, s 10559Specify the video size for the output. For the syntax of this option, check 10560the "Video size" section in the ffmpeg-utils manual. Default value is 10561@code{640x512}. 10562 10563@item slide 10564Specify if the spectrum should slide along the window. Default value is 10565@code{0}. 10566 10567@item mode 10568Specify display mode. 10569 10570It accepts the following values: 10571@table @samp 10572@item combined 10573all channels are displayed in the same row 10574@item separate 10575all channels are displayed in separate rows 10576@end table 10577 10578Default value is @samp{combined}. 10579 10580@item color 10581Specify display color mode. 10582 10583It accepts the following values: 10584@table @samp 10585@item channel 10586each channel is displayed in a separate color 10587@item intensity 10588each channel is is displayed using the same color scheme 10589@end table 10590 10591Default value is @samp{channel}. 10592 10593@item scale 10594Specify scale used for calculating intensity color values. 10595 10596It accepts the following values: 10597@table @samp 10598@item lin 10599linear 10600@item sqrt 10601square root, default 10602@item cbrt 10603cubic root 10604@item log 10605logarithmic 10606@end table 10607 10608Default value is @samp{sqrt}. 10609 10610@item saturation 10611Set saturation modifier for displayed colors. Negative values provide 10612alternative color scheme. @code{0} is no saturation at all. 10613Saturation must be in [-10.0, 10.0] range. 10614Default value is @code{1}. 10615 10616@item win_func 10617Set window function. 10618 10619It accepts the following values: 10620@table @samp 10621@item none 10622No samples pre-processing (do not expect this to be faster) 10623@item hann 10624Hann window 10625@item hamming 10626Hamming window 10627@item blackman 10628Blackman window 10629@end table 10630 10631Default value is @code{hann}. 10632@end table 10633 10634The usage is very similar to the showwaves filter; see the examples in that 10635section. 10636 10637@subsection Examples 10638 10639@itemize 10640@item 10641Large window with logarithmic color scaling: 10642@example 10643showspectrum=s=1280x480:scale=log 10644@end example 10645 10646@item 10647Complete example for a colored and sliding spectrum per channel using @command{ffplay}: 10648@example 10649ffplay -f lavfi 'amovie=input.mp3, asplit [a][out1]; 10650 [a] showspectrum=mode=separate:color=intensity:slide=1:scale=cbrt [out0]' 10651@end example 10652@end itemize 10653 10654@section showwaves 10655 10656Convert input audio to a video output, representing the samples waves. 10657 10658The filter accepts the following options: 10659 10660@table @option 10661@item size, s 10662Specify the video size for the output. For the syntax of this option, check 10663the "Video size" section in the ffmpeg-utils manual. Default value 10664is "600x240". 10665 10666@item mode 10667Set display mode. 10668 10669Available values are: 10670@table @samp 10671@item point 10672Draw a point for each sample. 10673 10674@item line 10675Draw a vertical line for each sample. 10676@end table 10677 10678Default value is @code{point}. 10679 10680@item n 10681Set the number of samples which are printed on the same column. A 10682larger value will decrease the frame rate. Must be a positive 10683integer. This option can be set only if the value for @var{rate} 10684is not explicitly specified. 10685 10686@item rate, r 10687Set the (approximate) output frame rate. This is done by setting the 10688option @var{n}. Default value is "25". 10689 10690@end table 10691 10692@subsection Examples 10693 10694@itemize 10695@item 10696Output the input file audio and the corresponding video representation 10697at the same time: 10698@example 10699amovie=a.mp3,asplit[out0],showwaves[out1] 10700@end example 10701 10702@item 10703Create a synthetic signal and show it with showwaves, forcing a 10704frame rate of 30 frames per second: 10705@example 10706aevalsrc=sin(1*2*PI*t)*sin(880*2*PI*t):cos(2*PI*200*t),asplit[out0],showwaves=r=30[out1] 10707@end example 10708@end itemize 10709 10710@section split, asplit 10711 10712Split input into several identical outputs. 10713 10714@code{asplit} works with audio input, @code{split} with video. 10715 10716The filter accepts a single parameter which specifies the number of outputs. If 10717unspecified, it defaults to 2. 10718 10719@subsection Examples 10720 10721@itemize 10722@item 10723Create two separate outputs from the same input: 10724@example 10725[in] split [out0][out1] 10726@end example 10727 10728@item 10729To create 3 or more outputs, you need to specify the number of 10730outputs, like in: 10731@example 10732[in] asplit=3 [out0][out1][out2] 10733@end example 10734 10735@item 10736Create two separate outputs from the same input, one cropped and 10737one padded: 10738@example 10739[in] split [splitout1][splitout2]; 10740[splitout1] crop=100:100:0:0 [cropout]; 10741[splitout2] pad=200:200:100:100 [padout]; 10742@end example 10743 10744@item 10745Create 5 copies of the input audio with @command{ffmpeg}: 10746@example 10747ffmpeg -i INPUT -filter_complex asplit=5 OUTPUT 10748@end example 10749@end itemize 10750 10751@section zmq, azmq 10752 10753Receive commands sent through a libzmq client, and forward them to 10754filters in the filtergraph. 10755 10756@code{zmq} and @code{azmq} work as a pass-through filters. @code{zmq} 10757must be inserted between two video filters, @code{azmq} between two 10758audio filters. 10759 10760To enable these filters you need to install the libzmq library and 10761headers and configure FFmpeg with @code{--enable-libzmq}. 10762 10763For more information about libzmq see: 10764@url{http://www.zeromq.org/} 10765 10766The @code{zmq} and @code{azmq} filters work as a libzmq server, which 10767receives messages sent through a network interface defined by the 10768@option{bind_address} option. 10769 10770The received message must be in the form: 10771@example 10772@var{TARGET} @var{COMMAND} [@var{ARG}] 10773@end example 10774 10775@var{TARGET} specifies the target of the command, usually the name of 10776the filter class or a specific filter instance name. 10777 10778@var{COMMAND} specifies the name of the command for the target filter. 10779 10780@var{ARG} is optional and specifies the optional argument list for the 10781given @var{COMMAND}. 10782 10783Upon reception, the message is processed and the corresponding command 10784is injected into the filtergraph. Depending on the result, the filter 10785will send a reply to the client, adopting the format: 10786@example 10787@var{ERROR_CODE} @var{ERROR_REASON} 10788@var{MESSAGE} 10789@end example 10790 10791@var{MESSAGE} is optional. 10792 10793@subsection Examples 10794 10795Look at @file{tools/zmqsend} for an example of a zmq client which can 10796be used to send commands processed by these filters. 10797 10798Consider the following filtergraph generated by @command{ffplay} 10799@example 10800ffplay -dumpgraph 1 -f lavfi " 10801color=s=100x100:c=red [l]; 10802color=s=100x100:c=blue [r]; 10803nullsrc=s=200x100, zmq [bg]; 10804[bg][l] overlay [bg+l]; 10805[bg+l][r] overlay=x=100 " 10806@end example 10807 10808To change the color of the left side of the video, the following 10809command can be used: 10810@example 10811echo Parsed_color_0 c yellow | tools/zmqsend 10812@end example 10813 10814To change the right side: 10815@example 10816echo Parsed_color_1 c pink | tools/zmqsend 10817@end example 10818 10819@c man end MULTIMEDIA FILTERS 10820 10821@chapter Multimedia Sources 10822@c man begin MULTIMEDIA SOURCES 10823 10824Below is a description of the currently available multimedia sources. 10825 10826@section amovie 10827 10828This is the same as @ref{movie} source, except it selects an audio 10829stream by default. 10830 10831@anchor{movie} 10832@section movie 10833 10834Read audio and/or video stream(s) from a movie container. 10835 10836It accepts the following parameters: 10837 10838@table @option 10839@item filename 10840The name of the resource to read (not necessarily a file; it can also be a 10841device or a stream accessed through some protocol). 10842 10843@item format_name, f 10844Specifies the format assumed for the movie to read, and can be either 10845the name of a container or an input device. If not specified, the 10846format is guessed from @var{movie_name} or by probing. 10847 10848@item seek_point, sp 10849Specifies the seek point in seconds. The frames will be output 10850starting from this seek point. The parameter is evaluated with 10851@code{av_strtod}, so the numerical value may be suffixed by an IS 10852postfix. The default value is "0". 10853 10854@item streams, s 10855Specifies the streams to read. Several streams can be specified, 10856separated by "+". The source will then have as many outputs, in the 10857same order. The syntax is explained in the ``Stream specifiers'' 10858section in the ffmpeg manual. Two special names, "dv" and "da" specify 10859respectively the default (best suited) video and audio stream. Default 10860is "dv", or "da" if the filter is called as "amovie". 10861 10862@item stream_index, si 10863Specifies the index of the video stream to read. If the value is -1, 10864the most suitable video stream will be automatically selected. The default 10865value is "-1". Deprecated. If the filter is called "amovie", it will select 10866audio instead of video. 10867 10868@item loop 10869Specifies how many times to read the stream in sequence. 10870If the value is less than 1, the stream will be read again and again. 10871Default value is "1". 10872 10873Note that when the movie is looped the source timestamps are not 10874changed, so it will generate non monotonically increasing timestamps. 10875@end table 10876 10877It allows overlaying a second video on top of the main input of 10878a filtergraph, as shown in this graph: 10879@example 10880input -----------> deltapts0 --> overlay --> output 10881 ^ 10882 | 10883movie --> scale--> deltapts1 -------+ 10884@end example 10885@subsection Examples 10886 10887@itemize 10888@item 10889Skip 3.2 seconds from the start of the AVI file in.avi, and overlay it 10890on top of the input labelled "in": 10891@example 10892movie=in.avi:seek_point=3.2, scale=180:-1, setpts=PTS-STARTPTS [over]; 10893[in] setpts=PTS-STARTPTS [main]; 10894[main][over] overlay=16:16 [out] 10895@end example 10896 10897@item 10898Read from a video4linux2 device, and overlay it on top of the input 10899labelled "in": 10900@example 10901movie=/dev/video0:f=video4linux2, scale=180:-1, setpts=PTS-STARTPTS [over]; 10902[in] setpts=PTS-STARTPTS [main]; 10903[main][over] overlay=16:16 [out] 10904@end example 10905 10906@item 10907Read the first video stream and the audio stream with id 0x81 from 10908dvd.vob; the video is connected to the pad named "video" and the audio is 10909connected to the pad named "audio": 10910@example 10911movie=dvd.vob:s=v:0+#0x81 [video] [audio] 10912@end example 10913@end itemize 10914 10915@c man end MULTIMEDIA SOURCES 10916