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@verbatim 12 [main] 13input --> split ---------------------> overlay --> output 14 | ^ 15 |[tmp] [flip]| 16 +-----> crop --> vflip -------+ 17@end verbatim 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 recognized by the 118@option{-filter}/@option{-vf}/@option{-af} and 119@option{-filter_complex} options in @command{ffmpeg} and 120@option{-vf}/@option{-af} in @command{ffplay}, and by the 121@code{avfilter_graph_parse_ptr()} function defined in 122@file{libavfilter/avfilter.h}. 123 124A filterchain consists of a sequence of connected filters, each one 125connected to the previous one in the sequence. A filterchain is 126represented by a list of ","-separated filter descriptions. 127 128A filtergraph consists of a sequence of filterchains. A sequence of 129filterchains is represented by a list of ";"-separated filterchain 130descriptions. 131 132A filter is represented by a string of the form: 133[@var{in_link_1}]...[@var{in_link_N}]@var{filter_name}@@@var{id}=@var{arguments}[@var{out_link_1}]...[@var{out_link_M}] 134 135@var{filter_name} is the name of the filter class of which the 136described filter is an instance of, and has to be the name of one of 137the filter classes registered in the program optionally followed by "@@@var{id}". 138The name of the filter class is optionally followed by a string 139"=@var{arguments}". 140 141@var{arguments} is a string which contains the parameters used to 142initialize the filter instance. It may have one of two forms: 143@itemize 144 145@item 146A ':'-separated list of @var{key=value} pairs. 147 148@item 149A ':'-separated list of @var{value}. In this case, the keys are assumed to be 150the option names in the order they are declared. E.g. the @code{fade} filter 151declares three options in this order -- @option{type}, @option{start_frame} and 152@option{nb_frames}. Then the parameter list @var{in:0:30} means that the value 153@var{in} is assigned to the option @option{type}, @var{0} to 154@option{start_frame} and @var{30} to @option{nb_frames}. 155 156@item 157A ':'-separated list of mixed direct @var{value} and long @var{key=value} 158pairs. The direct @var{value} must precede the @var{key=value} pairs, and 159follow the same constraints order of the previous point. The following 160@var{key=value} pairs can be set in any preferred order. 161 162@end itemize 163 164If the option value itself is a list of items (e.g. the @code{format} filter 165takes a list of pixel formats), the items in the list are usually separated by 166@samp{|}. 167 168The list of arguments can be quoted using the character @samp{'} as initial 169and ending mark, and the character @samp{\} for escaping the characters 170within the quoted text; otherwise the argument string is considered 171terminated when the next special character (belonging to the set 172@samp{[]=;,}) is encountered. 173 174The name and arguments of the filter are optionally preceded and 175followed by a list of link labels. 176A link label allows one to name a link and associate it to a filter output 177or input pad. The preceding labels @var{in_link_1} 178... @var{in_link_N}, are associated to the filter input pads, 179the following labels @var{out_link_1} ... @var{out_link_M}, are 180associated to the output pads. 181 182When two link labels with the same name are found in the 183filtergraph, a link between the corresponding input and output pad is 184created. 185 186If an output pad is not labelled, it is linked by default to the first 187unlabelled input pad of the next filter in the filterchain. 188For example in the filterchain 189@example 190nullsrc, split[L1], [L2]overlay, nullsink 191@end example 192the split filter instance has two output pads, and the overlay filter 193instance two input pads. The first output pad of split is labelled 194"L1", the first input pad of overlay is labelled "L2", and the second 195output pad of split is linked to the second input pad of overlay, 196which are both unlabelled. 197 198In a filter description, if the input label of the first filter is not 199specified, "in" is assumed; if the output label of the last filter is not 200specified, "out" is assumed. 201 202In a complete filterchain all the unlabelled filter input and output 203pads must be connected. A filtergraph is considered valid if all the 204filter input and output pads of all the filterchains are connected. 205 206Libavfilter will automatically insert @ref{scale} filters where format 207conversion is required. It is possible to specify swscale flags 208for those automatically inserted scalers by prepending 209@code{sws_flags=@var{flags};} 210to the filtergraph description. 211 212Here is a BNF description of the filtergraph syntax: 213@example 214@var{NAME} ::= sequence of alphanumeric characters and '_' 215@var{FILTER_NAME} ::= @var{NAME}["@@"@var{NAME}] 216@var{LINKLABEL} ::= "[" @var{NAME} "]" 217@var{LINKLABELS} ::= @var{LINKLABEL} [@var{LINKLABELS}] 218@var{FILTER_ARGUMENTS} ::= sequence of chars (possibly quoted) 219@var{FILTER} ::= [@var{LINKLABELS}] @var{FILTER_NAME} ["=" @var{FILTER_ARGUMENTS}] [@var{LINKLABELS}] 220@var{FILTERCHAIN} ::= @var{FILTER} [,@var{FILTERCHAIN}] 221@var{FILTERGRAPH} ::= [sws_flags=@var{flags};] @var{FILTERCHAIN} [;@var{FILTERGRAPH}] 222@end example 223 224@anchor{filtergraph escaping} 225@section Notes on filtergraph escaping 226 227Filtergraph description composition entails several levels of 228escaping. See @ref{quoting_and_escaping,,the "Quoting and escaping" 229section in the ffmpeg-utils(1) manual,ffmpeg-utils} for more 230information about the employed escaping procedure. 231 232A first level escaping affects the content of each filter option 233value, which may contain the special character @code{:} used to 234separate values, or one of the escaping characters @code{\'}. 235 236A second level escaping affects the whole filter description, which 237may contain the escaping characters @code{\'} or the special 238characters @code{[],;} used by the filtergraph description. 239 240Finally, when you specify a filtergraph on a shell commandline, you 241need to perform a third level escaping for the shell special 242characters contained within it. 243 244For example, consider the following string to be embedded in 245the @ref{drawtext} filter description @option{text} value: 246@example 247this is a 'string': may contain one, or more, special characters 248@end example 249 250This string contains the @code{'} special escaping character, and the 251@code{:} special character, so it needs to be escaped in this way: 252@example 253text=this is a \'string\'\: may contain one, or more, special characters 254@end example 255 256A second level of escaping is required when embedding the filter 257description in a filtergraph description, in order to escape all the 258filtergraph special characters. Thus the example above becomes: 259@example 260drawtext=text=this is a \\\'string\\\'\\: may contain one\, or more\, special characters 261@end example 262(note that in addition to the @code{\'} escaping special characters, 263also @code{,} needs to be escaped). 264 265Finally an additional level of escaping is needed when writing the 266filtergraph description in a shell command, which depends on the 267escaping rules of the adopted shell. For example, assuming that 268@code{\} is special and needs to be escaped with another @code{\}, the 269previous string will finally result in: 270@example 271-vf "drawtext=text=this is a \\\\\\'string\\\\\\'\\\\: may contain one\\, or more\\, special characters" 272@end example 273 274@chapter Timeline editing 275 276Some filters support a generic @option{enable} option. For the filters 277supporting timeline editing, this option can be set to an expression which is 278evaluated before sending a frame to the filter. If the evaluation is non-zero, 279the filter will be enabled, otherwise the frame will be sent unchanged to the 280next filter in the filtergraph. 281 282The expression accepts the following values: 283@table @samp 284@item t 285timestamp expressed in seconds, NAN if the input timestamp is unknown 286 287@item n 288sequential number of the input frame, starting from 0 289 290@item pos 291the position in the file of the input frame, NAN if unknown 292 293@item w 294@item h 295width and height of the input frame if video 296@end table 297 298Additionally, these filters support an @option{enable} command that can be used 299to re-define the expression. 300 301Like any other filtering option, the @option{enable} option follows the same 302rules. 303 304For example, to enable a blur filter (@ref{smartblur}) from 10 seconds to 3 305minutes, and a @ref{curves} filter starting at 3 seconds: 306@example 307smartblur = enable='between(t,10,3*60)', 308curves = enable='gte(t,3)' : preset=cross_process 309@end example 310 311See @code{ffmpeg -filters} to view which filters have timeline support. 312 313@c man end FILTERGRAPH DESCRIPTION 314 315@anchor{framesync} 316@chapter Options for filters with several inputs (framesync) 317@c man begin OPTIONS FOR FILTERS WITH SEVERAL INPUTS 318 319Some filters with several inputs support a common set of options. 320These options can only be set by name, not with the short notation. 321 322@table @option 323@item eof_action 324The action to take when EOF is encountered on the secondary input; it accepts 325one of the following values: 326 327@table @option 328@item repeat 329Repeat the last frame (the default). 330@item endall 331End both streams. 332@item pass 333Pass the main input through. 334@end table 335 336@item shortest 337If set to 1, force the output to terminate when the shortest input 338terminates. Default value is 0. 339 340@item repeatlast 341If set to 1, force the filter to extend the last frame of secondary streams 342until the end of the primary stream. A value of 0 disables this behavior. 343Default value is 1. 344@end table 345 346@c man end OPTIONS FOR FILTERS WITH SEVERAL INPUTS 347 348@chapter Audio Filters 349@c man begin AUDIO FILTERS 350 351When you configure your FFmpeg build, you can disable any of the 352existing filters using @code{--disable-filters}. 353The configure output will show the audio filters included in your 354build. 355 356Below is a description of the currently available audio filters. 357 358@section acompressor 359 360A compressor is mainly used to reduce the dynamic range of a signal. 361Especially modern music is mostly compressed at a high ratio to 362improve the overall loudness. It's done to get the highest attention 363of a listener, "fatten" the sound and bring more "power" to the track. 364If a signal is compressed too much it may sound dull or "dead" 365afterwards or it may start to "pump" (which could be a powerful effect 366but can also destroy a track completely). 367The right compression is the key to reach a professional sound and is 368the high art of mixing and mastering. Because of its complex settings 369it may take a long time to get the right feeling for this kind of effect. 370 371Compression is done by detecting the volume above a chosen level 372@code{threshold} and dividing it by the factor set with @code{ratio}. 373So if you set the threshold to -12dB and your signal reaches -6dB a ratio 374of 2:1 will result in a signal at -9dB. Because an exact manipulation of 375the signal would cause distortion of the waveform the reduction can be 376levelled over the time. This is done by setting "Attack" and "Release". 377@code{attack} determines how long the signal has to rise above the threshold 378before any reduction will occur and @code{release} sets the time the signal 379has to fall below the threshold to reduce the reduction again. Shorter signals 380than the chosen attack time will be left untouched. 381The overall reduction of the signal can be made up afterwards with the 382@code{makeup} setting. So compressing the peaks of a signal about 6dB and 383raising the makeup to this level results in a signal twice as loud than the 384source. To gain a softer entry in the compression the @code{knee} flattens the 385hard edge at the threshold in the range of the chosen decibels. 386 387The filter accepts the following options: 388 389@table @option 390@item level_in 391Set input gain. Default is 1. Range is between 0.015625 and 64. 392 393@item threshold 394If a signal of stream rises above this level it will affect the gain 395reduction. 396By default it is 0.125. Range is between 0.00097563 and 1. 397 398@item ratio 399Set a ratio by which the signal is reduced. 1:2 means that if the level 400rose 4dB above the threshold, it will be only 2dB above after the reduction. 401Default is 2. Range is between 1 and 20. 402 403@item attack 404Amount of milliseconds the signal has to rise above the threshold before gain 405reduction starts. Default is 20. Range is between 0.01 and 2000. 406 407@item release 408Amount of milliseconds the signal has to fall below the threshold before 409reduction is decreased again. Default is 250. Range is between 0.01 and 9000. 410 411@item makeup 412Set the amount by how much signal will be amplified after processing. 413Default is 1. Range is from 1 to 64. 414 415@item knee 416Curve the sharp knee around the threshold to enter gain reduction more softly. 417Default is 2.82843. Range is between 1 and 8. 418 419@item link 420Choose if the @code{average} level between all channels of input stream 421or the louder(@code{maximum}) channel of input stream affects the 422reduction. Default is @code{average}. 423 424@item detection 425Should the exact signal be taken in case of @code{peak} or an RMS one in case 426of @code{rms}. Default is @code{rms} which is mostly smoother. 427 428@item mix 429How much to use compressed signal in output. Default is 1. 430Range is between 0 and 1. 431@end table 432 433@section acontrast 434Simple audio dynamic range commpression/expansion filter. 435 436The filter accepts the following options: 437 438@table @option 439@item contrast 440Set contrast. Default is 33. Allowed range is between 0 and 100. 441@end table 442 443@section acopy 444 445Copy the input audio source unchanged to the output. This is mainly useful for 446testing purposes. 447 448@section acrossfade 449 450Apply cross fade from one input audio stream to another input audio stream. 451The cross fade is applied for specified duration near the end of first stream. 452 453The filter accepts the following options: 454 455@table @option 456@item nb_samples, ns 457Specify the number of samples for which the cross fade effect has to last. 458At the end of the cross fade effect the first input audio will be completely 459silent. Default is 44100. 460 461@item duration, d 462Specify the duration of the cross fade effect. See 463@ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils} 464for the accepted syntax. 465By default the duration is determined by @var{nb_samples}. 466If set this option is used instead of @var{nb_samples}. 467 468@item overlap, o 469Should first stream end overlap with second stream start. Default is enabled. 470 471@item curve1 472Set curve for cross fade transition for first stream. 473 474@item curve2 475Set curve for cross fade transition for second stream. 476 477For description of available curve types see @ref{afade} filter description. 478@end table 479 480@subsection Examples 481 482@itemize 483@item 484Cross fade from one input to another: 485@example 486ffmpeg -i first.flac -i second.flac -filter_complex acrossfade=d=10:c1=exp:c2=exp output.flac 487@end example 488 489@item 490Cross fade from one input to another but without overlapping: 491@example 492ffmpeg -i first.flac -i second.flac -filter_complex acrossfade=d=10:o=0:c1=exp:c2=exp output.flac 493@end example 494@end itemize 495 496@section acrossover 497Split audio stream into several bands. 498 499This filter splits audio stream into two or more frequency ranges. 500Summing all streams back will give flat output. 501 502The filter accepts the following options: 503 504@table @option 505@item split 506Set split frequencies. Those must be positive and increasing. 507 508@item order 509Set filter order, can be @var{2nd}, @var{4th} or @var{8th}. 510Default is @var{4th}. 511@end table 512 513@section acrusher 514 515Reduce audio bit resolution. 516 517This filter is bit crusher with enhanced functionality. A bit crusher 518is used to audibly reduce number of bits an audio signal is sampled 519with. This doesn't change the bit depth at all, it just produces the 520effect. Material reduced in bit depth sounds more harsh and "digital". 521This filter is able to even round to continuous values instead of discrete 522bit depths. 523Additionally it has a D/C offset which results in different crushing of 524the lower and the upper half of the signal. 525An Anti-Aliasing setting is able to produce "softer" crushing sounds. 526 527Another feature of this filter is the logarithmic mode. 528This setting switches from linear distances between bits to logarithmic ones. 529The result is a much more "natural" sounding crusher which doesn't gate low 530signals for example. The human ear has a logarithmic perception, 531so this kind of crushing is much more pleasant. 532Logarithmic crushing is also able to get anti-aliased. 533 534The filter accepts the following options: 535 536@table @option 537@item level_in 538Set level in. 539 540@item level_out 541Set level out. 542 543@item bits 544Set bit reduction. 545 546@item mix 547Set mixing amount. 548 549@item mode 550Can be linear: @code{lin} or logarithmic: @code{log}. 551 552@item dc 553Set DC. 554 555@item aa 556Set anti-aliasing. 557 558@item samples 559Set sample reduction. 560 561@item lfo 562Enable LFO. By default disabled. 563 564@item lforange 565Set LFO range. 566 567@item lforate 568Set LFO rate. 569@end table 570 571@section acue 572 573Delay audio filtering until a given wallclock timestamp. See the @ref{cue} 574filter. 575 576@section adeclick 577Remove impulsive noise from input audio. 578 579Samples detected as impulsive noise are replaced by interpolated samples using 580autoregressive modelling. 581 582@table @option 583@item w 584Set window size, in milliseconds. Allowed range is from @code{10} to 585@code{100}. Default value is @code{55} milliseconds. 586This sets size of window which will be processed at once. 587 588@item o 589Set window overlap, in percentage of window size. Allowed range is from 590@code{50} to @code{95}. Default value is @code{75} percent. 591Setting this to a very high value increases impulsive noise removal but makes 592whole process much slower. 593 594@item a 595Set autoregression order, in percentage of window size. Allowed range is from 596@code{0} to @code{25}. Default value is @code{2} percent. This option also 597controls quality of interpolated samples using neighbour good samples. 598 599@item t 600Set threshold value. Allowed range is from @code{1} to @code{100}. 601Default value is @code{2}. 602This controls the strength of impulsive noise which is going to be removed. 603The lower value, the more samples will be detected as impulsive noise. 604 605@item b 606Set burst fusion, in percentage of window size. Allowed range is @code{0} to 607@code{10}. Default value is @code{2}. 608If any two samples deteced as noise are spaced less than this value then any 609sample inbetween those two samples will be also detected as noise. 610 611@item m 612Set overlap method. 613 614It accepts the following values: 615@table @option 616@item a 617Select overlap-add method. Even not interpolated samples are slightly 618changed with this method. 619 620@item s 621Select overlap-save method. Not interpolated samples remain unchanged. 622@end table 623 624Default value is @code{a}. 625@end table 626 627@section adeclip 628Remove clipped samples from input audio. 629 630Samples detected as clipped are replaced by interpolated samples using 631autoregressive modelling. 632 633@table @option 634@item w 635Set window size, in milliseconds. Allowed range is from @code{10} to @code{100}. 636Default value is @code{55} milliseconds. 637This sets size of window which will be processed at once. 638 639@item o 640Set window overlap, in percentage of window size. Allowed range is from @code{50} 641to @code{95}. Default value is @code{75} percent. 642 643@item a 644Set autoregression order, in percentage of window size. Allowed range is from 645@code{0} to @code{25}. Default value is @code{8} percent. This option also controls 646quality of interpolated samples using neighbour good samples. 647 648@item t 649Set threshold value. Allowed range is from @code{1} to @code{100}. 650Default value is @code{10}. Higher values make clip detection less aggressive. 651 652@item n 653Set size of histogram used to detect clips. Allowed range is from @code{100} to @code{9999}. 654Default value is @code{1000}. Higher values make clip detection less aggressive. 655 656@item m 657Set overlap method. 658 659It accepts the following values: 660@table @option 661@item a 662Select overlap-add method. Even not interpolated samples are slightly changed 663with this method. 664 665@item s 666Select overlap-save method. Not interpolated samples remain unchanged. 667@end table 668 669Default value is @code{a}. 670@end table 671 672@section adelay 673 674Delay one or more audio channels. 675 676Samples in delayed channel are filled with silence. 677 678The filter accepts the following option: 679 680@table @option 681@item delays 682Set list of delays in milliseconds for each channel separated by '|'. 683Unused delays will be silently ignored. If number of given delays is 684smaller than number of channels all remaining channels will not be delayed. 685If you want to delay exact number of samples, append 'S' to number. 686@end table 687 688@subsection Examples 689 690@itemize 691@item 692Delay first channel by 1.5 seconds, the third channel by 0.5 seconds and leave 693the second channel (and any other channels that may be present) unchanged. 694@example 695adelay=1500|0|500 696@end example 697 698@item 699Delay second channel by 500 samples, the third channel by 700 samples and leave 700the first channel (and any other channels that may be present) unchanged. 701@example 702adelay=0|500S|700S 703@end example 704@end itemize 705 706@section aderivative, aintegral 707 708Compute derivative/integral of audio stream. 709 710Applying both filters one after another produces original audio. 711 712@section aecho 713 714Apply echoing to the input audio. 715 716Echoes are reflected sound and can occur naturally amongst mountains 717(and sometimes large buildings) when talking or shouting; digital echo 718effects emulate this behaviour and are often used to help fill out the 719sound of a single instrument or vocal. The time difference between the 720original signal and the reflection is the @code{delay}, and the 721loudness of the reflected signal is the @code{decay}. 722Multiple echoes can have different delays and decays. 723 724A description of the accepted parameters follows. 725 726@table @option 727@item in_gain 728Set input gain of reflected signal. Default is @code{0.6}. 729 730@item out_gain 731Set output gain of reflected signal. Default is @code{0.3}. 732 733@item delays 734Set list of time intervals in milliseconds between original signal and reflections 735separated by '|'. Allowed range for each @code{delay} is @code{(0 - 90000.0]}. 736Default is @code{1000}. 737 738@item decays 739Set list of loudness of reflected signals separated by '|'. 740Allowed range for each @code{decay} is @code{(0 - 1.0]}. 741Default is @code{0.5}. 742@end table 743 744@subsection Examples 745 746@itemize 747@item 748Make it sound as if there are twice as many instruments as are actually playing: 749@example 750aecho=0.8:0.88:60:0.4 751@end example 752 753@item 754If delay is very short, then it sound like a (metallic) robot playing music: 755@example 756aecho=0.8:0.88:6:0.4 757@end example 758 759@item 760A longer delay will sound like an open air concert in the mountains: 761@example 762aecho=0.8:0.9:1000:0.3 763@end example 764 765@item 766Same as above but with one more mountain: 767@example 768aecho=0.8:0.9:1000|1800:0.3|0.25 769@end example 770@end itemize 771 772@section aemphasis 773Audio emphasis filter creates or restores material directly taken from LPs or 774emphased CDs with different filter curves. E.g. to store music on vinyl the 775signal has to be altered by a filter first to even out the disadvantages of 776this recording medium. 777Once the material is played back the inverse filter has to be applied to 778restore the distortion of the frequency response. 779 780The filter accepts the following options: 781 782@table @option 783@item level_in 784Set input gain. 785 786@item level_out 787Set output gain. 788 789@item mode 790Set filter mode. For restoring material use @code{reproduction} mode, otherwise 791use @code{production} mode. Default is @code{reproduction} mode. 792 793@item type 794Set filter type. Selects medium. Can be one of the following: 795 796@table @option 797@item col 798select Columbia. 799@item emi 800select EMI. 801@item bsi 802select BSI (78RPM). 803@item riaa 804select RIAA. 805@item cd 806select Compact Disc (CD). 807@item 50fm 808select 50µs (FM). 809@item 75fm 810select 75µs (FM). 811@item 50kf 812select 50µs (FM-KF). 813@item 75kf 814select 75µs (FM-KF). 815@end table 816@end table 817 818@section aeval 819 820Modify an audio signal according to the specified expressions. 821 822This filter accepts one or more expressions (one for each channel), 823which are evaluated and used to modify a corresponding audio signal. 824 825It accepts the following parameters: 826 827@table @option 828@item exprs 829Set the '|'-separated expressions list for each separate channel. If 830the number of input channels is greater than the number of 831expressions, the last specified expression is used for the remaining 832output channels. 833 834@item channel_layout, c 835Set output channel layout. If not specified, the channel layout is 836specified by the number of expressions. If set to @samp{same}, it will 837use by default the same input channel layout. 838@end table 839 840Each expression in @var{exprs} can contain the following constants and functions: 841 842@table @option 843@item ch 844channel number of the current expression 845 846@item n 847number of the evaluated sample, starting from 0 848 849@item s 850sample rate 851 852@item t 853time of the evaluated sample expressed in seconds 854 855@item nb_in_channels 856@item nb_out_channels 857input and output number of channels 858 859@item val(CH) 860the value of input channel with number @var{CH} 861@end table 862 863Note: this filter is slow. For faster processing you should use a 864dedicated filter. 865 866@subsection Examples 867 868@itemize 869@item 870Half volume: 871@example 872aeval=val(ch)/2:c=same 873@end example 874 875@item 876Invert phase of the second channel: 877@example 878aeval=val(0)|-val(1) 879@end example 880@end itemize 881 882@anchor{afade} 883@section afade 884 885Apply fade-in/out effect to input audio. 886 887A description of the accepted parameters follows. 888 889@table @option 890@item type, t 891Specify the effect type, can be either @code{in} for fade-in, or 892@code{out} for a fade-out effect. Default is @code{in}. 893 894@item start_sample, ss 895Specify the number of the start sample for starting to apply the fade 896effect. Default is 0. 897 898@item nb_samples, ns 899Specify the number of samples for which the fade effect has to last. At 900the end of the fade-in effect the output audio will have the same 901volume as the input audio, at the end of the fade-out transition 902the output audio will be silence. Default is 44100. 903 904@item start_time, st 905Specify the start time of the fade effect. Default is 0. 906The value must be specified as a time duration; see 907@ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils} 908for the accepted syntax. 909If set this option is used instead of @var{start_sample}. 910 911@item duration, d 912Specify the duration of the fade effect. See 913@ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils} 914for the accepted syntax. 915At the end of the fade-in effect the output audio will have the same 916volume as the input audio, at the end of the fade-out transition 917the output audio will be silence. 918By default the duration is determined by @var{nb_samples}. 919If set this option is used instead of @var{nb_samples}. 920 921@item curve 922Set curve for fade transition. 923 924It accepts the following values: 925@table @option 926@item tri 927select triangular, linear slope (default) 928@item qsin 929select quarter of sine wave 930@item hsin 931select half of sine wave 932@item esin 933select exponential sine wave 934@item log 935select logarithmic 936@item ipar 937select inverted parabola 938@item qua 939select quadratic 940@item cub 941select cubic 942@item squ 943select square root 944@item cbr 945select cubic root 946@item par 947select parabola 948@item exp 949select exponential 950@item iqsin 951select inverted quarter of sine wave 952@item ihsin 953select inverted half of sine wave 954@item dese 955select double-exponential seat 956@item desi 957select double-exponential sigmoid 958@item losi 959select logistic sigmoid 960@end table 961@end table 962 963@subsection Examples 964 965@itemize 966@item 967Fade in first 15 seconds of audio: 968@example 969afade=t=in:ss=0:d=15 970@end example 971 972@item 973Fade out last 25 seconds of a 900 seconds audio: 974@example 975afade=t=out:st=875:d=25 976@end example 977@end itemize 978 979@section afftdn 980Denoise audio samples with FFT. 981 982A description of the accepted parameters follows. 983 984@table @option 985@item nr 986Set the noise reduction in dB, allowed range is 0.01 to 97. 987Default value is 12 dB. 988 989@item nf 990Set the noise floor in dB, allowed range is -80 to -20. 991Default value is -50 dB. 992 993@item nt 994Set the noise type. 995 996It accepts the following values: 997@table @option 998@item w 999Select white noise. 1000 1001@item v 1002Select vinyl noise. 1003 1004@item s 1005Select shellac noise. 1006 1007@item c 1008Select custom noise, defined in @code{bn} option. 1009 1010Default value is white noise. 1011@end table 1012 1013@item bn 1014Set custom band noise for every one of 15 bands. 1015Bands are separated by ' ' or '|'. 1016 1017@item rf 1018Set the residual floor in dB, allowed range is -80 to -20. 1019Default value is -38 dB. 1020 1021@item tn 1022Enable noise tracking. By default is disabled. 1023With this enabled, noise floor is automatically adjusted. 1024 1025@item tr 1026Enable residual tracking. By default is disabled. 1027 1028@item om 1029Set the output mode. 1030 1031It accepts the following values: 1032@table @option 1033@item i 1034Pass input unchanged. 1035 1036@item o 1037Pass noise filtered out. 1038 1039@item n 1040Pass only noise. 1041 1042Default value is @var{o}. 1043@end table 1044@end table 1045 1046@subsection Commands 1047 1048This filter supports the following commands: 1049@table @option 1050@item sample_noise, sn 1051Start or stop measuring noise profile. 1052Syntax for the command is : "start" or "stop" string. 1053After measuring noise profile is stopped it will be 1054automatically applied in filtering. 1055 1056@item noise_reduction, nr 1057Change noise reduction. Argument is single float number. 1058Syntax for the command is : "@var{noise_reduction}" 1059 1060@item noise_floor, nf 1061Change noise floor. Argument is single float number. 1062Syntax for the command is : "@var{noise_floor}" 1063 1064@item output_mode, om 1065Change output mode operation. 1066Syntax for the command is : "i", "o" or "n" string. 1067@end table 1068 1069@section afftfilt 1070Apply arbitrary expressions to samples in frequency domain. 1071 1072@table @option 1073@item real 1074Set frequency domain real expression for each separate channel separated 1075by '|'. Default is "1". 1076If the number of input channels is greater than the number of 1077expressions, the last specified expression is used for the remaining 1078output channels. 1079 1080@item imag 1081Set frequency domain imaginary expression for each separate channel 1082separated by '|'. If not set, @var{real} option is used. 1083 1084Each expression in @var{real} and @var{imag} can contain the following 1085constants: 1086 1087@table @option 1088@item sr 1089sample rate 1090 1091@item b 1092current frequency bin number 1093 1094@item nb 1095number of available bins 1096 1097@item ch 1098channel number of the current expression 1099 1100@item chs 1101number of channels 1102 1103@item pts 1104current frame pts 1105@end table 1106 1107@item win_size 1108Set window size. 1109 1110It accepts the following values: 1111@table @samp 1112@item w16 1113@item w32 1114@item w64 1115@item w128 1116@item w256 1117@item w512 1118@item w1024 1119@item w2048 1120@item w4096 1121@item w8192 1122@item w16384 1123@item w32768 1124@item w65536 1125@end table 1126Default is @code{w4096} 1127 1128@item win_func 1129Set window function. Default is @code{hann}. 1130 1131@item overlap 1132Set window overlap. If set to 1, the recommended overlap for selected 1133window function will be picked. Default is @code{0.75}. 1134@end table 1135 1136@subsection Examples 1137 1138@itemize 1139@item 1140Leave almost only low frequencies in audio: 1141@example 1142afftfilt="1-clip((b/nb)*b,0,1)" 1143@end example 1144@end itemize 1145 1146@anchor{afir} 1147@section afir 1148 1149Apply an arbitrary Frequency Impulse Response filter. 1150 1151This filter is designed for applying long FIR filters, 1152up to 60 seconds long. 1153 1154It can be used as component for digital crossover filters, 1155room equalization, cross talk cancellation, wavefield synthesis, 1156auralization, ambiophonics and ambisonics. 1157 1158This filter uses second stream as FIR coefficients. 1159If second stream holds single channel, it will be used 1160for all input channels in first stream, otherwise 1161number of channels in second stream must be same as 1162number of channels in first stream. 1163 1164It accepts the following parameters: 1165 1166@table @option 1167@item dry 1168Set dry gain. This sets input gain. 1169 1170@item wet 1171Set wet gain. This sets final output gain. 1172 1173@item length 1174Set Impulse Response filter length. Default is 1, which means whole IR is processed. 1175 1176@item gtype 1177Enable applying gain measured from power of IR. 1178 1179Set which approach to use for auto gain measurement. 1180 1181@table @option 1182@item none 1183Do not apply any gain. 1184 1185@item peak 1186select peak gain, very conservative approach. This is default value. 1187 1188@item dc 1189select DC gain, limited application. 1190 1191@item gn 1192select gain to noise approach, this is most popular one. 1193@end table 1194 1195@item irgain 1196Set gain to be applied to IR coefficients before filtering. 1197Allowed range is 0 to 1. This gain is applied after any gain applied with @var{gtype} option. 1198 1199@item irfmt 1200Set format of IR stream. Can be @code{mono} or @code{input}. 1201Default is @code{input}. 1202 1203@item maxir 1204Set max allowed Impulse Response filter duration in seconds. Default is 30 seconds. 1205Allowed range is 0.1 to 60 seconds. 1206 1207@item response 1208Show IR frequency reponse, magnitude(magenta) and phase(green) and group delay(yellow) in additional video stream. 1209By default it is disabled. 1210 1211@item channel 1212Set for which IR channel to display frequency response. By default is first channel 1213displayed. This option is used only when @var{response} is enabled. 1214 1215@item size 1216Set video stream size. This option is used only when @var{response} is enabled. 1217@end table 1218 1219@subsection Examples 1220 1221@itemize 1222@item 1223Apply reverb to stream using mono IR file as second input, complete command using ffmpeg: 1224@example 1225ffmpeg -i input.wav -i middle_tunnel_1way_mono.wav -lavfi afir output.wav 1226@end example 1227@end itemize 1228 1229@anchor{aformat} 1230@section aformat 1231 1232Set output format constraints for the input audio. The framework will 1233negotiate the most appropriate format to minimize conversions. 1234 1235It accepts the following parameters: 1236@table @option 1237 1238@item sample_fmts 1239A '|'-separated list of requested sample formats. 1240 1241@item sample_rates 1242A '|'-separated list of requested sample rates. 1243 1244@item channel_layouts 1245A '|'-separated list of requested channel layouts. 1246 1247See @ref{channel layout syntax,,the Channel Layout section in the ffmpeg-utils(1) manual,ffmpeg-utils} 1248for the required syntax. 1249@end table 1250 1251If a parameter is omitted, all values are allowed. 1252 1253Force the output to either unsigned 8-bit or signed 16-bit stereo 1254@example 1255aformat=sample_fmts=u8|s16:channel_layouts=stereo 1256@end example 1257 1258@section agate 1259 1260A gate is mainly used to reduce lower parts of a signal. This kind of signal 1261processing reduces disturbing noise between useful signals. 1262 1263Gating is done by detecting the volume below a chosen level @var{threshold} 1264and dividing it by the factor set with @var{ratio}. The bottom of the noise 1265floor is set via @var{range}. Because an exact manipulation of the signal 1266would cause distortion of the waveform the reduction can be levelled over 1267time. This is done by setting @var{attack} and @var{release}. 1268 1269@var{attack} determines how long the signal has to fall below the threshold 1270before any reduction will occur and @var{release} sets the time the signal 1271has to rise above the threshold to reduce the reduction again. 1272Shorter signals than the chosen attack time will be left untouched. 1273 1274@table @option 1275@item level_in 1276Set input level before filtering. 1277Default is 1. Allowed range is from 0.015625 to 64. 1278 1279@item range 1280Set the level of gain reduction when the signal is below the threshold. 1281Default is 0.06125. Allowed range is from 0 to 1. 1282 1283@item threshold 1284If a signal rises above this level the gain reduction is released. 1285Default is 0.125. Allowed range is from 0 to 1. 1286 1287@item ratio 1288Set a ratio by which the signal is reduced. 1289Default is 2. Allowed range is from 1 to 9000. 1290 1291@item attack 1292Amount of milliseconds the signal has to rise above the threshold before gain 1293reduction stops. 1294Default is 20 milliseconds. Allowed range is from 0.01 to 9000. 1295 1296@item release 1297Amount of milliseconds the signal has to fall below the threshold before the 1298reduction is increased again. Default is 250 milliseconds. 1299Allowed range is from 0.01 to 9000. 1300 1301@item makeup 1302Set amount of amplification of signal after processing. 1303Default is 1. Allowed range is from 1 to 64. 1304 1305@item knee 1306Curve the sharp knee around the threshold to enter gain reduction more softly. 1307Default is 2.828427125. Allowed range is from 1 to 8. 1308 1309@item detection 1310Choose if exact signal should be taken for detection or an RMS like one. 1311Default is @code{rms}. Can be @code{peak} or @code{rms}. 1312 1313@item link 1314Choose if the average level between all channels or the louder channel affects 1315the reduction. 1316Default is @code{average}. Can be @code{average} or @code{maximum}. 1317@end table 1318 1319@section aiir 1320 1321Apply an arbitrary Infinite Impulse Response filter. 1322 1323It accepts the following parameters: 1324 1325@table @option 1326@item z 1327Set numerator/zeros coefficients. 1328 1329@item p 1330Set denominator/poles coefficients. 1331 1332@item k 1333Set channels gains. 1334 1335@item dry_gain 1336Set input gain. 1337 1338@item wet_gain 1339Set output gain. 1340 1341@item f 1342Set coefficients format. 1343 1344@table @samp 1345@item tf 1346transfer function 1347@item zp 1348Z-plane zeros/poles, cartesian (default) 1349@item pr 1350Z-plane zeros/poles, polar radians 1351@item pd 1352Z-plane zeros/poles, polar degrees 1353@end table 1354 1355@item r 1356Set kind of processing. 1357Can be @code{d} - direct or @code{s} - serial cascading. Defauls is @code{s}. 1358 1359@item e 1360Set filtering precision. 1361 1362@table @samp 1363@item dbl 1364double-precision floating-point (default) 1365@item flt 1366single-precision floating-point 1367@item i32 136832-bit integers 1369@item i16 137016-bit integers 1371@end table 1372 1373@item response 1374Show IR frequency reponse, magnitude and phase in additional video stream. 1375By default it is disabled. 1376 1377@item channel 1378Set for which IR channel to display frequency response. By default is first channel 1379displayed. This option is used only when @var{response} is enabled. 1380 1381@item size 1382Set video stream size. This option is used only when @var{response} is enabled. 1383@end table 1384 1385Coefficients in @code{tf} format are separated by spaces and are in ascending 1386order. 1387 1388Coefficients in @code{zp} format are separated by spaces and order of coefficients 1389doesn't matter. Coefficients in @code{zp} format are complex numbers with @var{i} 1390imaginary unit. 1391 1392Different coefficients and gains can be provided for every channel, in such case 1393use '|' to separate coefficients or gains. Last provided coefficients will be 1394used for all remaining channels. 1395 1396@subsection Examples 1397 1398@itemize 1399@item 1400Apply 2 pole elliptic notch at arround 5000Hz for 48000 Hz sample rate: 1401@example 1402aiir=k=1:z=7.957584807809675810E-1 -2.575128568908332300 3.674839853930788710 -2.57512875289799137 7.957586296317130880E-1:p=1 -2.86950072432325953 3.63022088054647218 -2.28075678147272232 6.361362326477423500E-1:f=tf:r=d 1403@end example 1404 1405@item 1406Same as above but in @code{zp} format: 1407@example 1408aiir=k=0.79575848078096756:z=0.80918701+0.58773007i 0.80918701-0.58773007i 0.80884700+0.58784055i 0.80884700-0.58784055i:p=0.63892345+0.59951235i 0.63892345-0.59951235i 0.79582691+0.44198673i 0.79582691-0.44198673i:f=zp:r=s 1409@end example 1410@end itemize 1411 1412@section alimiter 1413 1414The limiter prevents an input signal from rising over a desired threshold. 1415This limiter uses lookahead technology to prevent your signal from distorting. 1416It means that there is a small delay after the signal is processed. Keep in mind 1417that the delay it produces is the attack time you set. 1418 1419The filter accepts the following options: 1420 1421@table @option 1422@item level_in 1423Set input gain. Default is 1. 1424 1425@item level_out 1426Set output gain. Default is 1. 1427 1428@item limit 1429Don't let signals above this level pass the limiter. Default is 1. 1430 1431@item attack 1432The limiter will reach its attenuation level in this amount of time in 1433milliseconds. Default is 5 milliseconds. 1434 1435@item release 1436Come back from limiting to attenuation 1.0 in this amount of milliseconds. 1437Default is 50 milliseconds. 1438 1439@item asc 1440When gain reduction is always needed ASC takes care of releasing to an 1441average reduction level rather than reaching a reduction of 0 in the release 1442time. 1443 1444@item asc_level 1445Select how much the release time is affected by ASC, 0 means nearly no changes 1446in release time while 1 produces higher release times. 1447 1448@item level 1449Auto level output signal. Default is enabled. 1450This normalizes audio back to 0dB if enabled. 1451@end table 1452 1453Depending on picked setting it is recommended to upsample input 2x or 4x times 1454with @ref{aresample} before applying this filter. 1455 1456@section allpass 1457 1458Apply a two-pole all-pass filter with central frequency (in Hz) 1459@var{frequency}, and filter-width @var{width}. 1460An all-pass filter changes the audio's frequency to phase relationship 1461without changing its frequency to amplitude relationship. 1462 1463The filter accepts the following options: 1464 1465@table @option 1466@item frequency, f 1467Set frequency in Hz. 1468 1469@item width_type, t 1470Set method to specify band-width of filter. 1471@table @option 1472@item h 1473Hz 1474@item q 1475Q-Factor 1476@item o 1477octave 1478@item s 1479slope 1480@item k 1481kHz 1482@end table 1483 1484@item width, w 1485Specify the band-width of a filter in width_type units. 1486 1487@item channels, c 1488Specify which channels to filter, by default all available are filtered. 1489@end table 1490 1491@subsection Commands 1492 1493This filter supports the following commands: 1494@table @option 1495@item frequency, f 1496Change allpass frequency. 1497Syntax for the command is : "@var{frequency}" 1498 1499@item width_type, t 1500Change allpass width_type. 1501Syntax for the command is : "@var{width_type}" 1502 1503@item width, w 1504Change allpass width. 1505Syntax for the command is : "@var{width}" 1506@end table 1507 1508@section aloop 1509 1510Loop audio samples. 1511 1512The filter accepts the following options: 1513 1514@table @option 1515@item loop 1516Set the number of loops. Setting this value to -1 will result in infinite loops. 1517Default is 0. 1518 1519@item size 1520Set maximal number of samples. Default is 0. 1521 1522@item start 1523Set first sample of loop. Default is 0. 1524@end table 1525 1526@anchor{amerge} 1527@section amerge 1528 1529Merge two or more audio streams into a single multi-channel stream. 1530 1531The filter accepts the following options: 1532 1533@table @option 1534 1535@item inputs 1536Set the number of inputs. Default is 2. 1537 1538@end table 1539 1540If the channel layouts of the inputs are disjoint, and therefore compatible, 1541the channel layout of the output will be set accordingly and the channels 1542will be reordered as necessary. If the channel layouts of the inputs are not 1543disjoint, the output will have all the channels of the first input then all 1544the channels of the second input, in that order, and the channel layout of 1545the output will be the default value corresponding to the total number of 1546channels. 1547 1548For example, if the first input is in 2.1 (FL+FR+LF) and the second input 1549is FC+BL+BR, then the output will be in 5.1, with the channels in the 1550following order: a1, a2, b1, a3, b2, b3 (a1 is the first channel of the 1551first input, b1 is the first channel of the second input). 1552 1553On the other hand, if both input are in stereo, the output channels will be 1554in the default order: a1, a2, b1, b2, and the channel layout will be 1555arbitrarily set to 4.0, which may or may not be the expected value. 1556 1557All inputs must have the same sample rate, and format. 1558 1559If inputs do not have the same duration, the output will stop with the 1560shortest. 1561 1562@subsection Examples 1563 1564@itemize 1565@item 1566Merge two mono files into a stereo stream: 1567@example 1568amovie=left.wav [l] ; amovie=right.mp3 [r] ; [l] [r] amerge 1569@end example 1570 1571@item 1572Multiple merges assuming 1 video stream and 6 audio streams in @file{input.mkv}: 1573@example 1574ffmpeg -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 1575@end example 1576@end itemize 1577 1578@section amix 1579 1580Mixes multiple audio inputs into a single output. 1581 1582Note that this filter only supports float samples (the @var{amerge} 1583and @var{pan} audio filters support many formats). If the @var{amix} 1584input has integer samples then @ref{aresample} will be automatically 1585inserted to perform the conversion to float samples. 1586 1587For example 1588@example 1589ffmpeg -i INPUT1 -i INPUT2 -i INPUT3 -filter_complex amix=inputs=3:duration=first:dropout_transition=3 OUTPUT 1590@end example 1591will mix 3 input audio streams to a single output with the same duration as the 1592first input and a dropout transition time of 3 seconds. 1593 1594It accepts the following parameters: 1595@table @option 1596 1597@item inputs 1598The number of inputs. If unspecified, it defaults to 2. 1599 1600@item duration 1601How to determine the end-of-stream. 1602@table @option 1603 1604@item longest 1605The duration of the longest input. (default) 1606 1607@item shortest 1608The duration of the shortest input. 1609 1610@item first 1611The duration of the first input. 1612 1613@end table 1614 1615@item dropout_transition 1616The transition time, in seconds, for volume renormalization when an input 1617stream ends. The default value is 2 seconds. 1618 1619@item weights 1620Specify weight of each input audio stream as sequence. 1621Each weight is separated by space. By default all inputs have same weight. 1622@end table 1623 1624@section amultiply 1625 1626Multiply first audio stream with second audio stream and store result 1627in output audio stream. Multiplication is done by multiplying each 1628sample from first stream with sample at same position from second stream. 1629 1630With this element-wise multiplication one can create amplitude fades and 1631amplitude modulations. 1632 1633@section anequalizer 1634 1635High-order parametric multiband equalizer for each channel. 1636 1637It accepts the following parameters: 1638@table @option 1639@item params 1640 1641This option string is in format: 1642"c@var{chn} f=@var{cf} w=@var{w} g=@var{g} t=@var{f} | ..." 1643Each equalizer band is separated by '|'. 1644 1645@table @option 1646@item chn 1647Set channel number to which equalization will be applied. 1648If input doesn't have that channel the entry is ignored. 1649 1650@item f 1651Set central frequency for band. 1652If input doesn't have that frequency the entry is ignored. 1653 1654@item w 1655Set band width in hertz. 1656 1657@item g 1658Set band gain in dB. 1659 1660@item t 1661Set filter type for band, optional, can be: 1662 1663@table @samp 1664@item 0 1665Butterworth, this is default. 1666 1667@item 1 1668Chebyshev type 1. 1669 1670@item 2 1671Chebyshev type 2. 1672@end table 1673@end table 1674 1675@item curves 1676With this option activated frequency response of anequalizer is displayed 1677in video stream. 1678 1679@item size 1680Set video stream size. Only useful if curves option is activated. 1681 1682@item mgain 1683Set max gain that will be displayed. Only useful if curves option is activated. 1684Setting this to a reasonable value makes it possible to display gain which is derived from 1685neighbour bands which are too close to each other and thus produce higher gain 1686when both are activated. 1687 1688@item fscale 1689Set frequency scale used to draw frequency response in video output. 1690Can be linear or logarithmic. Default is logarithmic. 1691 1692@item colors 1693Set color for each channel curve which is going to be displayed in video stream. 1694This is list of color names separated by space or by '|'. 1695Unrecognised or missing colors will be replaced by white color. 1696@end table 1697 1698@subsection Examples 1699 1700@itemize 1701@item 1702Lower gain by 10 of central frequency 200Hz and width 100 Hz 1703for first 2 channels using Chebyshev type 1 filter: 1704@example 1705anequalizer=c0 f=200 w=100 g=-10 t=1|c1 f=200 w=100 g=-10 t=1 1706@end example 1707@end itemize 1708 1709@subsection Commands 1710 1711This filter supports the following commands: 1712@table @option 1713@item change 1714Alter existing filter parameters. 1715Syntax for the commands is : "@var{fN}|f=@var{freq}|w=@var{width}|g=@var{gain}" 1716 1717@var{fN} is existing filter number, starting from 0, if no such filter is available 1718error is returned. 1719@var{freq} set new frequency parameter. 1720@var{width} set new width parameter in herz. 1721@var{gain} set new gain parameter in dB. 1722 1723Full filter invocation with asendcmd may look like this: 1724asendcmd=c='4.0 anequalizer change 0|f=200|w=50|g=1',anequalizer=... 1725@end table 1726 1727@section anull 1728 1729Pass the audio source unchanged to the output. 1730 1731@section apad 1732 1733Pad the end of an audio stream with silence. 1734 1735This can be used together with @command{ffmpeg} @option{-shortest} to 1736extend audio streams to the same length as the video stream. 1737 1738A description of the accepted options follows. 1739 1740@table @option 1741@item packet_size 1742Set silence packet size. Default value is 4096. 1743 1744@item pad_len 1745Set the number of samples of silence to add to the end. After the 1746value is reached, the stream is terminated. This option is mutually 1747exclusive with @option{whole_len}. 1748 1749@item whole_len 1750Set the minimum total number of samples in the output audio stream. If 1751the value is longer than the input audio length, silence is added to 1752the end, until the value is reached. This option is mutually exclusive 1753with @option{pad_len}. 1754@end table 1755 1756If neither the @option{pad_len} nor the @option{whole_len} option is 1757set, the filter will add silence to the end of the input stream 1758indefinitely. 1759 1760@subsection Examples 1761 1762@itemize 1763@item 1764Add 1024 samples of silence to the end of the input: 1765@example 1766apad=pad_len=1024 1767@end example 1768 1769@item 1770Make sure the audio output will contain at least 10000 samples, pad 1771the input with silence if required: 1772@example 1773apad=whole_len=10000 1774@end example 1775 1776@item 1777Use @command{ffmpeg} to pad the audio input with silence, so that the 1778video stream will always result the shortest and will be converted 1779until the end in the output file when using the @option{shortest} 1780option: 1781@example 1782ffmpeg -i VIDEO -i AUDIO -filter_complex "[1:0]apad" -shortest OUTPUT 1783@end example 1784@end itemize 1785 1786@section aphaser 1787Add a phasing effect to the input audio. 1788 1789A phaser filter creates series of peaks and troughs in the frequency spectrum. 1790The position of the peaks and troughs are modulated so that they vary over time, creating a sweeping effect. 1791 1792A description of the accepted parameters follows. 1793 1794@table @option 1795@item in_gain 1796Set input gain. Default is 0.4. 1797 1798@item out_gain 1799Set output gain. Default is 0.74 1800 1801@item delay 1802Set delay in milliseconds. Default is 3.0. 1803 1804@item decay 1805Set decay. Default is 0.4. 1806 1807@item speed 1808Set modulation speed in Hz. Default is 0.5. 1809 1810@item type 1811Set modulation type. Default is triangular. 1812 1813It accepts the following values: 1814@table @samp 1815@item triangular, t 1816@item sinusoidal, s 1817@end table 1818@end table 1819 1820@section apulsator 1821 1822Audio pulsator is something between an autopanner and a tremolo. 1823But it can produce funny stereo effects as well. Pulsator changes the volume 1824of the left and right channel based on a LFO (low frequency oscillator) with 1825different waveforms and shifted phases. 1826This filter have the ability to define an offset between left and right 1827channel. An offset of 0 means that both LFO shapes match each other. 1828The left and right channel are altered equally - a conventional tremolo. 1829An offset of 50% means that the shape of the right channel is exactly shifted 1830in phase (or moved backwards about half of the frequency) - pulsator acts as 1831an autopanner. At 1 both curves match again. Every setting in between moves the 1832phase shift gapless between all stages and produces some "bypassing" sounds with 1833sine and triangle waveforms. The more you set the offset near 1 (starting from 1834the 0.5) the faster the signal passes from the left to the right speaker. 1835 1836The filter accepts the following options: 1837 1838@table @option 1839@item level_in 1840Set input gain. By default it is 1. Range is [0.015625 - 64]. 1841 1842@item level_out 1843Set output gain. By default it is 1. Range is [0.015625 - 64]. 1844 1845@item mode 1846Set waveform shape the LFO will use. Can be one of: sine, triangle, square, 1847sawup or sawdown. Default is sine. 1848 1849@item amount 1850Set modulation. Define how much of original signal is affected by the LFO. 1851 1852@item offset_l 1853Set left channel offset. Default is 0. Allowed range is [0 - 1]. 1854 1855@item offset_r 1856Set right channel offset. Default is 0.5. Allowed range is [0 - 1]. 1857 1858@item width 1859Set pulse width. Default is 1. Allowed range is [0 - 2]. 1860 1861@item timing 1862Set possible timing mode. Can be one of: bpm, ms or hz. Default is hz. 1863 1864@item bpm 1865Set bpm. Default is 120. Allowed range is [30 - 300]. Only used if timing 1866is set to bpm. 1867 1868@item ms 1869Set ms. Default is 500. Allowed range is [10 - 2000]. Only used if timing 1870is set to ms. 1871 1872@item hz 1873Set frequency in Hz. Default is 2. Allowed range is [0.01 - 100]. Only used 1874if timing is set to hz. 1875@end table 1876 1877@anchor{aresample} 1878@section aresample 1879 1880Resample the input audio to the specified parameters, using the 1881libswresample library. If none are specified then the filter will 1882automatically convert between its input and output. 1883 1884This filter is also able to stretch/squeeze the audio data to make it match 1885the timestamps or to inject silence / cut out audio to make it match the 1886timestamps, do a combination of both or do neither. 1887 1888The filter accepts the syntax 1889[@var{sample_rate}:]@var{resampler_options}, where @var{sample_rate} 1890expresses a sample rate and @var{resampler_options} is a list of 1891@var{key}=@var{value} pairs, separated by ":". See the 1892@ref{Resampler Options,,"Resampler Options" section in the 1893ffmpeg-resampler(1) manual,ffmpeg-resampler} 1894for the complete list of supported options. 1895 1896@subsection Examples 1897 1898@itemize 1899@item 1900Resample the input audio to 44100Hz: 1901@example 1902aresample=44100 1903@end example 1904 1905@item 1906Stretch/squeeze samples to the given timestamps, with a maximum of 1000 1907samples per second compensation: 1908@example 1909aresample=async=1000 1910@end example 1911@end itemize 1912 1913@section areverse 1914 1915Reverse an audio clip. 1916 1917Warning: This filter requires memory to buffer the entire clip, so trimming 1918is suggested. 1919 1920@subsection Examples 1921 1922@itemize 1923@item 1924Take the first 5 seconds of a clip, and reverse it. 1925@example 1926atrim=end=5,areverse 1927@end example 1928@end itemize 1929 1930@section asetnsamples 1931 1932Set the number of samples per each output audio frame. 1933 1934The last output packet may contain a different number of samples, as 1935the filter will flush all the remaining samples when the input audio 1936signals its end. 1937 1938The filter accepts the following options: 1939 1940@table @option 1941 1942@item nb_out_samples, n 1943Set the number of frames per each output audio frame. The number is 1944intended as the number of samples @emph{per each channel}. 1945Default value is 1024. 1946 1947@item pad, p 1948If set to 1, the filter will pad the last audio frame with zeroes, so 1949that the last frame will contain the same number of samples as the 1950previous ones. Default value is 1. 1951@end table 1952 1953For example, to set the number of per-frame samples to 1234 and 1954disable padding for the last frame, use: 1955@example 1956asetnsamples=n=1234:p=0 1957@end example 1958 1959@section asetrate 1960 1961Set the sample rate without altering the PCM data. 1962This will result in a change of speed and pitch. 1963 1964The filter accepts the following options: 1965 1966@table @option 1967@item sample_rate, r 1968Set the output sample rate. Default is 44100 Hz. 1969@end table 1970 1971@section ashowinfo 1972 1973Show a line containing various information for each input audio frame. 1974The input audio is not modified. 1975 1976The shown line contains a sequence of key/value pairs of the form 1977@var{key}:@var{value}. 1978 1979The following values are shown in the output: 1980 1981@table @option 1982@item n 1983The (sequential) number of the input frame, starting from 0. 1984 1985@item pts 1986The presentation timestamp of the input frame, in time base units; the time base 1987depends on the filter input pad, and is usually 1/@var{sample_rate}. 1988 1989@item pts_time 1990The presentation timestamp of the input frame in seconds. 1991 1992@item pos 1993position of the frame in the input stream, -1 if this information in 1994unavailable and/or meaningless (for example in case of synthetic audio) 1995 1996@item fmt 1997The sample format. 1998 1999@item chlayout 2000The channel layout. 2001 2002@item rate 2003The sample rate for the audio frame. 2004 2005@item nb_samples 2006The number of samples (per channel) in the frame. 2007 2008@item checksum 2009The Adler-32 checksum (printed in hexadecimal) of the audio data. For planar 2010audio, the data is treated as if all the planes were concatenated. 2011 2012@item plane_checksums 2013A list of Adler-32 checksums for each data plane. 2014@end table 2015 2016@anchor{astats} 2017@section astats 2018 2019Display time domain statistical information about the audio channels. 2020Statistics are calculated and displayed for each audio channel and, 2021where applicable, an overall figure is also given. 2022 2023It accepts the following option: 2024@table @option 2025@item length 2026Short window length in seconds, used for peak and trough RMS measurement. 2027Default is @code{0.05} (50 milliseconds). Allowed range is @code{[0.01 - 10]}. 2028 2029@item metadata 2030 2031Set metadata injection. All the metadata keys are prefixed with @code{lavfi.astats.X}, 2032where @code{X} is channel number starting from 1 or string @code{Overall}. Default is 2033disabled. 2034 2035Available keys for each channel are: 2036DC_offset 2037Min_level 2038Max_level 2039Min_difference 2040Max_difference 2041Mean_difference 2042RMS_difference 2043Peak_level 2044RMS_peak 2045RMS_trough 2046Crest_factor 2047Flat_factor 2048Peak_count 2049Bit_depth 2050Dynamic_range 2051Zero_crossings 2052Zero_crossings_rate 2053 2054and for Overall: 2055DC_offset 2056Min_level 2057Max_level 2058Min_difference 2059Max_difference 2060Mean_difference 2061RMS_difference 2062Peak_level 2063RMS_level 2064RMS_peak 2065RMS_trough 2066Flat_factor 2067Peak_count 2068Bit_depth 2069Number_of_samples 2070 2071For example full key look like this @code{lavfi.astats.1.DC_offset} or 2072this @code{lavfi.astats.Overall.Peak_count}. 2073 2074For description what each key means read below. 2075 2076@item reset 2077Set number of frame after which stats are going to be recalculated. 2078Default is disabled. 2079@end table 2080 2081A description of each shown parameter follows: 2082 2083@table @option 2084@item DC offset 2085Mean amplitude displacement from zero. 2086 2087@item Min level 2088Minimal sample level. 2089 2090@item Max level 2091Maximal sample level. 2092 2093@item Min difference 2094Minimal difference between two consecutive samples. 2095 2096@item Max difference 2097Maximal difference between two consecutive samples. 2098 2099@item Mean difference 2100Mean difference between two consecutive samples. 2101The average of each difference between two consecutive samples. 2102 2103@item RMS difference 2104Root Mean Square difference between two consecutive samples. 2105 2106@item Peak level dB 2107@item RMS level dB 2108Standard peak and RMS level measured in dBFS. 2109 2110@item RMS peak dB 2111@item RMS trough dB 2112Peak and trough values for RMS level measured over a short window. 2113 2114@item Crest factor 2115Standard ratio of peak to RMS level (note: not in dB). 2116 2117@item Flat factor 2118Flatness (i.e. consecutive samples with the same value) of the signal at its peak levels 2119(i.e. either @var{Min level} or @var{Max level}). 2120 2121@item Peak count 2122Number of occasions (not the number of samples) that the signal attained either 2123@var{Min level} or @var{Max level}. 2124 2125@item Bit depth 2126Overall bit depth of audio. Number of bits used for each sample. 2127 2128@item Dynamic range 2129Measured dynamic range of audio in dB. 2130 2131@item Zero crossings 2132Number of points where the waveform crosses the zero level axis. 2133 2134@item Zero crossings rate 2135Rate of Zero crossings and number of audio samples. 2136@end table 2137 2138@section atempo 2139 2140Adjust audio tempo. 2141 2142The filter accepts exactly one parameter, the audio tempo. If not 2143specified then the filter will assume nominal 1.0 tempo. Tempo must 2144be in the [0.5, 100.0] range. 2145 2146Note that tempo greater than 2 will skip some samples rather than 2147blend them in. If for any reason this is a concern it is always 2148possible to daisy-chain several instances of atempo to achieve the 2149desired product tempo. 2150 2151@subsection Examples 2152 2153@itemize 2154@item 2155Slow down audio to 80% tempo: 2156@example 2157atempo=0.8 2158@end example 2159 2160@item 2161To speed up audio to 300% tempo: 2162@example 2163atempo=3 2164@end example 2165 2166@item 2167To speed up audio to 300% tempo by daisy-chaining two atempo instances: 2168@example 2169atempo=sqrt(3),atempo=sqrt(3) 2170@end example 2171@end itemize 2172 2173@section atrim 2174 2175Trim the input so that the output contains one continuous subpart of the input. 2176 2177It accepts the following parameters: 2178@table @option 2179@item start 2180Timestamp (in seconds) of the start of the section to keep. I.e. the audio 2181sample with the timestamp @var{start} will be the first sample in the output. 2182 2183@item end 2184Specify time of the first audio sample that will be dropped, i.e. the 2185audio sample immediately preceding the one with the timestamp @var{end} will be 2186the last sample in the output. 2187 2188@item start_pts 2189Same as @var{start}, except this option sets the start timestamp in samples 2190instead of seconds. 2191 2192@item end_pts 2193Same as @var{end}, except this option sets the end timestamp in samples instead 2194of seconds. 2195 2196@item duration 2197The maximum duration of the output in seconds. 2198 2199@item start_sample 2200The number of the first sample that should be output. 2201 2202@item end_sample 2203The number of the first sample that should be dropped. 2204@end table 2205 2206@option{start}, @option{end}, and @option{duration} are expressed as time 2207duration specifications; see 2208@ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}. 2209 2210Note that the first two sets of the start/end options and the @option{duration} 2211option look at the frame timestamp, while the _sample options simply count the 2212samples that pass through the filter. So start/end_pts and start/end_sample will 2213give different results when the timestamps are wrong, inexact or do not start at 2214zero. Also note that this filter does not modify the timestamps. If you wish 2215to have the output timestamps start at zero, insert the asetpts filter after the 2216atrim filter. 2217 2218If multiple start or end options are set, this filter tries to be greedy and 2219keep all samples that match at least one of the specified constraints. To keep 2220only the part that matches all the constraints at once, chain multiple atrim 2221filters. 2222 2223The defaults are such that all the input is kept. So it is possible to set e.g. 2224just the end values to keep everything before the specified time. 2225 2226Examples: 2227@itemize 2228@item 2229Drop everything except the second minute of input: 2230@example 2231ffmpeg -i INPUT -af atrim=60:120 2232@end example 2233 2234@item 2235Keep only the first 1000 samples: 2236@example 2237ffmpeg -i INPUT -af atrim=end_sample=1000 2238@end example 2239 2240@end itemize 2241 2242@section bandpass 2243 2244Apply a two-pole Butterworth band-pass filter with central 2245frequency @var{frequency}, and (3dB-point) band-width width. 2246The @var{csg} option selects a constant skirt gain (peak gain = Q) 2247instead of the default: constant 0dB peak gain. 2248The filter roll off at 6dB per octave (20dB per decade). 2249 2250The filter accepts the following options: 2251 2252@table @option 2253@item frequency, f 2254Set the filter's central frequency. Default is @code{3000}. 2255 2256@item csg 2257Constant skirt gain if set to 1. Defaults to 0. 2258 2259@item width_type, t 2260Set method to specify band-width of filter. 2261@table @option 2262@item h 2263Hz 2264@item q 2265Q-Factor 2266@item o 2267octave 2268@item s 2269slope 2270@item k 2271kHz 2272@end table 2273 2274@item width, w 2275Specify the band-width of a filter in width_type units. 2276 2277@item channels, c 2278Specify which channels to filter, by default all available are filtered. 2279@end table 2280 2281@subsection Commands 2282 2283This filter supports the following commands: 2284@table @option 2285@item frequency, f 2286Change bandpass frequency. 2287Syntax for the command is : "@var{frequency}" 2288 2289@item width_type, t 2290Change bandpass width_type. 2291Syntax for the command is : "@var{width_type}" 2292 2293@item width, w 2294Change bandpass width. 2295Syntax for the command is : "@var{width}" 2296@end table 2297 2298@section bandreject 2299 2300Apply a two-pole Butterworth band-reject filter with central 2301frequency @var{frequency}, and (3dB-point) band-width @var{width}. 2302The filter roll off at 6dB per octave (20dB per decade). 2303 2304The filter accepts the following options: 2305 2306@table @option 2307@item frequency, f 2308Set the filter's central frequency. Default is @code{3000}. 2309 2310@item width_type, t 2311Set method to specify band-width of filter. 2312@table @option 2313@item h 2314Hz 2315@item q 2316Q-Factor 2317@item o 2318octave 2319@item s 2320slope 2321@item k 2322kHz 2323@end table 2324 2325@item width, w 2326Specify the band-width of a filter in width_type units. 2327 2328@item channels, c 2329Specify which channels to filter, by default all available are filtered. 2330@end table 2331 2332@subsection Commands 2333 2334This filter supports the following commands: 2335@table @option 2336@item frequency, f 2337Change bandreject frequency. 2338Syntax for the command is : "@var{frequency}" 2339 2340@item width_type, t 2341Change bandreject width_type. 2342Syntax for the command is : "@var{width_type}" 2343 2344@item width, w 2345Change bandreject width. 2346Syntax for the command is : "@var{width}" 2347@end table 2348 2349@section bass, lowshelf 2350 2351Boost or cut the bass (lower) frequencies of the audio using a two-pole 2352shelving filter with a response similar to that of a standard 2353hi-fi's tone-controls. This is also known as shelving equalisation (EQ). 2354 2355The filter accepts the following options: 2356 2357@table @option 2358@item gain, g 2359Give the gain at 0 Hz. Its useful range is about -20 2360(for a large cut) to +20 (for a large boost). 2361Beware of clipping when using a positive gain. 2362 2363@item frequency, f 2364Set the filter's central frequency and so can be used 2365to extend or reduce the frequency range to be boosted or cut. 2366The default value is @code{100} Hz. 2367 2368@item width_type, t 2369Set method to specify band-width of filter. 2370@table @option 2371@item h 2372Hz 2373@item q 2374Q-Factor 2375@item o 2376octave 2377@item s 2378slope 2379@item k 2380kHz 2381@end table 2382 2383@item width, w 2384Determine how steep is the filter's shelf transition. 2385 2386@item channels, c 2387Specify which channels to filter, by default all available are filtered. 2388@end table 2389 2390@subsection Commands 2391 2392This filter supports the following commands: 2393@table @option 2394@item frequency, f 2395Change bass frequency. 2396Syntax for the command is : "@var{frequency}" 2397 2398@item width_type, t 2399Change bass width_type. 2400Syntax for the command is : "@var{width_type}" 2401 2402@item width, w 2403Change bass width. 2404Syntax for the command is : "@var{width}" 2405 2406@item gain, g 2407Change bass gain. 2408Syntax for the command is : "@var{gain}" 2409@end table 2410 2411@section biquad 2412 2413Apply a biquad IIR filter with the given coefficients. 2414Where @var{b0}, @var{b1}, @var{b2} and @var{a0}, @var{a1}, @var{a2} 2415are the numerator and denominator coefficients respectively. 2416and @var{channels}, @var{c} specify which channels to filter, by default all 2417available are filtered. 2418 2419@subsection Commands 2420 2421This filter supports the following commands: 2422@table @option 2423@item a0 2424@item a1 2425@item a2 2426@item b0 2427@item b1 2428@item b2 2429Change biquad parameter. 2430Syntax for the command is : "@var{value}" 2431@end table 2432 2433@section bs2b 2434Bauer stereo to binaural transformation, which improves headphone listening of 2435stereo audio records. 2436 2437To enable compilation of this filter you need to configure FFmpeg with 2438@code{--enable-libbs2b}. 2439 2440It accepts the following parameters: 2441@table @option 2442 2443@item profile 2444Pre-defined crossfeed level. 2445@table @option 2446 2447@item default 2448Default level (fcut=700, feed=50). 2449 2450@item cmoy 2451Chu Moy circuit (fcut=700, feed=60). 2452 2453@item jmeier 2454Jan Meier circuit (fcut=650, feed=95). 2455 2456@end table 2457 2458@item fcut 2459Cut frequency (in Hz). 2460 2461@item feed 2462Feed level (in Hz). 2463 2464@end table 2465 2466@section channelmap 2467 2468Remap input channels to new locations. 2469 2470It accepts the following parameters: 2471@table @option 2472@item map 2473Map channels from input to output. The argument is a '|'-separated list of 2474mappings, each in the @code{@var{in_channel}-@var{out_channel}} or 2475@var{in_channel} form. @var{in_channel} can be either the name of the input 2476channel (e.g. FL for front left) or its index in the input channel layout. 2477@var{out_channel} is the name of the output channel or its index in the output 2478channel layout. If @var{out_channel} is not given then it is implicitly an 2479index, starting with zero and increasing by one for each mapping. 2480 2481@item channel_layout 2482The channel layout of the output stream. 2483@end table 2484 2485If no mapping is present, the filter will implicitly map input channels to 2486output channels, preserving indices. 2487 2488@subsection Examples 2489 2490@itemize 2491@item 2492For example, assuming a 5.1+downmix input MOV file, 2493@example 2494ffmpeg -i in.mov -filter 'channelmap=map=DL-FL|DR-FR' out.wav 2495@end example 2496will create an output WAV file tagged as stereo from the downmix channels of 2497the input. 2498 2499@item 2500To fix a 5.1 WAV improperly encoded in AAC's native channel order 2501@example 2502ffmpeg -i in.wav -filter 'channelmap=1|2|0|5|3|4:5.1' out.wav 2503@end example 2504@end itemize 2505 2506@section channelsplit 2507 2508Split each channel from an input audio stream into a separate output stream. 2509 2510It accepts the following parameters: 2511@table @option 2512@item channel_layout 2513The channel layout of the input stream. The default is "stereo". 2514@item channels 2515A channel layout describing the channels to be extracted as separate output streams 2516or "all" to extract each input channel as a separate stream. The default is "all". 2517 2518Choosing channels not present in channel layout in the input will result in an error. 2519@end table 2520 2521@subsection Examples 2522 2523@itemize 2524@item 2525For example, assuming a stereo input MP3 file, 2526@example 2527ffmpeg -i in.mp3 -filter_complex channelsplit out.mkv 2528@end example 2529will create an output Matroska file with two audio streams, one containing only 2530the left channel and the other the right channel. 2531 2532@item 2533Split a 5.1 WAV file into per-channel files: 2534@example 2535ffmpeg -i in.wav -filter_complex 2536'channelsplit=channel_layout=5.1[FL][FR][FC][LFE][SL][SR]' 2537-map '[FL]' front_left.wav -map '[FR]' front_right.wav -map '[FC]' 2538front_center.wav -map '[LFE]' lfe.wav -map '[SL]' side_left.wav -map '[SR]' 2539side_right.wav 2540@end example 2541 2542@item 2543Extract only LFE from a 5.1 WAV file: 2544@example 2545ffmpeg -i in.wav -filter_complex 'channelsplit=channel_layout=5.1:channels=LFE[LFE]' 2546-map '[LFE]' lfe.wav 2547@end example 2548@end itemize 2549 2550@section chorus 2551Add a chorus effect to the audio. 2552 2553Can make a single vocal sound like a chorus, but can also be applied to instrumentation. 2554 2555Chorus resembles an echo effect with a short delay, but whereas with echo the delay is 2556constant, with chorus, it is varied using using sinusoidal or triangular modulation. 2557The modulation depth defines the range the modulated delay is played before or after 2558the delay. Hence the delayed sound will sound slower or faster, that is the delayed 2559sound tuned around the original one, like in a chorus where some vocals are slightly 2560off key. 2561 2562It accepts the following parameters: 2563@table @option 2564@item in_gain 2565Set input gain. Default is 0.4. 2566 2567@item out_gain 2568Set output gain. Default is 0.4. 2569 2570@item delays 2571Set delays. A typical delay is around 40ms to 60ms. 2572 2573@item decays 2574Set decays. 2575 2576@item speeds 2577Set speeds. 2578 2579@item depths 2580Set depths. 2581@end table 2582 2583@subsection Examples 2584 2585@itemize 2586@item 2587A single delay: 2588@example 2589chorus=0.7:0.9:55:0.4:0.25:2 2590@end example 2591 2592@item 2593Two delays: 2594@example 2595chorus=0.6:0.9:50|60:0.4|0.32:0.25|0.4:2|1.3 2596@end example 2597 2598@item 2599Fuller sounding chorus with three delays: 2600@example 2601chorus=0.5:0.9:50|60|40:0.4|0.32|0.3:0.25|0.4|0.3:2|2.3|1.3 2602@end example 2603@end itemize 2604 2605@section compand 2606Compress or expand the audio's dynamic range. 2607 2608It accepts the following parameters: 2609 2610@table @option 2611 2612@item attacks 2613@item decays 2614A list of times in seconds for each channel over which the instantaneous level 2615of the input signal is averaged to determine its volume. @var{attacks} refers to 2616increase of volume and @var{decays} refers to decrease of volume. For most 2617situations, the attack time (response to the audio getting louder) should be 2618shorter than the decay time, because the human ear is more sensitive to sudden 2619loud audio than sudden soft audio. A typical value for attack is 0.3 seconds and 2620a typical value for decay is 0.8 seconds. 2621If specified number of attacks & decays is lower than number of channels, the last 2622set attack/decay will be used for all remaining channels. 2623 2624@item points 2625A list of points for the transfer function, specified in dB relative to the 2626maximum possible signal amplitude. Each key points list must be defined using 2627the following syntax: @code{x0/y0|x1/y1|x2/y2|....} or 2628@code{x0/y0 x1/y1 x2/y2 ....} 2629 2630The input values must be in strictly increasing order but the transfer function 2631does not have to be monotonically rising. The point @code{0/0} is assumed but 2632may be overridden (by @code{0/out-dBn}). Typical values for the transfer 2633function are @code{-70/-70|-60/-20|1/0}. 2634 2635@item soft-knee 2636Set the curve radius in dB for all joints. It defaults to 0.01. 2637 2638@item gain 2639Set the additional gain in dB to be applied at all points on the transfer 2640function. This allows for easy adjustment of the overall gain. 2641It defaults to 0. 2642 2643@item volume 2644Set an initial volume, in dB, to be assumed for each channel when filtering 2645starts. This permits the user to supply a nominal level initially, so that, for 2646example, a very large gain is not applied to initial signal levels before the 2647companding has begun to operate. A typical value for audio which is initially 2648quiet is -90 dB. It defaults to 0. 2649 2650@item delay 2651Set a delay, in seconds. The input audio is analyzed immediately, but audio is 2652delayed before being fed to the volume adjuster. Specifying a delay 2653approximately equal to the attack/decay times allows the filter to effectively 2654operate in predictive rather than reactive mode. It defaults to 0. 2655 2656@end table 2657 2658@subsection Examples 2659 2660@itemize 2661@item 2662Make music with both quiet and loud passages suitable for listening to in a 2663noisy environment: 2664@example 2665compand=.3|.3:1|1:-90/-60|-60/-40|-40/-30|-20/-20:6:0:-90:0.2 2666@end example 2667 2668Another example for audio with whisper and explosion parts: 2669@example 2670compand=0|0:1|1:-90/-900|-70/-70|-30/-9|0/-3:6:0:0:0 2671@end example 2672 2673@item 2674A noise gate for when the noise is at a lower level than the signal: 2675@example 2676compand=.1|.1:.2|.2:-900/-900|-50.1/-900|-50/-50:.01:0:-90:.1 2677@end example 2678 2679@item 2680Here is another noise gate, this time for when the noise is at a higher level 2681than the signal (making it, in some ways, similar to squelch): 2682@example 2683compand=.1|.1:.1|.1:-45.1/-45.1|-45/-900|0/-900:.01:45:-90:.1 2684@end example 2685 2686@item 26872:1 compression starting at -6dB: 2688@example 2689compand=points=-80/-80|-6/-6|0/-3.8|20/3.5 2690@end example 2691 2692@item 26932:1 compression starting at -9dB: 2694@example 2695compand=points=-80/-80|-9/-9|0/-5.3|20/2.9 2696@end example 2697 2698@item 26992:1 compression starting at -12dB: 2700@example 2701compand=points=-80/-80|-12/-12|0/-6.8|20/1.9 2702@end example 2703 2704@item 27052:1 compression starting at -18dB: 2706@example 2707compand=points=-80/-80|-18/-18|0/-9.8|20/0.7 2708@end example 2709 2710@item 27113:1 compression starting at -15dB: 2712@example 2713compand=points=-80/-80|-15/-15|0/-10.8|20/-5.2 2714@end example 2715 2716@item 2717Compressor/Gate: 2718@example 2719compand=points=-80/-105|-62/-80|-15.4/-15.4|0/-12|20/-7.6 2720@end example 2721 2722@item 2723Expander: 2724@example 2725compand=attacks=0:points=-80/-169|-54/-80|-49.5/-64.6|-41.1/-41.1|-25.8/-15|-10.8/-4.5|0/0|20/8.3 2726@end example 2727 2728@item 2729Hard limiter at -6dB: 2730@example 2731compand=attacks=0:points=-80/-80|-6/-6|20/-6 2732@end example 2733 2734@item 2735Hard limiter at -12dB: 2736@example 2737compand=attacks=0:points=-80/-80|-12/-12|20/-12 2738@end example 2739 2740@item 2741Hard noise gate at -35 dB: 2742@example 2743compand=attacks=0:points=-80/-115|-35.1/-80|-35/-35|20/20 2744@end example 2745 2746@item 2747Soft limiter: 2748@example 2749compand=attacks=0:points=-80/-80|-12.4/-12.4|-6/-8|0/-6.8|20/-2.8 2750@end example 2751@end itemize 2752 2753@section compensationdelay 2754 2755Compensation Delay Line is a metric based delay to compensate differing 2756positions of microphones or speakers. 2757 2758For example, you have recorded guitar with two microphones placed in 2759different location. Because the front of sound wave has fixed speed in 2760normal conditions, the phasing of microphones can vary and depends on 2761their location and interposition. The best sound mix can be achieved when 2762these microphones are in phase (synchronized). Note that distance of 2763~30 cm between microphones makes one microphone to capture signal in 2764antiphase to another microphone. That makes the final mix sounding moody. 2765This filter helps to solve phasing problems by adding different delays 2766to each microphone track and make them synchronized. 2767 2768The best result can be reached when you take one track as base and 2769synchronize other tracks one by one with it. 2770Remember that synchronization/delay tolerance depends on sample rate, too. 2771Higher sample rates will give more tolerance. 2772 2773It accepts the following parameters: 2774 2775@table @option 2776@item mm 2777Set millimeters distance. This is compensation distance for fine tuning. 2778Default is 0. 2779 2780@item cm 2781Set cm distance. This is compensation distance for tightening distance setup. 2782Default is 0. 2783 2784@item m 2785Set meters distance. This is compensation distance for hard distance setup. 2786Default is 0. 2787 2788@item dry 2789Set dry amount. Amount of unprocessed (dry) signal. 2790Default is 0. 2791 2792@item wet 2793Set wet amount. Amount of processed (wet) signal. 2794Default is 1. 2795 2796@item temp 2797Set temperature degree in Celsius. This is the temperature of the environment. 2798Default is 20. 2799@end table 2800 2801@section crossfeed 2802Apply headphone crossfeed filter. 2803 2804Crossfeed is the process of blending the left and right channels of stereo 2805audio recording. 2806It is mainly used to reduce extreme stereo separation of low frequencies. 2807 2808The intent is to produce more speaker like sound to the listener. 2809 2810The filter accepts the following options: 2811 2812@table @option 2813@item strength 2814Set strength of crossfeed. Default is 0.2. Allowed range is from 0 to 1. 2815This sets gain of low shelf filter for side part of stereo image. 2816Default is -6dB. Max allowed is -30db when strength is set to 1. 2817 2818@item range 2819Set soundstage wideness. Default is 0.5. Allowed range is from 0 to 1. 2820This sets cut off frequency of low shelf filter. Default is cut off near 28211550 Hz. With range set to 1 cut off frequency is set to 2100 Hz. 2822 2823@item level_in 2824Set input gain. Default is 0.9. 2825 2826@item level_out 2827Set output gain. Default is 1. 2828@end table 2829 2830@section crystalizer 2831Simple algorithm to expand audio dynamic range. 2832 2833The filter accepts the following options: 2834 2835@table @option 2836@item i 2837Sets the intensity of effect (default: 2.0). Must be in range between 0.0 2838(unchanged sound) to 10.0 (maximum effect). 2839 2840@item c 2841Enable clipping. By default is enabled. 2842@end table 2843 2844@section dcshift 2845Apply a DC shift to the audio. 2846 2847This can be useful to remove a DC offset (caused perhaps by a hardware problem 2848in the recording chain) from the audio. The effect of a DC offset is reduced 2849headroom and hence volume. The @ref{astats} filter can be used to determine if 2850a signal has a DC offset. 2851 2852@table @option 2853@item shift 2854Set the DC shift, allowed range is [-1, 1]. It indicates the amount to shift 2855the audio. 2856 2857@item limitergain 2858Optional. It should have a value much less than 1 (e.g. 0.05 or 0.02) and is 2859used to prevent clipping. 2860@end table 2861 2862@section drmeter 2863Measure audio dynamic range. 2864 2865DR values of 14 and higher is found in very dynamic material. DR of 8 to 13 2866is found in transition material. And anything less that 8 have very poor dynamics 2867and is very compressed. 2868 2869The filter accepts the following options: 2870 2871@table @option 2872@item length 2873Set window length in seconds used to split audio into segments of equal length. 2874Default is 3 seconds. 2875@end table 2876 2877@section dynaudnorm 2878Dynamic Audio Normalizer. 2879 2880This filter applies a certain amount of gain to the input audio in order 2881to bring its peak magnitude to a target level (e.g. 0 dBFS). However, in 2882contrast to more "simple" normalization algorithms, the Dynamic Audio 2883Normalizer *dynamically* re-adjusts the gain factor to the input audio. 2884This allows for applying extra gain to the "quiet" sections of the audio 2885while avoiding distortions or clipping the "loud" sections. In other words: 2886The Dynamic Audio Normalizer will "even out" the volume of quiet and loud 2887sections, in the sense that the volume of each section is brought to the 2888same target level. Note, however, that the Dynamic Audio Normalizer achieves 2889this goal *without* applying "dynamic range compressing". It will retain 100% 2890of the dynamic range *within* each section of the audio file. 2891 2892@table @option 2893@item f 2894Set the frame length in milliseconds. In range from 10 to 8000 milliseconds. 2895Default is 500 milliseconds. 2896The Dynamic Audio Normalizer processes the input audio in small chunks, 2897referred to as frames. This is required, because a peak magnitude has no 2898meaning for just a single sample value. Instead, we need to determine the 2899peak magnitude for a contiguous sequence of sample values. While a "standard" 2900normalizer would simply use the peak magnitude of the complete file, the 2901Dynamic Audio Normalizer determines the peak magnitude individually for each 2902frame. The length of a frame is specified in milliseconds. By default, the 2903Dynamic Audio Normalizer uses a frame length of 500 milliseconds, which has 2904been found to give good results with most files. 2905Note that the exact frame length, in number of samples, will be determined 2906automatically, based on the sampling rate of the individual input audio file. 2907 2908@item g 2909Set the Gaussian filter window size. In range from 3 to 301, must be odd 2910number. Default is 31. 2911Probably the most important parameter of the Dynamic Audio Normalizer is the 2912@code{window size} of the Gaussian smoothing filter. The filter's window size 2913is specified in frames, centered around the current frame. For the sake of 2914simplicity, this must be an odd number. Consequently, the default value of 31 2915takes into account the current frame, as well as the 15 preceding frames and 2916the 15 subsequent frames. Using a larger window results in a stronger 2917smoothing effect and thus in less gain variation, i.e. slower gain 2918adaptation. Conversely, using a smaller window results in a weaker smoothing 2919effect and thus in more gain variation, i.e. faster gain adaptation. 2920In other words, the more you increase this value, the more the Dynamic Audio 2921Normalizer will behave like a "traditional" normalization filter. On the 2922contrary, the more you decrease this value, the more the Dynamic Audio 2923Normalizer will behave like a dynamic range compressor. 2924 2925@item p 2926Set the target peak value. This specifies the highest permissible magnitude 2927level for the normalized audio input. This filter will try to approach the 2928target peak magnitude as closely as possible, but at the same time it also 2929makes sure that the normalized signal will never exceed the peak magnitude. 2930A frame's maximum local gain factor is imposed directly by the target peak 2931magnitude. The default value is 0.95 and thus leaves a headroom of 5%*. 2932It is not recommended to go above this value. 2933 2934@item m 2935Set the maximum gain factor. In range from 1.0 to 100.0. Default is 10.0. 2936The Dynamic Audio Normalizer determines the maximum possible (local) gain 2937factor for each input frame, i.e. the maximum gain factor that does not 2938result in clipping or distortion. The maximum gain factor is determined by 2939the frame's highest magnitude sample. However, the Dynamic Audio Normalizer 2940additionally bounds the frame's maximum gain factor by a predetermined 2941(global) maximum gain factor. This is done in order to avoid excessive gain 2942factors in "silent" or almost silent frames. By default, the maximum gain 2943factor is 10.0, For most inputs the default value should be sufficient and 2944it usually is not recommended to increase this value. Though, for input 2945with an extremely low overall volume level, it may be necessary to allow even 2946higher gain factors. Note, however, that the Dynamic Audio Normalizer does 2947not simply apply a "hard" threshold (i.e. cut off values above the threshold). 2948Instead, a "sigmoid" threshold function will be applied. This way, the 2949gain factors will smoothly approach the threshold value, but never exceed that 2950value. 2951 2952@item r 2953Set the target RMS. In range from 0.0 to 1.0. Default is 0.0 - disabled. 2954By default, the Dynamic Audio Normalizer performs "peak" normalization. 2955This means that the maximum local gain factor for each frame is defined 2956(only) by the frame's highest magnitude sample. This way, the samples can 2957be amplified as much as possible without exceeding the maximum signal 2958level, i.e. without clipping. Optionally, however, the Dynamic Audio 2959Normalizer can also take into account the frame's root mean square, 2960abbreviated RMS. In electrical engineering, the RMS is commonly used to 2961determine the power of a time-varying signal. It is therefore considered 2962that the RMS is a better approximation of the "perceived loudness" than 2963just looking at the signal's peak magnitude. Consequently, by adjusting all 2964frames to a constant RMS value, a uniform "perceived loudness" can be 2965established. If a target RMS value has been specified, a frame's local gain 2966factor is defined as the factor that would result in exactly that RMS value. 2967Note, however, that the maximum local gain factor is still restricted by the 2968frame's highest magnitude sample, in order to prevent clipping. 2969 2970@item n 2971Enable channels coupling. By default is enabled. 2972By default, the Dynamic Audio Normalizer will amplify all channels by the same 2973amount. This means the same gain factor will be applied to all channels, i.e. 2974the maximum possible gain factor is determined by the "loudest" channel. 2975However, in some recordings, it may happen that the volume of the different 2976channels is uneven, e.g. one channel may be "quieter" than the other one(s). 2977In this case, this option can be used to disable the channel coupling. This way, 2978the gain factor will be determined independently for each channel, depending 2979only on the individual channel's highest magnitude sample. This allows for 2980harmonizing the volume of the different channels. 2981 2982@item c 2983Enable DC bias correction. By default is disabled. 2984An audio signal (in the time domain) is a sequence of sample values. 2985In the Dynamic Audio Normalizer these sample values are represented in the 2986-1.0 to 1.0 range, regardless of the original input format. Normally, the 2987audio signal, or "waveform", should be centered around the zero point. 2988That means if we calculate the mean value of all samples in a file, or in a 2989single frame, then the result should be 0.0 or at least very close to that 2990value. If, however, there is a significant deviation of the mean value from 29910.0, in either positive or negative direction, this is referred to as a 2992DC bias or DC offset. Since a DC bias is clearly undesirable, the Dynamic 2993Audio Normalizer provides optional DC bias correction. 2994With DC bias correction enabled, the Dynamic Audio Normalizer will determine 2995the mean value, or "DC correction" offset, of each input frame and subtract 2996that value from all of the frame's sample values which ensures those samples 2997are centered around 0.0 again. Also, in order to avoid "gaps" at the frame 2998boundaries, the DC correction offset values will be interpolated smoothly 2999between neighbouring frames. 3000 3001@item b 3002Enable alternative boundary mode. By default is disabled. 3003The Dynamic Audio Normalizer takes into account a certain neighbourhood 3004around each frame. This includes the preceding frames as well as the 3005subsequent frames. However, for the "boundary" frames, located at the very 3006beginning and at the very end of the audio file, not all neighbouring 3007frames are available. In particular, for the first few frames in the audio 3008file, the preceding frames are not known. And, similarly, for the last few 3009frames in the audio file, the subsequent frames are not known. Thus, the 3010question arises which gain factors should be assumed for the missing frames 3011in the "boundary" region. The Dynamic Audio Normalizer implements two modes 3012to deal with this situation. The default boundary mode assumes a gain factor 3013of exactly 1.0 for the missing frames, resulting in a smooth "fade in" and 3014"fade out" at the beginning and at the end of the input, respectively. 3015 3016@item s 3017Set the compress factor. In range from 0.0 to 30.0. Default is 0.0. 3018By default, the Dynamic Audio Normalizer does not apply "traditional" 3019compression. This means that signal peaks will not be pruned and thus the 3020full dynamic range will be retained within each local neighbourhood. However, 3021in some cases it may be desirable to combine the Dynamic Audio Normalizer's 3022normalization algorithm with a more "traditional" compression. 3023For this purpose, the Dynamic Audio Normalizer provides an optional compression 3024(thresholding) function. If (and only if) the compression feature is enabled, 3025all input frames will be processed by a soft knee thresholding function prior 3026to the actual normalization process. Put simply, the thresholding function is 3027going to prune all samples whose magnitude exceeds a certain threshold value. 3028However, the Dynamic Audio Normalizer does not simply apply a fixed threshold 3029value. Instead, the threshold value will be adjusted for each individual 3030frame. 3031In general, smaller parameters result in stronger compression, and vice versa. 3032Values below 3.0 are not recommended, because audible distortion may appear. 3033@end table 3034 3035@section earwax 3036 3037Make audio easier to listen to on headphones. 3038 3039This filter adds `cues' to 44.1kHz stereo (i.e. audio CD format) audio 3040so that when listened to on headphones the stereo image is moved from 3041inside your head (standard for headphones) to outside and in front of 3042the listener (standard for speakers). 3043 3044Ported from SoX. 3045 3046@section equalizer 3047 3048Apply a two-pole peaking equalisation (EQ) filter. With this 3049filter, the signal-level at and around a selected frequency can 3050be increased or decreased, whilst (unlike bandpass and bandreject 3051filters) that at all other frequencies is unchanged. 3052 3053In order to produce complex equalisation curves, this filter can 3054be given several times, each with a different central frequency. 3055 3056The filter accepts the following options: 3057 3058@table @option 3059@item frequency, f 3060Set the filter's central frequency in Hz. 3061 3062@item width_type, t 3063Set method to specify band-width of filter. 3064@table @option 3065@item h 3066Hz 3067@item q 3068Q-Factor 3069@item o 3070octave 3071@item s 3072slope 3073@item k 3074kHz 3075@end table 3076 3077@item width, w 3078Specify the band-width of a filter in width_type units. 3079 3080@item gain, g 3081Set the required gain or attenuation in dB. 3082Beware of clipping when using a positive gain. 3083 3084@item channels, c 3085Specify which channels to filter, by default all available are filtered. 3086@end table 3087 3088@subsection Examples 3089@itemize 3090@item 3091Attenuate 10 dB at 1000 Hz, with a bandwidth of 200 Hz: 3092@example 3093equalizer=f=1000:t=h:width=200:g=-10 3094@end example 3095 3096@item 3097Apply 2 dB gain at 1000 Hz with Q 1 and attenuate 5 dB at 100 Hz with Q 2: 3098@example 3099equalizer=f=1000:t=q:w=1:g=2,equalizer=f=100:t=q:w=2:g=-5 3100@end example 3101@end itemize 3102 3103@subsection Commands 3104 3105This filter supports the following commands: 3106@table @option 3107@item frequency, f 3108Change equalizer frequency. 3109Syntax for the command is : "@var{frequency}" 3110 3111@item width_type, t 3112Change equalizer width_type. 3113Syntax for the command is : "@var{width_type}" 3114 3115@item width, w 3116Change equalizer width. 3117Syntax for the command is : "@var{width}" 3118 3119@item gain, g 3120Change equalizer gain. 3121Syntax for the command is : "@var{gain}" 3122@end table 3123 3124@section extrastereo 3125 3126Linearly increases the difference between left and right channels which 3127adds some sort of "live" effect to playback. 3128 3129The filter accepts the following options: 3130 3131@table @option 3132@item m 3133Sets the difference coefficient (default: 2.5). 0.0 means mono sound 3134(average of both channels), with 1.0 sound will be unchanged, with 3135-1.0 left and right channels will be swapped. 3136 3137@item c 3138Enable clipping. By default is enabled. 3139@end table 3140 3141@section firequalizer 3142Apply FIR Equalization using arbitrary frequency response. 3143 3144The filter accepts the following option: 3145 3146@table @option 3147@item gain 3148Set gain curve equation (in dB). The expression can contain variables: 3149@table @option 3150@item f 3151the evaluated frequency 3152@item sr 3153sample rate 3154@item ch 3155channel number, set to 0 when multichannels evaluation is disabled 3156@item chid 3157channel id, see libavutil/channel_layout.h, set to the first channel id when 3158multichannels evaluation is disabled 3159@item chs 3160number of channels 3161@item chlayout 3162channel_layout, see libavutil/channel_layout.h 3163 3164@end table 3165and functions: 3166@table @option 3167@item gain_interpolate(f) 3168interpolate gain on frequency f based on gain_entry 3169@item cubic_interpolate(f) 3170same as gain_interpolate, but smoother 3171@end table 3172This option is also available as command. Default is @code{gain_interpolate(f)}. 3173 3174@item gain_entry 3175Set gain entry for gain_interpolate function. The expression can 3176contain functions: 3177@table @option 3178@item entry(f, g) 3179store gain entry at frequency f with value g 3180@end table 3181This option is also available as command. 3182 3183@item delay 3184Set filter delay in seconds. Higher value means more accurate. 3185Default is @code{0.01}. 3186 3187@item accuracy 3188Set filter accuracy in Hz. Lower value means more accurate. 3189Default is @code{5}. 3190 3191@item wfunc 3192Set window function. Acceptable values are: 3193@table @option 3194@item rectangular 3195rectangular window, useful when gain curve is already smooth 3196@item hann 3197hann window (default) 3198@item hamming 3199hamming window 3200@item blackman 3201blackman window 3202@item nuttall3 32033-terms continuous 1st derivative nuttall window 3204@item mnuttall3 3205minimum 3-terms discontinuous nuttall window 3206@item nuttall 32074-terms continuous 1st derivative nuttall window 3208@item bnuttall 3209minimum 4-terms discontinuous nuttall (blackman-nuttall) window 3210@item bharris 3211blackman-harris window 3212@item tukey 3213tukey window 3214@end table 3215 3216@item fixed 3217If enabled, use fixed number of audio samples. This improves speed when 3218filtering with large delay. Default is disabled. 3219 3220@item multi 3221Enable multichannels evaluation on gain. Default is disabled. 3222 3223@item zero_phase 3224Enable zero phase mode by subtracting timestamp to compensate delay. 3225Default is disabled. 3226 3227@item scale 3228Set scale used by gain. Acceptable values are: 3229@table @option 3230@item linlin 3231linear frequency, linear gain 3232@item linlog 3233linear frequency, logarithmic (in dB) gain (default) 3234@item loglin 3235logarithmic (in octave scale where 20 Hz is 0) frequency, linear gain 3236@item loglog 3237logarithmic frequency, logarithmic gain 3238@end table 3239 3240@item dumpfile 3241Set file for dumping, suitable for gnuplot. 3242 3243@item dumpscale 3244Set scale for dumpfile. Acceptable values are same with scale option. 3245Default is linlog. 3246 3247@item fft2 3248Enable 2-channel convolution using complex FFT. This improves speed significantly. 3249Default is disabled. 3250 3251@item min_phase 3252Enable minimum phase impulse response. Default is disabled. 3253@end table 3254 3255@subsection Examples 3256@itemize 3257@item 3258lowpass at 1000 Hz: 3259@example 3260firequalizer=gain='if(lt(f,1000), 0, -INF)' 3261@end example 3262@item 3263lowpass at 1000 Hz with gain_entry: 3264@example 3265firequalizer=gain_entry='entry(1000,0); entry(1001, -INF)' 3266@end example 3267@item 3268custom equalization: 3269@example 3270firequalizer=gain_entry='entry(100,0); entry(400, -4); entry(1000, -6); entry(2000, 0)' 3271@end example 3272@item 3273higher delay with zero phase to compensate delay: 3274@example 3275firequalizer=delay=0.1:fixed=on:zero_phase=on 3276@end example 3277@item 3278lowpass on left channel, highpass on right channel: 3279@example 3280firequalizer=gain='if(eq(chid,1), gain_interpolate(f), if(eq(chid,2), gain_interpolate(1e6+f), 0))' 3281:gain_entry='entry(1000, 0); entry(1001,-INF); entry(1e6+1000,0)':multi=on 3282@end example 3283@end itemize 3284 3285@section flanger 3286Apply a flanging effect to the audio. 3287 3288The filter accepts the following options: 3289 3290@table @option 3291@item delay 3292Set base delay in milliseconds. Range from 0 to 30. Default value is 0. 3293 3294@item depth 3295Set added sweep delay in milliseconds. Range from 0 to 10. Default value is 2. 3296 3297@item regen 3298Set percentage regeneration (delayed signal feedback). Range from -95 to 95. 3299Default value is 0. 3300 3301@item width 3302Set percentage of delayed signal mixed with original. Range from 0 to 100. 3303Default value is 71. 3304 3305@item speed 3306Set sweeps per second (Hz). Range from 0.1 to 10. Default value is 0.5. 3307 3308@item shape 3309Set swept wave shape, can be @var{triangular} or @var{sinusoidal}. 3310Default value is @var{sinusoidal}. 3311 3312@item phase 3313Set swept wave percentage-shift for multi channel. Range from 0 to 100. 3314Default value is 25. 3315 3316@item interp 3317Set delay-line interpolation, @var{linear} or @var{quadratic}. 3318Default is @var{linear}. 3319@end table 3320 3321@section haas 3322Apply Haas effect to audio. 3323 3324Note that this makes most sense to apply on mono signals. 3325With this filter applied to mono signals it give some directionality and 3326stretches its stereo image. 3327 3328The filter accepts the following options: 3329 3330@table @option 3331@item level_in 3332Set input level. By default is @var{1}, or 0dB 3333 3334@item level_out 3335Set output level. By default is @var{1}, or 0dB. 3336 3337@item side_gain 3338Set gain applied to side part of signal. By default is @var{1}. 3339 3340@item middle_source 3341Set kind of middle source. Can be one of the following: 3342 3343@table @samp 3344@item left 3345Pick left channel. 3346 3347@item right 3348Pick right channel. 3349 3350@item mid 3351Pick middle part signal of stereo image. 3352 3353@item side 3354Pick side part signal of stereo image. 3355@end table 3356 3357@item middle_phase 3358Change middle phase. By default is disabled. 3359 3360@item left_delay 3361Set left channel delay. By default is @var{2.05} milliseconds. 3362 3363@item left_balance 3364Set left channel balance. By default is @var{-1}. 3365 3366@item left_gain 3367Set left channel gain. By default is @var{1}. 3368 3369@item left_phase 3370Change left phase. By default is disabled. 3371 3372@item right_delay 3373Set right channel delay. By defaults is @var{2.12} milliseconds. 3374 3375@item right_balance 3376Set right channel balance. By default is @var{1}. 3377 3378@item right_gain 3379Set right channel gain. By default is @var{1}. 3380 3381@item right_phase 3382Change right phase. By default is enabled. 3383@end table 3384 3385@section hdcd 3386 3387Decodes High Definition Compatible Digital (HDCD) data. A 16-bit PCM stream with 3388embedded HDCD codes is expanded into a 20-bit PCM stream. 3389 3390The filter supports the Peak Extend and Low-level Gain Adjustment features 3391of HDCD, and detects the Transient Filter flag. 3392 3393@example 3394ffmpeg -i HDCD16.flac -af hdcd OUT24.flac 3395@end example 3396 3397When using the filter with wav, note the default encoding for wav is 16-bit, 3398so the resulting 20-bit stream will be truncated back to 16-bit. Use something 3399like @command{-acodec pcm_s24le} after the filter to get 24-bit PCM output. 3400@example 3401ffmpeg -i HDCD16.wav -af hdcd OUT16.wav 3402ffmpeg -i HDCD16.wav -af hdcd -c:a pcm_s24le OUT24.wav 3403@end example 3404 3405The filter accepts the following options: 3406 3407@table @option 3408@item disable_autoconvert 3409Disable any automatic format conversion or resampling in the filter graph. 3410 3411@item process_stereo 3412Process the stereo channels together. If target_gain does not match between 3413channels, consider it invalid and use the last valid target_gain. 3414 3415@item cdt_ms 3416Set the code detect timer period in ms. 3417 3418@item force_pe 3419Always extend peaks above -3dBFS even if PE isn't signaled. 3420 3421@item analyze_mode 3422Replace audio with a solid tone and adjust the amplitude to signal some 3423specific aspect of the decoding process. The output file can be loaded in 3424an audio editor alongside the original to aid analysis. 3425 3426@code{analyze_mode=pe:force_pe=true} can be used to see all samples above the PE level. 3427 3428Modes are: 3429@table @samp 3430@item 0, off 3431Disabled 3432@item 1, lle 3433Gain adjustment level at each sample 3434@item 2, pe 3435Samples where peak extend occurs 3436@item 3, cdt 3437Samples where the code detect timer is active 3438@item 4, tgm 3439Samples where the target gain does not match between channels 3440@end table 3441@end table 3442 3443@section headphone 3444 3445Apply head-related transfer functions (HRTFs) to create virtual 3446loudspeakers around the user for binaural listening via headphones. 3447The HRIRs are provided via additional streams, for each channel 3448one stereo input stream is needed. 3449 3450The filter accepts the following options: 3451 3452@table @option 3453@item map 3454Set mapping of input streams for convolution. 3455The argument is a '|'-separated list of channel names in order as they 3456are given as additional stream inputs for filter. 3457This also specify number of input streams. Number of input streams 3458must be not less than number of channels in first stream plus one. 3459 3460@item gain 3461Set gain applied to audio. Value is in dB. Default is 0. 3462 3463@item type 3464Set processing type. Can be @var{time} or @var{freq}. @var{time} is 3465processing audio in time domain which is slow. 3466@var{freq} is processing audio in frequency domain which is fast. 3467Default is @var{freq}. 3468 3469@item lfe 3470Set custom gain for LFE channels. Value is in dB. Default is 0. 3471 3472@item size 3473Set size of frame in number of samples which will be processed at once. 3474Default value is @var{1024}. Allowed range is from 1024 to 96000. 3475 3476@item hrir 3477Set format of hrir stream. 3478Default value is @var{stereo}. Alternative value is @var{multich}. 3479If value is set to @var{stereo}, number of additional streams should 3480be greater or equal to number of input channels in first input stream. 3481Also each additional stream should have stereo number of channels. 3482If value is set to @var{multich}, number of additional streams should 3483be exactly one. Also number of input channels of additional stream 3484should be equal or greater than twice number of channels of first input 3485stream. 3486@end table 3487 3488@subsection Examples 3489 3490@itemize 3491@item 3492Full example using wav files as coefficients with amovie filters for 7.1 downmix, 3493each amovie filter use stereo file with IR coefficients as input. 3494The files give coefficients for each position of virtual loudspeaker: 3495@example 3496ffmpeg -i input.wav -lavfi-complex "amovie=azi_270_ele_0_DFC.wav[sr],amovie=azi_90_ele_0_DFC.wav[sl],amovie=azi_225_ele_0_DFC.wav[br],amovie=azi_135_ele_0_DFC.wav[bl],amovie=azi_0_ele_0_DFC.wav,asplit[fc][lfe],amovie=azi_35_ele_0_DFC.wav[fl],amovie=azi_325_ele_0_DFC.wav[fr],[a:0][fl][fr][fc][lfe][bl][br][sl][sr]headphone=FL|FR|FC|LFE|BL|BR|SL|SR" 3497output.wav 3498@end example 3499 3500@item 3501Full example using wav files as coefficients with amovie filters for 7.1 downmix, 3502but now in @var{multich} @var{hrir} format. 3503@example 3504ffmpeg -i input.wav -lavfi-complex "amovie=minp.wav[hrirs],[a:0][hrirs]headphone=map=FL|FR|FC|LFE|BL|BR|SL|SR:hrir=multich" 3505output.wav 3506@end example 3507@end itemize 3508 3509@section highpass 3510 3511Apply a high-pass filter with 3dB point frequency. 3512The filter can be either single-pole, or double-pole (the default). 3513The filter roll off at 6dB per pole per octave (20dB per pole per decade). 3514 3515The filter accepts the following options: 3516 3517@table @option 3518@item frequency, f 3519Set frequency in Hz. Default is 3000. 3520 3521@item poles, p 3522Set number of poles. Default is 2. 3523 3524@item width_type, t 3525Set method to specify band-width of filter. 3526@table @option 3527@item h 3528Hz 3529@item q 3530Q-Factor 3531@item o 3532octave 3533@item s 3534slope 3535@item k 3536kHz 3537@end table 3538 3539@item width, w 3540Specify the band-width of a filter in width_type units. 3541Applies only to double-pole filter. 3542The default is 0.707q and gives a Butterworth response. 3543 3544@item channels, c 3545Specify which channels to filter, by default all available are filtered. 3546@end table 3547 3548@subsection Commands 3549 3550This filter supports the following commands: 3551@table @option 3552@item frequency, f 3553Change highpass frequency. 3554Syntax for the command is : "@var{frequency}" 3555 3556@item width_type, t 3557Change highpass width_type. 3558Syntax for the command is : "@var{width_type}" 3559 3560@item width, w 3561Change highpass width. 3562Syntax for the command is : "@var{width}" 3563@end table 3564 3565@section join 3566 3567Join multiple input streams into one multi-channel stream. 3568 3569It accepts the following parameters: 3570@table @option 3571 3572@item inputs 3573The number of input streams. It defaults to 2. 3574 3575@item channel_layout 3576The desired output channel layout. It defaults to stereo. 3577 3578@item map 3579Map channels from inputs to output. The argument is a '|'-separated list of 3580mappings, each in the @code{@var{input_idx}.@var{in_channel}-@var{out_channel}} 3581form. @var{input_idx} is the 0-based index of the input stream. @var{in_channel} 3582can be either the name of the input channel (e.g. FL for front left) or its 3583index in the specified input stream. @var{out_channel} is the name of the output 3584channel. 3585@end table 3586 3587The filter will attempt to guess the mappings when they are not specified 3588explicitly. It does so by first trying to find an unused matching input channel 3589and if that fails it picks the first unused input channel. 3590 3591Join 3 inputs (with properly set channel layouts): 3592@example 3593ffmpeg -i INPUT1 -i INPUT2 -i INPUT3 -filter_complex join=inputs=3 OUTPUT 3594@end example 3595 3596Build a 5.1 output from 6 single-channel streams: 3597@example 3598ffmpeg -i fl -i fr -i fc -i sl -i sr -i lfe -filter_complex 3599'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' 3600out 3601@end example 3602 3603@section ladspa 3604 3605Load a LADSPA (Linux Audio Developer's Simple Plugin API) plugin. 3606 3607To enable compilation of this filter you need to configure FFmpeg with 3608@code{--enable-ladspa}. 3609 3610@table @option 3611@item file, f 3612Specifies the name of LADSPA plugin library to load. If the environment 3613variable @env{LADSPA_PATH} is defined, the LADSPA plugin is searched in 3614each one of the directories specified by the colon separated list in 3615@env{LADSPA_PATH}, otherwise in the standard LADSPA paths, which are in 3616this order: @file{HOME/.ladspa/lib/}, @file{/usr/local/lib/ladspa/}, 3617@file{/usr/lib/ladspa/}. 3618 3619@item plugin, p 3620Specifies the plugin within the library. Some libraries contain only 3621one plugin, but others contain many of them. If this is not set filter 3622will list all available plugins within the specified library. 3623 3624@item controls, c 3625Set the '|' separated list of controls which are zero or more floating point 3626values that determine the behavior of the loaded plugin (for example delay, 3627threshold or gain). 3628Controls need to be defined using the following syntax: 3629c0=@var{value0}|c1=@var{value1}|c2=@var{value2}|..., where 3630@var{valuei} is the value set on the @var{i}-th control. 3631Alternatively they can be also defined using the following syntax: 3632@var{value0}|@var{value1}|@var{value2}|..., where 3633@var{valuei} is the value set on the @var{i}-th control. 3634If @option{controls} is set to @code{help}, all available controls and 3635their valid ranges are printed. 3636 3637@item sample_rate, s 3638Specify the sample rate, default to 44100. Only used if plugin have 3639zero inputs. 3640 3641@item nb_samples, n 3642Set the number of samples per channel per each output frame, default 3643is 1024. Only used if plugin have zero inputs. 3644 3645@item duration, d 3646Set the minimum duration of the sourced audio. See 3647@ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils} 3648for the accepted syntax. 3649Note that the resulting duration may be greater than the specified duration, 3650as the generated audio is always cut at the end of a complete frame. 3651If not specified, or the expressed duration is negative, the audio is 3652supposed to be generated forever. 3653Only used if plugin have zero inputs. 3654 3655@end table 3656 3657@subsection Examples 3658 3659@itemize 3660@item 3661List all available plugins within amp (LADSPA example plugin) library: 3662@example 3663ladspa=file=amp 3664@end example 3665 3666@item 3667List all available controls and their valid ranges for @code{vcf_notch} 3668plugin from @code{VCF} library: 3669@example 3670ladspa=f=vcf:p=vcf_notch:c=help 3671@end example 3672 3673@item 3674Simulate low quality audio equipment using @code{Computer Music Toolkit} (CMT) 3675plugin library: 3676@example 3677ladspa=file=cmt:plugin=lofi:controls=c0=22|c1=12|c2=12 3678@end example 3679 3680@item 3681Add reverberation to the audio using TAP-plugins 3682(Tom's Audio Processing plugins): 3683@example 3684ladspa=file=tap_reverb:tap_reverb 3685@end example 3686 3687@item 3688Generate white noise, with 0.2 amplitude: 3689@example 3690ladspa=file=cmt:noise_source_white:c=c0=.2 3691@end example 3692 3693@item 3694Generate 20 bpm clicks using plugin @code{C* Click - Metronome} from the 3695@code{C* Audio Plugin Suite} (CAPS) library: 3696@example 3697ladspa=file=caps:Click:c=c1=20' 3698@end example 3699 3700@item 3701Apply @code{C* Eq10X2 - Stereo 10-band equaliser} effect: 3702@example 3703ladspa=caps:Eq10X2:c=c0=-48|c9=-24|c3=12|c4=2 3704@end example 3705 3706@item 3707Increase volume by 20dB using fast lookahead limiter from Steve Harris 3708@code{SWH Plugins} collection: 3709@example 3710ladspa=fast_lookahead_limiter_1913:fastLookaheadLimiter:20|0|2 3711@end example 3712 3713@item 3714Attenuate low frequencies using Multiband EQ from Steve Harris 3715@code{SWH Plugins} collection: 3716@example 3717ladspa=mbeq_1197:mbeq:-24|-24|-24|0|0|0|0|0|0|0|0|0|0|0|0 3718@end example 3719 3720@item 3721Reduce stereo image using @code{Narrower} from the @code{C* Audio Plugin Suite} 3722(CAPS) library: 3723@example 3724ladspa=caps:Narrower 3725@end example 3726 3727@item 3728Another white noise, now using @code{C* Audio Plugin Suite} (CAPS) library: 3729@example 3730ladspa=caps:White:.2 3731@end example 3732 3733@item 3734Some fractal noise, using @code{C* Audio Plugin Suite} (CAPS) library: 3735@example 3736ladspa=caps:Fractal:c=c1=1 3737@end example 3738 3739@item 3740Dynamic volume normalization using @code{VLevel} plugin: 3741@example 3742ladspa=vlevel-ladspa:vlevel_mono 3743@end example 3744@end itemize 3745 3746@subsection Commands 3747 3748This filter supports the following commands: 3749@table @option 3750@item cN 3751Modify the @var{N}-th control value. 3752 3753If the specified value is not valid, it is ignored and prior one is kept. 3754@end table 3755 3756@section loudnorm 3757 3758EBU R128 loudness normalization. Includes both dynamic and linear normalization modes. 3759Support for both single pass (livestreams, files) and double pass (files) modes. 3760This algorithm can target IL, LRA, and maximum true peak. To accurately detect true peaks, 3761the audio stream will be upsampled to 192 kHz unless the normalization mode is linear. 3762Use the @code{-ar} option or @code{aresample} filter to explicitly set an output sample rate. 3763 3764The filter accepts the following options: 3765 3766@table @option 3767@item I, i 3768Set integrated loudness target. 3769Range is -70.0 - -5.0. Default value is -24.0. 3770 3771@item LRA, lra 3772Set loudness range target. 3773Range is 1.0 - 20.0. Default value is 7.0. 3774 3775@item TP, tp 3776Set maximum true peak. 3777Range is -9.0 - +0.0. Default value is -2.0. 3778 3779@item measured_I, measured_i 3780Measured IL of input file. 3781Range is -99.0 - +0.0. 3782 3783@item measured_LRA, measured_lra 3784Measured LRA of input file. 3785Range is 0.0 - 99.0. 3786 3787@item measured_TP, measured_tp 3788Measured true peak of input file. 3789Range is -99.0 - +99.0. 3790 3791@item measured_thresh 3792Measured threshold of input file. 3793Range is -99.0 - +0.0. 3794 3795@item offset 3796Set offset gain. Gain is applied before the true-peak limiter. 3797Range is -99.0 - +99.0. Default is +0.0. 3798 3799@item linear 3800Normalize linearly if possible. 3801measured_I, measured_LRA, measured_TP, and measured_thresh must also 3802to be specified in order to use this mode. 3803Options are true or false. Default is true. 3804 3805@item dual_mono 3806Treat mono input files as "dual-mono". If a mono file is intended for playback 3807on a stereo system, its EBU R128 measurement will be perceptually incorrect. 3808If set to @code{true}, this option will compensate for this effect. 3809Multi-channel input files are not affected by this option. 3810Options are true or false. Default is false. 3811 3812@item print_format 3813Set print format for stats. Options are summary, json, or none. 3814Default value is none. 3815@end table 3816 3817@section lowpass 3818 3819Apply a low-pass filter with 3dB point frequency. 3820The filter can be either single-pole or double-pole (the default). 3821The filter roll off at 6dB per pole per octave (20dB per pole per decade). 3822 3823The filter accepts the following options: 3824 3825@table @option 3826@item frequency, f 3827Set frequency in Hz. Default is 500. 3828 3829@item poles, p 3830Set number of poles. Default is 2. 3831 3832@item width_type, t 3833Set method to specify band-width of filter. 3834@table @option 3835@item h 3836Hz 3837@item q 3838Q-Factor 3839@item o 3840octave 3841@item s 3842slope 3843@item k 3844kHz 3845@end table 3846 3847@item width, w 3848Specify the band-width of a filter in width_type units. 3849Applies only to double-pole filter. 3850The default is 0.707q and gives a Butterworth response. 3851 3852@item channels, c 3853Specify which channels to filter, by default all available are filtered. 3854@end table 3855 3856@subsection Examples 3857@itemize 3858@item 3859Lowpass only LFE channel, it LFE is not present it does nothing: 3860@example 3861lowpass=c=LFE 3862@end example 3863@end itemize 3864 3865@subsection Commands 3866 3867This filter supports the following commands: 3868@table @option 3869@item frequency, f 3870Change lowpass frequency. 3871Syntax for the command is : "@var{frequency}" 3872 3873@item width_type, t 3874Change lowpass width_type. 3875Syntax for the command is : "@var{width_type}" 3876 3877@item width, w 3878Change lowpass width. 3879Syntax for the command is : "@var{width}" 3880@end table 3881 3882@section lv2 3883 3884Load a LV2 (LADSPA Version 2) plugin. 3885 3886To enable compilation of this filter you need to configure FFmpeg with 3887@code{--enable-lv2}. 3888 3889@table @option 3890@item plugin, p 3891Specifies the plugin URI. You may need to escape ':'. 3892 3893@item controls, c 3894Set the '|' separated list of controls which are zero or more floating point 3895values that determine the behavior of the loaded plugin (for example delay, 3896threshold or gain). 3897If @option{controls} is set to @code{help}, all available controls and 3898their valid ranges are printed. 3899 3900@item sample_rate, s 3901Specify the sample rate, default to 44100. Only used if plugin have 3902zero inputs. 3903 3904@item nb_samples, n 3905Set the number of samples per channel per each output frame, default 3906is 1024. Only used if plugin have zero inputs. 3907 3908@item duration, d 3909Set the minimum duration of the sourced audio. See 3910@ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils} 3911for the accepted syntax. 3912Note that the resulting duration may be greater than the specified duration, 3913as the generated audio is always cut at the end of a complete frame. 3914If not specified, or the expressed duration is negative, the audio is 3915supposed to be generated forever. 3916Only used if plugin have zero inputs. 3917@end table 3918 3919@subsection Examples 3920 3921@itemize 3922@item 3923Apply bass enhancer plugin from Calf: 3924@example 3925lv2=p=http\\\\://calf.sourceforge.net/plugins/BassEnhancer:c=amount=2 3926@end example 3927 3928@item 3929Apply vinyl plugin from Calf: 3930@example 3931lv2=p=http\\\\://calf.sourceforge.net/plugins/Vinyl:c=drone=0.2|aging=0.5 3932@end example 3933 3934@item 3935Apply bit crusher plugin from ArtyFX: 3936@example 3937lv2=p=http\\\\://www.openavproductions.com/artyfx#bitta:c=crush=0.3 3938@end example 3939@end itemize 3940 3941@section mcompand 3942Multiband Compress or expand the audio's dynamic range. 3943 3944The input audio is divided into bands using 4th order Linkwitz-Riley IIRs. 3945This is akin to the crossover of a loudspeaker, and results in flat frequency 3946response when absent compander action. 3947 3948It accepts the following parameters: 3949 3950@table @option 3951@item args 3952This option syntax is: 3953attack,decay,[attack,decay..] soft-knee points crossover_frequency [delay [initial_volume [gain]]] | attack,decay ... 3954For explanation of each item refer to compand filter documentation. 3955@end table 3956 3957@anchor{pan} 3958@section pan 3959 3960Mix channels with specific gain levels. The filter accepts the output 3961channel layout followed by a set of channels definitions. 3962 3963This filter is also designed to efficiently remap the channels of an audio 3964stream. 3965 3966The filter accepts parameters of the form: 3967"@var{l}|@var{outdef}|@var{outdef}|..." 3968 3969@table @option 3970@item l 3971output channel layout or number of channels 3972 3973@item outdef 3974output channel specification, of the form: 3975"@var{out_name}=[@var{gain}*]@var{in_name}[(+-)[@var{gain}*]@var{in_name}...]" 3976 3977@item out_name 3978output channel to define, either a channel name (FL, FR, etc.) or a channel 3979number (c0, c1, etc.) 3980 3981@item gain 3982multiplicative coefficient for the channel, 1 leaving the volume unchanged 3983 3984@item in_name 3985input channel to use, see out_name for details; it is not possible to mix 3986named and numbered input channels 3987@end table 3988 3989If the `=' in a channel specification is replaced by `<', then the gains for 3990that specification will be renormalized so that the total is 1, thus 3991avoiding clipping noise. 3992 3993@subsection Mixing examples 3994 3995For example, if you want to down-mix from stereo to mono, but with a bigger 3996factor for the left channel: 3997@example 3998pan=1c|c0=0.9*c0+0.1*c1 3999@end example 4000 4001A customized down-mix to stereo that works automatically for 3-, 4-, 5- and 40027-channels surround: 4003@example 4004pan=stereo| FL < FL + 0.5*FC + 0.6*BL + 0.6*SL | FR < FR + 0.5*FC + 0.6*BR + 0.6*SR 4005@end example 4006 4007Note that @command{ffmpeg} integrates a default down-mix (and up-mix) system 4008that should be preferred (see "-ac" option) unless you have very specific 4009needs. 4010 4011@subsection Remapping examples 4012 4013The channel remapping will be effective if, and only if: 4014 4015@itemize 4016@item gain coefficients are zeroes or ones, 4017@item only one input per channel output, 4018@end itemize 4019 4020If all these conditions are satisfied, the filter will notify the user ("Pure 4021channel mapping detected"), and use an optimized and lossless method to do the 4022remapping. 4023 4024For example, if you have a 5.1 source and want a stereo audio stream by 4025dropping the extra channels: 4026@example 4027pan="stereo| c0=FL | c1=FR" 4028@end example 4029 4030Given the same source, you can also switch front left and front right channels 4031and keep the input channel layout: 4032@example 4033pan="5.1| c0=c1 | c1=c0 | c2=c2 | c3=c3 | c4=c4 | c5=c5" 4034@end example 4035 4036If the input is a stereo audio stream, you can mute the front left channel (and 4037still keep the stereo channel layout) with: 4038@example 4039pan="stereo|c1=c1" 4040@end example 4041 4042Still with a stereo audio stream input, you can copy the right channel in both 4043front left and right: 4044@example 4045pan="stereo| c0=FR | c1=FR" 4046@end example 4047 4048@section replaygain 4049 4050ReplayGain scanner filter. This filter takes an audio stream as an input and 4051outputs it unchanged. 4052At end of filtering it displays @code{track_gain} and @code{track_peak}. 4053 4054@section resample 4055 4056Convert the audio sample format, sample rate and channel layout. It is 4057not meant to be used directly. 4058 4059@section rubberband 4060Apply time-stretching and pitch-shifting with librubberband. 4061 4062To enable compilation of this filter, you need to configure FFmpeg with 4063@code{--enable-librubberband}. 4064 4065The filter accepts the following options: 4066 4067@table @option 4068@item tempo 4069Set tempo scale factor. 4070 4071@item pitch 4072Set pitch scale factor. 4073 4074@item transients 4075Set transients detector. 4076Possible values are: 4077@table @var 4078@item crisp 4079@item mixed 4080@item smooth 4081@end table 4082 4083@item detector 4084Set detector. 4085Possible values are: 4086@table @var 4087@item compound 4088@item percussive 4089@item soft 4090@end table 4091 4092@item phase 4093Set phase. 4094Possible values are: 4095@table @var 4096@item laminar 4097@item independent 4098@end table 4099 4100@item window 4101Set processing window size. 4102Possible values are: 4103@table @var 4104@item standard 4105@item short 4106@item long 4107@end table 4108 4109@item smoothing 4110Set smoothing. 4111Possible values are: 4112@table @var 4113@item off 4114@item on 4115@end table 4116 4117@item formant 4118Enable formant preservation when shift pitching. 4119Possible values are: 4120@table @var 4121@item shifted 4122@item preserved 4123@end table 4124 4125@item pitchq 4126Set pitch quality. 4127Possible values are: 4128@table @var 4129@item quality 4130@item speed 4131@item consistency 4132@end table 4133 4134@item channels 4135Set channels. 4136Possible values are: 4137@table @var 4138@item apart 4139@item together 4140@end table 4141@end table 4142 4143@section sidechaincompress 4144 4145This filter acts like normal compressor but has the ability to compress 4146detected signal using second input signal. 4147It needs two input streams and returns one output stream. 4148First input stream will be processed depending on second stream signal. 4149The filtered signal then can be filtered with other filters in later stages of 4150processing. See @ref{pan} and @ref{amerge} filter. 4151 4152The filter accepts the following options: 4153 4154@table @option 4155@item level_in 4156Set input gain. Default is 1. Range is between 0.015625 and 64. 4157 4158@item threshold 4159If a signal of second stream raises above this level it will affect the gain 4160reduction of first stream. 4161By default is 0.125. Range is between 0.00097563 and 1. 4162 4163@item ratio 4164Set a ratio about which the signal is reduced. 1:2 means that if the level 4165raised 4dB above the threshold, it will be only 2dB above after the reduction. 4166Default is 2. Range is between 1 and 20. 4167 4168@item attack 4169Amount of milliseconds the signal has to rise above the threshold before gain 4170reduction starts. Default is 20. Range is between 0.01 and 2000. 4171 4172@item release 4173Amount of milliseconds the signal has to fall below the threshold before 4174reduction is decreased again. Default is 250. Range is between 0.01 and 9000. 4175 4176@item makeup 4177Set the amount by how much signal will be amplified after processing. 4178Default is 1. Range is from 1 to 64. 4179 4180@item knee 4181Curve the sharp knee around the threshold to enter gain reduction more softly. 4182Default is 2.82843. Range is between 1 and 8. 4183 4184@item link 4185Choose if the @code{average} level between all channels of side-chain stream 4186or the louder(@code{maximum}) channel of side-chain stream affects the 4187reduction. Default is @code{average}. 4188 4189@item detection 4190Should the exact signal be taken in case of @code{peak} or an RMS one in case 4191of @code{rms}. Default is @code{rms} which is mainly smoother. 4192 4193@item level_sc 4194Set sidechain gain. Default is 1. Range is between 0.015625 and 64. 4195 4196@item mix 4197How much to use compressed signal in output. Default is 1. 4198Range is between 0 and 1. 4199@end table 4200 4201@subsection Examples 4202 4203@itemize 4204@item 4205Full ffmpeg example taking 2 audio inputs, 1st input to be compressed 4206depending on the signal of 2nd input and later compressed signal to be 4207merged with 2nd input: 4208@example 4209ffmpeg -i main.flac -i sidechain.flac -filter_complex "[1:a]asplit=2[sc][mix];[0:a][sc]sidechaincompress[compr];[compr][mix]amerge" 4210@end example 4211@end itemize 4212 4213@section sidechaingate 4214 4215A sidechain gate acts like a normal (wideband) gate but has the ability to 4216filter the detected signal before sending it to the gain reduction stage. 4217Normally a gate uses the full range signal to detect a level above the 4218threshold. 4219For example: If you cut all lower frequencies from your sidechain signal 4220the gate will decrease the volume of your track only if not enough highs 4221appear. With this technique you are able to reduce the resonation of a 4222natural drum or remove "rumbling" of muted strokes from a heavily distorted 4223guitar. 4224It needs two input streams and returns one output stream. 4225First input stream will be processed depending on second stream signal. 4226 4227The filter accepts the following options: 4228 4229@table @option 4230@item level_in 4231Set input level before filtering. 4232Default is 1. Allowed range is from 0.015625 to 64. 4233 4234@item range 4235Set the level of gain reduction when the signal is below the threshold. 4236Default is 0.06125. Allowed range is from 0 to 1. 4237 4238@item threshold 4239If a signal rises above this level the gain reduction is released. 4240Default is 0.125. Allowed range is from 0 to 1. 4241 4242@item ratio 4243Set a ratio about which the signal is reduced. 4244Default is 2. Allowed range is from 1 to 9000. 4245 4246@item attack 4247Amount of milliseconds the signal has to rise above the threshold before gain 4248reduction stops. 4249Default is 20 milliseconds. Allowed range is from 0.01 to 9000. 4250 4251@item release 4252Amount of milliseconds the signal has to fall below the threshold before the 4253reduction is increased again. Default is 250 milliseconds. 4254Allowed range is from 0.01 to 9000. 4255 4256@item makeup 4257Set amount of amplification of signal after processing. 4258Default is 1. Allowed range is from 1 to 64. 4259 4260@item knee 4261Curve the sharp knee around the threshold to enter gain reduction more softly. 4262Default is 2.828427125. Allowed range is from 1 to 8. 4263 4264@item detection 4265Choose if exact signal should be taken for detection or an RMS like one. 4266Default is rms. Can be peak or rms. 4267 4268@item link 4269Choose if the average level between all channels or the louder channel affects 4270the reduction. 4271Default is average. Can be average or maximum. 4272 4273@item level_sc 4274Set sidechain gain. Default is 1. Range is from 0.015625 to 64. 4275@end table 4276 4277@section silencedetect 4278 4279Detect silence in an audio stream. 4280 4281This filter logs a message when it detects that the input audio volume is less 4282or equal to a noise tolerance value for a duration greater or equal to the 4283minimum detected noise duration. 4284 4285The printed times and duration are expressed in seconds. 4286 4287The filter accepts the following options: 4288 4289@table @option 4290@item noise, n 4291Set noise tolerance. Can be specified in dB (in case "dB" is appended to the 4292specified value) or amplitude ratio. Default is -60dB, or 0.001. 4293 4294@item duration, d 4295Set silence duration until notification (default is 2 seconds). 4296 4297@item mono, m 4298Process each channel separately, instead of combined. By default is disabled. 4299@end table 4300 4301@subsection Examples 4302 4303@itemize 4304@item 4305Detect 5 seconds of silence with -50dB noise tolerance: 4306@example 4307silencedetect=n=-50dB:d=5 4308@end example 4309 4310@item 4311Complete example with @command{ffmpeg} to detect silence with 0.0001 noise 4312tolerance in @file{silence.mp3}: 4313@example 4314ffmpeg -i silence.mp3 -af silencedetect=noise=0.0001 -f null - 4315@end example 4316@end itemize 4317 4318@section silenceremove 4319 4320Remove silence from the beginning, middle or end of the audio. 4321 4322The filter accepts the following options: 4323 4324@table @option 4325@item start_periods 4326This value is used to indicate if audio should be trimmed at beginning of 4327the audio. A value of zero indicates no silence should be trimmed from the 4328beginning. When specifying a non-zero value, it trims audio up until it 4329finds non-silence. Normally, when trimming silence from beginning of audio 4330the @var{start_periods} will be @code{1} but it can be increased to higher 4331values to trim all audio up to specific count of non-silence periods. 4332Default value is @code{0}. 4333 4334@item start_duration 4335Specify the amount of time that non-silence must be detected before it stops 4336trimming audio. By increasing the duration, bursts of noises can be treated 4337as silence and trimmed off. Default value is @code{0}. 4338 4339@item start_threshold 4340This indicates what sample value should be treated as silence. For digital 4341audio, a value of @code{0} may be fine but for audio recorded from analog, 4342you may wish to increase the value to account for background noise. 4343Can be specified in dB (in case "dB" is appended to the specified value) 4344or amplitude ratio. Default value is @code{0}. 4345 4346@item start_silence 4347Specify max duration of silence at beginning that will be kept after 4348trimming. Default is 0, which is equal to trimming all samples detected 4349as silence. 4350 4351@item start_mode 4352Specify mode of detection of silence end in start of multi-channel audio. 4353Can be @var{any} or @var{all}. Default is @var{any}. 4354With @var{any}, any sample that is detected as non-silence will cause 4355stopped trimming of silence. 4356With @var{all}, only if all channels are detected as non-silence will cause 4357stopped trimming of silence. 4358 4359@item stop_periods 4360Set the count for trimming silence from the end of audio. 4361To remove silence from the middle of a file, specify a @var{stop_periods} 4362that is negative. This value is then treated as a positive value and is 4363used to indicate the effect should restart processing as specified by 4364@var{start_periods}, making it suitable for removing periods of silence 4365in the middle of the audio. 4366Default value is @code{0}. 4367 4368@item stop_duration 4369Specify a duration of silence that must exist before audio is not copied any 4370more. By specifying a higher duration, silence that is wanted can be left in 4371the audio. 4372Default value is @code{0}. 4373 4374@item stop_threshold 4375This is the same as @option{start_threshold} but for trimming silence from 4376the end of audio. 4377Can be specified in dB (in case "dB" is appended to the specified value) 4378or amplitude ratio. Default value is @code{0}. 4379 4380@item stop_silence 4381Specify max duration of silence at end that will be kept after 4382trimming. Default is 0, which is equal to trimming all samples detected 4383as silence. 4384 4385@item stop_mode 4386Specify mode of detection of silence start in end of multi-channel audio. 4387Can be @var{any} or @var{all}. Default is @var{any}. 4388With @var{any}, any sample that is detected as non-silence will cause 4389stopped trimming of silence. 4390With @var{all}, only if all channels are detected as non-silence will cause 4391stopped trimming of silence. 4392 4393@item detection 4394Set how is silence detected. Can be @code{rms} or @code{peak}. Second is faster 4395and works better with digital silence which is exactly 0. 4396Default value is @code{rms}. 4397 4398@item window 4399Set duration in number of seconds used to calculate size of window in number 4400of samples for detecting silence. 4401Default value is @code{0.02}. Allowed range is from @code{0} to @code{10}. 4402@end table 4403 4404@subsection Examples 4405 4406@itemize 4407@item 4408The following example shows how this filter can be used to start a recording 4409that does not contain the delay at the start which usually occurs between 4410pressing the record button and the start of the performance: 4411@example 4412silenceremove=start_periods=1:start_duration=5:start_threshold=0.02 4413@end example 4414 4415@item 4416Trim all silence encountered from beginning to end where there is more than 1 4417second of silence in audio: 4418@example 4419silenceremove=stop_periods=-1:stop_duration=1:stop_threshold=-90dB 4420@end example 4421@end itemize 4422 4423@section sofalizer 4424 4425SOFAlizer uses head-related transfer functions (HRTFs) to create virtual 4426loudspeakers around the user for binaural listening via headphones (audio 4427formats up to 9 channels supported). 4428The HRTFs are stored in SOFA files (see @url{http://www.sofacoustics.org/} for a database). 4429SOFAlizer is developed at the Acoustics Research Institute (ARI) of the 4430Austrian Academy of Sciences. 4431 4432To enable compilation of this filter you need to configure FFmpeg with 4433@code{--enable-libmysofa}. 4434 4435The filter accepts the following options: 4436 4437@table @option 4438@item sofa 4439Set the SOFA file used for rendering. 4440 4441@item gain 4442Set gain applied to audio. Value is in dB. Default is 0. 4443 4444@item rotation 4445Set rotation of virtual loudspeakers in deg. Default is 0. 4446 4447@item elevation 4448Set elevation of virtual speakers in deg. Default is 0. 4449 4450@item radius 4451Set distance in meters between loudspeakers and the listener with near-field 4452HRTFs. Default is 1. 4453 4454@item type 4455Set processing type. Can be @var{time} or @var{freq}. @var{time} is 4456processing audio in time domain which is slow. 4457@var{freq} is processing audio in frequency domain which is fast. 4458Default is @var{freq}. 4459 4460@item speakers 4461Set custom positions of virtual loudspeakers. Syntax for this option is: 4462<CH> <AZIM> <ELEV>[|<CH> <AZIM> <ELEV>|...]. 4463Each virtual loudspeaker is described with short channel name following with 4464azimuth and elevation in degrees. 4465Each virtual loudspeaker description is separated by '|'. 4466For example to override front left and front right channel positions use: 4467'speakers=FL 45 15|FR 345 15'. 4468Descriptions with unrecognised channel names are ignored. 4469 4470@item lfegain 4471Set custom gain for LFE channels. Value is in dB. Default is 0. 4472@end table 4473 4474@subsection Examples 4475 4476@itemize 4477@item 4478Using ClubFritz6 sofa file: 4479@example 4480sofalizer=sofa=/path/to/ClubFritz6.sofa:type=freq:radius=1 4481@end example 4482 4483@item 4484Using ClubFritz12 sofa file and bigger radius with small rotation: 4485@example 4486sofalizer=sofa=/path/to/ClubFritz12.sofa:type=freq:radius=2:rotation=5 4487@end example 4488 4489@item 4490Similar as above but with custom speaker positions for front left, front right, back left and back right 4491and also with custom gain: 4492@example 4493"sofalizer=sofa=/path/to/ClubFritz6.sofa:type=freq:radius=2:speakers=FL 45|FR 315|BL 135|BR 225:gain=28" 4494@end example 4495@end itemize 4496 4497@section stereotools 4498 4499This filter has some handy utilities to manage stereo signals, for converting 4500M/S stereo recordings to L/R signal while having control over the parameters 4501or spreading the stereo image of master track. 4502 4503The filter accepts the following options: 4504 4505@table @option 4506@item level_in 4507Set input level before filtering for both channels. Defaults is 1. 4508Allowed range is from 0.015625 to 64. 4509 4510@item level_out 4511Set output level after filtering for both channels. Defaults is 1. 4512Allowed range is from 0.015625 to 64. 4513 4514@item balance_in 4515Set input balance between both channels. Default is 0. 4516Allowed range is from -1 to 1. 4517 4518@item balance_out 4519Set output balance between both channels. Default is 0. 4520Allowed range is from -1 to 1. 4521 4522@item softclip 4523Enable softclipping. Results in analog distortion instead of harsh digital 0dB 4524clipping. Disabled by default. 4525 4526@item mutel 4527Mute the left channel. Disabled by default. 4528 4529@item muter 4530Mute the right channel. Disabled by default. 4531 4532@item phasel 4533Change the phase of the left channel. Disabled by default. 4534 4535@item phaser 4536Change the phase of the right channel. Disabled by default. 4537 4538@item mode 4539Set stereo mode. Available values are: 4540 4541@table @samp 4542@item lr>lr 4543Left/Right to Left/Right, this is default. 4544 4545@item lr>ms 4546Left/Right to Mid/Side. 4547 4548@item ms>lr 4549Mid/Side to Left/Right. 4550 4551@item lr>ll 4552Left/Right to Left/Left. 4553 4554@item lr>rr 4555Left/Right to Right/Right. 4556 4557@item lr>l+r 4558Left/Right to Left + Right. 4559 4560@item lr>rl 4561Left/Right to Right/Left. 4562 4563@item ms>ll 4564Mid/Side to Left/Left. 4565 4566@item ms>rr 4567Mid/Side to Right/Right. 4568@end table 4569 4570@item slev 4571Set level of side signal. Default is 1. 4572Allowed range is from 0.015625 to 64. 4573 4574@item sbal 4575Set balance of side signal. Default is 0. 4576Allowed range is from -1 to 1. 4577 4578@item mlev 4579Set level of the middle signal. Default is 1. 4580Allowed range is from 0.015625 to 64. 4581 4582@item mpan 4583Set middle signal pan. Default is 0. Allowed range is from -1 to 1. 4584 4585@item base 4586Set stereo base between mono and inversed channels. Default is 0. 4587Allowed range is from -1 to 1. 4588 4589@item delay 4590Set delay in milliseconds how much to delay left from right channel and 4591vice versa. Default is 0. Allowed range is from -20 to 20. 4592 4593@item sclevel 4594Set S/C level. Default is 1. Allowed range is from 1 to 100. 4595 4596@item phase 4597Set the stereo phase in degrees. Default is 0. Allowed range is from 0 to 360. 4598 4599@item bmode_in, bmode_out 4600Set balance mode for balance_in/balance_out option. 4601 4602Can be one of the following: 4603 4604@table @samp 4605@item balance 4606Classic balance mode. Attenuate one channel at time. 4607Gain is raised up to 1. 4608 4609@item amplitude 4610Similar as classic mode above but gain is raised up to 2. 4611 4612@item power 4613Equal power distribution, from -6dB to +6dB range. 4614@end table 4615@end table 4616 4617@subsection Examples 4618 4619@itemize 4620@item 4621Apply karaoke like effect: 4622@example 4623stereotools=mlev=0.015625 4624@end example 4625 4626@item 4627Convert M/S signal to L/R: 4628@example 4629"stereotools=mode=ms>lr" 4630@end example 4631@end itemize 4632 4633@section stereowiden 4634 4635This filter enhance the stereo effect by suppressing signal common to both 4636channels and by delaying the signal of left into right and vice versa, 4637thereby widening the stereo effect. 4638 4639The filter accepts the following options: 4640 4641@table @option 4642@item delay 4643Time in milliseconds of the delay of left signal into right and vice versa. 4644Default is 20 milliseconds. 4645 4646@item feedback 4647Amount of gain in delayed signal into right and vice versa. Gives a delay 4648effect of left signal in right output and vice versa which gives widening 4649effect. Default is 0.3. 4650 4651@item crossfeed 4652Cross feed of left into right with inverted phase. This helps in suppressing 4653the mono. If the value is 1 it will cancel all the signal common to both 4654channels. Default is 0.3. 4655 4656@item drymix 4657Set level of input signal of original channel. Default is 0.8. 4658@end table 4659 4660@section superequalizer 4661Apply 18 band equalizer. 4662 4663The filter accepts the following options: 4664@table @option 4665@item 1b 4666Set 65Hz band gain. 4667@item 2b 4668Set 92Hz band gain. 4669@item 3b 4670Set 131Hz band gain. 4671@item 4b 4672Set 185Hz band gain. 4673@item 5b 4674Set 262Hz band gain. 4675@item 6b 4676Set 370Hz band gain. 4677@item 7b 4678Set 523Hz band gain. 4679@item 8b 4680Set 740Hz band gain. 4681@item 9b 4682Set 1047Hz band gain. 4683@item 10b 4684Set 1480Hz band gain. 4685@item 11b 4686Set 2093Hz band gain. 4687@item 12b 4688Set 2960Hz band gain. 4689@item 13b 4690Set 4186Hz band gain. 4691@item 14b 4692Set 5920Hz band gain. 4693@item 15b 4694Set 8372Hz band gain. 4695@item 16b 4696Set 11840Hz band gain. 4697@item 17b 4698Set 16744Hz band gain. 4699@item 18b 4700Set 20000Hz band gain. 4701@end table 4702 4703@section surround 4704Apply audio surround upmix filter. 4705 4706This filter allows to produce multichannel output from audio stream. 4707 4708The filter accepts the following options: 4709 4710@table @option 4711@item chl_out 4712Set output channel layout. By default, this is @var{5.1}. 4713 4714See @ref{channel layout syntax,,the Channel Layout section in the ffmpeg-utils(1) manual,ffmpeg-utils} 4715for the required syntax. 4716 4717@item chl_in 4718Set input channel layout. By default, this is @var{stereo}. 4719 4720See @ref{channel layout syntax,,the Channel Layout section in the ffmpeg-utils(1) manual,ffmpeg-utils} 4721for the required syntax. 4722 4723@item level_in 4724Set input volume level. By default, this is @var{1}. 4725 4726@item level_out 4727Set output volume level. By default, this is @var{1}. 4728 4729@item lfe 4730Enable LFE channel output if output channel layout has it. By default, this is enabled. 4731 4732@item lfe_low 4733Set LFE low cut off frequency. By default, this is @var{128} Hz. 4734 4735@item lfe_high 4736Set LFE high cut off frequency. By default, this is @var{256} Hz. 4737 4738@item fc_in 4739Set front center input volume. By default, this is @var{1}. 4740 4741@item fc_out 4742Set front center output volume. By default, this is @var{1}. 4743 4744@item lfe_in 4745Set LFE input volume. By default, this is @var{1}. 4746 4747@item lfe_out 4748Set LFE output volume. By default, this is @var{1}. 4749@end table 4750 4751@section treble, highshelf 4752 4753Boost or cut treble (upper) frequencies of the audio using a two-pole 4754shelving filter with a response similar to that of a standard 4755hi-fi's tone-controls. This is also known as shelving equalisation (EQ). 4756 4757The filter accepts the following options: 4758 4759@table @option 4760@item gain, g 4761Give the gain at whichever is the lower of ~22 kHz and the 4762Nyquist frequency. Its useful range is about -20 (for a large cut) 4763to +20 (for a large boost). Beware of clipping when using a positive gain. 4764 4765@item frequency, f 4766Set the filter's central frequency and so can be used 4767to extend or reduce the frequency range to be boosted or cut. 4768The default value is @code{3000} Hz. 4769 4770@item width_type, t 4771Set method to specify band-width of filter. 4772@table @option 4773@item h 4774Hz 4775@item q 4776Q-Factor 4777@item o 4778octave 4779@item s 4780slope 4781@item k 4782kHz 4783@end table 4784 4785@item width, w 4786Determine how steep is the filter's shelf transition. 4787 4788@item channels, c 4789Specify which channels to filter, by default all available are filtered. 4790@end table 4791 4792@subsection Commands 4793 4794This filter supports the following commands: 4795@table @option 4796@item frequency, f 4797Change treble frequency. 4798Syntax for the command is : "@var{frequency}" 4799 4800@item width_type, t 4801Change treble width_type. 4802Syntax for the command is : "@var{width_type}" 4803 4804@item width, w 4805Change treble width. 4806Syntax for the command is : "@var{width}" 4807 4808@item gain, g 4809Change treble gain. 4810Syntax for the command is : "@var{gain}" 4811@end table 4812 4813@section tremolo 4814 4815Sinusoidal amplitude modulation. 4816 4817The filter accepts the following options: 4818 4819@table @option 4820@item f 4821Modulation frequency in Hertz. Modulation frequencies in the subharmonic range 4822(20 Hz or lower) will result in a tremolo effect. 4823This filter may also be used as a ring modulator by specifying 4824a modulation frequency higher than 20 Hz. 4825Range is 0.1 - 20000.0. Default value is 5.0 Hz. 4826 4827@item d 4828Depth of modulation as a percentage. Range is 0.0 - 1.0. 4829Default value is 0.5. 4830@end table 4831 4832@section vibrato 4833 4834Sinusoidal phase modulation. 4835 4836The filter accepts the following options: 4837 4838@table @option 4839@item f 4840Modulation frequency in Hertz. 4841Range is 0.1 - 20000.0. Default value is 5.0 Hz. 4842 4843@item d 4844Depth of modulation as a percentage. Range is 0.0 - 1.0. 4845Default value is 0.5. 4846@end table 4847 4848@section volume 4849 4850Adjust the input audio volume. 4851 4852It accepts the following parameters: 4853@table @option 4854 4855@item volume 4856Set audio volume expression. 4857 4858Output values are clipped to the maximum value. 4859 4860The output audio volume is given by the relation: 4861@example 4862@var{output_volume} = @var{volume} * @var{input_volume} 4863@end example 4864 4865The default value for @var{volume} is "1.0". 4866 4867@item precision 4868This parameter represents the mathematical precision. 4869 4870It determines which input sample formats will be allowed, which affects the 4871precision of the volume scaling. 4872 4873@table @option 4874@item fixed 48758-bit fixed-point; this limits input sample format to U8, S16, and S32. 4876@item float 487732-bit floating-point; this limits input sample format to FLT. (default) 4878@item double 487964-bit floating-point; this limits input sample format to DBL. 4880@end table 4881 4882@item replaygain 4883Choose the behaviour on encountering ReplayGain side data in input frames. 4884 4885@table @option 4886@item drop 4887Remove ReplayGain side data, ignoring its contents (the default). 4888 4889@item ignore 4890Ignore ReplayGain side data, but leave it in the frame. 4891 4892@item track 4893Prefer the track gain, if present. 4894 4895@item album 4896Prefer the album gain, if present. 4897@end table 4898 4899@item replaygain_preamp 4900Pre-amplification gain in dB to apply to the selected replaygain gain. 4901 4902Default value for @var{replaygain_preamp} is 0.0. 4903 4904@item eval 4905Set when the volume expression is evaluated. 4906 4907It accepts the following values: 4908@table @samp 4909@item once 4910only evaluate expression once during the filter initialization, or 4911when the @samp{volume} command is sent 4912 4913@item frame 4914evaluate expression for each incoming frame 4915@end table 4916 4917Default value is @samp{once}. 4918@end table 4919 4920The volume expression can contain the following parameters. 4921 4922@table @option 4923@item n 4924frame number (starting at zero) 4925@item nb_channels 4926number of channels 4927@item nb_consumed_samples 4928number of samples consumed by the filter 4929@item nb_samples 4930number of samples in the current frame 4931@item pos 4932original frame position in the file 4933@item pts 4934frame PTS 4935@item sample_rate 4936sample rate 4937@item startpts 4938PTS at start of stream 4939@item startt 4940time at start of stream 4941@item t 4942frame time 4943@item tb 4944timestamp timebase 4945@item volume 4946last set volume value 4947@end table 4948 4949Note that when @option{eval} is set to @samp{once} only the 4950@var{sample_rate} and @var{tb} variables are available, all other 4951variables will evaluate to NAN. 4952 4953@subsection Commands 4954 4955This filter supports the following commands: 4956@table @option 4957@item volume 4958Modify the volume expression. 4959The command accepts the same syntax of the corresponding option. 4960 4961If the specified expression is not valid, it is kept at its current 4962value. 4963@item replaygain_noclip 4964Prevent clipping by limiting the gain applied. 4965 4966Default value for @var{replaygain_noclip} is 1. 4967 4968@end table 4969 4970@subsection Examples 4971 4972@itemize 4973@item 4974Halve the input audio volume: 4975@example 4976volume=volume=0.5 4977volume=volume=1/2 4978volume=volume=-6.0206dB 4979@end example 4980 4981In all the above example the named key for @option{volume} can be 4982omitted, for example like in: 4983@example 4984volume=0.5 4985@end example 4986 4987@item 4988Increase input audio power by 6 decibels using fixed-point precision: 4989@example 4990volume=volume=6dB:precision=fixed 4991@end example 4992 4993@item 4994Fade volume after time 10 with an annihilation period of 5 seconds: 4995@example 4996volume='if(lt(t,10),1,max(1-(t-10)/5,0))':eval=frame 4997@end example 4998@end itemize 4999 5000@section volumedetect 5001 5002Detect the volume of the input video. 5003 5004The filter has no parameters. The input is not modified. Statistics about 5005the volume will be printed in the log when the input stream end is reached. 5006 5007In particular it will show the mean volume (root mean square), maximum 5008volume (on a per-sample basis), and the beginning of a histogram of the 5009registered volume values (from the maximum value to a cumulated 1/1000 of 5010the samples). 5011 5012All volumes are in decibels relative to the maximum PCM value. 5013 5014@subsection Examples 5015 5016Here is an excerpt of the output: 5017@example 5018[Parsed_volumedetect_0 @ 0xa23120] mean_volume: -27 dB 5019[Parsed_volumedetect_0 @ 0xa23120] max_volume: -4 dB 5020[Parsed_volumedetect_0 @ 0xa23120] histogram_4db: 6 5021[Parsed_volumedetect_0 @ 0xa23120] histogram_5db: 62 5022[Parsed_volumedetect_0 @ 0xa23120] histogram_6db: 286 5023[Parsed_volumedetect_0 @ 0xa23120] histogram_7db: 1042 5024[Parsed_volumedetect_0 @ 0xa23120] histogram_8db: 2551 5025[Parsed_volumedetect_0 @ 0xa23120] histogram_9db: 4609 5026[Parsed_volumedetect_0 @ 0xa23120] histogram_10db: 8409 5027@end example 5028 5029It means that: 5030@itemize 5031@item 5032The mean square energy is approximately -27 dB, or 10^-2.7. 5033@item 5034The largest sample is at -4 dB, or more precisely between -4 dB and -5 dB. 5035@item 5036There are 6 samples at -4 dB, 62 at -5 dB, 286 at -6 dB, etc. 5037@end itemize 5038 5039In other words, raising the volume by +4 dB does not cause any clipping, 5040raising it by +5 dB causes clipping for 6 samples, etc. 5041 5042@c man end AUDIO FILTERS 5043 5044@chapter Audio Sources 5045@c man begin AUDIO SOURCES 5046 5047Below is a description of the currently available audio sources. 5048 5049@section abuffer 5050 5051Buffer audio frames, and make them available to the filter chain. 5052 5053This source is mainly intended for a programmatic use, in particular 5054through the interface defined in @file{libavfilter/asrc_abuffer.h}. 5055 5056It accepts the following parameters: 5057@table @option 5058 5059@item time_base 5060The timebase which will be used for timestamps of submitted frames. It must be 5061either a floating-point number or in @var{numerator}/@var{denominator} form. 5062 5063@item sample_rate 5064The sample rate of the incoming audio buffers. 5065 5066@item sample_fmt 5067The sample format of the incoming audio buffers. 5068Either a sample format name or its corresponding integer representation from 5069the enum AVSampleFormat in @file{libavutil/samplefmt.h} 5070 5071@item channel_layout 5072The channel layout of the incoming audio buffers. 5073Either a channel layout name from channel_layout_map in 5074@file{libavutil/channel_layout.c} or its corresponding integer representation 5075from the AV_CH_LAYOUT_* macros in @file{libavutil/channel_layout.h} 5076 5077@item channels 5078The number of channels of the incoming audio buffers. 5079If both @var{channels} and @var{channel_layout} are specified, then they 5080must be consistent. 5081 5082@end table 5083 5084@subsection Examples 5085 5086@example 5087abuffer=sample_rate=44100:sample_fmt=s16p:channel_layout=stereo 5088@end example 5089 5090will instruct the source to accept planar 16bit signed stereo at 44100Hz. 5091Since the sample format with name "s16p" corresponds to the number 50926 and the "stereo" channel layout corresponds to the value 0x3, this is 5093equivalent to: 5094@example 5095abuffer=sample_rate=44100:sample_fmt=6:channel_layout=0x3 5096@end example 5097 5098@section aevalsrc 5099 5100Generate an audio signal specified by an expression. 5101 5102This source accepts in input one or more expressions (one for each 5103channel), which are evaluated and used to generate a corresponding 5104audio signal. 5105 5106This source accepts the following options: 5107 5108@table @option 5109@item exprs 5110Set the '|'-separated expressions list for each separate channel. In case the 5111@option{channel_layout} option is not specified, the selected channel layout 5112depends on the number of provided expressions. Otherwise the last 5113specified expression is applied to the remaining output channels. 5114 5115@item channel_layout, c 5116Set the channel layout. The number of channels in the specified layout 5117must be equal to the number of specified expressions. 5118 5119@item duration, d 5120Set the minimum duration of the sourced audio. See 5121@ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils} 5122for the accepted syntax. 5123Note that the resulting duration may be greater than the specified 5124duration, as the generated audio is always cut at the end of a 5125complete frame. 5126 5127If not specified, or the expressed duration is negative, the audio is 5128supposed to be generated forever. 5129 5130@item nb_samples, n 5131Set the number of samples per channel per each output frame, 5132default to 1024. 5133 5134@item sample_rate, s 5135Specify the sample rate, default to 44100. 5136@end table 5137 5138Each expression in @var{exprs} can contain the following constants: 5139 5140@table @option 5141@item n 5142number of the evaluated sample, starting from 0 5143 5144@item t 5145time of the evaluated sample expressed in seconds, starting from 0 5146 5147@item s 5148sample rate 5149 5150@end table 5151 5152@subsection Examples 5153 5154@itemize 5155@item 5156Generate silence: 5157@example 5158aevalsrc=0 5159@end example 5160 5161@item 5162Generate a sin signal with frequency of 440 Hz, set sample rate to 51638000 Hz: 5164@example 5165aevalsrc="sin(440*2*PI*t):s=8000" 5166@end example 5167 5168@item 5169Generate a two channels signal, specify the channel layout (Front 5170Center + Back Center) explicitly: 5171@example 5172aevalsrc="sin(420*2*PI*t)|cos(430*2*PI*t):c=FC|BC" 5173@end example 5174 5175@item 5176Generate white noise: 5177@example 5178aevalsrc="-2+random(0)" 5179@end example 5180 5181@item 5182Generate an amplitude modulated signal: 5183@example 5184aevalsrc="sin(10*2*PI*t)*sin(880*2*PI*t)" 5185@end example 5186 5187@item 5188Generate 2.5 Hz binaural beats on a 360 Hz carrier: 5189@example 5190aevalsrc="0.1*sin(2*PI*(360-2.5/2)*t) | 0.1*sin(2*PI*(360+2.5/2)*t)" 5191@end example 5192 5193@end itemize 5194 5195@section anullsrc 5196 5197The null audio source, return unprocessed audio frames. It is mainly useful 5198as a template and to be employed in analysis / debugging tools, or as 5199the source for filters which ignore the input data (for example the sox 5200synth filter). 5201 5202This source accepts the following options: 5203 5204@table @option 5205 5206@item channel_layout, cl 5207 5208Specifies the channel layout, and can be either an integer or a string 5209representing a channel layout. The default value of @var{channel_layout} 5210is "stereo". 5211 5212Check the channel_layout_map definition in 5213@file{libavutil/channel_layout.c} for the mapping between strings and 5214channel layout values. 5215 5216@item sample_rate, r 5217Specifies the sample rate, and defaults to 44100. 5218 5219@item nb_samples, n 5220Set the number of samples per requested frames. 5221 5222@end table 5223 5224@subsection Examples 5225 5226@itemize 5227@item 5228Set the sample rate to 48000 Hz and the channel layout to AV_CH_LAYOUT_MONO. 5229@example 5230anullsrc=r=48000:cl=4 5231@end example 5232 5233@item 5234Do the same operation with a more obvious syntax: 5235@example 5236anullsrc=r=48000:cl=mono 5237@end example 5238@end itemize 5239 5240All the parameters need to be explicitly defined. 5241 5242@section flite 5243 5244Synthesize a voice utterance using the libflite library. 5245 5246To enable compilation of this filter you need to configure FFmpeg with 5247@code{--enable-libflite}. 5248 5249Note that versions of the flite library prior to 2.0 are not thread-safe. 5250 5251The filter accepts the following options: 5252 5253@table @option 5254 5255@item list_voices 5256If set to 1, list the names of the available voices and exit 5257immediately. Default value is 0. 5258 5259@item nb_samples, n 5260Set the maximum number of samples per frame. Default value is 512. 5261 5262@item textfile 5263Set the filename containing the text to speak. 5264 5265@item text 5266Set the text to speak. 5267 5268@item voice, v 5269Set the voice to use for the speech synthesis. Default value is 5270@code{kal}. See also the @var{list_voices} option. 5271@end table 5272 5273@subsection Examples 5274 5275@itemize 5276@item 5277Read from file @file{speech.txt}, and synthesize the text using the 5278standard flite voice: 5279@example 5280flite=textfile=speech.txt 5281@end example 5282 5283@item 5284Read the specified text selecting the @code{slt} voice: 5285@example 5286flite=text='So fare thee well, poor devil of a Sub-Sub, whose commentator I am':voice=slt 5287@end example 5288 5289@item 5290Input text to ffmpeg: 5291@example 5292ffmpeg -f lavfi -i flite=text='So fare thee well, poor devil of a Sub-Sub, whose commentator I am':voice=slt 5293@end example 5294 5295@item 5296Make @file{ffplay} speak the specified text, using @code{flite} and 5297the @code{lavfi} device: 5298@example 5299ffplay -f lavfi flite=text='No more be grieved for which that thou hast done.' 5300@end example 5301@end itemize 5302 5303For more information about libflite, check: 5304@url{http://www.festvox.org/flite/} 5305 5306@section anoisesrc 5307 5308Generate a noise audio signal. 5309 5310The filter accepts the following options: 5311 5312@table @option 5313@item sample_rate, r 5314Specify the sample rate. Default value is 48000 Hz. 5315 5316@item amplitude, a 5317Specify the amplitude (0.0 - 1.0) of the generated audio stream. Default value 5318is 1.0. 5319 5320@item duration, d 5321Specify the duration of the generated audio stream. Not specifying this option 5322results in noise with an infinite length. 5323 5324@item color, colour, c 5325Specify the color of noise. Available noise colors are white, pink, brown, 5326blue and violet. Default color is white. 5327 5328@item seed, s 5329Specify a value used to seed the PRNG. 5330 5331@item nb_samples, n 5332Set the number of samples per each output frame, default is 1024. 5333@end table 5334 5335@subsection Examples 5336 5337@itemize 5338 5339@item 5340Generate 60 seconds of pink noise, with a 44.1 kHz sampling rate and an amplitude of 0.5: 5341@example 5342anoisesrc=d=60:c=pink:r=44100:a=0.5 5343@end example 5344@end itemize 5345 5346@section hilbert 5347 5348Generate odd-tap Hilbert transform FIR coefficients. 5349 5350The resulting stream can be used with @ref{afir} filter for phase-shifting 5351the signal by 90 degrees. 5352 5353This is used in many matrix coding schemes and for analytic signal generation. 5354The process is often written as a multiplication by i (or j), the imaginary unit. 5355 5356The filter accepts the following options: 5357 5358@table @option 5359 5360@item sample_rate, s 5361Set sample rate, default is 44100. 5362 5363@item taps, t 5364Set length of FIR filter, default is 22051. 5365 5366@item nb_samples, n 5367Set number of samples per each frame. 5368 5369@item win_func, w 5370Set window function to be used when generating FIR coefficients. 5371@end table 5372 5373@section sinc 5374 5375Generate a sinc kaiser-windowed low-pass, high-pass, band-pass, or band-reject FIR coefficients. 5376 5377The resulting stream can be used with @ref{afir} filter for filtering the audio signal. 5378 5379The filter accepts the following options: 5380 5381@table @option 5382@item sample_rate, r 5383Set sample rate, default is 44100. 5384 5385@item nb_samples, n 5386Set number of samples per each frame. Default is 1024. 5387 5388@item hp 5389Set high-pass frequency. Default is 0. 5390 5391@item lp 5392Set low-pass frequency. Default is 0. 5393If high-pass frequency is lower than low-pass frequency and low-pass frequency 5394is higher than 0 then filter will create band-pass filter coefficients, 5395otherwise band-reject filter coefficients. 5396 5397@item phase 5398Set filter phase response. Default is 50. Allowed range is from 0 to 100. 5399 5400@item beta 5401Set Kaiser window beta. 5402 5403@item att 5404Set stop-band attenuation. Default is 120dB, allowed range is from 40 to 180 dB. 5405 5406@item round 5407Enable rounding, by default is disabled. 5408 5409@item hptaps 5410Set number of taps for high-pass filter. 5411 5412@item lptaps 5413Set number of taps for low-pass filter. 5414@end table 5415 5416@section sine 5417 5418Generate an audio signal made of a sine wave with amplitude 1/8. 5419 5420The audio signal is bit-exact. 5421 5422The filter accepts the following options: 5423 5424@table @option 5425 5426@item frequency, f 5427Set the carrier frequency. Default is 440 Hz. 5428 5429@item beep_factor, b 5430Enable a periodic beep every second with frequency @var{beep_factor} times 5431the carrier frequency. Default is 0, meaning the beep is disabled. 5432 5433@item sample_rate, r 5434Specify the sample rate, default is 44100. 5435 5436@item duration, d 5437Specify the duration of the generated audio stream. 5438 5439@item samples_per_frame 5440Set the number of samples per output frame. 5441 5442The expression can contain the following constants: 5443 5444@table @option 5445@item n 5446The (sequential) number of the output audio frame, starting from 0. 5447 5448@item pts 5449The PTS (Presentation TimeStamp) of the output audio frame, 5450expressed in @var{TB} units. 5451 5452@item t 5453The PTS of the output audio frame, expressed in seconds. 5454 5455@item TB 5456The timebase of the output audio frames. 5457@end table 5458 5459Default is @code{1024}. 5460@end table 5461 5462@subsection Examples 5463 5464@itemize 5465 5466@item 5467Generate a simple 440 Hz sine wave: 5468@example 5469sine 5470@end example 5471 5472@item 5473Generate a 220 Hz sine wave with a 880 Hz beep each second, for 5 seconds: 5474@example 5475sine=220:4:d=5 5476sine=f=220:b=4:d=5 5477sine=frequency=220:beep_factor=4:duration=5 5478@end example 5479 5480@item 5481Generate a 1 kHz sine wave following @code{1602,1601,1602,1601,1602} NTSC 5482pattern: 5483@example 5484sine=1000:samples_per_frame='st(0,mod(n,5)); 1602-not(not(eq(ld(0),1)+eq(ld(0),3)))' 5485@end example 5486@end itemize 5487 5488@c man end AUDIO SOURCES 5489 5490@chapter Audio Sinks 5491@c man begin AUDIO SINKS 5492 5493Below is a description of the currently available audio sinks. 5494 5495@section abuffersink 5496 5497Buffer audio frames, and make them available to the end of filter chain. 5498 5499This sink is mainly intended for programmatic use, in particular 5500through the interface defined in @file{libavfilter/buffersink.h} 5501or the options system. 5502 5503It accepts a pointer to an AVABufferSinkContext structure, which 5504defines the incoming buffers' formats, to be passed as the opaque 5505parameter to @code{avfilter_init_filter} for initialization. 5506@section anullsink 5507 5508Null audio sink; do absolutely nothing with the input audio. It is 5509mainly useful as a template and for use in analysis / debugging 5510tools. 5511 5512@c man end AUDIO SINKS 5513 5514@chapter Video Filters 5515@c man begin VIDEO FILTERS 5516 5517When you configure your FFmpeg build, you can disable any of the 5518existing filters using @code{--disable-filters}. 5519The configure output will show the video filters included in your 5520build. 5521 5522Below is a description of the currently available video filters. 5523 5524@section alphaextract 5525 5526Extract the alpha component from the input as a grayscale video. This 5527is especially useful with the @var{alphamerge} filter. 5528 5529@section alphamerge 5530 5531Add or replace the alpha component of the primary input with the 5532grayscale value of a second input. This is intended for use with 5533@var{alphaextract} to allow the transmission or storage of frame 5534sequences that have alpha in a format that doesn't support an alpha 5535channel. 5536 5537For example, to reconstruct full frames from a normal YUV-encoded video 5538and a separate video created with @var{alphaextract}, you might use: 5539@example 5540movie=in_alpha.mkv [alpha]; [in][alpha] alphamerge [out] 5541@end example 5542 5543Since this filter is designed for reconstruction, it operates on frame 5544sequences without considering timestamps, and terminates when either 5545input reaches end of stream. This will cause problems if your encoding 5546pipeline drops frames. If you're trying to apply an image as an 5547overlay to a video stream, consider the @var{overlay} filter instead. 5548 5549@section amplify 5550 5551Amplify differences between current pixel and pixels of adjacent frames in 5552same pixel location. 5553 5554This filter accepts the following options: 5555 5556@table @option 5557@item radius 5558Set frame radius. Default is 2. Allowed range is from 1 to 63. 5559For example radius of 3 will instruct filter to calculate average of 7 frames. 5560 5561@item factor 5562Set factor to amplify difference. Default is 2. Allowed range is from 0 to 65535. 5563 5564@item threshold 5565Set threshold for difference amplification. Any differrence greater or equal to 5566this value will not alter source pixel. Default is 10. 5567Allowed range is from 0 to 65535. 5568 5569@item low 5570Set lower limit for changing source pixel. Default is 65535. Allowed range is from 0 to 65535. 5571This option controls maximum possible value that will decrease source pixel value. 5572 5573@item high 5574Set high limit for changing source pixel. Default is 65535. Allowed range is from 0 to 65535. 5575This option controls maximum possible value that will increase source pixel value. 5576 5577@item planes 5578Set which planes to filter. Default is all. Allowed range is from 0 to 15. 5579@end table 5580 5581@section ass 5582 5583Same as the @ref{subtitles} filter, except that it doesn't require libavcodec 5584and libavformat to work. On the other hand, it is limited to ASS (Advanced 5585Substation Alpha) subtitles files. 5586 5587This filter accepts the following option in addition to the common options from 5588the @ref{subtitles} filter: 5589 5590@table @option 5591@item shaping 5592Set the shaping engine 5593 5594Available values are: 5595@table @samp 5596@item auto 5597The default libass shaping engine, which is the best available. 5598@item simple 5599Fast, font-agnostic shaper that can do only substitutions 5600@item complex 5601Slower shaper using OpenType for substitutions and positioning 5602@end table 5603 5604The default is @code{auto}. 5605@end table 5606 5607@section atadenoise 5608Apply an Adaptive Temporal Averaging Denoiser to the video input. 5609 5610The filter accepts the following options: 5611 5612@table @option 5613@item 0a 5614Set threshold A for 1st plane. Default is 0.02. 5615Valid range is 0 to 0.3. 5616 5617@item 0b 5618Set threshold B for 1st plane. Default is 0.04. 5619Valid range is 0 to 5. 5620 5621@item 1a 5622Set threshold A for 2nd plane. Default is 0.02. 5623Valid range is 0 to 0.3. 5624 5625@item 1b 5626Set threshold B for 2nd plane. Default is 0.04. 5627Valid range is 0 to 5. 5628 5629@item 2a 5630Set threshold A for 3rd plane. Default is 0.02. 5631Valid range is 0 to 0.3. 5632 5633@item 2b 5634Set threshold B for 3rd plane. Default is 0.04. 5635Valid range is 0 to 5. 5636 5637Threshold A is designed to react on abrupt changes in the input signal and 5638threshold B is designed to react on continuous changes in the input signal. 5639 5640@item s 5641Set number of frames filter will use for averaging. Default is 9. Must be odd 5642number in range [5, 129]. 5643 5644@item p 5645Set what planes of frame filter will use for averaging. Default is all. 5646@end table 5647 5648@section avgblur 5649 5650Apply average blur filter. 5651 5652The filter accepts the following options: 5653 5654@table @option 5655@item sizeX 5656Set horizontal radius size. 5657 5658@item planes 5659Set which planes to filter. By default all planes are filtered. 5660 5661@item sizeY 5662Set vertical radius size, if zero it will be same as @code{sizeX}. 5663Default is @code{0}. 5664@end table 5665 5666@section bbox 5667 5668Compute the bounding box for the non-black pixels in the input frame 5669luminance plane. 5670 5671This filter computes the bounding box containing all the pixels with a 5672luminance value greater than the minimum allowed value. 5673The parameters describing the bounding box are printed on the filter 5674log. 5675 5676The filter accepts the following option: 5677 5678@table @option 5679@item min_val 5680Set the minimal luminance value. Default is @code{16}. 5681@end table 5682 5683@section bitplanenoise 5684 5685Show and measure bit plane noise. 5686 5687The filter accepts the following options: 5688 5689@table @option 5690@item bitplane 5691Set which plane to analyze. Default is @code{1}. 5692 5693@item filter 5694Filter out noisy pixels from @code{bitplane} set above. 5695Default is disabled. 5696@end table 5697 5698@section blackdetect 5699 5700Detect video intervals that are (almost) completely black. Can be 5701useful to detect chapter transitions, commercials, or invalid 5702recordings. Output lines contains the time for the start, end and 5703duration of the detected black interval expressed in seconds. 5704 5705In order to display the output lines, you need to set the loglevel at 5706least to the AV_LOG_INFO value. 5707 5708The filter accepts the following options: 5709 5710@table @option 5711@item black_min_duration, d 5712Set the minimum detected black duration expressed in seconds. It must 5713be a non-negative floating point number. 5714 5715Default value is 2.0. 5716 5717@item picture_black_ratio_th, pic_th 5718Set the threshold for considering a picture "black". 5719Express the minimum value for the ratio: 5720@example 5721@var{nb_black_pixels} / @var{nb_pixels} 5722@end example 5723 5724for which a picture is considered black. 5725Default value is 0.98. 5726 5727@item pixel_black_th, pix_th 5728Set the threshold for considering a pixel "black". 5729 5730The threshold expresses the maximum pixel luminance value for which a 5731pixel is considered "black". The provided value is scaled according to 5732the following equation: 5733@example 5734@var{absolute_threshold} = @var{luminance_minimum_value} + @var{pixel_black_th} * @var{luminance_range_size} 5735@end example 5736 5737@var{luminance_range_size} and @var{luminance_minimum_value} depend on 5738the input video format, the range is [0-255] for YUV full-range 5739formats and [16-235] for YUV non full-range formats. 5740 5741Default value is 0.10. 5742@end table 5743 5744The following example sets the maximum pixel threshold to the minimum 5745value, and detects only black intervals of 2 or more seconds: 5746@example 5747blackdetect=d=2:pix_th=0.00 5748@end example 5749 5750@section blackframe 5751 5752Detect frames that are (almost) completely black. Can be useful to 5753detect chapter transitions or commercials. Output lines consist of 5754the frame number of the detected frame, the percentage of blackness, 5755the position in the file if known or -1 and the timestamp in seconds. 5756 5757In order to display the output lines, you need to set the loglevel at 5758least to the AV_LOG_INFO value. 5759 5760This filter exports frame metadata @code{lavfi.blackframe.pblack}. 5761The value represents the percentage of pixels in the picture that 5762are below the threshold value. 5763 5764It accepts the following parameters: 5765 5766@table @option 5767 5768@item amount 5769The percentage of the pixels that have to be below the threshold; it defaults to 5770@code{98}. 5771 5772@item threshold, thresh 5773The threshold below which a pixel value is considered black; it defaults to 5774@code{32}. 5775 5776@end table 5777 5778@section blend, tblend 5779 5780Blend two video frames into each other. 5781 5782The @code{blend} filter takes two input streams and outputs one 5783stream, the first input is the "top" layer and second input is 5784"bottom" layer. By default, the output terminates when the longest input terminates. 5785 5786The @code{tblend} (time blend) filter takes two consecutive frames 5787from one single stream, and outputs the result obtained by blending 5788the new frame on top of the old frame. 5789 5790A description of the accepted options follows. 5791 5792@table @option 5793@item c0_mode 5794@item c1_mode 5795@item c2_mode 5796@item c3_mode 5797@item all_mode 5798Set blend mode for specific pixel component or all pixel components in case 5799of @var{all_mode}. Default value is @code{normal}. 5800 5801Available values for component modes are: 5802@table @samp 5803@item addition 5804@item grainmerge 5805@item and 5806@item average 5807@item burn 5808@item darken 5809@item difference 5810@item grainextract 5811@item divide 5812@item dodge 5813@item freeze 5814@item exclusion 5815@item extremity 5816@item glow 5817@item hardlight 5818@item hardmix 5819@item heat 5820@item lighten 5821@item linearlight 5822@item multiply 5823@item multiply128 5824@item negation 5825@item normal 5826@item or 5827@item overlay 5828@item phoenix 5829@item pinlight 5830@item reflect 5831@item screen 5832@item softlight 5833@item subtract 5834@item vividlight 5835@item xor 5836@end table 5837 5838@item c0_opacity 5839@item c1_opacity 5840@item c2_opacity 5841@item c3_opacity 5842@item all_opacity 5843Set blend opacity for specific pixel component or all pixel components in case 5844of @var{all_opacity}. Only used in combination with pixel component blend modes. 5845 5846@item c0_expr 5847@item c1_expr 5848@item c2_expr 5849@item c3_expr 5850@item all_expr 5851Set blend expression for specific pixel component or all pixel components in case 5852of @var{all_expr}. Note that related mode options will be ignored if those are set. 5853 5854The expressions can use the following variables: 5855 5856@table @option 5857@item N 5858The sequential number of the filtered frame, starting from @code{0}. 5859 5860@item X 5861@item Y 5862the coordinates of the current sample 5863 5864@item W 5865@item H 5866the width and height of currently filtered plane 5867 5868@item SW 5869@item SH 5870Width and height scale for the plane being filtered. It is the 5871ratio between the dimensions of the current plane to the luma plane, 5872e.g. for a @code{yuv420p} frame, the values are @code{1,1} for 5873the luma plane and @code{0.5,0.5} for the chroma planes. 5874 5875@item T 5876Time of the current frame, expressed in seconds. 5877 5878@item TOP, A 5879Value of pixel component at current location for first video frame (top layer). 5880 5881@item BOTTOM, B 5882Value of pixel component at current location for second video frame (bottom layer). 5883@end table 5884@end table 5885 5886The @code{blend} filter also supports the @ref{framesync} options. 5887 5888@subsection Examples 5889 5890@itemize 5891@item 5892Apply transition from bottom layer to top layer in first 10 seconds: 5893@example 5894blend=all_expr='A*(if(gte(T,10),1,T/10))+B*(1-(if(gte(T,10),1,T/10)))' 5895@end example 5896 5897@item 5898Apply linear horizontal transition from top layer to bottom layer: 5899@example 5900blend=all_expr='A*(X/W)+B*(1-X/W)' 5901@end example 5902 5903@item 5904Apply 1x1 checkerboard effect: 5905@example 5906blend=all_expr='if(eq(mod(X,2),mod(Y,2)),A,B)' 5907@end example 5908 5909@item 5910Apply uncover left effect: 5911@example 5912blend=all_expr='if(gte(N*SW+X,W),A,B)' 5913@end example 5914 5915@item 5916Apply uncover down effect: 5917@example 5918blend=all_expr='if(gte(Y-N*SH,0),A,B)' 5919@end example 5920 5921@item 5922Apply uncover up-left effect: 5923@example 5924blend=all_expr='if(gte(T*SH*40+Y,H)*gte((T*40*SW+X)*W/H,W),A,B)' 5925@end example 5926 5927@item 5928Split diagonally video and shows top and bottom layer on each side: 5929@example 5930blend=all_expr='if(gt(X,Y*(W/H)),A,B)' 5931@end example 5932 5933@item 5934Display differences between the current and the previous frame: 5935@example 5936tblend=all_mode=grainextract 5937@end example 5938@end itemize 5939 5940@section bm3d 5941 5942Denoise frames using Block-Matching 3D algorithm. 5943 5944The filter accepts the following options. 5945 5946@table @option 5947@item sigma 5948Set denoising strength. Default value is 1. 5949Allowed range is from 0 to 999.9. 5950The denoising algorith is very sensitive to sigma, so adjust it 5951according to the source. 5952 5953@item block 5954Set local patch size. This sets dimensions in 2D. 5955 5956@item bstep 5957Set sliding step for processing blocks. Default value is 4. 5958Allowed range is from 1 to 64. 5959Smaller values allows processing more reference blocks and is slower. 5960 5961@item group 5962Set maximal number of similar blocks for 3rd dimension. Default value is 1. 5963When set to 1, no block matching is done. Larger values allows more blocks 5964in single group. 5965Allowed range is from 1 to 256. 5966 5967@item range 5968Set radius for search block matching. Default is 9. 5969Allowed range is from 1 to INT32_MAX. 5970 5971@item mstep 5972Set step between two search locations for block matching. Default is 1. 5973Allowed range is from 1 to 64. Smaller is slower. 5974 5975@item thmse 5976Set threshold of mean square error for block matching. Valid range is 0 to 5977INT32_MAX. 5978 5979@item hdthr 5980Set thresholding parameter for hard thresholding in 3D transformed domain. 5981Larger values results in stronger hard-thresholding filtering in frequency 5982domain. 5983 5984@item estim 5985Set filtering estimation mode. Can be @code{basic} or @code{final}. 5986Default is @code{basic}. 5987 5988@item ref 5989If enabled, filter will use 2nd stream for block matching. 5990Default is disabled for @code{basic} value of @var{estim} option, 5991and always enabled if value of @var{estim} is @code{final}. 5992 5993@item planes 5994Set planes to filter. Default is all available except alpha. 5995@end table 5996 5997@subsection Examples 5998 5999@itemize 6000@item 6001Basic filtering with bm3d: 6002@example 6003bm3d=sigma=3:block=4:bstep=2:group=1:estim=basic 6004@end example 6005 6006@item 6007Same as above, but filtering only luma: 6008@example 6009bm3d=sigma=3:block=4:bstep=2:group=1:estim=basic:planes=1 6010@end example 6011 6012@item 6013Same as above, but with both estimation modes: 6014@example 6015split[a][b],[a]bm3d=sigma=3:block=4:bstep=2:group=1:estim=basic[a],[b][a]bm3d=sigma=3:block=4:bstep=2:group=16:estim=final:ref=1 6016@end example 6017 6018@item 6019Same as above, but prefilter with @ref{nlmeans} filter instead: 6020@example 6021split[a][b],[a]nlmeans=s=3:r=7:p=3[a],[b][a]bm3d=sigma=3:block=4:bstep=2:group=16:estim=final:ref=1 6022@end example 6023@end itemize 6024 6025@section boxblur 6026 6027Apply a boxblur algorithm to the input video. 6028 6029It accepts the following parameters: 6030 6031@table @option 6032 6033@item luma_radius, lr 6034@item luma_power, lp 6035@item chroma_radius, cr 6036@item chroma_power, cp 6037@item alpha_radius, ar 6038@item alpha_power, ap 6039 6040@end table 6041 6042A description of the accepted options follows. 6043 6044@table @option 6045@item luma_radius, lr 6046@item chroma_radius, cr 6047@item alpha_radius, ar 6048Set an expression for the box radius in pixels used for blurring the 6049corresponding input plane. 6050 6051The radius value must be a non-negative number, and must not be 6052greater than the value of the expression @code{min(w,h)/2} for the 6053luma and alpha planes, and of @code{min(cw,ch)/2} for the chroma 6054planes. 6055 6056Default value for @option{luma_radius} is "2". If not specified, 6057@option{chroma_radius} and @option{alpha_radius} default to the 6058corresponding value set for @option{luma_radius}. 6059 6060The expressions can contain the following constants: 6061@table @option 6062@item w 6063@item h 6064The input width and height in pixels. 6065 6066@item cw 6067@item ch 6068The input chroma image width and height in pixels. 6069 6070@item hsub 6071@item vsub 6072The horizontal and vertical chroma subsample values. For example, for the 6073pixel format "yuv422p", @var{hsub} is 2 and @var{vsub} is 1. 6074@end table 6075 6076@item luma_power, lp 6077@item chroma_power, cp 6078@item alpha_power, ap 6079Specify how many times the boxblur filter is applied to the 6080corresponding plane. 6081 6082Default value for @option{luma_power} is 2. If not specified, 6083@option{chroma_power} and @option{alpha_power} default to the 6084corresponding value set for @option{luma_power}. 6085 6086A value of 0 will disable the effect. 6087@end table 6088 6089@subsection Examples 6090 6091@itemize 6092@item 6093Apply a boxblur filter with the luma, chroma, and alpha radii 6094set to 2: 6095@example 6096boxblur=luma_radius=2:luma_power=1 6097boxblur=2:1 6098@end example 6099 6100@item 6101Set the luma radius to 2, and alpha and chroma radius to 0: 6102@example 6103boxblur=2:1:cr=0:ar=0 6104@end example 6105 6106@item 6107Set the luma and chroma radii to a fraction of the video dimension: 6108@example 6109boxblur=luma_radius=min(h\,w)/10:luma_power=1:chroma_radius=min(cw\,ch)/10:chroma_power=1 6110@end example 6111@end itemize 6112 6113@section bwdif 6114 6115Deinterlace the input video ("bwdif" stands for "Bob Weaver 6116Deinterlacing Filter"). 6117 6118Motion adaptive deinterlacing based on yadif with the use of w3fdif and cubic 6119interpolation algorithms. 6120It accepts the following parameters: 6121 6122@table @option 6123@item mode 6124The interlacing mode to adopt. It accepts one of the following values: 6125 6126@table @option 6127@item 0, send_frame 6128Output one frame for each frame. 6129@item 1, send_field 6130Output one frame for each field. 6131@end table 6132 6133The default value is @code{send_field}. 6134 6135@item parity 6136The picture field parity assumed for the input interlaced video. It accepts one 6137of the following values: 6138 6139@table @option 6140@item 0, tff 6141Assume the top field is first. 6142@item 1, bff 6143Assume the bottom field is first. 6144@item -1, auto 6145Enable automatic detection of field parity. 6146@end table 6147 6148The default value is @code{auto}. 6149If the interlacing is unknown or the decoder does not export this information, 6150top field first will be assumed. 6151 6152@item deint 6153Specify which frames to deinterlace. Accept one of the following 6154values: 6155 6156@table @option 6157@item 0, all 6158Deinterlace all frames. 6159@item 1, interlaced 6160Only deinterlace frames marked as interlaced. 6161@end table 6162 6163The default value is @code{all}. 6164@end table 6165 6166@section chromahold 6167Remove all color information for all colors except for certain one. 6168 6169The filter accepts the following options: 6170 6171@table @option 6172@item color 6173The color which will not be replaced with neutral chroma. 6174 6175@item similarity 6176Similarity percentage with the above color. 61770.01 matches only the exact key color, while 1.0 matches everything. 6178 6179@item yuv 6180Signals that the color passed is already in YUV instead of RGB. 6181 6182Literal colors like "green" or "red" don't make sense with this enabled anymore. 6183This can be used to pass exact YUV values as hexadecimal numbers. 6184@end table 6185 6186@section chromakey 6187YUV colorspace color/chroma keying. 6188 6189The filter accepts the following options: 6190 6191@table @option 6192@item color 6193The color which will be replaced with transparency. 6194 6195@item similarity 6196Similarity percentage with the key color. 6197 61980.01 matches only the exact key color, while 1.0 matches everything. 6199 6200@item blend 6201Blend percentage. 6202 62030.0 makes pixels either fully transparent, or not transparent at all. 6204 6205Higher values result in semi-transparent pixels, with a higher transparency 6206the more similar the pixels color is to the key color. 6207 6208@item yuv 6209Signals that the color passed is already in YUV instead of RGB. 6210 6211Literal colors like "green" or "red" don't make sense with this enabled anymore. 6212This can be used to pass exact YUV values as hexadecimal numbers. 6213@end table 6214 6215@subsection Examples 6216 6217@itemize 6218@item 6219Make every green pixel in the input image transparent: 6220@example 6221ffmpeg -i input.png -vf chromakey=green out.png 6222@end example 6223 6224@item 6225Overlay a greenscreen-video on top of a static black background. 6226@example 6227ffmpeg -f lavfi -i color=c=black:s=1280x720 -i video.mp4 -shortest -filter_complex "[1:v]chromakey=0x70de77:0.1:0.2[ckout];[0:v][ckout]overlay[out]" -map "[out]" output.mkv 6228@end example 6229@end itemize 6230 6231@section ciescope 6232 6233Display CIE color diagram with pixels overlaid onto it. 6234 6235The filter accepts the following options: 6236 6237@table @option 6238@item system 6239Set color system. 6240 6241@table @samp 6242@item ntsc, 470m 6243@item ebu, 470bg 6244@item smpte 6245@item 240m 6246@item apple 6247@item widergb 6248@item cie1931 6249@item rec709, hdtv 6250@item uhdtv, rec2020 6251@end table 6252 6253@item cie 6254Set CIE system. 6255 6256@table @samp 6257@item xyy 6258@item ucs 6259@item luv 6260@end table 6261 6262@item gamuts 6263Set what gamuts to draw. 6264 6265See @code{system} option for available values. 6266 6267@item size, s 6268Set ciescope size, by default set to 512. 6269 6270@item intensity, i 6271Set intensity used to map input pixel values to CIE diagram. 6272 6273@item contrast 6274Set contrast used to draw tongue colors that are out of active color system gamut. 6275 6276@item corrgamma 6277Correct gamma displayed on scope, by default enabled. 6278 6279@item showwhite 6280Show white point on CIE diagram, by default disabled. 6281 6282@item gamma 6283Set input gamma. Used only with XYZ input color space. 6284@end table 6285 6286@section codecview 6287 6288Visualize information exported by some codecs. 6289 6290Some codecs can export information through frames using side-data or other 6291means. For example, some MPEG based codecs export motion vectors through the 6292@var{export_mvs} flag in the codec @option{flags2} option. 6293 6294The filter accepts the following option: 6295 6296@table @option 6297@item mv 6298Set motion vectors to visualize. 6299 6300Available flags for @var{mv} are: 6301 6302@table @samp 6303@item pf 6304forward predicted MVs of P-frames 6305@item bf 6306forward predicted MVs of B-frames 6307@item bb 6308backward predicted MVs of B-frames 6309@end table 6310 6311@item qp 6312Display quantization parameters using the chroma planes. 6313 6314@item mv_type, mvt 6315Set motion vectors type to visualize. Includes MVs from all frames unless specified by @var{frame_type} option. 6316 6317Available flags for @var{mv_type} are: 6318 6319@table @samp 6320@item fp 6321forward predicted MVs 6322@item bp 6323backward predicted MVs 6324@end table 6325 6326@item frame_type, ft 6327Set frame type to visualize motion vectors of. 6328 6329Available flags for @var{frame_type} are: 6330 6331@table @samp 6332@item if 6333intra-coded frames (I-frames) 6334@item pf 6335predicted frames (P-frames) 6336@item bf 6337bi-directionally predicted frames (B-frames) 6338@end table 6339@end table 6340 6341@subsection Examples 6342 6343@itemize 6344@item 6345Visualize forward predicted MVs of all frames using @command{ffplay}: 6346@example 6347ffplay -flags2 +export_mvs input.mp4 -vf codecview=mv_type=fp 6348@end example 6349 6350@item 6351Visualize multi-directionals MVs of P and B-Frames using @command{ffplay}: 6352@example 6353ffplay -flags2 +export_mvs input.mp4 -vf codecview=mv=pf+bf+bb 6354@end example 6355@end itemize 6356 6357@section colorbalance 6358Modify intensity of primary colors (red, green and blue) of input frames. 6359 6360The filter allows an input frame to be adjusted in the shadows, midtones or highlights 6361regions for the red-cyan, green-magenta or blue-yellow balance. 6362 6363A positive adjustment value shifts the balance towards the primary color, a negative 6364value towards the complementary color. 6365 6366The filter accepts the following options: 6367 6368@table @option 6369@item rs 6370@item gs 6371@item bs 6372Adjust red, green and blue shadows (darkest pixels). 6373 6374@item rm 6375@item gm 6376@item bm 6377Adjust red, green and blue midtones (medium pixels). 6378 6379@item rh 6380@item gh 6381@item bh 6382Adjust red, green and blue highlights (brightest pixels). 6383 6384Allowed ranges for options are @code{[-1.0, 1.0]}. Defaults are @code{0}. 6385@end table 6386 6387@subsection Examples 6388 6389@itemize 6390@item 6391Add red color cast to shadows: 6392@example 6393colorbalance=rs=.3 6394@end example 6395@end itemize 6396 6397@section colorkey 6398RGB colorspace color keying. 6399 6400The filter accepts the following options: 6401 6402@table @option 6403@item color 6404The color which will be replaced with transparency. 6405 6406@item similarity 6407Similarity percentage with the key color. 6408 64090.01 matches only the exact key color, while 1.0 matches everything. 6410 6411@item blend 6412Blend percentage. 6413 64140.0 makes pixels either fully transparent, or not transparent at all. 6415 6416Higher values result in semi-transparent pixels, with a higher transparency 6417the more similar the pixels color is to the key color. 6418@end table 6419 6420@subsection Examples 6421 6422@itemize 6423@item 6424Make every green pixel in the input image transparent: 6425@example 6426ffmpeg -i input.png -vf colorkey=green out.png 6427@end example 6428 6429@item 6430Overlay a greenscreen-video on top of a static background image. 6431@example 6432ffmpeg -i background.png -i video.mp4 -filter_complex "[1:v]colorkey=0x3BBD1E:0.3:0.2[ckout];[0:v][ckout]overlay[out]" -map "[out]" output.flv 6433@end example 6434@end itemize 6435 6436@section colorlevels 6437 6438Adjust video input frames using levels. 6439 6440The filter accepts the following options: 6441 6442@table @option 6443@item rimin 6444@item gimin 6445@item bimin 6446@item aimin 6447Adjust red, green, blue and alpha input black point. 6448Allowed ranges for options are @code{[-1.0, 1.0]}. Defaults are @code{0}. 6449 6450@item rimax 6451@item gimax 6452@item bimax 6453@item aimax 6454Adjust red, green, blue and alpha input white point. 6455Allowed ranges for options are @code{[-1.0, 1.0]}. Defaults are @code{1}. 6456 6457Input levels are used to lighten highlights (bright tones), darken shadows 6458(dark tones), change the balance of bright and dark tones. 6459 6460@item romin 6461@item gomin 6462@item bomin 6463@item aomin 6464Adjust red, green, blue and alpha output black point. 6465Allowed ranges for options are @code{[0, 1.0]}. Defaults are @code{0}. 6466 6467@item romax 6468@item gomax 6469@item bomax 6470@item aomax 6471Adjust red, green, blue and alpha output white point. 6472Allowed ranges for options are @code{[0, 1.0]}. Defaults are @code{1}. 6473 6474Output levels allows manual selection of a constrained output level range. 6475@end table 6476 6477@subsection Examples 6478 6479@itemize 6480@item 6481Make video output darker: 6482@example 6483colorlevels=rimin=0.058:gimin=0.058:bimin=0.058 6484@end example 6485 6486@item 6487Increase contrast: 6488@example 6489colorlevels=rimin=0.039:gimin=0.039:bimin=0.039:rimax=0.96:gimax=0.96:bimax=0.96 6490@end example 6491 6492@item 6493Make video output lighter: 6494@example 6495colorlevels=rimax=0.902:gimax=0.902:bimax=0.902 6496@end example 6497 6498@item 6499Increase brightness: 6500@example 6501colorlevels=romin=0.5:gomin=0.5:bomin=0.5 6502@end example 6503@end itemize 6504 6505@section colorchannelmixer 6506 6507Adjust video input frames by re-mixing color channels. 6508 6509This filter modifies a color channel by adding the values associated to 6510the other channels of the same pixels. For example if the value to 6511modify is red, the output value will be: 6512@example 6513@var{red}=@var{red}*@var{rr} + @var{blue}*@var{rb} + @var{green}*@var{rg} + @var{alpha}*@var{ra} 6514@end example 6515 6516The filter accepts the following options: 6517 6518@table @option 6519@item rr 6520@item rg 6521@item rb 6522@item ra 6523Adjust contribution of input red, green, blue and alpha channels for output red channel. 6524Default is @code{1} for @var{rr}, and @code{0} for @var{rg}, @var{rb} and @var{ra}. 6525 6526@item gr 6527@item gg 6528@item gb 6529@item ga 6530Adjust contribution of input red, green, blue and alpha channels for output green channel. 6531Default is @code{1} for @var{gg}, and @code{0} for @var{gr}, @var{gb} and @var{ga}. 6532 6533@item br 6534@item bg 6535@item bb 6536@item ba 6537Adjust contribution of input red, green, blue and alpha channels for output blue channel. 6538Default is @code{1} for @var{bb}, and @code{0} for @var{br}, @var{bg} and @var{ba}. 6539 6540@item ar 6541@item ag 6542@item ab 6543@item aa 6544Adjust contribution of input red, green, blue and alpha channels for output alpha channel. 6545Default is @code{1} for @var{aa}, and @code{0} for @var{ar}, @var{ag} and @var{ab}. 6546 6547Allowed ranges for options are @code{[-2.0, 2.0]}. 6548@end table 6549 6550@subsection Examples 6551 6552@itemize 6553@item 6554Convert source to grayscale: 6555@example 6556colorchannelmixer=.3:.4:.3:0:.3:.4:.3:0:.3:.4:.3 6557@end example 6558@item 6559Simulate sepia tones: 6560@example 6561colorchannelmixer=.393:.769:.189:0:.349:.686:.168:0:.272:.534:.131 6562@end example 6563@end itemize 6564 6565@section colormatrix 6566 6567Convert color matrix. 6568 6569The filter accepts the following options: 6570 6571@table @option 6572@item src 6573@item dst 6574Specify the source and destination color matrix. Both values must be 6575specified. 6576 6577The accepted values are: 6578@table @samp 6579@item bt709 6580BT.709 6581 6582@item fcc 6583FCC 6584 6585@item bt601 6586BT.601 6587 6588@item bt470 6589BT.470 6590 6591@item bt470bg 6592BT.470BG 6593 6594@item smpte170m 6595SMPTE-170M 6596 6597@item smpte240m 6598SMPTE-240M 6599 6600@item bt2020 6601BT.2020 6602@end table 6603@end table 6604 6605For example to convert from BT.601 to SMPTE-240M, use the command: 6606@example 6607colormatrix=bt601:smpte240m 6608@end example 6609 6610@section colorspace 6611 6612Convert colorspace, transfer characteristics or color primaries. 6613Input video needs to have an even size. 6614 6615The filter accepts the following options: 6616 6617@table @option 6618@anchor{all} 6619@item all 6620Specify all color properties at once. 6621 6622The accepted values are: 6623@table @samp 6624@item bt470m 6625BT.470M 6626 6627@item bt470bg 6628BT.470BG 6629 6630@item bt601-6-525 6631BT.601-6 525 6632 6633@item bt601-6-625 6634BT.601-6 625 6635 6636@item bt709 6637BT.709 6638 6639@item smpte170m 6640SMPTE-170M 6641 6642@item smpte240m 6643SMPTE-240M 6644 6645@item bt2020 6646BT.2020 6647 6648@end table 6649 6650@anchor{space} 6651@item space 6652Specify output colorspace. 6653 6654The accepted values are: 6655@table @samp 6656@item bt709 6657BT.709 6658 6659@item fcc 6660FCC 6661 6662@item bt470bg 6663BT.470BG or BT.601-6 625 6664 6665@item smpte170m 6666SMPTE-170M or BT.601-6 525 6667 6668@item smpte240m 6669SMPTE-240M 6670 6671@item ycgco 6672YCgCo 6673 6674@item bt2020ncl 6675BT.2020 with non-constant luminance 6676 6677@end table 6678 6679@anchor{trc} 6680@item trc 6681Specify output transfer characteristics. 6682 6683The accepted values are: 6684@table @samp 6685@item bt709 6686BT.709 6687 6688@item bt470m 6689BT.470M 6690 6691@item bt470bg 6692BT.470BG 6693 6694@item gamma22 6695Constant gamma of 2.2 6696 6697@item gamma28 6698Constant gamma of 2.8 6699 6700@item smpte170m 6701SMPTE-170M, BT.601-6 625 or BT.601-6 525 6702 6703@item smpte240m 6704SMPTE-240M 6705 6706@item srgb 6707SRGB 6708 6709@item iec61966-2-1 6710iec61966-2-1 6711 6712@item iec61966-2-4 6713iec61966-2-4 6714 6715@item xvycc 6716xvycc 6717 6718@item bt2020-10 6719BT.2020 for 10-bits content 6720 6721@item bt2020-12 6722BT.2020 for 12-bits content 6723 6724@end table 6725 6726@anchor{primaries} 6727@item primaries 6728Specify output color primaries. 6729 6730The accepted values are: 6731@table @samp 6732@item bt709 6733BT.709 6734 6735@item bt470m 6736BT.470M 6737 6738@item bt470bg 6739BT.470BG or BT.601-6 625 6740 6741@item smpte170m 6742SMPTE-170M or BT.601-6 525 6743 6744@item smpte240m 6745SMPTE-240M 6746 6747@item film 6748film 6749 6750@item smpte431 6751SMPTE-431 6752 6753@item smpte432 6754SMPTE-432 6755 6756@item bt2020 6757BT.2020 6758 6759@item jedec-p22 6760JEDEC P22 phosphors 6761 6762@end table 6763 6764@anchor{range} 6765@item range 6766Specify output color range. 6767 6768The accepted values are: 6769@table @samp 6770@item tv 6771TV (restricted) range 6772 6773@item mpeg 6774MPEG (restricted) range 6775 6776@item pc 6777PC (full) range 6778 6779@item jpeg 6780JPEG (full) range 6781 6782@end table 6783 6784@item format 6785Specify output color format. 6786 6787The accepted values are: 6788@table @samp 6789@item yuv420p 6790YUV 4:2:0 planar 8-bits 6791 6792@item yuv420p10 6793YUV 4:2:0 planar 10-bits 6794 6795@item yuv420p12 6796YUV 4:2:0 planar 12-bits 6797 6798@item yuv422p 6799YUV 4:2:2 planar 8-bits 6800 6801@item yuv422p10 6802YUV 4:2:2 planar 10-bits 6803 6804@item yuv422p12 6805YUV 4:2:2 planar 12-bits 6806 6807@item yuv444p 6808YUV 4:4:4 planar 8-bits 6809 6810@item yuv444p10 6811YUV 4:4:4 planar 10-bits 6812 6813@item yuv444p12 6814YUV 4:4:4 planar 12-bits 6815 6816@end table 6817 6818@item fast 6819Do a fast conversion, which skips gamma/primary correction. This will take 6820significantly less CPU, but will be mathematically incorrect. To get output 6821compatible with that produced by the colormatrix filter, use fast=1. 6822 6823@item dither 6824Specify dithering mode. 6825 6826The accepted values are: 6827@table @samp 6828@item none 6829No dithering 6830 6831@item fsb 6832Floyd-Steinberg dithering 6833@end table 6834 6835@item wpadapt 6836Whitepoint adaptation mode. 6837 6838The accepted values are: 6839@table @samp 6840@item bradford 6841Bradford whitepoint adaptation 6842 6843@item vonkries 6844von Kries whitepoint adaptation 6845 6846@item identity 6847identity whitepoint adaptation (i.e. no whitepoint adaptation) 6848@end table 6849 6850@item iall 6851Override all input properties at once. Same accepted values as @ref{all}. 6852 6853@item ispace 6854Override input colorspace. Same accepted values as @ref{space}. 6855 6856@item iprimaries 6857Override input color primaries. Same accepted values as @ref{primaries}. 6858 6859@item itrc 6860Override input transfer characteristics. Same accepted values as @ref{trc}. 6861 6862@item irange 6863Override input color range. Same accepted values as @ref{range}. 6864 6865@end table 6866 6867The filter converts the transfer characteristics, color space and color 6868primaries to the specified user values. The output value, if not specified, 6869is set to a default value based on the "all" property. If that property is 6870also not specified, the filter will log an error. The output color range and 6871format default to the same value as the input color range and format. The 6872input transfer characteristics, color space, color primaries and color range 6873should be set on the input data. If any of these are missing, the filter will 6874log an error and no conversion will take place. 6875 6876For example to convert the input to SMPTE-240M, use the command: 6877@example 6878colorspace=smpte240m 6879@end example 6880 6881@section convolution 6882 6883Apply convolution of 3x3, 5x5, 7x7 or horizontal/vertical up to 49 elements. 6884 6885The filter accepts the following options: 6886 6887@table @option 6888@item 0m 6889@item 1m 6890@item 2m 6891@item 3m 6892Set matrix for each plane. 6893Matrix is sequence of 9, 25 or 49 signed integers in @var{square} mode, 6894and from 1 to 49 odd number of signed integers in @var{row} mode. 6895 6896@item 0rdiv 6897@item 1rdiv 6898@item 2rdiv 6899@item 3rdiv 6900Set multiplier for calculated value for each plane. 6901If unset or 0, it will be sum of all matrix elements. 6902 6903@item 0bias 6904@item 1bias 6905@item 2bias 6906@item 3bias 6907Set bias for each plane. This value is added to the result of the multiplication. 6908Useful for making the overall image brighter or darker. Default is 0.0. 6909 6910@item 0mode 6911@item 1mode 6912@item 2mode 6913@item 3mode 6914Set matrix mode for each plane. Can be @var{square}, @var{row} or @var{column}. 6915Default is @var{square}. 6916@end table 6917 6918@subsection Examples 6919 6920@itemize 6921@item 6922Apply sharpen: 6923@example 6924convolution="0 -1 0 -1 5 -1 0 -1 0:0 -1 0 -1 5 -1 0 -1 0:0 -1 0 -1 5 -1 0 -1 0:0 -1 0 -1 5 -1 0 -1 0" 6925@end example 6926 6927@item 6928Apply blur: 6929@example 6930convolution="1 1 1 1 1 1 1 1 1:1 1 1 1 1 1 1 1 1:1 1 1 1 1 1 1 1 1:1 1 1 1 1 1 1 1 1:1/9:1/9:1/9:1/9" 6931@end example 6932 6933@item 6934Apply edge enhance: 6935@example 6936convolution="0 0 0 -1 1 0 0 0 0:0 0 0 -1 1 0 0 0 0:0 0 0 -1 1 0 0 0 0:0 0 0 -1 1 0 0 0 0:5:1:1:1:0:128:128:128" 6937@end example 6938 6939@item 6940Apply edge detect: 6941@example 6942convolution="0 1 0 1 -4 1 0 1 0:0 1 0 1 -4 1 0 1 0:0 1 0 1 -4 1 0 1 0:0 1 0 1 -4 1 0 1 0:5:5:5:1:0:128:128:128" 6943@end example 6944 6945@item 6946Apply laplacian edge detector which includes diagonals: 6947@example 6948convolution="1 1 1 1 -8 1 1 1 1:1 1 1 1 -8 1 1 1 1:1 1 1 1 -8 1 1 1 1:1 1 1 1 -8 1 1 1 1:5:5:5:1:0:128:128:0" 6949@end example 6950 6951@item 6952Apply emboss: 6953@example 6954convolution="-2 -1 0 -1 1 1 0 1 2:-2 -1 0 -1 1 1 0 1 2:-2 -1 0 -1 1 1 0 1 2:-2 -1 0 -1 1 1 0 1 2" 6955@end example 6956@end itemize 6957 6958@section convolve 6959 6960Apply 2D convolution of video stream in frequency domain using second stream 6961as impulse. 6962 6963The filter accepts the following options: 6964 6965@table @option 6966@item planes 6967Set which planes to process. 6968 6969@item impulse 6970Set which impulse video frames will be processed, can be @var{first} 6971or @var{all}. Default is @var{all}. 6972@end table 6973 6974The @code{convolve} filter also supports the @ref{framesync} options. 6975 6976@section copy 6977 6978Copy the input video source unchanged to the output. This is mainly useful for 6979testing purposes. 6980 6981@anchor{coreimage} 6982@section coreimage 6983Video filtering on GPU using Apple's CoreImage API on OSX. 6984 6985Hardware acceleration is based on an OpenGL context. Usually, this means it is 6986processed by video hardware. However, software-based OpenGL implementations 6987exist which means there is no guarantee for hardware processing. It depends on 6988the respective OSX. 6989 6990There are many filters and image generators provided by Apple that come with a 6991large variety of options. The filter has to be referenced by its name along 6992with its options. 6993 6994The coreimage filter accepts the following options: 6995@table @option 6996@item list_filters 6997List all available filters and generators along with all their respective 6998options as well as possible minimum and maximum values along with the default 6999values. 7000@example 7001list_filters=true 7002@end example 7003 7004@item filter 7005Specify all filters by their respective name and options. 7006Use @var{list_filters} to determine all valid filter names and options. 7007Numerical options are specified by a float value and are automatically clamped 7008to their respective value range. Vector and color options have to be specified 7009by a list of space separated float values. Character escaping has to be done. 7010A special option name @code{default} is available to use default options for a 7011filter. 7012 7013It is required to specify either @code{default} or at least one of the filter options. 7014All omitted options are used with their default values. 7015The syntax of the filter string is as follows: 7016@example 7017filter=<NAME>@@<OPTION>=<VALUE>[@@<OPTION>=<VALUE>][@@...][#<NAME>@@<OPTION>=<VALUE>[@@<OPTION>=<VALUE>][@@...]][#...] 7018@end example 7019 7020@item output_rect 7021Specify a rectangle where the output of the filter chain is copied into the 7022input image. It is given by a list of space separated float values: 7023@example 7024output_rect=x\ y\ width\ height 7025@end example 7026If not given, the output rectangle equals the dimensions of the input image. 7027The output rectangle is automatically cropped at the borders of the input 7028image. Negative values are valid for each component. 7029@example 7030output_rect=25\ 25\ 100\ 100 7031@end example 7032@end table 7033 7034Several filters can be chained for successive processing without GPU-HOST 7035transfers allowing for fast processing of complex filter chains. 7036Currently, only filters with zero (generators) or exactly one (filters) input 7037image and one output image are supported. Also, transition filters are not yet 7038usable as intended. 7039 7040Some filters generate output images with additional padding depending on the 7041respective filter kernel. The padding is automatically removed to ensure the 7042filter output has the same size as the input image. 7043 7044For image generators, the size of the output image is determined by the 7045previous output image of the filter chain or the input image of the whole 7046filterchain, respectively. The generators do not use the pixel information of 7047this image to generate their output. However, the generated output is 7048blended onto this image, resulting in partial or complete coverage of the 7049output image. 7050 7051The @ref{coreimagesrc} video source can be used for generating input images 7052which are directly fed into the filter chain. By using it, providing input 7053images by another video source or an input video is not required. 7054 7055@subsection Examples 7056 7057@itemize 7058 7059@item 7060List all filters available: 7061@example 7062coreimage=list_filters=true 7063@end example 7064 7065@item 7066Use the CIBoxBlur filter with default options to blur an image: 7067@example 7068coreimage=filter=CIBoxBlur@@default 7069@end example 7070 7071@item 7072Use a filter chain with CISepiaTone at default values and CIVignetteEffect with 7073its center at 100x100 and a radius of 50 pixels: 7074@example 7075coreimage=filter=CIBoxBlur@@default#CIVignetteEffect@@inputCenter=100\ 100@@inputRadius=50 7076@end example 7077 7078@item 7079Use nullsrc and CIQRCodeGenerator to create a QR code for the FFmpeg homepage, 7080given as complete and escaped command-line for Apple's standard bash shell: 7081@example 7082ffmpeg -f lavfi -i nullsrc=s=100x100,coreimage=filter=CIQRCodeGenerator@@inputMessage=https\\\\\://FFmpeg.org/@@inputCorrectionLevel=H -frames:v 1 QRCode.png 7083@end example 7084@end itemize 7085 7086@section crop 7087 7088Crop the input video to given dimensions. 7089 7090It accepts the following parameters: 7091 7092@table @option 7093@item w, out_w 7094The width of the output video. It defaults to @code{iw}. 7095This expression is evaluated only once during the filter 7096configuration, or when the @samp{w} or @samp{out_w} command is sent. 7097 7098@item h, out_h 7099The height of the output video. It defaults to @code{ih}. 7100This expression is evaluated only once during the filter 7101configuration, or when the @samp{h} or @samp{out_h} command is sent. 7102 7103@item x 7104The horizontal position, in the input video, of the left edge of the output 7105video. It defaults to @code{(in_w-out_w)/2}. 7106This expression is evaluated per-frame. 7107 7108@item y 7109The vertical position, in the input video, of the top edge of the output video. 7110It defaults to @code{(in_h-out_h)/2}. 7111This expression is evaluated per-frame. 7112 7113@item keep_aspect 7114If set to 1 will force the output display aspect ratio 7115to be the same of the input, by changing the output sample aspect 7116ratio. It defaults to 0. 7117 7118@item exact 7119Enable exact cropping. If enabled, subsampled videos will be cropped at exact 7120width/height/x/y as specified and will not be rounded to nearest smaller value. 7121It defaults to 0. 7122@end table 7123 7124The @var{out_w}, @var{out_h}, @var{x}, @var{y} parameters are 7125expressions containing the following constants: 7126 7127@table @option 7128@item x 7129@item y 7130The computed values for @var{x} and @var{y}. They are evaluated for 7131each new frame. 7132 7133@item in_w 7134@item in_h 7135The input width and height. 7136 7137@item iw 7138@item ih 7139These are the same as @var{in_w} and @var{in_h}. 7140 7141@item out_w 7142@item out_h 7143The output (cropped) width and height. 7144 7145@item ow 7146@item oh 7147These are the same as @var{out_w} and @var{out_h}. 7148 7149@item a 7150same as @var{iw} / @var{ih} 7151 7152@item sar 7153input sample aspect ratio 7154 7155@item dar 7156input display aspect ratio, it is the same as (@var{iw} / @var{ih}) * @var{sar} 7157 7158@item hsub 7159@item vsub 7160horizontal and vertical chroma subsample values. For example for the 7161pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1. 7162 7163@item n 7164The number of the input frame, starting from 0. 7165 7166@item pos 7167the position in the file of the input frame, NAN if unknown 7168 7169@item t 7170The timestamp expressed in seconds. It's NAN if the input timestamp is unknown. 7171 7172@end table 7173 7174The expression for @var{out_w} may depend on the value of @var{out_h}, 7175and the expression for @var{out_h} may depend on @var{out_w}, but they 7176cannot depend on @var{x} and @var{y}, as @var{x} and @var{y} are 7177evaluated after @var{out_w} and @var{out_h}. 7178 7179The @var{x} and @var{y} parameters specify the expressions for the 7180position of the top-left corner of the output (non-cropped) area. They 7181are evaluated for each frame. If the evaluated value is not valid, it 7182is approximated to the nearest valid value. 7183 7184The expression for @var{x} may depend on @var{y}, and the expression 7185for @var{y} may depend on @var{x}. 7186 7187@subsection Examples 7188 7189@itemize 7190@item 7191Crop area with size 100x100 at position (12,34). 7192@example 7193crop=100:100:12:34 7194@end example 7195 7196Using named options, the example above becomes: 7197@example 7198crop=w=100:h=100:x=12:y=34 7199@end example 7200 7201@item 7202Crop the central input area with size 100x100: 7203@example 7204crop=100:100 7205@end example 7206 7207@item 7208Crop the central input area with size 2/3 of the input video: 7209@example 7210crop=2/3*in_w:2/3*in_h 7211@end example 7212 7213@item 7214Crop the input video central square: 7215@example 7216crop=out_w=in_h 7217crop=in_h 7218@end example 7219 7220@item 7221Delimit the rectangle with the top-left corner placed at position 7222100:100 and the right-bottom corner corresponding to the right-bottom 7223corner of the input image. 7224@example 7225crop=in_w-100:in_h-100:100:100 7226@end example 7227 7228@item 7229Crop 10 pixels from the left and right borders, and 20 pixels from 7230the top and bottom borders 7231@example 7232crop=in_w-2*10:in_h-2*20 7233@end example 7234 7235@item 7236Keep only the bottom right quarter of the input image: 7237@example 7238crop=in_w/2:in_h/2:in_w/2:in_h/2 7239@end example 7240 7241@item 7242Crop height for getting Greek harmony: 7243@example 7244crop=in_w:1/PHI*in_w 7245@end example 7246 7247@item 7248Apply trembling effect: 7249@example 7250crop=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) 7251@end example 7252 7253@item 7254Apply erratic camera effect depending on timestamp: 7255@example 7256crop=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)" 7257@end example 7258 7259@item 7260Set x depending on the value of y: 7261@example 7262crop=in_w/2:in_h/2:y:10+10*sin(n/10) 7263@end example 7264@end itemize 7265 7266@subsection Commands 7267 7268This filter supports the following commands: 7269@table @option 7270@item w, out_w 7271@item h, out_h 7272@item x 7273@item y 7274Set width/height of the output video and the horizontal/vertical position 7275in the input video. 7276The command accepts the same syntax of the corresponding option. 7277 7278If the specified expression is not valid, it is kept at its current 7279value. 7280@end table 7281 7282@section cropdetect 7283 7284Auto-detect the crop size. 7285 7286It calculates the necessary cropping parameters and prints the 7287recommended parameters via the logging system. The detected dimensions 7288correspond to the non-black area of the input video. 7289 7290It accepts the following parameters: 7291 7292@table @option 7293 7294@item limit 7295Set higher black value threshold, which can be optionally specified 7296from nothing (0) to everything (255 for 8-bit based formats). An intensity 7297value greater to the set value is considered non-black. It defaults to 24. 7298You can also specify a value between 0.0 and 1.0 which will be scaled depending 7299on the bitdepth of the pixel format. 7300 7301@item round 7302The value which the width/height should be divisible by. It defaults to 730316. The offset is automatically adjusted to center the video. Use 2 to 7304get only even dimensions (needed for 4:2:2 video). 16 is best when 7305encoding to most video codecs. 7306 7307@item reset_count, reset 7308Set the counter that determines after how many frames cropdetect will 7309reset the previously detected largest video area and start over to 7310detect the current optimal crop area. Default value is 0. 7311 7312This can be useful when channel logos distort the video area. 0 7313indicates 'never reset', and returns the largest area encountered during 7314playback. 7315@end table 7316 7317@anchor{cue} 7318@section cue 7319 7320Delay video filtering until a given wallclock timestamp. The filter first 7321passes on @option{preroll} amount of frames, then it buffers at most 7322@option{buffer} amount of frames and waits for the cue. After reaching the cue 7323it forwards the buffered frames and also any subsequent frames coming in its 7324input. 7325 7326The filter can be used synchronize the output of multiple ffmpeg processes for 7327realtime output devices like decklink. By putting the delay in the filtering 7328chain and pre-buffering frames the process can pass on data to output almost 7329immediately after the target wallclock timestamp is reached. 7330 7331Perfect frame accuracy cannot be guaranteed, but the result is good enough for 7332some use cases. 7333 7334@table @option 7335 7336@item cue 7337The cue timestamp expressed in a UNIX timestamp in microseconds. Default is 0. 7338 7339@item preroll 7340The duration of content to pass on as preroll expressed in seconds. Default is 0. 7341 7342@item buffer 7343The maximum duration of content to buffer before waiting for the cue expressed 7344in seconds. Default is 0. 7345 7346@end table 7347 7348@anchor{curves} 7349@section curves 7350 7351Apply color adjustments using curves. 7352 7353This filter is similar to the Adobe Photoshop and GIMP curves tools. Each 7354component (red, green and blue) has its values defined by @var{N} key points 7355tied from each other using a smooth curve. The x-axis represents the pixel 7356values from the input frame, and the y-axis the new pixel values to be set for 7357the output frame. 7358 7359By default, a component curve is defined by the two points @var{(0;0)} and 7360@var{(1;1)}. This creates a straight line where each original pixel value is 7361"adjusted" to its own value, which means no change to the image. 7362 7363The filter allows you to redefine these two points and add some more. A new 7364curve (using a natural cubic spline interpolation) will be define to pass 7365smoothly through all these new coordinates. The new defined points needs to be 7366strictly increasing over the x-axis, and their @var{x} and @var{y} values must 7367be in the @var{[0;1]} interval. If the computed curves happened to go outside 7368the vector spaces, the values will be clipped accordingly. 7369 7370The filter accepts the following options: 7371 7372@table @option 7373@item preset 7374Select one of the available color presets. This option can be used in addition 7375to the @option{r}, @option{g}, @option{b} parameters; in this case, the later 7376options takes priority on the preset values. 7377Available presets are: 7378@table @samp 7379@item none 7380@item color_negative 7381@item cross_process 7382@item darker 7383@item increase_contrast 7384@item lighter 7385@item linear_contrast 7386@item medium_contrast 7387@item negative 7388@item strong_contrast 7389@item vintage 7390@end table 7391Default is @code{none}. 7392@item master, m 7393Set the master key points. These points will define a second pass mapping. It 7394is sometimes called a "luminance" or "value" mapping. It can be used with 7395@option{r}, @option{g}, @option{b} or @option{all} since it acts like a 7396post-processing LUT. 7397@item red, r 7398Set the key points for the red component. 7399@item green, g 7400Set the key points for the green component. 7401@item blue, b 7402Set the key points for the blue component. 7403@item all 7404Set the key points for all components (not including master). 7405Can be used in addition to the other key points component 7406options. In this case, the unset component(s) will fallback on this 7407@option{all} setting. 7408@item psfile 7409Specify a Photoshop curves file (@code{.acv}) to import the settings from. 7410@item plot 7411Save Gnuplot script of the curves in specified file. 7412@end table 7413 7414To avoid some filtergraph syntax conflicts, each key points list need to be 7415defined using the following syntax: @code{x0/y0 x1/y1 x2/y2 ...}. 7416 7417@subsection Examples 7418 7419@itemize 7420@item 7421Increase slightly the middle level of blue: 7422@example 7423curves=blue='0/0 0.5/0.58 1/1' 7424@end example 7425 7426@item 7427Vintage effect: 7428@example 7429curves=r='0/0.11 .42/.51 1/0.95':g='0/0 0.50/0.48 1/1':b='0/0.22 .49/.44 1/0.8' 7430@end example 7431Here we obtain the following coordinates for each components: 7432@table @var 7433@item red 7434@code{(0;0.11) (0.42;0.51) (1;0.95)} 7435@item green 7436@code{(0;0) (0.50;0.48) (1;1)} 7437@item blue 7438@code{(0;0.22) (0.49;0.44) (1;0.80)} 7439@end table 7440 7441@item 7442The previous example can also be achieved with the associated built-in preset: 7443@example 7444curves=preset=vintage 7445@end example 7446 7447@item 7448Or simply: 7449@example 7450curves=vintage 7451@end example 7452 7453@item 7454Use a Photoshop preset and redefine the points of the green component: 7455@example 7456curves=psfile='MyCurvesPresets/purple.acv':green='0/0 0.45/0.53 1/1' 7457@end example 7458 7459@item 7460Check out the curves of the @code{cross_process} profile using @command{ffmpeg} 7461and @command{gnuplot}: 7462@example 7463ffmpeg -f lavfi -i color -vf curves=cross_process:plot=/tmp/curves.plt -frames:v 1 -f null - 7464gnuplot -p /tmp/curves.plt 7465@end example 7466@end itemize 7467 7468@section datascope 7469 7470Video data analysis filter. 7471 7472This filter shows hexadecimal pixel values of part of video. 7473 7474The filter accepts the following options: 7475 7476@table @option 7477@item size, s 7478Set output video size. 7479 7480@item x 7481Set x offset from where to pick pixels. 7482 7483@item y 7484Set y offset from where to pick pixels. 7485 7486@item mode 7487Set scope mode, can be one of the following: 7488@table @samp 7489@item mono 7490Draw hexadecimal pixel values with white color on black background. 7491 7492@item color 7493Draw hexadecimal pixel values with input video pixel color on black 7494background. 7495 7496@item color2 7497Draw hexadecimal pixel values on color background picked from input video, 7498the text color is picked in such way so its always visible. 7499@end table 7500 7501@item axis 7502Draw rows and columns numbers on left and top of video. 7503 7504@item opacity 7505Set background opacity. 7506@end table 7507 7508@section dctdnoiz 7509 7510Denoise frames using 2D DCT (frequency domain filtering). 7511 7512This filter is not designed for real time. 7513 7514The filter accepts the following options: 7515 7516@table @option 7517@item sigma, s 7518Set the noise sigma constant. 7519 7520This @var{sigma} defines a hard threshold of @code{3 * sigma}; every DCT 7521coefficient (absolute value) below this threshold with be dropped. 7522 7523If you need a more advanced filtering, see @option{expr}. 7524 7525Default is @code{0}. 7526 7527@item overlap 7528Set number overlapping pixels for each block. Since the filter can be slow, you 7529may want to reduce this value, at the cost of a less effective filter and the 7530risk of various artefacts. 7531 7532If the overlapping value doesn't permit processing the whole input width or 7533height, a warning will be displayed and according borders won't be denoised. 7534 7535Default value is @var{blocksize}-1, which is the best possible setting. 7536 7537@item expr, e 7538Set the coefficient factor expression. 7539 7540For each coefficient of a DCT block, this expression will be evaluated as a 7541multiplier value for the coefficient. 7542 7543If this is option is set, the @option{sigma} option will be ignored. 7544 7545The absolute value of the coefficient can be accessed through the @var{c} 7546variable. 7547 7548@item n 7549Set the @var{blocksize} using the number of bits. @code{1<<@var{n}} defines the 7550@var{blocksize}, which is the width and height of the processed blocks. 7551 7552The default value is @var{3} (8x8) and can be raised to @var{4} for a 7553@var{blocksize} of 16x16. Note that changing this setting has huge consequences 7554on the speed processing. Also, a larger block size does not necessarily means a 7555better de-noising. 7556@end table 7557 7558@subsection Examples 7559 7560Apply a denoise with a @option{sigma} of @code{4.5}: 7561@example 7562dctdnoiz=4.5 7563@end example 7564 7565The same operation can be achieved using the expression system: 7566@example 7567dctdnoiz=e='gte(c, 4.5*3)' 7568@end example 7569 7570Violent denoise using a block size of @code{16x16}: 7571@example 7572dctdnoiz=15:n=4 7573@end example 7574 7575@section deband 7576 7577Remove banding artifacts from input video. 7578It works by replacing banded pixels with average value of referenced pixels. 7579 7580The filter accepts the following options: 7581 7582@table @option 7583@item 1thr 7584@item 2thr 7585@item 3thr 7586@item 4thr 7587Set banding detection threshold for each plane. Default is 0.02. 7588Valid range is 0.00003 to 0.5. 7589If difference between current pixel and reference pixel is less than threshold, 7590it will be considered as banded. 7591 7592@item range, r 7593Banding detection range in pixels. Default is 16. If positive, random number 7594in range 0 to set value will be used. If negative, exact absolute value 7595will be used. 7596The range defines square of four pixels around current pixel. 7597 7598@item direction, d 7599Set direction in radians from which four pixel will be compared. If positive, 7600random direction from 0 to set direction will be picked. If negative, exact of 7601absolute value will be picked. For example direction 0, -PI or -2*PI radians 7602will pick only pixels on same row and -PI/2 will pick only pixels on same 7603column. 7604 7605@item blur, b 7606If enabled, current pixel is compared with average value of all four 7607surrounding pixels. The default is enabled. If disabled current pixel is 7608compared with all four surrounding pixels. The pixel is considered banded 7609if only all four differences with surrounding pixels are less than threshold. 7610 7611@item coupling, c 7612If enabled, current pixel is changed if and only if all pixel components are banded, 7613e.g. banding detection threshold is triggered for all color components. 7614The default is disabled. 7615@end table 7616 7617@section deblock 7618 7619Remove blocking artifacts from input video. 7620 7621The filter accepts the following options: 7622 7623@table @option 7624@item filter 7625Set filter type, can be @var{weak} or @var{strong}. Default is @var{strong}. 7626This controls what kind of deblocking is applied. 7627 7628@item block 7629Set size of block, allowed range is from 4 to 512. Default is @var{8}. 7630 7631@item alpha 7632@item beta 7633@item gamma 7634@item delta 7635Set blocking detection thresholds. Allowed range is 0 to 1. 7636Defaults are: @var{0.098} for @var{alpha} and @var{0.05} for the rest. 7637Using higher threshold gives more deblocking strength. 7638Setting @var{alpha} controls threshold detection at exact edge of block. 7639Remaining options controls threshold detection near the edge. Each one for 7640below/above or left/right. Setting any of those to @var{0} disables 7641deblocking. 7642 7643@item planes 7644Set planes to filter. Default is to filter all available planes. 7645@end table 7646 7647@subsection Examples 7648 7649@itemize 7650@item 7651Deblock using weak filter and block size of 4 pixels. 7652@example 7653deblock=filter=weak:block=4 7654@end example 7655 7656@item 7657Deblock using strong filter, block size of 4 pixels and custom thresholds for 7658deblocking more edges. 7659@example 7660deblock=filter=strong:block=4:alpha=0.12:beta=0.07:gamma=0.06:delta=0.05 7661@end example 7662 7663@item 7664Similar as above, but filter only first plane. 7665@example 7666deblock=filter=strong:block=4:alpha=0.12:beta=0.07:gamma=0.06:delta=0.05:planes=1 7667@end example 7668 7669@item 7670Similar as above, but filter only second and third plane. 7671@example 7672deblock=filter=strong:block=4:alpha=0.12:beta=0.07:gamma=0.06:delta=0.05:planes=6 7673@end example 7674@end itemize 7675 7676@anchor{decimate} 7677@section decimate 7678 7679Drop duplicated frames at regular intervals. 7680 7681The filter accepts the following options: 7682 7683@table @option 7684@item cycle 7685Set the number of frames from which one will be dropped. Setting this to 7686@var{N} means one frame in every batch of @var{N} frames will be dropped. 7687Default is @code{5}. 7688 7689@item dupthresh 7690Set the threshold for duplicate detection. If the difference metric for a frame 7691is less than or equal to this value, then it is declared as duplicate. Default 7692is @code{1.1} 7693 7694@item scthresh 7695Set scene change threshold. Default is @code{15}. 7696 7697@item blockx 7698@item blocky 7699Set the size of the x and y-axis blocks used during metric calculations. 7700Larger blocks give better noise suppression, but also give worse detection of 7701small movements. Must be a power of two. Default is @code{32}. 7702 7703@item ppsrc 7704Mark main input as a pre-processed input and activate clean source input 7705stream. This allows the input to be pre-processed with various filters to help 7706the metrics calculation while keeping the frame selection lossless. When set to 7707@code{1}, the first stream is for the pre-processed input, and the second 7708stream is the clean source from where the kept frames are chosen. Default is 7709@code{0}. 7710 7711@item chroma 7712Set whether or not chroma is considered in the metric calculations. Default is 7713@code{1}. 7714@end table 7715 7716@section deconvolve 7717 7718Apply 2D deconvolution of video stream in frequency domain using second stream 7719as impulse. 7720 7721The filter accepts the following options: 7722 7723@table @option 7724@item planes 7725Set which planes to process. 7726 7727@item impulse 7728Set which impulse video frames will be processed, can be @var{first} 7729or @var{all}. Default is @var{all}. 7730 7731@item noise 7732Set noise when doing divisions. Default is @var{0.0000001}. Useful when width 7733and height are not same and not power of 2 or if stream prior to convolving 7734had noise. 7735@end table 7736 7737The @code{deconvolve} filter also supports the @ref{framesync} options. 7738 7739@section deflate 7740 7741Apply deflate effect to the video. 7742 7743This filter replaces the pixel by the local(3x3) average by taking into account 7744only values lower than the pixel. 7745 7746It accepts the following options: 7747 7748@table @option 7749@item threshold0 7750@item threshold1 7751@item threshold2 7752@item threshold3 7753Limit the maximum change for each plane, default is 65535. 7754If 0, plane will remain unchanged. 7755@end table 7756 7757@section deflicker 7758 7759Remove temporal frame luminance variations. 7760 7761It accepts the following options: 7762 7763@table @option 7764@item size, s 7765Set moving-average filter size in frames. Default is 5. Allowed range is 2 - 129. 7766 7767@item mode, m 7768Set averaging mode to smooth temporal luminance variations. 7769 7770Available values are: 7771@table @samp 7772@item am 7773Arithmetic mean 7774 7775@item gm 7776Geometric mean 7777 7778@item hm 7779Harmonic mean 7780 7781@item qm 7782Quadratic mean 7783 7784@item cm 7785Cubic mean 7786 7787@item pm 7788Power mean 7789 7790@item median 7791Median 7792@end table 7793 7794@item bypass 7795Do not actually modify frame. Useful when one only wants metadata. 7796@end table 7797 7798@section dejudder 7799 7800Remove judder produced by partially interlaced telecined content. 7801 7802Judder can be introduced, for instance, by @ref{pullup} filter. If the original 7803source was partially telecined content then the output of @code{pullup,dejudder} 7804will have a variable frame rate. May change the recorded frame rate of the 7805container. Aside from that change, this filter will not affect constant frame 7806rate video. 7807 7808The option available in this filter is: 7809@table @option 7810 7811@item cycle 7812Specify the length of the window over which the judder repeats. 7813 7814Accepts any integer greater than 1. Useful values are: 7815@table @samp 7816 7817@item 4 7818If the original was telecined from 24 to 30 fps (Film to NTSC). 7819 7820@item 5 7821If the original was telecined from 25 to 30 fps (PAL to NTSC). 7822 7823@item 20 7824If a mixture of the two. 7825@end table 7826 7827The default is @samp{4}. 7828@end table 7829 7830@section delogo 7831 7832Suppress a TV station logo by a simple interpolation of the surrounding 7833pixels. Just set a rectangle covering the logo and watch it disappear 7834(and sometimes something even uglier appear - your mileage may vary). 7835 7836It accepts the following parameters: 7837@table @option 7838 7839@item x 7840@item y 7841Specify the top left corner coordinates of the logo. They must be 7842specified. 7843 7844@item w 7845@item h 7846Specify the width and height of the logo to clear. They must be 7847specified. 7848 7849@item band, t 7850Specify the thickness of the fuzzy edge of the rectangle (added to 7851@var{w} and @var{h}). The default value is 1. This option is 7852deprecated, setting higher values should no longer be necessary and 7853is not recommended. 7854 7855@item show 7856When set to 1, a green rectangle is drawn on the screen to simplify 7857finding the right @var{x}, @var{y}, @var{w}, and @var{h} parameters. 7858The default value is 0. 7859 7860The rectangle is drawn on the outermost pixels which will be (partly) 7861replaced with interpolated values. The values of the next pixels 7862immediately outside this rectangle in each direction will be used to 7863compute the interpolated pixel values inside the rectangle. 7864 7865@end table 7866 7867@subsection Examples 7868 7869@itemize 7870@item 7871Set a rectangle covering the area with top left corner coordinates 0,0 7872and size 100x77, and a band of size 10: 7873@example 7874delogo=x=0:y=0:w=100:h=77:band=10 7875@end example 7876 7877@end itemize 7878 7879@section deshake 7880 7881Attempt to fix small changes in horizontal and/or vertical shift. This 7882filter helps remove camera shake from hand-holding a camera, bumping a 7883tripod, moving on a vehicle, etc. 7884 7885The filter accepts the following options: 7886 7887@table @option 7888 7889@item x 7890@item y 7891@item w 7892@item h 7893Specify a rectangular area where to limit the search for motion 7894vectors. 7895If desired the search for motion vectors can be limited to a 7896rectangular area of the frame defined by its top left corner, width 7897and height. These parameters have the same meaning as the drawbox 7898filter which can be used to visualise the position of the bounding 7899box. 7900 7901This is useful when simultaneous movement of subjects within the frame 7902might be confused for camera motion by the motion vector search. 7903 7904If any or all of @var{x}, @var{y}, @var{w} and @var{h} are set to -1 7905then the full frame is used. This allows later options to be set 7906without specifying the bounding box for the motion vector search. 7907 7908Default - search the whole frame. 7909 7910@item rx 7911@item ry 7912Specify the maximum extent of movement in x and y directions in the 7913range 0-64 pixels. Default 16. 7914 7915@item edge 7916Specify how to generate pixels to fill blanks at the edge of the 7917frame. Available values are: 7918@table @samp 7919@item blank, 0 7920Fill zeroes at blank locations 7921@item original, 1 7922Original image at blank locations 7923@item clamp, 2 7924Extruded edge value at blank locations 7925@item mirror, 3 7926Mirrored edge at blank locations 7927@end table 7928Default value is @samp{mirror}. 7929 7930@item blocksize 7931Specify the blocksize to use for motion search. Range 4-128 pixels, 7932default 8. 7933 7934@item contrast 7935Specify the contrast threshold for blocks. Only blocks with more than 7936the specified contrast (difference between darkest and lightest 7937pixels) will be considered. Range 1-255, default 125. 7938 7939@item search 7940Specify the search strategy. Available values are: 7941@table @samp 7942@item exhaustive, 0 7943Set exhaustive search 7944@item less, 1 7945Set less exhaustive search. 7946@end table 7947Default value is @samp{exhaustive}. 7948 7949@item filename 7950If set then a detailed log of the motion search is written to the 7951specified file. 7952 7953@end table 7954 7955@section despill 7956 7957Remove unwanted contamination of foreground colors, caused by reflected color of 7958greenscreen or bluescreen. 7959 7960This filter accepts the following options: 7961 7962@table @option 7963@item type 7964Set what type of despill to use. 7965 7966@item mix 7967Set how spillmap will be generated. 7968 7969@item expand 7970Set how much to get rid of still remaining spill. 7971 7972@item red 7973Controls amount of red in spill area. 7974 7975@item green 7976Controls amount of green in spill area. 7977Should be -1 for greenscreen. 7978 7979@item blue 7980Controls amount of blue in spill area. 7981Should be -1 for bluescreen. 7982 7983@item brightness 7984Controls brightness of spill area, preserving colors. 7985 7986@item alpha 7987Modify alpha from generated spillmap. 7988@end table 7989 7990@section detelecine 7991 7992Apply an exact inverse of the telecine operation. It requires a predefined 7993pattern specified using the pattern option which must be the same as that passed 7994to the telecine filter. 7995 7996This filter accepts the following options: 7997 7998@table @option 7999@item first_field 8000@table @samp 8001@item top, t 8002top field first 8003@item bottom, b 8004bottom field first 8005The default value is @code{top}. 8006@end table 8007 8008@item pattern 8009A string of numbers representing the pulldown pattern you wish to apply. 8010The default value is @code{23}. 8011 8012@item start_frame 8013A number representing position of the first frame with respect to the telecine 8014pattern. This is to be used if the stream is cut. The default value is @code{0}. 8015@end table 8016 8017@section dilation 8018 8019Apply dilation effect to the video. 8020 8021This filter replaces the pixel by the local(3x3) maximum. 8022 8023It accepts the following options: 8024 8025@table @option 8026@item threshold0 8027@item threshold1 8028@item threshold2 8029@item threshold3 8030Limit the maximum change for each plane, default is 65535. 8031If 0, plane will remain unchanged. 8032 8033@item coordinates 8034Flag which specifies the pixel to refer to. Default is 255 i.e. all eight 8035pixels are used. 8036 8037Flags to local 3x3 coordinates maps like this: 8038 8039 1 2 3 8040 4 5 8041 6 7 8 8042@end table 8043 8044@section displace 8045 8046Displace pixels as indicated by second and third input stream. 8047 8048It takes three input streams and outputs one stream, the first input is the 8049source, and second and third input are displacement maps. 8050 8051The second input specifies how much to displace pixels along the 8052x-axis, while the third input specifies how much to displace pixels 8053along the y-axis. 8054If one of displacement map streams terminates, last frame from that 8055displacement map will be used. 8056 8057Note that once generated, displacements maps can be reused over and over again. 8058 8059A description of the accepted options follows. 8060 8061@table @option 8062@item edge 8063Set displace behavior for pixels that are out of range. 8064 8065Available values are: 8066@table @samp 8067@item blank 8068Missing pixels are replaced by black pixels. 8069 8070@item smear 8071Adjacent pixels will spread out to replace missing pixels. 8072 8073@item wrap 8074Out of range pixels are wrapped so they point to pixels of other side. 8075 8076@item mirror 8077Out of range pixels will be replaced with mirrored pixels. 8078@end table 8079Default is @samp{smear}. 8080 8081@end table 8082 8083@subsection Examples 8084 8085@itemize 8086@item 8087Add ripple effect to rgb input of video size hd720: 8088@example 8089ffmpeg -i INPUT -f lavfi -i nullsrc=s=hd720,lutrgb=128:128:128 -f lavfi -i nullsrc=s=hd720,geq='r=128+30*sin(2*PI*X/400+T):g=128+30*sin(2*PI*X/400+T):b=128+30*sin(2*PI*X/400+T)' -lavfi '[0][1][2]displace' OUTPUT 8090@end example 8091 8092@item 8093Add wave effect to rgb input of video size hd720: 8094@example 8095ffmpeg -i INPUT -f lavfi -i nullsrc=hd720,geq='r=128+80*(sin(sqrt((X-W/2)*(X-W/2)+(Y-H/2)*(Y-H/2))/220*2*PI+T)):g=128+80*(sin(sqrt((X-W/2)*(X-W/2)+(Y-H/2)*(Y-H/2))/220*2*PI+T)):b=128+80*(sin(sqrt((X-W/2)*(X-W/2)+(Y-H/2)*(Y-H/2))/220*2*PI+T))' -lavfi '[1]split[x][y],[0][x][y]displace' OUTPUT 8096@end example 8097@end itemize 8098 8099@section drawbox 8100 8101Draw a colored box on the input image. 8102 8103It accepts the following parameters: 8104 8105@table @option 8106@item x 8107@item y 8108The expressions which specify the top left corner coordinates of the box. It defaults to 0. 8109 8110@item width, w 8111@item height, h 8112The expressions which specify the width and height of the box; if 0 they are interpreted as 8113the input width and height. It defaults to 0. 8114 8115@item color, c 8116Specify the color of the box to write. For the general syntax of this option, 8117check the @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}. If the special 8118value @code{invert} is used, the box edge color is the same as the 8119video with inverted luma. 8120 8121@item thickness, t 8122The expression which sets the thickness of the box edge. 8123A value of @code{fill} will create a filled box. Default value is @code{3}. 8124 8125See below for the list of accepted constants. 8126 8127@item replace 8128Applicable if the input has alpha. With value @code{1}, the pixels of the painted box 8129will overwrite the video's color and alpha pixels. 8130Default is @code{0}, which composites the box onto the input, leaving the video's alpha intact. 8131@end table 8132 8133The parameters for @var{x}, @var{y}, @var{w} and @var{h} and @var{t} are expressions containing the 8134following constants: 8135 8136@table @option 8137@item dar 8138The input display aspect ratio, it is the same as (@var{w} / @var{h}) * @var{sar}. 8139 8140@item hsub 8141@item vsub 8142horizontal and vertical chroma subsample values. For example for the 8143pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1. 8144 8145@item in_h, ih 8146@item in_w, iw 8147The input width and height. 8148 8149@item sar 8150The input sample aspect ratio. 8151 8152@item x 8153@item y 8154The x and y offset coordinates where the box is drawn. 8155 8156@item w 8157@item h 8158The width and height of the drawn box. 8159 8160@item t 8161The thickness of the drawn box. 8162 8163These constants allow the @var{x}, @var{y}, @var{w}, @var{h} and @var{t} expressions to refer to 8164each other, so you may for example specify @code{y=x/dar} or @code{h=w/dar}. 8165 8166@end table 8167 8168@subsection Examples 8169 8170@itemize 8171@item 8172Draw a black box around the edge of the input image: 8173@example 8174drawbox 8175@end example 8176 8177@item 8178Draw a box with color red and an opacity of 50%: 8179@example 8180drawbox=10:20:200:60:red@@0.5 8181@end example 8182 8183The previous example can be specified as: 8184@example 8185drawbox=x=10:y=20:w=200:h=60:color=red@@0.5 8186@end example 8187 8188@item 8189Fill the box with pink color: 8190@example 8191drawbox=x=10:y=10:w=100:h=100:color=pink@@0.5:t=fill 8192@end example 8193 8194@item 8195Draw a 2-pixel red 2.40:1 mask: 8196@example 8197drawbox=x=-t:y=0.5*(ih-iw/2.4)-t:w=iw+t*2:h=iw/2.4+t*2:t=2:c=red 8198@end example 8199@end itemize 8200 8201@section drawgrid 8202 8203Draw a grid on the input image. 8204 8205It accepts the following parameters: 8206 8207@table @option 8208@item x 8209@item y 8210The expressions which specify the coordinates of some point of grid intersection (meant to configure offset). Both default to 0. 8211 8212@item width, w 8213@item height, h 8214The expressions which specify the width and height of the grid cell, if 0 they are interpreted as the 8215input width and height, respectively, minus @code{thickness}, so image gets 8216framed. Default to 0. 8217 8218@item color, c 8219Specify the color of the grid. For the general syntax of this option, 8220check the @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}. If the special 8221value @code{invert} is used, the grid color is the same as the 8222video with inverted luma. 8223 8224@item thickness, t 8225The expression which sets the thickness of the grid line. Default value is @code{1}. 8226 8227See below for the list of accepted constants. 8228 8229@item replace 8230Applicable if the input has alpha. With @code{1} the pixels of the painted grid 8231will overwrite the video's color and alpha pixels. 8232Default is @code{0}, which composites the grid onto the input, leaving the video's alpha intact. 8233@end table 8234 8235The parameters for @var{x}, @var{y}, @var{w} and @var{h} and @var{t} are expressions containing the 8236following constants: 8237 8238@table @option 8239@item dar 8240The input display aspect ratio, it is the same as (@var{w} / @var{h}) * @var{sar}. 8241 8242@item hsub 8243@item vsub 8244horizontal and vertical chroma subsample values. For example for the 8245pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1. 8246 8247@item in_h, ih 8248@item in_w, iw 8249The input grid cell width and height. 8250 8251@item sar 8252The input sample aspect ratio. 8253 8254@item x 8255@item y 8256The x and y coordinates of some point of grid intersection (meant to configure offset). 8257 8258@item w 8259@item h 8260The width and height of the drawn cell. 8261 8262@item t 8263The thickness of the drawn cell. 8264 8265These constants allow the @var{x}, @var{y}, @var{w}, @var{h} and @var{t} expressions to refer to 8266each other, so you may for example specify @code{y=x/dar} or @code{h=w/dar}. 8267 8268@end table 8269 8270@subsection Examples 8271 8272@itemize 8273@item 8274Draw a grid with cell 100x100 pixels, thickness 2 pixels, with color red and an opacity of 50%: 8275@example 8276drawgrid=width=100:height=100:thickness=2:color=red@@0.5 8277@end example 8278 8279@item 8280Draw a white 3x3 grid with an opacity of 50%: 8281@example 8282drawgrid=w=iw/3:h=ih/3:t=2:c=white@@0.5 8283@end example 8284@end itemize 8285 8286@anchor{drawtext} 8287@section drawtext 8288 8289Draw a text string or text from a specified file on top of a video, using the 8290libfreetype library. 8291 8292To enable compilation of this filter, you need to configure FFmpeg with 8293@code{--enable-libfreetype}. 8294To enable default font fallback and the @var{font} option you need to 8295configure FFmpeg with @code{--enable-libfontconfig}. 8296To enable the @var{text_shaping} option, you need to configure FFmpeg with 8297@code{--enable-libfribidi}. 8298 8299@subsection Syntax 8300 8301It accepts the following parameters: 8302 8303@table @option 8304 8305@item box 8306Used to draw a box around text using the background color. 8307The value must be either 1 (enable) or 0 (disable). 8308The default value of @var{box} is 0. 8309 8310@item boxborderw 8311Set the width of the border to be drawn around the box using @var{boxcolor}. 8312The default value of @var{boxborderw} is 0. 8313 8314@item boxcolor 8315The color to be used for drawing box around text. For the syntax of this 8316option, check the @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}. 8317 8318The default value of @var{boxcolor} is "white". 8319 8320@item line_spacing 8321Set the line spacing in pixels of the border to be drawn around the box using @var{box}. 8322The default value of @var{line_spacing} is 0. 8323 8324@item borderw 8325Set the width of the border to be drawn around the text using @var{bordercolor}. 8326The default value of @var{borderw} is 0. 8327 8328@item bordercolor 8329Set the color to be used for drawing border around text. For the syntax of this 8330option, check the @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}. 8331 8332The default value of @var{bordercolor} is "black". 8333 8334@item expansion 8335Select how the @var{text} is expanded. Can be either @code{none}, 8336@code{strftime} (deprecated) or 8337@code{normal} (default). See the @ref{drawtext_expansion, Text expansion} section 8338below for details. 8339 8340@item basetime 8341Set a start time for the count. Value is in microseconds. Only applied 8342in the deprecated strftime expansion mode. To emulate in normal expansion 8343mode use the @code{pts} function, supplying the start time (in seconds) 8344as the second argument. 8345 8346@item fix_bounds 8347If true, check and fix text coords to avoid clipping. 8348 8349@item fontcolor 8350The color to be used for drawing fonts. For the syntax of this option, check 8351the @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}. 8352 8353The default value of @var{fontcolor} is "black". 8354 8355@item fontcolor_expr 8356String which is expanded the same way as @var{text} to obtain dynamic 8357@var{fontcolor} value. By default this option has empty value and is not 8358processed. When this option is set, it overrides @var{fontcolor} option. 8359 8360@item font 8361The font family to be used for drawing text. By default Sans. 8362 8363@item fontfile 8364The font file to be used for drawing text. The path must be included. 8365This parameter is mandatory if the fontconfig support is disabled. 8366 8367@item alpha 8368Draw the text applying alpha blending. The value can 8369be a number between 0.0 and 1.0. 8370The expression accepts the same variables @var{x, y} as well. 8371The default value is 1. 8372Please see @var{fontcolor_expr}. 8373 8374@item fontsize 8375The font size to be used for drawing text. 8376The default value of @var{fontsize} is 16. 8377 8378@item text_shaping 8379If set to 1, attempt to shape the text (for example, reverse the order of 8380right-to-left text and join Arabic characters) before drawing it. 8381Otherwise, just draw the text exactly as given. 8382By default 1 (if supported). 8383 8384@item ft_load_flags 8385The flags to be used for loading the fonts. 8386 8387The flags map the corresponding flags supported by libfreetype, and are 8388a combination of the following values: 8389@table @var 8390@item default 8391@item no_scale 8392@item no_hinting 8393@item render 8394@item no_bitmap 8395@item vertical_layout 8396@item force_autohint 8397@item crop_bitmap 8398@item pedantic 8399@item ignore_global_advance_width 8400@item no_recurse 8401@item ignore_transform 8402@item monochrome 8403@item linear_design 8404@item no_autohint 8405@end table 8406 8407Default value is "default". 8408 8409For more information consult the documentation for the FT_LOAD_* 8410libfreetype flags. 8411 8412@item shadowcolor 8413The color to be used for drawing a shadow behind the drawn text. For the 8414syntax of this option, check the @ref{color syntax,,"Color" section in the 8415ffmpeg-utils manual,ffmpeg-utils}. 8416 8417The default value of @var{shadowcolor} is "black". 8418 8419@item shadowx 8420@item shadowy 8421The x and y offsets for the text shadow position with respect to the 8422position of the text. They can be either positive or negative 8423values. The default value for both is "0". 8424 8425@item start_number 8426The starting frame number for the n/frame_num variable. The default value 8427is "0". 8428 8429@item tabsize 8430The size in number of spaces to use for rendering the tab. 8431Default value is 4. 8432 8433@item timecode 8434Set the initial timecode representation in "hh:mm:ss[:;.]ff" 8435format. It can be used with or without text parameter. @var{timecode_rate} 8436option must be specified. 8437 8438@item timecode_rate, rate, r 8439Set the timecode frame rate (timecode only). Value will be rounded to nearest 8440integer. Minimum value is "1". 8441Drop-frame timecode is supported for frame rates 30 & 60. 8442 8443@item tc24hmax 8444If set to 1, the output of the timecode option will wrap around at 24 hours. 8445Default is 0 (disabled). 8446 8447@item text 8448The text string to be drawn. The text must be a sequence of UTF-8 8449encoded characters. 8450This parameter is mandatory if no file is specified with the parameter 8451@var{textfile}. 8452 8453@item textfile 8454A text file containing text to be drawn. The text must be a sequence 8455of UTF-8 encoded characters. 8456 8457This parameter is mandatory if no text string is specified with the 8458parameter @var{text}. 8459 8460If both @var{text} and @var{textfile} are specified, an error is thrown. 8461 8462@item reload 8463If set to 1, the @var{textfile} will be reloaded before each frame. 8464Be sure to update it atomically, or it may be read partially, or even fail. 8465 8466@item x 8467@item y 8468The expressions which specify the offsets where text will be drawn 8469within the video frame. They are relative to the top/left border of the 8470output image. 8471 8472The default value of @var{x} and @var{y} is "0". 8473 8474See below for the list of accepted constants and functions. 8475@end table 8476 8477The parameters for @var{x} and @var{y} are expressions containing the 8478following constants and functions: 8479 8480@table @option 8481@item dar 8482input display aspect ratio, it is the same as (@var{w} / @var{h}) * @var{sar} 8483 8484@item hsub 8485@item vsub 8486horizontal and vertical chroma subsample values. For example for the 8487pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1. 8488 8489@item line_h, lh 8490the height of each text line 8491 8492@item main_h, h, H 8493the input height 8494 8495@item main_w, w, W 8496the input width 8497 8498@item max_glyph_a, ascent 8499the maximum distance from the baseline to the highest/upper grid 8500coordinate used to place a glyph outline point, for all the rendered 8501glyphs. 8502It is a positive value, due to the grid's orientation with the Y axis 8503upwards. 8504 8505@item max_glyph_d, descent 8506the maximum distance from the baseline to the lowest grid coordinate 8507used to place a glyph outline point, for all the rendered glyphs. 8508This is a negative value, due to the grid's orientation, with the Y axis 8509upwards. 8510 8511@item max_glyph_h 8512maximum glyph height, that is the maximum height for all the glyphs 8513contained in the rendered text, it is equivalent to @var{ascent} - 8514@var{descent}. 8515 8516@item max_glyph_w 8517maximum glyph width, that is the maximum width for all the glyphs 8518contained in the rendered text 8519 8520@item n 8521the number of input frame, starting from 0 8522 8523@item rand(min, max) 8524return a random number included between @var{min} and @var{max} 8525 8526@item sar 8527The input sample aspect ratio. 8528 8529@item t 8530timestamp expressed in seconds, NAN if the input timestamp is unknown 8531 8532@item text_h, th 8533the height of the rendered text 8534 8535@item text_w, tw 8536the width of the rendered text 8537 8538@item x 8539@item y 8540the x and y offset coordinates where the text is drawn. 8541 8542These parameters allow the @var{x} and @var{y} expressions to refer 8543each other, so you can for example specify @code{y=x/dar}. 8544@end table 8545 8546@anchor{drawtext_expansion} 8547@subsection Text expansion 8548 8549If @option{expansion} is set to @code{strftime}, 8550the filter recognizes strftime() sequences in the provided text and 8551expands them accordingly. Check the documentation of strftime(). This 8552feature is deprecated. 8553 8554If @option{expansion} is set to @code{none}, the text is printed verbatim. 8555 8556If @option{expansion} is set to @code{normal} (which is the default), 8557the following expansion mechanism is used. 8558 8559The backslash character @samp{\}, followed by any character, always expands to 8560the second character. 8561 8562Sequences of the form @code{%@{...@}} are expanded. The text between the 8563braces is a function name, possibly followed by arguments separated by ':'. 8564If the arguments contain special characters or delimiters (':' or '@}'), 8565they should be escaped. 8566 8567Note that they probably must also be escaped as the value for the 8568@option{text} option in the filter argument string and as the filter 8569argument in the filtergraph description, and possibly also for the shell, 8570that makes up to four levels of escaping; using a text file avoids these 8571problems. 8572 8573The following functions are available: 8574 8575@table @command 8576 8577@item expr, e 8578The expression evaluation result. 8579 8580It must take one argument specifying the expression to be evaluated, 8581which accepts the same constants and functions as the @var{x} and 8582@var{y} values. Note that not all constants should be used, for 8583example the text size is not known when evaluating the expression, so 8584the constants @var{text_w} and @var{text_h} will have an undefined 8585value. 8586 8587@item expr_int_format, eif 8588Evaluate the expression's value and output as formatted integer. 8589 8590The first argument is the expression to be evaluated, just as for the @var{expr} function. 8591The second argument specifies the output format. Allowed values are @samp{x}, 8592@samp{X}, @samp{d} and @samp{u}. They are treated exactly as in the 8593@code{printf} function. 8594The third parameter is optional and sets the number of positions taken by the output. 8595It can be used to add padding with zeros from the left. 8596 8597@item gmtime 8598The time at which the filter is running, expressed in UTC. 8599It can accept an argument: a strftime() format string. 8600 8601@item localtime 8602The time at which the filter is running, expressed in the local time zone. 8603It can accept an argument: a strftime() format string. 8604 8605@item metadata 8606Frame metadata. Takes one or two arguments. 8607 8608The first argument is mandatory and specifies the metadata key. 8609 8610The second argument is optional and specifies a default value, used when the 8611metadata key is not found or empty. 8612 8613@item n, frame_num 8614The frame number, starting from 0. 8615 8616@item pict_type 8617A 1 character description of the current picture type. 8618 8619@item pts 8620The timestamp of the current frame. 8621It can take up to three arguments. 8622 8623The first argument is the format of the timestamp; it defaults to @code{flt} 8624for seconds as a decimal number with microsecond accuracy; @code{hms} stands 8625for a formatted @var{[-]HH:MM:SS.mmm} timestamp with millisecond accuracy. 8626@code{gmtime} stands for the timestamp of the frame formatted as UTC time; 8627@code{localtime} stands for the timestamp of the frame formatted as 8628local time zone time. 8629 8630The second argument is an offset added to the timestamp. 8631 8632If the format is set to @code{hms}, a third argument @code{24HH} may be 8633supplied to present the hour part of the formatted timestamp in 24h format 8634(00-23). 8635 8636If the format is set to @code{localtime} or @code{gmtime}, 8637a third argument may be supplied: a strftime() format string. 8638By default, @var{YYYY-MM-DD HH:MM:SS} format will be used. 8639@end table 8640 8641@subsection Examples 8642 8643@itemize 8644@item 8645Draw "Test Text" with font FreeSerif, using the default values for the 8646optional parameters. 8647 8648@example 8649drawtext="fontfile=/usr/share/fonts/truetype/freefont/FreeSerif.ttf: text='Test Text'" 8650@end example 8651 8652@item 8653Draw 'Test Text' with font FreeSerif of size 24 at position x=100 8654and y=50 (counting from the top-left corner of the screen), text is 8655yellow with a red box around it. Both the text and the box have an 8656opacity of 20%. 8657 8658@example 8659drawtext="fontfile=/usr/share/fonts/truetype/freefont/FreeSerif.ttf: text='Test Text':\ 8660 x=100: y=50: fontsize=24: fontcolor=yellow@@0.2: box=1: boxcolor=red@@0.2" 8661@end example 8662 8663Note that the double quotes are not necessary if spaces are not used 8664within the parameter list. 8665 8666@item 8667Show the text at the center of the video frame: 8668@example 8669drawtext="fontsize=30:fontfile=FreeSerif.ttf:text='hello world':x=(w-text_w)/2:y=(h-text_h)/2" 8670@end example 8671 8672@item 8673Show the text at a random position, switching to a new position every 30 seconds: 8674@example 8675drawtext="fontsize=30:fontfile=FreeSerif.ttf:text='hello world':x=if(eq(mod(t\,30)\,0)\,rand(0\,(w-text_w))\,x):y=if(eq(mod(t\,30)\,0)\,rand(0\,(h-text_h))\,y)" 8676@end example 8677 8678@item 8679Show a text line sliding from right to left in the last row of the video 8680frame. The file @file{LONG_LINE} is assumed to contain a single line 8681with no newlines. 8682@example 8683drawtext="fontsize=15:fontfile=FreeSerif.ttf:text=LONG_LINE:y=h-line_h:x=-50*t" 8684@end example 8685 8686@item 8687Show the content of file @file{CREDITS} off the bottom of the frame and scroll up. 8688@example 8689drawtext="fontsize=20:fontfile=FreeSerif.ttf:textfile=CREDITS:y=h-20*t" 8690@end example 8691 8692@item 8693Draw a single green letter "g", at the center of the input video. 8694The glyph baseline is placed at half screen height. 8695@example 8696drawtext="fontsize=60:fontfile=FreeSerif.ttf:fontcolor=green:text=g:x=(w-max_glyph_w)/2:y=h/2-ascent" 8697@end example 8698 8699@item 8700Show text for 1 second every 3 seconds: 8701@example 8702drawtext="fontfile=FreeSerif.ttf:fontcolor=white:x=100:y=x/dar:enable=lt(mod(t\,3)\,1):text='blink'" 8703@end example 8704 8705@item 8706Use fontconfig to set the font. Note that the colons need to be escaped. 8707@example 8708drawtext='fontfile=Linux Libertine O-40\:style=Semibold:text=FFmpeg' 8709@end example 8710 8711@item 8712Print the date of a real-time encoding (see strftime(3)): 8713@example 8714drawtext='fontfile=FreeSans.ttf:text=%@{localtime\:%a %b %d %Y@}' 8715@end example 8716 8717@item 8718Show text fading in and out (appearing/disappearing): 8719@example 8720#!/bin/sh 8721DS=1.0 # display start 8722DE=10.0 # display end 8723FID=1.5 # fade in duration 8724FOD=5 # fade out duration 8725ffplay -f lavfi "color,drawtext=text=TEST:fontsize=50:fontfile=FreeSerif.ttf:fontcolor_expr=ff0000%@{eif\\\\: clip(255*(1*between(t\\, $DS + $FID\\, $DE - $FOD) + ((t - $DS)/$FID)*between(t\\, $DS\\, $DS + $FID) + (-(t - $DE)/$FOD)*between(t\\, $DE - $FOD\\, $DE) )\\, 0\\, 255) \\\\: x\\\\: 2 @}" 8726@end example 8727 8728@item 8729Horizontally align multiple separate texts. Note that @option{max_glyph_a} 8730and the @option{fontsize} value are included in the @option{y} offset. 8731@example 8732drawtext=fontfile=FreeSans.ttf:text=DOG:fontsize=24:x=10:y=20+24-max_glyph_a, 8733drawtext=fontfile=FreeSans.ttf:text=cow:fontsize=24:x=80:y=20+24-max_glyph_a 8734@end example 8735 8736@end itemize 8737 8738For more information about libfreetype, check: 8739@url{http://www.freetype.org/}. 8740 8741For more information about fontconfig, check: 8742@url{http://freedesktop.org/software/fontconfig/fontconfig-user.html}. 8743 8744For more information about libfribidi, check: 8745@url{http://fribidi.org/}. 8746 8747@section edgedetect 8748 8749Detect and draw edges. The filter uses the Canny Edge Detection algorithm. 8750 8751The filter accepts the following options: 8752 8753@table @option 8754@item low 8755@item high 8756Set low and high threshold values used by the Canny thresholding 8757algorithm. 8758 8759The high threshold selects the "strong" edge pixels, which are then 8760connected through 8-connectivity with the "weak" edge pixels selected 8761by the low threshold. 8762 8763@var{low} and @var{high} threshold values must be chosen in the range 8764[0,1], and @var{low} should be lesser or equal to @var{high}. 8765 8766Default value for @var{low} is @code{20/255}, and default value for @var{high} 8767is @code{50/255}. 8768 8769@item mode 8770Define the drawing mode. 8771 8772@table @samp 8773@item wires 8774Draw white/gray wires on black background. 8775 8776@item colormix 8777Mix the colors to create a paint/cartoon effect. 8778 8779@item canny 8780Apply Canny edge detector on all selected planes. 8781@end table 8782Default value is @var{wires}. 8783 8784@item planes 8785Select planes for filtering. By default all available planes are filtered. 8786@end table 8787 8788@subsection Examples 8789 8790@itemize 8791@item 8792Standard edge detection with custom values for the hysteresis thresholding: 8793@example 8794edgedetect=low=0.1:high=0.4 8795@end example 8796 8797@item 8798Painting effect without thresholding: 8799@example 8800edgedetect=mode=colormix:high=0 8801@end example 8802@end itemize 8803 8804@section eq 8805Set brightness, contrast, saturation and approximate gamma adjustment. 8806 8807The filter accepts the following options: 8808 8809@table @option 8810@item contrast 8811Set the contrast expression. The value must be a float value in range 8812@code{-2.0} to @code{2.0}. The default value is "1". 8813 8814@item brightness 8815Set the brightness expression. The value must be a float value in 8816range @code{-1.0} to @code{1.0}. The default value is "0". 8817 8818@item saturation 8819Set the saturation expression. The value must be a float in 8820range @code{0.0} to @code{3.0}. The default value is "1". 8821 8822@item gamma 8823Set the gamma expression. The value must be a float in range 8824@code{0.1} to @code{10.0}. The default value is "1". 8825 8826@item gamma_r 8827Set the gamma expression for red. The value must be a float in 8828range @code{0.1} to @code{10.0}. The default value is "1". 8829 8830@item gamma_g 8831Set the gamma expression for green. The value must be a float in range 8832@code{0.1} to @code{10.0}. The default value is "1". 8833 8834@item gamma_b 8835Set the gamma expression for blue. The value must be a float in range 8836@code{0.1} to @code{10.0}. The default value is "1". 8837 8838@item gamma_weight 8839Set the gamma weight expression. It can be used to reduce the effect 8840of a high gamma value on bright image areas, e.g. keep them from 8841getting overamplified and just plain white. The value must be a float 8842in range @code{0.0} to @code{1.0}. A value of @code{0.0} turns the 8843gamma correction all the way down while @code{1.0} leaves it at its 8844full strength. Default is "1". 8845 8846@item eval 8847Set when the expressions for brightness, contrast, saturation and 8848gamma expressions are evaluated. 8849 8850It accepts the following values: 8851@table @samp 8852@item init 8853only evaluate expressions once during the filter initialization or 8854when a command is processed 8855 8856@item frame 8857evaluate expressions for each incoming frame 8858@end table 8859 8860Default value is @samp{init}. 8861@end table 8862 8863The expressions accept the following parameters: 8864@table @option 8865@item n 8866frame count of the input frame starting from 0 8867 8868@item pos 8869byte position of the corresponding packet in the input file, NAN if 8870unspecified 8871 8872@item r 8873frame rate of the input video, NAN if the input frame rate is unknown 8874 8875@item t 8876timestamp expressed in seconds, NAN if the input timestamp is unknown 8877@end table 8878 8879@subsection Commands 8880The filter supports the following commands: 8881 8882@table @option 8883@item contrast 8884Set the contrast expression. 8885 8886@item brightness 8887Set the brightness expression. 8888 8889@item saturation 8890Set the saturation expression. 8891 8892@item gamma 8893Set the gamma expression. 8894 8895@item gamma_r 8896Set the gamma_r expression. 8897 8898@item gamma_g 8899Set gamma_g expression. 8900 8901@item gamma_b 8902Set gamma_b expression. 8903 8904@item gamma_weight 8905Set gamma_weight expression. 8906 8907The command accepts the same syntax of the corresponding option. 8908 8909If the specified expression is not valid, it is kept at its current 8910value. 8911 8912@end table 8913 8914@section erosion 8915 8916Apply erosion effect to the video. 8917 8918This filter replaces the pixel by the local(3x3) minimum. 8919 8920It accepts the following options: 8921 8922@table @option 8923@item threshold0 8924@item threshold1 8925@item threshold2 8926@item threshold3 8927Limit the maximum change for each plane, default is 65535. 8928If 0, plane will remain unchanged. 8929 8930@item coordinates 8931Flag which specifies the pixel to refer to. Default is 255 i.e. all eight 8932pixels are used. 8933 8934Flags to local 3x3 coordinates maps like this: 8935 8936 1 2 3 8937 4 5 8938 6 7 8 8939@end table 8940 8941@section extractplanes 8942 8943Extract color channel components from input video stream into 8944separate grayscale video streams. 8945 8946The filter accepts the following option: 8947 8948@table @option 8949@item planes 8950Set plane(s) to extract. 8951 8952Available values for planes are: 8953@table @samp 8954@item y 8955@item u 8956@item v 8957@item a 8958@item r 8959@item g 8960@item b 8961@end table 8962 8963Choosing planes not available in the input will result in an error. 8964That means you cannot select @code{r}, @code{g}, @code{b} planes 8965with @code{y}, @code{u}, @code{v} planes at same time. 8966@end table 8967 8968@subsection Examples 8969 8970@itemize 8971@item 8972Extract luma, u and v color channel component from input video frame 8973into 3 grayscale outputs: 8974@example 8975ffmpeg -i video.avi -filter_complex 'extractplanes=y+u+v[y][u][v]' -map '[y]' y.avi -map '[u]' u.avi -map '[v]' v.avi 8976@end example 8977@end itemize 8978 8979@section elbg 8980 8981Apply a posterize effect using the ELBG (Enhanced LBG) algorithm. 8982 8983For each input image, the filter will compute the optimal mapping from 8984the input to the output given the codebook length, that is the number 8985of distinct output colors. 8986 8987This filter accepts the following options. 8988 8989@table @option 8990@item codebook_length, l 8991Set codebook length. The value must be a positive integer, and 8992represents the number of distinct output colors. Default value is 256. 8993 8994@item nb_steps, n 8995Set the maximum number of iterations to apply for computing the optimal 8996mapping. The higher the value the better the result and the higher the 8997computation time. Default value is 1. 8998 8999@item seed, s 9000Set a random seed, must be an integer included between 0 and 9001UINT32_MAX. If not specified, or if explicitly set to -1, the filter 9002will try to use a good random seed on a best effort basis. 9003 9004@item pal8 9005Set pal8 output pixel format. This option does not work with codebook 9006length greater than 256. 9007@end table 9008 9009@section entropy 9010 9011Measure graylevel entropy in histogram of color channels of video frames. 9012 9013It accepts the following parameters: 9014 9015@table @option 9016@item mode 9017Can be either @var{normal} or @var{diff}. Default is @var{normal}. 9018 9019@var{diff} mode measures entropy of histogram delta values, absolute differences 9020between neighbour histogram values. 9021@end table 9022 9023@section fade 9024 9025Apply a fade-in/out effect to the input video. 9026 9027It accepts the following parameters: 9028 9029@table @option 9030@item type, t 9031The effect type can be either "in" for a fade-in, or "out" for a fade-out 9032effect. 9033Default is @code{in}. 9034 9035@item start_frame, s 9036Specify the number of the frame to start applying the fade 9037effect at. Default is 0. 9038 9039@item nb_frames, n 9040The number of frames that the fade effect lasts. At the end of the 9041fade-in effect, the output video will have the same intensity as the input video. 9042At the end of the fade-out transition, the output video will be filled with the 9043selected @option{color}. 9044Default is 25. 9045 9046@item alpha 9047If set to 1, fade only alpha channel, if one exists on the input. 9048Default value is 0. 9049 9050@item start_time, st 9051Specify the timestamp (in seconds) of the frame to start to apply the fade 9052effect. If both start_frame and start_time are specified, the fade will start at 9053whichever comes last. Default is 0. 9054 9055@item duration, d 9056The number of seconds for which the fade effect has to last. At the end of the 9057fade-in effect the output video will have the same intensity as the input video, 9058at the end of the fade-out transition the output video will be filled with the 9059selected @option{color}. 9060If both duration and nb_frames are specified, duration is used. Default is 0 9061(nb_frames is used by default). 9062 9063@item color, c 9064Specify the color of the fade. Default is "black". 9065@end table 9066 9067@subsection Examples 9068 9069@itemize 9070@item 9071Fade in the first 30 frames of video: 9072@example 9073fade=in:0:30 9074@end example 9075 9076The command above is equivalent to: 9077@example 9078fade=t=in:s=0:n=30 9079@end example 9080 9081@item 9082Fade out the last 45 frames of a 200-frame video: 9083@example 9084fade=out:155:45 9085fade=type=out:start_frame=155:nb_frames=45 9086@end example 9087 9088@item 9089Fade in the first 25 frames and fade out the last 25 frames of a 1000-frame video: 9090@example 9091fade=in:0:25, fade=out:975:25 9092@end example 9093 9094@item 9095Make the first 5 frames yellow, then fade in from frame 5-24: 9096@example 9097fade=in:5:20:color=yellow 9098@end example 9099 9100@item 9101Fade in alpha over first 25 frames of video: 9102@example 9103fade=in:0:25:alpha=1 9104@end example 9105 9106@item 9107Make the first 5.5 seconds black, then fade in for 0.5 seconds: 9108@example 9109fade=t=in:st=5.5:d=0.5 9110@end example 9111 9112@end itemize 9113 9114@section fftfilt 9115Apply arbitrary expressions to samples in frequency domain 9116 9117@table @option 9118@item dc_Y 9119Adjust the dc value (gain) of the luma plane of the image. The filter 9120accepts an integer value in range @code{0} to @code{1000}. The default 9121value is set to @code{0}. 9122 9123@item dc_U 9124Adjust the dc value (gain) of the 1st chroma plane of the image. The 9125filter accepts an integer value in range @code{0} to @code{1000}. The 9126default value is set to @code{0}. 9127 9128@item dc_V 9129Adjust the dc value (gain) of the 2nd chroma plane of the image. The 9130filter accepts an integer value in range @code{0} to @code{1000}. The 9131default value is set to @code{0}. 9132 9133@item weight_Y 9134Set the frequency domain weight expression for the luma plane. 9135 9136@item weight_U 9137Set the frequency domain weight expression for the 1st chroma plane. 9138 9139@item weight_V 9140Set the frequency domain weight expression for the 2nd chroma plane. 9141 9142@item eval 9143Set when the expressions are evaluated. 9144 9145It accepts the following values: 9146@table @samp 9147@item init 9148Only evaluate expressions once during the filter initialization. 9149 9150@item frame 9151Evaluate expressions for each incoming frame. 9152@end table 9153 9154Default value is @samp{init}. 9155 9156The filter accepts the following variables: 9157@item X 9158@item Y 9159The coordinates of the current sample. 9160 9161@item W 9162@item H 9163The width and height of the image. 9164 9165@item N 9166The number of input frame, starting from 0. 9167@end table 9168 9169@subsection Examples 9170 9171@itemize 9172@item 9173High-pass: 9174@example 9175fftfilt=dc_Y=128:weight_Y='squish(1-(Y+X)/100)' 9176@end example 9177 9178@item 9179Low-pass: 9180@example 9181fftfilt=dc_Y=0:weight_Y='squish((Y+X)/100-1)' 9182@end example 9183 9184@item 9185Sharpen: 9186@example 9187fftfilt=dc_Y=0:weight_Y='1+squish(1-(Y+X)/100)' 9188@end example 9189 9190@item 9191Blur: 9192@example 9193fftfilt=dc_Y=0:weight_Y='exp(-4 * ((Y+X)/(W+H)))' 9194@end example 9195 9196@end itemize 9197 9198@section fftdnoiz 9199Denoise frames using 3D FFT (frequency domain filtering). 9200 9201The filter accepts the following options: 9202 9203@table @option 9204@item sigma 9205Set the noise sigma constant. This sets denoising strength. 9206Default value is 1. Allowed range is from 0 to 30. 9207Using very high sigma with low overlap may give blocking artifacts. 9208 9209@item amount 9210Set amount of denoising. By default all detected noise is reduced. 9211Default value is 1. Allowed range is from 0 to 1. 9212 9213@item block 9214Set size of block, Default is 4, can be 3, 4, 5 or 6. 9215Actual size of block in pixels is 2 to power of @var{block}, so by default 9216block size in pixels is 2^4 which is 16. 9217 9218@item overlap 9219Set block overlap. Default is 0.5. Allowed range is from 0.2 to 0.8. 9220 9221@item prev 9222Set number of previous frames to use for denoising. By default is set to 0. 9223 9224@item next 9225Set number of next frames to to use for denoising. By default is set to 0. 9226 9227@item planes 9228Set planes which will be filtered, by default are all available filtered 9229except alpha. 9230@end table 9231 9232@section field 9233 9234Extract a single field from an interlaced image using stride 9235arithmetic to avoid wasting CPU time. The output frames are marked as 9236non-interlaced. 9237 9238The filter accepts the following options: 9239 9240@table @option 9241@item type 9242Specify whether to extract the top (if the value is @code{0} or 9243@code{top}) or the bottom field (if the value is @code{1} or 9244@code{bottom}). 9245@end table 9246 9247@section fieldhint 9248 9249Create new frames by copying the top and bottom fields from surrounding frames 9250supplied as numbers by the hint file. 9251 9252@table @option 9253@item hint 9254Set file containing hints: absolute/relative frame numbers. 9255 9256There must be one line for each frame in a clip. Each line must contain two 9257numbers separated by the comma, optionally followed by @code{-} or @code{+}. 9258Numbers supplied on each line of file can not be out of [N-1,N+1] where N 9259is current frame number for @code{absolute} mode or out of [-1, 1] range 9260for @code{relative} mode. First number tells from which frame to pick up top 9261field and second number tells from which frame to pick up bottom field. 9262 9263If optionally followed by @code{+} output frame will be marked as interlaced, 9264else if followed by @code{-} output frame will be marked as progressive, else 9265it will be marked same as input frame. 9266If line starts with @code{#} or @code{;} that line is skipped. 9267 9268@item mode 9269Can be item @code{absolute} or @code{relative}. Default is @code{absolute}. 9270@end table 9271 9272Example of first several lines of @code{hint} file for @code{relative} mode: 9273@example 92740,0 - # first frame 92751,0 - # second frame, use third's frame top field and second's frame bottom field 92761,0 - # third frame, use fourth's frame top field and third's frame bottom field 92771,0 - 92780,0 - 92790,0 - 92801,0 - 92811,0 - 92821,0 - 92830,0 - 92840,0 - 92851,0 - 92861,0 - 92871,0 - 92880,0 - 9289@end example 9290 9291@section fieldmatch 9292 9293Field matching filter for inverse telecine. It is meant to reconstruct the 9294progressive frames from a telecined stream. The filter does not drop duplicated 9295frames, so to achieve a complete inverse telecine @code{fieldmatch} needs to be 9296followed by a decimation filter such as @ref{decimate} in the filtergraph. 9297 9298The separation of the field matching and the decimation is notably motivated by 9299the possibility of inserting a de-interlacing filter fallback between the two. 9300If the source has mixed telecined and real interlaced content, 9301@code{fieldmatch} will not be able to match fields for the interlaced parts. 9302But these remaining combed frames will be marked as interlaced, and thus can be 9303de-interlaced by a later filter such as @ref{yadif} before decimation. 9304 9305In addition to the various configuration options, @code{fieldmatch} can take an 9306optional second stream, activated through the @option{ppsrc} option. If 9307enabled, the frames reconstruction will be based on the fields and frames from 9308this second stream. This allows the first input to be pre-processed in order to 9309help the various algorithms of the filter, while keeping the output lossless 9310(assuming the fields are matched properly). Typically, a field-aware denoiser, 9311or brightness/contrast adjustments can help. 9312 9313Note that this filter uses the same algorithms as TIVTC/TFM (AviSynth project) 9314and VIVTC/VFM (VapourSynth project). The later is a light clone of TFM from 9315which @code{fieldmatch} is based on. While the semantic and usage are very 9316close, some behaviour and options names can differ. 9317 9318The @ref{decimate} filter currently only works for constant frame rate input. 9319If your input has mixed telecined (30fps) and progressive content with a lower 9320framerate like 24fps use the following filterchain to produce the necessary cfr 9321stream: @code{dejudder,fps=30000/1001,fieldmatch,decimate}. 9322 9323The filter accepts the following options: 9324 9325@table @option 9326@item order 9327Specify the assumed field order of the input stream. Available values are: 9328 9329@table @samp 9330@item auto 9331Auto detect parity (use FFmpeg's internal parity value). 9332@item bff 9333Assume bottom field first. 9334@item tff 9335Assume top field first. 9336@end table 9337 9338Note that it is sometimes recommended not to trust the parity announced by the 9339stream. 9340 9341Default value is @var{auto}. 9342 9343@item mode 9344Set the matching mode or strategy to use. @option{pc} mode is the safest in the 9345sense that it won't risk creating jerkiness due to duplicate frames when 9346possible, but if there are bad edits or blended fields it will end up 9347outputting combed frames when a good match might actually exist. On the other 9348hand, @option{pcn_ub} mode is the most risky in terms of creating jerkiness, 9349but will almost always find a good frame if there is one. The other values are 9350all somewhere in between @option{pc} and @option{pcn_ub} in terms of risking 9351jerkiness and creating duplicate frames versus finding good matches in sections 9352with bad edits, orphaned fields, blended fields, etc. 9353 9354More details about p/c/n/u/b are available in @ref{p/c/n/u/b meaning} section. 9355 9356Available values are: 9357 9358@table @samp 9359@item pc 93602-way matching (p/c) 9361@item pc_n 93622-way matching, and trying 3rd match if still combed (p/c + n) 9363@item pc_u 93642-way matching, and trying 3rd match (same order) if still combed (p/c + u) 9365@item pc_n_ub 93662-way matching, trying 3rd match if still combed, and trying 4th/5th matches if 9367still combed (p/c + n + u/b) 9368@item pcn 93693-way matching (p/c/n) 9370@item pcn_ub 93713-way matching, and trying 4th/5th matches if all 3 of the original matches are 9372detected as combed (p/c/n + u/b) 9373@end table 9374 9375The parenthesis at the end indicate the matches that would be used for that 9376mode assuming @option{order}=@var{tff} (and @option{field} on @var{auto} or 9377@var{top}). 9378 9379In terms of speed @option{pc} mode is by far the fastest and @option{pcn_ub} is 9380the slowest. 9381 9382Default value is @var{pc_n}. 9383 9384@item ppsrc 9385Mark the main input stream as a pre-processed input, and enable the secondary 9386input stream as the clean source to pick the fields from. See the filter 9387introduction for more details. It is similar to the @option{clip2} feature from 9388VFM/TFM. 9389 9390Default value is @code{0} (disabled). 9391 9392@item field 9393Set the field to match from. It is recommended to set this to the same value as 9394@option{order} unless you experience matching failures with that setting. In 9395certain circumstances changing the field that is used to match from can have a 9396large impact on matching performance. Available values are: 9397 9398@table @samp 9399@item auto 9400Automatic (same value as @option{order}). 9401@item bottom 9402Match from the bottom field. 9403@item top 9404Match from the top field. 9405@end table 9406 9407Default value is @var{auto}. 9408 9409@item mchroma 9410Set whether or not chroma is included during the match comparisons. In most 9411cases it is recommended to leave this enabled. You should set this to @code{0} 9412only if your clip has bad chroma problems such as heavy rainbowing or other 9413artifacts. Setting this to @code{0} could also be used to speed things up at 9414the cost of some accuracy. 9415 9416Default value is @code{1}. 9417 9418@item y0 9419@item y1 9420These define an exclusion band which excludes the lines between @option{y0} and 9421@option{y1} from being included in the field matching decision. An exclusion 9422band can be used to ignore subtitles, a logo, or other things that may 9423interfere with the matching. @option{y0} sets the starting scan line and 9424@option{y1} sets the ending line; all lines in between @option{y0} and 9425@option{y1} (including @option{y0} and @option{y1}) will be ignored. Setting 9426@option{y0} and @option{y1} to the same value will disable the feature. 9427@option{y0} and @option{y1} defaults to @code{0}. 9428 9429@item scthresh 9430Set the scene change detection threshold as a percentage of maximum change on 9431the luma plane. Good values are in the @code{[8.0, 14.0]} range. Scene change 9432detection is only relevant in case @option{combmatch}=@var{sc}. The range for 9433@option{scthresh} is @code{[0.0, 100.0]}. 9434 9435Default value is @code{12.0}. 9436 9437@item combmatch 9438When @option{combatch} is not @var{none}, @code{fieldmatch} will take into 9439account the combed scores of matches when deciding what match to use as the 9440final match. Available values are: 9441 9442@table @samp 9443@item none 9444No final matching based on combed scores. 9445@item sc 9446Combed scores are only used when a scene change is detected. 9447@item full 9448Use combed scores all the time. 9449@end table 9450 9451Default is @var{sc}. 9452 9453@item combdbg 9454Force @code{fieldmatch} to calculate the combed metrics for certain matches and 9455print them. This setting is known as @option{micout} in TFM/VFM vocabulary. 9456Available values are: 9457 9458@table @samp 9459@item none 9460No forced calculation. 9461@item pcn 9462Force p/c/n calculations. 9463@item pcnub 9464Force p/c/n/u/b calculations. 9465@end table 9466 9467Default value is @var{none}. 9468 9469@item cthresh 9470This is the area combing threshold used for combed frame detection. This 9471essentially controls how "strong" or "visible" combing must be to be detected. 9472Larger values mean combing must be more visible and smaller values mean combing 9473can be less visible or strong and still be detected. Valid settings are from 9474@code{-1} (every pixel will be detected as combed) to @code{255} (no pixel will 9475be detected as combed). This is basically a pixel difference value. A good 9476range is @code{[8, 12]}. 9477 9478Default value is @code{9}. 9479 9480@item chroma 9481Sets whether or not chroma is considered in the combed frame decision. Only 9482disable this if your source has chroma problems (rainbowing, etc.) that are 9483causing problems for the combed frame detection with chroma enabled. Actually, 9484using @option{chroma}=@var{0} is usually more reliable, except for the case 9485where there is chroma only combing in the source. 9486 9487Default value is @code{0}. 9488 9489@item blockx 9490@item blocky 9491Respectively set the x-axis and y-axis size of the window used during combed 9492frame detection. This has to do with the size of the area in which 9493@option{combpel} pixels are required to be detected as combed for a frame to be 9494declared combed. See the @option{combpel} parameter description for more info. 9495Possible values are any number that is a power of 2 starting at 4 and going up 9496to 512. 9497 9498Default value is @code{16}. 9499 9500@item combpel 9501The number of combed pixels inside any of the @option{blocky} by 9502@option{blockx} size blocks on the frame for the frame to be detected as 9503combed. While @option{cthresh} controls how "visible" the combing must be, this 9504setting controls "how much" combing there must be in any localized area (a 9505window defined by the @option{blockx} and @option{blocky} settings) on the 9506frame. Minimum value is @code{0} and maximum is @code{blocky x blockx} (at 9507which point no frames will ever be detected as combed). This setting is known 9508as @option{MI} in TFM/VFM vocabulary. 9509 9510Default value is @code{80}. 9511@end table 9512 9513@anchor{p/c/n/u/b meaning} 9514@subsection p/c/n/u/b meaning 9515 9516@subsubsection p/c/n 9517 9518We assume the following telecined stream: 9519 9520@example 9521Top fields: 1 2 2 3 4 9522Bottom fields: 1 2 3 4 4 9523@end example 9524 9525The numbers correspond to the progressive frame the fields relate to. Here, the 9526first two frames are progressive, the 3rd and 4th are combed, and so on. 9527 9528When @code{fieldmatch} is configured to run a matching from bottom 9529(@option{field}=@var{bottom}) this is how this input stream get transformed: 9530 9531@example 9532Input stream: 9533 T 1 2 2 3 4 9534 B 1 2 3 4 4 <-- matching reference 9535 9536Matches: c c n n c 9537 9538Output stream: 9539 T 1 2 3 4 4 9540 B 1 2 3 4 4 9541@end example 9542 9543As a result of the field matching, we can see that some frames get duplicated. 9544To perform a complete inverse telecine, you need to rely on a decimation filter 9545after this operation. See for instance the @ref{decimate} filter. 9546 9547The same operation now matching from top fields (@option{field}=@var{top}) 9548looks like this: 9549 9550@example 9551Input stream: 9552 T 1 2 2 3 4 <-- matching reference 9553 B 1 2 3 4 4 9554 9555Matches: c c p p c 9556 9557Output stream: 9558 T 1 2 2 3 4 9559 B 1 2 2 3 4 9560@end example 9561 9562In these examples, we can see what @var{p}, @var{c} and @var{n} mean; 9563basically, they refer to the frame and field of the opposite parity: 9564 9565@itemize 9566@item @var{p} matches the field of the opposite parity in the previous frame 9567@item @var{c} matches the field of the opposite parity in the current frame 9568@item @var{n} matches the field of the opposite parity in the next frame 9569@end itemize 9570 9571@subsubsection u/b 9572 9573The @var{u} and @var{b} matching are a bit special in the sense that they match 9574from the opposite parity flag. In the following examples, we assume that we are 9575currently matching the 2nd frame (Top:2, bottom:2). According to the match, a 9576'x' is placed above and below each matched fields. 9577 9578With bottom matching (@option{field}=@var{bottom}): 9579@example 9580Match: c p n b u 9581 9582 x x x x x 9583 Top 1 2 2 1 2 2 1 2 2 1 2 2 1 2 2 9584 Bottom 1 2 3 1 2 3 1 2 3 1 2 3 1 2 3 9585 x x x x x 9586 9587Output frames: 9588 2 1 2 2 2 9589 2 2 2 1 3 9590@end example 9591 9592With top matching (@option{field}=@var{top}): 9593@example 9594Match: c p n b u 9595 9596 x x x x x 9597 Top 1 2 2 1 2 2 1 2 2 1 2 2 1 2 2 9598 Bottom 1 2 3 1 2 3 1 2 3 1 2 3 1 2 3 9599 x x x x x 9600 9601Output frames: 9602 2 2 2 1 2 9603 2 1 3 2 2 9604@end example 9605 9606@subsection Examples 9607 9608Simple IVTC of a top field first telecined stream: 9609@example 9610fieldmatch=order=tff:combmatch=none, decimate 9611@end example 9612 9613Advanced IVTC, with fallback on @ref{yadif} for still combed frames: 9614@example 9615fieldmatch=order=tff:combmatch=full, yadif=deint=interlaced, decimate 9616@end example 9617 9618@section fieldorder 9619 9620Transform the field order of the input video. 9621 9622It accepts the following parameters: 9623 9624@table @option 9625 9626@item order 9627The output field order. Valid values are @var{tff} for top field first or @var{bff} 9628for bottom field first. 9629@end table 9630 9631The default value is @samp{tff}. 9632 9633The transformation is done by shifting the picture content up or down 9634by one line, and filling the remaining line with appropriate picture content. 9635This method is consistent with most broadcast field order converters. 9636 9637If the input video is not flagged as being interlaced, or it is already 9638flagged as being of the required output field order, then this filter does 9639not alter the incoming video. 9640 9641It is very useful when converting to or from PAL DV material, 9642which is bottom field first. 9643 9644For example: 9645@example 9646ffmpeg -i in.vob -vf "fieldorder=bff" out.dv 9647@end example 9648 9649@section fifo, afifo 9650 9651Buffer input images and send them when they are requested. 9652 9653It is mainly useful when auto-inserted by the libavfilter 9654framework. 9655 9656It does not take parameters. 9657 9658@section fillborders 9659 9660Fill borders of the input video, without changing video stream dimensions. 9661Sometimes video can have garbage at the four edges and you may not want to 9662crop video input to keep size multiple of some number. 9663 9664This filter accepts the following options: 9665 9666@table @option 9667@item left 9668Number of pixels to fill from left border. 9669 9670@item right 9671Number of pixels to fill from right border. 9672 9673@item top 9674Number of pixels to fill from top border. 9675 9676@item bottom 9677Number of pixels to fill from bottom border. 9678 9679@item mode 9680Set fill mode. 9681 9682It accepts the following values: 9683@table @samp 9684@item smear 9685fill pixels using outermost pixels 9686 9687@item mirror 9688fill pixels using mirroring 9689 9690@item fixed 9691fill pixels with constant value 9692@end table 9693 9694Default is @var{smear}. 9695 9696@item color 9697Set color for pixels in fixed mode. Default is @var{black}. 9698@end table 9699 9700@section find_rect 9701 9702Find a rectangular object 9703 9704It accepts the following options: 9705 9706@table @option 9707@item object 9708Filepath of the object image, needs to be in gray8. 9709 9710@item threshold 9711Detection threshold, default is 0.5. 9712 9713@item mipmaps 9714Number of mipmaps, default is 3. 9715 9716@item xmin, ymin, xmax, ymax 9717Specifies the rectangle in which to search. 9718@end table 9719 9720@subsection Examples 9721 9722@itemize 9723@item 9724Generate a representative palette of a given video using @command{ffmpeg}: 9725@example 9726ffmpeg -i file.ts -vf find_rect=newref.pgm,cover_rect=cover.jpg:mode=cover new.mkv 9727@end example 9728@end itemize 9729 9730@section cover_rect 9731 9732Cover a rectangular object 9733 9734It accepts the following options: 9735 9736@table @option 9737@item cover 9738Filepath of the optional cover image, needs to be in yuv420. 9739 9740@item mode 9741Set covering mode. 9742 9743It accepts the following values: 9744@table @samp 9745@item cover 9746cover it by the supplied image 9747@item blur 9748cover it by interpolating the surrounding pixels 9749@end table 9750 9751Default value is @var{blur}. 9752@end table 9753 9754@subsection Examples 9755 9756@itemize 9757@item 9758Generate a representative palette of a given video using @command{ffmpeg}: 9759@example 9760ffmpeg -i file.ts -vf find_rect=newref.pgm,cover_rect=cover.jpg:mode=cover new.mkv 9761@end example 9762@end itemize 9763 9764@section floodfill 9765 9766Flood area with values of same pixel components with another values. 9767 9768It accepts the following options: 9769@table @option 9770@item x 9771Set pixel x coordinate. 9772 9773@item y 9774Set pixel y coordinate. 9775 9776@item s0 9777Set source #0 component value. 9778 9779@item s1 9780Set source #1 component value. 9781 9782@item s2 9783Set source #2 component value. 9784 9785@item s3 9786Set source #3 component value. 9787 9788@item d0 9789Set destination #0 component value. 9790 9791@item d1 9792Set destination #1 component value. 9793 9794@item d2 9795Set destination #2 component value. 9796 9797@item d3 9798Set destination #3 component value. 9799@end table 9800 9801@anchor{format} 9802@section format 9803 9804Convert the input video to one of the specified pixel formats. 9805Libavfilter will try to pick one that is suitable as input to 9806the next filter. 9807 9808It accepts the following parameters: 9809@table @option 9810 9811@item pix_fmts 9812A '|'-separated list of pixel format names, such as 9813"pix_fmts=yuv420p|monow|rgb24". 9814 9815@end table 9816 9817@subsection Examples 9818 9819@itemize 9820@item 9821Convert the input video to the @var{yuv420p} format 9822@example 9823format=pix_fmts=yuv420p 9824@end example 9825 9826Convert the input video to any of the formats in the list 9827@example 9828format=pix_fmts=yuv420p|yuv444p|yuv410p 9829@end example 9830@end itemize 9831 9832@anchor{fps} 9833@section fps 9834 9835Convert the video to specified constant frame rate by duplicating or dropping 9836frames as necessary. 9837 9838It accepts the following parameters: 9839@table @option 9840 9841@item fps 9842The desired output frame rate. The default is @code{25}. 9843 9844@item start_time 9845Assume the first PTS should be the given value, in seconds. This allows for 9846padding/trimming at the start of stream. By default, no assumption is made 9847about the first frame's expected PTS, so no padding or trimming is done. 9848For example, this could be set to 0 to pad the beginning with duplicates of 9849the first frame if a video stream starts after the audio stream or to trim any 9850frames with a negative PTS. 9851 9852@item round 9853Timestamp (PTS) rounding method. 9854 9855Possible values are: 9856@table @option 9857@item zero 9858round towards 0 9859@item inf 9860round away from 0 9861@item down 9862round towards -infinity 9863@item up 9864round towards +infinity 9865@item near 9866round to nearest 9867@end table 9868The default is @code{near}. 9869 9870@item eof_action 9871Action performed when reading the last frame. 9872 9873Possible values are: 9874@table @option 9875@item round 9876Use same timestamp rounding method as used for other frames. 9877@item pass 9878Pass through last frame if input duration has not been reached yet. 9879@end table 9880The default is @code{round}. 9881 9882@end table 9883 9884Alternatively, the options can be specified as a flat string: 9885@var{fps}[:@var{start_time}[:@var{round}]]. 9886 9887See also the @ref{setpts} filter. 9888 9889@subsection Examples 9890 9891@itemize 9892@item 9893A typical usage in order to set the fps to 25: 9894@example 9895fps=fps=25 9896@end example 9897 9898@item 9899Sets the fps to 24, using abbreviation and rounding method to round to nearest: 9900@example 9901fps=fps=film:round=near 9902@end example 9903@end itemize 9904 9905@section framepack 9906 9907Pack two different video streams into a stereoscopic video, setting proper 9908metadata on supported codecs. The two views should have the same size and 9909framerate and processing will stop when the shorter video ends. Please note 9910that you may conveniently adjust view properties with the @ref{scale} and 9911@ref{fps} filters. 9912 9913It accepts the following parameters: 9914@table @option 9915 9916@item format 9917The desired packing format. Supported values are: 9918 9919@table @option 9920 9921@item sbs 9922The views are next to each other (default). 9923 9924@item tab 9925The views are on top of each other. 9926 9927@item lines 9928The views are packed by line. 9929 9930@item columns 9931The views are packed by column. 9932 9933@item frameseq 9934The views are temporally interleaved. 9935 9936@end table 9937 9938@end table 9939 9940Some examples: 9941 9942@example 9943# Convert left and right views into a frame-sequential video 9944ffmpeg -i LEFT -i RIGHT -filter_complex framepack=frameseq OUTPUT 9945 9946# Convert views into a side-by-side video with the same output resolution as the input 9947ffmpeg -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 9948@end example 9949 9950@section framerate 9951 9952Change the frame rate by interpolating new video output frames from the source 9953frames. 9954 9955This filter is not designed to function correctly with interlaced media. If 9956you wish to change the frame rate of interlaced media then you are required 9957to deinterlace before this filter and re-interlace after this filter. 9958 9959A description of the accepted options follows. 9960 9961@table @option 9962@item fps 9963Specify the output frames per second. This option can also be specified 9964as a value alone. The default is @code{50}. 9965 9966@item interp_start 9967Specify the start of a range where the output frame will be created as a 9968linear interpolation of two frames. The range is [@code{0}-@code{255}], 9969the default is @code{15}. 9970 9971@item interp_end 9972Specify the end of a range where the output frame will be created as a 9973linear interpolation of two frames. The range is [@code{0}-@code{255}], 9974the default is @code{240}. 9975 9976@item scene 9977Specify the level at which a scene change is detected as a value between 99780 and 100 to indicate a new scene; a low value reflects a low 9979probability for the current frame to introduce a new scene, while a higher 9980value means the current frame is more likely to be one. 9981The default is @code{8.2}. 9982 9983@item flags 9984Specify flags influencing the filter process. 9985 9986Available value for @var{flags} is: 9987 9988@table @option 9989@item scene_change_detect, scd 9990Enable scene change detection using the value of the option @var{scene}. 9991This flag is enabled by default. 9992@end table 9993@end table 9994 9995@section framestep 9996 9997Select one frame every N-th frame. 9998 9999This filter accepts the following option: 10000@table @option 10001@item step 10002Select frame after every @code{step} frames. 10003Allowed values are positive integers higher than 0. Default value is @code{1}. 10004@end table 10005 10006@anchor{frei0r} 10007@section frei0r 10008 10009Apply a frei0r effect to the input video. 10010 10011To enable the compilation of this filter, you need to install the frei0r 10012header and configure FFmpeg with @code{--enable-frei0r}. 10013 10014It accepts the following parameters: 10015 10016@table @option 10017 10018@item filter_name 10019The name of the frei0r effect to load. If the environment variable 10020@env{FREI0R_PATH} is defined, the frei0r effect is searched for in each of the 10021directories specified by the colon-separated list in @env{FREI0R_PATH}. 10022Otherwise, the standard frei0r paths are searched, in this order: 10023@file{HOME/.frei0r-1/lib/}, @file{/usr/local/lib/frei0r-1/}, 10024@file{/usr/lib/frei0r-1/}. 10025 10026@item filter_params 10027A '|'-separated list of parameters to pass to the frei0r effect. 10028 10029@end table 10030 10031A frei0r effect parameter can be a boolean (its value is either 10032"y" or "n"), a double, a color (specified as 10033@var{R}/@var{G}/@var{B}, where @var{R}, @var{G}, and @var{B} are floating point 10034numbers between 0.0 and 1.0, inclusive) or a color description as specified in the 10035@ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}, 10036a position (specified as @var{X}/@var{Y}, where 10037@var{X} and @var{Y} are floating point numbers) and/or a string. 10038 10039The number and types of parameters depend on the loaded effect. If an 10040effect parameter is not specified, the default value is set. 10041 10042@subsection Examples 10043 10044@itemize 10045@item 10046Apply the distort0r effect, setting the first two double parameters: 10047@example 10048frei0r=filter_name=distort0r:filter_params=0.5|0.01 10049@end example 10050 10051@item 10052Apply the colordistance effect, taking a color as the first parameter: 10053@example 10054frei0r=colordistance:0.2/0.3/0.4 10055frei0r=colordistance:violet 10056frei0r=colordistance:0x112233 10057@end example 10058 10059@item 10060Apply the perspective effect, specifying the top left and top right image 10061positions: 10062@example 10063frei0r=perspective:0.2/0.2|0.8/0.2 10064@end example 10065@end itemize 10066 10067For more information, see 10068@url{http://frei0r.dyne.org} 10069 10070@section fspp 10071 10072Apply fast and simple postprocessing. It is a faster version of @ref{spp}. 10073 10074It splits (I)DCT into horizontal/vertical passes. Unlike the simple post- 10075processing filter, one of them is performed once per block, not per pixel. 10076This allows for much higher speed. 10077 10078The filter accepts the following options: 10079 10080@table @option 10081@item quality 10082Set quality. This option defines the number of levels for averaging. It accepts 10083an integer in the range 4-5. Default value is @code{4}. 10084 10085@item qp 10086Force a constant quantization parameter. It accepts an integer in range 0-63. 10087If not set, the filter will use the QP from the video stream (if available). 10088 10089@item strength 10090Set filter strength. It accepts an integer in range -15 to 32. Lower values mean 10091more details but also more artifacts, while higher values make the image smoother 10092but also blurrier. Default value is @code{0} − PSNR optimal. 10093 10094@item use_bframe_qp 10095Enable the use of the QP from the B-Frames if set to @code{1}. Using this 10096option may cause flicker since the B-Frames have often larger QP. Default is 10097@code{0} (not enabled). 10098 10099@end table 10100 10101@section gblur 10102 10103Apply Gaussian blur filter. 10104 10105The filter accepts the following options: 10106 10107@table @option 10108@item sigma 10109Set horizontal sigma, standard deviation of Gaussian blur. Default is @code{0.5}. 10110 10111@item steps 10112Set number of steps for Gaussian approximation. Defauls is @code{1}. 10113 10114@item planes 10115Set which planes to filter. By default all planes are filtered. 10116 10117@item sigmaV 10118Set vertical sigma, if negative it will be same as @code{sigma}. 10119Default is @code{-1}. 10120@end table 10121 10122@section geq 10123 10124Apply generic equation to each pixel. 10125 10126The filter accepts the following options: 10127 10128@table @option 10129@item lum_expr, lum 10130Set the luminance expression. 10131@item cb_expr, cb 10132Set the chrominance blue expression. 10133@item cr_expr, cr 10134Set the chrominance red expression. 10135@item alpha_expr, a 10136Set the alpha expression. 10137@item red_expr, r 10138Set the red expression. 10139@item green_expr, g 10140Set the green expression. 10141@item blue_expr, b 10142Set the blue expression. 10143@end table 10144 10145The colorspace is selected according to the specified options. If one 10146of the @option{lum_expr}, @option{cb_expr}, or @option{cr_expr} 10147options is specified, the filter will automatically select a YCbCr 10148colorspace. If one of the @option{red_expr}, @option{green_expr}, or 10149@option{blue_expr} options is specified, it will select an RGB 10150colorspace. 10151 10152If one of the chrominance expression is not defined, it falls back on the other 10153one. If no alpha expression is specified it will evaluate to opaque value. 10154If none of chrominance expressions are specified, they will evaluate 10155to the luminance expression. 10156 10157The expressions can use the following variables and functions: 10158 10159@table @option 10160@item N 10161The sequential number of the filtered frame, starting from @code{0}. 10162 10163@item X 10164@item Y 10165The coordinates of the current sample. 10166 10167@item W 10168@item H 10169The width and height of the image. 10170 10171@item SW 10172@item SH 10173Width and height scale depending on the currently filtered plane. It is the 10174ratio between the corresponding luma plane number of pixels and the current 10175plane ones. E.g. for YUV4:2:0 the values are @code{1,1} for the luma plane, and 10176@code{0.5,0.5} for chroma planes. 10177 10178@item T 10179Time of the current frame, expressed in seconds. 10180 10181@item p(x, y) 10182Return the value of the pixel at location (@var{x},@var{y}) of the current 10183plane. 10184 10185@item lum(x, y) 10186Return the value of the pixel at location (@var{x},@var{y}) of the luminance 10187plane. 10188 10189@item cb(x, y) 10190Return the value of the pixel at location (@var{x},@var{y}) of the 10191blue-difference chroma plane. Return 0 if there is no such plane. 10192 10193@item cr(x, y) 10194Return the value of the pixel at location (@var{x},@var{y}) of the 10195red-difference chroma plane. Return 0 if there is no such plane. 10196 10197@item r(x, y) 10198@item g(x, y) 10199@item b(x, y) 10200Return the value of the pixel at location (@var{x},@var{y}) of the 10201red/green/blue component. Return 0 if there is no such component. 10202 10203@item alpha(x, y) 10204Return the value of the pixel at location (@var{x},@var{y}) of the alpha 10205plane. Return 0 if there is no such plane. 10206@end table 10207 10208For functions, if @var{x} and @var{y} are outside the area, the value will be 10209automatically clipped to the closer edge. 10210 10211@subsection Examples 10212 10213@itemize 10214@item 10215Flip the image horizontally: 10216@example 10217geq=p(W-X\,Y) 10218@end example 10219 10220@item 10221Generate a bidimensional sine wave, with angle @code{PI/3} and a 10222wavelength of 100 pixels: 10223@example 10224geq=128 + 100*sin(2*(PI/100)*(cos(PI/3)*(X-50*T) + sin(PI/3)*Y)):128:128 10225@end example 10226 10227@item 10228Generate a fancy enigmatic moving light: 10229@example 10230nullsrc=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 10231@end example 10232 10233@item 10234Generate a quick emboss effect: 10235@example 10236format=gray,geq=lum_expr='(p(X,Y)+(256-p(X-4,Y-4)))/2' 10237@end example 10238 10239@item 10240Modify RGB components depending on pixel position: 10241@example 10242geq=r='X/W*r(X,Y)':g='(1-X/W)*g(X,Y)':b='(H-Y)/H*b(X,Y)' 10243@end example 10244 10245@item 10246Create a radial gradient that is the same size as the input (also see 10247the @ref{vignette} filter): 10248@example 10249geq=lum=255*gauss((X/W-0.5)*3)*gauss((Y/H-0.5)*3)/gauss(0)/gauss(0),format=gray 10250@end example 10251@end itemize 10252 10253@section gradfun 10254 10255Fix the banding artifacts that are sometimes introduced into nearly flat 10256regions by truncation to 8-bit color depth. 10257Interpolate the gradients that should go where the bands are, and 10258dither them. 10259 10260It is designed for playback only. Do not use it prior to 10261lossy compression, because compression tends to lose the dither and 10262bring back the bands. 10263 10264It accepts the following parameters: 10265 10266@table @option 10267 10268@item strength 10269The maximum amount by which the filter will change any one pixel. This is also 10270the threshold for detecting nearly flat regions. Acceptable values range from 10271.51 to 64; the default value is 1.2. Out-of-range values will be clipped to the 10272valid range. 10273 10274@item radius 10275The neighborhood to fit the gradient to. A larger radius makes for smoother 10276gradients, but also prevents the filter from modifying the pixels near detailed 10277regions. Acceptable values are 8-32; the default value is 16. Out-of-range 10278values will be clipped to the valid range. 10279 10280@end table 10281 10282Alternatively, the options can be specified as a flat string: 10283@var{strength}[:@var{radius}] 10284 10285@subsection Examples 10286 10287@itemize 10288@item 10289Apply the filter with a @code{3.5} strength and radius of @code{8}: 10290@example 10291gradfun=3.5:8 10292@end example 10293 10294@item 10295Specify radius, omitting the strength (which will fall-back to the default 10296value): 10297@example 10298gradfun=radius=8 10299@end example 10300 10301@end itemize 10302 10303@section graphmonitor, agraphmonitor 10304Show various filtergraph stats. 10305 10306With this filter one can debug complete filtergraph. 10307Especially issues with links filling with queued frames. 10308 10309The filter accepts the following options: 10310 10311@table @option 10312@item size, s 10313Set video output size. Default is @var{hd720}. 10314 10315@item opacity, o 10316Set video opacity. Default is @var{0.9}. Allowed range is from @var{0} to @var{1}. 10317 10318@item mode, m 10319Set output mode, can be @var{fulll} or @var{compact}. 10320In @var{compact} mode only filters with some queued frames have displayed stats. 10321 10322@item flags, f 10323Set flags which enable which stats are shown in video. 10324 10325Available values for flags are: 10326@table @samp 10327@item queue 10328Display number of queued frames in each link. 10329 10330@item frame_count_in 10331Display number of frames taken from filter. 10332 10333@item frame_count_out 10334Display number of frames given out from filter. 10335 10336@item pts 10337Display current filtered frame pts. 10338 10339@item time 10340Display current filtered frame time. 10341 10342@item timebase 10343Display time base for filter link. 10344 10345@item format 10346Display used format for filter link. 10347 10348@item size 10349Display video size or number of audio channels in case of audio used by filter link. 10350 10351@item rate 10352Display video frame rate or sample rate in case of audio used by filter link. 10353@end table 10354 10355@item rate, r 10356Set upper limit for video rate of output stream, Default value is @var{25}. 10357This guarantee that output video frame rate will not be higher than this value. 10358@end table 10359 10360@section greyedge 10361A color constancy variation filter which estimates scene illumination via grey edge algorithm 10362and corrects the scene colors accordingly. 10363 10364See: @url{https://staff.science.uva.nl/th.gevers/pub/GeversTIP07.pdf} 10365 10366The filter accepts the following options: 10367 10368@table @option 10369@item difford 10370The order of differentiation to be applied on the scene. Must be chosen in the range 10371[0,2] and default value is 1. 10372 10373@item minknorm 10374The Minkowski parameter to be used for calculating the Minkowski distance. Must 10375be chosen in the range [0,20] and default value is 1. Set to 0 for getting 10376max value instead of calculating Minkowski distance. 10377 10378@item sigma 10379The standard deviation of Gaussian blur to be applied on the scene. Must be 10380chosen in the range [0,1024.0] and default value = 1. floor( @var{sigma} * break_off_sigma(3) ) 10381can't be euqal to 0 if @var{difford} is greater than 0. 10382@end table 10383 10384@subsection Examples 10385@itemize 10386 10387@item 10388Grey Edge: 10389@example 10390greyedge=difford=1:minknorm=5:sigma=2 10391@end example 10392 10393@item 10394Max Edge: 10395@example 10396greyedge=difford=1:minknorm=0:sigma=2 10397@end example 10398 10399@end itemize 10400 10401@anchor{haldclut} 10402@section haldclut 10403 10404Apply a Hald CLUT to a video stream. 10405 10406First input is the video stream to process, and second one is the Hald CLUT. 10407The Hald CLUT input can be a simple picture or a complete video stream. 10408 10409The filter accepts the following options: 10410 10411@table @option 10412@item shortest 10413Force termination when the shortest input terminates. Default is @code{0}. 10414@item repeatlast 10415Continue applying the last CLUT after the end of the stream. A value of 10416@code{0} disable the filter after the last frame of the CLUT is reached. 10417Default is @code{1}. 10418@end table 10419 10420@code{haldclut} also has the same interpolation options as @ref{lut3d} (both 10421filters share the same internals). 10422 10423More information about the Hald CLUT can be found on Eskil Steenberg's website 10424(Hald CLUT author) at @url{http://www.quelsolaar.com/technology/clut.html}. 10425 10426@subsection Workflow examples 10427 10428@subsubsection Hald CLUT video stream 10429 10430Generate an identity Hald CLUT stream altered with various effects: 10431@example 10432ffmpeg -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 10433@end example 10434 10435Note: make sure you use a lossless codec. 10436 10437Then use it with @code{haldclut} to apply it on some random stream: 10438@example 10439ffmpeg -f lavfi -i mandelbrot -i clut.nut -filter_complex '[0][1] haldclut' -t 20 mandelclut.mkv 10440@end example 10441 10442The Hald CLUT will be applied to the 10 first seconds (duration of 10443@file{clut.nut}), then the latest picture of that CLUT stream will be applied 10444to the remaining frames of the @code{mandelbrot} stream. 10445 10446@subsubsection Hald CLUT with preview 10447 10448A Hald CLUT is supposed to be a squared image of @code{Level*Level*Level} by 10449@code{Level*Level*Level} pixels. For a given Hald CLUT, FFmpeg will select the 10450biggest possible square starting at the top left of the picture. The remaining 10451padding pixels (bottom or right) will be ignored. This area can be used to add 10452a preview of the Hald CLUT. 10453 10454Typically, the following generated Hald CLUT will be supported by the 10455@code{haldclut} filter: 10456 10457@example 10458ffmpeg -f lavfi -i @ref{haldclutsrc}=8 -vf " 10459 pad=iw+320 [padded_clut]; 10460 smptebars=s=320x256, split [a][b]; 10461 [padded_clut][a] overlay=W-320:h, curves=color_negative [main]; 10462 [main][b] overlay=W-320" -frames:v 1 clut.png 10463@end example 10464 10465It contains the original and a preview of the effect of the CLUT: SMPTE color 10466bars are displayed on the right-top, and below the same color bars processed by 10467the color changes. 10468 10469Then, the effect of this Hald CLUT can be visualized with: 10470@example 10471ffplay input.mkv -vf "movie=clut.png, [in] haldclut" 10472@end example 10473 10474@section hflip 10475 10476Flip the input video horizontally. 10477 10478For example, to horizontally flip the input video with @command{ffmpeg}: 10479@example 10480ffmpeg -i in.avi -vf "hflip" out.avi 10481@end example 10482 10483@section histeq 10484This filter applies a global color histogram equalization on a 10485per-frame basis. 10486 10487It can be used to correct video that has a compressed range of pixel 10488intensities. The filter redistributes the pixel intensities to 10489equalize their distribution across the intensity range. It may be 10490viewed as an "automatically adjusting contrast filter". This filter is 10491useful only for correcting degraded or poorly captured source 10492video. 10493 10494The filter accepts the following options: 10495 10496@table @option 10497@item strength 10498Determine the amount of equalization to be applied. As the strength 10499is reduced, the distribution of pixel intensities more-and-more 10500approaches that of the input frame. The value must be a float number 10501in the range [0,1] and defaults to 0.200. 10502 10503@item intensity 10504Set the maximum intensity that can generated and scale the output 10505values appropriately. The strength should be set as desired and then 10506the intensity can be limited if needed to avoid washing-out. The value 10507must be a float number in the range [0,1] and defaults to 0.210. 10508 10509@item antibanding 10510Set the antibanding level. If enabled the filter will randomly vary 10511the luminance of output pixels by a small amount to avoid banding of 10512the histogram. Possible values are @code{none}, @code{weak} or 10513@code{strong}. It defaults to @code{none}. 10514@end table 10515 10516@section histogram 10517 10518Compute and draw a color distribution histogram for the input video. 10519 10520The computed histogram is a representation of the color component 10521distribution in an image. 10522 10523Standard histogram displays the color components distribution in an image. 10524Displays color graph for each color component. Shows distribution of 10525the Y, U, V, A or R, G, B components, depending on input format, in the 10526current frame. Below each graph a color component scale meter is shown. 10527 10528The filter accepts the following options: 10529 10530@table @option 10531@item level_height 10532Set height of level. Default value is @code{200}. 10533Allowed range is [50, 2048]. 10534 10535@item scale_height 10536Set height of color scale. Default value is @code{12}. 10537Allowed range is [0, 40]. 10538 10539@item display_mode 10540Set display mode. 10541It accepts the following values: 10542@table @samp 10543@item stack 10544Per color component graphs are placed below each other. 10545 10546@item parade 10547Per color component graphs are placed side by side. 10548 10549@item overlay 10550Presents information identical to that in the @code{parade}, except 10551that the graphs representing color components are superimposed directly 10552over one another. 10553@end table 10554Default is @code{stack}. 10555 10556@item levels_mode 10557Set mode. Can be either @code{linear}, or @code{logarithmic}. 10558Default is @code{linear}. 10559 10560@item components 10561Set what color components to display. 10562Default is @code{7}. 10563 10564@item fgopacity 10565Set foreground opacity. Default is @code{0.7}. 10566 10567@item bgopacity 10568Set background opacity. Default is @code{0.5}. 10569@end table 10570 10571@subsection Examples 10572 10573@itemize 10574 10575@item 10576Calculate and draw histogram: 10577@example 10578ffplay -i input -vf histogram 10579@end example 10580 10581@end itemize 10582 10583@anchor{hqdn3d} 10584@section hqdn3d 10585 10586This is a high precision/quality 3d denoise filter. It aims to reduce 10587image noise, producing smooth images and making still images really 10588still. It should enhance compressibility. 10589 10590It accepts the following optional parameters: 10591 10592@table @option 10593@item luma_spatial 10594A non-negative floating point number which specifies spatial luma strength. 10595It defaults to 4.0. 10596 10597@item chroma_spatial 10598A non-negative floating point number which specifies spatial chroma strength. 10599It defaults to 3.0*@var{luma_spatial}/4.0. 10600 10601@item luma_tmp 10602A floating point number which specifies luma temporal strength. It defaults to 106036.0*@var{luma_spatial}/4.0. 10604 10605@item chroma_tmp 10606A floating point number which specifies chroma temporal strength. It defaults to 10607@var{luma_tmp}*@var{chroma_spatial}/@var{luma_spatial}. 10608@end table 10609 10610@section hwdownload 10611 10612Download hardware frames to system memory. 10613 10614The input must be in hardware frames, and the output a non-hardware format. 10615Not all formats will be supported on the output - it may be necessary to insert 10616an additional @option{format} filter immediately following in the graph to get 10617the output in a supported format. 10618 10619@section hwmap 10620 10621Map hardware frames to system memory or to another device. 10622 10623This filter has several different modes of operation; which one is used depends 10624on the input and output formats: 10625@itemize 10626@item 10627Hardware frame input, normal frame output 10628 10629Map the input frames to system memory and pass them to the output. If the 10630original hardware frame is later required (for example, after overlaying 10631something else on part of it), the @option{hwmap} filter can be used again 10632in the next mode to retrieve it. 10633@item 10634Normal frame input, hardware frame output 10635 10636If the input is actually a software-mapped hardware frame, then unmap it - 10637that is, return the original hardware frame. 10638 10639Otherwise, a device must be provided. Create new hardware surfaces on that 10640device for the output, then map them back to the software format at the input 10641and give those frames to the preceding filter. This will then act like the 10642@option{hwupload} filter, but may be able to avoid an additional copy when 10643the input is already in a compatible format. 10644@item 10645Hardware frame input and output 10646 10647A device must be supplied for the output, either directly or with the 10648@option{derive_device} option. The input and output devices must be of 10649different types and compatible - the exact meaning of this is 10650system-dependent, but typically it means that they must refer to the same 10651underlying hardware context (for example, refer to the same graphics card). 10652 10653If the input frames were originally created on the output device, then unmap 10654to retrieve the original frames. 10655 10656Otherwise, map the frames to the output device - create new hardware frames 10657on the output corresponding to the frames on the input. 10658@end itemize 10659 10660The following additional parameters are accepted: 10661 10662@table @option 10663@item mode 10664Set the frame mapping mode. Some combination of: 10665@table @var 10666@item read 10667The mapped frame should be readable. 10668@item write 10669The mapped frame should be writeable. 10670@item overwrite 10671The mapping will always overwrite the entire frame. 10672 10673This may improve performance in some cases, as the original contents of the 10674frame need not be loaded. 10675@item direct 10676The mapping must not involve any copying. 10677 10678Indirect mappings to copies of frames are created in some cases where either 10679direct mapping is not possible or it would have unexpected properties. 10680Setting this flag ensures that the mapping is direct and will fail if that is 10681not possible. 10682@end table 10683Defaults to @var{read+write} if not specified. 10684 10685@item derive_device @var{type} 10686Rather than using the device supplied at initialisation, instead derive a new 10687device of type @var{type} from the device the input frames exist on. 10688 10689@item reverse 10690In a hardware to hardware mapping, map in reverse - create frames in the sink 10691and map them back to the source. This may be necessary in some cases where 10692a mapping in one direction is required but only the opposite direction is 10693supported by the devices being used. 10694 10695This option is dangerous - it may break the preceding filter in undefined 10696ways if there are any additional constraints on that filter's output. 10697Do not use it without fully understanding the implications of its use. 10698@end table 10699 10700@section hwupload 10701 10702Upload system memory frames to hardware surfaces. 10703 10704The device to upload to must be supplied when the filter is initialised. If 10705using ffmpeg, select the appropriate device with the @option{-filter_hw_device} 10706option. 10707 10708@anchor{hwupload_cuda} 10709@section hwupload_cuda 10710 10711Upload system memory frames to a CUDA device. 10712 10713It accepts the following optional parameters: 10714 10715@table @option 10716@item device 10717The number of the CUDA device to use 10718@end table 10719 10720@section hqx 10721 10722Apply a high-quality magnification filter designed for pixel art. This filter 10723was originally created by Maxim Stepin. 10724 10725It accepts the following option: 10726 10727@table @option 10728@item n 10729Set the scaling dimension: @code{2} for @code{hq2x}, @code{3} for 10730@code{hq3x} and @code{4} for @code{hq4x}. 10731Default is @code{3}. 10732@end table 10733 10734@section hstack 10735Stack input videos horizontally. 10736 10737All streams must be of same pixel format and of same height. 10738 10739Note that this filter is faster than using @ref{overlay} and @ref{pad} filter 10740to create same output. 10741 10742The filter accept the following option: 10743 10744@table @option 10745@item inputs 10746Set number of input streams. Default is 2. 10747 10748@item shortest 10749If set to 1, force the output to terminate when the shortest input 10750terminates. Default value is 0. 10751@end table 10752 10753@section hue 10754 10755Modify the hue and/or the saturation of the input. 10756 10757It accepts the following parameters: 10758 10759@table @option 10760@item h 10761Specify the hue angle as a number of degrees. It accepts an expression, 10762and defaults to "0". 10763 10764@item s 10765Specify the saturation in the [-10,10] range. It accepts an expression and 10766defaults to "1". 10767 10768@item H 10769Specify the hue angle as a number of radians. It accepts an 10770expression, and defaults to "0". 10771 10772@item b 10773Specify the brightness in the [-10,10] range. It accepts an expression and 10774defaults to "0". 10775@end table 10776 10777@option{h} and @option{H} are mutually exclusive, and can't be 10778specified at the same time. 10779 10780The @option{b}, @option{h}, @option{H} and @option{s} option values are 10781expressions containing the following constants: 10782 10783@table @option 10784@item n 10785frame count of the input frame starting from 0 10786 10787@item pts 10788presentation timestamp of the input frame expressed in time base units 10789 10790@item r 10791frame rate of the input video, NAN if the input frame rate is unknown 10792 10793@item t 10794timestamp expressed in seconds, NAN if the input timestamp is unknown 10795 10796@item tb 10797time base of the input video 10798@end table 10799 10800@subsection Examples 10801 10802@itemize 10803@item 10804Set the hue to 90 degrees and the saturation to 1.0: 10805@example 10806hue=h=90:s=1 10807@end example 10808 10809@item 10810Same command but expressing the hue in radians: 10811@example 10812hue=H=PI/2:s=1 10813@end example 10814 10815@item 10816Rotate hue and make the saturation swing between 0 10817and 2 over a period of 1 second: 10818@example 10819hue="H=2*PI*t: s=sin(2*PI*t)+1" 10820@end example 10821 10822@item 10823Apply a 3 seconds saturation fade-in effect starting at 0: 10824@example 10825hue="s=min(t/3\,1)" 10826@end example 10827 10828The general fade-in expression can be written as: 10829@example 10830hue="s=min(0\, max((t-START)/DURATION\, 1))" 10831@end example 10832 10833@item 10834Apply a 3 seconds saturation fade-out effect starting at 5 seconds: 10835@example 10836hue="s=max(0\, min(1\, (8-t)/3))" 10837@end example 10838 10839The general fade-out expression can be written as: 10840@example 10841hue="s=max(0\, min(1\, (START+DURATION-t)/DURATION))" 10842@end example 10843 10844@end itemize 10845 10846@subsection Commands 10847 10848This filter supports the following commands: 10849@table @option 10850@item b 10851@item s 10852@item h 10853@item H 10854Modify the hue and/or the saturation and/or brightness of the input video. 10855The command accepts the same syntax of the corresponding option. 10856 10857If the specified expression is not valid, it is kept at its current 10858value. 10859@end table 10860 10861@section hysteresis 10862 10863Grow first stream into second stream by connecting components. 10864This makes it possible to build more robust edge masks. 10865 10866This filter accepts the following options: 10867 10868@table @option 10869@item planes 10870Set which planes will be processed as bitmap, unprocessed planes will be 10871copied from first stream. 10872By default value 0xf, all planes will be processed. 10873 10874@item threshold 10875Set threshold which is used in filtering. If pixel component value is higher than 10876this value filter algorithm for connecting components is activated. 10877By default value is 0. 10878@end table 10879 10880@section idet 10881 10882Detect video interlacing type. 10883 10884This filter tries to detect if the input frames are interlaced, progressive, 10885top or bottom field first. It will also try to detect fields that are 10886repeated between adjacent frames (a sign of telecine). 10887 10888Single frame detection considers only immediately adjacent frames when classifying each frame. 10889Multiple frame detection incorporates the classification history of previous frames. 10890 10891The filter will log these metadata values: 10892 10893@table @option 10894@item single.current_frame 10895Detected type of current frame using single-frame detection. One of: 10896``tff'' (top field first), ``bff'' (bottom field first), 10897``progressive'', or ``undetermined'' 10898 10899@item single.tff 10900Cumulative number of frames detected as top field first using single-frame detection. 10901 10902@item multiple.tff 10903Cumulative number of frames detected as top field first using multiple-frame detection. 10904 10905@item single.bff 10906Cumulative number of frames detected as bottom field first using single-frame detection. 10907 10908@item multiple.current_frame 10909Detected type of current frame using multiple-frame detection. One of: 10910``tff'' (top field first), ``bff'' (bottom field first), 10911``progressive'', or ``undetermined'' 10912 10913@item multiple.bff 10914Cumulative number of frames detected as bottom field first using multiple-frame detection. 10915 10916@item single.progressive 10917Cumulative number of frames detected as progressive using single-frame detection. 10918 10919@item multiple.progressive 10920Cumulative number of frames detected as progressive using multiple-frame detection. 10921 10922@item single.undetermined 10923Cumulative number of frames that could not be classified using single-frame detection. 10924 10925@item multiple.undetermined 10926Cumulative number of frames that could not be classified using multiple-frame detection. 10927 10928@item repeated.current_frame 10929Which field in the current frame is repeated from the last. One of ``neither'', ``top'', or ``bottom''. 10930 10931@item repeated.neither 10932Cumulative number of frames with no repeated field. 10933 10934@item repeated.top 10935Cumulative number of frames with the top field repeated from the previous frame's top field. 10936 10937@item repeated.bottom 10938Cumulative number of frames with the bottom field repeated from the previous frame's bottom field. 10939@end table 10940 10941The filter accepts the following options: 10942 10943@table @option 10944@item intl_thres 10945Set interlacing threshold. 10946@item prog_thres 10947Set progressive threshold. 10948@item rep_thres 10949Threshold for repeated field detection. 10950@item half_life 10951Number of frames after which a given frame's contribution to the 10952statistics is halved (i.e., it contributes only 0.5 to its 10953classification). The default of 0 means that all frames seen are given 10954full weight of 1.0 forever. 10955@item analyze_interlaced_flag 10956When this is not 0 then idet will use the specified number of frames to determine 10957if the interlaced flag is accurate, it will not count undetermined frames. 10958If the flag is found to be accurate it will be used without any further 10959computations, if it is found to be inaccurate it will be cleared without any 10960further computations. This allows inserting the idet filter as a low computational 10961method to clean up the interlaced flag 10962@end table 10963 10964@section il 10965 10966Deinterleave or interleave fields. 10967 10968This filter allows one to process interlaced images fields without 10969deinterlacing them. Deinterleaving splits the input frame into 2 10970fields (so called half pictures). Odd lines are moved to the top 10971half of the output image, even lines to the bottom half. 10972You can process (filter) them independently and then re-interleave them. 10973 10974The filter accepts the following options: 10975 10976@table @option 10977@item luma_mode, l 10978@item chroma_mode, c 10979@item alpha_mode, a 10980Available values for @var{luma_mode}, @var{chroma_mode} and 10981@var{alpha_mode} are: 10982 10983@table @samp 10984@item none 10985Do nothing. 10986 10987@item deinterleave, d 10988Deinterleave fields, placing one above the other. 10989 10990@item interleave, i 10991Interleave fields. Reverse the effect of deinterleaving. 10992@end table 10993Default value is @code{none}. 10994 10995@item luma_swap, ls 10996@item chroma_swap, cs 10997@item alpha_swap, as 10998Swap luma/chroma/alpha fields. Exchange even & odd lines. Default value is @code{0}. 10999@end table 11000 11001@section inflate 11002 11003Apply inflate effect to the video. 11004 11005This filter replaces the pixel by the local(3x3) average by taking into account 11006only values higher than the pixel. 11007 11008It accepts the following options: 11009 11010@table @option 11011@item threshold0 11012@item threshold1 11013@item threshold2 11014@item threshold3 11015Limit the maximum change for each plane, default is 65535. 11016If 0, plane will remain unchanged. 11017@end table 11018 11019@section interlace 11020 11021Simple interlacing filter from progressive contents. This interleaves upper (or 11022lower) lines from odd frames with lower (or upper) lines from even frames, 11023halving the frame rate and preserving image height. 11024 11025@example 11026 Original Original New Frame 11027 Frame 'j' Frame 'j+1' (tff) 11028 ========== =========== ================== 11029 Line 0 --------------------> Frame 'j' Line 0 11030 Line 1 Line 1 ----> Frame 'j+1' Line 1 11031 Line 2 ---------------------> Frame 'j' Line 2 11032 Line 3 Line 3 ----> Frame 'j+1' Line 3 11033 ... ... ... 11034New Frame + 1 will be generated by Frame 'j+2' and Frame 'j+3' and so on 11035@end example 11036 11037It accepts the following optional parameters: 11038 11039@table @option 11040@item scan 11041This determines whether the interlaced frame is taken from the even 11042(tff - default) or odd (bff) lines of the progressive frame. 11043 11044@item lowpass 11045Vertical lowpass filter to avoid twitter interlacing and 11046reduce moire patterns. 11047 11048@table @samp 11049@item 0, off 11050Disable vertical lowpass filter 11051 11052@item 1, linear 11053Enable linear filter (default) 11054 11055@item 2, complex 11056Enable complex filter. This will slightly less reduce twitter and moire 11057but better retain detail and subjective sharpness impression. 11058 11059@end table 11060@end table 11061 11062@section kerndeint 11063 11064Deinterlace input video by applying Donald Graft's adaptive kernel 11065deinterling. Work on interlaced parts of a video to produce 11066progressive frames. 11067 11068The description of the accepted parameters follows. 11069 11070@table @option 11071@item thresh 11072Set the threshold which affects the filter's tolerance when 11073determining if a pixel line must be processed. It must be an integer 11074in the range [0,255] and defaults to 10. A value of 0 will result in 11075applying the process on every pixels. 11076 11077@item map 11078Paint pixels exceeding the threshold value to white if set to 1. 11079Default is 0. 11080 11081@item order 11082Set the fields order. Swap fields if set to 1, leave fields alone if 110830. Default is 0. 11084 11085@item sharp 11086Enable additional sharpening if set to 1. Default is 0. 11087 11088@item twoway 11089Enable twoway sharpening if set to 1. Default is 0. 11090@end table 11091 11092@subsection Examples 11093 11094@itemize 11095@item 11096Apply default values: 11097@example 11098kerndeint=thresh=10:map=0:order=0:sharp=0:twoway=0 11099@end example 11100 11101@item 11102Enable additional sharpening: 11103@example 11104kerndeint=sharp=1 11105@end example 11106 11107@item 11108Paint processed pixels in white: 11109@example 11110kerndeint=map=1 11111@end example 11112@end itemize 11113 11114@section lenscorrection 11115 11116Correct radial lens distortion 11117 11118This filter can be used to correct for radial distortion as can result from the use 11119of wide angle lenses, and thereby re-rectify the image. To find the right parameters 11120one can use tools available for example as part of opencv or simply trial-and-error. 11121To use opencv use the calibration sample (under samples/cpp) from the opencv sources 11122and extract the k1 and k2 coefficients from the resulting matrix. 11123 11124Note that effectively the same filter is available in the open-source tools Krita and 11125Digikam from the KDE project. 11126 11127In contrast to the @ref{vignette} filter, which can also be used to compensate lens errors, 11128this filter corrects the distortion of the image, whereas @ref{vignette} corrects the 11129brightness distribution, so you may want to use both filters together in certain 11130cases, though you will have to take care of ordering, i.e. whether vignetting should 11131be applied before or after lens correction. 11132 11133@subsection Options 11134 11135The filter accepts the following options: 11136 11137@table @option 11138@item cx 11139Relative x-coordinate of the focal point of the image, and thereby the center of the 11140distortion. This value has a range [0,1] and is expressed as fractions of the image 11141width. Default is 0.5. 11142@item cy 11143Relative y-coordinate of the focal point of the image, and thereby the center of the 11144distortion. This value has a range [0,1] and is expressed as fractions of the image 11145height. Default is 0.5. 11146@item k1 11147Coefficient of the quadratic correction term. This value has a range [-1,1]. 0 means 11148no correction. Default is 0. 11149@item k2 11150Coefficient of the double quadratic correction term. This value has a range [-1,1]. 111510 means no correction. Default is 0. 11152@end table 11153 11154The formula that generates the correction is: 11155 11156@var{r_src} = @var{r_tgt} * (1 + @var{k1} * (@var{r_tgt} / @var{r_0})^2 + @var{k2} * (@var{r_tgt} / @var{r_0})^4) 11157 11158where @var{r_0} is halve of the image diagonal and @var{r_src} and @var{r_tgt} are the 11159distances from the focal point in the source and target images, respectively. 11160 11161@section lensfun 11162 11163Apply lens correction via the lensfun library (@url{http://lensfun.sourceforge.net/}). 11164 11165The @code{lensfun} filter requires the camera make, camera model, and lens model 11166to apply the lens correction. The filter will load the lensfun database and 11167query it to find the corresponding camera and lens entries in the database. As 11168long as these entries can be found with the given options, the filter can 11169perform corrections on frames. Note that incomplete strings will result in the 11170filter choosing the best match with the given options, and the filter will 11171output the chosen camera and lens models (logged with level "info"). You must 11172provide the make, camera model, and lens model as they are required. 11173 11174The filter accepts the following options: 11175 11176@table @option 11177@item make 11178The make of the camera (for example, "Canon"). This option is required. 11179 11180@item model 11181The model of the camera (for example, "Canon EOS 100D"). This option is 11182required. 11183 11184@item lens_model 11185The model of the lens (for example, "Canon EF-S 18-55mm f/3.5-5.6 IS STM"). This 11186option is required. 11187 11188@item mode 11189The type of correction to apply. The following values are valid options: 11190 11191@table @samp 11192@item vignetting 11193Enables fixing lens vignetting. 11194 11195@item geometry 11196Enables fixing lens geometry. This is the default. 11197 11198@item subpixel 11199Enables fixing chromatic aberrations. 11200 11201@item vig_geo 11202Enables fixing lens vignetting and lens geometry. 11203 11204@item vig_subpixel 11205Enables fixing lens vignetting and chromatic aberrations. 11206 11207@item distortion 11208Enables fixing both lens geometry and chromatic aberrations. 11209 11210@item all 11211Enables all possible corrections. 11212 11213@end table 11214@item focal_length 11215The focal length of the image/video (zoom; expected constant for video). For 11216example, a 18--55mm lens has focal length range of [18--55], so a value in that 11217range should be chosen when using that lens. Default 18. 11218 11219@item aperture 11220The aperture of the image/video (expected constant for video). Note that 11221aperture is only used for vignetting correction. Default 3.5. 11222 11223@item focus_distance 11224The focus distance of the image/video (expected constant for video). Note that 11225focus distance is only used for vignetting and only slightly affects the 11226vignetting correction process. If unknown, leave it at the default value (which 11227is 1000). 11228 11229@item target_geometry 11230The target geometry of the output image/video. The following values are valid 11231options: 11232 11233@table @samp 11234@item rectilinear (default) 11235@item fisheye 11236@item panoramic 11237@item equirectangular 11238@item fisheye_orthographic 11239@item fisheye_stereographic 11240@item fisheye_equisolid 11241@item fisheye_thoby 11242@end table 11243@item reverse 11244Apply the reverse of image correction (instead of correcting distortion, apply 11245it). 11246 11247@item interpolation 11248The type of interpolation used when correcting distortion. The following values 11249are valid options: 11250 11251@table @samp 11252@item nearest 11253@item linear (default) 11254@item lanczos 11255@end table 11256@end table 11257 11258@subsection Examples 11259 11260@itemize 11261@item 11262Apply lens correction with make "Canon", camera model "Canon EOS 100D", and lens 11263model "Canon EF-S 18-55mm f/3.5-5.6 IS STM" with focal length of "18" and 11264aperture of "8.0". 11265 11266@example 11267ffmpeg -i input.mov -vf lensfun=make=Canon:model="Canon EOS 100D":lens_model="Canon EF-S 18-55mm f/3.5-5.6 IS STM":focal_length=18:aperture=8 -c:v h264 -b:v 8000k output.mov 11268@end example 11269 11270@item 11271Apply the same as before, but only for the first 5 seconds of video. 11272 11273@example 11274ffmpeg -i input.mov -vf lensfun=make=Canon:model="Canon EOS 100D":lens_model="Canon EF-S 18-55mm f/3.5-5.6 IS STM":focal_length=18:aperture=8:enable='lte(t\,5)' -c:v h264 -b:v 8000k output.mov 11275@end example 11276 11277@end itemize 11278 11279@section libvmaf 11280 11281Obtain the VMAF (Video Multi-Method Assessment Fusion) 11282score between two input videos. 11283 11284The obtained VMAF score is printed through the logging system. 11285 11286It requires Netflix's vmaf library (libvmaf) as a pre-requisite. 11287After installing the library it can be enabled using: 11288@code{./configure --enable-libvmaf --enable-version3}. 11289If no model path is specified it uses the default model: @code{vmaf_v0.6.1.pkl}. 11290 11291The filter has following options: 11292 11293@table @option 11294@item model_path 11295Set the model path which is to be used for SVM. 11296Default value: @code{"vmaf_v0.6.1.pkl"} 11297 11298@item log_path 11299Set the file path to be used to store logs. 11300 11301@item log_fmt 11302Set the format of the log file (xml or json). 11303 11304@item enable_transform 11305Enables transform for computing vmaf. 11306 11307@item phone_model 11308Invokes the phone model which will generate VMAF scores higher than in the 11309regular model, which is more suitable for laptop, TV, etc. viewing conditions. 11310 11311@item psnr 11312Enables computing psnr along with vmaf. 11313 11314@item ssim 11315Enables computing ssim along with vmaf. 11316 11317@item ms_ssim 11318Enables computing ms_ssim along with vmaf. 11319 11320@item pool 11321Set the pool method (mean, min or harmonic mean) to be used for computing vmaf. 11322 11323@item n_threads 11324Set number of threads to be used when computing vmaf. 11325 11326@item n_subsample 11327Set interval for frame subsampling used when computing vmaf. 11328 11329@item enable_conf_interval 11330Enables confidence interval. 11331@end table 11332 11333This filter also supports the @ref{framesync} options. 11334 11335On the below examples the input file @file{main.mpg} being processed is 11336compared with the reference file @file{ref.mpg}. 11337 11338@example 11339ffmpeg -i main.mpg -i ref.mpg -lavfi libvmaf -f null - 11340@end example 11341 11342Example with options: 11343@example 11344ffmpeg -i main.mpg -i ref.mpg -lavfi libvmaf="psnr=1:enable-transform=1" -f null - 11345@end example 11346 11347@section limiter 11348 11349Limits the pixel components values to the specified range [min, max]. 11350 11351The filter accepts the following options: 11352 11353@table @option 11354@item min 11355Lower bound. Defaults to the lowest allowed value for the input. 11356 11357@item max 11358Upper bound. Defaults to the highest allowed value for the input. 11359 11360@item planes 11361Specify which planes will be processed. Defaults to all available. 11362@end table 11363 11364@section loop 11365 11366Loop video frames. 11367 11368The filter accepts the following options: 11369 11370@table @option 11371@item loop 11372Set the number of loops. Setting this value to -1 will result in infinite loops. 11373Default is 0. 11374 11375@item size 11376Set maximal size in number of frames. Default is 0. 11377 11378@item start 11379Set first frame of loop. Default is 0. 11380@end table 11381 11382@subsection Examples 11383 11384@itemize 11385@item 11386Loop single first frame infinitely: 11387@example 11388loop=loop=-1:size=1:start=0 11389@end example 11390 11391@item 11392Loop single first frame 10 times: 11393@example 11394loop=loop=10:size=1:start=0 11395@end example 11396 11397@item 11398Loop 10 first frames 5 times: 11399@example 11400loop=loop=5:size=10:start=0 11401@end example 11402@end itemize 11403 11404@section lut1d 11405 11406Apply a 1D LUT to an input video. 11407 11408The filter accepts the following options: 11409 11410@table @option 11411@item file 11412Set the 1D LUT file name. 11413 11414Currently supported formats: 11415@table @samp 11416@item cube 11417Iridas 11418@end table 11419 11420@item interp 11421Select interpolation mode. 11422 11423Available values are: 11424 11425@table @samp 11426@item nearest 11427Use values from the nearest defined point. 11428@item linear 11429Interpolate values using the linear interpolation. 11430@item cubic 11431Interpolate values using the cubic interpolation. 11432@end table 11433@end table 11434 11435@anchor{lut3d} 11436@section lut3d 11437 11438Apply a 3D LUT to an input video. 11439 11440The filter accepts the following options: 11441 11442@table @option 11443@item file 11444Set the 3D LUT file name. 11445 11446Currently supported formats: 11447@table @samp 11448@item 3dl 11449AfterEffects 11450@item cube 11451Iridas 11452@item dat 11453DaVinci 11454@item m3d 11455Pandora 11456@end table 11457@item interp 11458Select interpolation mode. 11459 11460Available values are: 11461 11462@table @samp 11463@item nearest 11464Use values from the nearest defined point. 11465@item trilinear 11466Interpolate values using the 8 points defining a cube. 11467@item tetrahedral 11468Interpolate values using a tetrahedron. 11469@end table 11470@end table 11471 11472This filter also supports the @ref{framesync} options. 11473 11474@section lumakey 11475 11476Turn certain luma values into transparency. 11477 11478The filter accepts the following options: 11479 11480@table @option 11481@item threshold 11482Set the luma which will be used as base for transparency. 11483Default value is @code{0}. 11484 11485@item tolerance 11486Set the range of luma values to be keyed out. 11487Default value is @code{0}. 11488 11489@item softness 11490Set the range of softness. Default value is @code{0}. 11491Use this to control gradual transition from zero to full transparency. 11492@end table 11493 11494@section lut, lutrgb, lutyuv 11495 11496Compute a look-up table for binding each pixel component input value 11497to an output value, and apply it to the input video. 11498 11499@var{lutyuv} applies a lookup table to a YUV input video, @var{lutrgb} 11500to an RGB input video. 11501 11502These filters accept the following parameters: 11503@table @option 11504@item c0 11505set first pixel component expression 11506@item c1 11507set second pixel component expression 11508@item c2 11509set third pixel component expression 11510@item c3 11511set fourth pixel component expression, corresponds to the alpha component 11512 11513@item r 11514set red component expression 11515@item g 11516set green component expression 11517@item b 11518set blue component expression 11519@item a 11520alpha component expression 11521 11522@item y 11523set Y/luminance component expression 11524@item u 11525set U/Cb component expression 11526@item v 11527set V/Cr component expression 11528@end table 11529 11530Each of them specifies the expression to use for computing the lookup table for 11531the corresponding pixel component values. 11532 11533The exact component associated to each of the @var{c*} options depends on the 11534format in input. 11535 11536The @var{lut} filter requires either YUV or RGB pixel formats in input, 11537@var{lutrgb} requires RGB pixel formats in input, and @var{lutyuv} requires YUV. 11538 11539The expressions can contain the following constants and functions: 11540 11541@table @option 11542@item w 11543@item h 11544The input width and height. 11545 11546@item val 11547The input value for the pixel component. 11548 11549@item clipval 11550The input value, clipped to the @var{minval}-@var{maxval} range. 11551 11552@item maxval 11553The maximum value for the pixel component. 11554 11555@item minval 11556The minimum value for the pixel component. 11557 11558@item negval 11559The negated value for the pixel component value, clipped to the 11560@var{minval}-@var{maxval} range; it corresponds to the expression 11561"maxval-clipval+minval". 11562 11563@item clip(val) 11564The computed value in @var{val}, clipped to the 11565@var{minval}-@var{maxval} range. 11566 11567@item gammaval(gamma) 11568The computed gamma correction value of the pixel component value, 11569clipped to the @var{minval}-@var{maxval} range. It corresponds to the 11570expression 11571"pow((clipval-minval)/(maxval-minval)\,@var{gamma})*(maxval-minval)+minval" 11572 11573@end table 11574 11575All expressions default to "val". 11576 11577@subsection Examples 11578 11579@itemize 11580@item 11581Negate input video: 11582@example 11583lutrgb="r=maxval+minval-val:g=maxval+minval-val:b=maxval+minval-val" 11584lutyuv="y=maxval+minval-val:u=maxval+minval-val:v=maxval+minval-val" 11585@end example 11586 11587The above is the same as: 11588@example 11589lutrgb="r=negval:g=negval:b=negval" 11590lutyuv="y=negval:u=negval:v=negval" 11591@end example 11592 11593@item 11594Negate luminance: 11595@example 11596lutyuv=y=negval 11597@end example 11598 11599@item 11600Remove chroma components, turning the video into a graytone image: 11601@example 11602lutyuv="u=128:v=128" 11603@end example 11604 11605@item 11606Apply a luma burning effect: 11607@example 11608lutyuv="y=2*val" 11609@end example 11610 11611@item 11612Remove green and blue components: 11613@example 11614lutrgb="g=0:b=0" 11615@end example 11616 11617@item 11618Set a constant alpha channel value on input: 11619@example 11620format=rgba,lutrgb=a="maxval-minval/2" 11621@end example 11622 11623@item 11624Correct luminance gamma by a factor of 0.5: 11625@example 11626lutyuv=y=gammaval(0.5) 11627@end example 11628 11629@item 11630Discard least significant bits of luma: 11631@example 11632lutyuv=y='bitand(val, 128+64+32)' 11633@end example 11634 11635@item 11636Technicolor like effect: 11637@example 11638lutyuv=u='(val-maxval/2)*2+maxval/2':v='(val-maxval/2)*2+maxval/2' 11639@end example 11640@end itemize 11641 11642@section lut2, tlut2 11643 11644The @code{lut2} filter takes two input streams and outputs one 11645stream. 11646 11647The @code{tlut2} (time lut2) filter takes two consecutive frames 11648from one single stream. 11649 11650This filter accepts the following parameters: 11651@table @option 11652@item c0 11653set first pixel component expression 11654@item c1 11655set second pixel component expression 11656@item c2 11657set third pixel component expression 11658@item c3 11659set fourth pixel component expression, corresponds to the alpha component 11660@end table 11661 11662Each of them specifies the expression to use for computing the lookup table for 11663the corresponding pixel component values. 11664 11665The exact component associated to each of the @var{c*} options depends on the 11666format in inputs. 11667 11668The expressions can contain the following constants: 11669 11670@table @option 11671@item w 11672@item h 11673The input width and height. 11674 11675@item x 11676The first input value for the pixel component. 11677 11678@item y 11679The second input value for the pixel component. 11680 11681@item bdx 11682The first input video bit depth. 11683 11684@item bdy 11685The second input video bit depth. 11686@end table 11687 11688All expressions default to "x". 11689 11690@subsection Examples 11691 11692@itemize 11693@item 11694Highlight differences between two RGB video streams: 11695@example 11696lut2='ifnot(x-y,0,pow(2,bdx)-1):ifnot(x-y,0,pow(2,bdx)-1):ifnot(x-y,0,pow(2,bdx)-1)' 11697@end example 11698 11699@item 11700Highlight differences between two YUV video streams: 11701@example 11702lut2='ifnot(x-y,0,pow(2,bdx)-1):ifnot(x-y,pow(2,bdx-1),pow(2,bdx)-1):ifnot(x-y,pow(2,bdx-1),pow(2,bdx)-1)' 11703@end example 11704 11705@item 11706Show max difference between two video streams: 11707@example 11708lut2='if(lt(x,y),0,if(gt(x,y),pow(2,bdx)-1,pow(2,bdx-1))):if(lt(x,y),0,if(gt(x,y),pow(2,bdx)-1,pow(2,bdx-1))):if(lt(x,y),0,if(gt(x,y),pow(2,bdx)-1,pow(2,bdx-1)))' 11709@end example 11710@end itemize 11711 11712@section maskedclamp 11713 11714Clamp the first input stream with the second input and third input stream. 11715 11716Returns the value of first stream to be between second input 11717stream - @code{undershoot} and third input stream + @code{overshoot}. 11718 11719This filter accepts the following options: 11720@table @option 11721@item undershoot 11722Default value is @code{0}. 11723 11724@item overshoot 11725Default value is @code{0}. 11726 11727@item planes 11728Set which planes will be processed as bitmap, unprocessed planes will be 11729copied from first stream. 11730By default value 0xf, all planes will be processed. 11731@end table 11732 11733@section maskedmerge 11734 11735Merge the first input stream with the second input stream using per pixel 11736weights in the third input stream. 11737 11738A value of 0 in the third stream pixel component means that pixel component 11739from first stream is returned unchanged, while maximum value (eg. 255 for 117408-bit videos) means that pixel component from second stream is returned 11741unchanged. Intermediate values define the amount of merging between both 11742input stream's pixel components. 11743 11744This filter accepts the following options: 11745@table @option 11746@item planes 11747Set which planes will be processed as bitmap, unprocessed planes will be 11748copied from first stream. 11749By default value 0xf, all planes will be processed. 11750@end table 11751 11752@section mcdeint 11753 11754Apply motion-compensation deinterlacing. 11755 11756It needs one field per frame as input and must thus be used together 11757with yadif=1/3 or equivalent. 11758 11759This filter accepts the following options: 11760@table @option 11761@item mode 11762Set the deinterlacing mode. 11763 11764It accepts one of the following values: 11765@table @samp 11766@item fast 11767@item medium 11768@item slow 11769use iterative motion estimation 11770@item extra_slow 11771like @samp{slow}, but use multiple reference frames. 11772@end table 11773Default value is @samp{fast}. 11774 11775@item parity 11776Set the picture field parity assumed for the input video. It must be 11777one of the following values: 11778 11779@table @samp 11780@item 0, tff 11781assume top field first 11782@item 1, bff 11783assume bottom field first 11784@end table 11785 11786Default value is @samp{bff}. 11787 11788@item qp 11789Set per-block quantization parameter (QP) used by the internal 11790encoder. 11791 11792Higher values should result in a smoother motion vector field but less 11793optimal individual vectors. Default value is 1. 11794@end table 11795 11796@section mergeplanes 11797 11798Merge color channel components from several video streams. 11799 11800The filter accepts up to 4 input streams, and merge selected input 11801planes to the output video. 11802 11803This filter accepts the following options: 11804@table @option 11805@item mapping 11806Set input to output plane mapping. Default is @code{0}. 11807 11808The mappings is specified as a bitmap. It should be specified as a 11809hexadecimal number in the form 0xAa[Bb[Cc[Dd]]]. 'Aa' describes the 11810mapping for the first plane of the output stream. 'A' sets the number of 11811the input stream to use (from 0 to 3), and 'a' the plane number of the 11812corresponding input to use (from 0 to 3). The rest of the mappings is 11813similar, 'Bb' describes the mapping for the output stream second 11814plane, 'Cc' describes the mapping for the output stream third plane and 11815'Dd' describes the mapping for the output stream fourth plane. 11816 11817@item format 11818Set output pixel format. Default is @code{yuva444p}. 11819@end table 11820 11821@subsection Examples 11822 11823@itemize 11824@item 11825Merge three gray video streams of same width and height into single video stream: 11826@example 11827[a0][a1][a2]mergeplanes=0x001020:yuv444p 11828@end example 11829 11830@item 11831Merge 1st yuv444p stream and 2nd gray video stream into yuva444p video stream: 11832@example 11833[a0][a1]mergeplanes=0x00010210:yuva444p 11834@end example 11835 11836@item 11837Swap Y and A plane in yuva444p stream: 11838@example 11839format=yuva444p,mergeplanes=0x03010200:yuva444p 11840@end example 11841 11842@item 11843Swap U and V plane in yuv420p stream: 11844@example 11845format=yuv420p,mergeplanes=0x000201:yuv420p 11846@end example 11847 11848@item 11849Cast a rgb24 clip to yuv444p: 11850@example 11851format=rgb24,mergeplanes=0x000102:yuv444p 11852@end example 11853@end itemize 11854 11855@section mestimate 11856 11857Estimate and export motion vectors using block matching algorithms. 11858Motion vectors are stored in frame side data to be used by other filters. 11859 11860This filter accepts the following options: 11861@table @option 11862@item method 11863Specify the motion estimation method. Accepts one of the following values: 11864 11865@table @samp 11866@item esa 11867Exhaustive search algorithm. 11868@item tss 11869Three step search algorithm. 11870@item tdls 11871Two dimensional logarithmic search algorithm. 11872@item ntss 11873New three step search algorithm. 11874@item fss 11875Four step search algorithm. 11876@item ds 11877Diamond search algorithm. 11878@item hexbs 11879Hexagon-based search algorithm. 11880@item epzs 11881Enhanced predictive zonal search algorithm. 11882@item umh 11883Uneven multi-hexagon search algorithm. 11884@end table 11885Default value is @samp{esa}. 11886 11887@item mb_size 11888Macroblock size. Default @code{16}. 11889 11890@item search_param 11891Search parameter. Default @code{7}. 11892@end table 11893 11894@section midequalizer 11895 11896Apply Midway Image Equalization effect using two video streams. 11897 11898Midway Image Equalization adjusts a pair of images to have the same 11899histogram, while maintaining their dynamics as much as possible. It's 11900useful for e.g. matching exposures from a pair of stereo cameras. 11901 11902This filter has two inputs and one output, which must be of same pixel format, but 11903may be of different sizes. The output of filter is first input adjusted with 11904midway histogram of both inputs. 11905 11906This filter accepts the following option: 11907 11908@table @option 11909@item planes 11910Set which planes to process. Default is @code{15}, which is all available planes. 11911@end table 11912 11913@section minterpolate 11914 11915Convert the video to specified frame rate using motion interpolation. 11916 11917This filter accepts the following options: 11918@table @option 11919@item fps 11920Specify the output frame rate. This can be rational e.g. @code{60000/1001}. Frames are dropped if @var{fps} is lower than source fps. Default @code{60}. 11921 11922@item mi_mode 11923Motion interpolation mode. Following values are accepted: 11924@table @samp 11925@item dup 11926Duplicate previous or next frame for interpolating new ones. 11927@item blend 11928Blend source frames. Interpolated frame is mean of previous and next frames. 11929@item mci 11930Motion compensated interpolation. Following options are effective when this mode is selected: 11931 11932@table @samp 11933@item mc_mode 11934Motion compensation mode. Following values are accepted: 11935@table @samp 11936@item obmc 11937Overlapped block motion compensation. 11938@item aobmc 11939Adaptive overlapped block motion compensation. Window weighting coefficients are controlled adaptively according to the reliabilities of the neighboring motion vectors to reduce oversmoothing. 11940@end table 11941Default mode is @samp{obmc}. 11942 11943@item me_mode 11944Motion estimation mode. Following values are accepted: 11945@table @samp 11946@item bidir 11947Bidirectional motion estimation. Motion vectors are estimated for each source frame in both forward and backward directions. 11948@item bilat 11949Bilateral motion estimation. Motion vectors are estimated directly for interpolated frame. 11950@end table 11951Default mode is @samp{bilat}. 11952 11953@item me 11954The algorithm to be used for motion estimation. Following values are accepted: 11955@table @samp 11956@item esa 11957Exhaustive search algorithm. 11958@item tss 11959Three step search algorithm. 11960@item tdls 11961Two dimensional logarithmic search algorithm. 11962@item ntss 11963New three step search algorithm. 11964@item fss 11965Four step search algorithm. 11966@item ds 11967Diamond search algorithm. 11968@item hexbs 11969Hexagon-based search algorithm. 11970@item epzs 11971Enhanced predictive zonal search algorithm. 11972@item umh 11973Uneven multi-hexagon search algorithm. 11974@end table 11975Default algorithm is @samp{epzs}. 11976 11977@item mb_size 11978Macroblock size. Default @code{16}. 11979 11980@item search_param 11981Motion estimation search parameter. Default @code{32}. 11982 11983@item vsbmc 11984Enable variable-size block motion compensation. Motion estimation is applied with smaller block sizes at object boundaries in order to make the them less blur. Default is @code{0} (disabled). 11985@end table 11986@end table 11987 11988@item scd 11989Scene change detection method. Scene change leads motion vectors to be in random direction. Scene change detection replace interpolated frames by duplicate ones. May not be needed for other modes. Following values are accepted: 11990@table @samp 11991@item none 11992Disable scene change detection. 11993@item fdiff 11994Frame difference. Corresponding pixel values are compared and if it satisfies @var{scd_threshold} scene change is detected. 11995@end table 11996Default method is @samp{fdiff}. 11997 11998@item scd_threshold 11999Scene change detection threshold. Default is @code{5.0}. 12000@end table 12001 12002@section mix 12003 12004Mix several video input streams into one video stream. 12005 12006A description of the accepted options follows. 12007 12008@table @option 12009@item nb_inputs 12010The number of inputs. If unspecified, it defaults to 2. 12011 12012@item weights 12013Specify weight of each input video stream as sequence. 12014Each weight is separated by space. If number of weights 12015is smaller than number of @var{frames} last specified 12016weight will be used for all remaining unset weights. 12017 12018@item scale 12019Specify scale, if it is set it will be multiplied with sum 12020of each weight multiplied with pixel values to give final destination 12021pixel value. By default @var{scale} is auto scaled to sum of weights. 12022 12023@item duration 12024Specify how end of stream is determined. 12025@table @samp 12026@item longest 12027The duration of the longest input. (default) 12028 12029@item shortest 12030The duration of the shortest input. 12031 12032@item first 12033The duration of the first input. 12034@end table 12035@end table 12036 12037@section mpdecimate 12038 12039Drop frames that do not differ greatly from the previous frame in 12040order to reduce frame rate. 12041 12042The main use of this filter is for very-low-bitrate encoding 12043(e.g. streaming over dialup modem), but it could in theory be used for 12044fixing movies that were inverse-telecined incorrectly. 12045 12046A description of the accepted options follows. 12047 12048@table @option 12049@item max 12050Set the maximum number of consecutive frames which can be dropped (if 12051positive), or the minimum interval between dropped frames (if 12052negative). If the value is 0, the frame is dropped disregarding the 12053number of previous sequentially dropped frames. 12054 12055Default value is 0. 12056 12057@item hi 12058@item lo 12059@item frac 12060Set the dropping threshold values. 12061 12062Values for @option{hi} and @option{lo} are for 8x8 pixel blocks and 12063represent actual pixel value differences, so a threshold of 64 12064corresponds to 1 unit of difference for each pixel, or the same spread 12065out differently over the block. 12066 12067A frame is a candidate for dropping if no 8x8 blocks differ by more 12068than a threshold of @option{hi}, and if no more than @option{frac} blocks (1 12069meaning the whole image) differ by more than a threshold of @option{lo}. 12070 12071Default value for @option{hi} is 64*12, default value for @option{lo} is 1207264*5, and default value for @option{frac} is 0.33. 12073@end table 12074 12075 12076@section negate 12077 12078Negate (invert) the input video. 12079 12080It accepts the following option: 12081 12082@table @option 12083 12084@item negate_alpha 12085With value 1, it negates the alpha component, if present. Default value is 0. 12086@end table 12087 12088@anchor{nlmeans} 12089@section nlmeans 12090 12091Denoise frames using Non-Local Means algorithm. 12092 12093Each pixel is adjusted by looking for other pixels with similar contexts. This 12094context similarity is defined by comparing their surrounding patches of size 12095@option{p}x@option{p}. Patches are searched in an area of @option{r}x@option{r} 12096around the pixel. 12097 12098Note that the research area defines centers for patches, which means some 12099patches will be made of pixels outside that research area. 12100 12101The filter accepts the following options. 12102 12103@table @option 12104@item s 12105Set denoising strength. 12106 12107@item p 12108Set patch size. 12109 12110@item pc 12111Same as @option{p} but for chroma planes. 12112 12113The default value is @var{0} and means automatic. 12114 12115@item r 12116Set research size. 12117 12118@item rc 12119Same as @option{r} but for chroma planes. 12120 12121The default value is @var{0} and means automatic. 12122@end table 12123 12124@section nnedi 12125 12126Deinterlace video using neural network edge directed interpolation. 12127 12128This filter accepts the following options: 12129 12130@table @option 12131@item weights 12132Mandatory option, without binary file filter can not work. 12133Currently file can be found here: 12134https://github.com/dubhater/vapoursynth-nnedi3/blob/master/src/nnedi3_weights.bin 12135 12136@item deint 12137Set which frames to deinterlace, by default it is @code{all}. 12138Can be @code{all} or @code{interlaced}. 12139 12140@item field 12141Set mode of operation. 12142 12143Can be one of the following: 12144 12145@table @samp 12146@item af 12147Use frame flags, both fields. 12148@item a 12149Use frame flags, single field. 12150@item t 12151Use top field only. 12152@item b 12153Use bottom field only. 12154@item tf 12155Use both fields, top first. 12156@item bf 12157Use both fields, bottom first. 12158@end table 12159 12160@item planes 12161Set which planes to process, by default filter process all frames. 12162 12163@item nsize 12164Set size of local neighborhood around each pixel, used by the predictor neural 12165network. 12166 12167Can be one of the following: 12168 12169@table @samp 12170@item s8x6 12171@item s16x6 12172@item s32x6 12173@item s48x6 12174@item s8x4 12175@item s16x4 12176@item s32x4 12177@end table 12178 12179@item nns 12180Set the number of neurons in predictor neural network. 12181Can be one of the following: 12182 12183@table @samp 12184@item n16 12185@item n32 12186@item n64 12187@item n128 12188@item n256 12189@end table 12190 12191@item qual 12192Controls the number of different neural network predictions that are blended 12193together to compute the final output value. Can be @code{fast}, default or 12194@code{slow}. 12195 12196@item etype 12197Set which set of weights to use in the predictor. 12198Can be one of the following: 12199 12200@table @samp 12201@item a 12202weights trained to minimize absolute error 12203@item s 12204weights trained to minimize squared error 12205@end table 12206 12207@item pscrn 12208Controls whether or not the prescreener neural network is used to decide 12209which pixels should be processed by the predictor neural network and which 12210can be handled by simple cubic interpolation. 12211The prescreener is trained to know whether cubic interpolation will be 12212sufficient for a pixel or whether it should be predicted by the predictor nn. 12213The computational complexity of the prescreener nn is much less than that of 12214the predictor nn. Since most pixels can be handled by cubic interpolation, 12215using the prescreener generally results in much faster processing. 12216The prescreener is pretty accurate, so the difference between using it and not 12217using it is almost always unnoticeable. 12218 12219Can be one of the following: 12220 12221@table @samp 12222@item none 12223@item original 12224@item new 12225@end table 12226 12227Default is @code{new}. 12228 12229@item fapprox 12230Set various debugging flags. 12231@end table 12232 12233@section noformat 12234 12235Force libavfilter not to use any of the specified pixel formats for the 12236input to the next filter. 12237 12238It accepts the following parameters: 12239@table @option 12240 12241@item pix_fmts 12242A '|'-separated list of pixel format names, such as 12243pix_fmts=yuv420p|monow|rgb24". 12244 12245@end table 12246 12247@subsection Examples 12248 12249@itemize 12250@item 12251Force libavfilter to use a format different from @var{yuv420p} for the 12252input to the vflip filter: 12253@example 12254noformat=pix_fmts=yuv420p,vflip 12255@end example 12256 12257@item 12258Convert the input video to any of the formats not contained in the list: 12259@example 12260noformat=yuv420p|yuv444p|yuv410p 12261@end example 12262@end itemize 12263 12264@section noise 12265 12266Add noise on video input frame. 12267 12268The filter accepts the following options: 12269 12270@table @option 12271@item all_seed 12272@item c0_seed 12273@item c1_seed 12274@item c2_seed 12275@item c3_seed 12276Set noise seed for specific pixel component or all pixel components in case 12277of @var{all_seed}. Default value is @code{123457}. 12278 12279@item all_strength, alls 12280@item c0_strength, c0s 12281@item c1_strength, c1s 12282@item c2_strength, c2s 12283@item c3_strength, c3s 12284Set noise strength for specific pixel component or all pixel components in case 12285@var{all_strength}. Default value is @code{0}. Allowed range is [0, 100]. 12286 12287@item all_flags, allf 12288@item c0_flags, c0f 12289@item c1_flags, c1f 12290@item c2_flags, c2f 12291@item c3_flags, c3f 12292Set pixel component flags or set flags for all components if @var{all_flags}. 12293Available values for component flags are: 12294@table @samp 12295@item a 12296averaged temporal noise (smoother) 12297@item p 12298mix random noise with a (semi)regular pattern 12299@item t 12300temporal noise (noise pattern changes between frames) 12301@item u 12302uniform noise (gaussian otherwise) 12303@end table 12304@end table 12305 12306@subsection Examples 12307 12308Add temporal and uniform noise to input video: 12309@example 12310noise=alls=20:allf=t+u 12311@end example 12312 12313@section normalize 12314 12315Normalize RGB video (aka histogram stretching, contrast stretching). 12316See: https://en.wikipedia.org/wiki/Normalization_(image_processing) 12317 12318For each channel of each frame, the filter computes the input range and maps 12319it linearly to the user-specified output range. The output range defaults 12320to the full dynamic range from pure black to pure white. 12321 12322Temporal smoothing can be used on the input range to reduce flickering (rapid 12323changes in brightness) caused when small dark or bright objects enter or leave 12324the scene. This is similar to the auto-exposure (automatic gain control) on a 12325video camera, and, like a video camera, it may cause a period of over- or 12326under-exposure of the video. 12327 12328The R,G,B channels can be normalized independently, which may cause some 12329color shifting, or linked together as a single channel, which prevents 12330color shifting. Linked normalization preserves hue. Independent normalization 12331does not, so it can be used to remove some color casts. Independent and linked 12332normalization can be combined in any ratio. 12333 12334The normalize filter accepts the following options: 12335 12336@table @option 12337@item blackpt 12338@item whitept 12339Colors which define the output range. The minimum input value is mapped to 12340the @var{blackpt}. The maximum input value is mapped to the @var{whitept}. 12341The defaults are black and white respectively. Specifying white for 12342@var{blackpt} and black for @var{whitept} will give color-inverted, 12343normalized video. Shades of grey can be used to reduce the dynamic range 12344(contrast). Specifying saturated colors here can create some interesting 12345effects. 12346 12347@item smoothing 12348The number of previous frames to use for temporal smoothing. The input range 12349of each channel is smoothed using a rolling average over the current frame 12350and the @var{smoothing} previous frames. The default is 0 (no temporal 12351smoothing). 12352 12353@item independence 12354Controls the ratio of independent (color shifting) channel normalization to 12355linked (color preserving) normalization. 0.0 is fully linked, 1.0 is fully 12356independent. Defaults to 1.0 (fully independent). 12357 12358@item strength 12359Overall strength of the filter. 1.0 is full strength. 0.0 is a rather 12360expensive no-op. Defaults to 1.0 (full strength). 12361 12362@end table 12363 12364@subsection Examples 12365 12366Stretch video contrast to use the full dynamic range, with no temporal 12367smoothing; may flicker depending on the source content: 12368@example 12369normalize=blackpt=black:whitept=white:smoothing=0 12370@end example 12371 12372As above, but with 50 frames of temporal smoothing; flicker should be 12373reduced, depending on the source content: 12374@example 12375normalize=blackpt=black:whitept=white:smoothing=50 12376@end example 12377 12378As above, but with hue-preserving linked channel normalization: 12379@example 12380normalize=blackpt=black:whitept=white:smoothing=50:independence=0 12381@end example 12382 12383As above, but with half strength: 12384@example 12385normalize=blackpt=black:whitept=white:smoothing=50:independence=0:strength=0.5 12386@end example 12387 12388Map the darkest input color to red, the brightest input color to cyan: 12389@example 12390normalize=blackpt=red:whitept=cyan 12391@end example 12392 12393@section null 12394 12395Pass the video source unchanged to the output. 12396 12397@section ocr 12398Optical Character Recognition 12399 12400This filter uses Tesseract for optical character recognition. To enable 12401compilation of this filter, you need to configure FFmpeg with 12402@code{--enable-libtesseract}. 12403 12404It accepts the following options: 12405 12406@table @option 12407@item datapath 12408Set datapath to tesseract data. Default is to use whatever was 12409set at installation. 12410 12411@item language 12412Set language, default is "eng". 12413 12414@item whitelist 12415Set character whitelist. 12416 12417@item blacklist 12418Set character blacklist. 12419@end table 12420 12421The filter exports recognized text as the frame metadata @code{lavfi.ocr.text}. 12422 12423@section ocv 12424 12425Apply a video transform using libopencv. 12426 12427To enable this filter, install the libopencv library and headers and 12428configure FFmpeg with @code{--enable-libopencv}. 12429 12430It accepts the following parameters: 12431 12432@table @option 12433 12434@item filter_name 12435The name of the libopencv filter to apply. 12436 12437@item filter_params 12438The parameters to pass to the libopencv filter. If not specified, the default 12439values are assumed. 12440 12441@end table 12442 12443Refer to the official libopencv documentation for more precise 12444information: 12445@url{http://docs.opencv.org/master/modules/imgproc/doc/filtering.html} 12446 12447Several libopencv filters are supported; see the following subsections. 12448 12449@anchor{dilate} 12450@subsection dilate 12451 12452Dilate an image by using a specific structuring element. 12453It corresponds to the libopencv function @code{cvDilate}. 12454 12455It accepts the parameters: @var{struct_el}|@var{nb_iterations}. 12456 12457@var{struct_el} represents a structuring element, and has the syntax: 12458@var{cols}x@var{rows}+@var{anchor_x}x@var{anchor_y}/@var{shape} 12459 12460@var{cols} and @var{rows} represent the number of columns and rows of 12461the structuring element, @var{anchor_x} and @var{anchor_y} the anchor 12462point, and @var{shape} the shape for the structuring element. @var{shape} 12463must be "rect", "cross", "ellipse", or "custom". 12464 12465If the value for @var{shape} is "custom", it must be followed by a 12466string of the form "=@var{filename}". The file with name 12467@var{filename} is assumed to represent a binary image, with each 12468printable character corresponding to a bright pixel. When a custom 12469@var{shape} is used, @var{cols} and @var{rows} are ignored, the number 12470or columns and rows of the read file are assumed instead. 12471 12472The default value for @var{struct_el} is "3x3+0x0/rect". 12473 12474@var{nb_iterations} specifies the number of times the transform is 12475applied to the image, and defaults to 1. 12476 12477Some examples: 12478@example 12479# Use the default values 12480ocv=dilate 12481 12482# Dilate using a structuring element with a 5x5 cross, iterating two times 12483ocv=filter_name=dilate:filter_params=5x5+2x2/cross|2 12484 12485# Read the shape from the file diamond.shape, iterating two times. 12486# The file diamond.shape may contain a pattern of characters like this 12487# * 12488# *** 12489# ***** 12490# *** 12491# * 12492# The specified columns and rows are ignored 12493# but the anchor point coordinates are not 12494ocv=dilate:0x0+2x2/custom=diamond.shape|2 12495@end example 12496 12497@subsection erode 12498 12499Erode an image by using a specific structuring element. 12500It corresponds to the libopencv function @code{cvErode}. 12501 12502It accepts the parameters: @var{struct_el}:@var{nb_iterations}, 12503with the same syntax and semantics as the @ref{dilate} filter. 12504 12505@subsection smooth 12506 12507Smooth the input video. 12508 12509The filter takes the following parameters: 12510@var{type}|@var{param1}|@var{param2}|@var{param3}|@var{param4}. 12511 12512@var{type} is the type of smooth filter to apply, and must be one of 12513the following values: "blur", "blur_no_scale", "median", "gaussian", 12514or "bilateral". The default value is "gaussian". 12515 12516The meaning of @var{param1}, @var{param2}, @var{param3}, and @var{param4} 12517depend on the smooth type. @var{param1} and 12518@var{param2} accept integer positive values or 0. @var{param3} and 12519@var{param4} accept floating point values. 12520 12521The default value for @var{param1} is 3. The default value for the 12522other parameters is 0. 12523 12524These parameters correspond to the parameters assigned to the 12525libopencv function @code{cvSmooth}. 12526 12527@section oscilloscope 12528 125292D Video Oscilloscope. 12530 12531Useful to measure spatial impulse, step responses, chroma delays, etc. 12532 12533It accepts the following parameters: 12534 12535@table @option 12536@item x 12537Set scope center x position. 12538 12539@item y 12540Set scope center y position. 12541 12542@item s 12543Set scope size, relative to frame diagonal. 12544 12545@item t 12546Set scope tilt/rotation. 12547 12548@item o 12549Set trace opacity. 12550 12551@item tx 12552Set trace center x position. 12553 12554@item ty 12555Set trace center y position. 12556 12557@item tw 12558Set trace width, relative to width of frame. 12559 12560@item th 12561Set trace height, relative to height of frame. 12562 12563@item c 12564Set which components to trace. By default it traces first three components. 12565 12566@item g 12567Draw trace grid. By default is enabled. 12568 12569@item st 12570Draw some statistics. By default is enabled. 12571 12572@item sc 12573Draw scope. By default is enabled. 12574@end table 12575 12576@subsection Examples 12577 12578@itemize 12579@item 12580Inspect full first row of video frame. 12581@example 12582oscilloscope=x=0.5:y=0:s=1 12583@end example 12584 12585@item 12586Inspect full last row of video frame. 12587@example 12588oscilloscope=x=0.5:y=1:s=1 12589@end example 12590 12591@item 12592Inspect full 5th line of video frame of height 1080. 12593@example 12594oscilloscope=x=0.5:y=5/1080:s=1 12595@end example 12596 12597@item 12598Inspect full last column of video frame. 12599@example 12600oscilloscope=x=1:y=0.5:s=1:t=1 12601@end example 12602 12603@end itemize 12604 12605@anchor{overlay} 12606@section overlay 12607 12608Overlay one video on top of another. 12609 12610It takes two inputs and has one output. The first input is the "main" 12611video on which the second input is overlaid. 12612 12613It accepts the following parameters: 12614 12615A description of the accepted options follows. 12616 12617@table @option 12618@item x 12619@item y 12620Set the expression for the x and y coordinates of the overlaid video 12621on the main video. Default value is "0" for both expressions. In case 12622the expression is invalid, it is set to a huge value (meaning that the 12623overlay will not be displayed within the output visible area). 12624 12625@item eof_action 12626See @ref{framesync}. 12627 12628@item eval 12629Set when the expressions for @option{x}, and @option{y} are evaluated. 12630 12631It accepts the following values: 12632@table @samp 12633@item init 12634only evaluate expressions once during the filter initialization or 12635when a command is processed 12636 12637@item frame 12638evaluate expressions for each incoming frame 12639@end table 12640 12641Default value is @samp{frame}. 12642 12643@item shortest 12644See @ref{framesync}. 12645 12646@item format 12647Set the format for the output video. 12648 12649It accepts the following values: 12650@table @samp 12651@item yuv420 12652force YUV420 output 12653 12654@item yuv422 12655force YUV422 output 12656 12657@item yuv444 12658force YUV444 output 12659 12660@item rgb 12661force packed RGB output 12662 12663@item gbrp 12664force planar RGB output 12665 12666@item auto 12667automatically pick format 12668@end table 12669 12670Default value is @samp{yuv420}. 12671 12672@item repeatlast 12673See @ref{framesync}. 12674 12675@item alpha 12676Set format of alpha of the overlaid video, it can be @var{straight} or 12677@var{premultiplied}. Default is @var{straight}. 12678@end table 12679 12680The @option{x}, and @option{y} expressions can contain the following 12681parameters. 12682 12683@table @option 12684@item main_w, W 12685@item main_h, H 12686The main input width and height. 12687 12688@item overlay_w, w 12689@item overlay_h, h 12690The overlay input width and height. 12691 12692@item x 12693@item y 12694The computed values for @var{x} and @var{y}. They are evaluated for 12695each new frame. 12696 12697@item hsub 12698@item vsub 12699horizontal and vertical chroma subsample values of the output 12700format. For example for the pixel format "yuv422p" @var{hsub} is 2 and 12701@var{vsub} is 1. 12702 12703@item n 12704the number of input frame, starting from 0 12705 12706@item pos 12707the position in the file of the input frame, NAN if unknown 12708 12709@item t 12710The timestamp, expressed in seconds. It's NAN if the input timestamp is unknown. 12711 12712@end table 12713 12714This filter also supports the @ref{framesync} options. 12715 12716Note that the @var{n}, @var{pos}, @var{t} variables are available only 12717when evaluation is done @emph{per frame}, and will evaluate to NAN 12718when @option{eval} is set to @samp{init}. 12719 12720Be aware that frames are taken from each input video in timestamp 12721order, hence, if their initial timestamps differ, it is a good idea 12722to pass the two inputs through a @var{setpts=PTS-STARTPTS} filter to 12723have them begin in the same zero timestamp, as the example for 12724the @var{movie} filter does. 12725 12726You can chain together more overlays but you should test the 12727efficiency of such approach. 12728 12729@subsection Commands 12730 12731This filter supports the following commands: 12732@table @option 12733@item x 12734@item y 12735Modify the x and y of the overlay input. 12736The command accepts the same syntax of the corresponding option. 12737 12738If the specified expression is not valid, it is kept at its current 12739value. 12740@end table 12741 12742@subsection Examples 12743 12744@itemize 12745@item 12746Draw the overlay at 10 pixels from the bottom right corner of the main 12747video: 12748@example 12749overlay=main_w-overlay_w-10:main_h-overlay_h-10 12750@end example 12751 12752Using named options the example above becomes: 12753@example 12754overlay=x=main_w-overlay_w-10:y=main_h-overlay_h-10 12755@end example 12756 12757@item 12758Insert a transparent PNG logo in the bottom left corner of the input, 12759using the @command{ffmpeg} tool with the @code{-filter_complex} option: 12760@example 12761ffmpeg -i input -i logo -filter_complex 'overlay=10:main_h-overlay_h-10' output 12762@end example 12763 12764@item 12765Insert 2 different transparent PNG logos (second logo on bottom 12766right corner) using the @command{ffmpeg} tool: 12767@example 12768ffmpeg -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 12769@end example 12770 12771@item 12772Add a transparent color layer on top of the main video; @code{WxH} 12773must specify the size of the main input to the overlay filter: 12774@example 12775color=color=red@@.3:size=WxH [over]; [in][over] overlay [out] 12776@end example 12777 12778@item 12779Play an original video and a filtered version (here with the deshake 12780filter) side by side using the @command{ffplay} tool: 12781@example 12782ffplay input.avi -vf 'split[a][b]; [a]pad=iw*2:ih[src]; [b]deshake[filt]; [src][filt]overlay=w' 12783@end example 12784 12785The above command is the same as: 12786@example 12787ffplay input.avi -vf 'split[b], pad=iw*2[src], [b]deshake, [src]overlay=w' 12788@end example 12789 12790@item 12791Make a sliding overlay appearing from the left to the right top part of the 12792screen starting since time 2: 12793@example 12794overlay=x='if(gte(t,2), -w+(t-2)*20, NAN)':y=0 12795@end example 12796 12797@item 12798Compose output by putting two input videos side to side: 12799@example 12800ffmpeg -i left.avi -i right.avi -filter_complex " 12801nullsrc=size=200x100 [background]; 12802[0:v] setpts=PTS-STARTPTS, scale=100x100 [left]; 12803[1:v] setpts=PTS-STARTPTS, scale=100x100 [right]; 12804[background][left] overlay=shortest=1 [background+left]; 12805[background+left][right] overlay=shortest=1:x=100 [left+right] 12806" 12807@end example 12808 12809@item 12810Mask 10-20 seconds of a video by applying the delogo filter to a section 12811@example 12812ffmpeg -i test.avi -codec:v:0 wmv2 -ar 11025 -b:v 9000k 12813-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]' 12814masked.avi 12815@end example 12816 12817@item 12818Chain several overlays in cascade: 12819@example 12820nullsrc=s=200x200 [bg]; 12821testsrc=s=100x100, split=4 [in0][in1][in2][in3]; 12822[in0] lutrgb=r=0, [bg] overlay=0:0 [mid0]; 12823[in1] lutrgb=g=0, [mid0] overlay=100:0 [mid1]; 12824[in2] lutrgb=b=0, [mid1] overlay=0:100 [mid2]; 12825[in3] null, [mid2] overlay=100:100 [out0] 12826@end example 12827 12828@end itemize 12829 12830@section owdenoise 12831 12832Apply Overcomplete Wavelet denoiser. 12833 12834The filter accepts the following options: 12835 12836@table @option 12837@item depth 12838Set depth. 12839 12840Larger depth values will denoise lower frequency components more, but 12841slow down filtering. 12842 12843Must be an int in the range 8-16, default is @code{8}. 12844 12845@item luma_strength, ls 12846Set luma strength. 12847 12848Must be a double value in the range 0-1000, default is @code{1.0}. 12849 12850@item chroma_strength, cs 12851Set chroma strength. 12852 12853Must be a double value in the range 0-1000, default is @code{1.0}. 12854@end table 12855 12856@anchor{pad} 12857@section pad 12858 12859Add paddings to the input image, and place the original input at the 12860provided @var{x}, @var{y} coordinates. 12861 12862It accepts the following parameters: 12863 12864@table @option 12865@item width, w 12866@item height, h 12867Specify an expression for the size of the output image with the 12868paddings added. If the value for @var{width} or @var{height} is 0, the 12869corresponding input size is used for the output. 12870 12871The @var{width} expression can reference the value set by the 12872@var{height} expression, and vice versa. 12873 12874The default value of @var{width} and @var{height} is 0. 12875 12876@item x 12877@item y 12878Specify the offsets to place the input image at within the padded area, 12879with respect to the top/left border of the output image. 12880 12881The @var{x} expression can reference the value set by the @var{y} 12882expression, and vice versa. 12883 12884The default value of @var{x} and @var{y} is 0. 12885 12886If @var{x} or @var{y} evaluate to a negative number, they'll be changed 12887so the input image is centered on the padded area. 12888 12889@item color 12890Specify the color of the padded area. For the syntax of this option, 12891check the @ref{color syntax,,"Color" section in the ffmpeg-utils 12892manual,ffmpeg-utils}. 12893 12894The default value of @var{color} is "black". 12895 12896@item eval 12897Specify when to evaluate @var{width}, @var{height}, @var{x} and @var{y} expression. 12898 12899It accepts the following values: 12900 12901@table @samp 12902@item init 12903Only evaluate expressions once during the filter initialization or when 12904a command is processed. 12905 12906@item frame 12907Evaluate expressions for each incoming frame. 12908 12909@end table 12910 12911Default value is @samp{init}. 12912 12913@item aspect 12914Pad to aspect instead to a resolution. 12915 12916@end table 12917 12918The value for the @var{width}, @var{height}, @var{x}, and @var{y} 12919options are expressions containing the following constants: 12920 12921@table @option 12922@item in_w 12923@item in_h 12924The input video width and height. 12925 12926@item iw 12927@item ih 12928These are the same as @var{in_w} and @var{in_h}. 12929 12930@item out_w 12931@item out_h 12932The output width and height (the size of the padded area), as 12933specified by the @var{width} and @var{height} expressions. 12934 12935@item ow 12936@item oh 12937These are the same as @var{out_w} and @var{out_h}. 12938 12939@item x 12940@item y 12941The x and y offsets as specified by the @var{x} and @var{y} 12942expressions, or NAN if not yet specified. 12943 12944@item a 12945same as @var{iw} / @var{ih} 12946 12947@item sar 12948input sample aspect ratio 12949 12950@item dar 12951input display aspect ratio, it is the same as (@var{iw} / @var{ih}) * @var{sar} 12952 12953@item hsub 12954@item vsub 12955The horizontal and vertical chroma subsample values. For example for the 12956pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1. 12957@end table 12958 12959@subsection Examples 12960 12961@itemize 12962@item 12963Add paddings with the color "violet" to the input video. The output video 12964size is 640x480, and the top-left corner of the input video is placed at 12965column 0, row 40 12966@example 12967pad=640:480:0:40:violet 12968@end example 12969 12970The example above is equivalent to the following command: 12971@example 12972pad=width=640:height=480:x=0:y=40:color=violet 12973@end example 12974 12975@item 12976Pad the input to get an output with dimensions increased by 3/2, 12977and put the input video at the center of the padded area: 12978@example 12979pad="3/2*iw:3/2*ih:(ow-iw)/2:(oh-ih)/2" 12980@end example 12981 12982@item 12983Pad the input to get a squared output with size equal to the maximum 12984value between the input width and height, and put the input video at 12985the center of the padded area: 12986@example 12987pad="max(iw\,ih):ow:(ow-iw)/2:(oh-ih)/2" 12988@end example 12989 12990@item 12991Pad the input to get a final w/h ratio of 16:9: 12992@example 12993pad="ih*16/9:ih:(ow-iw)/2:(oh-ih)/2" 12994@end example 12995 12996@item 12997In case of anamorphic video, in order to set the output display aspect 12998correctly, it is necessary to use @var{sar} in the expression, 12999according to the relation: 13000@example 13001(ih * X / ih) * sar = output_dar 13002X = output_dar / sar 13003@end example 13004 13005Thus the previous example needs to be modified to: 13006@example 13007pad="ih*16/9/sar:ih:(ow-iw)/2:(oh-ih)/2" 13008@end example 13009 13010@item 13011Double the output size and put the input video in the bottom-right 13012corner of the output padded area: 13013@example 13014pad="2*iw:2*ih:ow-iw:oh-ih" 13015@end example 13016@end itemize 13017 13018@anchor{palettegen} 13019@section palettegen 13020 13021Generate one palette for a whole video stream. 13022 13023It accepts the following options: 13024 13025@table @option 13026@item max_colors 13027Set the maximum number of colors to quantize in the palette. 13028Note: the palette will still contain 256 colors; the unused palette entries 13029will be black. 13030 13031@item reserve_transparent 13032Create a palette of 255 colors maximum and reserve the last one for 13033transparency. Reserving the transparency color is useful for GIF optimization. 13034If not set, the maximum of colors in the palette will be 256. You probably want 13035to disable this option for a standalone image. 13036Set by default. 13037 13038@item transparency_color 13039Set the color that will be used as background for transparency. 13040 13041@item stats_mode 13042Set statistics mode. 13043 13044It accepts the following values: 13045@table @samp 13046@item full 13047Compute full frame histograms. 13048@item diff 13049Compute histograms only for the part that differs from previous frame. This 13050might be relevant to give more importance to the moving part of your input if 13051the background is static. 13052@item single 13053Compute new histogram for each frame. 13054@end table 13055 13056Default value is @var{full}. 13057@end table 13058 13059The filter also exports the frame metadata @code{lavfi.color_quant_ratio} 13060(@code{nb_color_in / nb_color_out}) which you can use to evaluate the degree of 13061color quantization of the palette. This information is also visible at 13062@var{info} logging level. 13063 13064@subsection Examples 13065 13066@itemize 13067@item 13068Generate a representative palette of a given video using @command{ffmpeg}: 13069@example 13070ffmpeg -i input.mkv -vf palettegen palette.png 13071@end example 13072@end itemize 13073 13074@section paletteuse 13075 13076Use a palette to downsample an input video stream. 13077 13078The filter takes two inputs: one video stream and a palette. The palette must 13079be a 256 pixels image. 13080 13081It accepts the following options: 13082 13083@table @option 13084@item dither 13085Select dithering mode. Available algorithms are: 13086@table @samp 13087@item bayer 13088Ordered 8x8 bayer dithering (deterministic) 13089@item heckbert 13090Dithering as defined by Paul Heckbert in 1982 (simple error diffusion). 13091Note: this dithering is sometimes considered "wrong" and is included as a 13092reference. 13093@item floyd_steinberg 13094Floyd and Steingberg dithering (error diffusion) 13095@item sierra2 13096Frankie Sierra dithering v2 (error diffusion) 13097@item sierra2_4a 13098Frankie Sierra dithering v2 "Lite" (error diffusion) 13099@end table 13100 13101Default is @var{sierra2_4a}. 13102 13103@item bayer_scale 13104When @var{bayer} dithering is selected, this option defines the scale of the 13105pattern (how much the crosshatch pattern is visible). A low value means more 13106visible pattern for less banding, and higher value means less visible pattern 13107at the cost of more banding. 13108 13109The option must be an integer value in the range [0,5]. Default is @var{2}. 13110 13111@item diff_mode 13112If set, define the zone to process 13113 13114@table @samp 13115@item rectangle 13116Only the changing rectangle will be reprocessed. This is similar to GIF 13117cropping/offsetting compression mechanism. This option can be useful for speed 13118if only a part of the image is changing, and has use cases such as limiting the 13119scope of the error diffusal @option{dither} to the rectangle that bounds the 13120moving scene (it leads to more deterministic output if the scene doesn't change 13121much, and as a result less moving noise and better GIF compression). 13122@end table 13123 13124Default is @var{none}. 13125 13126@item new 13127Take new palette for each output frame. 13128 13129@item alpha_threshold 13130Sets the alpha threshold for transparency. Alpha values above this threshold 13131will be treated as completely opaque, and values below this threshold will be 13132treated as completely transparent. 13133 13134The option must be an integer value in the range [0,255]. Default is @var{128}. 13135@end table 13136 13137@subsection Examples 13138 13139@itemize 13140@item 13141Use a palette (generated for example with @ref{palettegen}) to encode a GIF 13142using @command{ffmpeg}: 13143@example 13144ffmpeg -i input.mkv -i palette.png -lavfi paletteuse output.gif 13145@end example 13146@end itemize 13147 13148@section perspective 13149 13150Correct perspective of video not recorded perpendicular to the screen. 13151 13152A description of the accepted parameters follows. 13153 13154@table @option 13155@item x0 13156@item y0 13157@item x1 13158@item y1 13159@item x2 13160@item y2 13161@item x3 13162@item y3 13163Set coordinates expression for top left, top right, bottom left and bottom right corners. 13164Default values are @code{0:0:W:0:0:H:W:H} with which perspective will remain unchanged. 13165If the @code{sense} option is set to @code{source}, then the specified points will be sent 13166to the corners of the destination. If the @code{sense} option is set to @code{destination}, 13167then the corners of the source will be sent to the specified coordinates. 13168 13169The expressions can use the following variables: 13170 13171@table @option 13172@item W 13173@item H 13174the width and height of video frame. 13175@item in 13176Input frame count. 13177@item on 13178Output frame count. 13179@end table 13180 13181@item interpolation 13182Set interpolation for perspective correction. 13183 13184It accepts the following values: 13185@table @samp 13186@item linear 13187@item cubic 13188@end table 13189 13190Default value is @samp{linear}. 13191 13192@item sense 13193Set interpretation of coordinate options. 13194 13195It accepts the following values: 13196@table @samp 13197@item 0, source 13198 13199Send point in the source specified by the given coordinates to 13200the corners of the destination. 13201 13202@item 1, destination 13203 13204Send the corners of the source to the point in the destination specified 13205by the given coordinates. 13206 13207Default value is @samp{source}. 13208@end table 13209 13210@item eval 13211Set when the expressions for coordinates @option{x0,y0,...x3,y3} are evaluated. 13212 13213It accepts the following values: 13214@table @samp 13215@item init 13216only evaluate expressions once during the filter initialization or 13217when a command is processed 13218 13219@item frame 13220evaluate expressions for each incoming frame 13221@end table 13222 13223Default value is @samp{init}. 13224@end table 13225 13226@section phase 13227 13228Delay interlaced video by one field time so that the field order changes. 13229 13230The intended use is to fix PAL movies that have been captured with the 13231opposite field order to the film-to-video transfer. 13232 13233A description of the accepted parameters follows. 13234 13235@table @option 13236@item mode 13237Set phase mode. 13238 13239It accepts the following values: 13240@table @samp 13241@item t 13242Capture field order top-first, transfer bottom-first. 13243Filter will delay the bottom field. 13244 13245@item b 13246Capture field order bottom-first, transfer top-first. 13247Filter will delay the top field. 13248 13249@item p 13250Capture and transfer with the same field order. This mode only exists 13251for the documentation of the other options to refer to, but if you 13252actually select it, the filter will faithfully do nothing. 13253 13254@item a 13255Capture field order determined automatically by field flags, transfer 13256opposite. 13257Filter selects among @samp{t} and @samp{b} modes on a frame by frame 13258basis using field flags. If no field information is available, 13259then this works just like @samp{u}. 13260 13261@item u 13262Capture unknown or varying, transfer opposite. 13263Filter selects among @samp{t} and @samp{b} on a frame by frame basis by 13264analyzing the images and selecting the alternative that produces best 13265match between the fields. 13266 13267@item T 13268Capture top-first, transfer unknown or varying. 13269Filter selects among @samp{t} and @samp{p} using image analysis. 13270 13271@item B 13272Capture bottom-first, transfer unknown or varying. 13273Filter selects among @samp{b} and @samp{p} using image analysis. 13274 13275@item A 13276Capture determined by field flags, transfer unknown or varying. 13277Filter selects among @samp{t}, @samp{b} and @samp{p} using field flags and 13278image analysis. If no field information is available, then this works just 13279like @samp{U}. This is the default mode. 13280 13281@item U 13282Both capture and transfer unknown or varying. 13283Filter selects among @samp{t}, @samp{b} and @samp{p} using image analysis only. 13284@end table 13285@end table 13286 13287@section pixdesctest 13288 13289Pixel format descriptor test filter, mainly useful for internal 13290testing. The output video should be equal to the input video. 13291 13292For example: 13293@example 13294format=monow, pixdesctest 13295@end example 13296 13297can be used to test the monowhite pixel format descriptor definition. 13298 13299@section pixscope 13300 13301Display sample values of color channels. Mainly useful for checking color 13302and levels. Minimum supported resolution is 640x480. 13303 13304The filters accept the following options: 13305 13306@table @option 13307@item x 13308Set scope X position, relative offset on X axis. 13309 13310@item y 13311Set scope Y position, relative offset on Y axis. 13312 13313@item w 13314Set scope width. 13315 13316@item h 13317Set scope height. 13318 13319@item o 13320Set window opacity. This window also holds statistics about pixel area. 13321 13322@item wx 13323Set window X position, relative offset on X axis. 13324 13325@item wy 13326Set window Y position, relative offset on Y axis. 13327@end table 13328 13329@section pp 13330 13331Enable the specified chain of postprocessing subfilters using libpostproc. This 13332library should be automatically selected with a GPL build (@code{--enable-gpl}). 13333Subfilters must be separated by '/' and can be disabled by prepending a '-'. 13334Each subfilter and some options have a short and a long name that can be used 13335interchangeably, i.e. dr/dering are the same. 13336 13337The filters accept the following options: 13338 13339@table @option 13340@item subfilters 13341Set postprocessing subfilters string. 13342@end table 13343 13344All subfilters share common options to determine their scope: 13345 13346@table @option 13347@item a/autoq 13348Honor the quality commands for this subfilter. 13349 13350@item c/chrom 13351Do chrominance filtering, too (default). 13352 13353@item y/nochrom 13354Do luminance filtering only (no chrominance). 13355 13356@item n/noluma 13357Do chrominance filtering only (no luminance). 13358@end table 13359 13360These options can be appended after the subfilter name, separated by a '|'. 13361 13362Available subfilters are: 13363 13364@table @option 13365@item hb/hdeblock[|difference[|flatness]] 13366Horizontal deblocking filter 13367@table @option 13368@item difference 13369Difference factor where higher values mean more deblocking (default: @code{32}). 13370@item flatness 13371Flatness threshold where lower values mean more deblocking (default: @code{39}). 13372@end table 13373 13374@item vb/vdeblock[|difference[|flatness]] 13375Vertical deblocking filter 13376@table @option 13377@item difference 13378Difference factor where higher values mean more deblocking (default: @code{32}). 13379@item flatness 13380Flatness threshold where lower values mean more deblocking (default: @code{39}). 13381@end table 13382 13383@item ha/hadeblock[|difference[|flatness]] 13384Accurate horizontal deblocking filter 13385@table @option 13386@item difference 13387Difference factor where higher values mean more deblocking (default: @code{32}). 13388@item flatness 13389Flatness threshold where lower values mean more deblocking (default: @code{39}). 13390@end table 13391 13392@item va/vadeblock[|difference[|flatness]] 13393Accurate vertical deblocking filter 13394@table @option 13395@item difference 13396Difference factor where higher values mean more deblocking (default: @code{32}). 13397@item flatness 13398Flatness threshold where lower values mean more deblocking (default: @code{39}). 13399@end table 13400@end table 13401 13402The horizontal and vertical deblocking filters share the difference and 13403flatness values so you cannot set different horizontal and vertical 13404thresholds. 13405 13406@table @option 13407@item h1/x1hdeblock 13408Experimental horizontal deblocking filter 13409 13410@item v1/x1vdeblock 13411Experimental vertical deblocking filter 13412 13413@item dr/dering 13414Deringing filter 13415 13416@item tn/tmpnoise[|threshold1[|threshold2[|threshold3]]], temporal noise reducer 13417@table @option 13418@item threshold1 13419larger -> stronger filtering 13420@item threshold2 13421larger -> stronger filtering 13422@item threshold3 13423larger -> stronger filtering 13424@end table 13425 13426@item al/autolevels[:f/fullyrange], automatic brightness / contrast correction 13427@table @option 13428@item f/fullyrange 13429Stretch luminance to @code{0-255}. 13430@end table 13431 13432@item lb/linblenddeint 13433Linear blend deinterlacing filter that deinterlaces the given block by 13434filtering all lines with a @code{(1 2 1)} filter. 13435 13436@item li/linipoldeint 13437Linear interpolating deinterlacing filter that deinterlaces the given block by 13438linearly interpolating every second line. 13439 13440@item ci/cubicipoldeint 13441Cubic interpolating deinterlacing filter deinterlaces the given block by 13442cubically interpolating every second line. 13443 13444@item md/mediandeint 13445Median deinterlacing filter that deinterlaces the given block by applying a 13446median filter to every second line. 13447 13448@item fd/ffmpegdeint 13449FFmpeg deinterlacing filter that deinterlaces the given block by filtering every 13450second line with a @code{(-1 4 2 4 -1)} filter. 13451 13452@item l5/lowpass5 13453Vertically applied FIR lowpass deinterlacing filter that deinterlaces the given 13454block by filtering all lines with a @code{(-1 2 6 2 -1)} filter. 13455 13456@item fq/forceQuant[|quantizer] 13457Overrides the quantizer table from the input with the constant quantizer you 13458specify. 13459@table @option 13460@item quantizer 13461Quantizer to use 13462@end table 13463 13464@item de/default 13465Default pp filter combination (@code{hb|a,vb|a,dr|a}) 13466 13467@item fa/fast 13468Fast pp filter combination (@code{h1|a,v1|a,dr|a}) 13469 13470@item ac 13471High quality pp filter combination (@code{ha|a|128|7,va|a,dr|a}) 13472@end table 13473 13474@subsection Examples 13475 13476@itemize 13477@item 13478Apply horizontal and vertical deblocking, deringing and automatic 13479brightness/contrast: 13480@example 13481pp=hb/vb/dr/al 13482@end example 13483 13484@item 13485Apply default filters without brightness/contrast correction: 13486@example 13487pp=de/-al 13488@end example 13489 13490@item 13491Apply default filters and temporal denoiser: 13492@example 13493pp=default/tmpnoise|1|2|3 13494@end example 13495 13496@item 13497Apply deblocking on luminance only, and switch vertical deblocking on or off 13498automatically depending on available CPU time: 13499@example 13500pp=hb|y/vb|a 13501@end example 13502@end itemize 13503 13504@section pp7 13505Apply Postprocessing filter 7. It is variant of the @ref{spp} filter, 13506similar to spp = 6 with 7 point DCT, where only the center sample is 13507used after IDCT. 13508 13509The filter accepts the following options: 13510 13511@table @option 13512@item qp 13513Force a constant quantization parameter. It accepts an integer in range 135140 to 63. If not set, the filter will use the QP from the video stream 13515(if available). 13516 13517@item mode 13518Set thresholding mode. Available modes are: 13519 13520@table @samp 13521@item hard 13522Set hard thresholding. 13523@item soft 13524Set soft thresholding (better de-ringing effect, but likely blurrier). 13525@item medium 13526Set medium thresholding (good results, default). 13527@end table 13528@end table 13529 13530@section premultiply 13531Apply alpha premultiply effect to input video stream using first plane 13532of second stream as alpha. 13533 13534Both streams must have same dimensions and same pixel format. 13535 13536The filter accepts the following option: 13537 13538@table @option 13539@item planes 13540Set which planes will be processed, unprocessed planes will be copied. 13541By default value 0xf, all planes will be processed. 13542 13543@item inplace 13544Do not require 2nd input for processing, instead use alpha plane from input stream. 13545@end table 13546 13547@section prewitt 13548Apply prewitt operator to input video stream. 13549 13550The filter accepts the following option: 13551 13552@table @option 13553@item planes 13554Set which planes will be processed, unprocessed planes will be copied. 13555By default value 0xf, all planes will be processed. 13556 13557@item scale 13558Set value which will be multiplied with filtered result. 13559 13560@item delta 13561Set value which will be added to filtered result. 13562@end table 13563 13564@anchor{program_opencl} 13565@section program_opencl 13566 13567Filter video using an OpenCL program. 13568 13569@table @option 13570 13571@item source 13572OpenCL program source file. 13573 13574@item kernel 13575Kernel name in program. 13576 13577@item inputs 13578Number of inputs to the filter. Defaults to 1. 13579 13580@item size, s 13581Size of output frames. Defaults to the same as the first input. 13582 13583@end table 13584 13585The program source file must contain a kernel function with the given name, 13586which will be run once for each plane of the output. Each run on a plane 13587gets enqueued as a separate 2D global NDRange with one work-item for each 13588pixel to be generated. The global ID offset for each work-item is therefore 13589the coordinates of a pixel in the destination image. 13590 13591The kernel function needs to take the following arguments: 13592@itemize 13593@item 13594Destination image, @var{__write_only image2d_t}. 13595 13596This image will become the output; the kernel should write all of it. 13597@item 13598Frame index, @var{unsigned int}. 13599 13600This is a counter starting from zero and increasing by one for each frame. 13601@item 13602Source images, @var{__read_only image2d_t}. 13603 13604These are the most recent images on each input. The kernel may read from 13605them to generate the output, but they can't be written to. 13606@end itemize 13607 13608Example programs: 13609 13610@itemize 13611@item 13612Copy the input to the output (output must be the same size as the input). 13613@verbatim 13614__kernel void copy(__write_only image2d_t destination, 13615 unsigned int index, 13616 __read_only image2d_t source) 13617{ 13618 const sampler_t sampler = CLK_NORMALIZED_COORDS_FALSE; 13619 13620 int2 location = (int2)(get_global_id(0), get_global_id(1)); 13621 13622 float4 value = read_imagef(source, sampler, location); 13623 13624 write_imagef(destination, location, value); 13625} 13626@end verbatim 13627 13628@item 13629Apply a simple transformation, rotating the input by an amount increasing 13630with the index counter. Pixel values are linearly interpolated by the 13631sampler, and the output need not have the same dimensions as the input. 13632@verbatim 13633__kernel void rotate_image(__write_only image2d_t dst, 13634 unsigned int index, 13635 __read_only image2d_t src) 13636{ 13637 const sampler_t sampler = (CLK_NORMALIZED_COORDS_FALSE | 13638 CLK_FILTER_LINEAR); 13639 13640 float angle = (float)index / 100.0f; 13641 13642 float2 dst_dim = convert_float2(get_image_dim(dst)); 13643 float2 src_dim = convert_float2(get_image_dim(src)); 13644 13645 float2 dst_cen = dst_dim / 2.0f; 13646 float2 src_cen = src_dim / 2.0f; 13647 13648 int2 dst_loc = (int2)(get_global_id(0), get_global_id(1)); 13649 13650 float2 dst_pos = convert_float2(dst_loc) - dst_cen; 13651 float2 src_pos = { 13652 cos(angle) * dst_pos.x - sin(angle) * dst_pos.y, 13653 sin(angle) * dst_pos.x + cos(angle) * dst_pos.y 13654 }; 13655 src_pos = src_pos * src_dim / dst_dim; 13656 13657 float2 src_loc = src_pos + src_cen; 13658 13659 if (src_loc.x < 0.0f || src_loc.y < 0.0f || 13660 src_loc.x > src_dim.x || src_loc.y > src_dim.y) 13661 write_imagef(dst, dst_loc, 0.5f); 13662 else 13663 write_imagef(dst, dst_loc, read_imagef(src, sampler, src_loc)); 13664} 13665@end verbatim 13666 13667@item 13668Blend two inputs together, with the amount of each input used varying 13669with the index counter. 13670@verbatim 13671__kernel void blend_images(__write_only image2d_t dst, 13672 unsigned int index, 13673 __read_only image2d_t src1, 13674 __read_only image2d_t src2) 13675{ 13676 const sampler_t sampler = (CLK_NORMALIZED_COORDS_FALSE | 13677 CLK_FILTER_LINEAR); 13678 13679 float blend = (cos((float)index / 50.0f) + 1.0f) / 2.0f; 13680 13681 int2 dst_loc = (int2)(get_global_id(0), get_global_id(1)); 13682 int2 src1_loc = dst_loc * get_image_dim(src1) / get_image_dim(dst); 13683 int2 src2_loc = dst_loc * get_image_dim(src2) / get_image_dim(dst); 13684 13685 float4 val1 = read_imagef(src1, sampler, src1_loc); 13686 float4 val2 = read_imagef(src2, sampler, src2_loc); 13687 13688 write_imagef(dst, dst_loc, val1 * blend + val2 * (1.0f - blend)); 13689} 13690@end verbatim 13691 13692@end itemize 13693 13694@section pseudocolor 13695 13696Alter frame colors in video with pseudocolors. 13697 13698This filter accept the following options: 13699 13700@table @option 13701@item c0 13702set pixel first component expression 13703 13704@item c1 13705set pixel second component expression 13706 13707@item c2 13708set pixel third component expression 13709 13710@item c3 13711set pixel fourth component expression, corresponds to the alpha component 13712 13713@item i 13714set component to use as base for altering colors 13715@end table 13716 13717Each of them specifies the expression to use for computing the lookup table for 13718the corresponding pixel component values. 13719 13720The expressions can contain the following constants and functions: 13721 13722@table @option 13723@item w 13724@item h 13725The input width and height. 13726 13727@item val 13728The input value for the pixel component. 13729 13730@item ymin, umin, vmin, amin 13731The minimum allowed component value. 13732 13733@item ymax, umax, vmax, amax 13734The maximum allowed component value. 13735@end table 13736 13737All expressions default to "val". 13738 13739@subsection Examples 13740 13741@itemize 13742@item 13743Change too high luma values to gradient: 13744@example 13745pseudocolor="'if(between(val,ymax,amax),lerp(ymin,ymax,(val-ymax)/(amax-ymax)),-1):if(between(val,ymax,amax),lerp(umax,umin,(val-ymax)/(amax-ymax)),-1):if(between(val,ymax,amax),lerp(vmin,vmax,(val-ymax)/(amax-ymax)),-1):-1'" 13746@end example 13747@end itemize 13748 13749@section psnr 13750 13751Obtain the average, maximum and minimum PSNR (Peak Signal to Noise 13752Ratio) between two input videos. 13753 13754This filter takes in input two input videos, the first input is 13755considered the "main" source and is passed unchanged to the 13756output. The second input is used as a "reference" video for computing 13757the PSNR. 13758 13759Both video inputs must have the same resolution and pixel format for 13760this filter to work correctly. Also it assumes that both inputs 13761have the same number of frames, which are compared one by one. 13762 13763The obtained average PSNR is printed through the logging system. 13764 13765The filter stores the accumulated MSE (mean squared error) of each 13766frame, and at the end of the processing it is averaged across all frames 13767equally, and the following formula is applied to obtain the PSNR: 13768 13769@example 13770PSNR = 10*log10(MAX^2/MSE) 13771@end example 13772 13773Where MAX is the average of the maximum values of each component of the 13774image. 13775 13776The description of the accepted parameters follows. 13777 13778@table @option 13779@item stats_file, f 13780If specified the filter will use the named file to save the PSNR of 13781each individual frame. When filename equals "-" the data is sent to 13782standard output. 13783 13784@item stats_version 13785Specifies which version of the stats file format to use. Details of 13786each format are written below. 13787Default value is 1. 13788 13789@item stats_add_max 13790Determines whether the max value is output to the stats log. 13791Default value is 0. 13792Requires stats_version >= 2. If this is set and stats_version < 2, 13793the filter will return an error. 13794@end table 13795 13796This filter also supports the @ref{framesync} options. 13797 13798The file printed if @var{stats_file} is selected, contains a sequence of 13799key/value pairs of the form @var{key}:@var{value} for each compared 13800couple of frames. 13801 13802If a @var{stats_version} greater than 1 is specified, a header line precedes 13803the list of per-frame-pair stats, with key value pairs following the frame 13804format with the following parameters: 13805 13806@table @option 13807@item psnr_log_version 13808The version of the log file format. Will match @var{stats_version}. 13809 13810@item fields 13811A comma separated list of the per-frame-pair parameters included in 13812the log. 13813@end table 13814 13815A description of each shown per-frame-pair parameter follows: 13816 13817@table @option 13818@item n 13819sequential number of the input frame, starting from 1 13820 13821@item mse_avg 13822Mean Square Error pixel-by-pixel average difference of the compared 13823frames, averaged over all the image components. 13824 13825@item mse_y, mse_u, mse_v, mse_r, mse_g, mse_b, mse_a 13826Mean Square Error pixel-by-pixel average difference of the compared 13827frames for the component specified by the suffix. 13828 13829@item psnr_y, psnr_u, psnr_v, psnr_r, psnr_g, psnr_b, psnr_a 13830Peak Signal to Noise ratio of the compared frames for the component 13831specified by the suffix. 13832 13833@item max_avg, max_y, max_u, max_v 13834Maximum allowed value for each channel, and average over all 13835channels. 13836@end table 13837 13838For example: 13839@example 13840movie=ref_movie.mpg, setpts=PTS-STARTPTS [main]; 13841[main][ref] psnr="stats_file=stats.log" [out] 13842@end example 13843 13844On this example the input file being processed is compared with the 13845reference file @file{ref_movie.mpg}. The PSNR of each individual frame 13846is stored in @file{stats.log}. 13847 13848@anchor{pullup} 13849@section pullup 13850 13851Pulldown reversal (inverse telecine) filter, capable of handling mixed 13852hard-telecine, 24000/1001 fps progressive, and 30000/1001 fps progressive 13853content. 13854 13855The pullup filter is designed to take advantage of future context in making 13856its decisions. This filter is stateless in the sense that it does not lock 13857onto a pattern to follow, but it instead looks forward to the following 13858fields in order to identify matches and rebuild progressive frames. 13859 13860To produce content with an even framerate, insert the fps filter after 13861pullup, use @code{fps=24000/1001} if the input frame rate is 29.97fps, 13862@code{fps=24} for 30fps and the (rare) telecined 25fps input. 13863 13864The filter accepts the following options: 13865 13866@table @option 13867@item jl 13868@item jr 13869@item jt 13870@item jb 13871These options set the amount of "junk" to ignore at the left, right, top, and 13872bottom of the image, respectively. Left and right are in units of 8 pixels, 13873while top and bottom are in units of 2 lines. 13874The default is 8 pixels on each side. 13875 13876@item sb 13877Set the strict breaks. Setting this option to 1 will reduce the chances of 13878filter generating an occasional mismatched frame, but it may also cause an 13879excessive number of frames to be dropped during high motion sequences. 13880Conversely, setting it to -1 will make filter match fields more easily. 13881This may help processing of video where there is slight blurring between 13882the fields, but may also cause there to be interlaced frames in the output. 13883Default value is @code{0}. 13884 13885@item mp 13886Set the metric plane to use. It accepts the following values: 13887@table @samp 13888@item l 13889Use luma plane. 13890 13891@item u 13892Use chroma blue plane. 13893 13894@item v 13895Use chroma red plane. 13896@end table 13897 13898This option may be set to use chroma plane instead of the default luma plane 13899for doing filter's computations. This may improve accuracy on very clean 13900source material, but more likely will decrease accuracy, especially if there 13901is chroma noise (rainbow effect) or any grayscale video. 13902The main purpose of setting @option{mp} to a chroma plane is to reduce CPU 13903load and make pullup usable in realtime on slow machines. 13904@end table 13905 13906For best results (without duplicated frames in the output file) it is 13907necessary to change the output frame rate. For example, to inverse 13908telecine NTSC input: 13909@example 13910ffmpeg -i input -vf pullup -r 24000/1001 ... 13911@end example 13912 13913@section qp 13914 13915Change video quantization parameters (QP). 13916 13917The filter accepts the following option: 13918 13919@table @option 13920@item qp 13921Set expression for quantization parameter. 13922@end table 13923 13924The expression is evaluated through the eval API and can contain, among others, 13925the following constants: 13926 13927@table @var 13928@item known 139291 if index is not 129, 0 otherwise. 13930 13931@item qp 13932Sequential index starting from -129 to 128. 13933@end table 13934 13935@subsection Examples 13936 13937@itemize 13938@item 13939Some equation like: 13940@example 13941qp=2+2*sin(PI*qp) 13942@end example 13943@end itemize 13944 13945@section random 13946 13947Flush video frames from internal cache of frames into a random order. 13948No frame is discarded. 13949Inspired by @ref{frei0r} nervous filter. 13950 13951@table @option 13952@item frames 13953Set size in number of frames of internal cache, in range from @code{2} to 13954@code{512}. Default is @code{30}. 13955 13956@item seed 13957Set seed for random number generator, must be an integer included between 13958@code{0} and @code{UINT32_MAX}. If not specified, or if explicitly set to 13959less than @code{0}, the filter will try to use a good random seed on a 13960best effort basis. 13961@end table 13962 13963@section readeia608 13964 13965Read closed captioning (EIA-608) information from the top lines of a video frame. 13966 13967This filter adds frame metadata for @code{lavfi.readeia608.X.cc} and 13968@code{lavfi.readeia608.X.line}, where @code{X} is the number of the identified line 13969with EIA-608 data (starting from 0). A description of each metadata value follows: 13970 13971@table @option 13972@item lavfi.readeia608.X.cc 13973The two bytes stored as EIA-608 data (printed in hexadecimal). 13974 13975@item lavfi.readeia608.X.line 13976The number of the line on which the EIA-608 data was identified and read. 13977@end table 13978 13979This filter accepts the following options: 13980 13981@table @option 13982@item scan_min 13983Set the line to start scanning for EIA-608 data. Default is @code{0}. 13984 13985@item scan_max 13986Set the line to end scanning for EIA-608 data. Default is @code{29}. 13987 13988@item mac 13989Set minimal acceptable amplitude change for sync codes detection. 13990Default is @code{0.2}. Allowed range is @code{[0.001 - 1]}. 13991 13992@item spw 13993Set the ratio of width reserved for sync code detection. 13994Default is @code{0.27}. Allowed range is @code{[0.01 - 0.7]}. 13995 13996@item mhd 13997Set the max peaks height difference for sync code detection. 13998Default is @code{0.1}. Allowed range is @code{[0.0 - 0.5]}. 13999 14000@item mpd 14001Set max peaks period difference for sync code detection. 14002Default is @code{0.1}. Allowed range is @code{[0.0 - 0.5]}. 14003 14004@item msd 14005Set the first two max start code bits differences. 14006Default is @code{0.02}. Allowed range is @code{[0.0 - 0.5]}. 14007 14008@item bhd 14009Set the minimum ratio of bits height compared to 3rd start code bit. 14010Default is @code{0.75}. Allowed range is @code{[0.01 - 1]}. 14011 14012@item th_w 14013Set the white color threshold. Default is @code{0.35}. Allowed range is @code{[0.1 - 1]}. 14014 14015@item th_b 14016Set the black color threshold. Default is @code{0.15}. Allowed range is @code{[0.0 - 0.5]}. 14017 14018@item chp 14019Enable checking the parity bit. In the event of a parity error, the filter will output 14020@code{0x00} for that character. Default is false. 14021@end table 14022 14023@subsection Examples 14024 14025@itemize 14026@item 14027Output a csv with presentation time and the first two lines of identified EIA-608 captioning data. 14028@example 14029ffprobe -f lavfi -i movie=captioned_video.mov,readeia608 -show_entries frame=pkt_pts_time:frame_tags=lavfi.readeia608.0.cc,lavfi.readeia608.1.cc -of csv 14030@end example 14031@end itemize 14032 14033@section readvitc 14034 14035Read vertical interval timecode (VITC) information from the top lines of a 14036video frame. 14037 14038The filter adds frame metadata key @code{lavfi.readvitc.tc_str} with the 14039timecode value, if a valid timecode has been detected. Further metadata key 14040@code{lavfi.readvitc.found} is set to 0/1 depending on whether 14041timecode data has been found or not. 14042 14043This filter accepts the following options: 14044 14045@table @option 14046@item scan_max 14047Set the maximum number of lines to scan for VITC data. If the value is set to 14048@code{-1} the full video frame is scanned. Default is @code{45}. 14049 14050@item thr_b 14051Set the luma threshold for black. Accepts float numbers in the range [0.0,1.0], 14052default value is @code{0.2}. The value must be equal or less than @code{thr_w}. 14053 14054@item thr_w 14055Set the luma threshold for white. Accepts float numbers in the range [0.0,1.0], 14056default value is @code{0.6}. The value must be equal or greater than @code{thr_b}. 14057@end table 14058 14059@subsection Examples 14060 14061@itemize 14062@item 14063Detect and draw VITC data onto the video frame; if no valid VITC is detected, 14064draw @code{--:--:--:--} as a placeholder: 14065@example 14066ffmpeg -i input.avi -filter:v 'readvitc,drawtext=fontfile=FreeMono.ttf:text=%@{metadata\\:lavfi.readvitc.tc_str\\:--\\\\\\:--\\\\\\:--\\\\\\:--@}:x=(w-tw)/2:y=400-ascent' 14067@end example 14068@end itemize 14069 14070@section remap 14071 14072Remap pixels using 2nd: Xmap and 3rd: Ymap input video stream. 14073 14074Destination pixel at position (X, Y) will be picked from source (x, y) position 14075where x = Xmap(X, Y) and y = Ymap(X, Y). If mapping values are out of range, zero 14076value for pixel will be used for destination pixel. 14077 14078Xmap and Ymap input video streams must be of same dimensions. Output video stream 14079will have Xmap/Ymap video stream dimensions. 14080Xmap and Ymap input video streams are 16bit depth, single channel. 14081 14082@section removegrain 14083 14084The removegrain filter is a spatial denoiser for progressive video. 14085 14086@table @option 14087@item m0 14088Set mode for the first plane. 14089 14090@item m1 14091Set mode for the second plane. 14092 14093@item m2 14094Set mode for the third plane. 14095 14096@item m3 14097Set mode for the fourth plane. 14098@end table 14099 14100Range of mode is from 0 to 24. Description of each mode follows: 14101 14102@table @var 14103@item 0 14104Leave input plane unchanged. Default. 14105 14106@item 1 14107Clips the pixel with the minimum and maximum of the 8 neighbour pixels. 14108 14109@item 2 14110Clips the pixel with the second minimum and maximum of the 8 neighbour pixels. 14111 14112@item 3 14113Clips the pixel with the third minimum and maximum of the 8 neighbour pixels. 14114 14115@item 4 14116Clips the pixel with the fourth minimum and maximum of the 8 neighbour pixels. 14117This is equivalent to a median filter. 14118 14119@item 5 14120Line-sensitive clipping giving the minimal change. 14121 14122@item 6 14123Line-sensitive clipping, intermediate. 14124 14125@item 7 14126Line-sensitive clipping, intermediate. 14127 14128@item 8 14129Line-sensitive clipping, intermediate. 14130 14131@item 9 14132Line-sensitive clipping on a line where the neighbours pixels are the closest. 14133 14134@item 10 14135Replaces the target pixel with the closest neighbour. 14136 14137@item 11 14138[1 2 1] horizontal and vertical kernel blur. 14139 14140@item 12 14141Same as mode 11. 14142 14143@item 13 14144Bob mode, interpolates top field from the line where the neighbours 14145pixels are the closest. 14146 14147@item 14 14148Bob mode, interpolates bottom field from the line where the neighbours 14149pixels are the closest. 14150 14151@item 15 14152Bob mode, interpolates top field. Same as 13 but with a more complicated 14153interpolation formula. 14154 14155@item 16 14156Bob mode, interpolates bottom field. Same as 14 but with a more complicated 14157interpolation formula. 14158 14159@item 17 14160Clips the pixel with the minimum and maximum of respectively the maximum and 14161minimum of each pair of opposite neighbour pixels. 14162 14163@item 18 14164Line-sensitive clipping using opposite neighbours whose greatest distance from 14165the current pixel is minimal. 14166 14167@item 19 14168Replaces the pixel with the average of its 8 neighbours. 14169 14170@item 20 14171Averages the 9 pixels ([1 1 1] horizontal and vertical blur). 14172 14173@item 21 14174Clips pixels using the averages of opposite neighbour. 14175 14176@item 22 14177Same as mode 21 but simpler and faster. 14178 14179@item 23 14180Small edge and halo removal, but reputed useless. 14181 14182@item 24 14183Similar as 23. 14184@end table 14185 14186@section removelogo 14187 14188Suppress a TV station logo, using an image file to determine which 14189pixels comprise the logo. It works by filling in the pixels that 14190comprise the logo with neighboring pixels. 14191 14192The filter accepts the following options: 14193 14194@table @option 14195@item filename, f 14196Set the filter bitmap file, which can be any image format supported by 14197libavformat. The width and height of the image file must match those of the 14198video stream being processed. 14199@end table 14200 14201Pixels in the provided bitmap image with a value of zero are not 14202considered part of the logo, non-zero pixels are considered part of 14203the logo. If you use white (255) for the logo and black (0) for the 14204rest, you will be safe. For making the filter bitmap, it is 14205recommended to take a screen capture of a black frame with the logo 14206visible, and then using a threshold filter followed by the erode 14207filter once or twice. 14208 14209If needed, little splotches can be fixed manually. Remember that if 14210logo pixels are not covered, the filter quality will be much 14211reduced. Marking too many pixels as part of the logo does not hurt as 14212much, but it will increase the amount of blurring needed to cover over 14213the image and will destroy more information than necessary, and extra 14214pixels will slow things down on a large logo. 14215 14216@section repeatfields 14217 14218This filter uses the repeat_field flag from the Video ES headers and hard repeats 14219fields based on its value. 14220 14221@section reverse 14222 14223Reverse a video clip. 14224 14225Warning: This filter requires memory to buffer the entire clip, so trimming 14226is suggested. 14227 14228@subsection Examples 14229 14230@itemize 14231@item 14232Take the first 5 seconds of a clip, and reverse it. 14233@example 14234trim=end=5,reverse 14235@end example 14236@end itemize 14237 14238@section roberts 14239Apply roberts cross operator to input video stream. 14240 14241The filter accepts the following option: 14242 14243@table @option 14244@item planes 14245Set which planes will be processed, unprocessed planes will be copied. 14246By default value 0xf, all planes will be processed. 14247 14248@item scale 14249Set value which will be multiplied with filtered result. 14250 14251@item delta 14252Set value which will be added to filtered result. 14253@end table 14254 14255@section rotate 14256 14257Rotate video by an arbitrary angle expressed in radians. 14258 14259The filter accepts the following options: 14260 14261A description of the optional parameters follows. 14262@table @option 14263@item angle, a 14264Set an expression for the angle by which to rotate the input video 14265clockwise, expressed as a number of radians. A negative value will 14266result in a counter-clockwise rotation. By default it is set to "0". 14267 14268This expression is evaluated for each frame. 14269 14270@item out_w, ow 14271Set the output width expression, default value is "iw". 14272This expression is evaluated just once during configuration. 14273 14274@item out_h, oh 14275Set the output height expression, default value is "ih". 14276This expression is evaluated just once during configuration. 14277 14278@item bilinear 14279Enable bilinear interpolation if set to 1, a value of 0 disables 14280it. Default value is 1. 14281 14282@item fillcolor, c 14283Set the color used to fill the output area not covered by the rotated 14284image. For the general syntax of this option, check the 14285@ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}. 14286If the special value "none" is selected then no 14287background is printed (useful for example if the background is never shown). 14288 14289Default value is "black". 14290@end table 14291 14292The expressions for the angle and the output size can contain the 14293following constants and functions: 14294 14295@table @option 14296@item n 14297sequential number of the input frame, starting from 0. It is always NAN 14298before the first frame is filtered. 14299 14300@item t 14301time in seconds of the input frame, it is set to 0 when the filter is 14302configured. It is always NAN before the first frame is filtered. 14303 14304@item hsub 14305@item vsub 14306horizontal and vertical chroma subsample values. For example for the 14307pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1. 14308 14309@item in_w, iw 14310@item in_h, ih 14311the input video width and height 14312 14313@item out_w, ow 14314@item out_h, oh 14315the output width and height, that is the size of the padded area as 14316specified by the @var{width} and @var{height} expressions 14317 14318@item rotw(a) 14319@item roth(a) 14320the minimal width/height required for completely containing the input 14321video rotated by @var{a} radians. 14322 14323These are only available when computing the @option{out_w} and 14324@option{out_h} expressions. 14325@end table 14326 14327@subsection Examples 14328 14329@itemize 14330@item 14331Rotate the input by PI/6 radians clockwise: 14332@example 14333rotate=PI/6 14334@end example 14335 14336@item 14337Rotate the input by PI/6 radians counter-clockwise: 14338@example 14339rotate=-PI/6 14340@end example 14341 14342@item 14343Rotate the input by 45 degrees clockwise: 14344@example 14345rotate=45*PI/180 14346@end example 14347 14348@item 14349Apply a constant rotation with period T, starting from an angle of PI/3: 14350@example 14351rotate=PI/3+2*PI*t/T 14352@end example 14353 14354@item 14355Make the input video rotation oscillating with a period of T 14356seconds and an amplitude of A radians: 14357@example 14358rotate=A*sin(2*PI/T*t) 14359@end example 14360 14361@item 14362Rotate the video, output size is chosen so that the whole rotating 14363input video is always completely contained in the output: 14364@example 14365rotate='2*PI*t:ow=hypot(iw,ih):oh=ow' 14366@end example 14367 14368@item 14369Rotate the video, reduce the output size so that no background is ever 14370shown: 14371@example 14372rotate=2*PI*t:ow='min(iw,ih)/sqrt(2)':oh=ow:c=none 14373@end example 14374@end itemize 14375 14376@subsection Commands 14377 14378The filter supports the following commands: 14379 14380@table @option 14381@item a, angle 14382Set the angle expression. 14383The command accepts the same syntax of the corresponding option. 14384 14385If the specified expression is not valid, it is kept at its current 14386value. 14387@end table 14388 14389@section sab 14390 14391Apply Shape Adaptive Blur. 14392 14393The filter accepts the following options: 14394 14395@table @option 14396@item luma_radius, lr 14397Set luma blur filter strength, must be a value in range 0.1-4.0, default 14398value is 1.0. A greater value will result in a more blurred image, and 14399in slower processing. 14400 14401@item luma_pre_filter_radius, lpfr 14402Set luma pre-filter radius, must be a value in the 0.1-2.0 range, default 14403value is 1.0. 14404 14405@item luma_strength, ls 14406Set luma maximum difference between pixels to still be considered, must 14407be a value in the 0.1-100.0 range, default value is 1.0. 14408 14409@item chroma_radius, cr 14410Set chroma blur filter strength, must be a value in range -0.9-4.0. A 14411greater value will result in a more blurred image, and in slower 14412processing. 14413 14414@item chroma_pre_filter_radius, cpfr 14415Set chroma pre-filter radius, must be a value in the -0.9-2.0 range. 14416 14417@item chroma_strength, cs 14418Set chroma maximum difference between pixels to still be considered, 14419must be a value in the -0.9-100.0 range. 14420@end table 14421 14422Each chroma option value, if not explicitly specified, is set to the 14423corresponding luma option value. 14424 14425@anchor{scale} 14426@section scale 14427 14428Scale (resize) the input video, using the libswscale library. 14429 14430The scale filter forces the output display aspect ratio to be the same 14431of the input, by changing the output sample aspect ratio. 14432 14433If the input image format is different from the format requested by 14434the next filter, the scale filter will convert the input to the 14435requested format. 14436 14437@subsection Options 14438The filter accepts the following options, or any of the options 14439supported by the libswscale scaler. 14440 14441See @ref{scaler_options,,the ffmpeg-scaler manual,ffmpeg-scaler} for 14442the complete list of scaler options. 14443 14444@table @option 14445@item width, w 14446@item height, h 14447Set the output video dimension expression. Default value is the input 14448dimension. 14449 14450If the @var{width} or @var{w} value is 0, the input width is used for 14451the output. If the @var{height} or @var{h} value is 0, the input height 14452is used for the output. 14453 14454If one and only one of the values is -n with n >= 1, the scale filter 14455will use a value that maintains the aspect ratio of the input image, 14456calculated from the other specified dimension. After that it will, 14457however, make sure that the calculated dimension is divisible by n and 14458adjust the value if necessary. 14459 14460If both values are -n with n >= 1, the behavior will be identical to 14461both values being set to 0 as previously detailed. 14462 14463See below for the list of accepted constants for use in the dimension 14464expression. 14465 14466@item eval 14467Specify when to evaluate @var{width} and @var{height} expression. It accepts the following values: 14468 14469@table @samp 14470@item init 14471Only evaluate expressions once during the filter initialization or when a command is processed. 14472 14473@item frame 14474Evaluate expressions for each incoming frame. 14475 14476@end table 14477 14478Default value is @samp{init}. 14479 14480 14481@item interl 14482Set the interlacing mode. It accepts the following values: 14483 14484@table @samp 14485@item 1 14486Force interlaced aware scaling. 14487 14488@item 0 14489Do not apply interlaced scaling. 14490 14491@item -1 14492Select interlaced aware scaling depending on whether the source frames 14493are flagged as interlaced or not. 14494@end table 14495 14496Default value is @samp{0}. 14497 14498@item flags 14499Set libswscale scaling flags. See 14500@ref{sws_flags,,the ffmpeg-scaler manual,ffmpeg-scaler} for the 14501complete list of values. If not explicitly specified the filter applies 14502the default flags. 14503 14504 14505@item param0, param1 14506Set libswscale input parameters for scaling algorithms that need them. See 14507@ref{sws_params,,the ffmpeg-scaler manual,ffmpeg-scaler} for the 14508complete documentation. If not explicitly specified the filter applies 14509empty parameters. 14510 14511 14512 14513@item size, s 14514Set the video size. For the syntax of this option, check the 14515@ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}. 14516 14517@item in_color_matrix 14518@item out_color_matrix 14519Set in/output YCbCr color space type. 14520 14521This allows the autodetected value to be overridden as well as allows forcing 14522a specific value used for the output and encoder. 14523 14524If not specified, the color space type depends on the pixel format. 14525 14526Possible values: 14527 14528@table @samp 14529@item auto 14530Choose automatically. 14531 14532@item bt709 14533Format conforming to International Telecommunication Union (ITU) 14534Recommendation BT.709. 14535 14536@item fcc 14537Set color space conforming to the United States Federal Communications 14538Commission (FCC) Code of Federal Regulations (CFR) Title 47 (2003) 73.682 (a). 14539 14540@item bt601 14541Set color space conforming to: 14542 14543@itemize 14544@item 14545ITU Radiocommunication Sector (ITU-R) Recommendation BT.601 14546 14547@item 14548ITU-R Rec. BT.470-6 (1998) Systems B, B1, and G 14549 14550@item 14551Society of Motion Picture and Television Engineers (SMPTE) ST 170:2004 14552 14553@end itemize 14554 14555@item smpte240m 14556Set color space conforming to SMPTE ST 240:1999. 14557@end table 14558 14559@item in_range 14560@item out_range 14561Set in/output YCbCr sample range. 14562 14563This allows the autodetected value to be overridden as well as allows forcing 14564a specific value used for the output and encoder. If not specified, the 14565range depends on the pixel format. Possible values: 14566 14567@table @samp 14568@item auto/unknown 14569Choose automatically. 14570 14571@item jpeg/full/pc 14572Set full range (0-255 in case of 8-bit luma). 14573 14574@item mpeg/limited/tv 14575Set "MPEG" range (16-235 in case of 8-bit luma). 14576@end table 14577 14578@item force_original_aspect_ratio 14579Enable decreasing or increasing output video width or height if necessary to 14580keep the original aspect ratio. Possible values: 14581 14582@table @samp 14583@item disable 14584Scale the video as specified and disable this feature. 14585 14586@item decrease 14587The output video dimensions will automatically be decreased if needed. 14588 14589@item increase 14590The output video dimensions will automatically be increased if needed. 14591 14592@end table 14593 14594One useful instance of this option is that when you know a specific device's 14595maximum allowed resolution, you can use this to limit the output video to 14596that, while retaining the aspect ratio. For example, device A allows 145971280x720 playback, and your video is 1920x800. Using this option (set it to 14598decrease) and specifying 1280x720 to the command line makes the output 145991280x533. 14600 14601Please note that this is a different thing than specifying -1 for @option{w} 14602or @option{h}, you still need to specify the output resolution for this option 14603to work. 14604 14605@end table 14606 14607The values of the @option{w} and @option{h} options are expressions 14608containing the following constants: 14609 14610@table @var 14611@item in_w 14612@item in_h 14613The input width and height 14614 14615@item iw 14616@item ih 14617These are the same as @var{in_w} and @var{in_h}. 14618 14619@item out_w 14620@item out_h 14621The output (scaled) width and height 14622 14623@item ow 14624@item oh 14625These are the same as @var{out_w} and @var{out_h} 14626 14627@item a 14628The same as @var{iw} / @var{ih} 14629 14630@item sar 14631input sample aspect ratio 14632 14633@item dar 14634The input display aspect ratio. Calculated from @code{(iw / ih) * sar}. 14635 14636@item hsub 14637@item vsub 14638horizontal and vertical input chroma subsample values. For example for the 14639pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1. 14640 14641@item ohsub 14642@item ovsub 14643horizontal and vertical output chroma subsample values. For example for the 14644pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1. 14645@end table 14646 14647@subsection Examples 14648 14649@itemize 14650@item 14651Scale the input video to a size of 200x100 14652@example 14653scale=w=200:h=100 14654@end example 14655 14656This is equivalent to: 14657@example 14658scale=200:100 14659@end example 14660 14661or: 14662@example 14663scale=200x100 14664@end example 14665 14666@item 14667Specify a size abbreviation for the output size: 14668@example 14669scale=qcif 14670@end example 14671 14672which can also be written as: 14673@example 14674scale=size=qcif 14675@end example 14676 14677@item 14678Scale the input to 2x: 14679@example 14680scale=w=2*iw:h=2*ih 14681@end example 14682 14683@item 14684The above is the same as: 14685@example 14686scale=2*in_w:2*in_h 14687@end example 14688 14689@item 14690Scale the input to 2x with forced interlaced scaling: 14691@example 14692scale=2*iw:2*ih:interl=1 14693@end example 14694 14695@item 14696Scale the input to half size: 14697@example 14698scale=w=iw/2:h=ih/2 14699@end example 14700 14701@item 14702Increase the width, and set the height to the same size: 14703@example 14704scale=3/2*iw:ow 14705@end example 14706 14707@item 14708Seek Greek harmony: 14709@example 14710scale=iw:1/PHI*iw 14711scale=ih*PHI:ih 14712@end example 14713 14714@item 14715Increase the height, and set the width to 3/2 of the height: 14716@example 14717scale=w=3/2*oh:h=3/5*ih 14718@end example 14719 14720@item 14721Increase the size, making the size a multiple of the chroma 14722subsample values: 14723@example 14724scale="trunc(3/2*iw/hsub)*hsub:trunc(3/2*ih/vsub)*vsub" 14725@end example 14726 14727@item 14728Increase the width to a maximum of 500 pixels, 14729keeping the same aspect ratio as the input: 14730@example 14731scale=w='min(500\, iw*3/2):h=-1' 14732@end example 14733 14734@item 14735Make pixels square by combining scale and setsar: 14736@example 14737scale='trunc(ih*dar):ih',setsar=1/1 14738@end example 14739 14740@item 14741Make pixels square by combining scale and setsar, 14742making sure the resulting resolution is even (required by some codecs): 14743@example 14744scale='trunc(ih*dar/2)*2:trunc(ih/2)*2',setsar=1/1 14745@end example 14746@end itemize 14747 14748@subsection Commands 14749 14750This filter supports the following commands: 14751@table @option 14752@item width, w 14753@item height, h 14754Set the output video dimension expression. 14755The command accepts the same syntax of the corresponding option. 14756 14757If the specified expression is not valid, it is kept at its current 14758value. 14759@end table 14760 14761@section scale_npp 14762 14763Use the NVIDIA Performance Primitives (libnpp) to perform scaling and/or pixel 14764format conversion on CUDA video frames. Setting the output width and height 14765works in the same way as for the @var{scale} filter. 14766 14767The following additional options are accepted: 14768@table @option 14769@item format 14770The pixel format of the output CUDA frames. If set to the string "same" (the 14771default), the input format will be kept. Note that automatic format negotiation 14772and conversion is not yet supported for hardware frames 14773 14774@item interp_algo 14775The interpolation algorithm used for resizing. One of the following: 14776@table @option 14777@item nn 14778Nearest neighbour. 14779 14780@item linear 14781@item cubic 14782@item cubic2p_bspline 147832-parameter cubic (B=1, C=0) 14784 14785@item cubic2p_catmullrom 147862-parameter cubic (B=0, C=1/2) 14787 14788@item cubic2p_b05c03 147892-parameter cubic (B=1/2, C=3/10) 14790 14791@item super 14792Supersampling 14793 14794@item lanczos 14795@end table 14796 14797@end table 14798 14799@section scale2ref 14800 14801Scale (resize) the input video, based on a reference video. 14802 14803See the scale filter for available options, scale2ref supports the same but 14804uses the reference video instead of the main input as basis. scale2ref also 14805supports the following additional constants for the @option{w} and 14806@option{h} options: 14807 14808@table @var 14809@item main_w 14810@item main_h 14811The main input video's width and height 14812 14813@item main_a 14814The same as @var{main_w} / @var{main_h} 14815 14816@item main_sar 14817The main input video's sample aspect ratio 14818 14819@item main_dar, mdar 14820The main input video's display aspect ratio. Calculated from 14821@code{(main_w / main_h) * main_sar}. 14822 14823@item main_hsub 14824@item main_vsub 14825The main input video's horizontal and vertical chroma subsample values. 14826For example for the pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} 14827is 1. 14828@end table 14829 14830@subsection Examples 14831 14832@itemize 14833@item 14834Scale a subtitle stream (b) to match the main video (a) in size before overlaying 14835@example 14836'scale2ref[b][a];[a][b]overlay' 14837@end example 14838@end itemize 14839 14840@anchor{selectivecolor} 14841@section selectivecolor 14842 14843Adjust cyan, magenta, yellow and black (CMYK) to certain ranges of colors (such 14844as "reds", "yellows", "greens", "cyans", ...). The adjustment range is defined 14845by the "purity" of the color (that is, how saturated it already is). 14846 14847This filter is similar to the Adobe Photoshop Selective Color tool. 14848 14849The filter accepts the following options: 14850 14851@table @option 14852@item correction_method 14853Select color correction method. 14854 14855Available values are: 14856@table @samp 14857@item absolute 14858Specified adjustments are applied "as-is" (added/subtracted to original pixel 14859component value). 14860@item relative 14861Specified adjustments are relative to the original component value. 14862@end table 14863Default is @code{absolute}. 14864@item reds 14865Adjustments for red pixels (pixels where the red component is the maximum) 14866@item yellows 14867Adjustments for yellow pixels (pixels where the blue component is the minimum) 14868@item greens 14869Adjustments for green pixels (pixels where the green component is the maximum) 14870@item cyans 14871Adjustments for cyan pixels (pixels where the red component is the minimum) 14872@item blues 14873Adjustments for blue pixels (pixels where the blue component is the maximum) 14874@item magentas 14875Adjustments for magenta pixels (pixels where the green component is the minimum) 14876@item whites 14877Adjustments for white pixels (pixels where all components are greater than 128) 14878@item neutrals 14879Adjustments for all pixels except pure black and pure white 14880@item blacks 14881Adjustments for black pixels (pixels where all components are lesser than 128) 14882@item psfile 14883Specify a Photoshop selective color file (@code{.asv}) to import the settings from. 14884@end table 14885 14886All the adjustment settings (@option{reds}, @option{yellows}, ...) accept up to 148874 space separated floating point adjustment values in the [-1,1] range, 14888respectively to adjust the amount of cyan, magenta, yellow and black for the 14889pixels of its range. 14890 14891@subsection Examples 14892 14893@itemize 14894@item 14895Increase cyan by 50% and reduce yellow by 33% in every green areas, and 14896increase magenta by 27% in blue areas: 14897@example 14898selectivecolor=greens=.5 0 -.33 0:blues=0 .27 14899@end example 14900 14901@item 14902Use a Photoshop selective color preset: 14903@example 14904selectivecolor=psfile=MySelectiveColorPresets/Misty.asv 14905@end example 14906@end itemize 14907 14908@anchor{separatefields} 14909@section separatefields 14910 14911The @code{separatefields} takes a frame-based video input and splits 14912each frame into its components fields, producing a new half height clip 14913with twice the frame rate and twice the frame count. 14914 14915This filter use field-dominance information in frame to decide which 14916of each pair of fields to place first in the output. 14917If it gets it wrong use @ref{setfield} filter before @code{separatefields} filter. 14918 14919@section setdar, setsar 14920 14921The @code{setdar} filter sets the Display Aspect Ratio for the filter 14922output video. 14923 14924This is done by changing the specified Sample (aka Pixel) Aspect 14925Ratio, according to the following equation: 14926@example 14927@var{DAR} = @var{HORIZONTAL_RESOLUTION} / @var{VERTICAL_RESOLUTION} * @var{SAR} 14928@end example 14929 14930Keep in mind that the @code{setdar} filter does not modify the pixel 14931dimensions of the video frame. Also, the display aspect ratio set by 14932this filter may be changed by later filters in the filterchain, 14933e.g. in case of scaling or if another "setdar" or a "setsar" filter is 14934applied. 14935 14936The @code{setsar} filter sets the Sample (aka Pixel) Aspect Ratio for 14937the filter output video. 14938 14939Note that as a consequence of the application of this filter, the 14940output display aspect ratio will change according to the equation 14941above. 14942 14943Keep in mind that the sample aspect ratio set by the @code{setsar} 14944filter may be changed by later filters in the filterchain, e.g. if 14945another "setsar" or a "setdar" filter is applied. 14946 14947It accepts the following parameters: 14948 14949@table @option 14950@item r, ratio, dar (@code{setdar} only), sar (@code{setsar} only) 14951Set the aspect ratio used by the filter. 14952 14953The parameter can be a floating point number string, an expression, or 14954a string of the form @var{num}:@var{den}, where @var{num} and 14955@var{den} are the numerator and denominator of the aspect ratio. If 14956the parameter is not specified, it is assumed the value "0". 14957In case the form "@var{num}:@var{den}" is used, the @code{:} character 14958should be escaped. 14959 14960@item max 14961Set the maximum integer value to use for expressing numerator and 14962denominator when reducing the expressed aspect ratio to a rational. 14963Default value is @code{100}. 14964 14965@end table 14966 14967The parameter @var{sar} is an expression containing 14968the following constants: 14969 14970@table @option 14971@item E, PI, PHI 14972These are approximated values for the mathematical constants e 14973(Euler's number), pi (Greek pi), and phi (the golden ratio). 14974 14975@item w, h 14976The input width and height. 14977 14978@item a 14979These are the same as @var{w} / @var{h}. 14980 14981@item sar 14982The input sample aspect ratio. 14983 14984@item dar 14985The input display aspect ratio. It is the same as 14986(@var{w} / @var{h}) * @var{sar}. 14987 14988@item hsub, vsub 14989Horizontal and vertical chroma subsample values. For example, for the 14990pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1. 14991@end table 14992 14993@subsection Examples 14994 14995@itemize 14996 14997@item 14998To change the display aspect ratio to 16:9, specify one of the following: 14999@example 15000setdar=dar=1.77777 15001setdar=dar=16/9 15002@end example 15003 15004@item 15005To change the sample aspect ratio to 10:11, specify: 15006@example 15007setsar=sar=10/11 15008@end example 15009 15010@item 15011To set a display aspect ratio of 16:9, and specify a maximum integer value of 150121000 in the aspect ratio reduction, use the command: 15013@example 15014setdar=ratio=16/9:max=1000 15015@end example 15016 15017@end itemize 15018 15019@anchor{setfield} 15020@section setfield 15021 15022Force field for the output video frame. 15023 15024The @code{setfield} filter marks the interlace type field for the 15025output frames. It does not change the input frame, but only sets the 15026corresponding property, which affects how the frame is treated by 15027following filters (e.g. @code{fieldorder} or @code{yadif}). 15028 15029The filter accepts the following options: 15030 15031@table @option 15032 15033@item mode 15034Available values are: 15035 15036@table @samp 15037@item auto 15038Keep the same field property. 15039 15040@item bff 15041Mark the frame as bottom-field-first. 15042 15043@item tff 15044Mark the frame as top-field-first. 15045 15046@item prog 15047Mark the frame as progressive. 15048@end table 15049@end table 15050 15051@anchor{setparams} 15052@section setparams 15053 15054Force frame parameter for the output video frame. 15055 15056The @code{setparams} filter marks interlace and color range for the 15057output frames. It does not change the input frame, but only sets the 15058corresponding property, which affects how the frame is treated by 15059filters/encoders. 15060 15061@table @option 15062@item field_mode 15063Available values are: 15064 15065@table @samp 15066@item auto 15067Keep the same field property (default). 15068 15069@item bff 15070Mark the frame as bottom-field-first. 15071 15072@item tff 15073Mark the frame as top-field-first. 15074 15075@item prog 15076Mark the frame as progressive. 15077@end table 15078 15079@item range 15080Available values are: 15081 15082@table @samp 15083@item auto 15084Keep the same color range property (default). 15085 15086@item unspecified, unknown 15087Mark the frame as unspecified color range. 15088 15089@item limited, tv, mpeg 15090Mark the frame as limited range. 15091 15092@item full, pc, jpeg 15093Mark the frame as full range. 15094@end table 15095 15096@item color_primaries 15097Set the color primaries. 15098Available values are: 15099 15100@table @samp 15101@item auto 15102Keep the same color primaries property (default). 15103 15104@item bt709 15105@item unknown 15106@item bt470m 15107@item bt470bg 15108@item smpte170m 15109@item smpte240m 15110@item film 15111@item bt2020 15112@item smpte428 15113@item smpte431 15114@item smpte432 15115@item jedec-p22 15116@end table 15117 15118@item color_trc 15119Set the color transfert. 15120Available values are: 15121 15122@table @samp 15123@item auto 15124Keep the same color trc property (default). 15125 15126@item bt709 15127@item unknown 15128@item bt470m 15129@item bt470bg 15130@item smpte170m 15131@item smpte240m 15132@item linear 15133@item log100 15134@item log316 15135@item iec61966-2-4 15136@item bt1361e 15137@item iec61966-2-1 15138@item bt2020-10 15139@item bt2020-12 15140@item smpte2084 15141@item smpte428 15142@item arib-std-b67 15143@end table 15144 15145@item colorspace 15146Set the colorspace. 15147Available values are: 15148 15149@table @samp 15150@item auto 15151Keep the same colorspace property (default). 15152 15153@item gbr 15154@item bt709 15155@item unknown 15156@item fcc 15157@item bt470bg 15158@item smpte170m 15159@item smpte240m 15160@item ycgco 15161@item bt2020nc 15162@item bt2020c 15163@item smpte2085 15164@item chroma-derived-nc 15165@item chroma-derived-c 15166@item ictcp 15167@end table 15168@end table 15169 15170@section showinfo 15171 15172Show a line containing various information for each input video frame. 15173The input video is not modified. 15174 15175The shown line contains a sequence of key/value pairs of the form 15176@var{key}:@var{value}. 15177 15178The following values are shown in the output: 15179 15180@table @option 15181@item n 15182The (sequential) number of the input frame, starting from 0. 15183 15184@item pts 15185The Presentation TimeStamp of the input frame, expressed as a number of 15186time base units. The time base unit depends on the filter input pad. 15187 15188@item pts_time 15189The Presentation TimeStamp of the input frame, expressed as a number of 15190seconds. 15191 15192@item pos 15193The position of the frame in the input stream, or -1 if this information is 15194unavailable and/or meaningless (for example in case of synthetic video). 15195 15196@item fmt 15197The pixel format name. 15198 15199@item sar 15200The sample aspect ratio of the input frame, expressed in the form 15201@var{num}/@var{den}. 15202 15203@item s 15204The size of the input frame. For the syntax of this option, check the 15205@ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}. 15206 15207@item i 15208The type of interlaced mode ("P" for "progressive", "T" for top field first, "B" 15209for bottom field first). 15210 15211@item iskey 15212This is 1 if the frame is a key frame, 0 otherwise. 15213 15214@item type 15215The picture type of the input frame ("I" for an I-frame, "P" for a 15216P-frame, "B" for a B-frame, or "?" for an unknown type). 15217Also refer to the documentation of the @code{AVPictureType} enum and of 15218the @code{av_get_picture_type_char} function defined in 15219@file{libavutil/avutil.h}. 15220 15221@item checksum 15222The Adler-32 checksum (printed in hexadecimal) of all the planes of the input frame. 15223 15224@item plane_checksum 15225The Adler-32 checksum (printed in hexadecimal) of each plane of the input frame, 15226expressed in the form "[@var{c0} @var{c1} @var{c2} @var{c3}]". 15227@end table 15228 15229@section showpalette 15230 15231Displays the 256 colors palette of each frame. This filter is only relevant for 15232@var{pal8} pixel format frames. 15233 15234It accepts the following option: 15235 15236@table @option 15237@item s 15238Set the size of the box used to represent one palette color entry. Default is 15239@code{30} (for a @code{30x30} pixel box). 15240@end table 15241 15242@section shuffleframes 15243 15244Reorder and/or duplicate and/or drop video frames. 15245 15246It accepts the following parameters: 15247 15248@table @option 15249@item mapping 15250Set the destination indexes of input frames. 15251This is space or '|' separated list of indexes that maps input frames to output 15252frames. Number of indexes also sets maximal value that each index may have. 15253'-1' index have special meaning and that is to drop frame. 15254@end table 15255 15256The first frame has the index 0. The default is to keep the input unchanged. 15257 15258@subsection Examples 15259 15260@itemize 15261@item 15262Swap second and third frame of every three frames of the input: 15263@example 15264ffmpeg -i INPUT -vf "shuffleframes=0 2 1" OUTPUT 15265@end example 15266 15267@item 15268Swap 10th and 1st frame of every ten frames of the input: 15269@example 15270ffmpeg -i INPUT -vf "shuffleframes=9 1 2 3 4 5 6 7 8 0" OUTPUT 15271@end example 15272@end itemize 15273 15274@section shuffleplanes 15275 15276Reorder and/or duplicate video planes. 15277 15278It accepts the following parameters: 15279 15280@table @option 15281 15282@item map0 15283The index of the input plane to be used as the first output plane. 15284 15285@item map1 15286The index of the input plane to be used as the second output plane. 15287 15288@item map2 15289The index of the input plane to be used as the third output plane. 15290 15291@item map3 15292The index of the input plane to be used as the fourth output plane. 15293 15294@end table 15295 15296The first plane has the index 0. The default is to keep the input unchanged. 15297 15298@subsection Examples 15299 15300@itemize 15301@item 15302Swap the second and third planes of the input: 15303@example 15304ffmpeg -i INPUT -vf shuffleplanes=0:2:1:3 OUTPUT 15305@end example 15306@end itemize 15307 15308@anchor{signalstats} 15309@section signalstats 15310Evaluate various visual metrics that assist in determining issues associated 15311with the digitization of analog video media. 15312 15313By default the filter will log these metadata values: 15314 15315@table @option 15316@item YMIN 15317Display the minimal Y value contained within the input frame. Expressed in 15318range of [0-255]. 15319 15320@item YLOW 15321Display the Y value at the 10% percentile within the input frame. Expressed in 15322range of [0-255]. 15323 15324@item YAVG 15325Display the average Y value within the input frame. Expressed in range of 15326[0-255]. 15327 15328@item YHIGH 15329Display the Y value at the 90% percentile within the input frame. Expressed in 15330range of [0-255]. 15331 15332@item YMAX 15333Display the maximum Y value contained within the input frame. Expressed in 15334range of [0-255]. 15335 15336@item UMIN 15337Display the minimal U value contained within the input frame. Expressed in 15338range of [0-255]. 15339 15340@item ULOW 15341Display the U value at the 10% percentile within the input frame. Expressed in 15342range of [0-255]. 15343 15344@item UAVG 15345Display the average U value within the input frame. Expressed in range of 15346[0-255]. 15347 15348@item UHIGH 15349Display the U value at the 90% percentile within the input frame. Expressed in 15350range of [0-255]. 15351 15352@item UMAX 15353Display the maximum U value contained within the input frame. Expressed in 15354range of [0-255]. 15355 15356@item VMIN 15357Display the minimal V value contained within the input frame. Expressed in 15358range of [0-255]. 15359 15360@item VLOW 15361Display the V value at the 10% percentile within the input frame. Expressed in 15362range of [0-255]. 15363 15364@item VAVG 15365Display the average V value within the input frame. Expressed in range of 15366[0-255]. 15367 15368@item VHIGH 15369Display the V value at the 90% percentile within the input frame. Expressed in 15370range of [0-255]. 15371 15372@item VMAX 15373Display the maximum V value contained within the input frame. Expressed in 15374range of [0-255]. 15375 15376@item SATMIN 15377Display the minimal saturation value contained within the input frame. 15378Expressed in range of [0-~181.02]. 15379 15380@item SATLOW 15381Display the saturation value at the 10% percentile within the input frame. 15382Expressed in range of [0-~181.02]. 15383 15384@item SATAVG 15385Display the average saturation value within the input frame. Expressed in range 15386of [0-~181.02]. 15387 15388@item SATHIGH 15389Display the saturation value at the 90% percentile within the input frame. 15390Expressed in range of [0-~181.02]. 15391 15392@item SATMAX 15393Display the maximum saturation value contained within the input frame. 15394Expressed in range of [0-~181.02]. 15395 15396@item HUEMED 15397Display the median value for hue within the input frame. Expressed in range of 15398[0-360]. 15399 15400@item HUEAVG 15401Display the average value for hue within the input frame. Expressed in range of 15402[0-360]. 15403 15404@item YDIF 15405Display the average of sample value difference between all values of the Y 15406plane in the current frame and corresponding values of the previous input frame. 15407Expressed in range of [0-255]. 15408 15409@item UDIF 15410Display the average of sample value difference between all values of the U 15411plane in the current frame and corresponding values of the previous input frame. 15412Expressed in range of [0-255]. 15413 15414@item VDIF 15415Display the average of sample value difference between all values of the V 15416plane in the current frame and corresponding values of the previous input frame. 15417Expressed in range of [0-255]. 15418 15419@item YBITDEPTH 15420Display bit depth of Y plane in current frame. 15421Expressed in range of [0-16]. 15422 15423@item UBITDEPTH 15424Display bit depth of U plane in current frame. 15425Expressed in range of [0-16]. 15426 15427@item VBITDEPTH 15428Display bit depth of V plane in current frame. 15429Expressed in range of [0-16]. 15430@end table 15431 15432The filter accepts the following options: 15433 15434@table @option 15435@item stat 15436@item out 15437 15438@option{stat} specify an additional form of image analysis. 15439@option{out} output video with the specified type of pixel highlighted. 15440 15441Both options accept the following values: 15442 15443@table @samp 15444@item tout 15445Identify @var{temporal outliers} pixels. A @var{temporal outlier} is a pixel 15446unlike the neighboring pixels of the same field. Examples of temporal outliers 15447include the results of video dropouts, head clogs, or tape tracking issues. 15448 15449@item vrep 15450Identify @var{vertical line repetition}. Vertical line repetition includes 15451similar rows of pixels within a frame. In born-digital video vertical line 15452repetition is common, but this pattern is uncommon in video digitized from an 15453analog source. When it occurs in video that results from the digitization of an 15454analog source it can indicate concealment from a dropout compensator. 15455 15456@item brng 15457Identify pixels that fall outside of legal broadcast range. 15458@end table 15459 15460@item color, c 15461Set the highlight color for the @option{out} option. The default color is 15462yellow. 15463@end table 15464 15465@subsection Examples 15466 15467@itemize 15468@item 15469Output data of various video metrics: 15470@example 15471ffprobe -f lavfi movie=example.mov,signalstats="stat=tout+vrep+brng" -show_frames 15472@end example 15473 15474@item 15475Output specific data about the minimum and maximum values of the Y plane per frame: 15476@example 15477ffprobe -f lavfi movie=example.mov,signalstats -show_entries frame_tags=lavfi.signalstats.YMAX,lavfi.signalstats.YMIN 15478@end example 15479 15480@item 15481Playback video while highlighting pixels that are outside of broadcast range in red. 15482@example 15483ffplay example.mov -vf signalstats="out=brng:color=red" 15484@end example 15485 15486@item 15487Playback video with signalstats metadata drawn over the frame. 15488@example 15489ffplay example.mov -vf signalstats=stat=brng+vrep+tout,drawtext=fontfile=FreeSerif.ttf:textfile=signalstat_drawtext.txt 15490@end example 15491 15492The contents of signalstat_drawtext.txt used in the command are: 15493@example 15494time %@{pts:hms@} 15495Y (%@{metadata:lavfi.signalstats.YMIN@}-%@{metadata:lavfi.signalstats.YMAX@}) 15496U (%@{metadata:lavfi.signalstats.UMIN@}-%@{metadata:lavfi.signalstats.UMAX@}) 15497V (%@{metadata:lavfi.signalstats.VMIN@}-%@{metadata:lavfi.signalstats.VMAX@}) 15498saturation maximum: %@{metadata:lavfi.signalstats.SATMAX@} 15499 15500@end example 15501@end itemize 15502 15503@anchor{signature} 15504@section signature 15505 15506Calculates the MPEG-7 Video Signature. The filter can handle more than one 15507input. In this case the matching between the inputs can be calculated additionally. 15508The filter always passes through the first input. The signature of each stream can 15509be written into a file. 15510 15511It accepts the following options: 15512 15513@table @option 15514@item detectmode 15515Enable or disable the matching process. 15516 15517Available values are: 15518 15519@table @samp 15520@item off 15521Disable the calculation of a matching (default). 15522@item full 15523Calculate the matching for the whole video and output whether the whole video 15524matches or only parts. 15525@item fast 15526Calculate only until a matching is found or the video ends. Should be faster in 15527some cases. 15528@end table 15529 15530@item nb_inputs 15531Set the number of inputs. The option value must be a non negative integer. 15532Default value is 1. 15533 15534@item filename 15535Set the path to which the output is written. If there is more than one input, 15536the path must be a prototype, i.e. must contain %d or %0nd (where n is a positive 15537integer), that will be replaced with the input number. If no filename is 15538specified, no output will be written. This is the default. 15539 15540@item format 15541Choose the output format. 15542 15543Available values are: 15544 15545@table @samp 15546@item binary 15547Use the specified binary representation (default). 15548@item xml 15549Use the specified xml representation. 15550@end table 15551 15552@item th_d 15553Set threshold to detect one word as similar. The option value must be an integer 15554greater than zero. The default value is 9000. 15555 15556@item th_dc 15557Set threshold to detect all words as similar. The option value must be an integer 15558greater than zero. The default value is 60000. 15559 15560@item th_xh 15561Set threshold to detect frames as similar. The option value must be an integer 15562greater than zero. The default value is 116. 15563 15564@item th_di 15565Set the minimum length of a sequence in frames to recognize it as matching 15566sequence. The option value must be a non negative integer value. 15567The default value is 0. 15568 15569@item th_it 15570Set the minimum relation, that matching frames to all frames must have. 15571The option value must be a double value between 0 and 1. The default value is 0.5. 15572@end table 15573 15574@subsection Examples 15575 15576@itemize 15577@item 15578To calculate the signature of an input video and store it in signature.bin: 15579@example 15580ffmpeg -i input.mkv -vf signature=filename=signature.bin -map 0:v -f null - 15581@end example 15582 15583@item 15584To detect whether two videos match and store the signatures in XML format in 15585signature0.xml and signature1.xml: 15586@example 15587ffmpeg -i input1.mkv -i input2.mkv -filter_complex "[0:v][1:v] signature=nb_inputs=2:detectmode=full:format=xml:filename=signature%d.xml" -map :v -f null - 15588@end example 15589 15590@end itemize 15591 15592@anchor{smartblur} 15593@section smartblur 15594 15595Blur the input video without impacting the outlines. 15596 15597It accepts the following options: 15598 15599@table @option 15600@item luma_radius, lr 15601Set the luma radius. The option value must be a float number in 15602the range [0.1,5.0] that specifies the variance of the gaussian filter 15603used to blur the image (slower if larger). Default value is 1.0. 15604 15605@item luma_strength, ls 15606Set the luma strength. The option value must be a float number 15607in the range [-1.0,1.0] that configures the blurring. A value included 15608in [0.0,1.0] will blur the image whereas a value included in 15609[-1.0,0.0] will sharpen the image. Default value is 1.0. 15610 15611@item luma_threshold, lt 15612Set the luma threshold used as a coefficient to determine 15613whether a pixel should be blurred or not. The option value must be an 15614integer in the range [-30,30]. A value of 0 will filter all the image, 15615a value included in [0,30] will filter flat areas and a value included 15616in [-30,0] will filter edges. Default value is 0. 15617 15618@item chroma_radius, cr 15619Set the chroma radius. The option value must be a float number in 15620the range [0.1,5.0] that specifies the variance of the gaussian filter 15621used to blur the image (slower if larger). Default value is @option{luma_radius}. 15622 15623@item chroma_strength, cs 15624Set the chroma strength. The option value must be a float number 15625in the range [-1.0,1.0] that configures the blurring. A value included 15626in [0.0,1.0] will blur the image whereas a value included in 15627[-1.0,0.0] will sharpen the image. Default value is @option{luma_strength}. 15628 15629@item chroma_threshold, ct 15630Set the chroma threshold used as a coefficient to determine 15631whether a pixel should be blurred or not. The option value must be an 15632integer in the range [-30,30]. A value of 0 will filter all the image, 15633a value included in [0,30] will filter flat areas and a value included 15634in [-30,0] will filter edges. Default value is @option{luma_threshold}. 15635@end table 15636 15637If a chroma option is not explicitly set, the corresponding luma value 15638is set. 15639 15640@section ssim 15641 15642Obtain the SSIM (Structural SImilarity Metric) between two input videos. 15643 15644This filter takes in input two input videos, the first input is 15645considered the "main" source and is passed unchanged to the 15646output. The second input is used as a "reference" video for computing 15647the SSIM. 15648 15649Both video inputs must have the same resolution and pixel format for 15650this filter to work correctly. Also it assumes that both inputs 15651have the same number of frames, which are compared one by one. 15652 15653The filter stores the calculated SSIM of each frame. 15654 15655The description of the accepted parameters follows. 15656 15657@table @option 15658@item stats_file, f 15659If specified the filter will use the named file to save the SSIM of 15660each individual frame. When filename equals "-" the data is sent to 15661standard output. 15662@end table 15663 15664The file printed if @var{stats_file} is selected, contains a sequence of 15665key/value pairs of the form @var{key}:@var{value} for each compared 15666couple of frames. 15667 15668A description of each shown parameter follows: 15669 15670@table @option 15671@item n 15672sequential number of the input frame, starting from 1 15673 15674@item Y, U, V, R, G, B 15675SSIM of the compared frames for the component specified by the suffix. 15676 15677@item All 15678SSIM of the compared frames for the whole frame. 15679 15680@item dB 15681Same as above but in dB representation. 15682@end table 15683 15684This filter also supports the @ref{framesync} options. 15685 15686For example: 15687@example 15688movie=ref_movie.mpg, setpts=PTS-STARTPTS [main]; 15689[main][ref] ssim="stats_file=stats.log" [out] 15690@end example 15691 15692On this example the input file being processed is compared with the 15693reference file @file{ref_movie.mpg}. The SSIM of each individual frame 15694is stored in @file{stats.log}. 15695 15696Another example with both psnr and ssim at same time: 15697@example 15698ffmpeg -i main.mpg -i ref.mpg -lavfi "ssim;[0:v][1:v]psnr" -f null - 15699@end example 15700 15701@section stereo3d 15702 15703Convert between different stereoscopic image formats. 15704 15705The filters accept the following options: 15706 15707@table @option 15708@item in 15709Set stereoscopic image format of input. 15710 15711Available values for input image formats are: 15712@table @samp 15713@item sbsl 15714side by side parallel (left eye left, right eye right) 15715 15716@item sbsr 15717side by side crosseye (right eye left, left eye right) 15718 15719@item sbs2l 15720side by side parallel with half width resolution 15721(left eye left, right eye right) 15722 15723@item sbs2r 15724side by side crosseye with half width resolution 15725(right eye left, left eye right) 15726 15727@item abl 15728above-below (left eye above, right eye below) 15729 15730@item abr 15731above-below (right eye above, left eye below) 15732 15733@item ab2l 15734above-below with half height resolution 15735(left eye above, right eye below) 15736 15737@item ab2r 15738above-below with half height resolution 15739(right eye above, left eye below) 15740 15741@item al 15742alternating frames (left eye first, right eye second) 15743 15744@item ar 15745alternating frames (right eye first, left eye second) 15746 15747@item irl 15748interleaved rows (left eye has top row, right eye starts on next row) 15749 15750@item irr 15751interleaved rows (right eye has top row, left eye starts on next row) 15752 15753@item icl 15754interleaved columns, left eye first 15755 15756@item icr 15757interleaved columns, right eye first 15758 15759Default value is @samp{sbsl}. 15760@end table 15761 15762@item out 15763Set stereoscopic image format of output. 15764 15765@table @samp 15766@item sbsl 15767side by side parallel (left eye left, right eye right) 15768 15769@item sbsr 15770side by side crosseye (right eye left, left eye right) 15771 15772@item sbs2l 15773side by side parallel with half width resolution 15774(left eye left, right eye right) 15775 15776@item sbs2r 15777side by side crosseye with half width resolution 15778(right eye left, left eye right) 15779 15780@item abl 15781above-below (left eye above, right eye below) 15782 15783@item abr 15784above-below (right eye above, left eye below) 15785 15786@item ab2l 15787above-below with half height resolution 15788(left eye above, right eye below) 15789 15790@item ab2r 15791above-below with half height resolution 15792(right eye above, left eye below) 15793 15794@item al 15795alternating frames (left eye first, right eye second) 15796 15797@item ar 15798alternating frames (right eye first, left eye second) 15799 15800@item irl 15801interleaved rows (left eye has top row, right eye starts on next row) 15802 15803@item irr 15804interleaved rows (right eye has top row, left eye starts on next row) 15805 15806@item arbg 15807anaglyph red/blue gray 15808(red filter on left eye, blue filter on right eye) 15809 15810@item argg 15811anaglyph red/green gray 15812(red filter on left eye, green filter on right eye) 15813 15814@item arcg 15815anaglyph red/cyan gray 15816(red filter on left eye, cyan filter on right eye) 15817 15818@item arch 15819anaglyph red/cyan half colored 15820(red filter on left eye, cyan filter on right eye) 15821 15822@item arcc 15823anaglyph red/cyan color 15824(red filter on left eye, cyan filter on right eye) 15825 15826@item arcd 15827anaglyph red/cyan color optimized with the least squares projection of dubois 15828(red filter on left eye, cyan filter on right eye) 15829 15830@item agmg 15831anaglyph green/magenta gray 15832(green filter on left eye, magenta filter on right eye) 15833 15834@item agmh 15835anaglyph green/magenta half colored 15836(green filter on left eye, magenta filter on right eye) 15837 15838@item agmc 15839anaglyph green/magenta colored 15840(green filter on left eye, magenta filter on right eye) 15841 15842@item agmd 15843anaglyph green/magenta color optimized with the least squares projection of dubois 15844(green filter on left eye, magenta filter on right eye) 15845 15846@item aybg 15847anaglyph yellow/blue gray 15848(yellow filter on left eye, blue filter on right eye) 15849 15850@item aybh 15851anaglyph yellow/blue half colored 15852(yellow filter on left eye, blue filter on right eye) 15853 15854@item aybc 15855anaglyph yellow/blue colored 15856(yellow filter on left eye, blue filter on right eye) 15857 15858@item aybd 15859anaglyph yellow/blue color optimized with the least squares projection of dubois 15860(yellow filter on left eye, blue filter on right eye) 15861 15862@item ml 15863mono output (left eye only) 15864 15865@item mr 15866mono output (right eye only) 15867 15868@item chl 15869checkerboard, left eye first 15870 15871@item chr 15872checkerboard, right eye first 15873 15874@item icl 15875interleaved columns, left eye first 15876 15877@item icr 15878interleaved columns, right eye first 15879 15880@item hdmi 15881HDMI frame pack 15882@end table 15883 15884Default value is @samp{arcd}. 15885@end table 15886 15887@subsection Examples 15888 15889@itemize 15890@item 15891Convert input video from side by side parallel to anaglyph yellow/blue dubois: 15892@example 15893stereo3d=sbsl:aybd 15894@end example 15895 15896@item 15897Convert input video from above below (left eye above, right eye below) to side by side crosseye. 15898@example 15899stereo3d=abl:sbsr 15900@end example 15901@end itemize 15902 15903@section streamselect, astreamselect 15904Select video or audio streams. 15905 15906The filter accepts the following options: 15907 15908@table @option 15909@item inputs 15910Set number of inputs. Default is 2. 15911 15912@item map 15913Set input indexes to remap to outputs. 15914@end table 15915 15916@subsection Commands 15917 15918The @code{streamselect} and @code{astreamselect} filter supports the following 15919commands: 15920 15921@table @option 15922@item map 15923Set input indexes to remap to outputs. 15924@end table 15925 15926@subsection Examples 15927 15928@itemize 15929@item 15930Select first 5 seconds 1st stream and rest of time 2nd stream: 15931@example 15932sendcmd='5.0 streamselect map 1',streamselect=inputs=2:map=0 15933@end example 15934 15935@item 15936Same as above, but for audio: 15937@example 15938asendcmd='5.0 astreamselect map 1',astreamselect=inputs=2:map=0 15939@end example 15940@end itemize 15941 15942@section sobel 15943Apply sobel operator to input video stream. 15944 15945The filter accepts the following option: 15946 15947@table @option 15948@item planes 15949Set which planes will be processed, unprocessed planes will be copied. 15950By default value 0xf, all planes will be processed. 15951 15952@item scale 15953Set value which will be multiplied with filtered result. 15954 15955@item delta 15956Set value which will be added to filtered result. 15957@end table 15958 15959@anchor{spp} 15960@section spp 15961 15962Apply a simple postprocessing filter that compresses and decompresses the image 15963at several (or - in the case of @option{quality} level @code{6} - all) shifts 15964and average the results. 15965 15966The filter accepts the following options: 15967 15968@table @option 15969@item quality 15970Set quality. This option defines the number of levels for averaging. It accepts 15971an integer in the range 0-6. If set to @code{0}, the filter will have no 15972effect. A value of @code{6} means the higher quality. For each increment of 15973that value the speed drops by a factor of approximately 2. Default value is 15974@code{3}. 15975 15976@item qp 15977Force a constant quantization parameter. If not set, the filter will use the QP 15978from the video stream (if available). 15979 15980@item mode 15981Set thresholding mode. Available modes are: 15982 15983@table @samp 15984@item hard 15985Set hard thresholding (default). 15986@item soft 15987Set soft thresholding (better de-ringing effect, but likely blurrier). 15988@end table 15989 15990@item use_bframe_qp 15991Enable the use of the QP from the B-Frames if set to @code{1}. Using this 15992option may cause flicker since the B-Frames have often larger QP. Default is 15993@code{0} (not enabled). 15994@end table 15995 15996@section sr 15997 15998Scale the input by applying one of the super-resolution methods based on 15999convolutional neural networks. Supported models: 16000 16001@itemize 16002@item 16003Super-Resolution Convolutional Neural Network model (SRCNN). 16004See @url{https://arxiv.org/abs/1501.00092}. 16005 16006@item 16007Efficient Sub-Pixel Convolutional Neural Network model (ESPCN). 16008See @url{https://arxiv.org/abs/1609.05158}. 16009@end itemize 16010 16011Training scripts as well as scripts for model generation are provided in 16012the repository at @url{https://github.com/HighVoltageRocknRoll/sr.git}. 16013 16014The filter accepts the following options: 16015 16016@table @option 16017@item dnn_backend 16018Specify which DNN backend to use for model loading and execution. This option accepts 16019the following values: 16020 16021@table @samp 16022@item native 16023Native implementation of DNN loading and execution. 16024 16025@item tensorflow 16026TensorFlow backend. To enable this backend you 16027need to install the TensorFlow for C library (see 16028@url{https://www.tensorflow.org/install/install_c}) and configure FFmpeg with 16029@code{--enable-libtensorflow} 16030@end table 16031 16032Default value is @samp{native}. 16033 16034@item model 16035Set path to model file specifying network architecture and its parameters. 16036Note that different backends use different file formats. TensorFlow backend 16037can load files for both formats, while native backend can load files for only 16038its format. 16039 16040@item scale_factor 16041Set scale factor for SRCNN model. Allowed values are @code{2}, @code{3} and @code{4}. 16042Default value is @code{2}. Scale factor is necessary for SRCNN model, because it accepts 16043input upscaled using bicubic upscaling with proper scale factor. 16044@end table 16045 16046@anchor{subtitles} 16047@section subtitles 16048 16049Draw subtitles on top of input video using the libass library. 16050 16051To enable compilation of this filter you need to configure FFmpeg with 16052@code{--enable-libass}. This filter also requires a build with libavcodec and 16053libavformat to convert the passed subtitles file to ASS (Advanced Substation 16054Alpha) subtitles format. 16055 16056The filter accepts the following options: 16057 16058@table @option 16059@item filename, f 16060Set the filename of the subtitle file to read. It must be specified. 16061 16062@item original_size 16063Specify the size of the original video, the video for which the ASS file 16064was composed. For the syntax of this option, check the 16065@ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}. 16066Due to a misdesign in ASS aspect ratio arithmetic, this is necessary to 16067correctly scale the fonts if the aspect ratio has been changed. 16068 16069@item fontsdir 16070Set a directory path containing fonts that can be used by the filter. 16071These fonts will be used in addition to whatever the font provider uses. 16072 16073@item alpha 16074Process alpha channel, by default alpha channel is untouched. 16075 16076@item charenc 16077Set subtitles input character encoding. @code{subtitles} filter only. Only 16078useful if not UTF-8. 16079 16080@item stream_index, si 16081Set subtitles stream index. @code{subtitles} filter only. 16082 16083@item force_style 16084Override default style or script info parameters of the subtitles. It accepts a 16085string containing ASS style format @code{KEY=VALUE} couples separated by ",". 16086@end table 16087 16088If the first key is not specified, it is assumed that the first value 16089specifies the @option{filename}. 16090 16091For example, to render the file @file{sub.srt} on top of the input 16092video, use the command: 16093@example 16094subtitles=sub.srt 16095@end example 16096 16097which is equivalent to: 16098@example 16099subtitles=filename=sub.srt 16100@end example 16101 16102To render the default subtitles stream from file @file{video.mkv}, use: 16103@example 16104subtitles=video.mkv 16105@end example 16106 16107To render the second subtitles stream from that file, use: 16108@example 16109subtitles=video.mkv:si=1 16110@end example 16111 16112To make the subtitles stream from @file{sub.srt} appear in 80% transparent blue 16113@code{DejaVu Serif}, use: 16114@example 16115subtitles=sub.srt:force_style='FontName=DejaVu Serif,PrimaryColour=&HCCFF0000' 16116@end example 16117 16118@section super2xsai 16119 16120Scale the input by 2x and smooth using the Super2xSaI (Scale and 16121Interpolate) pixel art scaling algorithm. 16122 16123Useful for enlarging pixel art images without reducing sharpness. 16124 16125@section swaprect 16126 16127Swap two rectangular objects in video. 16128 16129This filter accepts the following options: 16130 16131@table @option 16132@item w 16133Set object width. 16134 16135@item h 16136Set object height. 16137 16138@item x1 16139Set 1st rect x coordinate. 16140 16141@item y1 16142Set 1st rect y coordinate. 16143 16144@item x2 16145Set 2nd rect x coordinate. 16146 16147@item y2 16148Set 2nd rect y coordinate. 16149 16150All expressions are evaluated once for each frame. 16151@end table 16152 16153The all options are expressions containing the following constants: 16154 16155@table @option 16156@item w 16157@item h 16158The input width and height. 16159 16160@item a 16161same as @var{w} / @var{h} 16162 16163@item sar 16164input sample aspect ratio 16165 16166@item dar 16167input display aspect ratio, it is the same as (@var{w} / @var{h}) * @var{sar} 16168 16169@item n 16170The number of the input frame, starting from 0. 16171 16172@item t 16173The timestamp expressed in seconds. It's NAN if the input timestamp is unknown. 16174 16175@item pos 16176the position in the file of the input frame, NAN if unknown 16177@end table 16178 16179@section swapuv 16180Swap U & V plane. 16181 16182@section telecine 16183 16184Apply telecine process to the video. 16185 16186This filter accepts the following options: 16187 16188@table @option 16189@item first_field 16190@table @samp 16191@item top, t 16192top field first 16193@item bottom, b 16194bottom field first 16195The default value is @code{top}. 16196@end table 16197 16198@item pattern 16199A string of numbers representing the pulldown pattern you wish to apply. 16200The default value is @code{23}. 16201@end table 16202 16203@example 16204Some typical patterns: 16205 16206NTSC output (30i): 1620727.5p: 32222 1620824p: 23 (classic) 1620924p: 2332 (preferred) 1621020p: 33 1621118p: 334 1621216p: 3444 16213 16214PAL output (25i): 1621527.5p: 12222 1621624p: 222222222223 ("Euro pulldown") 1621716.67p: 33 1621816p: 33333334 16219@end example 16220 16221@section threshold 16222 16223Apply threshold effect to video stream. 16224 16225This filter needs four video streams to perform thresholding. 16226First stream is stream we are filtering. 16227Second stream is holding threshold values, third stream is holding min values, 16228and last, fourth stream is holding max values. 16229 16230The filter accepts the following option: 16231 16232@table @option 16233@item planes 16234Set which planes will be processed, unprocessed planes will be copied. 16235By default value 0xf, all planes will be processed. 16236@end table 16237 16238For example if first stream pixel's component value is less then threshold value 16239of pixel component from 2nd threshold stream, third stream value will picked, 16240otherwise fourth stream pixel component value will be picked. 16241 16242Using color source filter one can perform various types of thresholding: 16243 16244@subsection Examples 16245 16246@itemize 16247@item 16248Binary threshold, using gray color as threshold: 16249@example 16250ffmpeg -i 320x240.avi -f lavfi -i color=gray -f lavfi -i color=black -f lavfi -i color=white -lavfi threshold output.avi 16251@end example 16252 16253@item 16254Inverted binary threshold, using gray color as threshold: 16255@example 16256ffmpeg -i 320x240.avi -f lavfi -i color=gray -f lavfi -i color=white -f lavfi -i color=black -lavfi threshold output.avi 16257@end example 16258 16259@item 16260Truncate binary threshold, using gray color as threshold: 16261@example 16262ffmpeg -i 320x240.avi -f lavfi -i color=gray -i 320x240.avi -f lavfi -i color=gray -lavfi threshold output.avi 16263@end example 16264 16265@item 16266Threshold to zero, using gray color as threshold: 16267@example 16268ffmpeg -i 320x240.avi -f lavfi -i color=gray -f lavfi -i color=white -i 320x240.avi -lavfi threshold output.avi 16269@end example 16270 16271@item 16272Inverted threshold to zero, using gray color as threshold: 16273@example 16274ffmpeg -i 320x240.avi -f lavfi -i color=gray -i 320x240.avi -f lavfi -i color=white -lavfi threshold output.avi 16275@end example 16276@end itemize 16277 16278@section thumbnail 16279Select the most representative frame in a given sequence of consecutive frames. 16280 16281The filter accepts the following options: 16282 16283@table @option 16284@item n 16285Set the frames batch size to analyze; in a set of @var{n} frames, the filter 16286will pick one of them, and then handle the next batch of @var{n} frames until 16287the end. Default is @code{100}. 16288@end table 16289 16290Since the filter keeps track of the whole frames sequence, a bigger @var{n} 16291value will result in a higher memory usage, so a high value is not recommended. 16292 16293@subsection Examples 16294 16295@itemize 16296@item 16297Extract one picture each 50 frames: 16298@example 16299thumbnail=50 16300@end example 16301 16302@item 16303Complete example of a thumbnail creation with @command{ffmpeg}: 16304@example 16305ffmpeg -i in.avi -vf thumbnail,scale=300:200 -frames:v 1 out.png 16306@end example 16307@end itemize 16308 16309@section tile 16310 16311Tile several successive frames together. 16312 16313The filter accepts the following options: 16314 16315@table @option 16316 16317@item layout 16318Set the grid size (i.e. the number of lines and columns). For the syntax of 16319this option, check the 16320@ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}. 16321 16322@item nb_frames 16323Set the maximum number of frames to render in the given area. It must be less 16324than or equal to @var{w}x@var{h}. The default value is @code{0}, meaning all 16325the area will be used. 16326 16327@item margin 16328Set the outer border margin in pixels. 16329 16330@item padding 16331Set the inner border thickness (i.e. the number of pixels between frames). For 16332more advanced padding options (such as having different values for the edges), 16333refer to the pad video filter. 16334 16335@item color 16336Specify the color of the unused area. For the syntax of this option, check the 16337@ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}. 16338The default value of @var{color} is "black". 16339 16340@item overlap 16341Set the number of frames to overlap when tiling several successive frames together. 16342The value must be between @code{0} and @var{nb_frames - 1}. 16343 16344@item init_padding 16345Set the number of frames to initially be empty before displaying first output frame. 16346This controls how soon will one get first output frame. 16347The value must be between @code{0} and @var{nb_frames - 1}. 16348@end table 16349 16350@subsection Examples 16351 16352@itemize 16353@item 16354Produce 8x8 PNG tiles of all keyframes (@option{-skip_frame nokey}) in a movie: 16355@example 16356ffmpeg -skip_frame nokey -i file.avi -vf 'scale=128:72,tile=8x8' -an -vsync 0 keyframes%03d.png 16357@end example 16358The @option{-vsync 0} is necessary to prevent @command{ffmpeg} from 16359duplicating each output frame to accommodate the originally detected frame 16360rate. 16361 16362@item 16363Display @code{5} pictures in an area of @code{3x2} frames, 16364with @code{7} pixels between them, and @code{2} pixels of initial margin, using 16365mixed flat and named options: 16366@example 16367tile=3x2:nb_frames=5:padding=7:margin=2 16368@end example 16369@end itemize 16370 16371@section tinterlace 16372 16373Perform various types of temporal field interlacing. 16374 16375Frames are counted starting from 1, so the first input frame is 16376considered odd. 16377 16378The filter accepts the following options: 16379 16380@table @option 16381 16382@item mode 16383Specify the mode of the interlacing. This option can also be specified 16384as a value alone. See below for a list of values for this option. 16385 16386Available values are: 16387 16388@table @samp 16389@item merge, 0 16390Move odd frames into the upper field, even into the lower field, 16391generating a double height frame at half frame rate. 16392@example 16393 ------> time 16394Input: 16395Frame 1 Frame 2 Frame 3 Frame 4 16396 1639711111 22222 33333 44444 1639811111 22222 33333 44444 1639911111 22222 33333 44444 1640011111 22222 33333 44444 16401 16402Output: 1640311111 33333 1640422222 44444 1640511111 33333 1640622222 44444 1640711111 33333 1640822222 44444 1640911111 33333 1641022222 44444 16411@end example 16412 16413@item drop_even, 1 16414Only output odd frames, even frames are dropped, generating a frame with 16415unchanged height at half frame rate. 16416 16417@example 16418 ------> time 16419Input: 16420Frame 1 Frame 2 Frame 3 Frame 4 16421 1642211111 22222 33333 44444 1642311111 22222 33333 44444 1642411111 22222 33333 44444 1642511111 22222 33333 44444 16426 16427Output: 1642811111 33333 1642911111 33333 1643011111 33333 1643111111 33333 16432@end example 16433 16434@item drop_odd, 2 16435Only output even frames, odd frames are dropped, generating a frame with 16436unchanged height at half frame rate. 16437 16438@example 16439 ------> time 16440Input: 16441Frame 1 Frame 2 Frame 3 Frame 4 16442 1644311111 22222 33333 44444 1644411111 22222 33333 44444 1644511111 22222 33333 44444 1644611111 22222 33333 44444 16447 16448Output: 16449 22222 44444 16450 22222 44444 16451 22222 44444 16452 22222 44444 16453@end example 16454 16455@item pad, 3 16456Expand each frame to full height, but pad alternate lines with black, 16457generating a frame with double height at the same input frame rate. 16458 16459@example 16460 ------> time 16461Input: 16462Frame 1 Frame 2 Frame 3 Frame 4 16463 1646411111 22222 33333 44444 1646511111 22222 33333 44444 1646611111 22222 33333 44444 1646711111 22222 33333 44444 16468 16469Output: 1647011111 ..... 33333 ..... 16471..... 22222 ..... 44444 1647211111 ..... 33333 ..... 16473..... 22222 ..... 44444 1647411111 ..... 33333 ..... 16475..... 22222 ..... 44444 1647611111 ..... 33333 ..... 16477..... 22222 ..... 44444 16478@end example 16479 16480 16481@item interleave_top, 4 16482Interleave the upper field from odd frames with the lower field from 16483even frames, generating a frame with unchanged height at half frame rate. 16484 16485@example 16486 ------> time 16487Input: 16488Frame 1 Frame 2 Frame 3 Frame 4 16489 1649011111<- 22222 33333<- 44444 1649111111 22222<- 33333 44444<- 1649211111<- 22222 33333<- 44444 1649311111 22222<- 33333 44444<- 16494 16495Output: 1649611111 33333 1649722222 44444 1649811111 33333 1649922222 44444 16500@end example 16501 16502 16503@item interleave_bottom, 5 16504Interleave the lower field from odd frames with the upper field from 16505even frames, generating a frame with unchanged height at half frame rate. 16506 16507@example 16508 ------> time 16509Input: 16510Frame 1 Frame 2 Frame 3 Frame 4 16511 1651211111 22222<- 33333 44444<- 1651311111<- 22222 33333<- 44444 1651411111 22222<- 33333 44444<- 1651511111<- 22222 33333<- 44444 16516 16517Output: 1651822222 44444 1651911111 33333 1652022222 44444 1652111111 33333 16522@end example 16523 16524 16525@item interlacex2, 6 16526Double frame rate with unchanged height. Frames are inserted each 16527containing the second temporal field from the previous input frame and 16528the first temporal field from the next input frame. This mode relies on 16529the top_field_first flag. Useful for interlaced video displays with no 16530field synchronisation. 16531 16532@example 16533 ------> time 16534Input: 16535Frame 1 Frame 2 Frame 3 Frame 4 16536 1653711111 22222 33333 44444 16538 11111 22222 33333 44444 1653911111 22222 33333 44444 16540 11111 22222 33333 44444 16541 16542Output: 1654311111 22222 22222 33333 33333 44444 44444 16544 11111 11111 22222 22222 33333 33333 44444 1654511111 22222 22222 33333 33333 44444 44444 16546 11111 11111 22222 22222 33333 33333 44444 16547@end example 16548 16549 16550@item mergex2, 7 16551Move odd frames into the upper field, even into the lower field, 16552generating a double height frame at same frame rate. 16553 16554@example 16555 ------> time 16556Input: 16557Frame 1 Frame 2 Frame 3 Frame 4 16558 1655911111 22222 33333 44444 1656011111 22222 33333 44444 1656111111 22222 33333 44444 1656211111 22222 33333 44444 16563 16564Output: 1656511111 33333 33333 55555 1656622222 22222 44444 44444 1656711111 33333 33333 55555 1656822222 22222 44444 44444 1656911111 33333 33333 55555 1657022222 22222 44444 44444 1657111111 33333 33333 55555 1657222222 22222 44444 44444 16573@end example 16574 16575@end table 16576 16577Numeric values are deprecated but are accepted for backward 16578compatibility reasons. 16579 16580Default mode is @code{merge}. 16581 16582@item flags 16583Specify flags influencing the filter process. 16584 16585Available value for @var{flags} is: 16586 16587@table @option 16588@item low_pass_filter, vlfp 16589Enable linear vertical low-pass filtering in the filter. 16590Vertical low-pass filtering is required when creating an interlaced 16591destination from a progressive source which contains high-frequency 16592vertical detail. Filtering will reduce interlace 'twitter' and Moire 16593patterning. 16594 16595@item complex_filter, cvlfp 16596Enable complex vertical low-pass filtering. 16597This will slightly less reduce interlace 'twitter' and Moire 16598patterning but better retain detail and subjective sharpness impression. 16599 16600@end table 16601 16602Vertical low-pass filtering can only be enabled for @option{mode} 16603@var{interleave_top} and @var{interleave_bottom}. 16604 16605@end table 16606 16607@section tmix 16608 16609Mix successive video frames. 16610 16611A description of the accepted options follows. 16612 16613@table @option 16614@item frames 16615The number of successive frames to mix. If unspecified, it defaults to 3. 16616 16617@item weights 16618Specify weight of each input video frame. 16619Each weight is separated by space. If number of weights is smaller than 16620number of @var{frames} last specified weight will be used for all remaining 16621unset weights. 16622 16623@item scale 16624Specify scale, if it is set it will be multiplied with sum 16625of each weight multiplied with pixel values to give final destination 16626pixel value. By default @var{scale} is auto scaled to sum of weights. 16627@end table 16628 16629@subsection Examples 16630 16631@itemize 16632@item 16633Average 7 successive frames: 16634@example 16635tmix=frames=7:weights="1 1 1 1 1 1 1" 16636@end example 16637 16638@item 16639Apply simple temporal convolution: 16640@example 16641tmix=frames=3:weights="-1 3 -1" 16642@end example 16643 16644@item 16645Similar as above but only showing temporal differences: 16646@example 16647tmix=frames=3:weights="-1 2 -1":scale=1 16648@end example 16649@end itemize 16650 16651@section tonemap 16652Tone map colors from different dynamic ranges. 16653 16654This filter expects data in single precision floating point, as it needs to 16655operate on (and can output) out-of-range values. Another filter, such as 16656@ref{zscale}, is needed to convert the resulting frame to a usable format. 16657 16658The tonemapping algorithms implemented only work on linear light, so input 16659data should be linearized beforehand (and possibly correctly tagged). 16660 16661@example 16662ffmpeg -i INPUT -vf zscale=transfer=linear,tonemap=clip,zscale=transfer=bt709,format=yuv420p OUTPUT 16663@end example 16664 16665@subsection Options 16666The filter accepts the following options. 16667 16668@table @option 16669@item tonemap 16670Set the tone map algorithm to use. 16671 16672Possible values are: 16673@table @var 16674@item none 16675Do not apply any tone map, only desaturate overbright pixels. 16676 16677@item clip 16678Hard-clip any out-of-range values. Use it for perfect color accuracy for 16679in-range values, while distorting out-of-range values. 16680 16681@item linear 16682Stretch the entire reference gamut to a linear multiple of the display. 16683 16684@item gamma 16685Fit a logarithmic transfer between the tone curves. 16686 16687@item reinhard 16688Preserve overall image brightness with a simple curve, using nonlinear 16689contrast, which results in flattening details and degrading color accuracy. 16690 16691@item hable 16692Preserve both dark and bright details better than @var{reinhard}, at the cost 16693of slightly darkening everything. Use it when detail preservation is more 16694important than color and brightness accuracy. 16695 16696@item mobius 16697Smoothly map out-of-range values, while retaining contrast and colors for 16698in-range material as much as possible. Use it when color accuracy is more 16699important than detail preservation. 16700@end table 16701 16702Default is none. 16703 16704@item param 16705Tune the tone mapping algorithm. 16706 16707This affects the following algorithms: 16708@table @var 16709@item none 16710Ignored. 16711 16712@item linear 16713Specifies the scale factor to use while stretching. 16714Default to 1.0. 16715 16716@item gamma 16717Specifies the exponent of the function. 16718Default to 1.8. 16719 16720@item clip 16721Specify an extra linear coefficient to multiply into the signal before clipping. 16722Default to 1.0. 16723 16724@item reinhard 16725Specify the local contrast coefficient at the display peak. 16726Default to 0.5, which means that in-gamut values will be about half as bright 16727as when clipping. 16728 16729@item hable 16730Ignored. 16731 16732@item mobius 16733Specify the transition point from linear to mobius transform. Every value 16734below this point is guaranteed to be mapped 1:1. The higher the value, the 16735more accurate the result will be, at the cost of losing bright details. 16736Default to 0.3, which due to the steep initial slope still preserves in-range 16737colors fairly accurately. 16738@end table 16739 16740@item desat 16741Apply desaturation for highlights that exceed this level of brightness. The 16742higher the parameter, the more color information will be preserved. This 16743setting helps prevent unnaturally blown-out colors for super-highlights, by 16744(smoothly) turning into white instead. This makes images feel more natural, 16745at the cost of reducing information about out-of-range colors. 16746 16747The default of 2.0 is somewhat conservative and will mostly just apply to 16748skies or directly sunlit surfaces. A setting of 0.0 disables this option. 16749 16750This option works only if the input frame has a supported color tag. 16751 16752@item peak 16753Override signal/nominal/reference peak with this value. Useful when the 16754embedded peak information in display metadata is not reliable or when tone 16755mapping from a lower range to a higher range. 16756@end table 16757 16758@anchor{transpose} 16759@section transpose 16760 16761Transpose rows with columns in the input video and optionally flip it. 16762 16763It accepts the following parameters: 16764 16765@table @option 16766 16767@item dir 16768Specify the transposition direction. 16769 16770Can assume the following values: 16771@table @samp 16772@item 0, 4, cclock_flip 16773Rotate by 90 degrees counterclockwise and vertically flip (default), that is: 16774@example 16775L.R L.l 16776. . -> . . 16777l.r R.r 16778@end example 16779 16780@item 1, 5, clock 16781Rotate by 90 degrees clockwise, that is: 16782@example 16783L.R l.L 16784. . -> . . 16785l.r r.R 16786@end example 16787 16788@item 2, 6, cclock 16789Rotate by 90 degrees counterclockwise, that is: 16790@example 16791L.R R.r 16792. . -> . . 16793l.r L.l 16794@end example 16795 16796@item 3, 7, clock_flip 16797Rotate by 90 degrees clockwise and vertically flip, that is: 16798@example 16799L.R r.R 16800. . -> . . 16801l.r l.L 16802@end example 16803@end table 16804 16805For values between 4-7, the transposition is only done if the input 16806video geometry is portrait and not landscape. These values are 16807deprecated, the @code{passthrough} option should be used instead. 16808 16809Numerical values are deprecated, and should be dropped in favor of 16810symbolic constants. 16811 16812@item passthrough 16813Do not apply the transposition if the input geometry matches the one 16814specified by the specified value. It accepts the following values: 16815@table @samp 16816@item none 16817Always apply transposition. 16818@item portrait 16819Preserve portrait geometry (when @var{height} >= @var{width}). 16820@item landscape 16821Preserve landscape geometry (when @var{width} >= @var{height}). 16822@end table 16823 16824Default value is @code{none}. 16825@end table 16826 16827For example to rotate by 90 degrees clockwise and preserve portrait 16828layout: 16829@example 16830transpose=dir=1:passthrough=portrait 16831@end example 16832 16833The command above can also be specified as: 16834@example 16835transpose=1:portrait 16836@end example 16837 16838@section transpose_npp 16839 16840Transpose rows with columns in the input video and optionally flip it. 16841For more in depth examples see the @ref{transpose} video filter, which shares mostly the same options. 16842 16843It accepts the following parameters: 16844 16845@table @option 16846 16847@item dir 16848Specify the transposition direction. 16849 16850Can assume the following values: 16851@table @samp 16852@item cclock_flip 16853Rotate by 90 degrees counterclockwise and vertically flip. (default) 16854 16855@item clock 16856Rotate by 90 degrees clockwise. 16857 16858@item cclock 16859Rotate by 90 degrees counterclockwise. 16860 16861@item clock_flip 16862Rotate by 90 degrees clockwise and vertically flip. 16863@end table 16864 16865@item passthrough 16866Do not apply the transposition if the input geometry matches the one 16867specified by the specified value. It accepts the following values: 16868@table @samp 16869@item none 16870Always apply transposition. (default) 16871@item portrait 16872Preserve portrait geometry (when @var{height} >= @var{width}). 16873@item landscape 16874Preserve landscape geometry (when @var{width} >= @var{height}). 16875@end table 16876 16877@end table 16878 16879@section trim 16880Trim the input so that the output contains one continuous subpart of the input. 16881 16882It accepts the following parameters: 16883@table @option 16884@item start 16885Specify the time of the start of the kept section, i.e. the frame with the 16886timestamp @var{start} will be the first frame in the output. 16887 16888@item end 16889Specify the time of the first frame that will be dropped, i.e. the frame 16890immediately preceding the one with the timestamp @var{end} will be the last 16891frame in the output. 16892 16893@item start_pts 16894This is the same as @var{start}, except this option sets the start timestamp 16895in timebase units instead of seconds. 16896 16897@item end_pts 16898This is the same as @var{end}, except this option sets the end timestamp 16899in timebase units instead of seconds. 16900 16901@item duration 16902The maximum duration of the output in seconds. 16903 16904@item start_frame 16905The number of the first frame that should be passed to the output. 16906 16907@item end_frame 16908The number of the first frame that should be dropped. 16909@end table 16910 16911@option{start}, @option{end}, and @option{duration} are expressed as time 16912duration specifications; see 16913@ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils} 16914for the accepted syntax. 16915 16916Note that the first two sets of the start/end options and the @option{duration} 16917option look at the frame timestamp, while the _frame variants simply count the 16918frames that pass through the filter. Also note that this filter does not modify 16919the timestamps. If you wish for the output timestamps to start at zero, insert a 16920setpts filter after the trim filter. 16921 16922If multiple start or end options are set, this filter tries to be greedy and 16923keep all the frames that match at least one of the specified constraints. To keep 16924only the part that matches all the constraints at once, chain multiple trim 16925filters. 16926 16927The defaults are such that all the input is kept. So it is possible to set e.g. 16928just the end values to keep everything before the specified time. 16929 16930Examples: 16931@itemize 16932@item 16933Drop everything except the second minute of input: 16934@example 16935ffmpeg -i INPUT -vf trim=60:120 16936@end example 16937 16938@item 16939Keep only the first second: 16940@example 16941ffmpeg -i INPUT -vf trim=duration=1 16942@end example 16943 16944@end itemize 16945 16946@section unpremultiply 16947Apply alpha unpremultiply effect to input video stream using first plane 16948of second stream as alpha. 16949 16950Both streams must have same dimensions and same pixel format. 16951 16952The filter accepts the following option: 16953 16954@table @option 16955@item planes 16956Set which planes will be processed, unprocessed planes will be copied. 16957By default value 0xf, all planes will be processed. 16958 16959If the format has 1 or 2 components, then luma is bit 0. 16960If the format has 3 or 4 components: 16961for RGB formats bit 0 is green, bit 1 is blue and bit 2 is red; 16962for YUV formats bit 0 is luma, bit 1 is chroma-U and bit 2 is chroma-V. 16963If present, the alpha channel is always the last bit. 16964 16965@item inplace 16966Do not require 2nd input for processing, instead use alpha plane from input stream. 16967@end table 16968 16969@anchor{unsharp} 16970@section unsharp 16971 16972Sharpen or blur the input video. 16973 16974It accepts the following parameters: 16975 16976@table @option 16977@item luma_msize_x, lx 16978Set the luma matrix horizontal size. It must be an odd integer between 169793 and 23. The default value is 5. 16980 16981@item luma_msize_y, ly 16982Set the luma matrix vertical size. It must be an odd integer between 3 16983and 23. The default value is 5. 16984 16985@item luma_amount, la 16986Set the luma effect strength. It must be a floating point number, reasonable 16987values lay between -1.5 and 1.5. 16988 16989Negative values will blur the input video, while positive values will 16990sharpen it, a value of zero will disable the effect. 16991 16992Default value is 1.0. 16993 16994@item chroma_msize_x, cx 16995Set the chroma matrix horizontal size. It must be an odd integer 16996between 3 and 23. The default value is 5. 16997 16998@item chroma_msize_y, cy 16999Set the chroma matrix vertical size. It must be an odd integer 17000between 3 and 23. The default value is 5. 17001 17002@item chroma_amount, ca 17003Set the chroma effect strength. It must be a floating point number, reasonable 17004values lay between -1.5 and 1.5. 17005 17006Negative values will blur the input video, while positive values will 17007sharpen it, a value of zero will disable the effect. 17008 17009Default value is 0.0. 17010 17011@end table 17012 17013All parameters are optional and default to the equivalent of the 17014string '5:5:1.0:5:5:0.0'. 17015 17016@subsection Examples 17017 17018@itemize 17019@item 17020Apply strong luma sharpen effect: 17021@example 17022unsharp=luma_msize_x=7:luma_msize_y=7:luma_amount=2.5 17023@end example 17024 17025@item 17026Apply a strong blur of both luma and chroma parameters: 17027@example 17028unsharp=7:7:-2:7:7:-2 17029@end example 17030@end itemize 17031 17032@section uspp 17033 17034Apply ultra slow/simple postprocessing filter that compresses and decompresses 17035the image at several (or - in the case of @option{quality} level @code{8} - all) 17036shifts and average the results. 17037 17038The way this differs from the behavior of spp is that uspp actually encodes & 17039decodes each case with libavcodec Snow, whereas spp uses a simplified intra only 8x8 17040DCT similar to MJPEG. 17041 17042The filter accepts the following options: 17043 17044@table @option 17045@item quality 17046Set quality. This option defines the number of levels for averaging. It accepts 17047an integer in the range 0-8. If set to @code{0}, the filter will have no 17048effect. A value of @code{8} means the higher quality. For each increment of 17049that value the speed drops by a factor of approximately 2. Default value is 17050@code{3}. 17051 17052@item qp 17053Force a constant quantization parameter. If not set, the filter will use the QP 17054from the video stream (if available). 17055@end table 17056 17057@section vaguedenoiser 17058 17059Apply a wavelet based denoiser. 17060 17061It transforms each frame from the video input into the wavelet domain, 17062using Cohen-Daubechies-Feauveau 9/7. Then it applies some filtering to 17063the obtained coefficients. It does an inverse wavelet transform after. 17064Due to wavelet properties, it should give a nice smoothed result, and 17065reduced noise, without blurring picture features. 17066 17067This filter accepts the following options: 17068 17069@table @option 17070@item threshold 17071The filtering strength. The higher, the more filtered the video will be. 17072Hard thresholding can use a higher threshold than soft thresholding 17073before the video looks overfiltered. Default value is 2. 17074 17075@item method 17076The filtering method the filter will use. 17077 17078It accepts the following values: 17079@table @samp 17080@item hard 17081All values under the threshold will be zeroed. 17082 17083@item soft 17084All values under the threshold will be zeroed. All values above will be 17085reduced by the threshold. 17086 17087@item garrote 17088Scales or nullifies coefficients - intermediary between (more) soft and 17089(less) hard thresholding. 17090@end table 17091 17092Default is garrote. 17093 17094@item nsteps 17095Number of times, the wavelet will decompose the picture. Picture can't 17096be decomposed beyond a particular point (typically, 8 for a 640x480 17097frame - as 2^9 = 512 > 480). Valid values are integers between 1 and 32. Default value is 6. 17098 17099@item percent 17100Partial of full denoising (limited coefficients shrinking), from 0 to 100. Default value is 85. 17101 17102@item planes 17103A list of the planes to process. By default all planes are processed. 17104@end table 17105 17106@section vectorscope 17107 17108Display 2 color component values in the two dimensional graph (which is called 17109a vectorscope). 17110 17111This filter accepts the following options: 17112 17113@table @option 17114@item mode, m 17115Set vectorscope mode. 17116 17117It accepts the following values: 17118@table @samp 17119@item gray 17120Gray values are displayed on graph, higher brightness means more pixels have 17121same component color value on location in graph. This is the default mode. 17122 17123@item color 17124Gray values are displayed on graph. Surrounding pixels values which are not 17125present in video frame are drawn in gradient of 2 color components which are 17126set by option @code{x} and @code{y}. The 3rd color component is static. 17127 17128@item color2 17129Actual color components values present in video frame are displayed on graph. 17130 17131@item color3 17132Similar as color2 but higher frequency of same values @code{x} and @code{y} 17133on graph increases value of another color component, which is luminance by 17134default values of @code{x} and @code{y}. 17135 17136@item color4 17137Actual colors present in video frame are displayed on graph. If two different 17138colors map to same position on graph then color with higher value of component 17139not present in graph is picked. 17140 17141@item color5 17142Gray values are displayed on graph. Similar to @code{color} but with 3rd color 17143component picked from radial gradient. 17144@end table 17145 17146@item x 17147Set which color component will be represented on X-axis. Default is @code{1}. 17148 17149@item y 17150Set which color component will be represented on Y-axis. Default is @code{2}. 17151 17152@item intensity, i 17153Set intensity, used by modes: gray, color, color3 and color5 for increasing brightness 17154of color component which represents frequency of (X, Y) location in graph. 17155 17156@item envelope, e 17157@table @samp 17158@item none 17159No envelope, this is default. 17160 17161@item instant 17162Instant envelope, even darkest single pixel will be clearly highlighted. 17163 17164@item peak 17165Hold maximum and minimum values presented in graph over time. This way you 17166can still spot out of range values without constantly looking at vectorscope. 17167 17168@item peak+instant 17169Peak and instant envelope combined together. 17170@end table 17171 17172@item graticule, g 17173Set what kind of graticule to draw. 17174@table @samp 17175@item none 17176@item green 17177@item color 17178@end table 17179 17180@item opacity, o 17181Set graticule opacity. 17182 17183@item flags, f 17184Set graticule flags. 17185 17186@table @samp 17187@item white 17188Draw graticule for white point. 17189 17190@item black 17191Draw graticule for black point. 17192 17193@item name 17194Draw color points short names. 17195@end table 17196 17197@item bgopacity, b 17198Set background opacity. 17199 17200@item lthreshold, l 17201Set low threshold for color component not represented on X or Y axis. 17202Values lower than this value will be ignored. Default is 0. 17203Note this value is multiplied with actual max possible value one pixel component 17204can have. So for 8-bit input and low threshold value of 0.1 actual threshold 17205is 0.1 * 255 = 25. 17206 17207@item hthreshold, h 17208Set high threshold for color component not represented on X or Y axis. 17209Values higher than this value will be ignored. Default is 1. 17210Note this value is multiplied with actual max possible value one pixel component 17211can have. So for 8-bit input and high threshold value of 0.9 actual threshold 17212is 0.9 * 255 = 230. 17213 17214@item colorspace, c 17215Set what kind of colorspace to use when drawing graticule. 17216@table @samp 17217@item auto 17218@item 601 17219@item 709 17220@end table 17221Default is auto. 17222@end table 17223 17224@anchor{vidstabdetect} 17225@section vidstabdetect 17226 17227Analyze video stabilization/deshaking. Perform pass 1 of 2, see 17228@ref{vidstabtransform} for pass 2. 17229 17230This filter generates a file with relative translation and rotation 17231transform information about subsequent frames, which is then used by 17232the @ref{vidstabtransform} filter. 17233 17234To enable compilation of this filter you need to configure FFmpeg with 17235@code{--enable-libvidstab}. 17236 17237This filter accepts the following options: 17238 17239@table @option 17240@item result 17241Set the path to the file used to write the transforms information. 17242Default value is @file{transforms.trf}. 17243 17244@item shakiness 17245Set how shaky the video is and how quick the camera is. It accepts an 17246integer in the range 1-10, a value of 1 means little shakiness, a 17247value of 10 means strong shakiness. Default value is 5. 17248 17249@item accuracy 17250Set the accuracy of the detection process. It must be a value in the 17251range 1-15. A value of 1 means low accuracy, a value of 15 means high 17252accuracy. Default value is 15. 17253 17254@item stepsize 17255Set stepsize of the search process. The region around minimum is 17256scanned with 1 pixel resolution. Default value is 6. 17257 17258@item mincontrast 17259Set minimum contrast. Below this value a local measurement field is 17260discarded. Must be a floating point value in the range 0-1. Default 17261value is 0.3. 17262 17263@item tripod 17264Set reference frame number for tripod mode. 17265 17266If enabled, the motion of the frames is compared to a reference frame 17267in the filtered stream, identified by the specified number. The idea 17268is to compensate all movements in a more-or-less static scene and keep 17269the camera view absolutely still. 17270 17271If set to 0, it is disabled. The frames are counted starting from 1. 17272 17273@item show 17274Show fields and transforms in the resulting frames. It accepts an 17275integer in the range 0-2. Default value is 0, which disables any 17276visualization. 17277@end table 17278 17279@subsection Examples 17280 17281@itemize 17282@item 17283Use default values: 17284@example 17285vidstabdetect 17286@end example 17287 17288@item 17289Analyze strongly shaky movie and put the results in file 17290@file{mytransforms.trf}: 17291@example 17292vidstabdetect=shakiness=10:accuracy=15:result="mytransforms.trf" 17293@end example 17294 17295@item 17296Visualize the result of internal transformations in the resulting 17297video: 17298@example 17299vidstabdetect=show=1 17300@end example 17301 17302@item 17303Analyze a video with medium shakiness using @command{ffmpeg}: 17304@example 17305ffmpeg -i input -vf vidstabdetect=shakiness=5:show=1 dummy.avi 17306@end example 17307@end itemize 17308 17309@anchor{vidstabtransform} 17310@section vidstabtransform 17311 17312Video stabilization/deshaking: pass 2 of 2, 17313see @ref{vidstabdetect} for pass 1. 17314 17315Read a file with transform information for each frame and 17316apply/compensate them. Together with the @ref{vidstabdetect} 17317filter this can be used to deshake videos. See also 17318@url{http://public.hronopik.de/vid.stab}. It is important to also use 17319the @ref{unsharp} filter, see below. 17320 17321To enable compilation of this filter you need to configure FFmpeg with 17322@code{--enable-libvidstab}. 17323 17324@subsection Options 17325 17326@table @option 17327@item input 17328Set path to the file used to read the transforms. Default value is 17329@file{transforms.trf}. 17330 17331@item smoothing 17332Set the number of frames (value*2 + 1) used for lowpass filtering the 17333camera movements. Default value is 10. 17334 17335For example a number of 10 means that 21 frames are used (10 in the 17336past and 10 in the future) to smoothen the motion in the video. A 17337larger value leads to a smoother video, but limits the acceleration of 17338the camera (pan/tilt movements). 0 is a special case where a static 17339camera is simulated. 17340 17341@item optalgo 17342Set the camera path optimization algorithm. 17343 17344Accepted values are: 17345@table @samp 17346@item gauss 17347gaussian kernel low-pass filter on camera motion (default) 17348@item avg 17349averaging on transformations 17350@end table 17351 17352@item maxshift 17353Set maximal number of pixels to translate frames. Default value is -1, 17354meaning no limit. 17355 17356@item maxangle 17357Set maximal angle in radians (degree*PI/180) to rotate frames. Default 17358value is -1, meaning no limit. 17359 17360@item crop 17361Specify how to deal with borders that may be visible due to movement 17362compensation. 17363 17364Available values are: 17365@table @samp 17366@item keep 17367keep image information from previous frame (default) 17368@item black 17369fill the border black 17370@end table 17371 17372@item invert 17373Invert transforms if set to 1. Default value is 0. 17374 17375@item relative 17376Consider transforms as relative to previous frame if set to 1, 17377absolute if set to 0. Default value is 0. 17378 17379@item zoom 17380Set percentage to zoom. A positive value will result in a zoom-in 17381effect, a negative value in a zoom-out effect. Default value is 0 (no 17382zoom). 17383 17384@item optzoom 17385Set optimal zooming to avoid borders. 17386 17387Accepted values are: 17388@table @samp 17389@item 0 17390disabled 17391@item 1 17392optimal static zoom value is determined (only very strong movements 17393will lead to visible borders) (default) 17394@item 2 17395optimal adaptive zoom value is determined (no borders will be 17396visible), see @option{zoomspeed} 17397@end table 17398 17399Note that the value given at zoom is added to the one calculated here. 17400 17401@item zoomspeed 17402Set percent to zoom maximally each frame (enabled when 17403@option{optzoom} is set to 2). Range is from 0 to 5, default value is 174040.25. 17405 17406@item interpol 17407Specify type of interpolation. 17408 17409Available values are: 17410@table @samp 17411@item no 17412no interpolation 17413@item linear 17414linear only horizontal 17415@item bilinear 17416linear in both directions (default) 17417@item bicubic 17418cubic in both directions (slow) 17419@end table 17420 17421@item tripod 17422Enable virtual tripod mode if set to 1, which is equivalent to 17423@code{relative=0:smoothing=0}. Default value is 0. 17424 17425Use also @code{tripod} option of @ref{vidstabdetect}. 17426 17427@item debug 17428Increase log verbosity if set to 1. Also the detected global motions 17429are written to the temporary file @file{global_motions.trf}. Default 17430value is 0. 17431@end table 17432 17433@subsection Examples 17434 17435@itemize 17436@item 17437Use @command{ffmpeg} for a typical stabilization with default values: 17438@example 17439ffmpeg -i inp.mpeg -vf vidstabtransform,unsharp=5:5:0.8:3:3:0.4 inp_stabilized.mpeg 17440@end example 17441 17442Note the use of the @ref{unsharp} filter which is always recommended. 17443 17444@item 17445Zoom in a bit more and load transform data from a given file: 17446@example 17447vidstabtransform=zoom=5:input="mytransforms.trf" 17448@end example 17449 17450@item 17451Smoothen the video even more: 17452@example 17453vidstabtransform=smoothing=30 17454@end example 17455@end itemize 17456 17457@section vflip 17458 17459Flip the input video vertically. 17460 17461For example, to vertically flip a video with @command{ffmpeg}: 17462@example 17463ffmpeg -i in.avi -vf "vflip" out.avi 17464@end example 17465 17466@section vfrdet 17467 17468Detect variable frame rate video. 17469 17470This filter tries to detect if the input is variable or constant frame rate. 17471 17472At end it will output number of frames detected as having variable delta pts, 17473and ones with constant delta pts. 17474If there was frames with variable delta, than it will also show min and max delta 17475encountered. 17476 17477@section vibrance 17478 17479Boost or alter saturation. 17480 17481The filter accepts the following options: 17482@table @option 17483@item intensity 17484Set strength of boost if positive value or strength of alter if negative value. 17485Default is 0. Allowed range is from -2 to 2. 17486 17487@item rbal 17488Set the red balance. Default is 1. Allowed range is from -10 to 10. 17489 17490@item gbal 17491Set the green balance. Default is 1. Allowed range is from -10 to 10. 17492 17493@item bbal 17494Set the blue balance. Default is 1. Allowed range is from -10 to 10. 17495 17496@item rlum 17497Set the red luma coefficient. 17498 17499@item glum 17500Set the green luma coefficient. 17501 17502@item blum 17503Set the blue luma coefficient. 17504@end table 17505 17506@anchor{vignette} 17507@section vignette 17508 17509Make or reverse a natural vignetting effect. 17510 17511The filter accepts the following options: 17512 17513@table @option 17514@item angle, a 17515Set lens angle expression as a number of radians. 17516 17517The value is clipped in the @code{[0,PI/2]} range. 17518 17519Default value: @code{"PI/5"} 17520 17521@item x0 17522@item y0 17523Set center coordinates expressions. Respectively @code{"w/2"} and @code{"h/2"} 17524by default. 17525 17526@item mode 17527Set forward/backward mode. 17528 17529Available modes are: 17530@table @samp 17531@item forward 17532The larger the distance from the central point, the darker the image becomes. 17533 17534@item backward 17535The larger the distance from the central point, the brighter the image becomes. 17536This can be used to reverse a vignette effect, though there is no automatic 17537detection to extract the lens @option{angle} and other settings (yet). It can 17538also be used to create a burning effect. 17539@end table 17540 17541Default value is @samp{forward}. 17542 17543@item eval 17544Set evaluation mode for the expressions (@option{angle}, @option{x0}, @option{y0}). 17545 17546It accepts the following values: 17547@table @samp 17548@item init 17549Evaluate expressions only once during the filter initialization. 17550 17551@item frame 17552Evaluate expressions for each incoming frame. This is way slower than the 17553@samp{init} mode since it requires all the scalers to be re-computed, but it 17554allows advanced dynamic expressions. 17555@end table 17556 17557Default value is @samp{init}. 17558 17559@item dither 17560Set dithering to reduce the circular banding effects. Default is @code{1} 17561(enabled). 17562 17563@item aspect 17564Set vignette aspect. This setting allows one to adjust the shape of the vignette. 17565Setting this value to the SAR of the input will make a rectangular vignetting 17566following the dimensions of the video. 17567 17568Default is @code{1/1}. 17569@end table 17570 17571@subsection Expressions 17572 17573The @option{alpha}, @option{x0} and @option{y0} expressions can contain the 17574following parameters. 17575 17576@table @option 17577@item w 17578@item h 17579input width and height 17580 17581@item n 17582the number of input frame, starting from 0 17583 17584@item pts 17585the PTS (Presentation TimeStamp) time of the filtered video frame, expressed in 17586@var{TB} units, NAN if undefined 17587 17588@item r 17589frame rate of the input video, NAN if the input frame rate is unknown 17590 17591@item t 17592the PTS (Presentation TimeStamp) of the filtered video frame, 17593expressed in seconds, NAN if undefined 17594 17595@item tb 17596time base of the input video 17597@end table 17598 17599 17600@subsection Examples 17601 17602@itemize 17603@item 17604Apply simple strong vignetting effect: 17605@example 17606vignette=PI/4 17607@end example 17608 17609@item 17610Make a flickering vignetting: 17611@example 17612vignette='PI/4+random(1)*PI/50':eval=frame 17613@end example 17614 17615@end itemize 17616 17617@section vmafmotion 17618 17619Obtain the average vmaf motion score of a video. 17620It is one of the component filters of VMAF. 17621 17622The obtained average motion score is printed through the logging system. 17623 17624In the below example the input file @file{ref.mpg} is being processed and score 17625is computed. 17626 17627@example 17628ffmpeg -i ref.mpg -lavfi vmafmotion -f null - 17629@end example 17630 17631@section vstack 17632Stack input videos vertically. 17633 17634All streams must be of same pixel format and of same width. 17635 17636Note that this filter is faster than using @ref{overlay} and @ref{pad} filter 17637to create same output. 17638 17639The filter accept the following option: 17640 17641@table @option 17642@item inputs 17643Set number of input streams. Default is 2. 17644 17645@item shortest 17646If set to 1, force the output to terminate when the shortest input 17647terminates. Default value is 0. 17648@end table 17649 17650@section w3fdif 17651 17652Deinterlace the input video ("w3fdif" stands for "Weston 3 Field 17653Deinterlacing Filter"). 17654 17655Based on the process described by Martin Weston for BBC R&D, and 17656implemented based on the de-interlace algorithm written by Jim 17657Easterbrook for BBC R&D, the Weston 3 field deinterlacing filter 17658uses filter coefficients calculated by BBC R&D. 17659 17660There are two sets of filter coefficients, so called "simple": 17661and "complex". Which set of filter coefficients is used can 17662be set by passing an optional parameter: 17663 17664@table @option 17665@item filter 17666Set the interlacing filter coefficients. Accepts one of the following values: 17667 17668@table @samp 17669@item simple 17670Simple filter coefficient set. 17671@item complex 17672More-complex filter coefficient set. 17673@end table 17674Default value is @samp{complex}. 17675 17676@item deint 17677Specify which frames to deinterlace. Accept one of the following values: 17678 17679@table @samp 17680@item all 17681Deinterlace all frames, 17682@item interlaced 17683Only deinterlace frames marked as interlaced. 17684@end table 17685 17686Default value is @samp{all}. 17687@end table 17688 17689@section waveform 17690Video waveform monitor. 17691 17692The waveform monitor plots color component intensity. By default luminance 17693only. Each column of the waveform corresponds to a column of pixels in the 17694source video. 17695 17696It accepts the following options: 17697 17698@table @option 17699@item mode, m 17700Can be either @code{row}, or @code{column}. Default is @code{column}. 17701In row mode, the graph on the left side represents color component value 0 and 17702the right side represents value = 255. In column mode, the top side represents 17703color component value = 0 and bottom side represents value = 255. 17704 17705@item intensity, i 17706Set intensity. Smaller values are useful to find out how many values of the same 17707luminance are distributed across input rows/columns. 17708Default value is @code{0.04}. Allowed range is [0, 1]. 17709 17710@item mirror, r 17711Set mirroring mode. @code{0} means unmirrored, @code{1} means mirrored. 17712In mirrored mode, higher values will be represented on the left 17713side for @code{row} mode and at the top for @code{column} mode. Default is 17714@code{1} (mirrored). 17715 17716@item display, d 17717Set display mode. 17718It accepts the following values: 17719@table @samp 17720@item overlay 17721Presents information identical to that in the @code{parade}, except 17722that the graphs representing color components are superimposed directly 17723over one another. 17724 17725This display mode makes it easier to spot relative differences or similarities 17726in overlapping areas of the color components that are supposed to be identical, 17727such as neutral whites, grays, or blacks. 17728 17729@item stack 17730Display separate graph for the color components side by side in 17731@code{row} mode or one below the other in @code{column} mode. 17732 17733@item parade 17734Display separate graph for the color components side by side in 17735@code{column} mode or one below the other in @code{row} mode. 17736 17737Using this display mode makes it easy to spot color casts in the highlights 17738and shadows of an image, by comparing the contours of the top and the bottom 17739graphs of each waveform. Since whites, grays, and blacks are characterized 17740by exactly equal amounts of red, green, and blue, neutral areas of the picture 17741should display three waveforms of roughly equal width/height. If not, the 17742correction is easy to perform by making level adjustments the three waveforms. 17743@end table 17744Default is @code{stack}. 17745 17746@item components, c 17747Set which color components to display. Default is 1, which means only luminance 17748or red color component if input is in RGB colorspace. If is set for example to 177497 it will display all 3 (if) available color components. 17750 17751@item envelope, e 17752@table @samp 17753@item none 17754No envelope, this is default. 17755 17756@item instant 17757Instant envelope, minimum and maximum values presented in graph will be easily 17758visible even with small @code{step} value. 17759 17760@item peak 17761Hold minimum and maximum values presented in graph across time. This way you 17762can still spot out of range values without constantly looking at waveforms. 17763 17764@item peak+instant 17765Peak and instant envelope combined together. 17766@end table 17767 17768@item filter, f 17769@table @samp 17770@item lowpass 17771No filtering, this is default. 17772 17773@item flat 17774Luma and chroma combined together. 17775 17776@item aflat 17777Similar as above, but shows difference between blue and red chroma. 17778 17779@item xflat 17780Similar as above, but use different colors. 17781 17782@item chroma 17783Displays only chroma. 17784 17785@item color 17786Displays actual color value on waveform. 17787 17788@item acolor 17789Similar as above, but with luma showing frequency of chroma values. 17790@end table 17791 17792@item graticule, g 17793Set which graticule to display. 17794 17795@table @samp 17796@item none 17797Do not display graticule. 17798 17799@item green 17800Display green graticule showing legal broadcast ranges. 17801 17802@item orange 17803Display orange graticule showing legal broadcast ranges. 17804@end table 17805 17806@item opacity, o 17807Set graticule opacity. 17808 17809@item flags, fl 17810Set graticule flags. 17811 17812@table @samp 17813@item numbers 17814Draw numbers above lines. By default enabled. 17815 17816@item dots 17817Draw dots instead of lines. 17818@end table 17819 17820@item scale, s 17821Set scale used for displaying graticule. 17822 17823@table @samp 17824@item digital 17825@item millivolts 17826@item ire 17827@end table 17828Default is digital. 17829 17830@item bgopacity, b 17831Set background opacity. 17832@end table 17833 17834@section weave, doubleweave 17835 17836The @code{weave} takes a field-based video input and join 17837each two sequential fields into single frame, producing a new double 17838height clip with half the frame rate and half the frame count. 17839 17840The @code{doubleweave} works same as @code{weave} but without 17841halving frame rate and frame count. 17842 17843It accepts the following option: 17844 17845@table @option 17846@item first_field 17847Set first field. Available values are: 17848 17849@table @samp 17850@item top, t 17851Set the frame as top-field-first. 17852 17853@item bottom, b 17854Set the frame as bottom-field-first. 17855@end table 17856@end table 17857 17858@subsection Examples 17859 17860@itemize 17861@item 17862Interlace video using @ref{select} and @ref{separatefields} filter: 17863@example 17864separatefields,select=eq(mod(n,4),0)+eq(mod(n,4),3),weave 17865@end example 17866@end itemize 17867 17868@section xbr 17869Apply the xBR high-quality magnification filter which is designed for pixel 17870art. It follows a set of edge-detection rules, see 17871@url{https://forums.libretro.com/t/xbr-algorithm-tutorial/123}. 17872 17873It accepts the following option: 17874 17875@table @option 17876@item n 17877Set the scaling dimension: @code{2} for @code{2xBR}, @code{3} for 17878@code{3xBR} and @code{4} for @code{4xBR}. 17879Default is @code{3}. 17880@end table 17881 17882@section xstack 17883Stack video inputs into custom layout. 17884 17885All streams must be of same pixel format. 17886 17887The filter accept the following option: 17888 17889@table @option 17890@item inputs 17891Set number of input streams. Default is 2. 17892 17893@item layout 17894Specify layout of inputs. 17895This option requires the desired layout configuration to be explicitly set by the user. 17896This sets position of each video input in output. Each input 17897is separated by '|'. 17898The first number represents the column, and the second number represents the row. 17899Numbers start at 0 and are separated by '_'. Optionally one can use wX and hX, 17900where X is video input from which to take width or height. 17901Multiple values can be used when separated by '+'. In such 17902case values are summed together. 17903 17904@item shortest 17905If set to 1, force the output to terminate when the shortest input 17906terminates. Default value is 0. 17907@end table 17908 17909@subsection Examples 17910 17911@itemize 17912@item 17913Display 4 inputs into 2x2 grid, 17914note that if inputs are of different sizes unused gaps might appear, 17915as not all of output video is used. 17916@example 17917xstack=inputs=4:layout=0_0|0_h0|w0_0|w0_h0 17918@end example 17919 17920@item 17921Display 4 inputs into 1x4 grid, 17922note that if inputs are of different sizes unused gaps might appear, 17923as not all of output video is used. 17924@example 17925xstack=inputs=4:layout=0_0|0_h0|0_h0+h1|0_h0+h1+h2 17926@end example 17927 17928@item 17929Display 9 inputs into 3x3 grid, 17930note that if inputs are of different sizes unused gaps might appear, 17931as not all of output video is used. 17932@example 17933xstack=inputs=9:layout=w3_0|w3_h0+h2|w3_h0|0_h4|0_0|w3+w1_0|0_h1+h2|w3+w1_h0|w3+w1_h1+h2 17934@end example 17935@end itemize 17936 17937@anchor{yadif} 17938@section yadif 17939 17940Deinterlace the input video ("yadif" means "yet another deinterlacing 17941filter"). 17942 17943It accepts the following parameters: 17944 17945 17946@table @option 17947 17948@item mode 17949The interlacing mode to adopt. It accepts one of the following values: 17950 17951@table @option 17952@item 0, send_frame 17953Output one frame for each frame. 17954@item 1, send_field 17955Output one frame for each field. 17956@item 2, send_frame_nospatial 17957Like @code{send_frame}, but it skips the spatial interlacing check. 17958@item 3, send_field_nospatial 17959Like @code{send_field}, but it skips the spatial interlacing check. 17960@end table 17961 17962The default value is @code{send_frame}. 17963 17964@item parity 17965The picture field parity assumed for the input interlaced video. It accepts one 17966of the following values: 17967 17968@table @option 17969@item 0, tff 17970Assume the top field is first. 17971@item 1, bff 17972Assume the bottom field is first. 17973@item -1, auto 17974Enable automatic detection of field parity. 17975@end table 17976 17977The default value is @code{auto}. 17978If the interlacing is unknown or the decoder does not export this information, 17979top field first will be assumed. 17980 17981@item deint 17982Specify which frames to deinterlace. Accept one of the following 17983values: 17984 17985@table @option 17986@item 0, all 17987Deinterlace all frames. 17988@item 1, interlaced 17989Only deinterlace frames marked as interlaced. 17990@end table 17991 17992The default value is @code{all}. 17993@end table 17994 17995@section yadif_cuda 17996 17997Deinterlace the input video using the @ref{yadif} algorithm, but implemented 17998in CUDA so that it can work as part of a GPU accelerated pipeline with nvdec 17999and/or nvenc. 18000 18001It accepts the following parameters: 18002 18003 18004@table @option 18005 18006@item mode 18007The interlacing mode to adopt. It accepts one of the following values: 18008 18009@table @option 18010@item 0, send_frame 18011Output one frame for each frame. 18012@item 1, send_field 18013Output one frame for each field. 18014@item 2, send_frame_nospatial 18015Like @code{send_frame}, but it skips the spatial interlacing check. 18016@item 3, send_field_nospatial 18017Like @code{send_field}, but it skips the spatial interlacing check. 18018@end table 18019 18020The default value is @code{send_frame}. 18021 18022@item parity 18023The picture field parity assumed for the input interlaced video. It accepts one 18024of the following values: 18025 18026@table @option 18027@item 0, tff 18028Assume the top field is first. 18029@item 1, bff 18030Assume the bottom field is first. 18031@item -1, auto 18032Enable automatic detection of field parity. 18033@end table 18034 18035The default value is @code{auto}. 18036If the interlacing is unknown or the decoder does not export this information, 18037top field first will be assumed. 18038 18039@item deint 18040Specify which frames to deinterlace. Accept one of the following 18041values: 18042 18043@table @option 18044@item 0, all 18045Deinterlace all frames. 18046@item 1, interlaced 18047Only deinterlace frames marked as interlaced. 18048@end table 18049 18050The default value is @code{all}. 18051@end table 18052 18053@section zoompan 18054 18055Apply Zoom & Pan effect. 18056 18057This filter accepts the following options: 18058 18059@table @option 18060@item zoom, z 18061Set the zoom expression. Default is 1. 18062 18063@item x 18064@item y 18065Set the x and y expression. Default is 0. 18066 18067@item d 18068Set the duration expression in number of frames. 18069This sets for how many number of frames effect will last for 18070single input image. 18071 18072@item s 18073Set the output image size, default is 'hd720'. 18074 18075@item fps 18076Set the output frame rate, default is '25'. 18077@end table 18078 18079Each expression can contain the following constants: 18080 18081@table @option 18082@item in_w, iw 18083Input width. 18084 18085@item in_h, ih 18086Input height. 18087 18088@item out_w, ow 18089Output width. 18090 18091@item out_h, oh 18092Output height. 18093 18094@item in 18095Input frame count. 18096 18097@item on 18098Output frame count. 18099 18100@item x 18101@item y 18102Last calculated 'x' and 'y' position from 'x' and 'y' expression 18103for current input frame. 18104 18105@item px 18106@item py 18107'x' and 'y' of last output frame of previous input frame or 0 when there was 18108not yet such frame (first input frame). 18109 18110@item zoom 18111Last calculated zoom from 'z' expression for current input frame. 18112 18113@item pzoom 18114Last calculated zoom of last output frame of previous input frame. 18115 18116@item duration 18117Number of output frames for current input frame. Calculated from 'd' expression 18118for each input frame. 18119 18120@item pduration 18121number of output frames created for previous input frame 18122 18123@item a 18124Rational number: input width / input height 18125 18126@item sar 18127sample aspect ratio 18128 18129@item dar 18130display aspect ratio 18131 18132@end table 18133 18134@subsection Examples 18135 18136@itemize 18137@item 18138Zoom-in up to 1.5 and pan at same time to some spot near center of picture: 18139@example 18140zoompan=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 18141@end example 18142 18143@item 18144Zoom-in up to 1.5 and pan always at center of picture: 18145@example 18146zoompan=z='min(zoom+0.0015,1.5)':d=700:x='iw/2-(iw/zoom/2)':y='ih/2-(ih/zoom/2)' 18147@end example 18148 18149@item 18150Same as above but without pausing: 18151@example 18152zoompan=z='min(max(zoom,pzoom)+0.0015,1.5)':d=1:x='iw/2-(iw/zoom/2)':y='ih/2-(ih/zoom/2)' 18153@end example 18154@end itemize 18155 18156@anchor{zscale} 18157@section zscale 18158Scale (resize) the input video, using the z.lib library: 18159@url{https://github.com/sekrit-twc/zimg}. To enable compilation of this 18160filter, you need to configure FFmpeg with @code{--enable-libzimg}. 18161 18162The zscale filter forces the output display aspect ratio to be the same 18163as the input, by changing the output sample aspect ratio. 18164 18165If the input image format is different from the format requested by 18166the next filter, the zscale filter will convert the input to the 18167requested format. 18168 18169@subsection Options 18170The filter accepts the following options. 18171 18172@table @option 18173@item width, w 18174@item height, h 18175Set the output video dimension expression. Default value is the input 18176dimension. 18177 18178If the @var{width} or @var{w} value is 0, the input width is used for 18179the output. If the @var{height} or @var{h} value is 0, the input height 18180is used for the output. 18181 18182If one and only one of the values is -n with n >= 1, the zscale filter 18183will use a value that maintains the aspect ratio of the input image, 18184calculated from the other specified dimension. After that it will, 18185however, make sure that the calculated dimension is divisible by n and 18186adjust the value if necessary. 18187 18188If both values are -n with n >= 1, the behavior will be identical to 18189both values being set to 0 as previously detailed. 18190 18191See below for the list of accepted constants for use in the dimension 18192expression. 18193 18194@item size, s 18195Set the video size. For the syntax of this option, check the 18196@ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}. 18197 18198@item dither, d 18199Set the dither type. 18200 18201Possible values are: 18202@table @var 18203@item none 18204@item ordered 18205@item random 18206@item error_diffusion 18207@end table 18208 18209Default is none. 18210 18211@item filter, f 18212Set the resize filter type. 18213 18214Possible values are: 18215@table @var 18216@item point 18217@item bilinear 18218@item bicubic 18219@item spline16 18220@item spline36 18221@item lanczos 18222@end table 18223 18224Default is bilinear. 18225 18226@item range, r 18227Set the color range. 18228 18229Possible values are: 18230@table @var 18231@item input 18232@item limited 18233@item full 18234@end table 18235 18236Default is same as input. 18237 18238@item primaries, p 18239Set the color primaries. 18240 18241Possible values are: 18242@table @var 18243@item input 18244@item 709 18245@item unspecified 18246@item 170m 18247@item 240m 18248@item 2020 18249@end table 18250 18251Default is same as input. 18252 18253@item transfer, t 18254Set the transfer characteristics. 18255 18256Possible values are: 18257@table @var 18258@item input 18259@item 709 18260@item unspecified 18261@item 601 18262@item linear 18263@item 2020_10 18264@item 2020_12 18265@item smpte2084 18266@item iec61966-2-1 18267@item arib-std-b67 18268@end table 18269 18270Default is same as input. 18271 18272@item matrix, m 18273Set the colorspace matrix. 18274 18275Possible value are: 18276@table @var 18277@item input 18278@item 709 18279@item unspecified 18280@item 470bg 18281@item 170m 18282@item 2020_ncl 18283@item 2020_cl 18284@end table 18285 18286Default is same as input. 18287 18288@item rangein, rin 18289Set the input color range. 18290 18291Possible values are: 18292@table @var 18293@item input 18294@item limited 18295@item full 18296@end table 18297 18298Default is same as input. 18299 18300@item primariesin, pin 18301Set the input color primaries. 18302 18303Possible values are: 18304@table @var 18305@item input 18306@item 709 18307@item unspecified 18308@item 170m 18309@item 240m 18310@item 2020 18311@end table 18312 18313Default is same as input. 18314 18315@item transferin, tin 18316Set the input transfer characteristics. 18317 18318Possible values are: 18319@table @var 18320@item input 18321@item 709 18322@item unspecified 18323@item 601 18324@item linear 18325@item 2020_10 18326@item 2020_12 18327@end table 18328 18329Default is same as input. 18330 18331@item matrixin, min 18332Set the input colorspace matrix. 18333 18334Possible value are: 18335@table @var 18336@item input 18337@item 709 18338@item unspecified 18339@item 470bg 18340@item 170m 18341@item 2020_ncl 18342@item 2020_cl 18343@end table 18344 18345@item chromal, c 18346Set the output chroma location. 18347 18348Possible values are: 18349@table @var 18350@item input 18351@item left 18352@item center 18353@item topleft 18354@item top 18355@item bottomleft 18356@item bottom 18357@end table 18358 18359@item chromalin, cin 18360Set the input chroma location. 18361 18362Possible values are: 18363@table @var 18364@item input 18365@item left 18366@item center 18367@item topleft 18368@item top 18369@item bottomleft 18370@item bottom 18371@end table 18372 18373@item npl 18374Set the nominal peak luminance. 18375@end table 18376 18377The values of the @option{w} and @option{h} options are expressions 18378containing the following constants: 18379 18380@table @var 18381@item in_w 18382@item in_h 18383The input width and height 18384 18385@item iw 18386@item ih 18387These are the same as @var{in_w} and @var{in_h}. 18388 18389@item out_w 18390@item out_h 18391The output (scaled) width and height 18392 18393@item ow 18394@item oh 18395These are the same as @var{out_w} and @var{out_h} 18396 18397@item a 18398The same as @var{iw} / @var{ih} 18399 18400@item sar 18401input sample aspect ratio 18402 18403@item dar 18404The input display aspect ratio. Calculated from @code{(iw / ih) * sar}. 18405 18406@item hsub 18407@item vsub 18408horizontal and vertical input chroma subsample values. For example for the 18409pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1. 18410 18411@item ohsub 18412@item ovsub 18413horizontal and vertical output chroma subsample values. For example for the 18414pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1. 18415@end table 18416 18417@table @option 18418@end table 18419 18420@c man end VIDEO FILTERS 18421 18422@chapter Video Sources 18423@c man begin VIDEO SOURCES 18424 18425Below is a description of the currently available video sources. 18426 18427@section buffer 18428 18429Buffer video frames, and make them available to the filter chain. 18430 18431This source is mainly intended for a programmatic use, in particular 18432through the interface defined in @file{libavfilter/vsrc_buffer.h}. 18433 18434It accepts the following parameters: 18435 18436@table @option 18437 18438@item video_size 18439Specify the size (width and height) of the buffered video frames. For the 18440syntax of this option, check the 18441@ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}. 18442 18443@item width 18444The input video width. 18445 18446@item height 18447The input video height. 18448 18449@item pix_fmt 18450A string representing the pixel format of the buffered video frames. 18451It may be a number corresponding to a pixel format, or a pixel format 18452name. 18453 18454@item time_base 18455Specify the timebase assumed by the timestamps of the buffered frames. 18456 18457@item frame_rate 18458Specify the frame rate expected for the video stream. 18459 18460@item pixel_aspect, sar 18461The sample (pixel) aspect ratio of the input video. 18462 18463@item sws_param 18464Specify the optional parameters to be used for the scale filter which 18465is automatically inserted when an input change is detected in the 18466input size or format. 18467 18468@item hw_frames_ctx 18469When using a hardware pixel format, this should be a reference to an 18470AVHWFramesContext describing input frames. 18471@end table 18472 18473For example: 18474@example 18475buffer=width=320:height=240:pix_fmt=yuv410p:time_base=1/24:sar=1 18476@end example 18477 18478will instruct the source to accept video frames with size 320x240 and 18479with format "yuv410p", assuming 1/24 as the timestamps timebase and 18480square pixels (1:1 sample aspect ratio). 18481Since the pixel format with name "yuv410p" corresponds to the number 6 18482(check the enum AVPixelFormat definition in @file{libavutil/pixfmt.h}), 18483this example corresponds to: 18484@example 18485buffer=size=320x240:pixfmt=6:time_base=1/24:pixel_aspect=1/1 18486@end example 18487 18488Alternatively, the options can be specified as a flat string, but this 18489syntax is deprecated: 18490 18491@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}] 18492 18493@section cellauto 18494 18495Create a pattern generated by an elementary cellular automaton. 18496 18497The initial state of the cellular automaton can be defined through the 18498@option{filename} and @option{pattern} options. If such options are 18499not specified an initial state is created randomly. 18500 18501At each new frame a new row in the video is filled with the result of 18502the cellular automaton next generation. The behavior when the whole 18503frame is filled is defined by the @option{scroll} option. 18504 18505This source accepts the following options: 18506 18507@table @option 18508@item filename, f 18509Read the initial cellular automaton state, i.e. the starting row, from 18510the specified file. 18511In the file, each non-whitespace character is considered an alive 18512cell, a newline will terminate the row, and further characters in the 18513file will be ignored. 18514 18515@item pattern, p 18516Read the initial cellular automaton state, i.e. the starting row, from 18517the specified string. 18518 18519Each non-whitespace character in the string is considered an alive 18520cell, a newline will terminate the row, and further characters in the 18521string will be ignored. 18522 18523@item rate, r 18524Set the video rate, that is the number of frames generated per second. 18525Default is 25. 18526 18527@item random_fill_ratio, ratio 18528Set the random fill ratio for the initial cellular automaton row. It 18529is a floating point number value ranging from 0 to 1, defaults to 185301/PHI. 18531 18532This option is ignored when a file or a pattern is specified. 18533 18534@item random_seed, seed 18535Set the seed for filling randomly the initial row, must be an integer 18536included between 0 and UINT32_MAX. If not specified, or if explicitly 18537set to -1, the filter will try to use a good random seed on a best 18538effort basis. 18539 18540@item rule 18541Set the cellular automaton rule, it is a number ranging from 0 to 255. 18542Default value is 110. 18543 18544@item size, s 18545Set the size of the output video. For the syntax of this option, check the 18546@ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}. 18547 18548If @option{filename} or @option{pattern} is specified, the size is set 18549by default to the width of the specified initial state row, and the 18550height is set to @var{width} * PHI. 18551 18552If @option{size} is set, it must contain the width of the specified 18553pattern string, and the specified pattern will be centered in the 18554larger row. 18555 18556If a filename or a pattern string is not specified, the size value 18557defaults to "320x518" (used for a randomly generated initial state). 18558 18559@item scroll 18560If set to 1, scroll the output upward when all the rows in the output 18561have been already filled. If set to 0, the new generated row will be 18562written over the top row just after the bottom row is filled. 18563Defaults to 1. 18564 18565@item start_full, full 18566If set to 1, completely fill the output with generated rows before 18567outputting the first frame. 18568This is the default behavior, for disabling set the value to 0. 18569 18570@item stitch 18571If set to 1, stitch the left and right row edges together. 18572This is the default behavior, for disabling set the value to 0. 18573@end table 18574 18575@subsection Examples 18576 18577@itemize 18578@item 18579Read the initial state from @file{pattern}, and specify an output of 18580size 200x400. 18581@example 18582cellauto=f=pattern:s=200x400 18583@end example 18584 18585@item 18586Generate a random initial row with a width of 200 cells, with a fill 18587ratio of 2/3: 18588@example 18589cellauto=ratio=2/3:s=200x200 18590@end example 18591 18592@item 18593Create a pattern generated by rule 18 starting by a single alive cell 18594centered on an initial row with width 100: 18595@example 18596cellauto=p=@@:s=100x400:full=0:rule=18 18597@end example 18598 18599@item 18600Specify a more elaborated initial pattern: 18601@example 18602cellauto=p='@@@@ @@ @@@@':s=100x400:full=0:rule=18 18603@end example 18604 18605@end itemize 18606 18607@anchor{coreimagesrc} 18608@section coreimagesrc 18609Video source generated on GPU using Apple's CoreImage API on OSX. 18610 18611This video source is a specialized version of the @ref{coreimage} video filter. 18612Use a core image generator at the beginning of the applied filterchain to 18613generate the content. 18614 18615The coreimagesrc video source accepts the following options: 18616@table @option 18617@item list_generators 18618List all available generators along with all their respective options as well as 18619possible minimum and maximum values along with the default values. 18620@example 18621list_generators=true 18622@end example 18623 18624@item size, s 18625Specify the size of the sourced video. For the syntax of this option, check the 18626@ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}. 18627The default value is @code{320x240}. 18628 18629@item rate, r 18630Specify the frame rate of the sourced video, as the number of frames 18631generated per second. It has to be a string in the format 18632@var{frame_rate_num}/@var{frame_rate_den}, an integer number, a floating point 18633number or a valid video frame rate abbreviation. The default value is 18634"25". 18635 18636@item sar 18637Set the sample aspect ratio of the sourced video. 18638 18639@item duration, d 18640Set the duration of the sourced video. See 18641@ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils} 18642for the accepted syntax. 18643 18644If not specified, or the expressed duration is negative, the video is 18645supposed to be generated forever. 18646@end table 18647 18648Additionally, all options of the @ref{coreimage} video filter are accepted. 18649A complete filterchain can be used for further processing of the 18650generated input without CPU-HOST transfer. See @ref{coreimage} documentation 18651and examples for details. 18652 18653@subsection Examples 18654 18655@itemize 18656 18657@item 18658Use CIQRCodeGenerator to create a QR code for the FFmpeg homepage, 18659given as complete and escaped command-line for Apple's standard bash shell: 18660@example 18661ffmpeg -f lavfi -i coreimagesrc=s=100x100:filter=CIQRCodeGenerator@@inputMessage=https\\\\\://FFmpeg.org/@@inputCorrectionLevel=H -frames:v 1 QRCode.png 18662@end example 18663This example is equivalent to the QRCode example of @ref{coreimage} without the 18664need for a nullsrc video source. 18665@end itemize 18666 18667 18668@section mandelbrot 18669 18670Generate a Mandelbrot set fractal, and progressively zoom towards the 18671point specified with @var{start_x} and @var{start_y}. 18672 18673This source accepts the following options: 18674 18675@table @option 18676 18677@item end_pts 18678Set the terminal pts value. Default value is 400. 18679 18680@item end_scale 18681Set the terminal scale value. 18682Must be a floating point value. Default value is 0.3. 18683 18684@item inner 18685Set the inner coloring mode, that is the algorithm used to draw the 18686Mandelbrot fractal internal region. 18687 18688It shall assume one of the following values: 18689@table @option 18690@item black 18691Set black mode. 18692@item convergence 18693Show time until convergence. 18694@item mincol 18695Set color based on point closest to the origin of the iterations. 18696@item period 18697Set period mode. 18698@end table 18699 18700Default value is @var{mincol}. 18701 18702@item bailout 18703Set the bailout value. Default value is 10.0. 18704 18705@item maxiter 18706Set the maximum of iterations performed by the rendering 18707algorithm. Default value is 7189. 18708 18709@item outer 18710Set outer coloring mode. 18711It shall assume one of following values: 18712@table @option 18713@item iteration_count 18714Set iteration cound mode. 18715@item normalized_iteration_count 18716set normalized iteration count mode. 18717@end table 18718Default value is @var{normalized_iteration_count}. 18719 18720@item rate, r 18721Set frame rate, expressed as number of frames per second. Default 18722value is "25". 18723 18724@item size, s 18725Set frame size. For the syntax of this option, check the @ref{video size syntax,,"Video 18726size" section in the ffmpeg-utils manual,ffmpeg-utils}. Default value is "640x480". 18727 18728@item start_scale 18729Set the initial scale value. Default value is 3.0. 18730 18731@item start_x 18732Set the initial x position. Must be a floating point value between 18733-100 and 100. Default value is -0.743643887037158704752191506114774. 18734 18735@item start_y 18736Set the initial y position. Must be a floating point value between 18737-100 and 100. Default value is -0.131825904205311970493132056385139. 18738@end table 18739 18740@section mptestsrc 18741 18742Generate various test patterns, as generated by the MPlayer test filter. 18743 18744The size of the generated video is fixed, and is 256x256. 18745This source is useful in particular for testing encoding features. 18746 18747This source accepts the following options: 18748 18749@table @option 18750 18751@item rate, r 18752Specify the frame rate of the sourced video, as the number of frames 18753generated per second. It has to be a string in the format 18754@var{frame_rate_num}/@var{frame_rate_den}, an integer number, a floating point 18755number or a valid video frame rate abbreviation. The default value is 18756"25". 18757 18758@item duration, d 18759Set the duration of the sourced video. See 18760@ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils} 18761for the accepted syntax. 18762 18763If not specified, or the expressed duration is negative, the video is 18764supposed to be generated forever. 18765 18766@item test, t 18767 18768Set the number or the name of the test to perform. Supported tests are: 18769@table @option 18770@item dc_luma 18771@item dc_chroma 18772@item freq_luma 18773@item freq_chroma 18774@item amp_luma 18775@item amp_chroma 18776@item cbp 18777@item mv 18778@item ring1 18779@item ring2 18780@item all 18781 18782@end table 18783 18784Default value is "all", which will cycle through the list of all tests. 18785@end table 18786 18787Some examples: 18788@example 18789mptestsrc=t=dc_luma 18790@end example 18791 18792will generate a "dc_luma" test pattern. 18793 18794@section frei0r_src 18795 18796Provide a frei0r source. 18797 18798To enable compilation of this filter you need to install the frei0r 18799header and configure FFmpeg with @code{--enable-frei0r}. 18800 18801This source accepts the following parameters: 18802 18803@table @option 18804 18805@item size 18806The size of the video to generate. For the syntax of this option, check the 18807@ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}. 18808 18809@item framerate 18810The framerate of the generated video. It may be a string of the form 18811@var{num}/@var{den} or a frame rate abbreviation. 18812 18813@item filter_name 18814The name to the frei0r source to load. For more information regarding frei0r and 18815how to set the parameters, read the @ref{frei0r} section in the video filters 18816documentation. 18817 18818@item filter_params 18819A '|'-separated list of parameters to pass to the frei0r source. 18820 18821@end table 18822 18823For example, to generate a frei0r partik0l source with size 200x200 18824and frame rate 10 which is overlaid on the overlay filter main input: 18825@example 18826frei0r_src=size=200x200:framerate=10:filter_name=partik0l:filter_params=1234 [overlay]; [in][overlay] overlay 18827@end example 18828 18829@section life 18830 18831Generate a life pattern. 18832 18833This source is based on a generalization of John Conway's life game. 18834 18835The sourced input represents a life grid, each pixel represents a cell 18836which can be in one of two possible states, alive or dead. Every cell 18837interacts with its eight neighbours, which are the cells that are 18838horizontally, vertically, or diagonally adjacent. 18839 18840At each interaction the grid evolves according to the adopted rule, 18841which specifies the number of neighbor alive cells which will make a 18842cell stay alive or born. The @option{rule} option allows one to specify 18843the rule to adopt. 18844 18845This source accepts the following options: 18846 18847@table @option 18848@item filename, f 18849Set the file from which to read the initial grid state. In the file, 18850each non-whitespace character is considered an alive cell, and newline 18851is used to delimit the end of each row. 18852 18853If this option is not specified, the initial grid is generated 18854randomly. 18855 18856@item rate, r 18857Set the video rate, that is the number of frames generated per second. 18858Default is 25. 18859 18860@item random_fill_ratio, ratio 18861Set the random fill ratio for the initial random grid. It is a 18862floating point number value ranging from 0 to 1, defaults to 1/PHI. 18863It is ignored when a file is specified. 18864 18865@item random_seed, seed 18866Set the seed for filling the initial random grid, must be an integer 18867included between 0 and UINT32_MAX. If not specified, or if explicitly 18868set to -1, the filter will try to use a good random seed on a best 18869effort basis. 18870 18871@item rule 18872Set the life rule. 18873 18874A rule can be specified with a code of the kind "S@var{NS}/B@var{NB}", 18875where @var{NS} and @var{NB} are sequences of numbers in the range 0-8, 18876@var{NS} specifies the number of alive neighbor cells which make a 18877live cell stay alive, and @var{NB} the number of alive neighbor cells 18878which make a dead cell to become alive (i.e. to "born"). 18879"s" and "b" can be used in place of "S" and "B", respectively. 18880 18881Alternatively a rule can be specified by an 18-bits integer. The 9 18882high order bits are used to encode the next cell state if it is alive 18883for each number of neighbor alive cells, the low order bits specify 18884the rule for "borning" new cells. Higher order bits encode for an 18885higher number of neighbor cells. 18886For example the number 6153 = @code{(12<<9)+9} specifies a stay alive 18887rule of 12 and a born rule of 9, which corresponds to "S23/B03". 18888 18889Default value is "S23/B3", which is the original Conway's game of life 18890rule, and will keep a cell alive if it has 2 or 3 neighbor alive 18891cells, and will born a new cell if there are three alive cells around 18892a dead cell. 18893 18894@item size, s 18895Set the size of the output video. For the syntax of this option, check the 18896@ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}. 18897 18898If @option{filename} is specified, the size is set by default to the 18899same size of the input file. If @option{size} is set, it must contain 18900the size specified in the input file, and the initial grid defined in 18901that file is centered in the larger resulting area. 18902 18903If a filename is not specified, the size value defaults to "320x240" 18904(used for a randomly generated initial grid). 18905 18906@item stitch 18907If set to 1, stitch the left and right grid edges together, and the 18908top and bottom edges also. Defaults to 1. 18909 18910@item mold 18911Set cell mold speed. If set, a dead cell will go from @option{death_color} to 18912@option{mold_color} with a step of @option{mold}. @option{mold} can have a 18913value from 0 to 255. 18914 18915@item life_color 18916Set the color of living (or new born) cells. 18917 18918@item death_color 18919Set the color of dead cells. If @option{mold} is set, this is the first color 18920used to represent a dead cell. 18921 18922@item mold_color 18923Set mold color, for definitely dead and moldy cells. 18924 18925For the syntax of these 3 color options, check the @ref{color syntax,,"Color" section in the 18926ffmpeg-utils manual,ffmpeg-utils}. 18927@end table 18928 18929@subsection Examples 18930 18931@itemize 18932@item 18933Read a grid from @file{pattern}, and center it on a grid of size 18934300x300 pixels: 18935@example 18936life=f=pattern:s=300x300 18937@end example 18938 18939@item 18940Generate a random grid of size 200x200, with a fill ratio of 2/3: 18941@example 18942life=ratio=2/3:s=200x200 18943@end example 18944 18945@item 18946Specify a custom rule for evolving a randomly generated grid: 18947@example 18948life=rule=S14/B34 18949@end example 18950 18951@item 18952Full example with slow death effect (mold) using @command{ffplay}: 18953@example 18954ffplay -f lavfi life=s=300x200:mold=10:r=60:ratio=0.1:death_color=#C83232:life_color=#00ff00,scale=1200:800:flags=16 18955@end example 18956@end itemize 18957 18958@anchor{allrgb} 18959@anchor{allyuv} 18960@anchor{color} 18961@anchor{haldclutsrc} 18962@anchor{nullsrc} 18963@anchor{pal75bars} 18964@anchor{pal100bars} 18965@anchor{rgbtestsrc} 18966@anchor{smptebars} 18967@anchor{smptehdbars} 18968@anchor{testsrc} 18969@anchor{testsrc2} 18970@anchor{yuvtestsrc} 18971@section allrgb, allyuv, color, haldclutsrc, nullsrc, pal75bars, pal100bars, rgbtestsrc, smptebars, smptehdbars, testsrc, testsrc2, yuvtestsrc 18972 18973The @code{allrgb} source returns frames of size 4096x4096 of all rgb colors. 18974 18975The @code{allyuv} source returns frames of size 4096x4096 of all yuv colors. 18976 18977The @code{color} source provides an uniformly colored input. 18978 18979The @code{haldclutsrc} source provides an identity Hald CLUT. See also 18980@ref{haldclut} filter. 18981 18982The @code{nullsrc} source returns unprocessed video frames. It is 18983mainly useful to be employed in analysis / debugging tools, or as the 18984source for filters which ignore the input data. 18985 18986The @code{pal75bars} source generates a color bars pattern, based on 18987EBU PAL recommendations with 75% color levels. 18988 18989The @code{pal100bars} source generates a color bars pattern, based on 18990EBU PAL recommendations with 100% color levels. 18991 18992The @code{rgbtestsrc} source generates an RGB test pattern useful for 18993detecting RGB vs BGR issues. You should see a red, green and blue 18994stripe from top to bottom. 18995 18996The @code{smptebars} source generates a color bars pattern, based on 18997the SMPTE Engineering Guideline EG 1-1990. 18998 18999The @code{smptehdbars} source generates a color bars pattern, based on 19000the SMPTE RP 219-2002. 19001 19002The @code{testsrc} source generates a test video pattern, showing a 19003color pattern, a scrolling gradient and a timestamp. This is mainly 19004intended for testing purposes. 19005 19006The @code{testsrc2} source is similar to testsrc, but supports more 19007pixel formats instead of just @code{rgb24}. This allows using it as an 19008input for other tests without requiring a format conversion. 19009 19010The @code{yuvtestsrc} source generates an YUV test pattern. You should 19011see a y, cb and cr stripe from top to bottom. 19012 19013The sources accept the following parameters: 19014 19015@table @option 19016 19017@item level 19018Specify the level of the Hald CLUT, only available in the @code{haldclutsrc} 19019source. A level of @code{N} generates a picture of @code{N*N*N} by @code{N*N*N} 19020pixels to be used as identity matrix for 3D lookup tables. Each component is 19021coded on a @code{1/(N*N)} scale. 19022 19023@item color, c 19024Specify the color of the source, only available in the @code{color} 19025source. For the syntax of this option, check the 19026@ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}. 19027 19028@item size, s 19029Specify the size of the sourced video. For the syntax of this option, check the 19030@ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}. 19031The default value is @code{320x240}. 19032 19033This option is not available with the @code{allrgb}, @code{allyuv}, and 19034@code{haldclutsrc} filters. 19035 19036@item rate, r 19037Specify the frame rate of the sourced video, as the number of frames 19038generated per second. It has to be a string in the format 19039@var{frame_rate_num}/@var{frame_rate_den}, an integer number, a floating point 19040number or a valid video frame rate abbreviation. The default value is 19041"25". 19042 19043@item duration, d 19044Set the duration of the sourced video. See 19045@ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils} 19046for the accepted syntax. 19047 19048If not specified, or the expressed duration is negative, the video is 19049supposed to be generated forever. 19050 19051@item sar 19052Set the sample aspect ratio of the sourced video. 19053 19054@item alpha 19055Specify the alpha (opacity) of the background, only available in the 19056@code{testsrc2} source. The value must be between 0 (fully transparent) and 19057255 (fully opaque, the default). 19058 19059@item decimals, n 19060Set the number of decimals to show in the timestamp, only available in the 19061@code{testsrc} source. 19062 19063The displayed timestamp value will correspond to the original 19064timestamp value multiplied by the power of 10 of the specified 19065value. Default value is 0. 19066@end table 19067 19068@subsection Examples 19069 19070@itemize 19071@item 19072Generate a video with a duration of 5.3 seconds, with size 19073176x144 and a frame rate of 10 frames per second: 19074@example 19075testsrc=duration=5.3:size=qcif:rate=10 19076@end example 19077 19078@item 19079The following graph description will generate a red source 19080with an opacity of 0.2, with size "qcif" and a frame rate of 10 19081frames per second: 19082@example 19083color=c=red@@0.2:s=qcif:r=10 19084@end example 19085 19086@item 19087If the input content is to be ignored, @code{nullsrc} can be used. The 19088following command generates noise in the luminance plane by employing 19089the @code{geq} filter: 19090@example 19091nullsrc=s=256x256, geq=random(1)*255:128:128 19092@end example 19093@end itemize 19094 19095@subsection Commands 19096 19097The @code{color} source supports the following commands: 19098 19099@table @option 19100@item c, color 19101Set the color of the created image. Accepts the same syntax of the 19102corresponding @option{color} option. 19103@end table 19104 19105@section openclsrc 19106 19107Generate video using an OpenCL program. 19108 19109@table @option 19110 19111@item source 19112OpenCL program source file. 19113 19114@item kernel 19115Kernel name in program. 19116 19117@item size, s 19118Size of frames to generate. This must be set. 19119 19120@item format 19121Pixel format to use for the generated frames. This must be set. 19122 19123@item rate, r 19124Number of frames generated every second. Default value is '25'. 19125 19126@end table 19127 19128For details of how the program loading works, see the @ref{program_opencl} 19129filter. 19130 19131Example programs: 19132 19133@itemize 19134@item 19135Generate a colour ramp by setting pixel values from the position of the pixel 19136in the output image. (Note that this will work with all pixel formats, but 19137the generated output will not be the same.) 19138@verbatim 19139__kernel void ramp(__write_only image2d_t dst, 19140 unsigned int index) 19141{ 19142 int2 loc = (int2)(get_global_id(0), get_global_id(1)); 19143 19144 float4 val; 19145 val.xy = val.zw = convert_float2(loc) / convert_float2(get_image_dim(dst)); 19146 19147 write_imagef(dst, loc, val); 19148} 19149@end verbatim 19150 19151@item 19152Generate a Sierpinski carpet pattern, panning by a single pixel each frame. 19153@verbatim 19154__kernel void sierpinski_carpet(__write_only image2d_t dst, 19155 unsigned int index) 19156{ 19157 int2 loc = (int2)(get_global_id(0), get_global_id(1)); 19158 19159 float4 value = 0.0f; 19160 int x = loc.x + index; 19161 int y = loc.y + index; 19162 while (x > 0 || y > 0) { 19163 if (x % 3 == 1 && y % 3 == 1) { 19164 value = 1.0f; 19165 break; 19166 } 19167 x /= 3; 19168 y /= 3; 19169 } 19170 19171 write_imagef(dst, loc, value); 19172} 19173@end verbatim 19174 19175@end itemize 19176 19177@c man end VIDEO SOURCES 19178 19179@chapter Video Sinks 19180@c man begin VIDEO SINKS 19181 19182Below is a description of the currently available video sinks. 19183 19184@section buffersink 19185 19186Buffer video frames, and make them available to the end of the filter 19187graph. 19188 19189This sink is mainly intended for programmatic use, in particular 19190through the interface defined in @file{libavfilter/buffersink.h} 19191or the options system. 19192 19193It accepts a pointer to an AVBufferSinkContext structure, which 19194defines the incoming buffers' formats, to be passed as the opaque 19195parameter to @code{avfilter_init_filter} for initialization. 19196 19197@section nullsink 19198 19199Null video sink: do absolutely nothing with the input video. It is 19200mainly useful as a template and for use in analysis / debugging 19201tools. 19202 19203@c man end VIDEO SINKS 19204 19205@chapter Multimedia Filters 19206@c man begin MULTIMEDIA FILTERS 19207 19208Below is a description of the currently available multimedia filters. 19209 19210@section abitscope 19211 19212Convert input audio to a video output, displaying the audio bit scope. 19213 19214The filter accepts the following options: 19215 19216@table @option 19217@item rate, r 19218Set frame rate, expressed as number of frames per second. Default 19219value is "25". 19220 19221@item size, s 19222Specify the video size for the output. For the syntax of this option, check the 19223@ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}. 19224Default value is @code{1024x256}. 19225 19226@item colors 19227Specify list of colors separated by space or by '|' which will be used to 19228draw channels. Unrecognized or missing colors will be replaced 19229by white color. 19230@end table 19231 19232@section ahistogram 19233 19234Convert input audio to a video output, displaying the volume histogram. 19235 19236The filter accepts the following options: 19237 19238@table @option 19239@item dmode 19240Specify how histogram is calculated. 19241 19242It accepts the following values: 19243@table @samp 19244@item single 19245Use single histogram for all channels. 19246@item separate 19247Use separate histogram for each channel. 19248@end table 19249Default is @code{single}. 19250 19251@item rate, r 19252Set frame rate, expressed as number of frames per second. Default 19253value is "25". 19254 19255@item size, s 19256Specify the video size for the output. For the syntax of this option, check the 19257@ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}. 19258Default value is @code{hd720}. 19259 19260@item scale 19261Set display scale. 19262 19263It accepts the following values: 19264@table @samp 19265@item log 19266logarithmic 19267@item sqrt 19268square root 19269@item cbrt 19270cubic root 19271@item lin 19272linear 19273@item rlog 19274reverse logarithmic 19275@end table 19276Default is @code{log}. 19277 19278@item ascale 19279Set amplitude scale. 19280 19281It accepts the following values: 19282@table @samp 19283@item log 19284logarithmic 19285@item lin 19286linear 19287@end table 19288Default is @code{log}. 19289 19290@item acount 19291Set how much frames to accumulate in histogram. 19292Defauls is 1. Setting this to -1 accumulates all frames. 19293 19294@item rheight 19295Set histogram ratio of window height. 19296 19297@item slide 19298Set sonogram sliding. 19299 19300It accepts the following values: 19301@table @samp 19302@item replace 19303replace old rows with new ones. 19304@item scroll 19305scroll from top to bottom. 19306@end table 19307Default is @code{replace}. 19308@end table 19309 19310@section aphasemeter 19311 19312Measures phase of input audio, which is exported as metadata @code{lavfi.aphasemeter.phase}, 19313representing mean phase of current audio frame. A video output can also be produced and is 19314enabled by default. The audio is passed through as first output. 19315 19316Audio will be rematrixed to stereo if it has a different channel layout. Phase value is in 19317range @code{[-1, 1]} where @code{-1} means left and right channels are completely out of phase 19318and @code{1} means channels are in phase. 19319 19320The filter accepts the following options, all related to its video output: 19321 19322@table @option 19323@item rate, r 19324Set the output frame rate. Default value is @code{25}. 19325 19326@item size, s 19327Set the video size for the output. For the syntax of this option, check the 19328@ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}. 19329Default value is @code{800x400}. 19330 19331@item rc 19332@item gc 19333@item bc 19334Specify the red, green, blue contrast. Default values are @code{2}, 19335@code{7} and @code{1}. 19336Allowed range is @code{[0, 255]}. 19337 19338@item mpc 19339Set color which will be used for drawing median phase. If color is 19340@code{none} which is default, no median phase value will be drawn. 19341 19342@item video 19343Enable video output. Default is enabled. 19344@end table 19345 19346@section avectorscope 19347 19348Convert input audio to a video output, representing the audio vector 19349scope. 19350 19351The filter is used to measure the difference between channels of stereo 19352audio stream. A monoaural signal, consisting of identical left and right 19353signal, results in straight vertical line. Any stereo separation is visible 19354as a deviation from this line, creating a Lissajous figure. 19355If the straight (or deviation from it) but horizontal line appears this 19356indicates that the left and right channels are out of phase. 19357 19358The filter accepts the following options: 19359 19360@table @option 19361@item mode, m 19362Set the vectorscope mode. 19363 19364Available values are: 19365@table @samp 19366@item lissajous 19367Lissajous rotated by 45 degrees. 19368 19369@item lissajous_xy 19370Same as above but not rotated. 19371 19372@item polar 19373Shape resembling half of circle. 19374@end table 19375 19376Default value is @samp{lissajous}. 19377 19378@item size, s 19379Set the video size for the output. For the syntax of this option, check the 19380@ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}. 19381Default value is @code{400x400}. 19382 19383@item rate, r 19384Set the output frame rate. Default value is @code{25}. 19385 19386@item rc 19387@item gc 19388@item bc 19389@item ac 19390Specify the red, green, blue and alpha contrast. Default values are @code{40}, 19391@code{160}, @code{80} and @code{255}. 19392Allowed range is @code{[0, 255]}. 19393 19394@item rf 19395@item gf 19396@item bf 19397@item af 19398Specify the red, green, blue and alpha fade. Default values are @code{15}, 19399@code{10}, @code{5} and @code{5}. 19400Allowed range is @code{[0, 255]}. 19401 19402@item zoom 19403Set the zoom factor. Default value is @code{1}. Allowed range is @code{[0, 10]}. 19404Values lower than @var{1} will auto adjust zoom factor to maximal possible value. 19405 19406@item draw 19407Set the vectorscope drawing mode. 19408 19409Available values are: 19410@table @samp 19411@item dot 19412Draw dot for each sample. 19413 19414@item line 19415Draw line between previous and current sample. 19416@end table 19417 19418Default value is @samp{dot}. 19419 19420@item scale 19421Specify amplitude scale of audio samples. 19422 19423Available values are: 19424@table @samp 19425@item lin 19426Linear. 19427 19428@item sqrt 19429Square root. 19430 19431@item cbrt 19432Cubic root. 19433 19434@item log 19435Logarithmic. 19436@end table 19437 19438@item swap 19439Swap left channel axis with right channel axis. 19440 19441@item mirror 19442Mirror axis. 19443 19444@table @samp 19445@item none 19446No mirror. 19447 19448@item x 19449Mirror only x axis. 19450 19451@item y 19452Mirror only y axis. 19453 19454@item xy 19455Mirror both axis. 19456@end table 19457 19458@end table 19459 19460@subsection Examples 19461 19462@itemize 19463@item 19464Complete example using @command{ffplay}: 19465@example 19466ffplay -f lavfi 'amovie=input.mp3, asplit [a][out1]; 19467 [a] avectorscope=zoom=1.3:rc=2:gc=200:bc=10:rf=1:gf=8:bf=7 [out0]' 19468@end example 19469@end itemize 19470 19471@section bench, abench 19472 19473Benchmark part of a filtergraph. 19474 19475The filter accepts the following options: 19476 19477@table @option 19478@item action 19479Start or stop a timer. 19480 19481Available values are: 19482@table @samp 19483@item start 19484Get the current time, set it as frame metadata (using the key 19485@code{lavfi.bench.start_time}), and forward the frame to the next filter. 19486 19487@item stop 19488Get the current time and fetch the @code{lavfi.bench.start_time} metadata from 19489the input frame metadata to get the time difference. Time difference, average, 19490maximum and minimum time (respectively @code{t}, @code{avg}, @code{max} and 19491@code{min}) are then printed. The timestamps are expressed in seconds. 19492@end table 19493@end table 19494 19495@subsection Examples 19496 19497@itemize 19498@item 19499Benchmark @ref{selectivecolor} filter: 19500@example 19501bench=start,selectivecolor=reds=-.2 .12 -.49,bench=stop 19502@end example 19503@end itemize 19504 19505@section concat 19506 19507Concatenate audio and video streams, joining them together one after the 19508other. 19509 19510The filter works on segments of synchronized video and audio streams. All 19511segments must have the same number of streams of each type, and that will 19512also be the number of streams at output. 19513 19514The filter accepts the following options: 19515 19516@table @option 19517 19518@item n 19519Set the number of segments. Default is 2. 19520 19521@item v 19522Set the number of output video streams, that is also the number of video 19523streams in each segment. Default is 1. 19524 19525@item a 19526Set the number of output audio streams, that is also the number of audio 19527streams in each segment. Default is 0. 19528 19529@item unsafe 19530Activate unsafe mode: do not fail if segments have a different format. 19531 19532@end table 19533 19534The filter has @var{v}+@var{a} outputs: first @var{v} video outputs, then 19535@var{a} audio outputs. 19536 19537There are @var{n}x(@var{v}+@var{a}) inputs: first the inputs for the first 19538segment, in the same order as the outputs, then the inputs for the second 19539segment, etc. 19540 19541Related streams do not always have exactly the same duration, for various 19542reasons including codec frame size or sloppy authoring. For that reason, 19543related synchronized streams (e.g. a video and its audio track) should be 19544concatenated at once. The concat filter will use the duration of the longest 19545stream in each segment (except the last one), and if necessary pad shorter 19546audio streams with silence. 19547 19548For this filter to work correctly, all segments must start at timestamp 0. 19549 19550All corresponding streams must have the same parameters in all segments; the 19551filtering system will automatically select a common pixel format for video 19552streams, and a common sample format, sample rate and channel layout for 19553audio streams, but other settings, such as resolution, must be converted 19554explicitly by the user. 19555 19556Different frame rates are acceptable but will result in variable frame rate 19557at output; be sure to configure the output file to handle it. 19558 19559@subsection Examples 19560 19561@itemize 19562@item 19563Concatenate an opening, an episode and an ending, all in bilingual version 19564(video in stream 0, audio in streams 1 and 2): 19565@example 19566ffmpeg -i opening.mkv -i episode.mkv -i ending.mkv -filter_complex \ 19567 '[0:0] [0:1] [0:2] [1:0] [1:1] [1:2] [2:0] [2:1] [2:2] 19568 concat=n=3:v=1:a=2 [v] [a1] [a2]' \ 19569 -map '[v]' -map '[a1]' -map '[a2]' output.mkv 19570@end example 19571 19572@item 19573Concatenate two parts, handling audio and video separately, using the 19574(a)movie sources, and adjusting the resolution: 19575@example 19576movie=part1.mp4, scale=512:288 [v1] ; amovie=part1.mp4 [a1] ; 19577movie=part2.mp4, scale=512:288 [v2] ; amovie=part2.mp4 [a2] ; 19578[v1] [v2] concat [outv] ; [a1] [a2] concat=v=0:a=1 [outa] 19579@end example 19580Note that a desync will happen at the stitch if the audio and video streams 19581do not have exactly the same duration in the first file. 19582 19583@end itemize 19584 19585@subsection Commands 19586 19587This filter supports the following commands: 19588@table @option 19589@item next 19590Close the current segment and step to the next one 19591@end table 19592 19593@section drawgraph, adrawgraph 19594 19595Draw a graph using input video or audio metadata. 19596 19597It accepts the following parameters: 19598 19599@table @option 19600@item m1 19601Set 1st frame metadata key from which metadata values will be used to draw a graph. 19602 19603@item fg1 19604Set 1st foreground color expression. 19605 19606@item m2 19607Set 2nd frame metadata key from which metadata values will be used to draw a graph. 19608 19609@item fg2 19610Set 2nd foreground color expression. 19611 19612@item m3 19613Set 3rd frame metadata key from which metadata values will be used to draw a graph. 19614 19615@item fg3 19616Set 3rd foreground color expression. 19617 19618@item m4 19619Set 4th frame metadata key from which metadata values will be used to draw a graph. 19620 19621@item fg4 19622Set 4th foreground color expression. 19623 19624@item min 19625Set minimal value of metadata value. 19626 19627@item max 19628Set maximal value of metadata value. 19629 19630@item bg 19631Set graph background color. Default is white. 19632 19633@item mode 19634Set graph mode. 19635 19636Available values for mode is: 19637@table @samp 19638@item bar 19639@item dot 19640@item line 19641@end table 19642 19643Default is @code{line}. 19644 19645@item slide 19646Set slide mode. 19647 19648Available values for slide is: 19649@table @samp 19650@item frame 19651Draw new frame when right border is reached. 19652 19653@item replace 19654Replace old columns with new ones. 19655 19656@item scroll 19657Scroll from right to left. 19658 19659@item rscroll 19660Scroll from left to right. 19661 19662@item picture 19663Draw single picture. 19664@end table 19665 19666Default is @code{frame}. 19667 19668@item size 19669Set size of graph video. For the syntax of this option, check the 19670@ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}. 19671The default value is @code{900x256}. 19672 19673The foreground color expressions can use the following variables: 19674@table @option 19675@item MIN 19676Minimal value of metadata value. 19677 19678@item MAX 19679Maximal value of metadata value. 19680 19681@item VAL 19682Current metadata key value. 19683@end table 19684 19685The color is defined as 0xAABBGGRR. 19686@end table 19687 19688Example using metadata from @ref{signalstats} filter: 19689@example 19690signalstats,drawgraph=lavfi.signalstats.YAVG:min=0:max=255 19691@end example 19692 19693Example using metadata from @ref{ebur128} filter: 19694@example 19695ebur128=metadata=1,adrawgraph=lavfi.r128.M:min=-120:max=5 19696@end example 19697 19698@anchor{ebur128} 19699@section ebur128 19700 19701EBU R128 scanner filter. This filter takes an audio stream as input and outputs 19702it unchanged. By default, it logs a message at a frequency of 10Hz with the 19703Momentary loudness (identified by @code{M}), Short-term loudness (@code{S}), 19704Integrated loudness (@code{I}) and Loudness Range (@code{LRA}). 19705 19706The filter also has a video output (see the @var{video} option) with a real 19707time graph to observe the loudness evolution. The graphic contains the logged 19708message mentioned above, so it is not printed anymore when this option is set, 19709unless the verbose logging is set. The main graphing area contains the 19710short-term loudness (3 seconds of analysis), and the gauge on the right is for 19711the momentary loudness (400 milliseconds), but can optionally be configured 19712to instead display short-term loudness (see @var{gauge}). 19713 19714The green area marks a +/- 1LU target range around the target loudness 19715(-23LUFS by default, unless modified through @var{target}). 19716 19717More information about the Loudness Recommendation EBU R128 on 19718@url{http://tech.ebu.ch/loudness}. 19719 19720The filter accepts the following options: 19721 19722@table @option 19723 19724@item video 19725Activate the video output. The audio stream is passed unchanged whether this 19726option is set or no. The video stream will be the first output stream if 19727activated. Default is @code{0}. 19728 19729@item size 19730Set the video size. This option is for video only. For the syntax of this 19731option, check the 19732@ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}. 19733Default and minimum resolution is @code{640x480}. 19734 19735@item meter 19736Set the EBU scale meter. Default is @code{9}. Common values are @code{9} and 19737@code{18}, respectively for EBU scale meter +9 and EBU scale meter +18. Any 19738other integer value between this range is allowed. 19739 19740@item metadata 19741Set metadata injection. If set to @code{1}, the audio input will be segmented 19742into 100ms output frames, each of them containing various loudness information 19743in metadata. All the metadata keys are prefixed with @code{lavfi.r128.}. 19744 19745Default is @code{0}. 19746 19747@item framelog 19748Force the frame logging level. 19749 19750Available values are: 19751@table @samp 19752@item info 19753information logging level 19754@item verbose 19755verbose logging level 19756@end table 19757 19758By default, the logging level is set to @var{info}. If the @option{video} or 19759the @option{metadata} options are set, it switches to @var{verbose}. 19760 19761@item peak 19762Set peak mode(s). 19763 19764Available modes can be cumulated (the option is a @code{flag} type). Possible 19765values are: 19766@table @samp 19767@item none 19768Disable any peak mode (default). 19769@item sample 19770Enable sample-peak mode. 19771 19772Simple peak mode looking for the higher sample value. It logs a message 19773for sample-peak (identified by @code{SPK}). 19774@item true 19775Enable true-peak mode. 19776 19777If enabled, the peak lookup is done on an over-sampled version of the input 19778stream for better peak accuracy. It logs a message for true-peak. 19779(identified by @code{TPK}) and true-peak per frame (identified by @code{FTPK}). 19780This mode requires a build with @code{libswresample}. 19781@end table 19782 19783@item dualmono 19784Treat mono input files as "dual mono". If a mono file is intended for playback 19785on a stereo system, its EBU R128 measurement will be perceptually incorrect. 19786If set to @code{true}, this option will compensate for this effect. 19787Multi-channel input files are not affected by this option. 19788 19789@item panlaw 19790Set a specific pan law to be used for the measurement of dual mono files. 19791This parameter is optional, and has a default value of -3.01dB. 19792 19793@item target 19794Set a specific target level (in LUFS) used as relative zero in the visualization. 19795This parameter is optional and has a default value of -23LUFS as specified 19796by EBU R128. However, material published online may prefer a level of -16LUFS 19797(e.g. for use with podcasts or video platforms). 19798 19799@item gauge 19800Set the value displayed by the gauge. Valid values are @code{momentary} and s 19801@code{shortterm}. By default the momentary value will be used, but in certain 19802scenarios it may be more useful to observe the short term value instead (e.g. 19803live mixing). 19804 19805@item scale 19806Sets the display scale for the loudness. Valid parameters are @code{absolute} 19807(in LUFS) or @code{relative} (LU) relative to the target. This only affects the 19808video output, not the summary or continuous log output. 19809@end table 19810 19811@subsection Examples 19812 19813@itemize 19814@item 19815Real-time graph using @command{ffplay}, with a EBU scale meter +18: 19816@example 19817ffplay -f lavfi -i "amovie=input.mp3,ebur128=video=1:meter=18 [out0][out1]" 19818@end example 19819 19820@item 19821Run an analysis with @command{ffmpeg}: 19822@example 19823ffmpeg -nostats -i input.mp3 -filter_complex ebur128 -f null - 19824@end example 19825@end itemize 19826 19827@section interleave, ainterleave 19828 19829Temporally interleave frames from several inputs. 19830 19831@code{interleave} works with video inputs, @code{ainterleave} with audio. 19832 19833These filters read frames from several inputs and send the oldest 19834queued frame to the output. 19835 19836Input streams must have well defined, monotonically increasing frame 19837timestamp values. 19838 19839In order to submit one frame to output, these filters need to enqueue 19840at least one frame for each input, so they cannot work in case one 19841input is not yet terminated and will not receive incoming frames. 19842 19843For example consider the case when one input is a @code{select} filter 19844which always drops input frames. The @code{interleave} filter will keep 19845reading from that input, but it will never be able to send new frames 19846to output until the input sends an end-of-stream signal. 19847 19848Also, depending on inputs synchronization, the filters will drop 19849frames in case one input receives more frames than the other ones, and 19850the queue is already filled. 19851 19852These filters accept the following options: 19853 19854@table @option 19855@item nb_inputs, n 19856Set the number of different inputs, it is 2 by default. 19857@end table 19858 19859@subsection Examples 19860 19861@itemize 19862@item 19863Interleave frames belonging to different streams using @command{ffmpeg}: 19864@example 19865ffmpeg -i bambi.avi -i pr0n.mkv -filter_complex "[0:v][1:v] interleave" out.avi 19866@end example 19867 19868@item 19869Add flickering blur effect: 19870@example 19871select='if(gt(random(0), 0.2), 1, 2)':n=2 [tmp], boxblur=2:2, [tmp] interleave 19872@end example 19873@end itemize 19874 19875@section metadata, ametadata 19876 19877Manipulate frame metadata. 19878 19879This filter accepts the following options: 19880 19881@table @option 19882@item mode 19883Set mode of operation of the filter. 19884 19885Can be one of the following: 19886 19887@table @samp 19888@item select 19889If both @code{value} and @code{key} is set, select frames 19890which have such metadata. If only @code{key} is set, select 19891every frame that has such key in metadata. 19892 19893@item add 19894Add new metadata @code{key} and @code{value}. If key is already available 19895do nothing. 19896 19897@item modify 19898Modify value of already present key. 19899 19900@item delete 19901If @code{value} is set, delete only keys that have such value. 19902Otherwise, delete key. If @code{key} is not set, delete all metadata values in 19903the frame. 19904 19905@item print 19906Print key and its value if metadata was found. If @code{key} is not set print all 19907metadata values available in frame. 19908@end table 19909 19910@item key 19911Set key used with all modes. Must be set for all modes except @code{print} and @code{delete}. 19912 19913@item value 19914Set metadata value which will be used. This option is mandatory for 19915@code{modify} and @code{add} mode. 19916 19917@item function 19918Which function to use when comparing metadata value and @code{value}. 19919 19920Can be one of following: 19921 19922@table @samp 19923@item same_str 19924Values are interpreted as strings, returns true if metadata value is same as @code{value}. 19925 19926@item starts_with 19927Values are interpreted as strings, returns true if metadata value starts with 19928the @code{value} option string. 19929 19930@item less 19931Values are interpreted as floats, returns true if metadata value is less than @code{value}. 19932 19933@item equal 19934Values are interpreted as floats, returns true if @code{value} is equal with metadata value. 19935 19936@item greater 19937Values are interpreted as floats, returns true if metadata value is greater than @code{value}. 19938 19939@item expr 19940Values are interpreted as floats, returns true if expression from option @code{expr} 19941evaluates to true. 19942@end table 19943 19944@item expr 19945Set expression which is used when @code{function} is set to @code{expr}. 19946The expression is evaluated through the eval API and can contain the following 19947constants: 19948 19949@table @option 19950@item VALUE1 19951Float representation of @code{value} from metadata key. 19952 19953@item VALUE2 19954Float representation of @code{value} as supplied by user in @code{value} option. 19955@end table 19956 19957@item file 19958If specified in @code{print} mode, output is written to the named file. Instead of 19959plain filename any writable url can be specified. Filename ``-'' is a shorthand 19960for standard output. If @code{file} option is not set, output is written to the log 19961with AV_LOG_INFO loglevel. 19962 19963@end table 19964 19965@subsection Examples 19966 19967@itemize 19968@item 19969Print all metadata values for frames with key @code{lavfi.signalstats.YDIF} with values 19970between 0 and 1. 19971@example 19972signalstats,metadata=print:key=lavfi.signalstats.YDIF:value=0:function=expr:expr='between(VALUE1,0,1)' 19973@end example 19974@item 19975Print silencedetect output to file @file{metadata.txt}. 19976@example 19977silencedetect,ametadata=mode=print:file=metadata.txt 19978@end example 19979@item 19980Direct all metadata to a pipe with file descriptor 4. 19981@example 19982metadata=mode=print:file='pipe\:4' 19983@end example 19984@end itemize 19985 19986@section perms, aperms 19987 19988Set read/write permissions for the output frames. 19989 19990These filters are mainly aimed at developers to test direct path in the 19991following filter in the filtergraph. 19992 19993The filters accept the following options: 19994 19995@table @option 19996@item mode 19997Select the permissions mode. 19998 19999It accepts the following values: 20000@table @samp 20001@item none 20002Do nothing. This is the default. 20003@item ro 20004Set all the output frames read-only. 20005@item rw 20006Set all the output frames directly writable. 20007@item toggle 20008Make the frame read-only if writable, and writable if read-only. 20009@item random 20010Set each output frame read-only or writable randomly. 20011@end table 20012 20013@item seed 20014Set the seed for the @var{random} mode, must be an integer included between 20015@code{0} and @code{UINT32_MAX}. If not specified, or if explicitly set to 20016@code{-1}, the filter will try to use a good random seed on a best effort 20017basis. 20018@end table 20019 20020Note: in case of auto-inserted filter between the permission filter and the 20021following one, the permission might not be received as expected in that 20022following filter. Inserting a @ref{format} or @ref{aformat} filter before the 20023perms/aperms filter can avoid this problem. 20024 20025@section realtime, arealtime 20026 20027Slow down filtering to match real time approximately. 20028 20029These filters will pause the filtering for a variable amount of time to 20030match the output rate with the input timestamps. 20031They are similar to the @option{re} option to @code{ffmpeg}. 20032 20033They accept the following options: 20034 20035@table @option 20036@item limit 20037Time limit for the pauses. Any pause longer than that will be considered 20038a timestamp discontinuity and reset the timer. Default is 2 seconds. 20039@end table 20040 20041@anchor{select} 20042@section select, aselect 20043 20044Select frames to pass in output. 20045 20046This filter accepts the following options: 20047 20048@table @option 20049 20050@item expr, e 20051Set expression, which is evaluated for each input frame. 20052 20053If the expression is evaluated to zero, the frame is discarded. 20054 20055If the evaluation result is negative or NaN, the frame is sent to the 20056first output; otherwise it is sent to the output with index 20057@code{ceil(val)-1}, assuming that the input index starts from 0. 20058 20059For example a value of @code{1.2} corresponds to the output with index 20060@code{ceil(1.2)-1 = 2-1 = 1}, that is the second output. 20061 20062@item outputs, n 20063Set the number of outputs. The output to which to send the selected 20064frame is based on the result of the evaluation. Default value is 1. 20065@end table 20066 20067The expression can contain the following constants: 20068 20069@table @option 20070@item n 20071The (sequential) number of the filtered frame, starting from 0. 20072 20073@item selected_n 20074The (sequential) number of the selected frame, starting from 0. 20075 20076@item prev_selected_n 20077The sequential number of the last selected frame. It's NAN if undefined. 20078 20079@item TB 20080The timebase of the input timestamps. 20081 20082@item pts 20083The PTS (Presentation TimeStamp) of the filtered video frame, 20084expressed in @var{TB} units. It's NAN if undefined. 20085 20086@item t 20087The PTS of the filtered video frame, 20088expressed in seconds. It's NAN if undefined. 20089 20090@item prev_pts 20091The PTS of the previously filtered video frame. It's NAN if undefined. 20092 20093@item prev_selected_pts 20094The PTS of the last previously filtered video frame. It's NAN if undefined. 20095 20096@item prev_selected_t 20097The PTS of the last previously selected video frame, expressed in seconds. It's NAN if undefined. 20098 20099@item start_pts 20100The PTS of the first video frame in the video. It's NAN if undefined. 20101 20102@item start_t 20103The time of the first video frame in the video. It's NAN if undefined. 20104 20105@item pict_type @emph{(video only)} 20106The type of the filtered frame. It can assume one of the following 20107values: 20108@table @option 20109@item I 20110@item P 20111@item B 20112@item S 20113@item SI 20114@item SP 20115@item BI 20116@end table 20117 20118@item interlace_type @emph{(video only)} 20119The frame interlace type. It can assume one of the following values: 20120@table @option 20121@item PROGRESSIVE 20122The frame is progressive (not interlaced). 20123@item TOPFIRST 20124The frame is top-field-first. 20125@item BOTTOMFIRST 20126The frame is bottom-field-first. 20127@end table 20128 20129@item consumed_sample_n @emph{(audio only)} 20130the number of selected samples before the current frame 20131 20132@item samples_n @emph{(audio only)} 20133the number of samples in the current frame 20134 20135@item sample_rate @emph{(audio only)} 20136the input sample rate 20137 20138@item key 20139This is 1 if the filtered frame is a key-frame, 0 otherwise. 20140 20141@item pos 20142the position in the file of the filtered frame, -1 if the information 20143is not available (e.g. for synthetic video) 20144 20145@item scene @emph{(video only)} 20146value between 0 and 1 to indicate a new scene; a low value reflects a low 20147probability for the current frame to introduce a new scene, while a higher 20148value means the current frame is more likely to be one (see the example below) 20149 20150@item concatdec_select 20151The concat demuxer can select only part of a concat input file by setting an 20152inpoint and an outpoint, but the output packets may not be entirely contained 20153in the selected interval. By using this variable, it is possible to skip frames 20154generated by the concat demuxer which are not exactly contained in the selected 20155interval. 20156 20157This works by comparing the frame pts against the @var{lavf.concat.start_time} 20158and the @var{lavf.concat.duration} packet metadata values which are also 20159present in the decoded frames. 20160 20161The @var{concatdec_select} variable is -1 if the frame pts is at least 20162start_time and either the duration metadata is missing or the frame pts is less 20163than start_time + duration, 0 otherwise, and NaN if the start_time metadata is 20164missing. 20165 20166That basically means that an input frame is selected if its pts is within the 20167interval set by the concat demuxer. 20168 20169@end table 20170 20171The default value of the select expression is "1". 20172 20173@subsection Examples 20174 20175@itemize 20176@item 20177Select all frames in input: 20178@example 20179select 20180@end example 20181 20182The example above is the same as: 20183@example 20184select=1 20185@end example 20186 20187@item 20188Skip all frames: 20189@example 20190select=0 20191@end example 20192 20193@item 20194Select only I-frames: 20195@example 20196select='eq(pict_type\,I)' 20197@end example 20198 20199@item 20200Select one frame every 100: 20201@example 20202select='not(mod(n\,100))' 20203@end example 20204 20205@item 20206Select only frames contained in the 10-20 time interval: 20207@example 20208select=between(t\,10\,20) 20209@end example 20210 20211@item 20212Select only I-frames contained in the 10-20 time interval: 20213@example 20214select=between(t\,10\,20)*eq(pict_type\,I) 20215@end example 20216 20217@item 20218Select frames with a minimum distance of 10 seconds: 20219@example 20220select='isnan(prev_selected_t)+gte(t-prev_selected_t\,10)' 20221@end example 20222 20223@item 20224Use aselect to select only audio frames with samples number > 100: 20225@example 20226aselect='gt(samples_n\,100)' 20227@end example 20228 20229@item 20230Create a mosaic of the first scenes: 20231@example 20232ffmpeg -i video.avi -vf select='gt(scene\,0.4)',scale=160:120,tile -frames:v 1 preview.png 20233@end example 20234 20235Comparing @var{scene} against a value between 0.3 and 0.5 is generally a sane 20236choice. 20237 20238@item 20239Send even and odd frames to separate outputs, and compose them: 20240@example 20241select=n=2:e='mod(n, 2)+1' [odd][even]; [odd] pad=h=2*ih [tmp]; [tmp][even] overlay=y=h 20242@end example 20243 20244@item 20245Select useful frames from an ffconcat file which is using inpoints and 20246outpoints but where the source files are not intra frame only. 20247@example 20248ffmpeg -copyts -vsync 0 -segment_time_metadata 1 -i input.ffconcat -vf select=concatdec_select -af aselect=concatdec_select output.avi 20249@end example 20250@end itemize 20251 20252@section sendcmd, asendcmd 20253 20254Send commands to filters in the filtergraph. 20255 20256These filters read commands to be sent to other filters in the 20257filtergraph. 20258 20259@code{sendcmd} must be inserted between two video filters, 20260@code{asendcmd} must be inserted between two audio filters, but apart 20261from that they act the same way. 20262 20263The specification of commands can be provided in the filter arguments 20264with the @var{commands} option, or in a file specified by the 20265@var{filename} option. 20266 20267These filters accept the following options: 20268@table @option 20269@item commands, c 20270Set the commands to be read and sent to the other filters. 20271@item filename, f 20272Set the filename of the commands to be read and sent to the other 20273filters. 20274@end table 20275 20276@subsection Commands syntax 20277 20278A commands description consists of a sequence of interval 20279specifications, comprising a list of commands to be executed when a 20280particular event related to that interval occurs. The occurring event 20281is typically the current frame time entering or leaving a given time 20282interval. 20283 20284An interval is specified by the following syntax: 20285@example 20286@var{START}[-@var{END}] @var{COMMANDS}; 20287@end example 20288 20289The time interval is specified by the @var{START} and @var{END} times. 20290@var{END} is optional and defaults to the maximum time. 20291 20292The current frame time is considered within the specified interval if 20293it is included in the interval [@var{START}, @var{END}), that is when 20294the time is greater or equal to @var{START} and is lesser than 20295@var{END}. 20296 20297@var{COMMANDS} consists of a sequence of one or more command 20298specifications, separated by ",", relating to that interval. The 20299syntax of a command specification is given by: 20300@example 20301[@var{FLAGS}] @var{TARGET} @var{COMMAND} @var{ARG} 20302@end example 20303 20304@var{FLAGS} is optional and specifies the type of events relating to 20305the time interval which enable sending the specified command, and must 20306be a non-null sequence of identifier flags separated by "+" or "|" and 20307enclosed between "[" and "]". 20308 20309The following flags are recognized: 20310@table @option 20311@item enter 20312The command is sent when the current frame timestamp enters the 20313specified interval. In other words, the command is sent when the 20314previous frame timestamp was not in the given interval, and the 20315current is. 20316 20317@item leave 20318The command is sent when the current frame timestamp leaves the 20319specified interval. In other words, the command is sent when the 20320previous frame timestamp was in the given interval, and the 20321current is not. 20322@end table 20323 20324If @var{FLAGS} is not specified, a default value of @code{[enter]} is 20325assumed. 20326 20327@var{TARGET} specifies the target of the command, usually the name of 20328the filter class or a specific filter instance name. 20329 20330@var{COMMAND} specifies the name of the command for the target filter. 20331 20332@var{ARG} is optional and specifies the optional list of argument for 20333the given @var{COMMAND}. 20334 20335Between one interval specification and another, whitespaces, or 20336sequences of characters starting with @code{#} until the end of line, 20337are ignored and can be used to annotate comments. 20338 20339A simplified BNF description of the commands specification syntax 20340follows: 20341@example 20342@var{COMMAND_FLAG} ::= "enter" | "leave" 20343@var{COMMAND_FLAGS} ::= @var{COMMAND_FLAG} [(+|"|")@var{COMMAND_FLAG}] 20344@var{COMMAND} ::= ["[" @var{COMMAND_FLAGS} "]"] @var{TARGET} @var{COMMAND} [@var{ARG}] 20345@var{COMMANDS} ::= @var{COMMAND} [,@var{COMMANDS}] 20346@var{INTERVAL} ::= @var{START}[-@var{END}] @var{COMMANDS} 20347@var{INTERVALS} ::= @var{INTERVAL}[;@var{INTERVALS}] 20348@end example 20349 20350@subsection Examples 20351 20352@itemize 20353@item 20354Specify audio tempo change at second 4: 20355@example 20356asendcmd=c='4.0 atempo tempo 1.5',atempo 20357@end example 20358 20359@item 20360Target a specific filter instance: 20361@example 20362asendcmd=c='4.0 atempo@@my tempo 1.5',atempo@@my 20363@end example 20364 20365@item 20366Specify a list of drawtext and hue commands in a file. 20367@example 20368# show text in the interval 5-10 203695.0-10.0 [enter] drawtext reinit 'fontfile=FreeSerif.ttf:text=hello world', 20370 [leave] drawtext reinit 'fontfile=FreeSerif.ttf:text='; 20371 20372# desaturate the image in the interval 15-20 2037315.0-20.0 [enter] hue s 0, 20374 [enter] drawtext reinit 'fontfile=FreeSerif.ttf:text=nocolor', 20375 [leave] hue s 1, 20376 [leave] drawtext reinit 'fontfile=FreeSerif.ttf:text=color'; 20377 20378# apply an exponential saturation fade-out effect, starting from time 25 2037925 [enter] hue s exp(25-t) 20380@end example 20381 20382A filtergraph allowing to read and process the above command list 20383stored in a file @file{test.cmd}, can be specified with: 20384@example 20385sendcmd=f=test.cmd,drawtext=fontfile=FreeSerif.ttf:text='',hue 20386@end example 20387@end itemize 20388 20389@anchor{setpts} 20390@section setpts, asetpts 20391 20392Change the PTS (presentation timestamp) of the input frames. 20393 20394@code{setpts} works on video frames, @code{asetpts} on audio frames. 20395 20396This filter accepts the following options: 20397 20398@table @option 20399 20400@item expr 20401The expression which is evaluated for each frame to construct its timestamp. 20402 20403@end table 20404 20405The expression is evaluated through the eval API and can contain the following 20406constants: 20407 20408@table @option 20409@item FRAME_RATE, FR 20410frame rate, only defined for constant frame-rate video 20411 20412@item PTS 20413The presentation timestamp in input 20414 20415@item N 20416The count of the input frame for video or the number of consumed samples, 20417not including the current frame for audio, starting from 0. 20418 20419@item NB_CONSUMED_SAMPLES 20420The number of consumed samples, not including the current frame (only 20421audio) 20422 20423@item NB_SAMPLES, S 20424The number of samples in the current frame (only audio) 20425 20426@item SAMPLE_RATE, SR 20427The audio sample rate. 20428 20429@item STARTPTS 20430The PTS of the first frame. 20431 20432@item STARTT 20433the time in seconds of the first frame 20434 20435@item INTERLACED 20436State whether the current frame is interlaced. 20437 20438@item T 20439the time in seconds of the current frame 20440 20441@item POS 20442original position in the file of the frame, or undefined if undefined 20443for the current frame 20444 20445@item PREV_INPTS 20446The previous input PTS. 20447 20448@item PREV_INT 20449previous input time in seconds 20450 20451@item PREV_OUTPTS 20452The previous output PTS. 20453 20454@item PREV_OUTT 20455previous output time in seconds 20456 20457@item RTCTIME 20458The wallclock (RTC) time in microseconds. This is deprecated, use time(0) 20459instead. 20460 20461@item RTCSTART 20462The wallclock (RTC) time at the start of the movie in microseconds. 20463 20464@item TB 20465The timebase of the input timestamps. 20466 20467@end table 20468 20469@subsection Examples 20470 20471@itemize 20472@item 20473Start counting PTS from zero 20474@example 20475setpts=PTS-STARTPTS 20476@end example 20477 20478@item 20479Apply fast motion effect: 20480@example 20481setpts=0.5*PTS 20482@end example 20483 20484@item 20485Apply slow motion effect: 20486@example 20487setpts=2.0*PTS 20488@end example 20489 20490@item 20491Set fixed rate of 25 frames per second: 20492@example 20493setpts=N/(25*TB) 20494@end example 20495 20496@item 20497Set fixed rate 25 fps with some jitter: 20498@example 20499setpts='1/(25*TB) * (N + 0.05 * sin(N*2*PI/25))' 20500@end example 20501 20502@item 20503Apply an offset of 10 seconds to the input PTS: 20504@example 20505setpts=PTS+10/TB 20506@end example 20507 20508@item 20509Generate timestamps from a "live source" and rebase onto the current timebase: 20510@example 20511setpts='(RTCTIME - RTCSTART) / (TB * 1000000)' 20512@end example 20513 20514@item 20515Generate timestamps by counting samples: 20516@example 20517asetpts=N/SR/TB 20518@end example 20519 20520@end itemize 20521 20522@section setrange 20523 20524Force color range for the output video frame. 20525 20526The @code{setrange} filter marks the color range property for the 20527output frames. It does not change the input frame, but only sets the 20528corresponding property, which affects how the frame is treated by 20529following filters. 20530 20531The filter accepts the following options: 20532 20533@table @option 20534 20535@item range 20536Available values are: 20537 20538@table @samp 20539@item auto 20540Keep the same color range property. 20541 20542@item unspecified, unknown 20543Set the color range as unspecified. 20544 20545@item limited, tv, mpeg 20546Set the color range as limited. 20547 20548@item full, pc, jpeg 20549Set the color range as full. 20550@end table 20551@end table 20552 20553@section settb, asettb 20554 20555Set the timebase to use for the output frames timestamps. 20556It is mainly useful for testing timebase configuration. 20557 20558It accepts the following parameters: 20559 20560@table @option 20561 20562@item expr, tb 20563The expression which is evaluated into the output timebase. 20564 20565@end table 20566 20567The value for @option{tb} is an arithmetic expression representing a 20568rational. The expression can contain the constants "AVTB" (the default 20569timebase), "intb" (the input timebase) and "sr" (the sample rate, 20570audio only). Default value is "intb". 20571 20572@subsection Examples 20573 20574@itemize 20575@item 20576Set the timebase to 1/25: 20577@example 20578settb=expr=1/25 20579@end example 20580 20581@item 20582Set the timebase to 1/10: 20583@example 20584settb=expr=0.1 20585@end example 20586 20587@item 20588Set the timebase to 1001/1000: 20589@example 20590settb=1+0.001 20591@end example 20592 20593@item 20594Set the timebase to 2*intb: 20595@example 20596settb=2*intb 20597@end example 20598 20599@item 20600Set the default timebase value: 20601@example 20602settb=AVTB 20603@end example 20604@end itemize 20605 20606@section showcqt 20607Convert input audio to a video output representing frequency spectrum 20608logarithmically using Brown-Puckette constant Q transform algorithm with 20609direct frequency domain coefficient calculation (but the transform itself 20610is not really constant Q, instead the Q factor is actually variable/clamped), 20611with musical tone scale, from E0 to D#10. 20612 20613The filter accepts the following options: 20614 20615@table @option 20616@item size, s 20617Specify the video size for the output. It must be even. For the syntax of this option, 20618check the @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}. 20619Default value is @code{1920x1080}. 20620 20621@item fps, rate, r 20622Set the output frame rate. Default value is @code{25}. 20623 20624@item bar_h 20625Set the bargraph height. It must be even. Default value is @code{-1} which 20626computes the bargraph height automatically. 20627 20628@item axis_h 20629Set the axis height. It must be even. Default value is @code{-1} which computes 20630the axis height automatically. 20631 20632@item sono_h 20633Set the sonogram height. It must be even. Default value is @code{-1} which 20634computes the sonogram height automatically. 20635 20636@item fullhd 20637Set the fullhd resolution. This option is deprecated, use @var{size}, @var{s} 20638instead. Default value is @code{1}. 20639 20640@item sono_v, volume 20641Specify the sonogram volume expression. It can contain variables: 20642@table @option 20643@item bar_v 20644the @var{bar_v} evaluated expression 20645@item frequency, freq, f 20646the frequency where it is evaluated 20647@item timeclamp, tc 20648the value of @var{timeclamp} option 20649@end table 20650and functions: 20651@table @option 20652@item a_weighting(f) 20653A-weighting of equal loudness 20654@item b_weighting(f) 20655B-weighting of equal loudness 20656@item c_weighting(f) 20657C-weighting of equal loudness. 20658@end table 20659Default value is @code{16}. 20660 20661@item bar_v, volume2 20662Specify the bargraph volume expression. It can contain variables: 20663@table @option 20664@item sono_v 20665the @var{sono_v} evaluated expression 20666@item frequency, freq, f 20667the frequency where it is evaluated 20668@item timeclamp, tc 20669the value of @var{timeclamp} option 20670@end table 20671and functions: 20672@table @option 20673@item a_weighting(f) 20674A-weighting of equal loudness 20675@item b_weighting(f) 20676B-weighting of equal loudness 20677@item c_weighting(f) 20678C-weighting of equal loudness. 20679@end table 20680Default value is @code{sono_v}. 20681 20682@item sono_g, gamma 20683Specify the sonogram gamma. Lower gamma makes the spectrum more contrast, 20684higher gamma makes the spectrum having more range. Default value is @code{3}. 20685Acceptable range is @code{[1, 7]}. 20686 20687@item bar_g, gamma2 20688Specify the bargraph gamma. Default value is @code{1}. Acceptable range is 20689@code{[1, 7]}. 20690 20691@item bar_t 20692Specify the bargraph transparency level. Lower value makes the bargraph sharper. 20693Default value is @code{1}. Acceptable range is @code{[0, 1]}. 20694 20695@item timeclamp, tc 20696Specify the transform timeclamp. At low frequency, there is trade-off between 20697accuracy in time domain and frequency domain. If timeclamp is lower, 20698event in time domain is represented more accurately (such as fast bass drum), 20699otherwise event in frequency domain is represented more accurately 20700(such as bass guitar). Acceptable range is @code{[0.002, 1]}. Default value is @code{0.17}. 20701 20702@item attack 20703Set attack time in seconds. The default is @code{0} (disabled). Otherwise, it 20704limits future samples by applying asymmetric windowing in time domain, useful 20705when low latency is required. Accepted range is @code{[0, 1]}. 20706 20707@item basefreq 20708Specify the transform base frequency. Default value is @code{20.01523126408007475}, 20709which is frequency 50 cents below E0. Acceptable range is @code{[10, 100000]}. 20710 20711@item endfreq 20712Specify the transform end frequency. Default value is @code{20495.59681441799654}, 20713which is frequency 50 cents above D#10. Acceptable range is @code{[10, 100000]}. 20714 20715@item coeffclamp 20716This option is deprecated and ignored. 20717 20718@item tlength 20719Specify the transform length in time domain. Use this option to control accuracy 20720trade-off between time domain and frequency domain at every frequency sample. 20721It can contain variables: 20722@table @option 20723@item frequency, freq, f 20724the frequency where it is evaluated 20725@item timeclamp, tc 20726the value of @var{timeclamp} option. 20727@end table 20728Default value is @code{384*tc/(384+tc*f)}. 20729 20730@item count 20731Specify the transform count for every video frame. Default value is @code{6}. 20732Acceptable range is @code{[1, 30]}. 20733 20734@item fcount 20735Specify the transform count for every single pixel. Default value is @code{0}, 20736which makes it computed automatically. Acceptable range is @code{[0, 10]}. 20737 20738@item fontfile 20739Specify font file for use with freetype to draw the axis. If not specified, 20740use embedded font. Note that drawing with font file or embedded font is not 20741implemented with custom @var{basefreq} and @var{endfreq}, use @var{axisfile} 20742option instead. 20743 20744@item font 20745Specify fontconfig pattern. This has lower priority than @var{fontfile}. 20746The : in the pattern may be replaced by | to avoid unnecessary escaping. 20747 20748@item fontcolor 20749Specify font color expression. This is arithmetic expression that should return 20750integer value 0xRRGGBB. It can contain variables: 20751@table @option 20752@item frequency, freq, f 20753the frequency where it is evaluated 20754@item timeclamp, tc 20755the value of @var{timeclamp} option 20756@end table 20757and functions: 20758@table @option 20759@item midi(f) 20760midi number of frequency f, some midi numbers: E0(16), C1(24), C2(36), A4(69) 20761@item r(x), g(x), b(x) 20762red, green, and blue value of intensity x. 20763@end table 20764Default value is @code{st(0, (midi(f)-59.5)/12); 20765st(1, if(between(ld(0),0,1), 0.5-0.5*cos(2*PI*ld(0)), 0)); 20766r(1-ld(1)) + b(ld(1))}. 20767 20768@item axisfile 20769Specify image file to draw the axis. This option override @var{fontfile} and 20770@var{fontcolor} option. 20771 20772@item axis, text 20773Enable/disable drawing text to the axis. If it is set to @code{0}, drawing to 20774the axis is disabled, ignoring @var{fontfile} and @var{axisfile} option. 20775Default value is @code{1}. 20776 20777@item csp 20778Set colorspace. The accepted values are: 20779@table @samp 20780@item unspecified 20781Unspecified (default) 20782 20783@item bt709 20784BT.709 20785 20786@item fcc 20787FCC 20788 20789@item bt470bg 20790BT.470BG or BT.601-6 625 20791 20792@item smpte170m 20793SMPTE-170M or BT.601-6 525 20794 20795@item smpte240m 20796SMPTE-240M 20797 20798@item bt2020ncl 20799BT.2020 with non-constant luminance 20800 20801@end table 20802 20803@item cscheme 20804Set spectrogram color scheme. This is list of floating point values with format 20805@code{left_r|left_g|left_b|right_r|right_g|right_b}. 20806The default is @code{1|0.5|0|0|0.5|1}. 20807 20808@end table 20809 20810@subsection Examples 20811 20812@itemize 20813@item 20814Playing audio while showing the spectrum: 20815@example 20816ffplay -f lavfi 'amovie=a.mp3, asplit [a][out1]; [a] showcqt [out0]' 20817@end example 20818 20819@item 20820Same as above, but with frame rate 30 fps: 20821@example 20822ffplay -f lavfi 'amovie=a.mp3, asplit [a][out1]; [a] showcqt=fps=30:count=5 [out0]' 20823@end example 20824 20825@item 20826Playing at 1280x720: 20827@example 20828ffplay -f lavfi 'amovie=a.mp3, asplit [a][out1]; [a] showcqt=s=1280x720:count=4 [out0]' 20829@end example 20830 20831@item 20832Disable sonogram display: 20833@example 20834sono_h=0 20835@end example 20836 20837@item 20838A1 and its harmonics: A1, A2, (near)E3, A3: 20839@example 20840ffplay -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), 20841 asplit[a][out1]; [a] showcqt [out0]' 20842@end example 20843 20844@item 20845Same as above, but with more accuracy in frequency domain: 20846@example 20847ffplay -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), 20848 asplit[a][out1]; [a] showcqt=timeclamp=0.5 [out0]' 20849@end example 20850 20851@item 20852Custom volume: 20853@example 20854bar_v=10:sono_v=bar_v*a_weighting(f) 20855@end example 20856 20857@item 20858Custom gamma, now spectrum is linear to the amplitude. 20859@example 20860bar_g=2:sono_g=2 20861@end example 20862 20863@item 20864Custom tlength equation: 20865@example 20866tc=0.33:tlength='st(0,0.17); 384*tc / (384 / ld(0) + tc*f /(1-ld(0))) + 384*tc / (tc*f / ld(0) + 384 /(1-ld(0)))' 20867@end example 20868 20869@item 20870Custom fontcolor and fontfile, C-note is colored green, others are colored blue: 20871@example 20872fontcolor='if(mod(floor(midi(f)+0.5),12), 0x0000FF, g(1))':fontfile=myfont.ttf 20873@end example 20874 20875@item 20876Custom font using fontconfig: 20877@example 20878font='Courier New,Monospace,mono|bold' 20879@end example 20880 20881@item 20882Custom frequency range with custom axis using image file: 20883@example 20884axisfile=myaxis.png:basefreq=40:endfreq=10000 20885@end example 20886@end itemize 20887 20888@section showfreqs 20889 20890Convert input audio to video output representing the audio power spectrum. 20891Audio amplitude is on Y-axis while frequency is on X-axis. 20892 20893The filter accepts the following options: 20894 20895@table @option 20896@item size, s 20897Specify size of video. For the syntax of this option, check the 20898@ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}. 20899Default is @code{1024x512}. 20900 20901@item mode 20902Set display mode. 20903This set how each frequency bin will be represented. 20904 20905It accepts the following values: 20906@table @samp 20907@item line 20908@item bar 20909@item dot 20910@end table 20911Default is @code{bar}. 20912 20913@item ascale 20914Set amplitude scale. 20915 20916It accepts the following values: 20917@table @samp 20918@item lin 20919Linear scale. 20920 20921@item sqrt 20922Square root scale. 20923 20924@item cbrt 20925Cubic root scale. 20926 20927@item log 20928Logarithmic scale. 20929@end table 20930Default is @code{log}. 20931 20932@item fscale 20933Set frequency scale. 20934 20935It accepts the following values: 20936@table @samp 20937@item lin 20938Linear scale. 20939 20940@item log 20941Logarithmic scale. 20942 20943@item rlog 20944Reverse logarithmic scale. 20945@end table 20946Default is @code{lin}. 20947 20948@item win_size 20949Set window size. 20950 20951It accepts the following values: 20952@table @samp 20953@item w16 20954@item w32 20955@item w64 20956@item w128 20957@item w256 20958@item w512 20959@item w1024 20960@item w2048 20961@item w4096 20962@item w8192 20963@item w16384 20964@item w32768 20965@item w65536 20966@end table 20967Default is @code{w2048} 20968 20969@item win_func 20970Set windowing function. 20971 20972It accepts the following values: 20973@table @samp 20974@item rect 20975@item bartlett 20976@item hanning 20977@item hamming 20978@item blackman 20979@item welch 20980@item flattop 20981@item bharris 20982@item bnuttall 20983@item bhann 20984@item sine 20985@item nuttall 20986@item lanczos 20987@item gauss 20988@item tukey 20989@item dolph 20990@item cauchy 20991@item parzen 20992@item poisson 20993@item bohman 20994@end table 20995Default is @code{hanning}. 20996 20997@item overlap 20998Set window overlap. In range @code{[0, 1]}. Default is @code{1}, 20999which means optimal overlap for selected window function will be picked. 21000 21001@item averaging 21002Set time averaging. Setting this to 0 will display current maximal peaks. 21003Default is @code{1}, which means time averaging is disabled. 21004 21005@item colors 21006Specify list of colors separated by space or by '|' which will be used to 21007draw channel frequencies. Unrecognized or missing colors will be replaced 21008by white color. 21009 21010@item cmode 21011Set channel display mode. 21012 21013It accepts the following values: 21014@table @samp 21015@item combined 21016@item separate 21017@end table 21018Default is @code{combined}. 21019 21020@item minamp 21021Set minimum amplitude used in @code{log} amplitude scaler. 21022 21023@end table 21024 21025@anchor{showspectrum} 21026@section showspectrum 21027 21028Convert input audio to a video output, representing the audio frequency 21029spectrum. 21030 21031The filter accepts the following options: 21032 21033@table @option 21034@item size, s 21035Specify the video size for the output. For the syntax of this option, check the 21036@ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}. 21037Default value is @code{640x512}. 21038 21039@item slide 21040Specify how the spectrum should slide along the window. 21041 21042It accepts the following values: 21043@table @samp 21044@item replace 21045the samples start again on the left when they reach the right 21046@item scroll 21047the samples scroll from right to left 21048@item fullframe 21049frames are only produced when the samples reach the right 21050@item rscroll 21051the samples scroll from left to right 21052@end table 21053 21054Default value is @code{replace}. 21055 21056@item mode 21057Specify display mode. 21058 21059It accepts the following values: 21060@table @samp 21061@item combined 21062all channels are displayed in the same row 21063@item separate 21064all channels are displayed in separate rows 21065@end table 21066 21067Default value is @samp{combined}. 21068 21069@item color 21070Specify display color mode. 21071 21072It accepts the following values: 21073@table @samp 21074@item channel 21075each channel is displayed in a separate color 21076@item intensity 21077each channel is displayed using the same color scheme 21078@item rainbow 21079each channel is displayed using the rainbow color scheme 21080@item moreland 21081each channel is displayed using the moreland color scheme 21082@item nebulae 21083each channel is displayed using the nebulae color scheme 21084@item fire 21085each channel is displayed using the fire color scheme 21086@item fiery 21087each channel is displayed using the fiery color scheme 21088@item fruit 21089each channel is displayed using the fruit color scheme 21090@item cool 21091each channel is displayed using the cool color scheme 21092@item magma 21093each channel is displayed using the magma color scheme 21094@item green 21095each channel is displayed using the green color scheme 21096@end table 21097 21098Default value is @samp{channel}. 21099 21100@item scale 21101Specify scale used for calculating intensity color values. 21102 21103It accepts the following values: 21104@table @samp 21105@item lin 21106linear 21107@item sqrt 21108square root, default 21109@item cbrt 21110cubic root 21111@item log 21112logarithmic 21113@item 4thrt 211144th root 21115@item 5thrt 211165th root 21117@end table 21118 21119Default value is @samp{sqrt}. 21120 21121@item saturation 21122Set saturation modifier for displayed colors. Negative values provide 21123alternative color scheme. @code{0} is no saturation at all. 21124Saturation must be in [-10.0, 10.0] range. 21125Default value is @code{1}. 21126 21127@item win_func 21128Set window function. 21129 21130It accepts the following values: 21131@table @samp 21132@item rect 21133@item bartlett 21134@item hann 21135@item hanning 21136@item hamming 21137@item blackman 21138@item welch 21139@item flattop 21140@item bharris 21141@item bnuttall 21142@item bhann 21143@item sine 21144@item nuttall 21145@item lanczos 21146@item gauss 21147@item tukey 21148@item dolph 21149@item cauchy 21150@item parzen 21151@item poisson 21152@item bohman 21153@end table 21154 21155Default value is @code{hann}. 21156 21157@item orientation 21158Set orientation of time vs frequency axis. Can be @code{vertical} or 21159@code{horizontal}. Default is @code{vertical}. 21160 21161@item overlap 21162Set ratio of overlap window. Default value is @code{0}. 21163When value is @code{1} overlap is set to recommended size for specific 21164window function currently used. 21165 21166@item gain 21167Set scale gain for calculating intensity color values. 21168Default value is @code{1}. 21169 21170@item data 21171Set which data to display. Can be @code{magnitude}, default or @code{phase}. 21172 21173@item rotation 21174Set color rotation, must be in [-1.0, 1.0] range. 21175Default value is @code{0}. 21176 21177@item start 21178Set start frequency from which to display spectrogram. Default is @code{0}. 21179 21180@item stop 21181Set stop frequency to which to display spectrogram. Default is @code{0}. 21182 21183@item fps 21184Set upper frame rate limit. Default is @code{auto}, unlimited. 21185 21186@item legend 21187Draw time and frequency axes and legends. Default is disabled. 21188@end table 21189 21190The usage is very similar to the showwaves filter; see the examples in that 21191section. 21192 21193@subsection Examples 21194 21195@itemize 21196@item 21197Large window with logarithmic color scaling: 21198@example 21199showspectrum=s=1280x480:scale=log 21200@end example 21201 21202@item 21203Complete example for a colored and sliding spectrum per channel using @command{ffplay}: 21204@example 21205ffplay -f lavfi 'amovie=input.mp3, asplit [a][out1]; 21206 [a] showspectrum=mode=separate:color=intensity:slide=1:scale=cbrt [out0]' 21207@end example 21208@end itemize 21209 21210@section showspectrumpic 21211 21212Convert input audio to a single video frame, representing the audio frequency 21213spectrum. 21214 21215The filter accepts the following options: 21216 21217@table @option 21218@item size, s 21219Specify the video size for the output. For the syntax of this option, check the 21220@ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}. 21221Default value is @code{4096x2048}. 21222 21223@item mode 21224Specify display mode. 21225 21226It accepts the following values: 21227@table @samp 21228@item combined 21229all channels are displayed in the same row 21230@item separate 21231all channels are displayed in separate rows 21232@end table 21233Default value is @samp{combined}. 21234 21235@item color 21236Specify display color mode. 21237 21238It accepts the following values: 21239@table @samp 21240@item channel 21241each channel is displayed in a separate color 21242@item intensity 21243each channel is displayed using the same color scheme 21244@item rainbow 21245each channel is displayed using the rainbow color scheme 21246@item moreland 21247each channel is displayed using the moreland color scheme 21248@item nebulae 21249each channel is displayed using the nebulae color scheme 21250@item fire 21251each channel is displayed using the fire color scheme 21252@item fiery 21253each channel is displayed using the fiery color scheme 21254@item fruit 21255each channel is displayed using the fruit color scheme 21256@item cool 21257each channel is displayed using the cool color scheme 21258@item magma 21259each channel is displayed using the magma color scheme 21260@item green 21261each channel is displayed using the green color scheme 21262@end table 21263Default value is @samp{intensity}. 21264 21265@item scale 21266Specify scale used for calculating intensity color values. 21267 21268It accepts the following values: 21269@table @samp 21270@item lin 21271linear 21272@item sqrt 21273square root, default 21274@item cbrt 21275cubic root 21276@item log 21277logarithmic 21278@item 4thrt 212794th root 21280@item 5thrt 212815th root 21282@end table 21283Default value is @samp{log}. 21284 21285@item saturation 21286Set saturation modifier for displayed colors. Negative values provide 21287alternative color scheme. @code{0} is no saturation at all. 21288Saturation must be in [-10.0, 10.0] range. 21289Default value is @code{1}. 21290 21291@item win_func 21292Set window function. 21293 21294It accepts the following values: 21295@table @samp 21296@item rect 21297@item bartlett 21298@item hann 21299@item hanning 21300@item hamming 21301@item blackman 21302@item welch 21303@item flattop 21304@item bharris 21305@item bnuttall 21306@item bhann 21307@item sine 21308@item nuttall 21309@item lanczos 21310@item gauss 21311@item tukey 21312@item dolph 21313@item cauchy 21314@item parzen 21315@item poisson 21316@item bohman 21317@end table 21318Default value is @code{hann}. 21319 21320@item orientation 21321Set orientation of time vs frequency axis. Can be @code{vertical} or 21322@code{horizontal}. Default is @code{vertical}. 21323 21324@item gain 21325Set scale gain for calculating intensity color values. 21326Default value is @code{1}. 21327 21328@item legend 21329Draw time and frequency axes and legends. Default is enabled. 21330 21331@item rotation 21332Set color rotation, must be in [-1.0, 1.0] range. 21333Default value is @code{0}. 21334 21335@item start 21336Set start frequency from which to display spectrogram. Default is @code{0}. 21337 21338@item stop 21339Set stop frequency to which to display spectrogram. Default is @code{0}. 21340@end table 21341 21342@subsection Examples 21343 21344@itemize 21345@item 21346Extract an audio spectrogram of a whole audio track 21347in a 1024x1024 picture using @command{ffmpeg}: 21348@example 21349ffmpeg -i audio.flac -lavfi showspectrumpic=s=1024x1024 spectrogram.png 21350@end example 21351@end itemize 21352 21353@section showvolume 21354 21355Convert input audio volume to a video output. 21356 21357The filter accepts the following options: 21358 21359@table @option 21360@item rate, r 21361Set video rate. 21362 21363@item b 21364Set border width, allowed range is [0, 5]. Default is 1. 21365 21366@item w 21367Set channel width, allowed range is [80, 8192]. Default is 400. 21368 21369@item h 21370Set channel height, allowed range is [1, 900]. Default is 20. 21371 21372@item f 21373Set fade, allowed range is [0, 1]. Default is 0.95. 21374 21375@item c 21376Set volume color expression. 21377 21378The expression can use the following variables: 21379 21380@table @option 21381@item VOLUME 21382Current max volume of channel in dB. 21383 21384@item PEAK 21385Current peak. 21386 21387@item CHANNEL 21388Current channel number, starting from 0. 21389@end table 21390 21391@item t 21392If set, displays channel names. Default is enabled. 21393 21394@item v 21395If set, displays volume values. Default is enabled. 21396 21397@item o 21398Set orientation, can be horizontal: @code{h} or vertical: @code{v}, 21399default is @code{h}. 21400 21401@item s 21402Set step size, allowed range is [0, 5]. Default is 0, which means 21403step is disabled. 21404 21405@item p 21406Set background opacity, allowed range is [0, 1]. Default is 0. 21407 21408@item m 21409Set metering mode, can be peak: @code{p} or rms: @code{r}, 21410default is @code{p}. 21411 21412@item ds 21413Set display scale, can be linear: @code{lin} or log: @code{log}, 21414default is @code{lin}. 21415 21416@item dm 21417In second. 21418If set to > 0., display a line for the max level 21419in the previous seconds. 21420default is disabled: @code{0.} 21421 21422@item dmc 21423The color of the max line. Use when @code{dm} option is set to > 0. 21424default is: @code{orange} 21425@end table 21426 21427@section showwaves 21428 21429Convert input audio to a video output, representing the samples waves. 21430 21431The filter accepts the following options: 21432 21433@table @option 21434@item size, s 21435Specify the video size for the output. For the syntax of this option, check the 21436@ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}. 21437Default value is @code{600x240}. 21438 21439@item mode 21440Set display mode. 21441 21442Available values are: 21443@table @samp 21444@item point 21445Draw a point for each sample. 21446 21447@item line 21448Draw a vertical line for each sample. 21449 21450@item p2p 21451Draw a point for each sample and a line between them. 21452 21453@item cline 21454Draw a centered vertical line for each sample. 21455@end table 21456 21457Default value is @code{point}. 21458 21459@item n 21460Set the number of samples which are printed on the same column. A 21461larger value will decrease the frame rate. Must be a positive 21462integer. This option can be set only if the value for @var{rate} 21463is not explicitly specified. 21464 21465@item rate, r 21466Set the (approximate) output frame rate. This is done by setting the 21467option @var{n}. Default value is "25". 21468 21469@item split_channels 21470Set if channels should be drawn separately or overlap. Default value is 0. 21471 21472@item colors 21473Set colors separated by '|' which are going to be used for drawing of each channel. 21474 21475@item scale 21476Set amplitude scale. 21477 21478Available values are: 21479@table @samp 21480@item lin 21481Linear. 21482 21483@item log 21484Logarithmic. 21485 21486@item sqrt 21487Square root. 21488 21489@item cbrt 21490Cubic root. 21491@end table 21492 21493Default is linear. 21494 21495@item draw 21496Set the draw mode. This is mostly useful to set for high @var{n}. 21497 21498Available values are: 21499@table @samp 21500@item scale 21501Scale pixel values for each drawn sample. 21502 21503@item full 21504Draw every sample directly. 21505@end table 21506 21507Default value is @code{scale}. 21508@end table 21509 21510@subsection Examples 21511 21512@itemize 21513@item 21514Output the input file audio and the corresponding video representation 21515at the same time: 21516@example 21517amovie=a.mp3,asplit[out0],showwaves[out1] 21518@end example 21519 21520@item 21521Create a synthetic signal and show it with showwaves, forcing a 21522frame rate of 30 frames per second: 21523@example 21524aevalsrc=sin(1*2*PI*t)*sin(880*2*PI*t):cos(2*PI*200*t),asplit[out0],showwaves=r=30[out1] 21525@end example 21526@end itemize 21527 21528@section showwavespic 21529 21530Convert input audio to a single video frame, representing the samples waves. 21531 21532The filter accepts the following options: 21533 21534@table @option 21535@item size, s 21536Specify the video size for the output. For the syntax of this option, check the 21537@ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}. 21538Default value is @code{600x240}. 21539 21540@item split_channels 21541Set if channels should be drawn separately or overlap. Default value is 0. 21542 21543@item colors 21544Set colors separated by '|' which are going to be used for drawing of each channel. 21545 21546@item scale 21547Set amplitude scale. 21548 21549Available values are: 21550@table @samp 21551@item lin 21552Linear. 21553 21554@item log 21555Logarithmic. 21556 21557@item sqrt 21558Square root. 21559 21560@item cbrt 21561Cubic root. 21562@end table 21563 21564Default is linear. 21565@end table 21566 21567@subsection Examples 21568 21569@itemize 21570@item 21571Extract a channel split representation of the wave form of a whole audio track 21572in a 1024x800 picture using @command{ffmpeg}: 21573@example 21574ffmpeg -i audio.flac -lavfi showwavespic=split_channels=1:s=1024x800 waveform.png 21575@end example 21576@end itemize 21577 21578@section sidedata, asidedata 21579 21580Delete frame side data, or select frames based on it. 21581 21582This filter accepts the following options: 21583 21584@table @option 21585@item mode 21586Set mode of operation of the filter. 21587 21588Can be one of the following: 21589 21590@table @samp 21591@item select 21592Select every frame with side data of @code{type}. 21593 21594@item delete 21595Delete side data of @code{type}. If @code{type} is not set, delete all side 21596data in the frame. 21597 21598@end table 21599 21600@item type 21601Set side data type used with all modes. Must be set for @code{select} mode. For 21602the list of frame side data types, refer to the @code{AVFrameSideDataType} enum 21603in @file{libavutil/frame.h}. For example, to choose 21604@code{AV_FRAME_DATA_PANSCAN} side data, you must specify @code{PANSCAN}. 21605 21606@end table 21607 21608@section spectrumsynth 21609 21610Sythesize audio from 2 input video spectrums, first input stream represents 21611magnitude across time and second represents phase across time. 21612The filter will transform from frequency domain as displayed in videos back 21613to time domain as presented in audio output. 21614 21615This filter is primarily created for reversing processed @ref{showspectrum} 21616filter outputs, but can synthesize sound from other spectrograms too. 21617But in such case results are going to be poor if the phase data is not 21618available, because in such cases phase data need to be recreated, usually 21619its just recreated from random noise. 21620For best results use gray only output (@code{channel} color mode in 21621@ref{showspectrum} filter) and @code{log} scale for magnitude video and 21622@code{lin} scale for phase video. To produce phase, for 2nd video, use 21623@code{data} option. Inputs videos should generally use @code{fullframe} 21624slide mode as that saves resources needed for decoding video. 21625 21626The filter accepts the following options: 21627 21628@table @option 21629@item sample_rate 21630Specify sample rate of output audio, the sample rate of audio from which 21631spectrum was generated may differ. 21632 21633@item channels 21634Set number of channels represented in input video spectrums. 21635 21636@item scale 21637Set scale which was used when generating magnitude input spectrum. 21638Can be @code{lin} or @code{log}. Default is @code{log}. 21639 21640@item slide 21641Set slide which was used when generating inputs spectrums. 21642Can be @code{replace}, @code{scroll}, @code{fullframe} or @code{rscroll}. 21643Default is @code{fullframe}. 21644 21645@item win_func 21646Set window function used for resynthesis. 21647 21648@item overlap 21649Set window overlap. In range @code{[0, 1]}. Default is @code{1}, 21650which means optimal overlap for selected window function will be picked. 21651 21652@item orientation 21653Set orientation of input videos. Can be @code{vertical} or @code{horizontal}. 21654Default is @code{vertical}. 21655@end table 21656 21657@subsection Examples 21658 21659@itemize 21660@item 21661First create magnitude and phase videos from audio, assuming audio is stereo with 44100 sample rate, 21662then resynthesize videos back to audio with spectrumsynth: 21663@example 21664ffmpeg -i input.flac -lavfi showspectrum=mode=separate:scale=log:overlap=0.875:color=channel:slide=fullframe:data=magnitude -an -c:v rawvideo magnitude.nut 21665ffmpeg -i input.flac -lavfi showspectrum=mode=separate:scale=lin:overlap=0.875:color=channel:slide=fullframe:data=phase -an -c:v rawvideo phase.nut 21666ffmpeg -i magnitude.nut -i phase.nut -lavfi spectrumsynth=channels=2:sample_rate=44100:win_func=hann:overlap=0.875:slide=fullframe output.flac 21667@end example 21668@end itemize 21669 21670@section split, asplit 21671 21672Split input into several identical outputs. 21673 21674@code{asplit} works with audio input, @code{split} with video. 21675 21676The filter accepts a single parameter which specifies the number of outputs. If 21677unspecified, it defaults to 2. 21678 21679@subsection Examples 21680 21681@itemize 21682@item 21683Create two separate outputs from the same input: 21684@example 21685[in] split [out0][out1] 21686@end example 21687 21688@item 21689To create 3 or more outputs, you need to specify the number of 21690outputs, like in: 21691@example 21692[in] asplit=3 [out0][out1][out2] 21693@end example 21694 21695@item 21696Create two separate outputs from the same input, one cropped and 21697one padded: 21698@example 21699[in] split [splitout1][splitout2]; 21700[splitout1] crop=100:100:0:0 [cropout]; 21701[splitout2] pad=200:200:100:100 [padout]; 21702@end example 21703 21704@item 21705Create 5 copies of the input audio with @command{ffmpeg}: 21706@example 21707ffmpeg -i INPUT -filter_complex asplit=5 OUTPUT 21708@end example 21709@end itemize 21710 21711@section zmq, azmq 21712 21713Receive commands sent through a libzmq client, and forward them to 21714filters in the filtergraph. 21715 21716@code{zmq} and @code{azmq} work as a pass-through filters. @code{zmq} 21717must be inserted between two video filters, @code{azmq} between two 21718audio filters. Both are capable to send messages to any filter type. 21719 21720To enable these filters you need to install the libzmq library and 21721headers and configure FFmpeg with @code{--enable-libzmq}. 21722 21723For more information about libzmq see: 21724@url{http://www.zeromq.org/} 21725 21726The @code{zmq} and @code{azmq} filters work as a libzmq server, which 21727receives messages sent through a network interface defined by the 21728@option{bind_address} (or the abbreviation "@option{b}") option. 21729Default value of this option is @file{tcp://localhost:5555}. You may 21730want to alter this value to your needs, but do not forget to escape any 21731':' signs (see @ref{filtergraph escaping}). 21732 21733The received message must be in the form: 21734@example 21735@var{TARGET} @var{COMMAND} [@var{ARG}] 21736@end example 21737 21738@var{TARGET} specifies the target of the command, usually the name of 21739the filter class or a specific filter instance name. The default 21740filter instance name uses the pattern @samp{Parsed_<filter_name>_<index>}, 21741but you can override this by using the @samp{filter_name@@id} syntax 21742(see @ref{Filtergraph syntax}). 21743 21744@var{COMMAND} specifies the name of the command for the target filter. 21745 21746@var{ARG} is optional and specifies the optional argument list for the 21747given @var{COMMAND}. 21748 21749Upon reception, the message is processed and the corresponding command 21750is injected into the filtergraph. Depending on the result, the filter 21751will send a reply to the client, adopting the format: 21752@example 21753@var{ERROR_CODE} @var{ERROR_REASON} 21754@var{MESSAGE} 21755@end example 21756 21757@var{MESSAGE} is optional. 21758 21759@subsection Examples 21760 21761Look at @file{tools/zmqsend} for an example of a zmq client which can 21762be used to send commands processed by these filters. 21763 21764Consider the following filtergraph generated by @command{ffplay}. 21765In this example the last overlay filter has an instance name. All other 21766filters will have default instance names. 21767 21768@example 21769ffplay -dumpgraph 1 -f lavfi " 21770color=s=100x100:c=red [l]; 21771color=s=100x100:c=blue [r]; 21772nullsrc=s=200x100, zmq [bg]; 21773[bg][l] overlay [bg+l]; 21774[bg+l][r] overlay@@my=x=100 " 21775@end example 21776 21777To change the color of the left side of the video, the following 21778command can be used: 21779@example 21780echo Parsed_color_0 c yellow | tools/zmqsend 21781@end example 21782 21783To change the right side: 21784@example 21785echo Parsed_color_1 c pink | tools/zmqsend 21786@end example 21787 21788To change the position of the right side: 21789@example 21790echo overlay@@my x 150 | tools/zmqsend 21791@end example 21792 21793 21794@c man end MULTIMEDIA FILTERS 21795 21796@chapter Multimedia Sources 21797@c man begin MULTIMEDIA SOURCES 21798 21799Below is a description of the currently available multimedia sources. 21800 21801@section amovie 21802 21803This is the same as @ref{movie} source, except it selects an audio 21804stream by default. 21805 21806@anchor{movie} 21807@section movie 21808 21809Read audio and/or video stream(s) from a movie container. 21810 21811It accepts the following parameters: 21812 21813@table @option 21814@item filename 21815The name of the resource to read (not necessarily a file; it can also be a 21816device or a stream accessed through some protocol). 21817 21818@item format_name, f 21819Specifies the format assumed for the movie to read, and can be either 21820the name of a container or an input device. If not specified, the 21821format is guessed from @var{movie_name} or by probing. 21822 21823@item seek_point, sp 21824Specifies the seek point in seconds. The frames will be output 21825starting from this seek point. The parameter is evaluated with 21826@code{av_strtod}, so the numerical value may be suffixed by an IS 21827postfix. The default value is "0". 21828 21829@item streams, s 21830Specifies the streams to read. Several streams can be specified, 21831separated by "+". The source will then have as many outputs, in the 21832same order. The syntax is explained in the @ref{Stream specifiers,,"Stream specifiers" 21833section in the ffmpeg manual,ffmpeg}. Two special names, "dv" and "da" specify 21834respectively the default (best suited) video and audio stream. Default 21835is "dv", or "da" if the filter is called as "amovie". 21836 21837@item stream_index, si 21838Specifies the index of the video stream to read. If the value is -1, 21839the most suitable video stream will be automatically selected. The default 21840value is "-1". Deprecated. If the filter is called "amovie", it will select 21841audio instead of video. 21842 21843@item loop 21844Specifies how many times to read the stream in sequence. 21845If the value is 0, the stream will be looped infinitely. 21846Default value is "1". 21847 21848Note that when the movie is looped the source timestamps are not 21849changed, so it will generate non monotonically increasing timestamps. 21850 21851@item discontinuity 21852Specifies the time difference between frames above which the point is 21853considered a timestamp discontinuity which is removed by adjusting the later 21854timestamps. 21855@end table 21856 21857It allows overlaying a second video on top of the main input of 21858a filtergraph, as shown in this graph: 21859@example 21860input -----------> deltapts0 --> overlay --> output 21861 ^ 21862 | 21863movie --> scale--> deltapts1 -------+ 21864@end example 21865@subsection Examples 21866 21867@itemize 21868@item 21869Skip 3.2 seconds from the start of the AVI file in.avi, and overlay it 21870on top of the input labelled "in": 21871@example 21872movie=in.avi:seek_point=3.2, scale=180:-1, setpts=PTS-STARTPTS [over]; 21873[in] setpts=PTS-STARTPTS [main]; 21874[main][over] overlay=16:16 [out] 21875@end example 21876 21877@item 21878Read from a video4linux2 device, and overlay it on top of the input 21879labelled "in": 21880@example 21881movie=/dev/video0:f=video4linux2, scale=180:-1, setpts=PTS-STARTPTS [over]; 21882[in] setpts=PTS-STARTPTS [main]; 21883[main][over] overlay=16:16 [out] 21884@end example 21885 21886@item 21887Read the first video stream and the audio stream with id 0x81 from 21888dvd.vob; the video is connected to the pad named "video" and the audio is 21889connected to the pad named "audio": 21890@example 21891movie=dvd.vob:s=v:0+#0x81 [video] [audio] 21892@end example 21893@end itemize 21894 21895@subsection Commands 21896 21897Both movie and amovie support the following commands: 21898@table @option 21899@item seek 21900Perform seek using "av_seek_frame". 21901The syntax is: seek @var{stream_index}|@var{timestamp}|@var{flags} 21902@itemize 21903@item 21904@var{stream_index}: If stream_index is -1, a default 21905stream is selected, and @var{timestamp} is automatically converted 21906from AV_TIME_BASE units to the stream specific time_base. 21907@item 21908@var{timestamp}: Timestamp in AVStream.time_base units 21909or, if no stream is specified, in AV_TIME_BASE units. 21910@item 21911@var{flags}: Flags which select direction and seeking mode. 21912@end itemize 21913 21914@item get_duration 21915Get movie duration in AV_TIME_BASE units. 21916 21917@end table 21918 21919@c man end MULTIMEDIA SOURCES 21920