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{commands} 316@chapter Changing options at runtime with a command 317 318Some options can be changed during the operation of the filter using 319a command. These options are marked 'T' on the output of 320@command{ffmpeg} @option{-h filter=<name of filter>}. 321The name of the command is the name of the option and the argument is 322the new value. 323 324@anchor{framesync} 325@chapter Options for filters with several inputs (framesync) 326@c man begin OPTIONS FOR FILTERS WITH SEVERAL INPUTS 327 328Some filters with several inputs support a common set of options. 329These options can only be set by name, not with the short notation. 330 331@table @option 332@item eof_action 333The action to take when EOF is encountered on the secondary input; it accepts 334one of the following values: 335 336@table @option 337@item repeat 338Repeat the last frame (the default). 339@item endall 340End both streams. 341@item pass 342Pass the main input through. 343@end table 344 345@item shortest 346If set to 1, force the output to terminate when the shortest input 347terminates. Default value is 0. 348 349@item repeatlast 350If set to 1, force the filter to extend the last frame of secondary streams 351until the end of the primary stream. A value of 0 disables this behavior. 352Default value is 1. 353@end table 354 355@c man end OPTIONS FOR FILTERS WITH SEVERAL INPUTS 356 357@chapter Audio Filters 358@c man begin AUDIO FILTERS 359 360When you configure your FFmpeg build, you can disable any of the 361existing filters using @code{--disable-filters}. 362The configure output will show the audio filters included in your 363build. 364 365Below is a description of the currently available audio filters. 366 367@section acompressor 368 369A compressor is mainly used to reduce the dynamic range of a signal. 370Especially modern music is mostly compressed at a high ratio to 371improve the overall loudness. It's done to get the highest attention 372of a listener, "fatten" the sound and bring more "power" to the track. 373If a signal is compressed too much it may sound dull or "dead" 374afterwards or it may start to "pump" (which could be a powerful effect 375but can also destroy a track completely). 376The right compression is the key to reach a professional sound and is 377the high art of mixing and mastering. Because of its complex settings 378it may take a long time to get the right feeling for this kind of effect. 379 380Compression is done by detecting the volume above a chosen level 381@code{threshold} and dividing it by the factor set with @code{ratio}. 382So if you set the threshold to -12dB and your signal reaches -6dB a ratio 383of 2:1 will result in a signal at -9dB. Because an exact manipulation of 384the signal would cause distortion of the waveform the reduction can be 385levelled over the time. This is done by setting "Attack" and "Release". 386@code{attack} determines how long the signal has to rise above the threshold 387before any reduction will occur and @code{release} sets the time the signal 388has to fall below the threshold to reduce the reduction again. Shorter signals 389than the chosen attack time will be left untouched. 390The overall reduction of the signal can be made up afterwards with the 391@code{makeup} setting. So compressing the peaks of a signal about 6dB and 392raising the makeup to this level results in a signal twice as loud than the 393source. To gain a softer entry in the compression the @code{knee} flattens the 394hard edge at the threshold in the range of the chosen decibels. 395 396The filter accepts the following options: 397 398@table @option 399@item level_in 400Set input gain. Default is 1. Range is between 0.015625 and 64. 401 402@item mode 403Set mode of compressor operation. Can be @code{upward} or @code{downward}. 404Default is @code{downward}. 405 406@item threshold 407If a signal of stream rises above this level it will affect the gain 408reduction. 409By default it is 0.125. Range is between 0.00097563 and 1. 410 411@item ratio 412Set a ratio by which the signal is reduced. 1:2 means that if the level 413rose 4dB above the threshold, it will be only 2dB above after the reduction. 414Default is 2. Range is between 1 and 20. 415 416@item attack 417Amount of milliseconds the signal has to rise above the threshold before gain 418reduction starts. Default is 20. Range is between 0.01 and 2000. 419 420@item release 421Amount of milliseconds the signal has to fall below the threshold before 422reduction is decreased again. Default is 250. Range is between 0.01 and 9000. 423 424@item makeup 425Set the amount by how much signal will be amplified after processing. 426Default is 1. Range is from 1 to 64. 427 428@item knee 429Curve the sharp knee around the threshold to enter gain reduction more softly. 430Default is 2.82843. Range is between 1 and 8. 431 432@item link 433Choose if the @code{average} level between all channels of input stream 434or the louder(@code{maximum}) channel of input stream affects the 435reduction. Default is @code{average}. 436 437@item detection 438Should the exact signal be taken in case of @code{peak} or an RMS one in case 439of @code{rms}. Default is @code{rms} which is mostly smoother. 440 441@item mix 442How much to use compressed signal in output. Default is 1. 443Range is between 0 and 1. 444@end table 445 446@subsection Commands 447 448This filter supports the all above options as @ref{commands}. 449 450@section acontrast 451Simple audio dynamic range compression/expansion filter. 452 453The filter accepts the following options: 454 455@table @option 456@item contrast 457Set contrast. Default is 33. Allowed range is between 0 and 100. 458@end table 459 460@section acopy 461 462Copy the input audio source unchanged to the output. This is mainly useful for 463testing purposes. 464 465@section acrossfade 466 467Apply cross fade from one input audio stream to another input audio stream. 468The cross fade is applied for specified duration near the end of first stream. 469 470The filter accepts the following options: 471 472@table @option 473@item nb_samples, ns 474Specify the number of samples for which the cross fade effect has to last. 475At the end of the cross fade effect the first input audio will be completely 476silent. Default is 44100. 477 478@item duration, d 479Specify the duration of the cross fade effect. See 480@ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils} 481for the accepted syntax. 482By default the duration is determined by @var{nb_samples}. 483If set this option is used instead of @var{nb_samples}. 484 485@item overlap, o 486Should first stream end overlap with second stream start. Default is enabled. 487 488@item curve1 489Set curve for cross fade transition for first stream. 490 491@item curve2 492Set curve for cross fade transition for second stream. 493 494For description of available curve types see @ref{afade} filter description. 495@end table 496 497@subsection Examples 498 499@itemize 500@item 501Cross fade from one input to another: 502@example 503ffmpeg -i first.flac -i second.flac -filter_complex acrossfade=d=10:c1=exp:c2=exp output.flac 504@end example 505 506@item 507Cross fade from one input to another but without overlapping: 508@example 509ffmpeg -i first.flac -i second.flac -filter_complex acrossfade=d=10:o=0:c1=exp:c2=exp output.flac 510@end example 511@end itemize 512 513@section acrossover 514Split audio stream into several bands. 515 516This filter splits audio stream into two or more frequency ranges. 517Summing all streams back will give flat output. 518 519The filter accepts the following options: 520 521@table @option 522@item split 523Set split frequencies. Those must be positive and increasing. 524 525@item order 526Set filter order for each band split. This controls filter roll-off or steepness 527of filter transfer function. 528Available values are: 529 530@table @samp 531@item 2nd 53212 dB per octave. 533@item 4th 53424 dB per octave. 535@item 6th 53636 dB per octave. 537@item 8th 53848 dB per octave. 539@item 10th 54060 dB per octave. 541@item 12th 54272 dB per octave. 543@item 14th 54484 dB per octave. 545@item 16th 54696 dB per octave. 547@item 18th 548108 dB per octave. 549@item 20th 550120 dB per octave. 551@end table 552 553Default is @var{4th}. 554 555@item level 556Set input gain level. Allowed range is from 0 to 1. Default value is 1. 557 558@item gains 559Set output gain for each band. Default value is 1 for all bands. 560@end table 561 562@subsection Examples 563 564@itemize 565@item 566Split input audio stream into two bands (low and high) with split frequency of 1500 Hz, 567each band will be in separate stream: 568@example 569ffmpeg -i in.flac -filter_complex 'acrossover=split=1500[LOW][HIGH]' -map '[LOW]' low.wav -map '[HIGH]' high.wav 570@end example 571 572@item 573Same as above, but with higher filter order: 574@example 575ffmpeg -i in.flac -filter_complex 'acrossover=split=1500:order=8th[LOW][HIGH]' -map '[LOW]' low.wav -map '[HIGH]' high.wav 576@end example 577 578@item 579Same as above, but also with additional middle band (frequencies between 1500 and 8000): 580@example 581ffmpeg -i in.flac -filter_complex 'acrossover=split=1500 8000:order=8th[LOW][MID][HIGH]' -map '[LOW]' low.wav -map '[MID]' mid.wav -map '[HIGH]' high.wav 582@end example 583@end itemize 584 585@section acrusher 586 587Reduce audio bit resolution. 588 589This filter is bit crusher with enhanced functionality. A bit crusher 590is used to audibly reduce number of bits an audio signal is sampled 591with. This doesn't change the bit depth at all, it just produces the 592effect. Material reduced in bit depth sounds more harsh and "digital". 593This filter is able to even round to continuous values instead of discrete 594bit depths. 595Additionally it has a D/C offset which results in different crushing of 596the lower and the upper half of the signal. 597An Anti-Aliasing setting is able to produce "softer" crushing sounds. 598 599Another feature of this filter is the logarithmic mode. 600This setting switches from linear distances between bits to logarithmic ones. 601The result is a much more "natural" sounding crusher which doesn't gate low 602signals for example. The human ear has a logarithmic perception, 603so this kind of crushing is much more pleasant. 604Logarithmic crushing is also able to get anti-aliased. 605 606The filter accepts the following options: 607 608@table @option 609@item level_in 610Set level in. 611 612@item level_out 613Set level out. 614 615@item bits 616Set bit reduction. 617 618@item mix 619Set mixing amount. 620 621@item mode 622Can be linear: @code{lin} or logarithmic: @code{log}. 623 624@item dc 625Set DC. 626 627@item aa 628Set anti-aliasing. 629 630@item samples 631Set sample reduction. 632 633@item lfo 634Enable LFO. By default disabled. 635 636@item lforange 637Set LFO range. 638 639@item lforate 640Set LFO rate. 641@end table 642 643@subsection Commands 644 645This filter supports the all above options as @ref{commands}. 646 647@section acue 648 649Delay audio filtering until a given wallclock timestamp. See the @ref{cue} 650filter. 651 652@section adeclick 653Remove impulsive noise from input audio. 654 655Samples detected as impulsive noise are replaced by interpolated samples using 656autoregressive modelling. 657 658@table @option 659@item window, w 660Set window size, in milliseconds. Allowed range is from @code{10} to 661@code{100}. Default value is @code{55} milliseconds. 662This sets size of window which will be processed at once. 663 664@item overlap, o 665Set window overlap, in percentage of window size. Allowed range is from 666@code{50} to @code{95}. Default value is @code{75} percent. 667Setting this to a very high value increases impulsive noise removal but makes 668whole process much slower. 669 670@item arorder, a 671Set autoregression order, in percentage of window size. Allowed range is from 672@code{0} to @code{25}. Default value is @code{2} percent. This option also 673controls quality of interpolated samples using neighbour good samples. 674 675@item threshold, t 676Set threshold value. Allowed range is from @code{1} to @code{100}. 677Default value is @code{2}. 678This controls the strength of impulsive noise which is going to be removed. 679The lower value, the more samples will be detected as impulsive noise. 680 681@item burst, b 682Set burst fusion, in percentage of window size. Allowed range is @code{0} to 683@code{10}. Default value is @code{2}. 684If any two samples detected as noise are spaced less than this value then any 685sample between those two samples will be also detected as noise. 686 687@item method, m 688Set overlap method. 689 690It accepts the following values: 691@table @option 692@item add, a 693Select overlap-add method. Even not interpolated samples are slightly 694changed with this method. 695 696@item save, s 697Select overlap-save method. Not interpolated samples remain unchanged. 698@end table 699 700Default value is @code{a}. 701@end table 702 703@section adeclip 704Remove clipped samples from input audio. 705 706Samples detected as clipped are replaced by interpolated samples using 707autoregressive modelling. 708 709@table @option 710@item window, w 711Set window size, in milliseconds. Allowed range is from @code{10} to @code{100}. 712Default value is @code{55} milliseconds. 713This sets size of window which will be processed at once. 714 715@item overlap, o 716Set window overlap, in percentage of window size. Allowed range is from @code{50} 717to @code{95}. Default value is @code{75} percent. 718 719@item arorder, a 720Set autoregression order, in percentage of window size. Allowed range is from 721@code{0} to @code{25}. Default value is @code{8} percent. This option also controls 722quality of interpolated samples using neighbour good samples. 723 724@item threshold, t 725Set threshold value. Allowed range is from @code{1} to @code{100}. 726Default value is @code{10}. Higher values make clip detection less aggressive. 727 728@item hsize, n 729Set size of histogram used to detect clips. Allowed range is from @code{100} to @code{9999}. 730Default value is @code{1000}. Higher values make clip detection less aggressive. 731 732@item method, m 733Set overlap method. 734 735It accepts the following values: 736@table @option 737@item add, a 738Select overlap-add method. Even not interpolated samples are slightly changed 739with this method. 740 741@item save, s 742Select overlap-save method. Not interpolated samples remain unchanged. 743@end table 744 745Default value is @code{a}. 746@end table 747 748@section adelay 749 750Delay one or more audio channels. 751 752Samples in delayed channel are filled with silence. 753 754The filter accepts the following option: 755 756@table @option 757@item delays 758Set list of delays in milliseconds for each channel separated by '|'. 759Unused delays will be silently ignored. If number of given delays is 760smaller than number of channels all remaining channels will not be delayed. 761If you want to delay exact number of samples, append 'S' to number. 762If you want instead to delay in seconds, append 's' to number. 763 764@item all 765Use last set delay for all remaining channels. By default is disabled. 766This option if enabled changes how option @code{delays} is interpreted. 767@end table 768 769@subsection Examples 770 771@itemize 772@item 773Delay first channel by 1.5 seconds, the third channel by 0.5 seconds and leave 774the second channel (and any other channels that may be present) unchanged. 775@example 776adelay=1500|0|500 777@end example 778 779@item 780Delay second channel by 500 samples, the third channel by 700 samples and leave 781the first channel (and any other channels that may be present) unchanged. 782@example 783adelay=0|500S|700S 784@end example 785 786@item 787Delay all channels by same number of samples: 788@example 789adelay=delays=64S:all=1 790@end example 791@end itemize 792 793@section adenorm 794Remedy denormals in audio by adding extremely low-level noise. 795 796This filter shall be placed before any filter that can produce denormals. 797 798A description of the accepted parameters follows. 799 800@table @option 801@item level 802Set level of added noise in dB. Default is @code{-351}. 803Allowed range is from -451 to -90. 804 805@item type 806Set type of added noise. 807 808@table @option 809@item dc 810Add DC signal. 811@item ac 812Add AC signal. 813@item square 814Add square signal. 815@item pulse 816Add pulse signal. 817@end table 818 819Default is @code{dc}. 820@end table 821 822@subsection Commands 823 824This filter supports the all above options as @ref{commands}. 825 826@section aderivative, aintegral 827 828Compute derivative/integral of audio stream. 829 830Applying both filters one after another produces original audio. 831 832@section aecho 833 834Apply echoing to the input audio. 835 836Echoes are reflected sound and can occur naturally amongst mountains 837(and sometimes large buildings) when talking or shouting; digital echo 838effects emulate this behaviour and are often used to help fill out the 839sound of a single instrument or vocal. The time difference between the 840original signal and the reflection is the @code{delay}, and the 841loudness of the reflected signal is the @code{decay}. 842Multiple echoes can have different delays and decays. 843 844A description of the accepted parameters follows. 845 846@table @option 847@item in_gain 848Set input gain of reflected signal. Default is @code{0.6}. 849 850@item out_gain 851Set output gain of reflected signal. Default is @code{0.3}. 852 853@item delays 854Set list of time intervals in milliseconds between original signal and reflections 855separated by '|'. Allowed range for each @code{delay} is @code{(0 - 90000.0]}. 856Default is @code{1000}. 857 858@item decays 859Set list of loudness of reflected signals separated by '|'. 860Allowed range for each @code{decay} is @code{(0 - 1.0]}. 861Default is @code{0.5}. 862@end table 863 864@subsection Examples 865 866@itemize 867@item 868Make it sound as if there are twice as many instruments as are actually playing: 869@example 870aecho=0.8:0.88:60:0.4 871@end example 872 873@item 874If delay is very short, then it sounds like a (metallic) robot playing music: 875@example 876aecho=0.8:0.88:6:0.4 877@end example 878 879@item 880A longer delay will sound like an open air concert in the mountains: 881@example 882aecho=0.8:0.9:1000:0.3 883@end example 884 885@item 886Same as above but with one more mountain: 887@example 888aecho=0.8:0.9:1000|1800:0.3|0.25 889@end example 890@end itemize 891 892@section aemphasis 893Audio emphasis filter creates or restores material directly taken from LPs or 894emphased CDs with different filter curves. E.g. to store music on vinyl the 895signal has to be altered by a filter first to even out the disadvantages of 896this recording medium. 897Once the material is played back the inverse filter has to be applied to 898restore the distortion of the frequency response. 899 900The filter accepts the following options: 901 902@table @option 903@item level_in 904Set input gain. 905 906@item level_out 907Set output gain. 908 909@item mode 910Set filter mode. For restoring material use @code{reproduction} mode, otherwise 911use @code{production} mode. Default is @code{reproduction} mode. 912 913@item type 914Set filter type. Selects medium. Can be one of the following: 915 916@table @option 917@item col 918select Columbia. 919@item emi 920select EMI. 921@item bsi 922select BSI (78RPM). 923@item riaa 924select RIAA. 925@item cd 926select Compact Disc (CD). 927@item 50fm 928select 50µs (FM). 929@item 75fm 930select 75µs (FM). 931@item 50kf 932select 50µs (FM-KF). 933@item 75kf 934select 75µs (FM-KF). 935@end table 936@end table 937 938@subsection Commands 939 940This filter supports the all above options as @ref{commands}. 941 942@section aeval 943 944Modify an audio signal according to the specified expressions. 945 946This filter accepts one or more expressions (one for each channel), 947which are evaluated and used to modify a corresponding audio signal. 948 949It accepts the following parameters: 950 951@table @option 952@item exprs 953Set the '|'-separated expressions list for each separate channel. If 954the number of input channels is greater than the number of 955expressions, the last specified expression is used for the remaining 956output channels. 957 958@item channel_layout, c 959Set output channel layout. If not specified, the channel layout is 960specified by the number of expressions. If set to @samp{same}, it will 961use by default the same input channel layout. 962@end table 963 964Each expression in @var{exprs} can contain the following constants and functions: 965 966@table @option 967@item ch 968channel number of the current expression 969 970@item n 971number of the evaluated sample, starting from 0 972 973@item s 974sample rate 975 976@item t 977time of the evaluated sample expressed in seconds 978 979@item nb_in_channels 980@item nb_out_channels 981input and output number of channels 982 983@item val(CH) 984the value of input channel with number @var{CH} 985@end table 986 987Note: this filter is slow. For faster processing you should use a 988dedicated filter. 989 990@subsection Examples 991 992@itemize 993@item 994Half volume: 995@example 996aeval=val(ch)/2:c=same 997@end example 998 999@item 1000Invert phase of the second channel: 1001@example 1002aeval=val(0)|-val(1) 1003@end example 1004@end itemize 1005 1006@section aexciter 1007 1008An exciter is used to produce high sound that is not present in the 1009original signal. This is done by creating harmonic distortions of the 1010signal which are restricted in range and added to the original signal. 1011An Exciter raises the upper end of an audio signal without simply raising 1012the higher frequencies like an equalizer would do to create a more 1013"crisp" or "brilliant" sound. 1014 1015The filter accepts the following options: 1016 1017@table @option 1018@item level_in 1019Set input level prior processing of signal. 1020Allowed range is from 0 to 64. 1021Default value is 1. 1022 1023@item level_out 1024Set output level after processing of signal. 1025Allowed range is from 0 to 64. 1026Default value is 1. 1027 1028@item amount 1029Set the amount of harmonics added to original signal. 1030Allowed range is from 0 to 64. 1031Default value is 1. 1032 1033@item drive 1034Set the amount of newly created harmonics. 1035Allowed range is from 0.1 to 10. 1036Default value is 8.5. 1037 1038@item blend 1039Set the octave of newly created harmonics. 1040Allowed range is from -10 to 10. 1041Default value is 0. 1042 1043@item freq 1044Set the lower frequency limit of producing harmonics in Hz. 1045Allowed range is from 2000 to 12000 Hz. 1046Default is 7500 Hz. 1047 1048@item ceil 1049Set the upper frequency limit of producing harmonics. 1050Allowed range is from 9999 to 20000 Hz. 1051If value is lower than 10000 Hz no limit is applied. 1052 1053@item listen 1054Mute the original signal and output only added harmonics. 1055By default is disabled. 1056@end table 1057 1058@subsection Commands 1059 1060This filter supports the all above options as @ref{commands}. 1061 1062@anchor{afade} 1063@section afade 1064 1065Apply fade-in/out effect to input audio. 1066 1067A description of the accepted parameters follows. 1068 1069@table @option 1070@item type, t 1071Specify the effect type, can be either @code{in} for fade-in, or 1072@code{out} for a fade-out effect. Default is @code{in}. 1073 1074@item start_sample, ss 1075Specify the number of the start sample for starting to apply the fade 1076effect. Default is 0. 1077 1078@item nb_samples, ns 1079Specify the number of samples for which the fade effect has to last. At 1080the end of the fade-in effect the output audio will have the same 1081volume as the input audio, at the end of the fade-out transition 1082the output audio will be silence. Default is 44100. 1083 1084@item start_time, st 1085Specify the start time of the fade effect. Default is 0. 1086The value must be specified as a time duration; see 1087@ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils} 1088for the accepted syntax. 1089If set this option is used instead of @var{start_sample}. 1090 1091@item duration, d 1092Specify the duration of the fade effect. See 1093@ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils} 1094for the accepted syntax. 1095At the end of the fade-in effect the output audio will have the same 1096volume as the input audio, at the end of the fade-out transition 1097the output audio will be silence. 1098By default the duration is determined by @var{nb_samples}. 1099If set this option is used instead of @var{nb_samples}. 1100 1101@item curve 1102Set curve for fade transition. 1103 1104It accepts the following values: 1105@table @option 1106@item tri 1107select triangular, linear slope (default) 1108@item qsin 1109select quarter of sine wave 1110@item hsin 1111select half of sine wave 1112@item esin 1113select exponential sine wave 1114@item log 1115select logarithmic 1116@item ipar 1117select inverted parabola 1118@item qua 1119select quadratic 1120@item cub 1121select cubic 1122@item squ 1123select square root 1124@item cbr 1125select cubic root 1126@item par 1127select parabola 1128@item exp 1129select exponential 1130@item iqsin 1131select inverted quarter of sine wave 1132@item ihsin 1133select inverted half of sine wave 1134@item dese 1135select double-exponential seat 1136@item desi 1137select double-exponential sigmoid 1138@item losi 1139select logistic sigmoid 1140@item sinc 1141select sine cardinal function 1142@item isinc 1143select inverted sine cardinal function 1144@item nofade 1145no fade applied 1146@end table 1147@end table 1148 1149@subsection Commands 1150 1151This filter supports the all above options as @ref{commands}. 1152 1153@subsection Examples 1154 1155@itemize 1156@item 1157Fade in first 15 seconds of audio: 1158@example 1159afade=t=in:ss=0:d=15 1160@end example 1161 1162@item 1163Fade out last 25 seconds of a 900 seconds audio: 1164@example 1165afade=t=out:st=875:d=25 1166@end example 1167@end itemize 1168 1169@section afftdn 1170Denoise audio samples with FFT. 1171 1172A description of the accepted parameters follows. 1173 1174@table @option 1175@item nr 1176Set the noise reduction in dB, allowed range is 0.01 to 97. 1177Default value is 12 dB. 1178 1179@item nf 1180Set the noise floor in dB, allowed range is -80 to -20. 1181Default value is -50 dB. 1182 1183@item nt 1184Set the noise type. 1185 1186It accepts the following values: 1187@table @option 1188@item w 1189Select white noise. 1190 1191@item v 1192Select vinyl noise. 1193 1194@item s 1195Select shellac noise. 1196 1197@item c 1198Select custom noise, defined in @code{bn} option. 1199 1200Default value is white noise. 1201@end table 1202 1203@item bn 1204Set custom band noise for every one of 15 bands. 1205Bands are separated by ' ' or '|'. 1206 1207@item rf 1208Set the residual floor in dB, allowed range is -80 to -20. 1209Default value is -38 dB. 1210 1211@item tn 1212Enable noise tracking. By default is disabled. 1213With this enabled, noise floor is automatically adjusted. 1214 1215@item tr 1216Enable residual tracking. By default is disabled. 1217 1218@item om 1219Set the output mode. 1220 1221It accepts the following values: 1222@table @option 1223@item i 1224Pass input unchanged. 1225 1226@item o 1227Pass noise filtered out. 1228 1229@item n 1230Pass only noise. 1231 1232Default value is @var{o}. 1233@end table 1234@end table 1235 1236@subsection Commands 1237 1238This filter supports the following commands: 1239@table @option 1240@item sample_noise, sn 1241Start or stop measuring noise profile. 1242Syntax for the command is : "start" or "stop" string. 1243After measuring noise profile is stopped it will be 1244automatically applied in filtering. 1245 1246@item noise_reduction, nr 1247Change noise reduction. Argument is single float number. 1248Syntax for the command is : "@var{noise_reduction}" 1249 1250@item noise_floor, nf 1251Change noise floor. Argument is single float number. 1252Syntax for the command is : "@var{noise_floor}" 1253 1254@item output_mode, om 1255Change output mode operation. 1256Syntax for the command is : "i", "o" or "n" string. 1257@end table 1258 1259@section afftfilt 1260Apply arbitrary expressions to samples in frequency domain. 1261 1262@table @option 1263@item real 1264Set frequency domain real expression for each separate channel separated 1265by '|'. Default is "re". 1266If the number of input channels is greater than the number of 1267expressions, the last specified expression is used for the remaining 1268output channels. 1269 1270@item imag 1271Set frequency domain imaginary expression for each separate channel 1272separated by '|'. Default is "im". 1273 1274Each expression in @var{real} and @var{imag} can contain the following 1275constants and functions: 1276 1277@table @option 1278@item sr 1279sample rate 1280 1281@item b 1282current frequency bin number 1283 1284@item nb 1285number of available bins 1286 1287@item ch 1288channel number of the current expression 1289 1290@item chs 1291number of channels 1292 1293@item pts 1294current frame pts 1295 1296@item re 1297current real part of frequency bin of current channel 1298 1299@item im 1300current imaginary part of frequency bin of current channel 1301 1302@item real(b, ch) 1303Return the value of real part of frequency bin at location (@var{bin},@var{channel}) 1304 1305@item imag(b, ch) 1306Return the value of imaginary part of frequency bin at location (@var{bin},@var{channel}) 1307@end table 1308 1309@item win_size 1310Set window size. Allowed range is from 16 to 131072. 1311Default is @code{4096} 1312 1313@item win_func 1314Set window function. Default is @code{hann}. 1315 1316@item overlap 1317Set window overlap. If set to 1, the recommended overlap for selected 1318window function will be picked. Default is @code{0.75}. 1319@end table 1320 1321@subsection Examples 1322 1323@itemize 1324@item 1325Leave almost only low frequencies in audio: 1326@example 1327afftfilt="'real=re * (1-clip((b/nb)*b,0,1))':imag='im * (1-clip((b/nb)*b,0,1))'" 1328@end example 1329 1330@item 1331Apply robotize effect: 1332@example 1333afftfilt="real='hypot(re,im)*sin(0)':imag='hypot(re,im)*cos(0)':win_size=512:overlap=0.75" 1334@end example 1335 1336@item 1337Apply whisper effect: 1338@example 1339afftfilt="real='hypot(re,im)*cos((random(0)*2-1)*2*3.14)':imag='hypot(re,im)*sin((random(1)*2-1)*2*3.14)':win_size=128:overlap=0.8" 1340@end example 1341@end itemize 1342 1343@anchor{afir} 1344@section afir 1345 1346Apply an arbitrary Finite Impulse Response filter. 1347 1348This filter is designed for applying long FIR filters, 1349up to 60 seconds long. 1350 1351It can be used as component for digital crossover filters, 1352room equalization, cross talk cancellation, wavefield synthesis, 1353auralization, ambiophonics, ambisonics and spatialization. 1354 1355This filter uses the streams higher than first one as FIR coefficients. 1356If the non-first stream holds a single channel, it will be used 1357for all input channels in the first stream, otherwise 1358the number of channels in the non-first stream must be same as 1359the number of channels in the first stream. 1360 1361It accepts the following parameters: 1362 1363@table @option 1364@item dry 1365Set dry gain. This sets input gain. 1366 1367@item wet 1368Set wet gain. This sets final output gain. 1369 1370@item length 1371Set Impulse Response filter length. Default is 1, which means whole IR is processed. 1372 1373@item gtype 1374Enable applying gain measured from power of IR. 1375 1376Set which approach to use for auto gain measurement. 1377 1378@table @option 1379@item none 1380Do not apply any gain. 1381 1382@item peak 1383select peak gain, very conservative approach. This is default value. 1384 1385@item dc 1386select DC gain, limited application. 1387 1388@item gn 1389select gain to noise approach, this is most popular one. 1390@end table 1391 1392@item irgain 1393Set gain to be applied to IR coefficients before filtering. 1394Allowed range is 0 to 1. This gain is applied after any gain applied with @var{gtype} option. 1395 1396@item irfmt 1397Set format of IR stream. Can be @code{mono} or @code{input}. 1398Default is @code{input}. 1399 1400@item maxir 1401Set max allowed Impulse Response filter duration in seconds. Default is 30 seconds. 1402Allowed range is 0.1 to 60 seconds. 1403 1404@item response 1405Show IR frequency response, magnitude(magenta), phase(green) and group delay(yellow) in additional video stream. 1406By default it is disabled. 1407 1408@item channel 1409Set for which IR channel to display frequency response. By default is first channel 1410displayed. This option is used only when @var{response} is enabled. 1411 1412@item size 1413Set video stream size. This option is used only when @var{response} is enabled. 1414 1415@item rate 1416Set video stream frame rate. This option is used only when @var{response} is enabled. 1417 1418@item minp 1419Set minimal partition size used for convolution. Default is @var{8192}. 1420Allowed range is from @var{1} to @var{32768}. 1421Lower values decreases latency at cost of higher CPU usage. 1422 1423@item maxp 1424Set maximal partition size used for convolution. Default is @var{8192}. 1425Allowed range is from @var{8} to @var{32768}. 1426Lower values may increase CPU usage. 1427 1428@item nbirs 1429Set number of input impulse responses streams which will be switchable at runtime. 1430Allowed range is from @var{1} to @var{32}. Default is @var{1}. 1431 1432@item ir 1433Set IR stream which will be used for convolution, starting from @var{0}, should always be 1434lower than supplied value by @code{nbirs} option. Default is @var{0}. 1435This option can be changed at runtime via @ref{commands}. 1436@end table 1437 1438@subsection Examples 1439 1440@itemize 1441@item 1442Apply reverb to stream using mono IR file as second input, complete command using ffmpeg: 1443@example 1444ffmpeg -i input.wav -i middle_tunnel_1way_mono.wav -lavfi afir output.wav 1445@end example 1446@end itemize 1447 1448@anchor{aformat} 1449@section aformat 1450 1451Set output format constraints for the input audio. The framework will 1452negotiate the most appropriate format to minimize conversions. 1453 1454It accepts the following parameters: 1455@table @option 1456 1457@item sample_fmts, f 1458A '|'-separated list of requested sample formats. 1459 1460@item sample_rates, r 1461A '|'-separated list of requested sample rates. 1462 1463@item channel_layouts, cl 1464A '|'-separated list of requested channel layouts. 1465 1466See @ref{channel layout syntax,,the Channel Layout section in the ffmpeg-utils(1) manual,ffmpeg-utils} 1467for the required syntax. 1468@end table 1469 1470If a parameter is omitted, all values are allowed. 1471 1472Force the output to either unsigned 8-bit or signed 16-bit stereo 1473@example 1474aformat=sample_fmts=u8|s16:channel_layouts=stereo 1475@end example 1476 1477@section afreqshift 1478Apply frequency shift to input audio samples. 1479 1480The filter accepts the following options: 1481 1482@table @option 1483@item shift 1484Specify frequency shift. Allowed range is -INT_MAX to INT_MAX. 1485Default value is 0.0. 1486 1487@item level 1488Set output gain applied to final output. Allowed range is from 0.0 to 1.0. 1489Default value is 1.0. 1490@end table 1491 1492@subsection Commands 1493 1494This filter supports the all above options as @ref{commands}. 1495 1496@section agate 1497 1498A gate is mainly used to reduce lower parts of a signal. This kind of signal 1499processing reduces disturbing noise between useful signals. 1500 1501Gating is done by detecting the volume below a chosen level @var{threshold} 1502and dividing it by the factor set with @var{ratio}. The bottom of the noise 1503floor is set via @var{range}. Because an exact manipulation of the signal 1504would cause distortion of the waveform the reduction can be levelled over 1505time. This is done by setting @var{attack} and @var{release}. 1506 1507@var{attack} determines how long the signal has to fall below the threshold 1508before any reduction will occur and @var{release} sets the time the signal 1509has to rise above the threshold to reduce the reduction again. 1510Shorter signals than the chosen attack time will be left untouched. 1511 1512@table @option 1513@item level_in 1514Set input level before filtering. 1515Default is 1. Allowed range is from 0.015625 to 64. 1516 1517@item mode 1518Set the mode of operation. Can be @code{upward} or @code{downward}. 1519Default is @code{downward}. If set to @code{upward} mode, higher parts of signal 1520will be amplified, expanding dynamic range in upward direction. 1521Otherwise, in case of @code{downward} lower parts of signal will be reduced. 1522 1523@item range 1524Set the level of gain reduction when the signal is below the threshold. 1525Default is 0.06125. Allowed range is from 0 to 1. 1526Setting this to 0 disables reduction and then filter behaves like expander. 1527 1528@item threshold 1529If a signal rises above this level the gain reduction is released. 1530Default is 0.125. Allowed range is from 0 to 1. 1531 1532@item ratio 1533Set a ratio by which the signal is reduced. 1534Default is 2. Allowed range is from 1 to 9000. 1535 1536@item attack 1537Amount of milliseconds the signal has to rise above the threshold before gain 1538reduction stops. 1539Default is 20 milliseconds. Allowed range is from 0.01 to 9000. 1540 1541@item release 1542Amount of milliseconds the signal has to fall below the threshold before the 1543reduction is increased again. Default is 250 milliseconds. 1544Allowed range is from 0.01 to 9000. 1545 1546@item makeup 1547Set amount of amplification of signal after processing. 1548Default is 1. Allowed range is from 1 to 64. 1549 1550@item knee 1551Curve the sharp knee around the threshold to enter gain reduction more softly. 1552Default is 2.828427125. Allowed range is from 1 to 8. 1553 1554@item detection 1555Choose if exact signal should be taken for detection or an RMS like one. 1556Default is @code{rms}. Can be @code{peak} or @code{rms}. 1557 1558@item link 1559Choose if the average level between all channels or the louder channel affects 1560the reduction. 1561Default is @code{average}. Can be @code{average} or @code{maximum}. 1562@end table 1563 1564@subsection Commands 1565 1566This filter supports the all above options as @ref{commands}. 1567 1568@section aiir 1569 1570Apply an arbitrary Infinite Impulse Response filter. 1571 1572It accepts the following parameters: 1573 1574@table @option 1575@item zeros, z 1576Set B/numerator/zeros/reflection coefficients. 1577 1578@item poles, p 1579Set A/denominator/poles/ladder coefficients. 1580 1581@item gains, k 1582Set channels gains. 1583 1584@item dry_gain 1585Set input gain. 1586 1587@item wet_gain 1588Set output gain. 1589 1590@item format, f 1591Set coefficients format. 1592 1593@table @samp 1594@item ll 1595lattice-ladder function 1596@item sf 1597analog transfer function 1598@item tf 1599digital transfer function 1600@item zp 1601Z-plane zeros/poles, cartesian (default) 1602@item pr 1603Z-plane zeros/poles, polar radians 1604@item pd 1605Z-plane zeros/poles, polar degrees 1606@item sp 1607S-plane zeros/poles 1608@end table 1609 1610@item process, r 1611Set type of processing. 1612 1613@table @samp 1614@item d 1615direct processing 1616@item s 1617serial processing 1618@item p 1619parallel processing 1620@end table 1621 1622@item precision, e 1623Set filtering precision. 1624 1625@table @samp 1626@item dbl 1627double-precision floating-point (default) 1628@item flt 1629single-precision floating-point 1630@item i32 163132-bit integers 1632@item i16 163316-bit integers 1634@end table 1635 1636@item normalize, n 1637Normalize filter coefficients, by default is enabled. 1638Enabling it will normalize magnitude response at DC to 0dB. 1639 1640@item mix 1641How much to use filtered signal in output. Default is 1. 1642Range is between 0 and 1. 1643 1644@item response 1645Show IR frequency response, magnitude(magenta), phase(green) and group delay(yellow) in additional video stream. 1646By default it is disabled. 1647 1648@item channel 1649Set for which IR channel to display frequency response. By default is first channel 1650displayed. This option is used only when @var{response} is enabled. 1651 1652@item size 1653Set video stream size. This option is used only when @var{response} is enabled. 1654@end table 1655 1656Coefficients in @code{tf} and @code{sf} format are separated by spaces and are in ascending 1657order. 1658 1659Coefficients in @code{zp} format are separated by spaces and order of coefficients 1660doesn't matter. Coefficients in @code{zp} format are complex numbers with @var{i} 1661imaginary unit. 1662 1663Different coefficients and gains can be provided for every channel, in such case 1664use '|' to separate coefficients or gains. Last provided coefficients will be 1665used for all remaining channels. 1666 1667@subsection Examples 1668 1669@itemize 1670@item 1671Apply 2 pole elliptic notch at around 5000Hz for 48000 Hz sample rate: 1672@example 1673aiir=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 1674@end example 1675 1676@item 1677Same as above but in @code{zp} format: 1678@example 1679aiir=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 1680@end example 1681 1682@item 1683Apply 3-rd order analog normalized Butterworth low-pass filter, using analog transfer function format: 1684@example 1685aiir=z=1.3057 0 0 0:p=1.3057 2.3892 2.1860 1:f=sf:r=d 1686@end example 1687@end itemize 1688 1689@section alimiter 1690 1691The limiter prevents an input signal from rising over a desired threshold. 1692This limiter uses lookahead technology to prevent your signal from distorting. 1693It means that there is a small delay after the signal is processed. Keep in mind 1694that the delay it produces is the attack time you set. 1695 1696The filter accepts the following options: 1697 1698@table @option 1699@item level_in 1700Set input gain. Default is 1. 1701 1702@item level_out 1703Set output gain. Default is 1. 1704 1705@item limit 1706Don't let signals above this level pass the limiter. Default is 1. 1707 1708@item attack 1709The limiter will reach its attenuation level in this amount of time in 1710milliseconds. Default is 5 milliseconds. 1711 1712@item release 1713Come back from limiting to attenuation 1.0 in this amount of milliseconds. 1714Default is 50 milliseconds. 1715 1716@item asc 1717When gain reduction is always needed ASC takes care of releasing to an 1718average reduction level rather than reaching a reduction of 0 in the release 1719time. 1720 1721@item asc_level 1722Select how much the release time is affected by ASC, 0 means nearly no changes 1723in release time while 1 produces higher release times. 1724 1725@item level 1726Auto level output signal. Default is enabled. 1727This normalizes audio back to 0dB if enabled. 1728@end table 1729 1730Depending on picked setting it is recommended to upsample input 2x or 4x times 1731with @ref{aresample} before applying this filter. 1732 1733@section allpass 1734 1735Apply a two-pole all-pass filter with central frequency (in Hz) 1736@var{frequency}, and filter-width @var{width}. 1737An all-pass filter changes the audio's frequency to phase relationship 1738without changing its frequency to amplitude relationship. 1739 1740The filter accepts the following options: 1741 1742@table @option 1743@item frequency, f 1744Set frequency in Hz. 1745 1746@item width_type, t 1747Set method to specify band-width of filter. 1748@table @option 1749@item h 1750Hz 1751@item q 1752Q-Factor 1753@item o 1754octave 1755@item s 1756slope 1757@item k 1758kHz 1759@end table 1760 1761@item width, w 1762Specify the band-width of a filter in width_type units. 1763 1764@item mix, m 1765How much to use filtered signal in output. Default is 1. 1766Range is between 0 and 1. 1767 1768@item channels, c 1769Specify which channels to filter, by default all available are filtered. 1770 1771@item normalize, n 1772Normalize biquad coefficients, by default is disabled. 1773Enabling it will normalize magnitude response at DC to 0dB. 1774 1775@item order, o 1776Set the filter order, can be 1 or 2. Default is 2. 1777 1778@item transform, a 1779Set transform type of IIR filter. 1780@table @option 1781@item di 1782@item dii 1783@item tdii 1784@item latt 1785@end table 1786 1787@item precision, r 1788Set precison of filtering. 1789@table @option 1790@item auto 1791Pick automatic sample format depending on surround filters. 1792@item s16 1793Always use signed 16-bit. 1794@item s32 1795Always use signed 32-bit. 1796@item f32 1797Always use float 32-bit. 1798@item f64 1799Always use float 64-bit. 1800@end table 1801@end table 1802 1803@subsection Commands 1804 1805This filter supports the following commands: 1806@table @option 1807@item frequency, f 1808Change allpass frequency. 1809Syntax for the command is : "@var{frequency}" 1810 1811@item width_type, t 1812Change allpass width_type. 1813Syntax for the command is : "@var{width_type}" 1814 1815@item width, w 1816Change allpass width. 1817Syntax for the command is : "@var{width}" 1818 1819@item mix, m 1820Change allpass mix. 1821Syntax for the command is : "@var{mix}" 1822@end table 1823 1824@section aloop 1825 1826Loop audio samples. 1827 1828The filter accepts the following options: 1829 1830@table @option 1831@item loop 1832Set the number of loops. Setting this value to -1 will result in infinite loops. 1833Default is 0. 1834 1835@item size 1836Set maximal number of samples. Default is 0. 1837 1838@item start 1839Set first sample of loop. Default is 0. 1840@end table 1841 1842@anchor{amerge} 1843@section amerge 1844 1845Merge two or more audio streams into a single multi-channel stream. 1846 1847The filter accepts the following options: 1848 1849@table @option 1850 1851@item inputs 1852Set the number of inputs. Default is 2. 1853 1854@end table 1855 1856If the channel layouts of the inputs are disjoint, and therefore compatible, 1857the channel layout of the output will be set accordingly and the channels 1858will be reordered as necessary. If the channel layouts of the inputs are not 1859disjoint, the output will have all the channels of the first input then all 1860the channels of the second input, in that order, and the channel layout of 1861the output will be the default value corresponding to the total number of 1862channels. 1863 1864For example, if the first input is in 2.1 (FL+FR+LF) and the second input 1865is FC+BL+BR, then the output will be in 5.1, with the channels in the 1866following order: a1, a2, b1, a3, b2, b3 (a1 is the first channel of the 1867first input, b1 is the first channel of the second input). 1868 1869On the other hand, if both input are in stereo, the output channels will be 1870in the default order: a1, a2, b1, b2, and the channel layout will be 1871arbitrarily set to 4.0, which may or may not be the expected value. 1872 1873All inputs must have the same sample rate, and format. 1874 1875If inputs do not have the same duration, the output will stop with the 1876shortest. 1877 1878@subsection Examples 1879 1880@itemize 1881@item 1882Merge two mono files into a stereo stream: 1883@example 1884amovie=left.wav [l] ; amovie=right.mp3 [r] ; [l] [r] amerge 1885@end example 1886 1887@item 1888Multiple merges assuming 1 video stream and 6 audio streams in @file{input.mkv}: 1889@example 1890ffmpeg -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 1891@end example 1892@end itemize 1893 1894@section amix 1895 1896Mixes multiple audio inputs into a single output. 1897 1898Note that this filter only supports float samples (the @var{amerge} 1899and @var{pan} audio filters support many formats). If the @var{amix} 1900input has integer samples then @ref{aresample} will be automatically 1901inserted to perform the conversion to float samples. 1902 1903For example 1904@example 1905ffmpeg -i INPUT1 -i INPUT2 -i INPUT3 -filter_complex amix=inputs=3:duration=first:dropout_transition=3 OUTPUT 1906@end example 1907will mix 3 input audio streams to a single output with the same duration as the 1908first input and a dropout transition time of 3 seconds. 1909 1910It accepts the following parameters: 1911@table @option 1912 1913@item inputs 1914The number of inputs. If unspecified, it defaults to 2. 1915 1916@item duration 1917How to determine the end-of-stream. 1918@table @option 1919 1920@item longest 1921The duration of the longest input. (default) 1922 1923@item shortest 1924The duration of the shortest input. 1925 1926@item first 1927The duration of the first input. 1928 1929@end table 1930 1931@item dropout_transition 1932The transition time, in seconds, for volume renormalization when an input 1933stream ends. The default value is 2 seconds. 1934 1935@item weights 1936Specify weight of each input audio stream as sequence. 1937Each weight is separated by space. By default all inputs have same weight. 1938 1939@item normalize 1940Always scale inputs instead of only doing summation of samples. 1941Beware of heavy clipping if inputs are not normalized prior or after filtering 1942by this filter if this option is disabled. By default is enabled. 1943@end table 1944 1945@subsection Commands 1946 1947This filter supports the following commands: 1948@table @option 1949@item weights 1950@item sum 1951Syntax is same as option with same name. 1952@end table 1953 1954@section amultiply 1955 1956Multiply first audio stream with second audio stream and store result 1957in output audio stream. Multiplication is done by multiplying each 1958sample from first stream with sample at same position from second stream. 1959 1960With this element-wise multiplication one can create amplitude fades and 1961amplitude modulations. 1962 1963@section anequalizer 1964 1965High-order parametric multiband equalizer for each channel. 1966 1967It accepts the following parameters: 1968@table @option 1969@item params 1970 1971This option string is in format: 1972"c@var{chn} f=@var{cf} w=@var{w} g=@var{g} t=@var{f} | ..." 1973Each equalizer band is separated by '|'. 1974 1975@table @option 1976@item chn 1977Set channel number to which equalization will be applied. 1978If input doesn't have that channel the entry is ignored. 1979 1980@item f 1981Set central frequency for band. 1982If input doesn't have that frequency the entry is ignored. 1983 1984@item w 1985Set band width in Hertz. 1986 1987@item g 1988Set band gain in dB. 1989 1990@item t 1991Set filter type for band, optional, can be: 1992 1993@table @samp 1994@item 0 1995Butterworth, this is default. 1996 1997@item 1 1998Chebyshev type 1. 1999 2000@item 2 2001Chebyshev type 2. 2002@end table 2003@end table 2004 2005@item curves 2006With this option activated frequency response of anequalizer is displayed 2007in video stream. 2008 2009@item size 2010Set video stream size. Only useful if curves option is activated. 2011 2012@item mgain 2013Set max gain that will be displayed. Only useful if curves option is activated. 2014Setting this to a reasonable value makes it possible to display gain which is derived from 2015neighbour bands which are too close to each other and thus produce higher gain 2016when both are activated. 2017 2018@item fscale 2019Set frequency scale used to draw frequency response in video output. 2020Can be linear or logarithmic. Default is logarithmic. 2021 2022@item colors 2023Set color for each channel curve which is going to be displayed in video stream. 2024This is list of color names separated by space or by '|'. 2025Unrecognised or missing colors will be replaced by white color. 2026@end table 2027 2028@subsection Examples 2029 2030@itemize 2031@item 2032Lower gain by 10 of central frequency 200Hz and width 100 Hz 2033for first 2 channels using Chebyshev type 1 filter: 2034@example 2035anequalizer=c0 f=200 w=100 g=-10 t=1|c1 f=200 w=100 g=-10 t=1 2036@end example 2037@end itemize 2038 2039@subsection Commands 2040 2041This filter supports the following commands: 2042@table @option 2043@item change 2044Alter existing filter parameters. 2045Syntax for the commands is : "@var{fN}|f=@var{freq}|w=@var{width}|g=@var{gain}" 2046 2047@var{fN} is existing filter number, starting from 0, if no such filter is available 2048error is returned. 2049@var{freq} set new frequency parameter. 2050@var{width} set new width parameter in Hertz. 2051@var{gain} set new gain parameter in dB. 2052 2053Full filter invocation with asendcmd may look like this: 2054asendcmd=c='4.0 anequalizer change 0|f=200|w=50|g=1',anequalizer=... 2055@end table 2056 2057@section anlmdn 2058 2059Reduce broadband noise in audio samples using Non-Local Means algorithm. 2060 2061Each sample is adjusted by looking for other samples with similar contexts. This 2062context similarity is defined by comparing their surrounding patches of size 2063@option{p}. Patches are searched in an area of @option{r} around the sample. 2064 2065The filter accepts the following options: 2066 2067@table @option 2068@item s 2069Set denoising strength. Allowed range is from 0.00001 to 10. Default value is 0.00001. 2070 2071@item p 2072Set patch radius duration. Allowed range is from 1 to 100 milliseconds. 2073Default value is 2 milliseconds. 2074 2075@item r 2076Set research radius duration. Allowed range is from 2 to 300 milliseconds. 2077Default value is 6 milliseconds. 2078 2079@item o 2080Set the output mode. 2081 2082It accepts the following values: 2083@table @option 2084@item i 2085Pass input unchanged. 2086 2087@item o 2088Pass noise filtered out. 2089 2090@item n 2091Pass only noise. 2092 2093Default value is @var{o}. 2094@end table 2095 2096@item m 2097Set smooth factor. Default value is @var{11}. Allowed range is from @var{1} to @var{15}. 2098@end table 2099 2100@subsection Commands 2101 2102This filter supports the all above options as @ref{commands}. 2103 2104@section anlms 2105Apply Normalized Least-Mean-Squares algorithm to the first audio stream using the second audio stream. 2106 2107This adaptive filter is used to mimic a desired filter by finding the filter coefficients that 2108relate to producing the least mean square of the error signal (difference between the desired, 21092nd input audio stream and the actual signal, the 1st input audio stream). 2110 2111A description of the accepted options follows. 2112 2113@table @option 2114@item order 2115Set filter order. 2116 2117@item mu 2118Set filter mu. 2119 2120@item eps 2121Set the filter eps. 2122 2123@item leakage 2124Set the filter leakage. 2125 2126@item out_mode 2127It accepts the following values: 2128@table @option 2129@item i 2130Pass the 1st input. 2131 2132@item d 2133Pass the 2nd input. 2134 2135@item o 2136Pass filtered samples. 2137 2138@item n 2139Pass difference between desired and filtered samples. 2140 2141Default value is @var{o}. 2142@end table 2143@end table 2144 2145@subsection Examples 2146 2147@itemize 2148@item 2149One of many usages of this filter is noise reduction, input audio is filtered 2150with same samples that are delayed by fixed amount, one such example for stereo audio is: 2151@example 2152asplit[a][b],[a]adelay=32S|32S[a],[b][a]anlms=order=128:leakage=0.0005:mu=.5:out_mode=o 2153@end example 2154@end itemize 2155 2156@subsection Commands 2157 2158This filter supports the same commands as options, excluding option @code{order}. 2159 2160@section anull 2161 2162Pass the audio source unchanged to the output. 2163 2164@section apad 2165 2166Pad the end of an audio stream with silence. 2167 2168This can be used together with @command{ffmpeg} @option{-shortest} to 2169extend audio streams to the same length as the video stream. 2170 2171A description of the accepted options follows. 2172 2173@table @option 2174@item packet_size 2175Set silence packet size. Default value is 4096. 2176 2177@item pad_len 2178Set the number of samples of silence to add to the end. After the 2179value is reached, the stream is terminated. This option is mutually 2180exclusive with @option{whole_len}. 2181 2182@item whole_len 2183Set the minimum total number of samples in the output audio stream. If 2184the value is longer than the input audio length, silence is added to 2185the end, until the value is reached. This option is mutually exclusive 2186with @option{pad_len}. 2187 2188@item pad_dur 2189Specify the duration of samples of silence to add. See 2190@ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils} 2191for the accepted syntax. Used only if set to non-zero value. 2192 2193@item whole_dur 2194Specify the minimum total duration in the output audio stream. See 2195@ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils} 2196for the accepted syntax. Used only if set to non-zero value. If the value is longer than 2197the input audio length, silence is added to the end, until the value is reached. 2198This option is mutually exclusive with @option{pad_dur} 2199@end table 2200 2201If neither the @option{pad_len} nor the @option{whole_len} nor @option{pad_dur} 2202nor @option{whole_dur} option is set, the filter will add silence to the end of 2203the input stream indefinitely. 2204 2205@subsection Examples 2206 2207@itemize 2208@item 2209Add 1024 samples of silence to the end of the input: 2210@example 2211apad=pad_len=1024 2212@end example 2213 2214@item 2215Make sure the audio output will contain at least 10000 samples, pad 2216the input with silence if required: 2217@example 2218apad=whole_len=10000 2219@end example 2220 2221@item 2222Use @command{ffmpeg} to pad the audio input with silence, so that the 2223video stream will always result the shortest and will be converted 2224until the end in the output file when using the @option{shortest} 2225option: 2226@example 2227ffmpeg -i VIDEO -i AUDIO -filter_complex "[1:0]apad" -shortest OUTPUT 2228@end example 2229@end itemize 2230 2231@section aphaser 2232Add a phasing effect to the input audio. 2233 2234A phaser filter creates series of peaks and troughs in the frequency spectrum. 2235The position of the peaks and troughs are modulated so that they vary over time, creating a sweeping effect. 2236 2237A description of the accepted parameters follows. 2238 2239@table @option 2240@item in_gain 2241Set input gain. Default is 0.4. 2242 2243@item out_gain 2244Set output gain. Default is 0.74 2245 2246@item delay 2247Set delay in milliseconds. Default is 3.0. 2248 2249@item decay 2250Set decay. Default is 0.4. 2251 2252@item speed 2253Set modulation speed in Hz. Default is 0.5. 2254 2255@item type 2256Set modulation type. Default is triangular. 2257 2258It accepts the following values: 2259@table @samp 2260@item triangular, t 2261@item sinusoidal, s 2262@end table 2263@end table 2264 2265@section aphaseshift 2266Apply phase shift to input audio samples. 2267 2268The filter accepts the following options: 2269 2270@table @option 2271@item shift 2272Specify phase shift. Allowed range is from -1.0 to 1.0. 2273Default value is 0.0. 2274 2275@item level 2276Set output gain applied to final output. Allowed range is from 0.0 to 1.0. 2277Default value is 1.0. 2278@end table 2279 2280@subsection Commands 2281 2282This filter supports the all above options as @ref{commands}. 2283 2284@section apulsator 2285 2286Audio pulsator is something between an autopanner and a tremolo. 2287But it can produce funny stereo effects as well. Pulsator changes the volume 2288of the left and right channel based on a LFO (low frequency oscillator) with 2289different waveforms and shifted phases. 2290This filter have the ability to define an offset between left and right 2291channel. An offset of 0 means that both LFO shapes match each other. 2292The left and right channel are altered equally - a conventional tremolo. 2293An offset of 50% means that the shape of the right channel is exactly shifted 2294in phase (or moved backwards about half of the frequency) - pulsator acts as 2295an autopanner. At 1 both curves match again. Every setting in between moves the 2296phase shift gapless between all stages and produces some "bypassing" sounds with 2297sine and triangle waveforms. The more you set the offset near 1 (starting from 2298the 0.5) the faster the signal passes from the left to the right speaker. 2299 2300The filter accepts the following options: 2301 2302@table @option 2303@item level_in 2304Set input gain. By default it is 1. Range is [0.015625 - 64]. 2305 2306@item level_out 2307Set output gain. By default it is 1. Range is [0.015625 - 64]. 2308 2309@item mode 2310Set waveform shape the LFO will use. Can be one of: sine, triangle, square, 2311sawup or sawdown. Default is sine. 2312 2313@item amount 2314Set modulation. Define how much of original signal is affected by the LFO. 2315 2316@item offset_l 2317Set left channel offset. Default is 0. Allowed range is [0 - 1]. 2318 2319@item offset_r 2320Set right channel offset. Default is 0.5. Allowed range is [0 - 1]. 2321 2322@item width 2323Set pulse width. Default is 1. Allowed range is [0 - 2]. 2324 2325@item timing 2326Set possible timing mode. Can be one of: bpm, ms or hz. Default is hz. 2327 2328@item bpm 2329Set bpm. Default is 120. Allowed range is [30 - 300]. Only used if timing 2330is set to bpm. 2331 2332@item ms 2333Set ms. Default is 500. Allowed range is [10 - 2000]. Only used if timing 2334is set to ms. 2335 2336@item hz 2337Set frequency in Hz. Default is 2. Allowed range is [0.01 - 100]. Only used 2338if timing is set to hz. 2339@end table 2340 2341@anchor{aresample} 2342@section aresample 2343 2344Resample the input audio to the specified parameters, using the 2345libswresample library. If none are specified then the filter will 2346automatically convert between its input and output. 2347 2348This filter is also able to stretch/squeeze the audio data to make it match 2349the timestamps or to inject silence / cut out audio to make it match the 2350timestamps, do a combination of both or do neither. 2351 2352The filter accepts the syntax 2353[@var{sample_rate}:]@var{resampler_options}, where @var{sample_rate} 2354expresses a sample rate and @var{resampler_options} is a list of 2355@var{key}=@var{value} pairs, separated by ":". See the 2356@ref{Resampler Options,,"Resampler Options" section in the 2357ffmpeg-resampler(1) manual,ffmpeg-resampler} 2358for the complete list of supported options. 2359 2360@subsection Examples 2361 2362@itemize 2363@item 2364Resample the input audio to 44100Hz: 2365@example 2366aresample=44100 2367@end example 2368 2369@item 2370Stretch/squeeze samples to the given timestamps, with a maximum of 1000 2371samples per second compensation: 2372@example 2373aresample=async=1000 2374@end example 2375@end itemize 2376 2377@section areverse 2378 2379Reverse an audio clip. 2380 2381Warning: This filter requires memory to buffer the entire clip, so trimming 2382is suggested. 2383 2384@subsection Examples 2385 2386@itemize 2387@item 2388Take the first 5 seconds of a clip, and reverse it. 2389@example 2390atrim=end=5,areverse 2391@end example 2392@end itemize 2393 2394@section arnndn 2395 2396Reduce noise from speech using Recurrent Neural Networks. 2397 2398This filter accepts the following options: 2399 2400@table @option 2401@item model, m 2402Set train model file to load. This option is always required. 2403 2404@item mix 2405Set how much to mix filtered samples into final output. 2406Allowed range is from -1 to 1. Default value is 1. 2407Negative values are special, they set how much to keep filtered noise 2408in the final filter output. Set this option to -1 to hear actual 2409noise removed from input signal. 2410@end table 2411 2412@subsection Commands 2413 2414This filter supports the all above options as @ref{commands}. 2415 2416@section asetnsamples 2417 2418Set the number of samples per each output audio frame. 2419 2420The last output packet may contain a different number of samples, as 2421the filter will flush all the remaining samples when the input audio 2422signals its end. 2423 2424The filter accepts the following options: 2425 2426@table @option 2427 2428@item nb_out_samples, n 2429Set the number of frames per each output audio frame. The number is 2430intended as the number of samples @emph{per each channel}. 2431Default value is 1024. 2432 2433@item pad, p 2434If set to 1, the filter will pad the last audio frame with zeroes, so 2435that the last frame will contain the same number of samples as the 2436previous ones. Default value is 1. 2437@end table 2438 2439For example, to set the number of per-frame samples to 1234 and 2440disable padding for the last frame, use: 2441@example 2442asetnsamples=n=1234:p=0 2443@end example 2444 2445@section asetrate 2446 2447Set the sample rate without altering the PCM data. 2448This will result in a change of speed and pitch. 2449 2450The filter accepts the following options: 2451 2452@table @option 2453@item sample_rate, r 2454Set the output sample rate. Default is 44100 Hz. 2455@end table 2456 2457@section ashowinfo 2458 2459Show a line containing various information for each input audio frame. 2460The input audio is not modified. 2461 2462The shown line contains a sequence of key/value pairs of the form 2463@var{key}:@var{value}. 2464 2465The following values are shown in the output: 2466 2467@table @option 2468@item n 2469The (sequential) number of the input frame, starting from 0. 2470 2471@item pts 2472The presentation timestamp of the input frame, in time base units; the time base 2473depends on the filter input pad, and is usually 1/@var{sample_rate}. 2474 2475@item pts_time 2476The presentation timestamp of the input frame in seconds. 2477 2478@item pos 2479position of the frame in the input stream, -1 if this information in 2480unavailable and/or meaningless (for example in case of synthetic audio) 2481 2482@item fmt 2483The sample format. 2484 2485@item chlayout 2486The channel layout. 2487 2488@item rate 2489The sample rate for the audio frame. 2490 2491@item nb_samples 2492The number of samples (per channel) in the frame. 2493 2494@item checksum 2495The Adler-32 checksum (printed in hexadecimal) of the audio data. For planar 2496audio, the data is treated as if all the planes were concatenated. 2497 2498@item plane_checksums 2499A list of Adler-32 checksums for each data plane. 2500@end table 2501 2502@section asoftclip 2503Apply audio soft clipping. 2504 2505Soft clipping is a type of distortion effect where the amplitude of a signal is saturated 2506along a smooth curve, rather than the abrupt shape of hard-clipping. 2507 2508This filter accepts the following options: 2509 2510@table @option 2511@item type 2512Set type of soft-clipping. 2513 2514It accepts the following values: 2515@table @option 2516@item hard 2517@item tanh 2518@item atan 2519@item cubic 2520@item exp 2521@item alg 2522@item quintic 2523@item sin 2524@item erf 2525@end table 2526 2527@item threshold 2528Set threshold from where to start clipping. Default value is 0dB or 1. 2529 2530@item output 2531Set gain applied to output. Default value is 0dB or 1. 2532 2533@item param 2534Set additional parameter which controls sigmoid function. 2535 2536@item oversample 2537Set oversampling factor. 2538@end table 2539 2540@subsection Commands 2541 2542This filter supports the all above options as @ref{commands}. 2543 2544@section asr 2545Automatic Speech Recognition 2546 2547This filter uses PocketSphinx for speech recognition. To enable 2548compilation of this filter, you need to configure FFmpeg with 2549@code{--enable-pocketsphinx}. 2550 2551It accepts the following options: 2552 2553@table @option 2554@item rate 2555Set sampling rate of input audio. Defaults is @code{16000}. 2556This need to match speech models, otherwise one will get poor results. 2557 2558@item hmm 2559Set dictionary containing acoustic model files. 2560 2561@item dict 2562Set pronunciation dictionary. 2563 2564@item lm 2565Set language model file. 2566 2567@item lmctl 2568Set language model set. 2569 2570@item lmname 2571Set which language model to use. 2572 2573@item logfn 2574Set output for log messages. 2575@end table 2576 2577The filter exports recognized speech as the frame metadata @code{lavfi.asr.text}. 2578 2579@anchor{astats} 2580@section astats 2581 2582Display time domain statistical information about the audio channels. 2583Statistics are calculated and displayed for each audio channel and, 2584where applicable, an overall figure is also given. 2585 2586It accepts the following option: 2587@table @option 2588@item length 2589Short window length in seconds, used for peak and trough RMS measurement. 2590Default is @code{0.05} (50 milliseconds). Allowed range is @code{[0.01 - 10]}. 2591 2592@item metadata 2593 2594Set metadata injection. All the metadata keys are prefixed with @code{lavfi.astats.X}, 2595where @code{X} is channel number starting from 1 or string @code{Overall}. Default is 2596disabled. 2597 2598Available keys for each channel are: 2599DC_offset 2600Min_level 2601Max_level 2602Min_difference 2603Max_difference 2604Mean_difference 2605RMS_difference 2606Peak_level 2607RMS_peak 2608RMS_trough 2609Crest_factor 2610Flat_factor 2611Peak_count 2612Noise_floor 2613Noise_floor_count 2614Bit_depth 2615Dynamic_range 2616Zero_crossings 2617Zero_crossings_rate 2618Number_of_NaNs 2619Number_of_Infs 2620Number_of_denormals 2621 2622and for Overall: 2623DC_offset 2624Min_level 2625Max_level 2626Min_difference 2627Max_difference 2628Mean_difference 2629RMS_difference 2630Peak_level 2631RMS_level 2632RMS_peak 2633RMS_trough 2634Flat_factor 2635Peak_count 2636Noise_floor 2637Noise_floor_count 2638Bit_depth 2639Number_of_samples 2640Number_of_NaNs 2641Number_of_Infs 2642Number_of_denormals 2643 2644For example full key look like this @code{lavfi.astats.1.DC_offset} or 2645this @code{lavfi.astats.Overall.Peak_count}. 2646 2647For description what each key means read below. 2648 2649@item reset 2650Set number of frame after which stats are going to be recalculated. 2651Default is disabled. 2652 2653@item measure_perchannel 2654Select the entries which need to be measured per channel. The metadata keys can 2655be used as flags, default is @option{all} which measures everything. 2656@option{none} disables all per channel measurement. 2657 2658@item measure_overall 2659Select the entries which need to be measured overall. The metadata keys can 2660be used as flags, default is @option{all} which measures everything. 2661@option{none} disables all overall measurement. 2662 2663@end table 2664 2665A description of each shown parameter follows: 2666 2667@table @option 2668@item DC offset 2669Mean amplitude displacement from zero. 2670 2671@item Min level 2672Minimal sample level. 2673 2674@item Max level 2675Maximal sample level. 2676 2677@item Min difference 2678Minimal difference between two consecutive samples. 2679 2680@item Max difference 2681Maximal difference between two consecutive samples. 2682 2683@item Mean difference 2684Mean difference between two consecutive samples. 2685The average of each difference between two consecutive samples. 2686 2687@item RMS difference 2688Root Mean Square difference between two consecutive samples. 2689 2690@item Peak level dB 2691@item RMS level dB 2692Standard peak and RMS level measured in dBFS. 2693 2694@item RMS peak dB 2695@item RMS trough dB 2696Peak and trough values for RMS level measured over a short window. 2697 2698@item Crest factor 2699Standard ratio of peak to RMS level (note: not in dB). 2700 2701@item Flat factor 2702Flatness (i.e. consecutive samples with the same value) of the signal at its peak levels 2703(i.e. either @var{Min level} or @var{Max level}). 2704 2705@item Peak count 2706Number of occasions (not the number of samples) that the signal attained either 2707@var{Min level} or @var{Max level}. 2708 2709@item Noise floor dB 2710Minimum local peak measured in dBFS over a short window. 2711 2712@item Noise floor count 2713Number of occasions (not the number of samples) that the signal attained 2714@var{Noise floor}. 2715 2716@item Bit depth 2717Overall bit depth of audio. Number of bits used for each sample. 2718 2719@item Dynamic range 2720Measured dynamic range of audio in dB. 2721 2722@item Zero crossings 2723Number of points where the waveform crosses the zero level axis. 2724 2725@item Zero crossings rate 2726Rate of Zero crossings and number of audio samples. 2727@end table 2728 2729@section asubboost 2730Boost subwoofer frequencies. 2731 2732The filter accepts the following options: 2733 2734@table @option 2735@item dry 2736Set dry gain, how much of original signal is kept. Allowed range is from 0 to 1. 2737Default value is 0.7. 2738 2739@item wet 2740Set wet gain, how much of filtered signal is kept. Allowed range is from 0 to 1. 2741Default value is 0.7. 2742 2743@item decay 2744Set delay line decay gain value. Allowed range is from 0 to 1. 2745Default value is 0.7. 2746 2747@item feedback 2748Set delay line feedback gain value. Allowed range is from 0 to 1. 2749Default value is 0.9. 2750 2751@item cutoff 2752Set cutoff frequency in Hertz. Allowed range is 50 to 900. 2753Default value is 100. 2754 2755@item slope 2756Set slope amount for cutoff frequency. Allowed range is 0.0001 to 1. 2757Default value is 0.5. 2758 2759@item delay 2760Set delay. Allowed range is from 1 to 100. 2761Default value is 20. 2762@end table 2763 2764@subsection Commands 2765 2766This filter supports the all above options as @ref{commands}. 2767 2768@section asubcut 2769Cut subwoofer frequencies. 2770 2771This filter allows to set custom, steeper 2772roll off than highpass filter, and thus is able to more attenuate 2773frequency content in stop-band. 2774 2775The filter accepts the following options: 2776 2777@table @option 2778@item cutoff 2779Set cutoff frequency in Hertz. Allowed range is 2 to 200. 2780Default value is 20. 2781 2782@item order 2783Set filter order. Available values are from 3 to 20. 2784Default value is 10. 2785 2786@item level 2787Set input gain level. Allowed range is from 0 to 1. Default value is 1. 2788@end table 2789 2790@subsection Commands 2791 2792This filter supports the all above options as @ref{commands}. 2793 2794@section asupercut 2795Cut super frequencies. 2796 2797The filter accepts the following options: 2798 2799@table @option 2800@item cutoff 2801Set cutoff frequency in Hertz. Allowed range is 20000 to 192000. 2802Default value is 20000. 2803 2804@item order 2805Set filter order. Available values are from 3 to 20. 2806Default value is 10. 2807 2808@item level 2809Set input gain level. Allowed range is from 0 to 1. Default value is 1. 2810@end table 2811 2812@subsection Commands 2813 2814This filter supports the all above options as @ref{commands}. 2815 2816@section asuperpass 2817Apply high order Butterworth band-pass filter. 2818 2819The filter accepts the following options: 2820 2821@table @option 2822@item centerf 2823Set center frequency in Hertz. Allowed range is 2 to 999999. 2824Default value is 1000. 2825 2826@item order 2827Set filter order. Available values are from 4 to 20. 2828Default value is 4. 2829 2830@item qfactor 2831Set Q-factor. Allowed range is from 0.01 to 100. Default value is 1. 2832 2833@item level 2834Set input gain level. Allowed range is from 0 to 2. Default value is 1. 2835@end table 2836 2837@subsection Commands 2838 2839This filter supports the all above options as @ref{commands}. 2840 2841@section asuperstop 2842Apply high order Butterworth band-stop filter. 2843 2844The filter accepts the following options: 2845 2846@table @option 2847@item centerf 2848Set center frequency in Hertz. Allowed range is 2 to 999999. 2849Default value is 1000. 2850 2851@item order 2852Set filter order. Available values are from 4 to 20. 2853Default value is 4. 2854 2855@item qfactor 2856Set Q-factor. Allowed range is from 0.01 to 100. Default value is 1. 2857 2858@item level 2859Set input gain level. Allowed range is from 0 to 2. Default value is 1. 2860@end table 2861 2862@subsection Commands 2863 2864This filter supports the all above options as @ref{commands}. 2865 2866@section atempo 2867 2868Adjust audio tempo. 2869 2870The filter accepts exactly one parameter, the audio tempo. If not 2871specified then the filter will assume nominal 1.0 tempo. Tempo must 2872be in the [0.5, 100.0] range. 2873 2874Note that tempo greater than 2 will skip some samples rather than 2875blend them in. If for any reason this is a concern it is always 2876possible to daisy-chain several instances of atempo to achieve the 2877desired product tempo. 2878 2879@subsection Examples 2880 2881@itemize 2882@item 2883Slow down audio to 80% tempo: 2884@example 2885atempo=0.8 2886@end example 2887 2888@item 2889To speed up audio to 300% tempo: 2890@example 2891atempo=3 2892@end example 2893 2894@item 2895To speed up audio to 300% tempo by daisy-chaining two atempo instances: 2896@example 2897atempo=sqrt(3),atempo=sqrt(3) 2898@end example 2899@end itemize 2900 2901@subsection Commands 2902 2903This filter supports the following commands: 2904@table @option 2905@item tempo 2906Change filter tempo scale factor. 2907Syntax for the command is : "@var{tempo}" 2908@end table 2909 2910@section atrim 2911 2912Trim the input so that the output contains one continuous subpart of the input. 2913 2914It accepts the following parameters: 2915@table @option 2916@item start 2917Timestamp (in seconds) of the start of the section to keep. I.e. the audio 2918sample with the timestamp @var{start} will be the first sample in the output. 2919 2920@item end 2921Specify time of the first audio sample that will be dropped, i.e. the 2922audio sample immediately preceding the one with the timestamp @var{end} will be 2923the last sample in the output. 2924 2925@item start_pts 2926Same as @var{start}, except this option sets the start timestamp in samples 2927instead of seconds. 2928 2929@item end_pts 2930Same as @var{end}, except this option sets the end timestamp in samples instead 2931of seconds. 2932 2933@item duration 2934The maximum duration of the output in seconds. 2935 2936@item start_sample 2937The number of the first sample that should be output. 2938 2939@item end_sample 2940The number of the first sample that should be dropped. 2941@end table 2942 2943@option{start}, @option{end}, and @option{duration} are expressed as time 2944duration specifications; see 2945@ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}. 2946 2947Note that the first two sets of the start/end options and the @option{duration} 2948option look at the frame timestamp, while the _sample options simply count the 2949samples that pass through the filter. So start/end_pts and start/end_sample will 2950give different results when the timestamps are wrong, inexact or do not start at 2951zero. Also note that this filter does not modify the timestamps. If you wish 2952to have the output timestamps start at zero, insert the asetpts filter after the 2953atrim filter. 2954 2955If multiple start or end options are set, this filter tries to be greedy and 2956keep all samples that match at least one of the specified constraints. To keep 2957only the part that matches all the constraints at once, chain multiple atrim 2958filters. 2959 2960The defaults are such that all the input is kept. So it is possible to set e.g. 2961just the end values to keep everything before the specified time. 2962 2963Examples: 2964@itemize 2965@item 2966Drop everything except the second minute of input: 2967@example 2968ffmpeg -i INPUT -af atrim=60:120 2969@end example 2970 2971@item 2972Keep only the first 1000 samples: 2973@example 2974ffmpeg -i INPUT -af atrim=end_sample=1000 2975@end example 2976 2977@end itemize 2978 2979@section axcorrelate 2980Calculate normalized cross-correlation between two input audio streams. 2981 2982Resulted samples are always between -1 and 1 inclusive. 2983If result is 1 it means two input samples are highly correlated in that selected segment. 2984Result 0 means they are not correlated at all. 2985If result is -1 it means two input samples are out of phase, which means they cancel each 2986other. 2987 2988The filter accepts the following options: 2989 2990@table @option 2991@item size 2992Set size of segment over which cross-correlation is calculated. 2993Default is 256. Allowed range is from 2 to 131072. 2994 2995@item algo 2996Set algorithm for cross-correlation. Can be @code{slow} or @code{fast}. 2997Default is @code{slow}. Fast algorithm assumes mean values over any given segment 2998are always zero and thus need much less calculations to make. 2999This is generally not true, but is valid for typical audio streams. 3000@end table 3001 3002@subsection Examples 3003 3004@itemize 3005@item 3006Calculate correlation between channels in stereo audio stream: 3007@example 3008ffmpeg -i stereo.wav -af channelsplit,axcorrelate=size=1024:algo=fast correlation.wav 3009@end example 3010@end itemize 3011 3012@section bandpass 3013 3014Apply a two-pole Butterworth band-pass filter with central 3015frequency @var{frequency}, and (3dB-point) band-width width. 3016The @var{csg} option selects a constant skirt gain (peak gain = Q) 3017instead of the default: constant 0dB peak gain. 3018The filter roll off at 6dB per octave (20dB per decade). 3019 3020The filter accepts the following options: 3021 3022@table @option 3023@item frequency, f 3024Set the filter's central frequency. Default is @code{3000}. 3025 3026@item csg 3027Constant skirt gain if set to 1. Defaults to 0. 3028 3029@item width_type, t 3030Set method to specify band-width of filter. 3031@table @option 3032@item h 3033Hz 3034@item q 3035Q-Factor 3036@item o 3037octave 3038@item s 3039slope 3040@item k 3041kHz 3042@end table 3043 3044@item width, w 3045Specify the band-width of a filter in width_type units. 3046 3047@item mix, m 3048How much to use filtered signal in output. Default is 1. 3049Range is between 0 and 1. 3050 3051@item channels, c 3052Specify which channels to filter, by default all available are filtered. 3053 3054@item normalize, n 3055Normalize biquad coefficients, by default is disabled. 3056Enabling it will normalize magnitude response at DC to 0dB. 3057 3058@item transform, a 3059Set transform type of IIR filter. 3060@table @option 3061@item di 3062@item dii 3063@item tdii 3064@item latt 3065@end table 3066 3067@item precision, r 3068Set precison of filtering. 3069@table @option 3070@item auto 3071Pick automatic sample format depending on surround filters. 3072@item s16 3073Always use signed 16-bit. 3074@item s32 3075Always use signed 32-bit. 3076@item f32 3077Always use float 32-bit. 3078@item f64 3079Always use float 64-bit. 3080@end table 3081@end table 3082 3083@subsection Commands 3084 3085This filter supports the following commands: 3086@table @option 3087@item frequency, f 3088Change bandpass frequency. 3089Syntax for the command is : "@var{frequency}" 3090 3091@item width_type, t 3092Change bandpass width_type. 3093Syntax for the command is : "@var{width_type}" 3094 3095@item width, w 3096Change bandpass width. 3097Syntax for the command is : "@var{width}" 3098 3099@item mix, m 3100Change bandpass mix. 3101Syntax for the command is : "@var{mix}" 3102@end table 3103 3104@section bandreject 3105 3106Apply a two-pole Butterworth band-reject filter with central 3107frequency @var{frequency}, and (3dB-point) band-width @var{width}. 3108The filter roll off at 6dB per octave (20dB per decade). 3109 3110The filter accepts the following options: 3111 3112@table @option 3113@item frequency, f 3114Set the filter's central frequency. Default is @code{3000}. 3115 3116@item width_type, t 3117Set method to specify band-width of filter. 3118@table @option 3119@item h 3120Hz 3121@item q 3122Q-Factor 3123@item o 3124octave 3125@item s 3126slope 3127@item k 3128kHz 3129@end table 3130 3131@item width, w 3132Specify the band-width of a filter in width_type units. 3133 3134@item mix, m 3135How much to use filtered signal in output. Default is 1. 3136Range is between 0 and 1. 3137 3138@item channels, c 3139Specify which channels to filter, by default all available are filtered. 3140 3141@item normalize, n 3142Normalize biquad coefficients, by default is disabled. 3143Enabling it will normalize magnitude response at DC to 0dB. 3144 3145@item transform, a 3146Set transform type of IIR filter. 3147@table @option 3148@item di 3149@item dii 3150@item tdii 3151@item latt 3152@end table 3153 3154@item precision, r 3155Set precison of filtering. 3156@table @option 3157@item auto 3158Pick automatic sample format depending on surround filters. 3159@item s16 3160Always use signed 16-bit. 3161@item s32 3162Always use signed 32-bit. 3163@item f32 3164Always use float 32-bit. 3165@item f64 3166Always use float 64-bit. 3167@end table 3168@end table 3169 3170@subsection Commands 3171 3172This filter supports the following commands: 3173@table @option 3174@item frequency, f 3175Change bandreject frequency. 3176Syntax for the command is : "@var{frequency}" 3177 3178@item width_type, t 3179Change bandreject width_type. 3180Syntax for the command is : "@var{width_type}" 3181 3182@item width, w 3183Change bandreject width. 3184Syntax for the command is : "@var{width}" 3185 3186@item mix, m 3187Change bandreject mix. 3188Syntax for the command is : "@var{mix}" 3189@end table 3190 3191@section bass, lowshelf 3192 3193Boost or cut the bass (lower) frequencies of the audio using a two-pole 3194shelving filter with a response similar to that of a standard 3195hi-fi's tone-controls. This is also known as shelving equalisation (EQ). 3196 3197The filter accepts the following options: 3198 3199@table @option 3200@item gain, g 3201Give the gain at 0 Hz. Its useful range is about -20 3202(for a large cut) to +20 (for a large boost). 3203Beware of clipping when using a positive gain. 3204 3205@item frequency, f 3206Set the filter's central frequency and so can be used 3207to extend or reduce the frequency range to be boosted or cut. 3208The default value is @code{100} Hz. 3209 3210@item width_type, t 3211Set method to specify band-width of filter. 3212@table @option 3213@item h 3214Hz 3215@item q 3216Q-Factor 3217@item o 3218octave 3219@item s 3220slope 3221@item k 3222kHz 3223@end table 3224 3225@item width, w 3226Determine how steep is the filter's shelf transition. 3227 3228@item poles, p 3229Set number of poles. Default is 2. 3230 3231@item mix, m 3232How much to use filtered signal in output. Default is 1. 3233Range is between 0 and 1. 3234 3235@item channels, c 3236Specify which channels to filter, by default all available are filtered. 3237 3238@item normalize, n 3239Normalize biquad coefficients, by default is disabled. 3240Enabling it will normalize magnitude response at DC to 0dB. 3241 3242@item transform, a 3243Set transform type of IIR filter. 3244@table @option 3245@item di 3246@item dii 3247@item tdii 3248@item latt 3249@end table 3250 3251@item precision, r 3252Set precison of filtering. 3253@table @option 3254@item auto 3255Pick automatic sample format depending on surround filters. 3256@item s16 3257Always use signed 16-bit. 3258@item s32 3259Always use signed 32-bit. 3260@item f32 3261Always use float 32-bit. 3262@item f64 3263Always use float 64-bit. 3264@end table 3265@end table 3266 3267@subsection Commands 3268 3269This filter supports the following commands: 3270@table @option 3271@item frequency, f 3272Change bass frequency. 3273Syntax for the command is : "@var{frequency}" 3274 3275@item width_type, t 3276Change bass width_type. 3277Syntax for the command is : "@var{width_type}" 3278 3279@item width, w 3280Change bass width. 3281Syntax for the command is : "@var{width}" 3282 3283@item gain, g 3284Change bass gain. 3285Syntax for the command is : "@var{gain}" 3286 3287@item mix, m 3288Change bass mix. 3289Syntax for the command is : "@var{mix}" 3290@end table 3291 3292@section biquad 3293 3294Apply a biquad IIR filter with the given coefficients. 3295Where @var{b0}, @var{b1}, @var{b2} and @var{a0}, @var{a1}, @var{a2} 3296are the numerator and denominator coefficients respectively. 3297and @var{channels}, @var{c} specify which channels to filter, by default all 3298available are filtered. 3299 3300@subsection Commands 3301 3302This filter supports the following commands: 3303@table @option 3304@item a0 3305@item a1 3306@item a2 3307@item b0 3308@item b1 3309@item b2 3310Change biquad parameter. 3311Syntax for the command is : "@var{value}" 3312 3313@item mix, m 3314How much to use filtered signal in output. Default is 1. 3315Range is between 0 and 1. 3316 3317@item channels, c 3318Specify which channels to filter, by default all available are filtered. 3319 3320@item normalize, n 3321Normalize biquad coefficients, by default is disabled. 3322Enabling it will normalize magnitude response at DC to 0dB. 3323 3324@item transform, a 3325Set transform type of IIR filter. 3326@table @option 3327@item di 3328@item dii 3329@item tdii 3330@item latt 3331@end table 3332 3333@item precision, r 3334Set precison of filtering. 3335@table @option 3336@item auto 3337Pick automatic sample format depending on surround filters. 3338@item s16 3339Always use signed 16-bit. 3340@item s32 3341Always use signed 32-bit. 3342@item f32 3343Always use float 32-bit. 3344@item f64 3345Always use float 64-bit. 3346@end table 3347@end table 3348 3349@section bs2b 3350Bauer stereo to binaural transformation, which improves headphone listening of 3351stereo audio records. 3352 3353To enable compilation of this filter you need to configure FFmpeg with 3354@code{--enable-libbs2b}. 3355 3356It accepts the following parameters: 3357@table @option 3358 3359@item profile 3360Pre-defined crossfeed level. 3361@table @option 3362 3363@item default 3364Default level (fcut=700, feed=50). 3365 3366@item cmoy 3367Chu Moy circuit (fcut=700, feed=60). 3368 3369@item jmeier 3370Jan Meier circuit (fcut=650, feed=95). 3371 3372@end table 3373 3374@item fcut 3375Cut frequency (in Hz). 3376 3377@item feed 3378Feed level (in Hz). 3379 3380@end table 3381 3382@section channelmap 3383 3384Remap input channels to new locations. 3385 3386It accepts the following parameters: 3387@table @option 3388@item map 3389Map channels from input to output. The argument is a '|'-separated list of 3390mappings, each in the @code{@var{in_channel}-@var{out_channel}} or 3391@var{in_channel} form. @var{in_channel} can be either the name of the input 3392channel (e.g. FL for front left) or its index in the input channel layout. 3393@var{out_channel} is the name of the output channel or its index in the output 3394channel layout. If @var{out_channel} is not given then it is implicitly an 3395index, starting with zero and increasing by one for each mapping. 3396 3397@item channel_layout 3398The channel layout of the output stream. 3399@end table 3400 3401If no mapping is present, the filter will implicitly map input channels to 3402output channels, preserving indices. 3403 3404@subsection Examples 3405 3406@itemize 3407@item 3408For example, assuming a 5.1+downmix input MOV file, 3409@example 3410ffmpeg -i in.mov -filter 'channelmap=map=DL-FL|DR-FR' out.wav 3411@end example 3412will create an output WAV file tagged as stereo from the downmix channels of 3413the input. 3414 3415@item 3416To fix a 5.1 WAV improperly encoded in AAC's native channel order 3417@example 3418ffmpeg -i in.wav -filter 'channelmap=1|2|0|5|3|4:5.1' out.wav 3419@end example 3420@end itemize 3421 3422@section channelsplit 3423 3424Split each channel from an input audio stream into a separate output stream. 3425 3426It accepts the following parameters: 3427@table @option 3428@item channel_layout 3429The channel layout of the input stream. The default is "stereo". 3430@item channels 3431A channel layout describing the channels to be extracted as separate output streams 3432or "all" to extract each input channel as a separate stream. The default is "all". 3433 3434Choosing channels not present in channel layout in the input will result in an error. 3435@end table 3436 3437@subsection Examples 3438 3439@itemize 3440@item 3441For example, assuming a stereo input MP3 file, 3442@example 3443ffmpeg -i in.mp3 -filter_complex channelsplit out.mkv 3444@end example 3445will create an output Matroska file with two audio streams, one containing only 3446the left channel and the other the right channel. 3447 3448@item 3449Split a 5.1 WAV file into per-channel files: 3450@example 3451ffmpeg -i in.wav -filter_complex 3452'channelsplit=channel_layout=5.1[FL][FR][FC][LFE][SL][SR]' 3453-map '[FL]' front_left.wav -map '[FR]' front_right.wav -map '[FC]' 3454front_center.wav -map '[LFE]' lfe.wav -map '[SL]' side_left.wav -map '[SR]' 3455side_right.wav 3456@end example 3457 3458@item 3459Extract only LFE from a 5.1 WAV file: 3460@example 3461ffmpeg -i in.wav -filter_complex 'channelsplit=channel_layout=5.1:channels=LFE[LFE]' 3462-map '[LFE]' lfe.wav 3463@end example 3464@end itemize 3465 3466@section chorus 3467Add a chorus effect to the audio. 3468 3469Can make a single vocal sound like a chorus, but can also be applied to instrumentation. 3470 3471Chorus resembles an echo effect with a short delay, but whereas with echo the delay is 3472constant, with chorus, it is varied using using sinusoidal or triangular modulation. 3473The modulation depth defines the range the modulated delay is played before or after 3474the delay. Hence the delayed sound will sound slower or faster, that is the delayed 3475sound tuned around the original one, like in a chorus where some vocals are slightly 3476off key. 3477 3478It accepts the following parameters: 3479@table @option 3480@item in_gain 3481Set input gain. Default is 0.4. 3482 3483@item out_gain 3484Set output gain. Default is 0.4. 3485 3486@item delays 3487Set delays. A typical delay is around 40ms to 60ms. 3488 3489@item decays 3490Set decays. 3491 3492@item speeds 3493Set speeds. 3494 3495@item depths 3496Set depths. 3497@end table 3498 3499@subsection Examples 3500 3501@itemize 3502@item 3503A single delay: 3504@example 3505chorus=0.7:0.9:55:0.4:0.25:2 3506@end example 3507 3508@item 3509Two delays: 3510@example 3511chorus=0.6:0.9:50|60:0.4|0.32:0.25|0.4:2|1.3 3512@end example 3513 3514@item 3515Fuller sounding chorus with three delays: 3516@example 3517chorus=0.5:0.9:50|60|40:0.4|0.32|0.3:0.25|0.4|0.3:2|2.3|1.3 3518@end example 3519@end itemize 3520 3521@section compand 3522Compress or expand the audio's dynamic range. 3523 3524It accepts the following parameters: 3525 3526@table @option 3527 3528@item attacks 3529@item decays 3530A list of times in seconds for each channel over which the instantaneous level 3531of the input signal is averaged to determine its volume. @var{attacks} refers to 3532increase of volume and @var{decays} refers to decrease of volume. For most 3533situations, the attack time (response to the audio getting louder) should be 3534shorter than the decay time, because the human ear is more sensitive to sudden 3535loud audio than sudden soft audio. A typical value for attack is 0.3 seconds and 3536a typical value for decay is 0.8 seconds. 3537If specified number of attacks & decays is lower than number of channels, the last 3538set attack/decay will be used for all remaining channels. 3539 3540@item points 3541A list of points for the transfer function, specified in dB relative to the 3542maximum possible signal amplitude. Each key points list must be defined using 3543the following syntax: @code{x0/y0|x1/y1|x2/y2|....} or 3544@code{x0/y0 x1/y1 x2/y2 ....} 3545 3546The input values must be in strictly increasing order but the transfer function 3547does not have to be monotonically rising. The point @code{0/0} is assumed but 3548may be overridden (by @code{0/out-dBn}). Typical values for the transfer 3549function are @code{-70/-70|-60/-20|1/0}. 3550 3551@item soft-knee 3552Set the curve radius in dB for all joints. It defaults to 0.01. 3553 3554@item gain 3555Set the additional gain in dB to be applied at all points on the transfer 3556function. This allows for easy adjustment of the overall gain. 3557It defaults to 0. 3558 3559@item volume 3560Set an initial volume, in dB, to be assumed for each channel when filtering 3561starts. This permits the user to supply a nominal level initially, so that, for 3562example, a very large gain is not applied to initial signal levels before the 3563companding has begun to operate. A typical value for audio which is initially 3564quiet is -90 dB. It defaults to 0. 3565 3566@item delay 3567Set a delay, in seconds. The input audio is analyzed immediately, but audio is 3568delayed before being fed to the volume adjuster. Specifying a delay 3569approximately equal to the attack/decay times allows the filter to effectively 3570operate in predictive rather than reactive mode. It defaults to 0. 3571 3572@end table 3573 3574@subsection Examples 3575 3576@itemize 3577@item 3578Make music with both quiet and loud passages suitable for listening to in a 3579noisy environment: 3580@example 3581compand=.3|.3:1|1:-90/-60|-60/-40|-40/-30|-20/-20:6:0:-90:0.2 3582@end example 3583 3584Another example for audio with whisper and explosion parts: 3585@example 3586compand=0|0:1|1:-90/-900|-70/-70|-30/-9|0/-3:6:0:0:0 3587@end example 3588 3589@item 3590A noise gate for when the noise is at a lower level than the signal: 3591@example 3592compand=.1|.1:.2|.2:-900/-900|-50.1/-900|-50/-50:.01:0:-90:.1 3593@end example 3594 3595@item 3596Here is another noise gate, this time for when the noise is at a higher level 3597than the signal (making it, in some ways, similar to squelch): 3598@example 3599compand=.1|.1:.1|.1:-45.1/-45.1|-45/-900|0/-900:.01:45:-90:.1 3600@end example 3601 3602@item 36032:1 compression starting at -6dB: 3604@example 3605compand=points=-80/-80|-6/-6|0/-3.8|20/3.5 3606@end example 3607 3608@item 36092:1 compression starting at -9dB: 3610@example 3611compand=points=-80/-80|-9/-9|0/-5.3|20/2.9 3612@end example 3613 3614@item 36152:1 compression starting at -12dB: 3616@example 3617compand=points=-80/-80|-12/-12|0/-6.8|20/1.9 3618@end example 3619 3620@item 36212:1 compression starting at -18dB: 3622@example 3623compand=points=-80/-80|-18/-18|0/-9.8|20/0.7 3624@end example 3625 3626@item 36273:1 compression starting at -15dB: 3628@example 3629compand=points=-80/-80|-15/-15|0/-10.8|20/-5.2 3630@end example 3631 3632@item 3633Compressor/Gate: 3634@example 3635compand=points=-80/-105|-62/-80|-15.4/-15.4|0/-12|20/-7.6 3636@end example 3637 3638@item 3639Expander: 3640@example 3641compand=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 3642@end example 3643 3644@item 3645Hard limiter at -6dB: 3646@example 3647compand=attacks=0:points=-80/-80|-6/-6|20/-6 3648@end example 3649 3650@item 3651Hard limiter at -12dB: 3652@example 3653compand=attacks=0:points=-80/-80|-12/-12|20/-12 3654@end example 3655 3656@item 3657Hard noise gate at -35 dB: 3658@example 3659compand=attacks=0:points=-80/-115|-35.1/-80|-35/-35|20/20 3660@end example 3661 3662@item 3663Soft limiter: 3664@example 3665compand=attacks=0:points=-80/-80|-12.4/-12.4|-6/-8|0/-6.8|20/-2.8 3666@end example 3667@end itemize 3668 3669@section compensationdelay 3670 3671Compensation Delay Line is a metric based delay to compensate differing 3672positions of microphones or speakers. 3673 3674For example, you have recorded guitar with two microphones placed in 3675different locations. Because the front of sound wave has fixed speed in 3676normal conditions, the phasing of microphones can vary and depends on 3677their location and interposition. The best sound mix can be achieved when 3678these microphones are in phase (synchronized). Note that a distance of 3679~30 cm between microphones makes one microphone capture the signal in 3680antiphase to the other microphone. That makes the final mix sound moody. 3681This filter helps to solve phasing problems by adding different delays 3682to each microphone track and make them synchronized. 3683 3684The best result can be reached when you take one track as base and 3685synchronize other tracks one by one with it. 3686Remember that synchronization/delay tolerance depends on sample rate, too. 3687Higher sample rates will give more tolerance. 3688 3689The filter accepts the following parameters: 3690 3691@table @option 3692@item mm 3693Set millimeters distance. This is compensation distance for fine tuning. 3694Default is 0. 3695 3696@item cm 3697Set cm distance. This is compensation distance for tightening distance setup. 3698Default is 0. 3699 3700@item m 3701Set meters distance. This is compensation distance for hard distance setup. 3702Default is 0. 3703 3704@item dry 3705Set dry amount. Amount of unprocessed (dry) signal. 3706Default is 0. 3707 3708@item wet 3709Set wet amount. Amount of processed (wet) signal. 3710Default is 1. 3711 3712@item temp 3713Set temperature in degrees Celsius. This is the temperature of the environment. 3714Default is 20. 3715@end table 3716 3717@section crossfeed 3718Apply headphone crossfeed filter. 3719 3720Crossfeed is the process of blending the left and right channels of stereo 3721audio recording. 3722It is mainly used to reduce extreme stereo separation of low frequencies. 3723 3724The intent is to produce more speaker like sound to the listener. 3725 3726The filter accepts the following options: 3727 3728@table @option 3729@item strength 3730Set strength of crossfeed. Default is 0.2. Allowed range is from 0 to 1. 3731This sets gain of low shelf filter for side part of stereo image. 3732Default is -6dB. Max allowed is -30db when strength is set to 1. 3733 3734@item range 3735Set soundstage wideness. Default is 0.5. Allowed range is from 0 to 1. 3736This sets cut off frequency of low shelf filter. Default is cut off near 37371550 Hz. With range set to 1 cut off frequency is set to 2100 Hz. 3738 3739@item slope 3740Set curve slope of low shelf filter. Default is 0.5. 3741Allowed range is from 0.01 to 1. 3742 3743@item level_in 3744Set input gain. Default is 0.9. 3745 3746@item level_out 3747Set output gain. Default is 1. 3748@end table 3749 3750@subsection Commands 3751 3752This filter supports the all above options as @ref{commands}. 3753 3754@section crystalizer 3755Simple algorithm for audio noise sharpening. 3756 3757This filter linearly increases differences betweeen each audio sample. 3758 3759The filter accepts the following options: 3760 3761@table @option 3762@item i 3763Sets the intensity of effect (default: 2.0). Must be in range between -10.0 to 0 3764(unchanged sound) to 10.0 (maximum effect). 3765To inverse filtering use negative value. 3766 3767@item c 3768Enable clipping. By default is enabled. 3769@end table 3770 3771@subsection Commands 3772 3773This filter supports the all above options as @ref{commands}. 3774 3775@section dcshift 3776Apply a DC shift to the audio. 3777 3778This can be useful to remove a DC offset (caused perhaps by a hardware problem 3779in the recording chain) from the audio. The effect of a DC offset is reduced 3780headroom and hence volume. The @ref{astats} filter can be used to determine if 3781a signal has a DC offset. 3782 3783@table @option 3784@item shift 3785Set the DC shift, allowed range is [-1, 1]. It indicates the amount to shift 3786the audio. 3787 3788@item limitergain 3789Optional. It should have a value much less than 1 (e.g. 0.05 or 0.02) and is 3790used to prevent clipping. 3791@end table 3792 3793@section deesser 3794 3795Apply de-essing to the audio samples. 3796 3797@table @option 3798@item i 3799Set intensity for triggering de-essing. Allowed range is from 0 to 1. 3800Default is 0. 3801 3802@item m 3803Set amount of ducking on treble part of sound. Allowed range is from 0 to 1. 3804Default is 0.5. 3805 3806@item f 3807How much of original frequency content to keep when de-essing. Allowed range is from 0 to 1. 3808Default is 0.5. 3809 3810@item s 3811Set the output mode. 3812 3813It accepts the following values: 3814@table @option 3815@item i 3816Pass input unchanged. 3817 3818@item o 3819Pass ess filtered out. 3820 3821@item e 3822Pass only ess. 3823 3824Default value is @var{o}. 3825@end table 3826 3827@end table 3828 3829@section drmeter 3830Measure audio dynamic range. 3831 3832DR values of 14 and higher is found in very dynamic material. DR of 8 to 13 3833is found in transition material. And anything less that 8 have very poor dynamics 3834and is very compressed. 3835 3836The filter accepts the following options: 3837 3838@table @option 3839@item length 3840Set window length in seconds used to split audio into segments of equal length. 3841Default is 3 seconds. 3842@end table 3843 3844@section dynaudnorm 3845Dynamic Audio Normalizer. 3846 3847This filter applies a certain amount of gain to the input audio in order 3848to bring its peak magnitude to a target level (e.g. 0 dBFS). However, in 3849contrast to more "simple" normalization algorithms, the Dynamic Audio 3850Normalizer *dynamically* re-adjusts the gain factor to the input audio. 3851This allows for applying extra gain to the "quiet" sections of the audio 3852while avoiding distortions or clipping the "loud" sections. In other words: 3853The Dynamic Audio Normalizer will "even out" the volume of quiet and loud 3854sections, in the sense that the volume of each section is brought to the 3855same target level. Note, however, that the Dynamic Audio Normalizer achieves 3856this goal *without* applying "dynamic range compressing". It will retain 100% 3857of the dynamic range *within* each section of the audio file. 3858 3859@table @option 3860@item framelen, f 3861Set the frame length in milliseconds. In range from 10 to 8000 milliseconds. 3862Default is 500 milliseconds. 3863The Dynamic Audio Normalizer processes the input audio in small chunks, 3864referred to as frames. This is required, because a peak magnitude has no 3865meaning for just a single sample value. Instead, we need to determine the 3866peak magnitude for a contiguous sequence of sample values. While a "standard" 3867normalizer would simply use the peak magnitude of the complete file, the 3868Dynamic Audio Normalizer determines the peak magnitude individually for each 3869frame. The length of a frame is specified in milliseconds. By default, the 3870Dynamic Audio Normalizer uses a frame length of 500 milliseconds, which has 3871been found to give good results with most files. 3872Note that the exact frame length, in number of samples, will be determined 3873automatically, based on the sampling rate of the individual input audio file. 3874 3875@item gausssize, g 3876Set the Gaussian filter window size. In range from 3 to 301, must be odd 3877number. Default is 31. 3878Probably the most important parameter of the Dynamic Audio Normalizer is the 3879@code{window size} of the Gaussian smoothing filter. The filter's window size 3880is specified in frames, centered around the current frame. For the sake of 3881simplicity, this must be an odd number. Consequently, the default value of 31 3882takes into account the current frame, as well as the 15 preceding frames and 3883the 15 subsequent frames. Using a larger window results in a stronger 3884smoothing effect and thus in less gain variation, i.e. slower gain 3885adaptation. Conversely, using a smaller window results in a weaker smoothing 3886effect and thus in more gain variation, i.e. faster gain adaptation. 3887In other words, the more you increase this value, the more the Dynamic Audio 3888Normalizer will behave like a "traditional" normalization filter. On the 3889contrary, the more you decrease this value, the more the Dynamic Audio 3890Normalizer will behave like a dynamic range compressor. 3891 3892@item peak, p 3893Set the target peak value. This specifies the highest permissible magnitude 3894level for the normalized audio input. This filter will try to approach the 3895target peak magnitude as closely as possible, but at the same time it also 3896makes sure that the normalized signal will never exceed the peak magnitude. 3897A frame's maximum local gain factor is imposed directly by the target peak 3898magnitude. The default value is 0.95 and thus leaves a headroom of 5%*. 3899It is not recommended to go above this value. 3900 3901@item maxgain, m 3902Set the maximum gain factor. In range from 1.0 to 100.0. Default is 10.0. 3903The Dynamic Audio Normalizer determines the maximum possible (local) gain 3904factor for each input frame, i.e. the maximum gain factor that does not 3905result in clipping or distortion. The maximum gain factor is determined by 3906the frame's highest magnitude sample. However, the Dynamic Audio Normalizer 3907additionally bounds the frame's maximum gain factor by a predetermined 3908(global) maximum gain factor. This is done in order to avoid excessive gain 3909factors in "silent" or almost silent frames. By default, the maximum gain 3910factor is 10.0, For most inputs the default value should be sufficient and 3911it usually is not recommended to increase this value. Though, for input 3912with an extremely low overall volume level, it may be necessary to allow even 3913higher gain factors. Note, however, that the Dynamic Audio Normalizer does 3914not simply apply a "hard" threshold (i.e. cut off values above the threshold). 3915Instead, a "sigmoid" threshold function will be applied. This way, the 3916gain factors will smoothly approach the threshold value, but never exceed that 3917value. 3918 3919@item targetrms, r 3920Set the target RMS. In range from 0.0 to 1.0. Default is 0.0 - disabled. 3921By default, the Dynamic Audio Normalizer performs "peak" normalization. 3922This means that the maximum local gain factor for each frame is defined 3923(only) by the frame's highest magnitude sample. This way, the samples can 3924be amplified as much as possible without exceeding the maximum signal 3925level, i.e. without clipping. Optionally, however, the Dynamic Audio 3926Normalizer can also take into account the frame's root mean square, 3927abbreviated RMS. In electrical engineering, the RMS is commonly used to 3928determine the power of a time-varying signal. It is therefore considered 3929that the RMS is a better approximation of the "perceived loudness" than 3930just looking at the signal's peak magnitude. Consequently, by adjusting all 3931frames to a constant RMS value, a uniform "perceived loudness" can be 3932established. If a target RMS value has been specified, a frame's local gain 3933factor is defined as the factor that would result in exactly that RMS value. 3934Note, however, that the maximum local gain factor is still restricted by the 3935frame's highest magnitude sample, in order to prevent clipping. 3936 3937@item coupling, n 3938Enable channels coupling. By default is enabled. 3939By default, the Dynamic Audio Normalizer will amplify all channels by the same 3940amount. This means the same gain factor will be applied to all channels, i.e. 3941the maximum possible gain factor is determined by the "loudest" channel. 3942However, in some recordings, it may happen that the volume of the different 3943channels is uneven, e.g. one channel may be "quieter" than the other one(s). 3944In this case, this option can be used to disable the channel coupling. This way, 3945the gain factor will be determined independently for each channel, depending 3946only on the individual channel's highest magnitude sample. This allows for 3947harmonizing the volume of the different channels. 3948 3949@item correctdc, c 3950Enable DC bias correction. By default is disabled. 3951An audio signal (in the time domain) is a sequence of sample values. 3952In the Dynamic Audio Normalizer these sample values are represented in the 3953-1.0 to 1.0 range, regardless of the original input format. Normally, the 3954audio signal, or "waveform", should be centered around the zero point. 3955That means if we calculate the mean value of all samples in a file, or in a 3956single frame, then the result should be 0.0 or at least very close to that 3957value. If, however, there is a significant deviation of the mean value from 39580.0, in either positive or negative direction, this is referred to as a 3959DC bias or DC offset. Since a DC bias is clearly undesirable, the Dynamic 3960Audio Normalizer provides optional DC bias correction. 3961With DC bias correction enabled, the Dynamic Audio Normalizer will determine 3962the mean value, or "DC correction" offset, of each input frame and subtract 3963that value from all of the frame's sample values which ensures those samples 3964are centered around 0.0 again. Also, in order to avoid "gaps" at the frame 3965boundaries, the DC correction offset values will be interpolated smoothly 3966between neighbouring frames. 3967 3968@item altboundary, b 3969Enable alternative boundary mode. By default is disabled. 3970The Dynamic Audio Normalizer takes into account a certain neighbourhood 3971around each frame. This includes the preceding frames as well as the 3972subsequent frames. However, for the "boundary" frames, located at the very 3973beginning and at the very end of the audio file, not all neighbouring 3974frames are available. In particular, for the first few frames in the audio 3975file, the preceding frames are not known. And, similarly, for the last few 3976frames in the audio file, the subsequent frames are not known. Thus, the 3977question arises which gain factors should be assumed for the missing frames 3978in the "boundary" region. The Dynamic Audio Normalizer implements two modes 3979to deal with this situation. The default boundary mode assumes a gain factor 3980of exactly 1.0 for the missing frames, resulting in a smooth "fade in" and 3981"fade out" at the beginning and at the end of the input, respectively. 3982 3983@item compress, s 3984Set the compress factor. In range from 0.0 to 30.0. Default is 0.0. 3985By default, the Dynamic Audio Normalizer does not apply "traditional" 3986compression. This means that signal peaks will not be pruned and thus the 3987full dynamic range will be retained within each local neighbourhood. However, 3988in some cases it may be desirable to combine the Dynamic Audio Normalizer's 3989normalization algorithm with a more "traditional" compression. 3990For this purpose, the Dynamic Audio Normalizer provides an optional compression 3991(thresholding) function. If (and only if) the compression feature is enabled, 3992all input frames will be processed by a soft knee thresholding function prior 3993to the actual normalization process. Put simply, the thresholding function is 3994going to prune all samples whose magnitude exceeds a certain threshold value. 3995However, the Dynamic Audio Normalizer does not simply apply a fixed threshold 3996value. Instead, the threshold value will be adjusted for each individual 3997frame. 3998In general, smaller parameters result in stronger compression, and vice versa. 3999Values below 3.0 are not recommended, because audible distortion may appear. 4000 4001@item threshold, t 4002Set the target threshold value. This specifies the lowest permissible 4003magnitude level for the audio input which will be normalized. 4004If input frame volume is above this value frame will be normalized. 4005Otherwise frame may not be normalized at all. The default value is set 4006to 0, which means all input frames will be normalized. 4007This option is mostly useful if digital noise is not wanted to be amplified. 4008@end table 4009 4010@subsection Commands 4011 4012This filter supports the all above options as @ref{commands}. 4013 4014@section earwax 4015 4016Make audio easier to listen to on headphones. 4017 4018This filter adds `cues' to 44.1kHz stereo (i.e. audio CD format) audio 4019so that when listened to on headphones the stereo image is moved from 4020inside your head (standard for headphones) to outside and in front of 4021the listener (standard for speakers). 4022 4023Ported from SoX. 4024 4025@section equalizer 4026 4027Apply a two-pole peaking equalisation (EQ) filter. With this 4028filter, the signal-level at and around a selected frequency can 4029be increased or decreased, whilst (unlike bandpass and bandreject 4030filters) that at all other frequencies is unchanged. 4031 4032In order to produce complex equalisation curves, this filter can 4033be given several times, each with a different central frequency. 4034 4035The filter accepts the following options: 4036 4037@table @option 4038@item frequency, f 4039Set the filter's central frequency in Hz. 4040 4041@item width_type, t 4042Set method to specify band-width of filter. 4043@table @option 4044@item h 4045Hz 4046@item q 4047Q-Factor 4048@item o 4049octave 4050@item s 4051slope 4052@item k 4053kHz 4054@end table 4055 4056@item width, w 4057Specify the band-width of a filter in width_type units. 4058 4059@item gain, g 4060Set the required gain or attenuation in dB. 4061Beware of clipping when using a positive gain. 4062 4063@item mix, m 4064How much to use filtered signal in output. Default is 1. 4065Range is between 0 and 1. 4066 4067@item channels, c 4068Specify which channels to filter, by default all available are filtered. 4069 4070@item normalize, n 4071Normalize biquad coefficients, by default is disabled. 4072Enabling it will normalize magnitude response at DC to 0dB. 4073 4074@item transform, a 4075Set transform type of IIR filter. 4076@table @option 4077@item di 4078@item dii 4079@item tdii 4080@item latt 4081@end table 4082 4083@item precision, r 4084Set precison of filtering. 4085@table @option 4086@item auto 4087Pick automatic sample format depending on surround filters. 4088@item s16 4089Always use signed 16-bit. 4090@item s32 4091Always use signed 32-bit. 4092@item f32 4093Always use float 32-bit. 4094@item f64 4095Always use float 64-bit. 4096@end table 4097@end table 4098 4099@subsection Examples 4100@itemize 4101@item 4102Attenuate 10 dB at 1000 Hz, with a bandwidth of 200 Hz: 4103@example 4104equalizer=f=1000:t=h:width=200:g=-10 4105@end example 4106 4107@item 4108Apply 2 dB gain at 1000 Hz with Q 1 and attenuate 5 dB at 100 Hz with Q 2: 4109@example 4110equalizer=f=1000:t=q:w=1:g=2,equalizer=f=100:t=q:w=2:g=-5 4111@end example 4112@end itemize 4113 4114@subsection Commands 4115 4116This filter supports the following commands: 4117@table @option 4118@item frequency, f 4119Change equalizer frequency. 4120Syntax for the command is : "@var{frequency}" 4121 4122@item width_type, t 4123Change equalizer width_type. 4124Syntax for the command is : "@var{width_type}" 4125 4126@item width, w 4127Change equalizer width. 4128Syntax for the command is : "@var{width}" 4129 4130@item gain, g 4131Change equalizer gain. 4132Syntax for the command is : "@var{gain}" 4133 4134@item mix, m 4135Change equalizer mix. 4136Syntax for the command is : "@var{mix}" 4137@end table 4138 4139@section extrastereo 4140 4141Linearly increases the difference between left and right channels which 4142adds some sort of "live" effect to playback. 4143 4144The filter accepts the following options: 4145 4146@table @option 4147@item m 4148Sets the difference coefficient (default: 2.5). 0.0 means mono sound 4149(average of both channels), with 1.0 sound will be unchanged, with 4150-1.0 left and right channels will be swapped. 4151 4152@item c 4153Enable clipping. By default is enabled. 4154@end table 4155 4156@subsection Commands 4157 4158This filter supports the all above options as @ref{commands}. 4159 4160@section firequalizer 4161Apply FIR Equalization using arbitrary frequency response. 4162 4163The filter accepts the following option: 4164 4165@table @option 4166@item gain 4167Set gain curve equation (in dB). The expression can contain variables: 4168@table @option 4169@item f 4170the evaluated frequency 4171@item sr 4172sample rate 4173@item ch 4174channel number, set to 0 when multichannels evaluation is disabled 4175@item chid 4176channel id, see libavutil/channel_layout.h, set to the first channel id when 4177multichannels evaluation is disabled 4178@item chs 4179number of channels 4180@item chlayout 4181channel_layout, see libavutil/channel_layout.h 4182 4183@end table 4184and functions: 4185@table @option 4186@item gain_interpolate(f) 4187interpolate gain on frequency f based on gain_entry 4188@item cubic_interpolate(f) 4189same as gain_interpolate, but smoother 4190@end table 4191This option is also available as command. Default is @code{gain_interpolate(f)}. 4192 4193@item gain_entry 4194Set gain entry for gain_interpolate function. The expression can 4195contain functions: 4196@table @option 4197@item entry(f, g) 4198store gain entry at frequency f with value g 4199@end table 4200This option is also available as command. 4201 4202@item delay 4203Set filter delay in seconds. Higher value means more accurate. 4204Default is @code{0.01}. 4205 4206@item accuracy 4207Set filter accuracy in Hz. Lower value means more accurate. 4208Default is @code{5}. 4209 4210@item wfunc 4211Set window function. Acceptable values are: 4212@table @option 4213@item rectangular 4214rectangular window, useful when gain curve is already smooth 4215@item hann 4216hann window (default) 4217@item hamming 4218hamming window 4219@item blackman 4220blackman window 4221@item nuttall3 42223-terms continuous 1st derivative nuttall window 4223@item mnuttall3 4224minimum 3-terms discontinuous nuttall window 4225@item nuttall 42264-terms continuous 1st derivative nuttall window 4227@item bnuttall 4228minimum 4-terms discontinuous nuttall (blackman-nuttall) window 4229@item bharris 4230blackman-harris window 4231@item tukey 4232tukey window 4233@end table 4234 4235@item fixed 4236If enabled, use fixed number of audio samples. This improves speed when 4237filtering with large delay. Default is disabled. 4238 4239@item multi 4240Enable multichannels evaluation on gain. Default is disabled. 4241 4242@item zero_phase 4243Enable zero phase mode by subtracting timestamp to compensate delay. 4244Default is disabled. 4245 4246@item scale 4247Set scale used by gain. Acceptable values are: 4248@table @option 4249@item linlin 4250linear frequency, linear gain 4251@item linlog 4252linear frequency, logarithmic (in dB) gain (default) 4253@item loglin 4254logarithmic (in octave scale where 20 Hz is 0) frequency, linear gain 4255@item loglog 4256logarithmic frequency, logarithmic gain 4257@end table 4258 4259@item dumpfile 4260Set file for dumping, suitable for gnuplot. 4261 4262@item dumpscale 4263Set scale for dumpfile. Acceptable values are same with scale option. 4264Default is linlog. 4265 4266@item fft2 4267Enable 2-channel convolution using complex FFT. This improves speed significantly. 4268Default is disabled. 4269 4270@item min_phase 4271Enable minimum phase impulse response. Default is disabled. 4272@end table 4273 4274@subsection Examples 4275@itemize 4276@item 4277lowpass at 1000 Hz: 4278@example 4279firequalizer=gain='if(lt(f,1000), 0, -INF)' 4280@end example 4281@item 4282lowpass at 1000 Hz with gain_entry: 4283@example 4284firequalizer=gain_entry='entry(1000,0); entry(1001, -INF)' 4285@end example 4286@item 4287custom equalization: 4288@example 4289firequalizer=gain_entry='entry(100,0); entry(400, -4); entry(1000, -6); entry(2000, 0)' 4290@end example 4291@item 4292higher delay with zero phase to compensate delay: 4293@example 4294firequalizer=delay=0.1:fixed=on:zero_phase=on 4295@end example 4296@item 4297lowpass on left channel, highpass on right channel: 4298@example 4299firequalizer=gain='if(eq(chid,1), gain_interpolate(f), if(eq(chid,2), gain_interpolate(1e6+f), 0))' 4300:gain_entry='entry(1000, 0); entry(1001,-INF); entry(1e6+1000,0)':multi=on 4301@end example 4302@end itemize 4303 4304@section flanger 4305Apply a flanging effect to the audio. 4306 4307The filter accepts the following options: 4308 4309@table @option 4310@item delay 4311Set base delay in milliseconds. Range from 0 to 30. Default value is 0. 4312 4313@item depth 4314Set added sweep delay in milliseconds. Range from 0 to 10. Default value is 2. 4315 4316@item regen 4317Set percentage regeneration (delayed signal feedback). Range from -95 to 95. 4318Default value is 0. 4319 4320@item width 4321Set percentage of delayed signal mixed with original. Range from 0 to 100. 4322Default value is 71. 4323 4324@item speed 4325Set sweeps per second (Hz). Range from 0.1 to 10. Default value is 0.5. 4326 4327@item shape 4328Set swept wave shape, can be @var{triangular} or @var{sinusoidal}. 4329Default value is @var{sinusoidal}. 4330 4331@item phase 4332Set swept wave percentage-shift for multi channel. Range from 0 to 100. 4333Default value is 25. 4334 4335@item interp 4336Set delay-line interpolation, @var{linear} or @var{quadratic}. 4337Default is @var{linear}. 4338@end table 4339 4340@section haas 4341Apply Haas effect to audio. 4342 4343Note that this makes most sense to apply on mono signals. 4344With this filter applied to mono signals it give some directionality and 4345stretches its stereo image. 4346 4347The filter accepts the following options: 4348 4349@table @option 4350@item level_in 4351Set input level. By default is @var{1}, or 0dB 4352 4353@item level_out 4354Set output level. By default is @var{1}, or 0dB. 4355 4356@item side_gain 4357Set gain applied to side part of signal. By default is @var{1}. 4358 4359@item middle_source 4360Set kind of middle source. Can be one of the following: 4361 4362@table @samp 4363@item left 4364Pick left channel. 4365 4366@item right 4367Pick right channel. 4368 4369@item mid 4370Pick middle part signal of stereo image. 4371 4372@item side 4373Pick side part signal of stereo image. 4374@end table 4375 4376@item middle_phase 4377Change middle phase. By default is disabled. 4378 4379@item left_delay 4380Set left channel delay. By default is @var{2.05} milliseconds. 4381 4382@item left_balance 4383Set left channel balance. By default is @var{-1}. 4384 4385@item left_gain 4386Set left channel gain. By default is @var{1}. 4387 4388@item left_phase 4389Change left phase. By default is disabled. 4390 4391@item right_delay 4392Set right channel delay. By defaults is @var{2.12} milliseconds. 4393 4394@item right_balance 4395Set right channel balance. By default is @var{1}. 4396 4397@item right_gain 4398Set right channel gain. By default is @var{1}. 4399 4400@item right_phase 4401Change right phase. By default is enabled. 4402@end table 4403 4404@section hdcd 4405 4406Decodes High Definition Compatible Digital (HDCD) data. A 16-bit PCM stream with 4407embedded HDCD codes is expanded into a 20-bit PCM stream. 4408 4409The filter supports the Peak Extend and Low-level Gain Adjustment features 4410of HDCD, and detects the Transient Filter flag. 4411 4412@example 4413ffmpeg -i HDCD16.flac -af hdcd OUT24.flac 4414@end example 4415 4416When using the filter with wav, note the default encoding for wav is 16-bit, 4417so the resulting 20-bit stream will be truncated back to 16-bit. Use something 4418like @command{-acodec pcm_s24le} after the filter to get 24-bit PCM output. 4419@example 4420ffmpeg -i HDCD16.wav -af hdcd OUT16.wav 4421ffmpeg -i HDCD16.wav -af hdcd -c:a pcm_s24le OUT24.wav 4422@end example 4423 4424The filter accepts the following options: 4425 4426@table @option 4427@item disable_autoconvert 4428Disable any automatic format conversion or resampling in the filter graph. 4429 4430@item process_stereo 4431Process the stereo channels together. If target_gain does not match between 4432channels, consider it invalid and use the last valid target_gain. 4433 4434@item cdt_ms 4435Set the code detect timer period in ms. 4436 4437@item force_pe 4438Always extend peaks above -3dBFS even if PE isn't signaled. 4439 4440@item analyze_mode 4441Replace audio with a solid tone and adjust the amplitude to signal some 4442specific aspect of the decoding process. The output file can be loaded in 4443an audio editor alongside the original to aid analysis. 4444 4445@code{analyze_mode=pe:force_pe=true} can be used to see all samples above the PE level. 4446 4447Modes are: 4448@table @samp 4449@item 0, off 4450Disabled 4451@item 1, lle 4452Gain adjustment level at each sample 4453@item 2, pe 4454Samples where peak extend occurs 4455@item 3, cdt 4456Samples where the code detect timer is active 4457@item 4, tgm 4458Samples where the target gain does not match between channels 4459@end table 4460@end table 4461 4462@section headphone 4463 4464Apply head-related transfer functions (HRTFs) to create virtual 4465loudspeakers around the user for binaural listening via headphones. 4466The HRIRs are provided via additional streams, for each channel 4467one stereo input stream is needed. 4468 4469The filter accepts the following options: 4470 4471@table @option 4472@item map 4473Set mapping of input streams for convolution. 4474The argument is a '|'-separated list of channel names in order as they 4475are given as additional stream inputs for filter. 4476This also specify number of input streams. Number of input streams 4477must be not less than number of channels in first stream plus one. 4478 4479@item gain 4480Set gain applied to audio. Value is in dB. Default is 0. 4481 4482@item type 4483Set processing type. Can be @var{time} or @var{freq}. @var{time} is 4484processing audio in time domain which is slow. 4485@var{freq} is processing audio in frequency domain which is fast. 4486Default is @var{freq}. 4487 4488@item lfe 4489Set custom gain for LFE channels. Value is in dB. Default is 0. 4490 4491@item size 4492Set size of frame in number of samples which will be processed at once. 4493Default value is @var{1024}. Allowed range is from 1024 to 96000. 4494 4495@item hrir 4496Set format of hrir stream. 4497Default value is @var{stereo}. Alternative value is @var{multich}. 4498If value is set to @var{stereo}, number of additional streams should 4499be greater or equal to number of input channels in first input stream. 4500Also each additional stream should have stereo number of channels. 4501If value is set to @var{multich}, number of additional streams should 4502be exactly one. Also number of input channels of additional stream 4503should be equal or greater than twice number of channels of first input 4504stream. 4505@end table 4506 4507@subsection Examples 4508 4509@itemize 4510@item 4511Full example using wav files as coefficients with amovie filters for 7.1 downmix, 4512each amovie filter use stereo file with IR coefficients as input. 4513The files give coefficients for each position of virtual loudspeaker: 4514@example 4515ffmpeg -i input.wav 4516-filter_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];[0:a][fl][fr][fc][lfe][bl][br][sl][sr]headphone=FL|FR|FC|LFE|BL|BR|SL|SR" 4517output.wav 4518@end example 4519 4520@item 4521Full example using wav files as coefficients with amovie filters for 7.1 downmix, 4522but now in @var{multich} @var{hrir} format. 4523@example 4524ffmpeg -i input.wav -filter_complex "amovie=minp.wav[hrirs];[0:a][hrirs]headphone=map=FL|FR|FC|LFE|BL|BR|SL|SR:hrir=multich" 4525output.wav 4526@end example 4527@end itemize 4528 4529@section highpass 4530 4531Apply a high-pass filter with 3dB point frequency. 4532The filter can be either single-pole, or double-pole (the default). 4533The filter roll off at 6dB per pole per octave (20dB per pole per decade). 4534 4535The filter accepts the following options: 4536 4537@table @option 4538@item frequency, f 4539Set frequency in Hz. Default is 3000. 4540 4541@item poles, p 4542Set number of poles. Default is 2. 4543 4544@item width_type, t 4545Set method to specify band-width of filter. 4546@table @option 4547@item h 4548Hz 4549@item q 4550Q-Factor 4551@item o 4552octave 4553@item s 4554slope 4555@item k 4556kHz 4557@end table 4558 4559@item width, w 4560Specify the band-width of a filter in width_type units. 4561Applies only to double-pole filter. 4562The default is 0.707q and gives a Butterworth response. 4563 4564@item mix, m 4565How much to use filtered signal in output. Default is 1. 4566Range is between 0 and 1. 4567 4568@item channels, c 4569Specify which channels to filter, by default all available are filtered. 4570 4571@item normalize, n 4572Normalize biquad coefficients, by default is disabled. 4573Enabling it will normalize magnitude response at DC to 0dB. 4574 4575@item transform, a 4576Set transform type of IIR filter. 4577@table @option 4578@item di 4579@item dii 4580@item tdii 4581@item latt 4582@end table 4583 4584@item precision, r 4585Set precison of filtering. 4586@table @option 4587@item auto 4588Pick automatic sample format depending on surround filters. 4589@item s16 4590Always use signed 16-bit. 4591@item s32 4592Always use signed 32-bit. 4593@item f32 4594Always use float 32-bit. 4595@item f64 4596Always use float 64-bit. 4597@end table 4598@end table 4599 4600@subsection Commands 4601 4602This filter supports the following commands: 4603@table @option 4604@item frequency, f 4605Change highpass frequency. 4606Syntax for the command is : "@var{frequency}" 4607 4608@item width_type, t 4609Change highpass width_type. 4610Syntax for the command is : "@var{width_type}" 4611 4612@item width, w 4613Change highpass width. 4614Syntax for the command is : "@var{width}" 4615 4616@item mix, m 4617Change highpass mix. 4618Syntax for the command is : "@var{mix}" 4619@end table 4620 4621@section join 4622 4623Join multiple input streams into one multi-channel stream. 4624 4625It accepts the following parameters: 4626@table @option 4627 4628@item inputs 4629The number of input streams. It defaults to 2. 4630 4631@item channel_layout 4632The desired output channel layout. It defaults to stereo. 4633 4634@item map 4635Map channels from inputs to output. The argument is a '|'-separated list of 4636mappings, each in the @code{@var{input_idx}.@var{in_channel}-@var{out_channel}} 4637form. @var{input_idx} is the 0-based index of the input stream. @var{in_channel} 4638can be either the name of the input channel (e.g. FL for front left) or its 4639index in the specified input stream. @var{out_channel} is the name of the output 4640channel. 4641@end table 4642 4643The filter will attempt to guess the mappings when they are not specified 4644explicitly. It does so by first trying to find an unused matching input channel 4645and if that fails it picks the first unused input channel. 4646 4647Join 3 inputs (with properly set channel layouts): 4648@example 4649ffmpeg -i INPUT1 -i INPUT2 -i INPUT3 -filter_complex join=inputs=3 OUTPUT 4650@end example 4651 4652Build a 5.1 output from 6 single-channel streams: 4653@example 4654ffmpeg -i fl -i fr -i fc -i sl -i sr -i lfe -filter_complex 4655'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' 4656out 4657@end example 4658 4659@section ladspa 4660 4661Load a LADSPA (Linux Audio Developer's Simple Plugin API) plugin. 4662 4663To enable compilation of this filter you need to configure FFmpeg with 4664@code{--enable-ladspa}. 4665 4666@table @option 4667@item file, f 4668Specifies the name of LADSPA plugin library to load. If the environment 4669variable @env{LADSPA_PATH} is defined, the LADSPA plugin is searched in 4670each one of the directories specified by the colon separated list in 4671@env{LADSPA_PATH}, otherwise in the standard LADSPA paths, which are in 4672this order: @file{HOME/.ladspa/lib/}, @file{/usr/local/lib/ladspa/}, 4673@file{/usr/lib/ladspa/}. 4674 4675@item plugin, p 4676Specifies the plugin within the library. Some libraries contain only 4677one plugin, but others contain many of them. If this is not set filter 4678will list all available plugins within the specified library. 4679 4680@item controls, c 4681Set the '|' separated list of controls which are zero or more floating point 4682values that determine the behavior of the loaded plugin (for example delay, 4683threshold or gain). 4684Controls need to be defined using the following syntax: 4685c0=@var{value0}|c1=@var{value1}|c2=@var{value2}|..., where 4686@var{valuei} is the value set on the @var{i}-th control. 4687Alternatively they can be also defined using the following syntax: 4688@var{value0}|@var{value1}|@var{value2}|..., where 4689@var{valuei} is the value set on the @var{i}-th control. 4690If @option{controls} is set to @code{help}, all available controls and 4691their valid ranges are printed. 4692 4693@item sample_rate, s 4694Specify the sample rate, default to 44100. Only used if plugin have 4695zero inputs. 4696 4697@item nb_samples, n 4698Set the number of samples per channel per each output frame, default 4699is 1024. Only used if plugin have zero inputs. 4700 4701@item duration, d 4702Set the minimum duration of the sourced audio. See 4703@ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils} 4704for the accepted syntax. 4705Note that the resulting duration may be greater than the specified duration, 4706as the generated audio is always cut at the end of a complete frame. 4707If not specified, or the expressed duration is negative, the audio is 4708supposed to be generated forever. 4709Only used if plugin have zero inputs. 4710 4711@item latency, l 4712Enable latency compensation, by default is disabled. 4713Only used if plugin have inputs. 4714@end table 4715 4716@subsection Examples 4717 4718@itemize 4719@item 4720List all available plugins within amp (LADSPA example plugin) library: 4721@example 4722ladspa=file=amp 4723@end example 4724 4725@item 4726List all available controls and their valid ranges for @code{vcf_notch} 4727plugin from @code{VCF} library: 4728@example 4729ladspa=f=vcf:p=vcf_notch:c=help 4730@end example 4731 4732@item 4733Simulate low quality audio equipment using @code{Computer Music Toolkit} (CMT) 4734plugin library: 4735@example 4736ladspa=file=cmt:plugin=lofi:controls=c0=22|c1=12|c2=12 4737@end example 4738 4739@item 4740Add reverberation to the audio using TAP-plugins 4741(Tom's Audio Processing plugins): 4742@example 4743ladspa=file=tap_reverb:tap_reverb 4744@end example 4745 4746@item 4747Generate white noise, with 0.2 amplitude: 4748@example 4749ladspa=file=cmt:noise_source_white:c=c0=.2 4750@end example 4751 4752@item 4753Generate 20 bpm clicks using plugin @code{C* Click - Metronome} from the 4754@code{C* Audio Plugin Suite} (CAPS) library: 4755@example 4756ladspa=file=caps:Click:c=c1=20' 4757@end example 4758 4759@item 4760Apply @code{C* Eq10X2 - Stereo 10-band equaliser} effect: 4761@example 4762ladspa=caps:Eq10X2:c=c0=-48|c9=-24|c3=12|c4=2 4763@end example 4764 4765@item 4766Increase volume by 20dB using fast lookahead limiter from Steve Harris 4767@code{SWH Plugins} collection: 4768@example 4769ladspa=fast_lookahead_limiter_1913:fastLookaheadLimiter:20|0|2 4770@end example 4771 4772@item 4773Attenuate low frequencies using Multiband EQ from Steve Harris 4774@code{SWH Plugins} collection: 4775@example 4776ladspa=mbeq_1197:mbeq:-24|-24|-24|0|0|0|0|0|0|0|0|0|0|0|0 4777@end example 4778 4779@item 4780Reduce stereo image using @code{Narrower} from the @code{C* Audio Plugin Suite} 4781(CAPS) library: 4782@example 4783ladspa=caps:Narrower 4784@end example 4785 4786@item 4787Another white noise, now using @code{C* Audio Plugin Suite} (CAPS) library: 4788@example 4789ladspa=caps:White:.2 4790@end example 4791 4792@item 4793Some fractal noise, using @code{C* Audio Plugin Suite} (CAPS) library: 4794@example 4795ladspa=caps:Fractal:c=c1=1 4796@end example 4797 4798@item 4799Dynamic volume normalization using @code{VLevel} plugin: 4800@example 4801ladspa=vlevel-ladspa:vlevel_mono 4802@end example 4803@end itemize 4804 4805@subsection Commands 4806 4807This filter supports the following commands: 4808@table @option 4809@item cN 4810Modify the @var{N}-th control value. 4811 4812If the specified value is not valid, it is ignored and prior one is kept. 4813@end table 4814 4815@section loudnorm 4816 4817EBU R128 loudness normalization. Includes both dynamic and linear normalization modes. 4818Support for both single pass (livestreams, files) and double pass (files) modes. 4819This algorithm can target IL, LRA, and maximum true peak. In dynamic mode, to accurately 4820detect true peaks, the audio stream will be upsampled to 192 kHz. 4821Use the @code{-ar} option or @code{aresample} filter to explicitly set an output sample rate. 4822 4823The filter accepts the following options: 4824 4825@table @option 4826@item I, i 4827Set integrated loudness target. 4828Range is -70.0 - -5.0. Default value is -24.0. 4829 4830@item LRA, lra 4831Set loudness range target. 4832Range is 1.0 - 20.0. Default value is 7.0. 4833 4834@item TP, tp 4835Set maximum true peak. 4836Range is -9.0 - +0.0. Default value is -2.0. 4837 4838@item measured_I, measured_i 4839Measured IL of input file. 4840Range is -99.0 - +0.0. 4841 4842@item measured_LRA, measured_lra 4843Measured LRA of input file. 4844Range is 0.0 - 99.0. 4845 4846@item measured_TP, measured_tp 4847Measured true peak of input file. 4848Range is -99.0 - +99.0. 4849 4850@item measured_thresh 4851Measured threshold of input file. 4852Range is -99.0 - +0.0. 4853 4854@item offset 4855Set offset gain. Gain is applied before the true-peak limiter. 4856Range is -99.0 - +99.0. Default is +0.0. 4857 4858@item linear 4859Normalize by linearly scaling the source audio. 4860@code{measured_I}, @code{measured_LRA}, @code{measured_TP}, 4861and @code{measured_thresh} must all be specified. Target LRA shouldn't 4862be lower than source LRA and the change in integrated loudness shouldn't 4863result in a true peak which exceeds the target TP. If any of these 4864conditions aren't met, normalization mode will revert to @var{dynamic}. 4865Options are @code{true} or @code{false}. Default is @code{true}. 4866 4867@item dual_mono 4868Treat mono input files as "dual-mono". If a mono file is intended for playback 4869on a stereo system, its EBU R128 measurement will be perceptually incorrect. 4870If set to @code{true}, this option will compensate for this effect. 4871Multi-channel input files are not affected by this option. 4872Options are true or false. Default is false. 4873 4874@item print_format 4875Set print format for stats. Options are summary, json, or none. 4876Default value is none. 4877@end table 4878 4879@section lowpass 4880 4881Apply a low-pass filter with 3dB point frequency. 4882The filter can be either single-pole or double-pole (the default). 4883The filter roll off at 6dB per pole per octave (20dB per pole per decade). 4884 4885The filter accepts the following options: 4886 4887@table @option 4888@item frequency, f 4889Set frequency in Hz. Default is 500. 4890 4891@item poles, p 4892Set number of poles. Default is 2. 4893 4894@item width_type, t 4895Set method to specify band-width of filter. 4896@table @option 4897@item h 4898Hz 4899@item q 4900Q-Factor 4901@item o 4902octave 4903@item s 4904slope 4905@item k 4906kHz 4907@end table 4908 4909@item width, w 4910Specify the band-width of a filter in width_type units. 4911Applies only to double-pole filter. 4912The default is 0.707q and gives a Butterworth response. 4913 4914@item mix, m 4915How much to use filtered signal in output. Default is 1. 4916Range is between 0 and 1. 4917 4918@item channels, c 4919Specify which channels to filter, by default all available are filtered. 4920 4921@item normalize, n 4922Normalize biquad coefficients, by default is disabled. 4923Enabling it will normalize magnitude response at DC to 0dB. 4924 4925@item transform, a 4926Set transform type of IIR filter. 4927@table @option 4928@item di 4929@item dii 4930@item tdii 4931@item latt 4932@end table 4933 4934@item precision, r 4935Set precison of filtering. 4936@table @option 4937@item auto 4938Pick automatic sample format depending on surround filters. 4939@item s16 4940Always use signed 16-bit. 4941@item s32 4942Always use signed 32-bit. 4943@item f32 4944Always use float 32-bit. 4945@item f64 4946Always use float 64-bit. 4947@end table 4948@end table 4949 4950@subsection Examples 4951@itemize 4952@item 4953Lowpass only LFE channel, it LFE is not present it does nothing: 4954@example 4955lowpass=c=LFE 4956@end example 4957@end itemize 4958 4959@subsection Commands 4960 4961This filter supports the following commands: 4962@table @option 4963@item frequency, f 4964Change lowpass frequency. 4965Syntax for the command is : "@var{frequency}" 4966 4967@item width_type, t 4968Change lowpass width_type. 4969Syntax for the command is : "@var{width_type}" 4970 4971@item width, w 4972Change lowpass width. 4973Syntax for the command is : "@var{width}" 4974 4975@item mix, m 4976Change lowpass mix. 4977Syntax for the command is : "@var{mix}" 4978@end table 4979 4980@section lv2 4981 4982Load a LV2 (LADSPA Version 2) plugin. 4983 4984To enable compilation of this filter you need to configure FFmpeg with 4985@code{--enable-lv2}. 4986 4987@table @option 4988@item plugin, p 4989Specifies the plugin URI. You may need to escape ':'. 4990 4991@item controls, c 4992Set the '|' separated list of controls which are zero or more floating point 4993values that determine the behavior of the loaded plugin (for example delay, 4994threshold or gain). 4995If @option{controls} is set to @code{help}, all available controls and 4996their valid ranges are printed. 4997 4998@item sample_rate, s 4999Specify the sample rate, default to 44100. Only used if plugin have 5000zero inputs. 5001 5002@item nb_samples, n 5003Set the number of samples per channel per each output frame, default 5004is 1024. Only used if plugin have zero inputs. 5005 5006@item duration, d 5007Set the minimum duration of the sourced audio. See 5008@ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils} 5009for the accepted syntax. 5010Note that the resulting duration may be greater than the specified duration, 5011as the generated audio is always cut at the end of a complete frame. 5012If not specified, or the expressed duration is negative, the audio is 5013supposed to be generated forever. 5014Only used if plugin have zero inputs. 5015@end table 5016 5017@subsection Examples 5018 5019@itemize 5020@item 5021Apply bass enhancer plugin from Calf: 5022@example 5023lv2=p=http\\\\://calf.sourceforge.net/plugins/BassEnhancer:c=amount=2 5024@end example 5025 5026@item 5027Apply vinyl plugin from Calf: 5028@example 5029lv2=p=http\\\\://calf.sourceforge.net/plugins/Vinyl:c=drone=0.2|aging=0.5 5030@end example 5031 5032@item 5033Apply bit crusher plugin from ArtyFX: 5034@example 5035lv2=p=http\\\\://www.openavproductions.com/artyfx#bitta:c=crush=0.3 5036@end example 5037@end itemize 5038 5039@section mcompand 5040Multiband Compress or expand the audio's dynamic range. 5041 5042The input audio is divided into bands using 4th order Linkwitz-Riley IIRs. 5043This is akin to the crossover of a loudspeaker, and results in flat frequency 5044response when absent compander action. 5045 5046It accepts the following parameters: 5047 5048@table @option 5049@item args 5050This option syntax is: 5051attack,decay,[attack,decay..] soft-knee points crossover_frequency [delay [initial_volume [gain]]] | attack,decay ... 5052For explanation of each item refer to compand filter documentation. 5053@end table 5054 5055@anchor{pan} 5056@section pan 5057 5058Mix channels with specific gain levels. The filter accepts the output 5059channel layout followed by a set of channels definitions. 5060 5061This filter is also designed to efficiently remap the channels of an audio 5062stream. 5063 5064The filter accepts parameters of the form: 5065"@var{l}|@var{outdef}|@var{outdef}|..." 5066 5067@table @option 5068@item l 5069output channel layout or number of channels 5070 5071@item outdef 5072output channel specification, of the form: 5073"@var{out_name}=[@var{gain}*]@var{in_name}[(+-)[@var{gain}*]@var{in_name}...]" 5074 5075@item out_name 5076output channel to define, either a channel name (FL, FR, etc.) or a channel 5077number (c0, c1, etc.) 5078 5079@item gain 5080multiplicative coefficient for the channel, 1 leaving the volume unchanged 5081 5082@item in_name 5083input channel to use, see out_name for details; it is not possible to mix 5084named and numbered input channels 5085@end table 5086 5087If the `=' in a channel specification is replaced by `<', then the gains for 5088that specification will be renormalized so that the total is 1, thus 5089avoiding clipping noise. 5090 5091@subsection Mixing examples 5092 5093For example, if you want to down-mix from stereo to mono, but with a bigger 5094factor for the left channel: 5095@example 5096pan=1c|c0=0.9*c0+0.1*c1 5097@end example 5098 5099A customized down-mix to stereo that works automatically for 3-, 4-, 5- and 51007-channels surround: 5101@example 5102pan=stereo| FL < FL + 0.5*FC + 0.6*BL + 0.6*SL | FR < FR + 0.5*FC + 0.6*BR + 0.6*SR 5103@end example 5104 5105Note that @command{ffmpeg} integrates a default down-mix (and up-mix) system 5106that should be preferred (see "-ac" option) unless you have very specific 5107needs. 5108 5109@subsection Remapping examples 5110 5111The channel remapping will be effective if, and only if: 5112 5113@itemize 5114@item gain coefficients are zeroes or ones, 5115@item only one input per channel output, 5116@end itemize 5117 5118If all these conditions are satisfied, the filter will notify the user ("Pure 5119channel mapping detected"), and use an optimized and lossless method to do the 5120remapping. 5121 5122For example, if you have a 5.1 source and want a stereo audio stream by 5123dropping the extra channels: 5124@example 5125pan="stereo| c0=FL | c1=FR" 5126@end example 5127 5128Given the same source, you can also switch front left and front right channels 5129and keep the input channel layout: 5130@example 5131pan="5.1| c0=c1 | c1=c0 | c2=c2 | c3=c3 | c4=c4 | c5=c5" 5132@end example 5133 5134If the input is a stereo audio stream, you can mute the front left channel (and 5135still keep the stereo channel layout) with: 5136@example 5137pan="stereo|c1=c1" 5138@end example 5139 5140Still with a stereo audio stream input, you can copy the right channel in both 5141front left and right: 5142@example 5143pan="stereo| c0=FR | c1=FR" 5144@end example 5145 5146@section replaygain 5147 5148ReplayGain scanner filter. This filter takes an audio stream as an input and 5149outputs it unchanged. 5150At end of filtering it displays @code{track_gain} and @code{track_peak}. 5151 5152@section resample 5153 5154Convert the audio sample format, sample rate and channel layout. It is 5155not meant to be used directly. 5156 5157@section rubberband 5158Apply time-stretching and pitch-shifting with librubberband. 5159 5160To enable compilation of this filter, you need to configure FFmpeg with 5161@code{--enable-librubberband}. 5162 5163The filter accepts the following options: 5164 5165@table @option 5166@item tempo 5167Set tempo scale factor. 5168 5169@item pitch 5170Set pitch scale factor. 5171 5172@item transients 5173Set transients detector. 5174Possible values are: 5175@table @var 5176@item crisp 5177@item mixed 5178@item smooth 5179@end table 5180 5181@item detector 5182Set detector. 5183Possible values are: 5184@table @var 5185@item compound 5186@item percussive 5187@item soft 5188@end table 5189 5190@item phase 5191Set phase. 5192Possible values are: 5193@table @var 5194@item laminar 5195@item independent 5196@end table 5197 5198@item window 5199Set processing window size. 5200Possible values are: 5201@table @var 5202@item standard 5203@item short 5204@item long 5205@end table 5206 5207@item smoothing 5208Set smoothing. 5209Possible values are: 5210@table @var 5211@item off 5212@item on 5213@end table 5214 5215@item formant 5216Enable formant preservation when shift pitching. 5217Possible values are: 5218@table @var 5219@item shifted 5220@item preserved 5221@end table 5222 5223@item pitchq 5224Set pitch quality. 5225Possible values are: 5226@table @var 5227@item quality 5228@item speed 5229@item consistency 5230@end table 5231 5232@item channels 5233Set channels. 5234Possible values are: 5235@table @var 5236@item apart 5237@item together 5238@end table 5239@end table 5240 5241@subsection Commands 5242 5243This filter supports the following commands: 5244@table @option 5245@item tempo 5246Change filter tempo scale factor. 5247Syntax for the command is : "@var{tempo}" 5248 5249@item pitch 5250Change filter pitch scale factor. 5251Syntax for the command is : "@var{pitch}" 5252@end table 5253 5254@section sidechaincompress 5255 5256This filter acts like normal compressor but has the ability to compress 5257detected signal using second input signal. 5258It needs two input streams and returns one output stream. 5259First input stream will be processed depending on second stream signal. 5260The filtered signal then can be filtered with other filters in later stages of 5261processing. See @ref{pan} and @ref{amerge} filter. 5262 5263The filter accepts the following options: 5264 5265@table @option 5266@item level_in 5267Set input gain. Default is 1. Range is between 0.015625 and 64. 5268 5269@item mode 5270Set mode of compressor operation. Can be @code{upward} or @code{downward}. 5271Default is @code{downward}. 5272 5273@item threshold 5274If a signal of second stream raises above this level it will affect the gain 5275reduction of first stream. 5276By default is 0.125. Range is between 0.00097563 and 1. 5277 5278@item ratio 5279Set a ratio about which the signal is reduced. 1:2 means that if the level 5280raised 4dB above the threshold, it will be only 2dB above after the reduction. 5281Default is 2. Range is between 1 and 20. 5282 5283@item attack 5284Amount of milliseconds the signal has to rise above the threshold before gain 5285reduction starts. Default is 20. Range is between 0.01 and 2000. 5286 5287@item release 5288Amount of milliseconds the signal has to fall below the threshold before 5289reduction is decreased again. Default is 250. Range is between 0.01 and 9000. 5290 5291@item makeup 5292Set the amount by how much signal will be amplified after processing. 5293Default is 1. Range is from 1 to 64. 5294 5295@item knee 5296Curve the sharp knee around the threshold to enter gain reduction more softly. 5297Default is 2.82843. Range is between 1 and 8. 5298 5299@item link 5300Choose if the @code{average} level between all channels of side-chain stream 5301or the louder(@code{maximum}) channel of side-chain stream affects the 5302reduction. Default is @code{average}. 5303 5304@item detection 5305Should the exact signal be taken in case of @code{peak} or an RMS one in case 5306of @code{rms}. Default is @code{rms} which is mainly smoother. 5307 5308@item level_sc 5309Set sidechain gain. Default is 1. Range is between 0.015625 and 64. 5310 5311@item mix 5312How much to use compressed signal in output. Default is 1. 5313Range is between 0 and 1. 5314@end table 5315 5316@subsection Commands 5317 5318This filter supports the all above options as @ref{commands}. 5319 5320@subsection Examples 5321 5322@itemize 5323@item 5324Full ffmpeg example taking 2 audio inputs, 1st input to be compressed 5325depending on the signal of 2nd input and later compressed signal to be 5326merged with 2nd input: 5327@example 5328ffmpeg -i main.flac -i sidechain.flac -filter_complex "[1:a]asplit=2[sc][mix];[0:a][sc]sidechaincompress[compr];[compr][mix]amerge" 5329@end example 5330@end itemize 5331 5332@section sidechaingate 5333 5334A sidechain gate acts like a normal (wideband) gate but has the ability to 5335filter the detected signal before sending it to the gain reduction stage. 5336Normally a gate uses the full range signal to detect a level above the 5337threshold. 5338For example: If you cut all lower frequencies from your sidechain signal 5339the gate will decrease the volume of your track only if not enough highs 5340appear. With this technique you are able to reduce the resonation of a 5341natural drum or remove "rumbling" of muted strokes from a heavily distorted 5342guitar. 5343It needs two input streams and returns one output stream. 5344First input stream will be processed depending on second stream signal. 5345 5346The filter accepts the following options: 5347 5348@table @option 5349@item level_in 5350Set input level before filtering. 5351Default is 1. Allowed range is from 0.015625 to 64. 5352 5353@item mode 5354Set the mode of operation. Can be @code{upward} or @code{downward}. 5355Default is @code{downward}. If set to @code{upward} mode, higher parts of signal 5356will be amplified, expanding dynamic range in upward direction. 5357Otherwise, in case of @code{downward} lower parts of signal will be reduced. 5358 5359@item range 5360Set the level of gain reduction when the signal is below the threshold. 5361Default is 0.06125. Allowed range is from 0 to 1. 5362Setting this to 0 disables reduction and then filter behaves like expander. 5363 5364@item threshold 5365If a signal rises above this level the gain reduction is released. 5366Default is 0.125. Allowed range is from 0 to 1. 5367 5368@item ratio 5369Set a ratio about which the signal is reduced. 5370Default is 2. Allowed range is from 1 to 9000. 5371 5372@item attack 5373Amount of milliseconds the signal has to rise above the threshold before gain 5374reduction stops. 5375Default is 20 milliseconds. Allowed range is from 0.01 to 9000. 5376 5377@item release 5378Amount of milliseconds the signal has to fall below the threshold before the 5379reduction is increased again. Default is 250 milliseconds. 5380Allowed range is from 0.01 to 9000. 5381 5382@item makeup 5383Set amount of amplification of signal after processing. 5384Default is 1. Allowed range is from 1 to 64. 5385 5386@item knee 5387Curve the sharp knee around the threshold to enter gain reduction more softly. 5388Default is 2.828427125. Allowed range is from 1 to 8. 5389 5390@item detection 5391Choose if exact signal should be taken for detection or an RMS like one. 5392Default is rms. Can be peak or rms. 5393 5394@item link 5395Choose if the average level between all channels or the louder channel affects 5396the reduction. 5397Default is average. Can be average or maximum. 5398 5399@item level_sc 5400Set sidechain gain. Default is 1. Range is from 0.015625 to 64. 5401@end table 5402 5403@subsection Commands 5404 5405This filter supports the all above options as @ref{commands}. 5406 5407@section silencedetect 5408 5409Detect silence in an audio stream. 5410 5411This filter logs a message when it detects that the input audio volume is less 5412or equal to a noise tolerance value for a duration greater or equal to the 5413minimum detected noise duration. 5414 5415The printed times and duration are expressed in seconds. The 5416@code{lavfi.silence_start} or @code{lavfi.silence_start.X} metadata key 5417is set on the first frame whose timestamp equals or exceeds the detection 5418duration and it contains the timestamp of the first frame of the silence. 5419 5420The @code{lavfi.silence_duration} or @code{lavfi.silence_duration.X} 5421and @code{lavfi.silence_end} or @code{lavfi.silence_end.X} metadata 5422keys are set on the first frame after the silence. If @option{mono} is 5423enabled, and each channel is evaluated separately, the @code{.X} 5424suffixed keys are used, and @code{X} corresponds to the channel number. 5425 5426The filter accepts the following options: 5427 5428@table @option 5429@item noise, n 5430Set noise tolerance. Can be specified in dB (in case "dB" is appended to the 5431specified value) or amplitude ratio. Default is -60dB, or 0.001. 5432 5433@item duration, d 5434Set silence duration until notification (default is 2 seconds). See 5435@ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils} 5436for the accepted syntax. 5437 5438@item mono, m 5439Process each channel separately, instead of combined. By default is disabled. 5440@end table 5441 5442@subsection Examples 5443 5444@itemize 5445@item 5446Detect 5 seconds of silence with -50dB noise tolerance: 5447@example 5448silencedetect=n=-50dB:d=5 5449@end example 5450 5451@item 5452Complete example with @command{ffmpeg} to detect silence with 0.0001 noise 5453tolerance in @file{silence.mp3}: 5454@example 5455ffmpeg -i silence.mp3 -af silencedetect=noise=0.0001 -f null - 5456@end example 5457@end itemize 5458 5459@section silenceremove 5460 5461Remove silence from the beginning, middle or end of the audio. 5462 5463The filter accepts the following options: 5464 5465@table @option 5466@item start_periods 5467This value is used to indicate if audio should be trimmed at beginning of 5468the audio. A value of zero indicates no silence should be trimmed from the 5469beginning. When specifying a non-zero value, it trims audio up until it 5470finds non-silence. Normally, when trimming silence from beginning of audio 5471the @var{start_periods} will be @code{1} but it can be increased to higher 5472values to trim all audio up to specific count of non-silence periods. 5473Default value is @code{0}. 5474 5475@item start_duration 5476Specify the amount of time that non-silence must be detected before it stops 5477trimming audio. By increasing the duration, bursts of noises can be treated 5478as silence and trimmed off. Default value is @code{0}. 5479 5480@item start_threshold 5481This indicates what sample value should be treated as silence. For digital 5482audio, a value of @code{0} may be fine but for audio recorded from analog, 5483you may wish to increase the value to account for background noise. 5484Can be specified in dB (in case "dB" is appended to the specified value) 5485or amplitude ratio. Default value is @code{0}. 5486 5487@item start_silence 5488Specify max duration of silence at beginning that will be kept after 5489trimming. Default is 0, which is equal to trimming all samples detected 5490as silence. 5491 5492@item start_mode 5493Specify mode of detection of silence end in start of multi-channel audio. 5494Can be @var{any} or @var{all}. Default is @var{any}. 5495With @var{any}, any sample that is detected as non-silence will cause 5496stopped trimming of silence. 5497With @var{all}, only if all channels are detected as non-silence will cause 5498stopped trimming of silence. 5499 5500@item stop_periods 5501Set the count for trimming silence from the end of audio. 5502To remove silence from the middle of a file, specify a @var{stop_periods} 5503that is negative. This value is then treated as a positive value and is 5504used to indicate the effect should restart processing as specified by 5505@var{start_periods}, making it suitable for removing periods of silence 5506in the middle of the audio. 5507Default value is @code{0}. 5508 5509@item stop_duration 5510Specify a duration of silence that must exist before audio is not copied any 5511more. By specifying a higher duration, silence that is wanted can be left in 5512the audio. 5513Default value is @code{0}. 5514 5515@item stop_threshold 5516This is the same as @option{start_threshold} but for trimming silence from 5517the end of audio. 5518Can be specified in dB (in case "dB" is appended to the specified value) 5519or amplitude ratio. Default value is @code{0}. 5520 5521@item stop_silence 5522Specify max duration of silence at end that will be kept after 5523trimming. Default is 0, which is equal to trimming all samples detected 5524as silence. 5525 5526@item stop_mode 5527Specify mode of detection of silence start in end of multi-channel audio. 5528Can be @var{any} or @var{all}. Default is @var{any}. 5529With @var{any}, any sample that is detected as non-silence will cause 5530stopped trimming of silence. 5531With @var{all}, only if all channels are detected as non-silence will cause 5532stopped trimming of silence. 5533 5534@item detection 5535Set how is silence detected. Can be @code{rms} or @code{peak}. Second is faster 5536and works better with digital silence which is exactly 0. 5537Default value is @code{rms}. 5538 5539@item window 5540Set duration in number of seconds used to calculate size of window in number 5541of samples for detecting silence. 5542Default value is @code{0.02}. Allowed range is from @code{0} to @code{10}. 5543@end table 5544 5545@subsection Examples 5546 5547@itemize 5548@item 5549The following example shows how this filter can be used to start a recording 5550that does not contain the delay at the start which usually occurs between 5551pressing the record button and the start of the performance: 5552@example 5553silenceremove=start_periods=1:start_duration=5:start_threshold=0.02 5554@end example 5555 5556@item 5557Trim all silence encountered from beginning to end where there is more than 1 5558second of silence in audio: 5559@example 5560silenceremove=stop_periods=-1:stop_duration=1:stop_threshold=-90dB 5561@end example 5562 5563@item 5564Trim all digital silence samples, using peak detection, from beginning to end 5565where there is more than 0 samples of digital silence in audio and digital 5566silence is detected in all channels at same positions in stream: 5567@example 5568silenceremove=window=0:detection=peak:stop_mode=all:start_mode=all:stop_periods=-1:stop_threshold=0 5569@end example 5570@end itemize 5571 5572@section sofalizer 5573 5574SOFAlizer uses head-related transfer functions (HRTFs) to create virtual 5575loudspeakers around the user for binaural listening via headphones (audio 5576formats up to 9 channels supported). 5577The HRTFs are stored in SOFA files (see @url{http://www.sofacoustics.org/} for a database). 5578SOFAlizer is developed at the Acoustics Research Institute (ARI) of the 5579Austrian Academy of Sciences. 5580 5581To enable compilation of this filter you need to configure FFmpeg with 5582@code{--enable-libmysofa}. 5583 5584The filter accepts the following options: 5585 5586@table @option 5587@item sofa 5588Set the SOFA file used for rendering. 5589 5590@item gain 5591Set gain applied to audio. Value is in dB. Default is 0. 5592 5593@item rotation 5594Set rotation of virtual loudspeakers in deg. Default is 0. 5595 5596@item elevation 5597Set elevation of virtual speakers in deg. Default is 0. 5598 5599@item radius 5600Set distance in meters between loudspeakers and the listener with near-field 5601HRTFs. Default is 1. 5602 5603@item type 5604Set processing type. Can be @var{time} or @var{freq}. @var{time} is 5605processing audio in time domain which is slow. 5606@var{freq} is processing audio in frequency domain which is fast. 5607Default is @var{freq}. 5608 5609@item speakers 5610Set custom positions of virtual loudspeakers. Syntax for this option is: 5611<CH> <AZIM> <ELEV>[|<CH> <AZIM> <ELEV>|...]. 5612Each virtual loudspeaker is described with short channel name following with 5613azimuth and elevation in degrees. 5614Each virtual loudspeaker description is separated by '|'. 5615For example to override front left and front right channel positions use: 5616'speakers=FL 45 15|FR 345 15'. 5617Descriptions with unrecognised channel names are ignored. 5618 5619@item lfegain 5620Set custom gain for LFE channels. Value is in dB. Default is 0. 5621 5622@item framesize 5623Set custom frame size in number of samples. Default is 1024. 5624Allowed range is from 1024 to 96000. Only used if option @samp{type} 5625is set to @var{freq}. 5626 5627@item normalize 5628Should all IRs be normalized upon importing SOFA file. 5629By default is enabled. 5630 5631@item interpolate 5632Should nearest IRs be interpolated with neighbor IRs if exact position 5633does not match. By default is disabled. 5634 5635@item minphase 5636Minphase all IRs upon loading of SOFA file. By default is disabled. 5637 5638@item anglestep 5639Set neighbor search angle step. Only used if option @var{interpolate} is enabled. 5640 5641@item radstep 5642Set neighbor search radius step. Only used if option @var{interpolate} is enabled. 5643@end table 5644 5645@subsection Examples 5646 5647@itemize 5648@item 5649Using ClubFritz6 sofa file: 5650@example 5651sofalizer=sofa=/path/to/ClubFritz6.sofa:type=freq:radius=1 5652@end example 5653 5654@item 5655Using ClubFritz12 sofa file and bigger radius with small rotation: 5656@example 5657sofalizer=sofa=/path/to/ClubFritz12.sofa:type=freq:radius=2:rotation=5 5658@end example 5659 5660@item 5661Similar as above but with custom speaker positions for front left, front right, back left and back right 5662and also with custom gain: 5663@example 5664"sofalizer=sofa=/path/to/ClubFritz6.sofa:type=freq:radius=2:speakers=FL 45|FR 315|BL 135|BR 225:gain=28" 5665@end example 5666@end itemize 5667 5668@section speechnorm 5669Speech Normalizer. 5670 5671This filter expands or compresses each half-cycle of audio samples 5672(local set of samples all above or all below zero and between two nearest zero crossings) depending 5673on threshold value, so audio reaches target peak value under conditions controlled by below options. 5674 5675The filter accepts the following options: 5676 5677@table @option 5678@item peak, p 5679Set the expansion target peak value. This specifies the highest allowed absolute amplitude 5680level for the normalized audio input. Default value is 0.95. Allowed range is from 0.0 to 1.0. 5681 5682@item expansion, e 5683Set the maximum expansion factor. Allowed range is from 1.0 to 50.0. Default value is 2.0. 5684This option controls maximum local half-cycle of samples expansion. The maximum expansion 5685would be such that local peak value reaches target peak value but never to surpass it and that 5686ratio between new and previous peak value does not surpass this option value. 5687 5688@item compression, c 5689Set the maximum compression factor. Allowed range is from 1.0 to 50.0. Default value is 2.0. 5690This option controls maximum local half-cycle of samples compression. This option is used 5691only if @option{threshold} option is set to value greater than 0.0, then in such cases 5692when local peak is lower or same as value set by @option{threshold} all samples belonging to 5693that peak's half-cycle will be compressed by current compression factor. 5694 5695@item threshold, t 5696Set the threshold value. Default value is 0.0. Allowed range is from 0.0 to 1.0. 5697This option specifies which half-cycles of samples will be compressed and which will be expanded. 5698Any half-cycle samples with their local peak value below or same as this option value will be 5699compressed by current compression factor, otherwise, if greater than threshold value they will be 5700expanded with expansion factor so that it could reach peak target value but never surpass it. 5701 5702@item raise, r 5703Set the expansion raising amount per each half-cycle of samples. Default value is 0.001. 5704Allowed range is from 0.0 to 1.0. This controls how fast expansion factor is raised per 5705each new half-cycle until it reaches @option{expansion} value. 5706Setting this options too high may lead to distortions. 5707 5708@item fall, f 5709Set the compression raising amount per each half-cycle of samples. Default value is 0.001. 5710Allowed range is from 0.0 to 1.0. This controls how fast compression factor is raised per 5711each new half-cycle until it reaches @option{compression} value. 5712 5713@item channels, h 5714Specify which channels to filter, by default all available channels are filtered. 5715 5716@item invert, i 5717Enable inverted filtering, by default is disabled. This inverts interpretation of @option{threshold} 5718option. When enabled any half-cycle of samples with their local peak value below or same as 5719@option{threshold} option will be expanded otherwise it will be compressed. 5720 5721@item link, l 5722Link channels when calculating gain applied to each filtered channel sample, by default is disabled. 5723When disabled each filtered channel gain calculation is independent, otherwise when this option 5724is enabled the minimum of all possible gains for each filtered channel is used. 5725@end table 5726 5727@subsection Commands 5728 5729This filter supports the all above options as @ref{commands}. 5730 5731@section stereotools 5732 5733This filter has some handy utilities to manage stereo signals, for converting 5734M/S stereo recordings to L/R signal while having control over the parameters 5735or spreading the stereo image of master track. 5736 5737The filter accepts the following options: 5738 5739@table @option 5740@item level_in 5741Set input level before filtering for both channels. Defaults is 1. 5742Allowed range is from 0.015625 to 64. 5743 5744@item level_out 5745Set output level after filtering for both channels. Defaults is 1. 5746Allowed range is from 0.015625 to 64. 5747 5748@item balance_in 5749Set input balance between both channels. Default is 0. 5750Allowed range is from -1 to 1. 5751 5752@item balance_out 5753Set output balance between both channels. Default is 0. 5754Allowed range is from -1 to 1. 5755 5756@item softclip 5757Enable softclipping. Results in analog distortion instead of harsh digital 0dB 5758clipping. Disabled by default. 5759 5760@item mutel 5761Mute the left channel. Disabled by default. 5762 5763@item muter 5764Mute the right channel. Disabled by default. 5765 5766@item phasel 5767Change the phase of the left channel. Disabled by default. 5768 5769@item phaser 5770Change the phase of the right channel. Disabled by default. 5771 5772@item mode 5773Set stereo mode. Available values are: 5774 5775@table @samp 5776@item lr>lr 5777Left/Right to Left/Right, this is default. 5778 5779@item lr>ms 5780Left/Right to Mid/Side. 5781 5782@item ms>lr 5783Mid/Side to Left/Right. 5784 5785@item lr>ll 5786Left/Right to Left/Left. 5787 5788@item lr>rr 5789Left/Right to Right/Right. 5790 5791@item lr>l+r 5792Left/Right to Left + Right. 5793 5794@item lr>rl 5795Left/Right to Right/Left. 5796 5797@item ms>ll 5798Mid/Side to Left/Left. 5799 5800@item ms>rr 5801Mid/Side to Right/Right. 5802 5803@item ms>rl 5804Mid/Side to Right/Left. 5805 5806@item lr>l-r 5807Left/Right to Left - Right. 5808@end table 5809 5810@item slev 5811Set level of side signal. Default is 1. 5812Allowed range is from 0.015625 to 64. 5813 5814@item sbal 5815Set balance of side signal. Default is 0. 5816Allowed range is from -1 to 1. 5817 5818@item mlev 5819Set level of the middle signal. Default is 1. 5820Allowed range is from 0.015625 to 64. 5821 5822@item mpan 5823Set middle signal pan. Default is 0. Allowed range is from -1 to 1. 5824 5825@item base 5826Set stereo base between mono and inversed channels. Default is 0. 5827Allowed range is from -1 to 1. 5828 5829@item delay 5830Set delay in milliseconds how much to delay left from right channel and 5831vice versa. Default is 0. Allowed range is from -20 to 20. 5832 5833@item sclevel 5834Set S/C level. Default is 1. Allowed range is from 1 to 100. 5835 5836@item phase 5837Set the stereo phase in degrees. Default is 0. Allowed range is from 0 to 360. 5838 5839@item bmode_in, bmode_out 5840Set balance mode for balance_in/balance_out option. 5841 5842Can be one of the following: 5843 5844@table @samp 5845@item balance 5846Classic balance mode. Attenuate one channel at time. 5847Gain is raised up to 1. 5848 5849@item amplitude 5850Similar as classic mode above but gain is raised up to 2. 5851 5852@item power 5853Equal power distribution, from -6dB to +6dB range. 5854@end table 5855@end table 5856 5857@subsection Commands 5858 5859This filter supports the all above options as @ref{commands}. 5860 5861@subsection Examples 5862 5863@itemize 5864@item 5865Apply karaoke like effect: 5866@example 5867stereotools=mlev=0.015625 5868@end example 5869 5870@item 5871Convert M/S signal to L/R: 5872@example 5873"stereotools=mode=ms>lr" 5874@end example 5875@end itemize 5876 5877@section stereowiden 5878 5879This filter enhance the stereo effect by suppressing signal common to both 5880channels and by delaying the signal of left into right and vice versa, 5881thereby widening the stereo effect. 5882 5883The filter accepts the following options: 5884 5885@table @option 5886@item delay 5887Time in milliseconds of the delay of left signal into right and vice versa. 5888Default is 20 milliseconds. 5889 5890@item feedback 5891Amount of gain in delayed signal into right and vice versa. Gives a delay 5892effect of left signal in right output and vice versa which gives widening 5893effect. Default is 0.3. 5894 5895@item crossfeed 5896Cross feed of left into right with inverted phase. This helps in suppressing 5897the mono. If the value is 1 it will cancel all the signal common to both 5898channels. Default is 0.3. 5899 5900@item drymix 5901Set level of input signal of original channel. Default is 0.8. 5902@end table 5903 5904@subsection Commands 5905 5906This filter supports the all above options except @code{delay} as @ref{commands}. 5907 5908@section superequalizer 5909Apply 18 band equalizer. 5910 5911The filter accepts the following options: 5912@table @option 5913@item 1b 5914Set 65Hz band gain. 5915@item 2b 5916Set 92Hz band gain. 5917@item 3b 5918Set 131Hz band gain. 5919@item 4b 5920Set 185Hz band gain. 5921@item 5b 5922Set 262Hz band gain. 5923@item 6b 5924Set 370Hz band gain. 5925@item 7b 5926Set 523Hz band gain. 5927@item 8b 5928Set 740Hz band gain. 5929@item 9b 5930Set 1047Hz band gain. 5931@item 10b 5932Set 1480Hz band gain. 5933@item 11b 5934Set 2093Hz band gain. 5935@item 12b 5936Set 2960Hz band gain. 5937@item 13b 5938Set 4186Hz band gain. 5939@item 14b 5940Set 5920Hz band gain. 5941@item 15b 5942Set 8372Hz band gain. 5943@item 16b 5944Set 11840Hz band gain. 5945@item 17b 5946Set 16744Hz band gain. 5947@item 18b 5948Set 20000Hz band gain. 5949@end table 5950 5951@section surround 5952Apply audio surround upmix filter. 5953 5954This filter allows to produce multichannel output from audio stream. 5955 5956The filter accepts the following options: 5957 5958@table @option 5959@item chl_out 5960Set output channel layout. By default, this is @var{5.1}. 5961 5962See @ref{channel layout syntax,,the Channel Layout section in the ffmpeg-utils(1) manual,ffmpeg-utils} 5963for the required syntax. 5964 5965@item chl_in 5966Set input channel layout. By default, this is @var{stereo}. 5967 5968See @ref{channel layout syntax,,the Channel Layout section in the ffmpeg-utils(1) manual,ffmpeg-utils} 5969for the required syntax. 5970 5971@item level_in 5972Set input volume level. By default, this is @var{1}. 5973 5974@item level_out 5975Set output volume level. By default, this is @var{1}. 5976 5977@item lfe 5978Enable LFE channel output if output channel layout has it. By default, this is enabled. 5979 5980@item lfe_low 5981Set LFE low cut off frequency. By default, this is @var{128} Hz. 5982 5983@item lfe_high 5984Set LFE high cut off frequency. By default, this is @var{256} Hz. 5985 5986@item lfe_mode 5987Set LFE mode, can be @var{add} or @var{sub}. Default is @var{add}. 5988In @var{add} mode, LFE channel is created from input audio and added to output. 5989In @var{sub} mode, LFE channel is created from input audio and added to output but 5990also all non-LFE output channels are subtracted with output LFE channel. 5991 5992@item angle 5993Set angle of stereo surround transform, Allowed range is from @var{0} to @var{360}. 5994Default is @var{90}. 5995 5996@item fc_in 5997Set front center input volume. By default, this is @var{1}. 5998 5999@item fc_out 6000Set front center output volume. By default, this is @var{1}. 6001 6002@item fl_in 6003Set front left input volume. By default, this is @var{1}. 6004 6005@item fl_out 6006Set front left output volume. By default, this is @var{1}. 6007 6008@item fr_in 6009Set front right input volume. By default, this is @var{1}. 6010 6011@item fr_out 6012Set front right output volume. By default, this is @var{1}. 6013 6014@item sl_in 6015Set side left input volume. By default, this is @var{1}. 6016 6017@item sl_out 6018Set side left output volume. By default, this is @var{1}. 6019 6020@item sr_in 6021Set side right input volume. By default, this is @var{1}. 6022 6023@item sr_out 6024Set side right output volume. By default, this is @var{1}. 6025 6026@item bl_in 6027Set back left input volume. By default, this is @var{1}. 6028 6029@item bl_out 6030Set back left output volume. By default, this is @var{1}. 6031 6032@item br_in 6033Set back right input volume. By default, this is @var{1}. 6034 6035@item br_out 6036Set back right output volume. By default, this is @var{1}. 6037 6038@item bc_in 6039Set back center input volume. By default, this is @var{1}. 6040 6041@item bc_out 6042Set back center output volume. By default, this is @var{1}. 6043 6044@item lfe_in 6045Set LFE input volume. By default, this is @var{1}. 6046 6047@item lfe_out 6048Set LFE output volume. By default, this is @var{1}. 6049 6050@item allx 6051Set spread usage of stereo image across X axis for all channels. 6052 6053@item ally 6054Set spread usage of stereo image across Y axis for all channels. 6055 6056@item fcx, flx, frx, blx, brx, slx, srx, bcx 6057Set spread usage of stereo image across X axis for each channel. 6058 6059@item fcy, fly, fry, bly, bry, sly, sry, bcy 6060Set spread usage of stereo image across Y axis for each channel. 6061 6062@item win_size 6063Set window size. Allowed range is from @var{1024} to @var{65536}. Default size is @var{4096}. 6064 6065@item win_func 6066Set window function. 6067 6068It accepts the following values: 6069@table @samp 6070@item rect 6071@item bartlett 6072@item hann, hanning 6073@item hamming 6074@item blackman 6075@item welch 6076@item flattop 6077@item bharris 6078@item bnuttall 6079@item bhann 6080@item sine 6081@item nuttall 6082@item lanczos 6083@item gauss 6084@item tukey 6085@item dolph 6086@item cauchy 6087@item parzen 6088@item poisson 6089@item bohman 6090@end table 6091Default is @code{hann}. 6092 6093@item overlap 6094Set window overlap. If set to 1, the recommended overlap for selected 6095window function will be picked. Default is @code{0.5}. 6096@end table 6097 6098@section treble, highshelf 6099 6100Boost or cut treble (upper) frequencies of the audio using a two-pole 6101shelving filter with a response similar to that of a standard 6102hi-fi's tone-controls. This is also known as shelving equalisation (EQ). 6103 6104The filter accepts the following options: 6105 6106@table @option 6107@item gain, g 6108Give the gain at whichever is the lower of ~22 kHz and the 6109Nyquist frequency. Its useful range is about -20 (for a large cut) 6110to +20 (for a large boost). Beware of clipping when using a positive gain. 6111 6112@item frequency, f 6113Set the filter's central frequency and so can be used 6114to extend or reduce the frequency range to be boosted or cut. 6115The default value is @code{3000} Hz. 6116 6117@item width_type, t 6118Set method to specify band-width of filter. 6119@table @option 6120@item h 6121Hz 6122@item q 6123Q-Factor 6124@item o 6125octave 6126@item s 6127slope 6128@item k 6129kHz 6130@end table 6131 6132@item width, w 6133Determine how steep is the filter's shelf transition. 6134 6135@item poles, p 6136Set number of poles. Default is 2. 6137 6138@item mix, m 6139How much to use filtered signal in output. Default is 1. 6140Range is between 0 and 1. 6141 6142@item channels, c 6143Specify which channels to filter, by default all available are filtered. 6144 6145@item normalize, n 6146Normalize biquad coefficients, by default is disabled. 6147Enabling it will normalize magnitude response at DC to 0dB. 6148 6149@item transform, a 6150Set transform type of IIR filter. 6151@table @option 6152@item di 6153@item dii 6154@item tdii 6155@item latt 6156@end table 6157 6158@item precision, r 6159Set precison of filtering. 6160@table @option 6161@item auto 6162Pick automatic sample format depending on surround filters. 6163@item s16 6164Always use signed 16-bit. 6165@item s32 6166Always use signed 32-bit. 6167@item f32 6168Always use float 32-bit. 6169@item f64 6170Always use float 64-bit. 6171@end table 6172@end table 6173 6174@subsection Commands 6175 6176This filter supports the following commands: 6177@table @option 6178@item frequency, f 6179Change treble frequency. 6180Syntax for the command is : "@var{frequency}" 6181 6182@item width_type, t 6183Change treble width_type. 6184Syntax for the command is : "@var{width_type}" 6185 6186@item width, w 6187Change treble width. 6188Syntax for the command is : "@var{width}" 6189 6190@item gain, g 6191Change treble gain. 6192Syntax for the command is : "@var{gain}" 6193 6194@item mix, m 6195Change treble mix. 6196Syntax for the command is : "@var{mix}" 6197@end table 6198 6199@section tremolo 6200 6201Sinusoidal amplitude modulation. 6202 6203The filter accepts the following options: 6204 6205@table @option 6206@item f 6207Modulation frequency in Hertz. Modulation frequencies in the subharmonic range 6208(20 Hz or lower) will result in a tremolo effect. 6209This filter may also be used as a ring modulator by specifying 6210a modulation frequency higher than 20 Hz. 6211Range is 0.1 - 20000.0. Default value is 5.0 Hz. 6212 6213@item d 6214Depth of modulation as a percentage. Range is 0.0 - 1.0. 6215Default value is 0.5. 6216@end table 6217 6218@section vibrato 6219 6220Sinusoidal phase modulation. 6221 6222The filter accepts the following options: 6223 6224@table @option 6225@item f 6226Modulation frequency in Hertz. 6227Range is 0.1 - 20000.0. Default value is 5.0 Hz. 6228 6229@item d 6230Depth of modulation as a percentage. Range is 0.0 - 1.0. 6231Default value is 0.5. 6232@end table 6233 6234@section volume 6235 6236Adjust the input audio volume. 6237 6238It accepts the following parameters: 6239@table @option 6240 6241@item volume 6242Set audio volume expression. 6243 6244Output values are clipped to the maximum value. 6245 6246The output audio volume is given by the relation: 6247@example 6248@var{output_volume} = @var{volume} * @var{input_volume} 6249@end example 6250 6251The default value for @var{volume} is "1.0". 6252 6253@item precision 6254This parameter represents the mathematical precision. 6255 6256It determines which input sample formats will be allowed, which affects the 6257precision of the volume scaling. 6258 6259@table @option 6260@item fixed 62618-bit fixed-point; this limits input sample format to U8, S16, and S32. 6262@item float 626332-bit floating-point; this limits input sample format to FLT. (default) 6264@item double 626564-bit floating-point; this limits input sample format to DBL. 6266@end table 6267 6268@item replaygain 6269Choose the behaviour on encountering ReplayGain side data in input frames. 6270 6271@table @option 6272@item drop 6273Remove ReplayGain side data, ignoring its contents (the default). 6274 6275@item ignore 6276Ignore ReplayGain side data, but leave it in the frame. 6277 6278@item track 6279Prefer the track gain, if present. 6280 6281@item album 6282Prefer the album gain, if present. 6283@end table 6284 6285@item replaygain_preamp 6286Pre-amplification gain in dB to apply to the selected replaygain gain. 6287 6288Default value for @var{replaygain_preamp} is 0.0. 6289 6290@item replaygain_noclip 6291Prevent clipping by limiting the gain applied. 6292 6293Default value for @var{replaygain_noclip} is 1. 6294 6295@item eval 6296Set when the volume expression is evaluated. 6297 6298It accepts the following values: 6299@table @samp 6300@item once 6301only evaluate expression once during the filter initialization, or 6302when the @samp{volume} command is sent 6303 6304@item frame 6305evaluate expression for each incoming frame 6306@end table 6307 6308Default value is @samp{once}. 6309@end table 6310 6311The volume expression can contain the following parameters. 6312 6313@table @option 6314@item n 6315frame number (starting at zero) 6316@item nb_channels 6317number of channels 6318@item nb_consumed_samples 6319number of samples consumed by the filter 6320@item nb_samples 6321number of samples in the current frame 6322@item pos 6323original frame position in the file 6324@item pts 6325frame PTS 6326@item sample_rate 6327sample rate 6328@item startpts 6329PTS at start of stream 6330@item startt 6331time at start of stream 6332@item t 6333frame time 6334@item tb 6335timestamp timebase 6336@item volume 6337last set volume value 6338@end table 6339 6340Note that when @option{eval} is set to @samp{once} only the 6341@var{sample_rate} and @var{tb} variables are available, all other 6342variables will evaluate to NAN. 6343 6344@subsection Commands 6345 6346This filter supports the following commands: 6347@table @option 6348@item volume 6349Modify the volume expression. 6350The command accepts the same syntax of the corresponding option. 6351 6352If the specified expression is not valid, it is kept at its current 6353value. 6354@end table 6355 6356@subsection Examples 6357 6358@itemize 6359@item 6360Halve the input audio volume: 6361@example 6362volume=volume=0.5 6363volume=volume=1/2 6364volume=volume=-6.0206dB 6365@end example 6366 6367In all the above example the named key for @option{volume} can be 6368omitted, for example like in: 6369@example 6370volume=0.5 6371@end example 6372 6373@item 6374Increase input audio power by 6 decibels using fixed-point precision: 6375@example 6376volume=volume=6dB:precision=fixed 6377@end example 6378 6379@item 6380Fade volume after time 10 with an annihilation period of 5 seconds: 6381@example 6382volume='if(lt(t,10),1,max(1-(t-10)/5,0))':eval=frame 6383@end example 6384@end itemize 6385 6386@section volumedetect 6387 6388Detect the volume of the input video. 6389 6390The filter has no parameters. The input is not modified. Statistics about 6391the volume will be printed in the log when the input stream end is reached. 6392 6393In particular it will show the mean volume (root mean square), maximum 6394volume (on a per-sample basis), and the beginning of a histogram of the 6395registered volume values (from the maximum value to a cumulated 1/1000 of 6396the samples). 6397 6398All volumes are in decibels relative to the maximum PCM value. 6399 6400@subsection Examples 6401 6402Here is an excerpt of the output: 6403@example 6404[Parsed_volumedetect_0 @ 0xa23120] mean_volume: -27 dB 6405[Parsed_volumedetect_0 @ 0xa23120] max_volume: -4 dB 6406[Parsed_volumedetect_0 @ 0xa23120] histogram_4db: 6 6407[Parsed_volumedetect_0 @ 0xa23120] histogram_5db: 62 6408[Parsed_volumedetect_0 @ 0xa23120] histogram_6db: 286 6409[Parsed_volumedetect_0 @ 0xa23120] histogram_7db: 1042 6410[Parsed_volumedetect_0 @ 0xa23120] histogram_8db: 2551 6411[Parsed_volumedetect_0 @ 0xa23120] histogram_9db: 4609 6412[Parsed_volumedetect_0 @ 0xa23120] histogram_10db: 8409 6413@end example 6414 6415It means that: 6416@itemize 6417@item 6418The mean square energy is approximately -27 dB, or 10^-2.7. 6419@item 6420The largest sample is at -4 dB, or more precisely between -4 dB and -5 dB. 6421@item 6422There are 6 samples at -4 dB, 62 at -5 dB, 286 at -6 dB, etc. 6423@end itemize 6424 6425In other words, raising the volume by +4 dB does not cause any clipping, 6426raising it by +5 dB causes clipping for 6 samples, etc. 6427 6428@c man end AUDIO FILTERS 6429 6430@chapter Audio Sources 6431@c man begin AUDIO SOURCES 6432 6433Below is a description of the currently available audio sources. 6434 6435@section abuffer 6436 6437Buffer audio frames, and make them available to the filter chain. 6438 6439This source is mainly intended for a programmatic use, in particular 6440through the interface defined in @file{libavfilter/buffersrc.h}. 6441 6442It accepts the following parameters: 6443@table @option 6444 6445@item time_base 6446The timebase which will be used for timestamps of submitted frames. It must be 6447either a floating-point number or in @var{numerator}/@var{denominator} form. 6448 6449@item sample_rate 6450The sample rate of the incoming audio buffers. 6451 6452@item sample_fmt 6453The sample format of the incoming audio buffers. 6454Either a sample format name or its corresponding integer representation from 6455the enum AVSampleFormat in @file{libavutil/samplefmt.h} 6456 6457@item channel_layout 6458The channel layout of the incoming audio buffers. 6459Either a channel layout name from channel_layout_map in 6460@file{libavutil/channel_layout.c} or its corresponding integer representation 6461from the AV_CH_LAYOUT_* macros in @file{libavutil/channel_layout.h} 6462 6463@item channels 6464The number of channels of the incoming audio buffers. 6465If both @var{channels} and @var{channel_layout} are specified, then they 6466must be consistent. 6467 6468@end table 6469 6470@subsection Examples 6471 6472@example 6473abuffer=sample_rate=44100:sample_fmt=s16p:channel_layout=stereo 6474@end example 6475 6476will instruct the source to accept planar 16bit signed stereo at 44100Hz. 6477Since the sample format with name "s16p" corresponds to the number 64786 and the "stereo" channel layout corresponds to the value 0x3, this is 6479equivalent to: 6480@example 6481abuffer=sample_rate=44100:sample_fmt=6:channel_layout=0x3 6482@end example 6483 6484@section aevalsrc 6485 6486Generate an audio signal specified by an expression. 6487 6488This source accepts in input one or more expressions (one for each 6489channel), which are evaluated and used to generate a corresponding 6490audio signal. 6491 6492This source accepts the following options: 6493 6494@table @option 6495@item exprs 6496Set the '|'-separated expressions list for each separate channel. In case the 6497@option{channel_layout} option is not specified, the selected channel layout 6498depends on the number of provided expressions. Otherwise the last 6499specified expression is applied to the remaining output channels. 6500 6501@item channel_layout, c 6502Set the channel layout. The number of channels in the specified layout 6503must be equal to the number of specified expressions. 6504 6505@item duration, d 6506Set the minimum duration of the sourced audio. See 6507@ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils} 6508for the accepted syntax. 6509Note that the resulting duration may be greater than the specified 6510duration, as the generated audio is always cut at the end of a 6511complete frame. 6512 6513If not specified, or the expressed duration is negative, the audio is 6514supposed to be generated forever. 6515 6516@item nb_samples, n 6517Set the number of samples per channel per each output frame, 6518default to 1024. 6519 6520@item sample_rate, s 6521Specify the sample rate, default to 44100. 6522@end table 6523 6524Each expression in @var{exprs} can contain the following constants: 6525 6526@table @option 6527@item n 6528number of the evaluated sample, starting from 0 6529 6530@item t 6531time of the evaluated sample expressed in seconds, starting from 0 6532 6533@item s 6534sample rate 6535 6536@end table 6537 6538@subsection Examples 6539 6540@itemize 6541@item 6542Generate silence: 6543@example 6544aevalsrc=0 6545@end example 6546 6547@item 6548Generate a sin signal with frequency of 440 Hz, set sample rate to 65498000 Hz: 6550@example 6551aevalsrc="sin(440*2*PI*t):s=8000" 6552@end example 6553 6554@item 6555Generate a two channels signal, specify the channel layout (Front 6556Center + Back Center) explicitly: 6557@example 6558aevalsrc="sin(420*2*PI*t)|cos(430*2*PI*t):c=FC|BC" 6559@end example 6560 6561@item 6562Generate white noise: 6563@example 6564aevalsrc="-2+random(0)" 6565@end example 6566 6567@item 6568Generate an amplitude modulated signal: 6569@example 6570aevalsrc="sin(10*2*PI*t)*sin(880*2*PI*t)" 6571@end example 6572 6573@item 6574Generate 2.5 Hz binaural beats on a 360 Hz carrier: 6575@example 6576aevalsrc="0.1*sin(2*PI*(360-2.5/2)*t) | 0.1*sin(2*PI*(360+2.5/2)*t)" 6577@end example 6578 6579@end itemize 6580 6581@section afirsrc 6582 6583Generate a FIR coefficients using frequency sampling method. 6584 6585The resulting stream can be used with @ref{afir} filter for filtering the audio signal. 6586 6587The filter accepts the following options: 6588 6589@table @option 6590@item taps, t 6591Set number of filter coefficents in output audio stream. 6592Default value is 1025. 6593 6594@item frequency, f 6595Set frequency points from where magnitude and phase are set. 6596This must be in non decreasing order, and first element must be 0, while last element 6597must be 1. Elements are separated by white spaces. 6598 6599@item magnitude, m 6600Set magnitude value for every frequency point set by @option{frequency}. 6601Number of values must be same as number of frequency points. 6602Values are separated by white spaces. 6603 6604@item phase, p 6605Set phase value for every frequency point set by @option{frequency}. 6606Number of values must be same as number of frequency points. 6607Values are separated by white spaces. 6608 6609@item sample_rate, r 6610Set sample rate, default is 44100. 6611 6612@item nb_samples, n 6613Set number of samples per each frame. Default is 1024. 6614 6615@item win_func, w 6616Set window function. Default is blackman. 6617@end table 6618 6619@section anullsrc 6620 6621The null audio source, return unprocessed audio frames. It is mainly useful 6622as a template and to be employed in analysis / debugging tools, or as 6623the source for filters which ignore the input data (for example the sox 6624synth filter). 6625 6626This source accepts the following options: 6627 6628@table @option 6629 6630@item channel_layout, cl 6631 6632Specifies the channel layout, and can be either an integer or a string 6633representing a channel layout. The default value of @var{channel_layout} 6634is "stereo". 6635 6636Check the channel_layout_map definition in 6637@file{libavutil/channel_layout.c} for the mapping between strings and 6638channel layout values. 6639 6640@item sample_rate, r 6641Specifies the sample rate, and defaults to 44100. 6642 6643@item nb_samples, n 6644Set the number of samples per requested frames. 6645 6646@item duration, d 6647Set the duration of the sourced audio. See 6648@ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils} 6649for the accepted syntax. 6650 6651If not specified, or the expressed duration is negative, the audio is 6652supposed to be generated forever. 6653@end table 6654 6655@subsection Examples 6656 6657@itemize 6658@item 6659Set the sample rate to 48000 Hz and the channel layout to AV_CH_LAYOUT_MONO. 6660@example 6661anullsrc=r=48000:cl=4 6662@end example 6663 6664@item 6665Do the same operation with a more obvious syntax: 6666@example 6667anullsrc=r=48000:cl=mono 6668@end example 6669@end itemize 6670 6671All the parameters need to be explicitly defined. 6672 6673@section flite 6674 6675Synthesize a voice utterance using the libflite library. 6676 6677To enable compilation of this filter you need to configure FFmpeg with 6678@code{--enable-libflite}. 6679 6680Note that versions of the flite library prior to 2.0 are not thread-safe. 6681 6682The filter accepts the following options: 6683 6684@table @option 6685 6686@item list_voices 6687If set to 1, list the names of the available voices and exit 6688immediately. Default value is 0. 6689 6690@item nb_samples, n 6691Set the maximum number of samples per frame. Default value is 512. 6692 6693@item textfile 6694Set the filename containing the text to speak. 6695 6696@item text 6697Set the text to speak. 6698 6699@item voice, v 6700Set the voice to use for the speech synthesis. Default value is 6701@code{kal}. See also the @var{list_voices} option. 6702@end table 6703 6704@subsection Examples 6705 6706@itemize 6707@item 6708Read from file @file{speech.txt}, and synthesize the text using the 6709standard flite voice: 6710@example 6711flite=textfile=speech.txt 6712@end example 6713 6714@item 6715Read the specified text selecting the @code{slt} voice: 6716@example 6717flite=text='So fare thee well, poor devil of a Sub-Sub, whose commentator I am':voice=slt 6718@end example 6719 6720@item 6721Input text to ffmpeg: 6722@example 6723ffmpeg -f lavfi -i flite=text='So fare thee well, poor devil of a Sub-Sub, whose commentator I am':voice=slt 6724@end example 6725 6726@item 6727Make @file{ffplay} speak the specified text, using @code{flite} and 6728the @code{lavfi} device: 6729@example 6730ffplay -f lavfi flite=text='No more be grieved for which that thou hast done.' 6731@end example 6732@end itemize 6733 6734For more information about libflite, check: 6735@url{http://www.festvox.org/flite/} 6736 6737@section anoisesrc 6738 6739Generate a noise audio signal. 6740 6741The filter accepts the following options: 6742 6743@table @option 6744@item sample_rate, r 6745Specify the sample rate. Default value is 48000 Hz. 6746 6747@item amplitude, a 6748Specify the amplitude (0.0 - 1.0) of the generated audio stream. Default value 6749is 1.0. 6750 6751@item duration, d 6752Specify the duration of the generated audio stream. Not specifying this option 6753results in noise with an infinite length. 6754 6755@item color, colour, c 6756Specify the color of noise. Available noise colors are white, pink, brown, 6757blue, violet and velvet. Default color is white. 6758 6759@item seed, s 6760Specify a value used to seed the PRNG. 6761 6762@item nb_samples, n 6763Set the number of samples per each output frame, default is 1024. 6764@end table 6765 6766@subsection Examples 6767 6768@itemize 6769 6770@item 6771Generate 60 seconds of pink noise, with a 44.1 kHz sampling rate and an amplitude of 0.5: 6772@example 6773anoisesrc=d=60:c=pink:r=44100:a=0.5 6774@end example 6775@end itemize 6776 6777@section hilbert 6778 6779Generate odd-tap Hilbert transform FIR coefficients. 6780 6781The resulting stream can be used with @ref{afir} filter for phase-shifting 6782the signal by 90 degrees. 6783 6784This is used in many matrix coding schemes and for analytic signal generation. 6785The process is often written as a multiplication by i (or j), the imaginary unit. 6786 6787The filter accepts the following options: 6788 6789@table @option 6790 6791@item sample_rate, s 6792Set sample rate, default is 44100. 6793 6794@item taps, t 6795Set length of FIR filter, default is 22051. 6796 6797@item nb_samples, n 6798Set number of samples per each frame. 6799 6800@item win_func, w 6801Set window function to be used when generating FIR coefficients. 6802@end table 6803 6804@section sinc 6805 6806Generate a sinc kaiser-windowed low-pass, high-pass, band-pass, or band-reject FIR coefficients. 6807 6808The resulting stream can be used with @ref{afir} filter for filtering the audio signal. 6809 6810The filter accepts the following options: 6811 6812@table @option 6813@item sample_rate, r 6814Set sample rate, default is 44100. 6815 6816@item nb_samples, n 6817Set number of samples per each frame. Default is 1024. 6818 6819@item hp 6820Set high-pass frequency. Default is 0. 6821 6822@item lp 6823Set low-pass frequency. Default is 0. 6824If high-pass frequency is lower than low-pass frequency and low-pass frequency 6825is higher than 0 then filter will create band-pass filter coefficients, 6826otherwise band-reject filter coefficients. 6827 6828@item phase 6829Set filter phase response. Default is 50. Allowed range is from 0 to 100. 6830 6831@item beta 6832Set Kaiser window beta. 6833 6834@item att 6835Set stop-band attenuation. Default is 120dB, allowed range is from 40 to 180 dB. 6836 6837@item round 6838Enable rounding, by default is disabled. 6839 6840@item hptaps 6841Set number of taps for high-pass filter. 6842 6843@item lptaps 6844Set number of taps for low-pass filter. 6845@end table 6846 6847@section sine 6848 6849Generate an audio signal made of a sine wave with amplitude 1/8. 6850 6851The audio signal is bit-exact. 6852 6853The filter accepts the following options: 6854 6855@table @option 6856 6857@item frequency, f 6858Set the carrier frequency. Default is 440 Hz. 6859 6860@item beep_factor, b 6861Enable a periodic beep every second with frequency @var{beep_factor} times 6862the carrier frequency. Default is 0, meaning the beep is disabled. 6863 6864@item sample_rate, r 6865Specify the sample rate, default is 44100. 6866 6867@item duration, d 6868Specify the duration of the generated audio stream. 6869 6870@item samples_per_frame 6871Set the number of samples per output frame. 6872 6873The expression can contain the following constants: 6874 6875@table @option 6876@item n 6877The (sequential) number of the output audio frame, starting from 0. 6878 6879@item pts 6880The PTS (Presentation TimeStamp) of the output audio frame, 6881expressed in @var{TB} units. 6882 6883@item t 6884The PTS of the output audio frame, expressed in seconds. 6885 6886@item TB 6887The timebase of the output audio frames. 6888@end table 6889 6890Default is @code{1024}. 6891@end table 6892 6893@subsection Examples 6894 6895@itemize 6896 6897@item 6898Generate a simple 440 Hz sine wave: 6899@example 6900sine 6901@end example 6902 6903@item 6904Generate a 220 Hz sine wave with a 880 Hz beep each second, for 5 seconds: 6905@example 6906sine=220:4:d=5 6907sine=f=220:b=4:d=5 6908sine=frequency=220:beep_factor=4:duration=5 6909@end example 6910 6911@item 6912Generate a 1 kHz sine wave following @code{1602,1601,1602,1601,1602} NTSC 6913pattern: 6914@example 6915sine=1000:samples_per_frame='st(0,mod(n,5)); 1602-not(not(eq(ld(0),1)+eq(ld(0),3)))' 6916@end example 6917@end itemize 6918 6919@c man end AUDIO SOURCES 6920 6921@chapter Audio Sinks 6922@c man begin AUDIO SINKS 6923 6924Below is a description of the currently available audio sinks. 6925 6926@section abuffersink 6927 6928Buffer audio frames, and make them available to the end of filter chain. 6929 6930This sink is mainly intended for programmatic use, in particular 6931through the interface defined in @file{libavfilter/buffersink.h} 6932or the options system. 6933 6934It accepts a pointer to an AVABufferSinkContext structure, which 6935defines the incoming buffers' formats, to be passed as the opaque 6936parameter to @code{avfilter_init_filter} for initialization. 6937@section anullsink 6938 6939Null audio sink; do absolutely nothing with the input audio. It is 6940mainly useful as a template and for use in analysis / debugging 6941tools. 6942 6943@c man end AUDIO SINKS 6944 6945@chapter Video Filters 6946@c man begin VIDEO FILTERS 6947 6948When you configure your FFmpeg build, you can disable any of the 6949existing filters using @code{--disable-filters}. 6950The configure output will show the video filters included in your 6951build. 6952 6953Below is a description of the currently available video filters. 6954 6955@section addroi 6956 6957Mark a region of interest in a video frame. 6958 6959The frame data is passed through unchanged, but metadata is attached 6960to the frame indicating regions of interest which can affect the 6961behaviour of later encoding. Multiple regions can be marked by 6962applying the filter multiple times. 6963 6964@table @option 6965@item x 6966Region distance in pixels from the left edge of the frame. 6967@item y 6968Region distance in pixels from the top edge of the frame. 6969@item w 6970Region width in pixels. 6971@item h 6972Region height in pixels. 6973 6974The parameters @var{x}, @var{y}, @var{w} and @var{h} are expressions, 6975and may contain the following variables: 6976@table @option 6977@item iw 6978Width of the input frame. 6979@item ih 6980Height of the input frame. 6981@end table 6982 6983@item qoffset 6984Quantisation offset to apply within the region. 6985 6986This must be a real value in the range -1 to +1. A value of zero 6987indicates no quality change. A negative value asks for better quality 6988(less quantisation), while a positive value asks for worse quality 6989(greater quantisation). 6990 6991The range is calibrated so that the extreme values indicate the 6992largest possible offset - if the rest of the frame is encoded with the 6993worst possible quality, an offset of -1 indicates that this region 6994should be encoded with the best possible quality anyway. Intermediate 6995values are then interpolated in some codec-dependent way. 6996 6997For example, in 10-bit H.264 the quantisation parameter varies between 6998-12 and 51. A typical qoffset value of -1/10 therefore indicates that 6999this region should be encoded with a QP around one-tenth of the full 7000range better than the rest of the frame. So, if most of the frame 7001were to be encoded with a QP of around 30, this region would get a QP 7002of around 24 (an offset of approximately -1/10 * (51 - -12) = -6.3). 7003An extreme value of -1 would indicate that this region should be 7004encoded with the best possible quality regardless of the treatment of 7005the rest of the frame - that is, should be encoded at a QP of -12. 7006@item clear 7007If set to true, remove any existing regions of interest marked on the 7008frame before adding the new one. 7009@end table 7010 7011@subsection Examples 7012 7013@itemize 7014@item 7015Mark the centre quarter of the frame as interesting. 7016@example 7017addroi=iw/4:ih/4:iw/2:ih/2:-1/10 7018@end example 7019@item 7020Mark the 100-pixel-wide region on the left edge of the frame as very 7021uninteresting (to be encoded at much lower quality than the rest of 7022the frame). 7023@example 7024addroi=0:0:100:ih:+1/5 7025@end example 7026@end itemize 7027 7028@section alphaextract 7029 7030Extract the alpha component from the input as a grayscale video. This 7031is especially useful with the @var{alphamerge} filter. 7032 7033@section alphamerge 7034 7035Add or replace the alpha component of the primary input with the 7036grayscale value of a second input. This is intended for use with 7037@var{alphaextract} to allow the transmission or storage of frame 7038sequences that have alpha in a format that doesn't support an alpha 7039channel. 7040 7041For example, to reconstruct full frames from a normal YUV-encoded video 7042and a separate video created with @var{alphaextract}, you might use: 7043@example 7044movie=in_alpha.mkv [alpha]; [in][alpha] alphamerge [out] 7045@end example 7046 7047@section amplify 7048 7049Amplify differences between current pixel and pixels of adjacent frames in 7050same pixel location. 7051 7052This filter accepts the following options: 7053 7054@table @option 7055@item radius 7056Set frame radius. Default is 2. Allowed range is from 1 to 63. 7057For example radius of 3 will instruct filter to calculate average of 7 frames. 7058 7059@item factor 7060Set factor to amplify difference. Default is 2. Allowed range is from 0 to 65535. 7061 7062@item threshold 7063Set threshold for difference amplification. Any difference greater or equal to 7064this value will not alter source pixel. Default is 10. 7065Allowed range is from 0 to 65535. 7066 7067@item tolerance 7068Set tolerance for difference amplification. Any difference lower to 7069this value will not alter source pixel. Default is 0. 7070Allowed range is from 0 to 65535. 7071 7072@item low 7073Set lower limit for changing source pixel. Default is 65535. Allowed range is from 0 to 65535. 7074This option controls maximum possible value that will decrease source pixel value. 7075 7076@item high 7077Set high limit for changing source pixel. Default is 65535. Allowed range is from 0 to 65535. 7078This option controls maximum possible value that will increase source pixel value. 7079 7080@item planes 7081Set which planes to filter. Default is all. Allowed range is from 0 to 15. 7082@end table 7083 7084@subsection Commands 7085 7086This filter supports the following @ref{commands} that corresponds to option of same name: 7087@table @option 7088@item factor 7089@item threshold 7090@item tolerance 7091@item low 7092@item high 7093@item planes 7094@end table 7095 7096@section ass 7097 7098Same as the @ref{subtitles} filter, except that it doesn't require libavcodec 7099and libavformat to work. On the other hand, it is limited to ASS (Advanced 7100Substation Alpha) subtitles files. 7101 7102This filter accepts the following option in addition to the common options from 7103the @ref{subtitles} filter: 7104 7105@table @option 7106@item shaping 7107Set the shaping engine 7108 7109Available values are: 7110@table @samp 7111@item auto 7112The default libass shaping engine, which is the best available. 7113@item simple 7114Fast, font-agnostic shaper that can do only substitutions 7115@item complex 7116Slower shaper using OpenType for substitutions and positioning 7117@end table 7118 7119The default is @code{auto}. 7120@end table 7121 7122@section atadenoise 7123Apply an Adaptive Temporal Averaging Denoiser to the video input. 7124 7125The filter accepts the following options: 7126 7127@table @option 7128@item 0a 7129Set threshold A for 1st plane. Default is 0.02. 7130Valid range is 0 to 0.3. 7131 7132@item 0b 7133Set threshold B for 1st plane. Default is 0.04. 7134Valid range is 0 to 5. 7135 7136@item 1a 7137Set threshold A for 2nd plane. Default is 0.02. 7138Valid range is 0 to 0.3. 7139 7140@item 1b 7141Set threshold B for 2nd plane. Default is 0.04. 7142Valid range is 0 to 5. 7143 7144@item 2a 7145Set threshold A for 3rd plane. Default is 0.02. 7146Valid range is 0 to 0.3. 7147 7148@item 2b 7149Set threshold B for 3rd plane. Default is 0.04. 7150Valid range is 0 to 5. 7151 7152Threshold A is designed to react on abrupt changes in the input signal and 7153threshold B is designed to react on continuous changes in the input signal. 7154 7155@item s 7156Set number of frames filter will use for averaging. Default is 9. Must be odd 7157number in range [5, 129]. 7158 7159@item p 7160Set what planes of frame filter will use for averaging. Default is all. 7161 7162@item a 7163Set what variant of algorithm filter will use for averaging. Default is @code{p} parallel. 7164Alternatively can be set to @code{s} serial. 7165 7166Parallel can be faster then serial, while other way around is never true. 7167Parallel will abort early on first change being greater then thresholds, while serial 7168will continue processing other side of frames if they are equal or below thresholds. 7169 7170@item 0s 7171@item 1s 7172@item 2s 7173Set sigma for 1st plane, 2nd plane or 3rd plane. Default is 32767. 7174Valid range is from 0 to 32767. 7175This options controls weight for each pixel in radius defined by size. 7176Default value means every pixel have same weight. 7177Setting this option to 0 effectively disables filtering. 7178@end table 7179 7180@subsection Commands 7181This filter supports same @ref{commands} as options except option @code{s}. 7182The command accepts the same syntax of the corresponding option. 7183 7184@section avgblur 7185 7186Apply average blur filter. 7187 7188The filter accepts the following options: 7189 7190@table @option 7191@item sizeX 7192Set horizontal radius size. 7193 7194@item planes 7195Set which planes to filter. By default all planes are filtered. 7196 7197@item sizeY 7198Set vertical radius size, if zero it will be same as @code{sizeX}. 7199Default is @code{0}. 7200@end table 7201 7202@subsection Commands 7203This filter supports same commands as options. 7204The command accepts the same syntax of the corresponding option. 7205 7206If the specified expression is not valid, it is kept at its current 7207value. 7208 7209@section bbox 7210 7211Compute the bounding box for the non-black pixels in the input frame 7212luminance plane. 7213 7214This filter computes the bounding box containing all the pixels with a 7215luminance value greater than the minimum allowed value. 7216The parameters describing the bounding box are printed on the filter 7217log. 7218 7219The filter accepts the following option: 7220 7221@table @option 7222@item min_val 7223Set the minimal luminance value. Default is @code{16}. 7224@end table 7225 7226@subsection Commands 7227 7228This filter supports the all above options as @ref{commands}. 7229 7230@section bilateral 7231Apply bilateral filter, spatial smoothing while preserving edges. 7232 7233The filter accepts the following options: 7234@table @option 7235@item sigmaS 7236Set sigma of gaussian function to calculate spatial weight. 7237Allowed range is 0 to 512. Default is 0.1. 7238 7239@item sigmaR 7240Set sigma of gaussian function to calculate range weight. 7241Allowed range is 0 to 1. Default is 0.1. 7242 7243@item planes 7244Set planes to filter. Default is first only. 7245@end table 7246 7247@subsection Commands 7248 7249This filter supports the all above options as @ref{commands}. 7250 7251@section bitplanenoise 7252 7253Show and measure bit plane noise. 7254 7255The filter accepts the following options: 7256 7257@table @option 7258@item bitplane 7259Set which plane to analyze. Default is @code{1}. 7260 7261@item filter 7262Filter out noisy pixels from @code{bitplane} set above. 7263Default is disabled. 7264@end table 7265 7266@section blackdetect 7267 7268Detect video intervals that are (almost) completely black. Can be 7269useful to detect chapter transitions, commercials, or invalid 7270recordings. 7271 7272The filter outputs its detection analysis to both the log as well as 7273frame metadata. If a black segment of at least the specified minimum 7274duration is found, a line with the start and end timestamps as well 7275as duration is printed to the log with level @code{info}. In addition, 7276a log line with level @code{debug} is printed per frame showing the 7277black amount detected for that frame. 7278 7279The filter also attaches metadata to the first frame of a black 7280segment with key @code{lavfi.black_start} and to the first frame 7281after the black segment ends with key @code{lavfi.black_end}. The 7282value is the frame's timestamp. This metadata is added regardless 7283of the minimum duration specified. 7284 7285The filter accepts the following options: 7286 7287@table @option 7288@item black_min_duration, d 7289Set the minimum detected black duration expressed in seconds. It must 7290be a non-negative floating point number. 7291 7292Default value is 2.0. 7293 7294@item picture_black_ratio_th, pic_th 7295Set the threshold for considering a picture "black". 7296Express the minimum value for the ratio: 7297@example 7298@var{nb_black_pixels} / @var{nb_pixels} 7299@end example 7300 7301for which a picture is considered black. 7302Default value is 0.98. 7303 7304@item pixel_black_th, pix_th 7305Set the threshold for considering a pixel "black". 7306 7307The threshold expresses the maximum pixel luminance value for which a 7308pixel is considered "black". The provided value is scaled according to 7309the following equation: 7310@example 7311@var{absolute_threshold} = @var{luminance_minimum_value} + @var{pixel_black_th} * @var{luminance_range_size} 7312@end example 7313 7314@var{luminance_range_size} and @var{luminance_minimum_value} depend on 7315the input video format, the range is [0-255] for YUV full-range 7316formats and [16-235] for YUV non full-range formats. 7317 7318Default value is 0.10. 7319@end table 7320 7321The following example sets the maximum pixel threshold to the minimum 7322value, and detects only black intervals of 2 or more seconds: 7323@example 7324blackdetect=d=2:pix_th=0.00 7325@end example 7326 7327@section blackframe 7328 7329Detect frames that are (almost) completely black. Can be useful to 7330detect chapter transitions or commercials. Output lines consist of 7331the frame number of the detected frame, the percentage of blackness, 7332the position in the file if known or -1 and the timestamp in seconds. 7333 7334In order to display the output lines, you need to set the loglevel at 7335least to the AV_LOG_INFO value. 7336 7337This filter exports frame metadata @code{lavfi.blackframe.pblack}. 7338The value represents the percentage of pixels in the picture that 7339are below the threshold value. 7340 7341It accepts the following parameters: 7342 7343@table @option 7344 7345@item amount 7346The percentage of the pixels that have to be below the threshold; it defaults to 7347@code{98}. 7348 7349@item threshold, thresh 7350The threshold below which a pixel value is considered black; it defaults to 7351@code{32}. 7352 7353@end table 7354 7355@anchor{blend} 7356@section blend 7357 7358Blend two video frames into each other. 7359 7360The @code{blend} filter takes two input streams and outputs one 7361stream, the first input is the "top" layer and second input is 7362"bottom" layer. By default, the output terminates when the longest input terminates. 7363 7364The @code{tblend} (time blend) filter takes two consecutive frames 7365from one single stream, and outputs the result obtained by blending 7366the new frame on top of the old frame. 7367 7368A description of the accepted options follows. 7369 7370@table @option 7371@item c0_mode 7372@item c1_mode 7373@item c2_mode 7374@item c3_mode 7375@item all_mode 7376Set blend mode for specific pixel component or all pixel components in case 7377of @var{all_mode}. Default value is @code{normal}. 7378 7379Available values for component modes are: 7380@table @samp 7381@item addition 7382@item grainmerge 7383@item and 7384@item average 7385@item burn 7386@item darken 7387@item difference 7388@item grainextract 7389@item divide 7390@item dodge 7391@item freeze 7392@item exclusion 7393@item extremity 7394@item glow 7395@item hardlight 7396@item hardmix 7397@item heat 7398@item lighten 7399@item linearlight 7400@item multiply 7401@item multiply128 7402@item negation 7403@item normal 7404@item or 7405@item overlay 7406@item phoenix 7407@item pinlight 7408@item reflect 7409@item screen 7410@item softlight 7411@item subtract 7412@item vividlight 7413@item xor 7414@end table 7415 7416@item c0_opacity 7417@item c1_opacity 7418@item c2_opacity 7419@item c3_opacity 7420@item all_opacity 7421Set blend opacity for specific pixel component or all pixel components in case 7422of @var{all_opacity}. Only used in combination with pixel component blend modes. 7423 7424@item c0_expr 7425@item c1_expr 7426@item c2_expr 7427@item c3_expr 7428@item all_expr 7429Set blend expression for specific pixel component or all pixel components in case 7430of @var{all_expr}. Note that related mode options will be ignored if those are set. 7431 7432The expressions can use the following variables: 7433 7434@table @option 7435@item N 7436The sequential number of the filtered frame, starting from @code{0}. 7437 7438@item X 7439@item Y 7440the coordinates of the current sample 7441 7442@item W 7443@item H 7444the width and height of currently filtered plane 7445 7446@item SW 7447@item SH 7448Width and height scale for the plane being filtered. It is the 7449ratio between the dimensions of the current plane to the luma plane, 7450e.g. for a @code{yuv420p} frame, the values are @code{1,1} for 7451the luma plane and @code{0.5,0.5} for the chroma planes. 7452 7453@item T 7454Time of the current frame, expressed in seconds. 7455 7456@item TOP, A 7457Value of pixel component at current location for first video frame (top layer). 7458 7459@item BOTTOM, B 7460Value of pixel component at current location for second video frame (bottom layer). 7461@end table 7462@end table 7463 7464The @code{blend} filter also supports the @ref{framesync} options. 7465 7466@subsection Examples 7467 7468@itemize 7469@item 7470Apply transition from bottom layer to top layer in first 10 seconds: 7471@example 7472blend=all_expr='A*(if(gte(T,10),1,T/10))+B*(1-(if(gte(T,10),1,T/10)))' 7473@end example 7474 7475@item 7476Apply linear horizontal transition from top layer to bottom layer: 7477@example 7478blend=all_expr='A*(X/W)+B*(1-X/W)' 7479@end example 7480 7481@item 7482Apply 1x1 checkerboard effect: 7483@example 7484blend=all_expr='if(eq(mod(X,2),mod(Y,2)),A,B)' 7485@end example 7486 7487@item 7488Apply uncover left effect: 7489@example 7490blend=all_expr='if(gte(N*SW+X,W),A,B)' 7491@end example 7492 7493@item 7494Apply uncover down effect: 7495@example 7496blend=all_expr='if(gte(Y-N*SH,0),A,B)' 7497@end example 7498 7499@item 7500Apply uncover up-left effect: 7501@example 7502blend=all_expr='if(gte(T*SH*40+Y,H)*gte((T*40*SW+X)*W/H,W),A,B)' 7503@end example 7504 7505@item 7506Split diagonally video and shows top and bottom layer on each side: 7507@example 7508blend=all_expr='if(gt(X,Y*(W/H)),A,B)' 7509@end example 7510 7511@item 7512Display differences between the current and the previous frame: 7513@example 7514tblend=all_mode=grainextract 7515@end example 7516@end itemize 7517 7518@subsection Commands 7519This filter supports same @ref{commands} as options. 7520 7521@section bm3d 7522 7523Denoise frames using Block-Matching 3D algorithm. 7524 7525The filter accepts the following options. 7526 7527@table @option 7528@item sigma 7529Set denoising strength. Default value is 1. 7530Allowed range is from 0 to 999.9. 7531The denoising algorithm is very sensitive to sigma, so adjust it 7532according to the source. 7533 7534@item block 7535Set local patch size. This sets dimensions in 2D. 7536 7537@item bstep 7538Set sliding step for processing blocks. Default value is 4. 7539Allowed range is from 1 to 64. 7540Smaller values allows processing more reference blocks and is slower. 7541 7542@item group 7543Set maximal number of similar blocks for 3rd dimension. Default value is 1. 7544When set to 1, no block matching is done. Larger values allows more blocks 7545in single group. 7546Allowed range is from 1 to 256. 7547 7548@item range 7549Set radius for search block matching. Default is 9. 7550Allowed range is from 1 to INT32_MAX. 7551 7552@item mstep 7553Set step between two search locations for block matching. Default is 1. 7554Allowed range is from 1 to 64. Smaller is slower. 7555 7556@item thmse 7557Set threshold of mean square error for block matching. Valid range is 0 to 7558INT32_MAX. 7559 7560@item hdthr 7561Set thresholding parameter for hard thresholding in 3D transformed domain. 7562Larger values results in stronger hard-thresholding filtering in frequency 7563domain. 7564 7565@item estim 7566Set filtering estimation mode. Can be @code{basic} or @code{final}. 7567Default is @code{basic}. 7568 7569@item ref 7570If enabled, filter will use 2nd stream for block matching. 7571Default is disabled for @code{basic} value of @var{estim} option, 7572and always enabled if value of @var{estim} is @code{final}. 7573 7574@item planes 7575Set planes to filter. Default is all available except alpha. 7576@end table 7577 7578@subsection Examples 7579 7580@itemize 7581@item 7582Basic filtering with bm3d: 7583@example 7584bm3d=sigma=3:block=4:bstep=2:group=1:estim=basic 7585@end example 7586 7587@item 7588Same as above, but filtering only luma: 7589@example 7590bm3d=sigma=3:block=4:bstep=2:group=1:estim=basic:planes=1 7591@end example 7592 7593@item 7594Same as above, but with both estimation modes: 7595@example 7596split[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 7597@end example 7598 7599@item 7600Same as above, but prefilter with @ref{nlmeans} filter instead: 7601@example 7602split[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 7603@end example 7604@end itemize 7605 7606@section boxblur 7607 7608Apply a boxblur algorithm to the input video. 7609 7610It accepts the following parameters: 7611 7612@table @option 7613 7614@item luma_radius, lr 7615@item luma_power, lp 7616@item chroma_radius, cr 7617@item chroma_power, cp 7618@item alpha_radius, ar 7619@item alpha_power, ap 7620 7621@end table 7622 7623A description of the accepted options follows. 7624 7625@table @option 7626@item luma_radius, lr 7627@item chroma_radius, cr 7628@item alpha_radius, ar 7629Set an expression for the box radius in pixels used for blurring the 7630corresponding input plane. 7631 7632The radius value must be a non-negative number, and must not be 7633greater than the value of the expression @code{min(w,h)/2} for the 7634luma and alpha planes, and of @code{min(cw,ch)/2} for the chroma 7635planes. 7636 7637Default value for @option{luma_radius} is "2". If not specified, 7638@option{chroma_radius} and @option{alpha_radius} default to the 7639corresponding value set for @option{luma_radius}. 7640 7641The expressions can contain the following constants: 7642@table @option 7643@item w 7644@item h 7645The input width and height in pixels. 7646 7647@item cw 7648@item ch 7649The input chroma image width and height in pixels. 7650 7651@item hsub 7652@item vsub 7653The horizontal and vertical chroma subsample values. For example, for the 7654pixel format "yuv422p", @var{hsub} is 2 and @var{vsub} is 1. 7655@end table 7656 7657@item luma_power, lp 7658@item chroma_power, cp 7659@item alpha_power, ap 7660Specify how many times the boxblur filter is applied to the 7661corresponding plane. 7662 7663Default value for @option{luma_power} is 2. If not specified, 7664@option{chroma_power} and @option{alpha_power} default to the 7665corresponding value set for @option{luma_power}. 7666 7667A value of 0 will disable the effect. 7668@end table 7669 7670@subsection Examples 7671 7672@itemize 7673@item 7674Apply a boxblur filter with the luma, chroma, and alpha radii 7675set to 2: 7676@example 7677boxblur=luma_radius=2:luma_power=1 7678boxblur=2:1 7679@end example 7680 7681@item 7682Set the luma radius to 2, and alpha and chroma radius to 0: 7683@example 7684boxblur=2:1:cr=0:ar=0 7685@end example 7686 7687@item 7688Set the luma and chroma radii to a fraction of the video dimension: 7689@example 7690boxblur=luma_radius=min(h\,w)/10:luma_power=1:chroma_radius=min(cw\,ch)/10:chroma_power=1 7691@end example 7692@end itemize 7693 7694@section bwdif 7695 7696Deinterlace the input video ("bwdif" stands for "Bob Weaver 7697Deinterlacing Filter"). 7698 7699Motion adaptive deinterlacing based on yadif with the use of w3fdif and cubic 7700interpolation algorithms. 7701It accepts the following parameters: 7702 7703@table @option 7704@item mode 7705The interlacing mode to adopt. It accepts one of the following values: 7706 7707@table @option 7708@item 0, send_frame 7709Output one frame for each frame. 7710@item 1, send_field 7711Output one frame for each field. 7712@end table 7713 7714The default value is @code{send_field}. 7715 7716@item parity 7717The picture field parity assumed for the input interlaced video. It accepts one 7718of the following values: 7719 7720@table @option 7721@item 0, tff 7722Assume the top field is first. 7723@item 1, bff 7724Assume the bottom field is first. 7725@item -1, auto 7726Enable automatic detection of field parity. 7727@end table 7728 7729The default value is @code{auto}. 7730If the interlacing is unknown or the decoder does not export this information, 7731top field first will be assumed. 7732 7733@item deint 7734Specify which frames to deinterlace. Accepts one of the following 7735values: 7736 7737@table @option 7738@item 0, all 7739Deinterlace all frames. 7740@item 1, interlaced 7741Only deinterlace frames marked as interlaced. 7742@end table 7743 7744The default value is @code{all}. 7745@end table 7746 7747@section cas 7748 7749Apply Contrast Adaptive Sharpen filter to video stream. 7750 7751The filter accepts the following options: 7752 7753@table @option 7754@item strength 7755Set the sharpening strength. Default value is 0. 7756 7757@item planes 7758Set planes to filter. Default value is to filter all 7759planes except alpha plane. 7760@end table 7761 7762@subsection Commands 7763This filter supports same @ref{commands} as options. 7764 7765@section chromahold 7766Remove all color information for all colors except for certain one. 7767 7768The filter accepts the following options: 7769 7770@table @option 7771@item color 7772The color which will not be replaced with neutral chroma. 7773 7774@item similarity 7775Similarity percentage with the above color. 77760.01 matches only the exact key color, while 1.0 matches everything. 7777 7778@item blend 7779Blend percentage. 77800.0 makes pixels either fully gray, or not gray at all. 7781Higher values result in more preserved color. 7782 7783@item yuv 7784Signals that the color passed is already in YUV instead of RGB. 7785 7786Literal colors like "green" or "red" don't make sense with this enabled anymore. 7787This can be used to pass exact YUV values as hexadecimal numbers. 7788@end table 7789 7790@subsection Commands 7791This filter supports same @ref{commands} as options. 7792The command accepts the same syntax of the corresponding option. 7793 7794If the specified expression is not valid, it is kept at its current 7795value. 7796 7797@section chromakey 7798YUV colorspace color/chroma keying. 7799 7800The filter accepts the following options: 7801 7802@table @option 7803@item color 7804The color which will be replaced with transparency. 7805 7806@item similarity 7807Similarity percentage with the key color. 7808 78090.01 matches only the exact key color, while 1.0 matches everything. 7810 7811@item blend 7812Blend percentage. 7813 78140.0 makes pixels either fully transparent, or not transparent at all. 7815 7816Higher values result in semi-transparent pixels, with a higher transparency 7817the more similar the pixels color is to the key color. 7818 7819@item yuv 7820Signals that the color passed is already in YUV instead of RGB. 7821 7822Literal colors like "green" or "red" don't make sense with this enabled anymore. 7823This can be used to pass exact YUV values as hexadecimal numbers. 7824@end table 7825 7826@subsection Commands 7827This filter supports same @ref{commands} as options. 7828The command accepts the same syntax of the corresponding option. 7829 7830If the specified expression is not valid, it is kept at its current 7831value. 7832 7833@subsection Examples 7834 7835@itemize 7836@item 7837Make every green pixel in the input image transparent: 7838@example 7839ffmpeg -i input.png -vf chromakey=green out.png 7840@end example 7841 7842@item 7843Overlay a greenscreen-video on top of a static black background. 7844@example 7845ffmpeg -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 7846@end example 7847@end itemize 7848 7849@section chromanr 7850Reduce chrominance noise. 7851 7852The filter accepts the following options: 7853 7854@table @option 7855@item thres 7856Set threshold for averaging chrominance values. 7857Sum of absolute difference of Y, U and V pixel components of current 7858pixel and neighbour pixels lower than this threshold will be used in 7859averaging. Luma component is left unchanged and is copied to output. 7860Default value is 30. Allowed range is from 1 to 200. 7861 7862@item sizew 7863Set horizontal radius of rectangle used for averaging. 7864Allowed range is from 1 to 100. Default value is 5. 7865 7866@item sizeh 7867Set vertical radius of rectangle used for averaging. 7868Allowed range is from 1 to 100. Default value is 5. 7869 7870@item stepw 7871Set horizontal step when averaging. Default value is 1. 7872Allowed range is from 1 to 50. 7873Mostly useful to speed-up filtering. 7874 7875@item steph 7876Set vertical step when averaging. Default value is 1. 7877Allowed range is from 1 to 50. 7878Mostly useful to speed-up filtering. 7879 7880@item threy 7881Set Y threshold for averaging chrominance values. 7882Set finer control for max allowed difference between Y components 7883of current pixel and neigbour pixels. 7884Default value is 200. Allowed range is from 1 to 200. 7885 7886@item threu 7887Set U threshold for averaging chrominance values. 7888Set finer control for max allowed difference between U components 7889of current pixel and neigbour pixels. 7890Default value is 200. Allowed range is from 1 to 200. 7891 7892@item threv 7893Set V threshold for averaging chrominance values. 7894Set finer control for max allowed difference between V components 7895of current pixel and neigbour pixels. 7896Default value is 200. Allowed range is from 1 to 200. 7897@end table 7898 7899@subsection Commands 7900This filter supports same @ref{commands} as options. 7901The command accepts the same syntax of the corresponding option. 7902 7903@section chromashift 7904Shift chroma pixels horizontally and/or vertically. 7905 7906The filter accepts the following options: 7907@table @option 7908@item cbh 7909Set amount to shift chroma-blue horizontally. 7910@item cbv 7911Set amount to shift chroma-blue vertically. 7912@item crh 7913Set amount to shift chroma-red horizontally. 7914@item crv 7915Set amount to shift chroma-red vertically. 7916@item edge 7917Set edge mode, can be @var{smear}, default, or @var{warp}. 7918@end table 7919 7920@subsection Commands 7921 7922This filter supports the all above options as @ref{commands}. 7923 7924@section ciescope 7925 7926Display CIE color diagram with pixels overlaid onto it. 7927 7928The filter accepts the following options: 7929 7930@table @option 7931@item system 7932Set color system. 7933 7934@table @samp 7935@item ntsc, 470m 7936@item ebu, 470bg 7937@item smpte 7938@item 240m 7939@item apple 7940@item widergb 7941@item cie1931 7942@item rec709, hdtv 7943@item uhdtv, rec2020 7944@item dcip3 7945@end table 7946 7947@item cie 7948Set CIE system. 7949 7950@table @samp 7951@item xyy 7952@item ucs 7953@item luv 7954@end table 7955 7956@item gamuts 7957Set what gamuts to draw. 7958 7959See @code{system} option for available values. 7960 7961@item size, s 7962Set ciescope size, by default set to 512. 7963 7964@item intensity, i 7965Set intensity used to map input pixel values to CIE diagram. 7966 7967@item contrast 7968Set contrast used to draw tongue colors that are out of active color system gamut. 7969 7970@item corrgamma 7971Correct gamma displayed on scope, by default enabled. 7972 7973@item showwhite 7974Show white point on CIE diagram, by default disabled. 7975 7976@item gamma 7977Set input gamma. Used only with XYZ input color space. 7978@end table 7979 7980@section codecview 7981 7982Visualize information exported by some codecs. 7983 7984Some codecs can export information through frames using side-data or other 7985means. For example, some MPEG based codecs export motion vectors through the 7986@var{export_mvs} flag in the codec @option{flags2} option. 7987 7988The filter accepts the following option: 7989 7990@table @option 7991@item mv 7992Set motion vectors to visualize. 7993 7994Available flags for @var{mv} are: 7995 7996@table @samp 7997@item pf 7998forward predicted MVs of P-frames 7999@item bf 8000forward predicted MVs of B-frames 8001@item bb 8002backward predicted MVs of B-frames 8003@end table 8004 8005@item qp 8006Display quantization parameters using the chroma planes. 8007 8008@item mv_type, mvt 8009Set motion vectors type to visualize. Includes MVs from all frames unless specified by @var{frame_type} option. 8010 8011Available flags for @var{mv_type} are: 8012 8013@table @samp 8014@item fp 8015forward predicted MVs 8016@item bp 8017backward predicted MVs 8018@end table 8019 8020@item frame_type, ft 8021Set frame type to visualize motion vectors of. 8022 8023Available flags for @var{frame_type} are: 8024 8025@table @samp 8026@item if 8027intra-coded frames (I-frames) 8028@item pf 8029predicted frames (P-frames) 8030@item bf 8031bi-directionally predicted frames (B-frames) 8032@end table 8033@end table 8034 8035@subsection Examples 8036 8037@itemize 8038@item 8039Visualize forward predicted MVs of all frames using @command{ffplay}: 8040@example 8041ffplay -flags2 +export_mvs input.mp4 -vf codecview=mv_type=fp 8042@end example 8043 8044@item 8045Visualize multi-directionals MVs of P and B-Frames using @command{ffplay}: 8046@example 8047ffplay -flags2 +export_mvs input.mp4 -vf codecview=mv=pf+bf+bb 8048@end example 8049@end itemize 8050 8051@section colorbalance 8052Modify intensity of primary colors (red, green and blue) of input frames. 8053 8054The filter allows an input frame to be adjusted in the shadows, midtones or highlights 8055regions for the red-cyan, green-magenta or blue-yellow balance. 8056 8057A positive adjustment value shifts the balance towards the primary color, a negative 8058value towards the complementary color. 8059 8060The filter accepts the following options: 8061 8062@table @option 8063@item rs 8064@item gs 8065@item bs 8066Adjust red, green and blue shadows (darkest pixels). 8067 8068@item rm 8069@item gm 8070@item bm 8071Adjust red, green and blue midtones (medium pixels). 8072 8073@item rh 8074@item gh 8075@item bh 8076Adjust red, green and blue highlights (brightest pixels). 8077 8078Allowed ranges for options are @code{[-1.0, 1.0]}. Defaults are @code{0}. 8079 8080@item pl 8081Preserve lightness when changing color balance. Default is disabled. 8082@end table 8083 8084@subsection Examples 8085 8086@itemize 8087@item 8088Add red color cast to shadows: 8089@example 8090colorbalance=rs=.3 8091@end example 8092@end itemize 8093 8094@subsection Commands 8095 8096This filter supports the all above options as @ref{commands}. 8097 8098@section colorcontrast 8099 8100Adjust color contrast between RGB components. 8101 8102The filter accepts the following options: 8103 8104@table @option 8105@item rc 8106Set the red-cyan contrast. Defaults is 0.0. Allowed range is from -1.0 to 1.0. 8107 8108@item gm 8109Set the green-magenta contrast. Defaults is 0.0. Allowed range is from -1.0 to 1.0. 8110 8111@item by 8112Set the blue-yellow contrast. Defaults is 0.0. Allowed range is from -1.0 to 1.0. 8113 8114@item rcw 8115@item gmw 8116@item byw 8117Set the weight of each @code{rc}, @code{gm}, @code{by} option value. Default value is 0.0. 8118Allowed range is from 0.0 to 1.0. If all weights are 0.0 filtering is disabled. 8119 8120@item pl 8121Set the amount of preserving lightness. Default value is 0.0. Allowed range is from 0.0 to 1.0. 8122@end table 8123 8124@subsection Commands 8125 8126This filter supports the all above options as @ref{commands}. 8127 8128@section colorcorrect 8129 8130Adjust color white balance selectively for blacks and whites. 8131This filter operates in YUV colorspace. 8132 8133The filter accepts the following options: 8134 8135@table @option 8136@item rl 8137Set the red shadow spot. Allowed range is from -1.0 to 1.0. 8138Default value is 0. 8139 8140@item bl 8141Set the blue shadow spot. Allowed range is from -1.0 to 1.0. 8142Default value is 0. 8143 8144@item rh 8145Set the red highlight spot. Allowed range is from -1.0 to 1.0. 8146Default value is 0. 8147 8148@item bh 8149Set the red highlight spot. Allowed range is from -1.0 to 1.0. 8150Default value is 0. 8151 8152@item saturation 8153Set the amount of saturation. Allowed range is from -3.0 to 3.0. 8154Default value is 1. 8155@end table 8156 8157@subsection Commands 8158 8159This filter supports the all above options as @ref{commands}. 8160 8161@section colorchannelmixer 8162 8163Adjust video input frames by re-mixing color channels. 8164 8165This filter modifies a color channel by adding the values associated to 8166the other channels of the same pixels. For example if the value to 8167modify is red, the output value will be: 8168@example 8169@var{red}=@var{red}*@var{rr} + @var{blue}*@var{rb} + @var{green}*@var{rg} + @var{alpha}*@var{ra} 8170@end example 8171 8172The filter accepts the following options: 8173 8174@table @option 8175@item rr 8176@item rg 8177@item rb 8178@item ra 8179Adjust contribution of input red, green, blue and alpha channels for output red channel. 8180Default is @code{1} for @var{rr}, and @code{0} for @var{rg}, @var{rb} and @var{ra}. 8181 8182@item gr 8183@item gg 8184@item gb 8185@item ga 8186Adjust contribution of input red, green, blue and alpha channels for output green channel. 8187Default is @code{1} for @var{gg}, and @code{0} for @var{gr}, @var{gb} and @var{ga}. 8188 8189@item br 8190@item bg 8191@item bb 8192@item ba 8193Adjust contribution of input red, green, blue and alpha channels for output blue channel. 8194Default is @code{1} for @var{bb}, and @code{0} for @var{br}, @var{bg} and @var{ba}. 8195 8196@item ar 8197@item ag 8198@item ab 8199@item aa 8200Adjust contribution of input red, green, blue and alpha channels for output alpha channel. 8201Default is @code{1} for @var{aa}, and @code{0} for @var{ar}, @var{ag} and @var{ab}. 8202 8203Allowed ranges for options are @code{[-2.0, 2.0]}. 8204 8205@item pl 8206Preserve lightness when changing colors. Allowed range is from @code{[0.0, 1.0]}. 8207Default is @code{0.0}, thus disabled. 8208@end table 8209 8210@subsection Examples 8211 8212@itemize 8213@item 8214Convert source to grayscale: 8215@example 8216colorchannelmixer=.3:.4:.3:0:.3:.4:.3:0:.3:.4:.3 8217@end example 8218@item 8219Simulate sepia tones: 8220@example 8221colorchannelmixer=.393:.769:.189:0:.349:.686:.168:0:.272:.534:.131 8222@end example 8223@end itemize 8224 8225@subsection Commands 8226 8227This filter supports the all above options as @ref{commands}. 8228 8229@section colorize 8230Overlay a solid color on the video stream. 8231 8232The filter accepts the following options: 8233 8234@table @option 8235@item hue 8236Set the color hue. Allowed range is from 0 to 360. 8237Default value is 0. 8238 8239@item saturation 8240Set the color saturation. Allowed range is from 0 to 1. 8241Default value is 0.5. 8242 8243@item lightness 8244Set the color lightness. Allowed range is from 0 to 1. 8245Default value is 0.5. 8246 8247@item mix 8248Set the mix of source lightness. By default is set to 1.0. 8249Allowed range is from 0.0 to 1.0. 8250@end table 8251 8252@subsection Commands 8253 8254This filter supports the all above options as @ref{commands}. 8255 8256@section colorkey 8257RGB colorspace color keying. 8258 8259The filter accepts the following options: 8260 8261@table @option 8262@item color 8263The color which will be replaced with transparency. 8264 8265@item similarity 8266Similarity percentage with the key color. 8267 82680.01 matches only the exact key color, while 1.0 matches everything. 8269 8270@item blend 8271Blend percentage. 8272 82730.0 makes pixels either fully transparent, or not transparent at all. 8274 8275Higher values result in semi-transparent pixels, with a higher transparency 8276the more similar the pixels color is to the key color. 8277@end table 8278 8279@subsection Examples 8280 8281@itemize 8282@item 8283Make every green pixel in the input image transparent: 8284@example 8285ffmpeg -i input.png -vf colorkey=green out.png 8286@end example 8287 8288@item 8289Overlay a greenscreen-video on top of a static background image. 8290@example 8291ffmpeg -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 8292@end example 8293@end itemize 8294 8295@subsection Commands 8296This filter supports same @ref{commands} as options. 8297The command accepts the same syntax of the corresponding option. 8298 8299If the specified expression is not valid, it is kept at its current 8300value. 8301 8302@section colorhold 8303Remove all color information for all RGB colors except for certain one. 8304 8305The filter accepts the following options: 8306 8307@table @option 8308@item color 8309The color which will not be replaced with neutral gray. 8310 8311@item similarity 8312Similarity percentage with the above color. 83130.01 matches only the exact key color, while 1.0 matches everything. 8314 8315@item blend 8316Blend percentage. 0.0 makes pixels fully gray. 8317Higher values result in more preserved color. 8318@end table 8319 8320@subsection Commands 8321This filter supports same @ref{commands} as options. 8322The command accepts the same syntax of the corresponding option. 8323 8324If the specified expression is not valid, it is kept at its current 8325value. 8326 8327@section colorlevels 8328 8329Adjust video input frames using levels. 8330 8331The filter accepts the following options: 8332 8333@table @option 8334@item rimin 8335@item gimin 8336@item bimin 8337@item aimin 8338Adjust red, green, blue and alpha input black point. 8339Allowed ranges for options are @code{[-1.0, 1.0]}. Defaults are @code{0}. 8340 8341@item rimax 8342@item gimax 8343@item bimax 8344@item aimax 8345Adjust red, green, blue and alpha input white point. 8346Allowed ranges for options are @code{[-1.0, 1.0]}. Defaults are @code{1}. 8347 8348Input levels are used to lighten highlights (bright tones), darken shadows 8349(dark tones), change the balance of bright and dark tones. 8350 8351@item romin 8352@item gomin 8353@item bomin 8354@item aomin 8355Adjust red, green, blue and alpha output black point. 8356Allowed ranges for options are @code{[0, 1.0]}. Defaults are @code{0}. 8357 8358@item romax 8359@item gomax 8360@item bomax 8361@item aomax 8362Adjust red, green, blue and alpha output white point. 8363Allowed ranges for options are @code{[0, 1.0]}. Defaults are @code{1}. 8364 8365Output levels allows manual selection of a constrained output level range. 8366@end table 8367 8368@subsection Examples 8369 8370@itemize 8371@item 8372Make video output darker: 8373@example 8374colorlevels=rimin=0.058:gimin=0.058:bimin=0.058 8375@end example 8376 8377@item 8378Increase contrast: 8379@example 8380colorlevels=rimin=0.039:gimin=0.039:bimin=0.039:rimax=0.96:gimax=0.96:bimax=0.96 8381@end example 8382 8383@item 8384Make video output lighter: 8385@example 8386colorlevels=rimax=0.902:gimax=0.902:bimax=0.902 8387@end example 8388 8389@item 8390Increase brightness: 8391@example 8392colorlevels=romin=0.5:gomin=0.5:bomin=0.5 8393@end example 8394@end itemize 8395 8396@subsection Commands 8397 8398This filter supports the all above options as @ref{commands}. 8399 8400@section colormatrix 8401 8402Convert color matrix. 8403 8404The filter accepts the following options: 8405 8406@table @option 8407@item src 8408@item dst 8409Specify the source and destination color matrix. Both values must be 8410specified. 8411 8412The accepted values are: 8413@table @samp 8414@item bt709 8415BT.709 8416 8417@item fcc 8418FCC 8419 8420@item bt601 8421BT.601 8422 8423@item bt470 8424BT.470 8425 8426@item bt470bg 8427BT.470BG 8428 8429@item smpte170m 8430SMPTE-170M 8431 8432@item smpte240m 8433SMPTE-240M 8434 8435@item bt2020 8436BT.2020 8437@end table 8438@end table 8439 8440For example to convert from BT.601 to SMPTE-240M, use the command: 8441@example 8442colormatrix=bt601:smpte240m 8443@end example 8444 8445@section colorspace 8446 8447Convert colorspace, transfer characteristics or color primaries. 8448Input video needs to have an even size. 8449 8450The filter accepts the following options: 8451 8452@table @option 8453@anchor{all} 8454@item all 8455Specify all color properties at once. 8456 8457The accepted values are: 8458@table @samp 8459@item bt470m 8460BT.470M 8461 8462@item bt470bg 8463BT.470BG 8464 8465@item bt601-6-525 8466BT.601-6 525 8467 8468@item bt601-6-625 8469BT.601-6 625 8470 8471@item bt709 8472BT.709 8473 8474@item smpte170m 8475SMPTE-170M 8476 8477@item smpte240m 8478SMPTE-240M 8479 8480@item bt2020 8481BT.2020 8482 8483@end table 8484 8485@anchor{space} 8486@item space 8487Specify output colorspace. 8488 8489The accepted values are: 8490@table @samp 8491@item bt709 8492BT.709 8493 8494@item fcc 8495FCC 8496 8497@item bt470bg 8498BT.470BG or BT.601-6 625 8499 8500@item smpte170m 8501SMPTE-170M or BT.601-6 525 8502 8503@item smpte240m 8504SMPTE-240M 8505 8506@item ycgco 8507YCgCo 8508 8509@item bt2020ncl 8510BT.2020 with non-constant luminance 8511 8512@end table 8513 8514@anchor{trc} 8515@item trc 8516Specify output transfer characteristics. 8517 8518The accepted values are: 8519@table @samp 8520@item bt709 8521BT.709 8522 8523@item bt470m 8524BT.470M 8525 8526@item bt470bg 8527BT.470BG 8528 8529@item gamma22 8530Constant gamma of 2.2 8531 8532@item gamma28 8533Constant gamma of 2.8 8534 8535@item smpte170m 8536SMPTE-170M, BT.601-6 625 or BT.601-6 525 8537 8538@item smpte240m 8539SMPTE-240M 8540 8541@item srgb 8542SRGB 8543 8544@item iec61966-2-1 8545iec61966-2-1 8546 8547@item iec61966-2-4 8548iec61966-2-4 8549 8550@item xvycc 8551xvycc 8552 8553@item bt2020-10 8554BT.2020 for 10-bits content 8555 8556@item bt2020-12 8557BT.2020 for 12-bits content 8558 8559@end table 8560 8561@anchor{primaries} 8562@item primaries 8563Specify output color primaries. 8564 8565The accepted values are: 8566@table @samp 8567@item bt709 8568BT.709 8569 8570@item bt470m 8571BT.470M 8572 8573@item bt470bg 8574BT.470BG or BT.601-6 625 8575 8576@item smpte170m 8577SMPTE-170M or BT.601-6 525 8578 8579@item smpte240m 8580SMPTE-240M 8581 8582@item film 8583film 8584 8585@item smpte431 8586SMPTE-431 8587 8588@item smpte432 8589SMPTE-432 8590 8591@item bt2020 8592BT.2020 8593 8594@item jedec-p22 8595JEDEC P22 phosphors 8596 8597@end table 8598 8599@anchor{range} 8600@item range 8601Specify output color range. 8602 8603The accepted values are: 8604@table @samp 8605@item tv 8606TV (restricted) range 8607 8608@item mpeg 8609MPEG (restricted) range 8610 8611@item pc 8612PC (full) range 8613 8614@item jpeg 8615JPEG (full) range 8616 8617@end table 8618 8619@item format 8620Specify output color format. 8621 8622The accepted values are: 8623@table @samp 8624@item yuv420p 8625YUV 4:2:0 planar 8-bits 8626 8627@item yuv420p10 8628YUV 4:2:0 planar 10-bits 8629 8630@item yuv420p12 8631YUV 4:2:0 planar 12-bits 8632 8633@item yuv422p 8634YUV 4:2:2 planar 8-bits 8635 8636@item yuv422p10 8637YUV 4:2:2 planar 10-bits 8638 8639@item yuv422p12 8640YUV 4:2:2 planar 12-bits 8641 8642@item yuv444p 8643YUV 4:4:4 planar 8-bits 8644 8645@item yuv444p10 8646YUV 4:4:4 planar 10-bits 8647 8648@item yuv444p12 8649YUV 4:4:4 planar 12-bits 8650 8651@end table 8652 8653@item fast 8654Do a fast conversion, which skips gamma/primary correction. This will take 8655significantly less CPU, but will be mathematically incorrect. To get output 8656compatible with that produced by the colormatrix filter, use fast=1. 8657 8658@item dither 8659Specify dithering mode. 8660 8661The accepted values are: 8662@table @samp 8663@item none 8664No dithering 8665 8666@item fsb 8667Floyd-Steinberg dithering 8668@end table 8669 8670@item wpadapt 8671Whitepoint adaptation mode. 8672 8673The accepted values are: 8674@table @samp 8675@item bradford 8676Bradford whitepoint adaptation 8677 8678@item vonkries 8679von Kries whitepoint adaptation 8680 8681@item identity 8682identity whitepoint adaptation (i.e. no whitepoint adaptation) 8683@end table 8684 8685@item iall 8686Override all input properties at once. Same accepted values as @ref{all}. 8687 8688@item ispace 8689Override input colorspace. Same accepted values as @ref{space}. 8690 8691@item iprimaries 8692Override input color primaries. Same accepted values as @ref{primaries}. 8693 8694@item itrc 8695Override input transfer characteristics. Same accepted values as @ref{trc}. 8696 8697@item irange 8698Override input color range. Same accepted values as @ref{range}. 8699 8700@end table 8701 8702The filter converts the transfer characteristics, color space and color 8703primaries to the specified user values. The output value, if not specified, 8704is set to a default value based on the "all" property. If that property is 8705also not specified, the filter will log an error. The output color range and 8706format default to the same value as the input color range and format. The 8707input transfer characteristics, color space, color primaries and color range 8708should be set on the input data. If any of these are missing, the filter will 8709log an error and no conversion will take place. 8710 8711For example to convert the input to SMPTE-240M, use the command: 8712@example 8713colorspace=smpte240m 8714@end example 8715 8716@section colortemperature 8717Adjust color temperature in video to simulate variations in ambient color temperature. 8718 8719The filter accepts the following options: 8720 8721@table @option 8722@item temperature 8723Set the temperature in Kelvin. Allowed range is from 1000 to 40000. 8724Default value is 6500 K. 8725 8726@item mix 8727Set mixing with filtered output. Allowed range is from 0 to 1. 8728Default value is 1. 8729 8730@item pl 8731Set the amount of preserving lightness. Allowed range is from 0 to 1. 8732Default value is 0. 8733@end table 8734 8735@subsection Commands 8736This filter supports same @ref{commands} as options. 8737 8738@section convolution 8739 8740Apply convolution of 3x3, 5x5, 7x7 or horizontal/vertical up to 49 elements. 8741 8742The filter accepts the following options: 8743 8744@table @option 8745@item 0m 8746@item 1m 8747@item 2m 8748@item 3m 8749Set matrix for each plane. 8750Matrix is sequence of 9, 25 or 49 signed integers in @var{square} mode, 8751and from 1 to 49 odd number of signed integers in @var{row} mode. 8752 8753@item 0rdiv 8754@item 1rdiv 8755@item 2rdiv 8756@item 3rdiv 8757Set multiplier for calculated value for each plane. 8758If unset or 0, it will be sum of all matrix elements. 8759 8760@item 0bias 8761@item 1bias 8762@item 2bias 8763@item 3bias 8764Set bias for each plane. This value is added to the result of the multiplication. 8765Useful for making the overall image brighter or darker. Default is 0.0. 8766 8767@item 0mode 8768@item 1mode 8769@item 2mode 8770@item 3mode 8771Set matrix mode for each plane. Can be @var{square}, @var{row} or @var{column}. 8772Default is @var{square}. 8773@end table 8774 8775@subsection Commands 8776 8777This filter supports the all above options as @ref{commands}. 8778 8779@subsection Examples 8780 8781@itemize 8782@item 8783Apply sharpen: 8784@example 8785convolution="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" 8786@end example 8787 8788@item 8789Apply blur: 8790@example 8791convolution="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" 8792@end example 8793 8794@item 8795Apply edge enhance: 8796@example 8797convolution="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" 8798@end example 8799 8800@item 8801Apply edge detect: 8802@example 8803convolution="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" 8804@end example 8805 8806@item 8807Apply laplacian edge detector which includes diagonals: 8808@example 8809convolution="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" 8810@end example 8811 8812@item 8813Apply emboss: 8814@example 8815convolution="-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" 8816@end example 8817@end itemize 8818 8819@section convolve 8820 8821Apply 2D convolution of video stream in frequency domain using second stream 8822as impulse. 8823 8824The filter accepts the following options: 8825 8826@table @option 8827@item planes 8828Set which planes to process. 8829 8830@item impulse 8831Set which impulse video frames will be processed, can be @var{first} 8832or @var{all}. Default is @var{all}. 8833@end table 8834 8835The @code{convolve} filter also supports the @ref{framesync} options. 8836 8837@section copy 8838 8839Copy the input video source unchanged to the output. This is mainly useful for 8840testing purposes. 8841 8842@anchor{coreimage} 8843@section coreimage 8844Video filtering on GPU using Apple's CoreImage API on OSX. 8845 8846Hardware acceleration is based on an OpenGL context. Usually, this means it is 8847processed by video hardware. However, software-based OpenGL implementations 8848exist which means there is no guarantee for hardware processing. It depends on 8849the respective OSX. 8850 8851There are many filters and image generators provided by Apple that come with a 8852large variety of options. The filter has to be referenced by its name along 8853with its options. 8854 8855The coreimage filter accepts the following options: 8856@table @option 8857@item list_filters 8858List all available filters and generators along with all their respective 8859options as well as possible minimum and maximum values along with the default 8860values. 8861@example 8862list_filters=true 8863@end example 8864 8865@item filter 8866Specify all filters by their respective name and options. 8867Use @var{list_filters} to determine all valid filter names and options. 8868Numerical options are specified by a float value and are automatically clamped 8869to their respective value range. Vector and color options have to be specified 8870by a list of space separated float values. Character escaping has to be done. 8871A special option name @code{default} is available to use default options for a 8872filter. 8873 8874It is required to specify either @code{default} or at least one of the filter options. 8875All omitted options are used with their default values. 8876The syntax of the filter string is as follows: 8877@example 8878filter=<NAME>@@<OPTION>=<VALUE>[@@<OPTION>=<VALUE>][@@...][#<NAME>@@<OPTION>=<VALUE>[@@<OPTION>=<VALUE>][@@...]][#...] 8879@end example 8880 8881@item output_rect 8882Specify a rectangle where the output of the filter chain is copied into the 8883input image. It is given by a list of space separated float values: 8884@example 8885output_rect=x\ y\ width\ height 8886@end example 8887If not given, the output rectangle equals the dimensions of the input image. 8888The output rectangle is automatically cropped at the borders of the input 8889image. Negative values are valid for each component. 8890@example 8891output_rect=25\ 25\ 100\ 100 8892@end example 8893@end table 8894 8895Several filters can be chained for successive processing without GPU-HOST 8896transfers allowing for fast processing of complex filter chains. 8897Currently, only filters with zero (generators) or exactly one (filters) input 8898image and one output image are supported. Also, transition filters are not yet 8899usable as intended. 8900 8901Some filters generate output images with additional padding depending on the 8902respective filter kernel. The padding is automatically removed to ensure the 8903filter output has the same size as the input image. 8904 8905For image generators, the size of the output image is determined by the 8906previous output image of the filter chain or the input image of the whole 8907filterchain, respectively. The generators do not use the pixel information of 8908this image to generate their output. However, the generated output is 8909blended onto this image, resulting in partial or complete coverage of the 8910output image. 8911 8912The @ref{coreimagesrc} video source can be used for generating input images 8913which are directly fed into the filter chain. By using it, providing input 8914images by another video source or an input video is not required. 8915 8916@subsection Examples 8917 8918@itemize 8919 8920@item 8921List all filters available: 8922@example 8923coreimage=list_filters=true 8924@end example 8925 8926@item 8927Use the CIBoxBlur filter with default options to blur an image: 8928@example 8929coreimage=filter=CIBoxBlur@@default 8930@end example 8931 8932@item 8933Use a filter chain with CISepiaTone at default values and CIVignetteEffect with 8934its center at 100x100 and a radius of 50 pixels: 8935@example 8936coreimage=filter=CIBoxBlur@@default#CIVignetteEffect@@inputCenter=100\ 100@@inputRadius=50 8937@end example 8938 8939@item 8940Use nullsrc and CIQRCodeGenerator to create a QR code for the FFmpeg homepage, 8941given as complete and escaped command-line for Apple's standard bash shell: 8942@example 8943ffmpeg -f lavfi -i nullsrc=s=100x100,coreimage=filter=CIQRCodeGenerator@@inputMessage=https\\\\\://FFmpeg.org/@@inputCorrectionLevel=H -frames:v 1 QRCode.png 8944@end example 8945@end itemize 8946 8947@section cover_rect 8948 8949Cover a rectangular object 8950 8951It accepts the following options: 8952 8953@table @option 8954@item cover 8955Filepath of the optional cover image, needs to be in yuv420. 8956 8957@item mode 8958Set covering mode. 8959 8960It accepts the following values: 8961@table @samp 8962@item cover 8963cover it by the supplied image 8964@item blur 8965cover it by interpolating the surrounding pixels 8966@end table 8967 8968Default value is @var{blur}. 8969@end table 8970 8971@subsection Examples 8972 8973@itemize 8974@item 8975Cover a rectangular object by the supplied image of a given video using @command{ffmpeg}: 8976@example 8977ffmpeg -i file.ts -vf find_rect=newref.pgm,cover_rect=cover.jpg:mode=cover new.mkv 8978@end example 8979@end itemize 8980 8981@section crop 8982 8983Crop the input video to given dimensions. 8984 8985It accepts the following parameters: 8986 8987@table @option 8988@item w, out_w 8989The width of the output video. It defaults to @code{iw}. 8990This expression is evaluated only once during the filter 8991configuration, or when the @samp{w} or @samp{out_w} command is sent. 8992 8993@item h, out_h 8994The height of the output video. It defaults to @code{ih}. 8995This expression is evaluated only once during the filter 8996configuration, or when the @samp{h} or @samp{out_h} command is sent. 8997 8998@item x 8999The horizontal position, in the input video, of the left edge of the output 9000video. It defaults to @code{(in_w-out_w)/2}. 9001This expression is evaluated per-frame. 9002 9003@item y 9004The vertical position, in the input video, of the top edge of the output video. 9005It defaults to @code{(in_h-out_h)/2}. 9006This expression is evaluated per-frame. 9007 9008@item keep_aspect 9009If set to 1 will force the output display aspect ratio 9010to be the same of the input, by changing the output sample aspect 9011ratio. It defaults to 0. 9012 9013@item exact 9014Enable exact cropping. If enabled, subsampled videos will be cropped at exact 9015width/height/x/y as specified and will not be rounded to nearest smaller value. 9016It defaults to 0. 9017@end table 9018 9019The @var{out_w}, @var{out_h}, @var{x}, @var{y} parameters are 9020expressions containing the following constants: 9021 9022@table @option 9023@item x 9024@item y 9025The computed values for @var{x} and @var{y}. They are evaluated for 9026each new frame. 9027 9028@item in_w 9029@item in_h 9030The input width and height. 9031 9032@item iw 9033@item ih 9034These are the same as @var{in_w} and @var{in_h}. 9035 9036@item out_w 9037@item out_h 9038The output (cropped) width and height. 9039 9040@item ow 9041@item oh 9042These are the same as @var{out_w} and @var{out_h}. 9043 9044@item a 9045same as @var{iw} / @var{ih} 9046 9047@item sar 9048input sample aspect ratio 9049 9050@item dar 9051input display aspect ratio, it is the same as (@var{iw} / @var{ih}) * @var{sar} 9052 9053@item hsub 9054@item vsub 9055horizontal and vertical chroma subsample values. For example for the 9056pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1. 9057 9058@item n 9059The number of the input frame, starting from 0. 9060 9061@item pos 9062the position in the file of the input frame, NAN if unknown 9063 9064@item t 9065The timestamp expressed in seconds. It's NAN if the input timestamp is unknown. 9066 9067@end table 9068 9069The expression for @var{out_w} may depend on the value of @var{out_h}, 9070and the expression for @var{out_h} may depend on @var{out_w}, but they 9071cannot depend on @var{x} and @var{y}, as @var{x} and @var{y} are 9072evaluated after @var{out_w} and @var{out_h}. 9073 9074The @var{x} and @var{y} parameters specify the expressions for the 9075position of the top-left corner of the output (non-cropped) area. They 9076are evaluated for each frame. If the evaluated value is not valid, it 9077is approximated to the nearest valid value. 9078 9079The expression for @var{x} may depend on @var{y}, and the expression 9080for @var{y} may depend on @var{x}. 9081 9082@subsection Examples 9083 9084@itemize 9085@item 9086Crop area with size 100x100 at position (12,34). 9087@example 9088crop=100:100:12:34 9089@end example 9090 9091Using named options, the example above becomes: 9092@example 9093crop=w=100:h=100:x=12:y=34 9094@end example 9095 9096@item 9097Crop the central input area with size 100x100: 9098@example 9099crop=100:100 9100@end example 9101 9102@item 9103Crop the central input area with size 2/3 of the input video: 9104@example 9105crop=2/3*in_w:2/3*in_h 9106@end example 9107 9108@item 9109Crop the input video central square: 9110@example 9111crop=out_w=in_h 9112crop=in_h 9113@end example 9114 9115@item 9116Delimit the rectangle with the top-left corner placed at position 9117100:100 and the right-bottom corner corresponding to the right-bottom 9118corner of the input image. 9119@example 9120crop=in_w-100:in_h-100:100:100 9121@end example 9122 9123@item 9124Crop 10 pixels from the left and right borders, and 20 pixels from 9125the top and bottom borders 9126@example 9127crop=in_w-2*10:in_h-2*20 9128@end example 9129 9130@item 9131Keep only the bottom right quarter of the input image: 9132@example 9133crop=in_w/2:in_h/2:in_w/2:in_h/2 9134@end example 9135 9136@item 9137Crop height for getting Greek harmony: 9138@example 9139crop=in_w:1/PHI*in_w 9140@end example 9141 9142@item 9143Apply trembling effect: 9144@example 9145crop=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) 9146@end example 9147 9148@item 9149Apply erratic camera effect depending on timestamp: 9150@example 9151crop=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)" 9152@end example 9153 9154@item 9155Set x depending on the value of y: 9156@example 9157crop=in_w/2:in_h/2:y:10+10*sin(n/10) 9158@end example 9159@end itemize 9160 9161@subsection Commands 9162 9163This filter supports the following commands: 9164@table @option 9165@item w, out_w 9166@item h, out_h 9167@item x 9168@item y 9169Set width/height of the output video and the horizontal/vertical position 9170in the input video. 9171The command accepts the same syntax of the corresponding option. 9172 9173If the specified expression is not valid, it is kept at its current 9174value. 9175@end table 9176 9177@section cropdetect 9178 9179Auto-detect the crop size. 9180 9181It calculates the necessary cropping parameters and prints the 9182recommended parameters via the logging system. The detected dimensions 9183correspond to the non-black area of the input video. 9184 9185It accepts the following parameters: 9186 9187@table @option 9188 9189@item limit 9190Set higher black value threshold, which can be optionally specified 9191from nothing (0) to everything (255 for 8-bit based formats). An intensity 9192value greater to the set value is considered non-black. It defaults to 24. 9193You can also specify a value between 0.0 and 1.0 which will be scaled depending 9194on the bitdepth of the pixel format. 9195 9196@item round 9197The value which the width/height should be divisible by. It defaults to 919816. The offset is automatically adjusted to center the video. Use 2 to 9199get only even dimensions (needed for 4:2:2 video). 16 is best when 9200encoding to most video codecs. 9201 9202@item skip 9203Set the number of initial frames for which evaluation is skipped. 9204Default is 2. Range is 0 to INT_MAX. 9205 9206@item reset_count, reset 9207Set the counter that determines after how many frames cropdetect will 9208reset the previously detected largest video area and start over to 9209detect the current optimal crop area. Default value is 0. 9210 9211This can be useful when channel logos distort the video area. 0 9212indicates 'never reset', and returns the largest area encountered during 9213playback. 9214@end table 9215 9216@anchor{cue} 9217@section cue 9218 9219Delay video filtering until a given wallclock timestamp. The filter first 9220passes on @option{preroll} amount of frames, then it buffers at most 9221@option{buffer} amount of frames and waits for the cue. After reaching the cue 9222it forwards the buffered frames and also any subsequent frames coming in its 9223input. 9224 9225The filter can be used synchronize the output of multiple ffmpeg processes for 9226realtime output devices like decklink. By putting the delay in the filtering 9227chain and pre-buffering frames the process can pass on data to output almost 9228immediately after the target wallclock timestamp is reached. 9229 9230Perfect frame accuracy cannot be guaranteed, but the result is good enough for 9231some use cases. 9232 9233@table @option 9234 9235@item cue 9236The cue timestamp expressed in a UNIX timestamp in microseconds. Default is 0. 9237 9238@item preroll 9239The duration of content to pass on as preroll expressed in seconds. Default is 0. 9240 9241@item buffer 9242The maximum duration of content to buffer before waiting for the cue expressed 9243in seconds. Default is 0. 9244 9245@end table 9246 9247@anchor{curves} 9248@section curves 9249 9250Apply color adjustments using curves. 9251 9252This filter is similar to the Adobe Photoshop and GIMP curves tools. Each 9253component (red, green and blue) has its values defined by @var{N} key points 9254tied from each other using a smooth curve. The x-axis represents the pixel 9255values from the input frame, and the y-axis the new pixel values to be set for 9256the output frame. 9257 9258By default, a component curve is defined by the two points @var{(0;0)} and 9259@var{(1;1)}. This creates a straight line where each original pixel value is 9260"adjusted" to its own value, which means no change to the image. 9261 9262The filter allows you to redefine these two points and add some more. A new 9263curve (using a natural cubic spline interpolation) will be define to pass 9264smoothly through all these new coordinates. The new defined points needs to be 9265strictly increasing over the x-axis, and their @var{x} and @var{y} values must 9266be in the @var{[0;1]} interval. If the computed curves happened to go outside 9267the vector spaces, the values will be clipped accordingly. 9268 9269The filter accepts the following options: 9270 9271@table @option 9272@item preset 9273Select one of the available color presets. This option can be used in addition 9274to the @option{r}, @option{g}, @option{b} parameters; in this case, the later 9275options takes priority on the preset values. 9276Available presets are: 9277@table @samp 9278@item none 9279@item color_negative 9280@item cross_process 9281@item darker 9282@item increase_contrast 9283@item lighter 9284@item linear_contrast 9285@item medium_contrast 9286@item negative 9287@item strong_contrast 9288@item vintage 9289@end table 9290Default is @code{none}. 9291@item master, m 9292Set the master key points. These points will define a second pass mapping. It 9293is sometimes called a "luminance" or "value" mapping. It can be used with 9294@option{r}, @option{g}, @option{b} or @option{all} since it acts like a 9295post-processing LUT. 9296@item red, r 9297Set the key points for the red component. 9298@item green, g 9299Set the key points for the green component. 9300@item blue, b 9301Set the key points for the blue component. 9302@item all 9303Set the key points for all components (not including master). 9304Can be used in addition to the other key points component 9305options. In this case, the unset component(s) will fallback on this 9306@option{all} setting. 9307@item psfile 9308Specify a Photoshop curves file (@code{.acv}) to import the settings from. 9309@item plot 9310Save Gnuplot script of the curves in specified file. 9311@end table 9312 9313To avoid some filtergraph syntax conflicts, each key points list need to be 9314defined using the following syntax: @code{x0/y0 x1/y1 x2/y2 ...}. 9315 9316@subsection Commands 9317 9318This filter supports same @ref{commands} as options. 9319 9320@subsection Examples 9321 9322@itemize 9323@item 9324Increase slightly the middle level of blue: 9325@example 9326curves=blue='0/0 0.5/0.58 1/1' 9327@end example 9328 9329@item 9330Vintage effect: 9331@example 9332curves=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' 9333@end example 9334Here we obtain the following coordinates for each components: 9335@table @var 9336@item red 9337@code{(0;0.11) (0.42;0.51) (1;0.95)} 9338@item green 9339@code{(0;0) (0.50;0.48) (1;1)} 9340@item blue 9341@code{(0;0.22) (0.49;0.44) (1;0.80)} 9342@end table 9343 9344@item 9345The previous example can also be achieved with the associated built-in preset: 9346@example 9347curves=preset=vintage 9348@end example 9349 9350@item 9351Or simply: 9352@example 9353curves=vintage 9354@end example 9355 9356@item 9357Use a Photoshop preset and redefine the points of the green component: 9358@example 9359curves=psfile='MyCurvesPresets/purple.acv':green='0/0 0.45/0.53 1/1' 9360@end example 9361 9362@item 9363Check out the curves of the @code{cross_process} profile using @command{ffmpeg} 9364and @command{gnuplot}: 9365@example 9366ffmpeg -f lavfi -i color -vf curves=cross_process:plot=/tmp/curves.plt -frames:v 1 -f null - 9367gnuplot -p /tmp/curves.plt 9368@end example 9369@end itemize 9370 9371@section datascope 9372 9373Video data analysis filter. 9374 9375This filter shows hexadecimal pixel values of part of video. 9376 9377The filter accepts the following options: 9378 9379@table @option 9380@item size, s 9381Set output video size. 9382 9383@item x 9384Set x offset from where to pick pixels. 9385 9386@item y 9387Set y offset from where to pick pixels. 9388 9389@item mode 9390Set scope mode, can be one of the following: 9391@table @samp 9392@item mono 9393Draw hexadecimal pixel values with white color on black background. 9394 9395@item color 9396Draw hexadecimal pixel values with input video pixel color on black 9397background. 9398 9399@item color2 9400Draw hexadecimal pixel values on color background picked from input video, 9401the text color is picked in such way so its always visible. 9402@end table 9403 9404@item axis 9405Draw rows and columns numbers on left and top of video. 9406 9407@item opacity 9408Set background opacity. 9409 9410@item format 9411Set display number format. Can be @code{hex}, or @code{dec}. Default is @code{hex}. 9412 9413@item components 9414Set pixel components to display. By default all pixel components are displayed. 9415@end table 9416 9417@subsection Commands 9418 9419This filter supports same @ref{commands} as options excluding @code{size} option. 9420 9421@section dblur 9422Apply Directional blur filter. 9423 9424The filter accepts the following options: 9425 9426@table @option 9427@item angle 9428Set angle of directional blur. Default is @code{45}. 9429 9430@item radius 9431Set radius of directional blur. Default is @code{5}. 9432 9433@item planes 9434Set which planes to filter. By default all planes are filtered. 9435@end table 9436 9437@subsection Commands 9438This filter supports same @ref{commands} as options. 9439The command accepts the same syntax of the corresponding option. 9440 9441If the specified expression is not valid, it is kept at its current 9442value. 9443 9444@section dctdnoiz 9445 9446Denoise frames using 2D DCT (frequency domain filtering). 9447 9448This filter is not designed for real time. 9449 9450The filter accepts the following options: 9451 9452@table @option 9453@item sigma, s 9454Set the noise sigma constant. 9455 9456This @var{sigma} defines a hard threshold of @code{3 * sigma}; every DCT 9457coefficient (absolute value) below this threshold with be dropped. 9458 9459If you need a more advanced filtering, see @option{expr}. 9460 9461Default is @code{0}. 9462 9463@item overlap 9464Set number overlapping pixels for each block. Since the filter can be slow, you 9465may want to reduce this value, at the cost of a less effective filter and the 9466risk of various artefacts. 9467 9468If the overlapping value doesn't permit processing the whole input width or 9469height, a warning will be displayed and according borders won't be denoised. 9470 9471Default value is @var{blocksize}-1, which is the best possible setting. 9472 9473@item expr, e 9474Set the coefficient factor expression. 9475 9476For each coefficient of a DCT block, this expression will be evaluated as a 9477multiplier value for the coefficient. 9478 9479If this is option is set, the @option{sigma} option will be ignored. 9480 9481The absolute value of the coefficient can be accessed through the @var{c} 9482variable. 9483 9484@item n 9485Set the @var{blocksize} using the number of bits. @code{1<<@var{n}} defines the 9486@var{blocksize}, which is the width and height of the processed blocks. 9487 9488The default value is @var{3} (8x8) and can be raised to @var{4} for a 9489@var{blocksize} of 16x16. Note that changing this setting has huge consequences 9490on the speed processing. Also, a larger block size does not necessarily means a 9491better de-noising. 9492@end table 9493 9494@subsection Examples 9495 9496Apply a denoise with a @option{sigma} of @code{4.5}: 9497@example 9498dctdnoiz=4.5 9499@end example 9500 9501The same operation can be achieved using the expression system: 9502@example 9503dctdnoiz=e='gte(c, 4.5*3)' 9504@end example 9505 9506Violent denoise using a block size of @code{16x16}: 9507@example 9508dctdnoiz=15:n=4 9509@end example 9510 9511@section deband 9512 9513Remove banding artifacts from input video. 9514It works by replacing banded pixels with average value of referenced pixels. 9515 9516The filter accepts the following options: 9517 9518@table @option 9519@item 1thr 9520@item 2thr 9521@item 3thr 9522@item 4thr 9523Set banding detection threshold for each plane. Default is 0.02. 9524Valid range is 0.00003 to 0.5. 9525If difference between current pixel and reference pixel is less than threshold, 9526it will be considered as banded. 9527 9528@item range, r 9529Banding detection range in pixels. Default is 16. If positive, random number 9530in range 0 to set value will be used. If negative, exact absolute value 9531will be used. 9532The range defines square of four pixels around current pixel. 9533 9534@item direction, d 9535Set direction in radians from which four pixel will be compared. If positive, 9536random direction from 0 to set direction will be picked. If negative, exact of 9537absolute value will be picked. For example direction 0, -PI or -2*PI radians 9538will pick only pixels on same row and -PI/2 will pick only pixels on same 9539column. 9540 9541@item blur, b 9542If enabled, current pixel is compared with average value of all four 9543surrounding pixels. The default is enabled. If disabled current pixel is 9544compared with all four surrounding pixels. The pixel is considered banded 9545if only all four differences with surrounding pixels are less than threshold. 9546 9547@item coupling, c 9548If enabled, current pixel is changed if and only if all pixel components are banded, 9549e.g. banding detection threshold is triggered for all color components. 9550The default is disabled. 9551@end table 9552 9553@subsection Commands 9554 9555This filter supports the all above options as @ref{commands}. 9556 9557@section deblock 9558 9559Remove blocking artifacts from input video. 9560 9561The filter accepts the following options: 9562 9563@table @option 9564@item filter 9565Set filter type, can be @var{weak} or @var{strong}. Default is @var{strong}. 9566This controls what kind of deblocking is applied. 9567 9568@item block 9569Set size of block, allowed range is from 4 to 512. Default is @var{8}. 9570 9571@item alpha 9572@item beta 9573@item gamma 9574@item delta 9575Set blocking detection thresholds. Allowed range is 0 to 1. 9576Defaults are: @var{0.098} for @var{alpha} and @var{0.05} for the rest. 9577Using higher threshold gives more deblocking strength. 9578Setting @var{alpha} controls threshold detection at exact edge of block. 9579Remaining options controls threshold detection near the edge. Each one for 9580below/above or left/right. Setting any of those to @var{0} disables 9581deblocking. 9582 9583@item planes 9584Set planes to filter. Default is to filter all available planes. 9585@end table 9586 9587@subsection Examples 9588 9589@itemize 9590@item 9591Deblock using weak filter and block size of 4 pixels. 9592@example 9593deblock=filter=weak:block=4 9594@end example 9595 9596@item 9597Deblock using strong filter, block size of 4 pixels and custom thresholds for 9598deblocking more edges. 9599@example 9600deblock=filter=strong:block=4:alpha=0.12:beta=0.07:gamma=0.06:delta=0.05 9601@end example 9602 9603@item 9604Similar as above, but filter only first plane. 9605@example 9606deblock=filter=strong:block=4:alpha=0.12:beta=0.07:gamma=0.06:delta=0.05:planes=1 9607@end example 9608 9609@item 9610Similar as above, but filter only second and third plane. 9611@example 9612deblock=filter=strong:block=4:alpha=0.12:beta=0.07:gamma=0.06:delta=0.05:planes=6 9613@end example 9614@end itemize 9615 9616@subsection Commands 9617 9618This filter supports the all above options as @ref{commands}. 9619 9620@anchor{decimate} 9621@section decimate 9622 9623Drop duplicated frames at regular intervals. 9624 9625The filter accepts the following options: 9626 9627@table @option 9628@item cycle 9629Set the number of frames from which one will be dropped. Setting this to 9630@var{N} means one frame in every batch of @var{N} frames will be dropped. 9631Default is @code{5}. 9632 9633@item dupthresh 9634Set the threshold for duplicate detection. If the difference metric for a frame 9635is less than or equal to this value, then it is declared as duplicate. Default 9636is @code{1.1} 9637 9638@item scthresh 9639Set scene change threshold. Default is @code{15}. 9640 9641@item blockx 9642@item blocky 9643Set the size of the x and y-axis blocks used during metric calculations. 9644Larger blocks give better noise suppression, but also give worse detection of 9645small movements. Must be a power of two. Default is @code{32}. 9646 9647@item ppsrc 9648Mark main input as a pre-processed input and activate clean source input 9649stream. This allows the input to be pre-processed with various filters to help 9650the metrics calculation while keeping the frame selection lossless. When set to 9651@code{1}, the first stream is for the pre-processed input, and the second 9652stream is the clean source from where the kept frames are chosen. Default is 9653@code{0}. 9654 9655@item chroma 9656Set whether or not chroma is considered in the metric calculations. Default is 9657@code{1}. 9658@end table 9659 9660@section deconvolve 9661 9662Apply 2D deconvolution of video stream in frequency domain using second stream 9663as impulse. 9664 9665The filter accepts the following options: 9666 9667@table @option 9668@item planes 9669Set which planes to process. 9670 9671@item impulse 9672Set which impulse video frames will be processed, can be @var{first} 9673or @var{all}. Default is @var{all}. 9674 9675@item noise 9676Set noise when doing divisions. Default is @var{0.0000001}. Useful when width 9677and height are not same and not power of 2 or if stream prior to convolving 9678had noise. 9679@end table 9680 9681The @code{deconvolve} filter also supports the @ref{framesync} options. 9682 9683@section dedot 9684 9685Reduce cross-luminance (dot-crawl) and cross-color (rainbows) from video. 9686 9687It accepts the following options: 9688 9689@table @option 9690@item m 9691Set mode of operation. Can be combination of @var{dotcrawl} for cross-luminance reduction and/or 9692@var{rainbows} for cross-color reduction. 9693 9694@item lt 9695Set spatial luma threshold. Lower values increases reduction of cross-luminance. 9696 9697@item tl 9698Set tolerance for temporal luma. Higher values increases reduction of cross-luminance. 9699 9700@item tc 9701Set tolerance for chroma temporal variation. Higher values increases reduction of cross-color. 9702 9703@item ct 9704Set temporal chroma threshold. Lower values increases reduction of cross-color. 9705@end table 9706 9707@section deflate 9708 9709Apply deflate effect to the video. 9710 9711This filter replaces the pixel by the local(3x3) average by taking into account 9712only values lower than the pixel. 9713 9714It accepts the following options: 9715 9716@table @option 9717@item threshold0 9718@item threshold1 9719@item threshold2 9720@item threshold3 9721Limit the maximum change for each plane, default is 65535. 9722If 0, plane will remain unchanged. 9723@end table 9724 9725@subsection Commands 9726 9727This filter supports the all above options as @ref{commands}. 9728 9729@section deflicker 9730 9731Remove temporal frame luminance variations. 9732 9733It accepts the following options: 9734 9735@table @option 9736@item size, s 9737Set moving-average filter size in frames. Default is 5. Allowed range is 2 - 129. 9738 9739@item mode, m 9740Set averaging mode to smooth temporal luminance variations. 9741 9742Available values are: 9743@table @samp 9744@item am 9745Arithmetic mean 9746 9747@item gm 9748Geometric mean 9749 9750@item hm 9751Harmonic mean 9752 9753@item qm 9754Quadratic mean 9755 9756@item cm 9757Cubic mean 9758 9759@item pm 9760Power mean 9761 9762@item median 9763Median 9764@end table 9765 9766@item bypass 9767Do not actually modify frame. Useful when one only wants metadata. 9768@end table 9769 9770@section dejudder 9771 9772Remove judder produced by partially interlaced telecined content. 9773 9774Judder can be introduced, for instance, by @ref{pullup} filter. If the original 9775source was partially telecined content then the output of @code{pullup,dejudder} 9776will have a variable frame rate. May change the recorded frame rate of the 9777container. Aside from that change, this filter will not affect constant frame 9778rate video. 9779 9780The option available in this filter is: 9781@table @option 9782 9783@item cycle 9784Specify the length of the window over which the judder repeats. 9785 9786Accepts any integer greater than 1. Useful values are: 9787@table @samp 9788 9789@item 4 9790If the original was telecined from 24 to 30 fps (Film to NTSC). 9791 9792@item 5 9793If the original was telecined from 25 to 30 fps (PAL to NTSC). 9794 9795@item 20 9796If a mixture of the two. 9797@end table 9798 9799The default is @samp{4}. 9800@end table 9801 9802@section delogo 9803 9804Suppress a TV station logo by a simple interpolation of the surrounding 9805pixels. Just set a rectangle covering the logo and watch it disappear 9806(and sometimes something even uglier appear - your mileage may vary). 9807 9808It accepts the following parameters: 9809@table @option 9810 9811@item x 9812@item y 9813Specify the top left corner coordinates of the logo. They must be 9814specified. 9815 9816@item w 9817@item h 9818Specify the width and height of the logo to clear. They must be 9819specified. 9820 9821@item show 9822When set to 1, a green rectangle is drawn on the screen to simplify 9823finding the right @var{x}, @var{y}, @var{w}, and @var{h} parameters. 9824The default value is 0. 9825 9826The rectangle is drawn on the outermost pixels which will be (partly) 9827replaced with interpolated values. The values of the next pixels 9828immediately outside this rectangle in each direction will be used to 9829compute the interpolated pixel values inside the rectangle. 9830 9831@end table 9832 9833@subsection Examples 9834 9835@itemize 9836@item 9837Set a rectangle covering the area with top left corner coordinates 0,0 9838and size 100x77: 9839@example 9840delogo=x=0:y=0:w=100:h=77 9841@end example 9842 9843@end itemize 9844 9845@anchor{derain} 9846@section derain 9847 9848Remove the rain in the input image/video by applying the derain methods based on 9849convolutional neural networks. Supported models: 9850 9851@itemize 9852@item 9853Recurrent Squeeze-and-Excitation Context Aggregation Net (RESCAN). 9854See @url{http://openaccess.thecvf.com/content_ECCV_2018/papers/Xia_Li_Recurrent_Squeeze-and-Excitation_Context_ECCV_2018_paper.pdf}. 9855@end itemize 9856 9857Training as well as model generation scripts are provided in 9858the repository at @url{https://github.com/XueweiMeng/derain_filter.git}. 9859 9860Native model files (.model) can be generated from TensorFlow model 9861files (.pb) by using tools/python/convert.py 9862 9863The filter accepts the following options: 9864 9865@table @option 9866@item filter_type 9867Specify which filter to use. This option accepts the following values: 9868 9869@table @samp 9870@item derain 9871Derain filter. To conduct derain filter, you need to use a derain model. 9872 9873@item dehaze 9874Dehaze filter. To conduct dehaze filter, you need to use a dehaze model. 9875@end table 9876Default value is @samp{derain}. 9877 9878@item dnn_backend 9879Specify which DNN backend to use for model loading and execution. This option accepts 9880the following values: 9881 9882@table @samp 9883@item native 9884Native implementation of DNN loading and execution. 9885 9886@item tensorflow 9887TensorFlow backend. To enable this backend you 9888need to install the TensorFlow for C library (see 9889@url{https://www.tensorflow.org/install/install_c}) and configure FFmpeg with 9890@code{--enable-libtensorflow} 9891@end table 9892Default value is @samp{native}. 9893 9894@item model 9895Set path to model file specifying network architecture and its parameters. 9896Note that different backends use different file formats. TensorFlow and native 9897backend can load files for only its format. 9898@end table 9899 9900It can also be finished with @ref{dnn_processing} filter. 9901 9902@section deshake 9903 9904Attempt to fix small changes in horizontal and/or vertical shift. This 9905filter helps remove camera shake from hand-holding a camera, bumping a 9906tripod, moving on a vehicle, etc. 9907 9908The filter accepts the following options: 9909 9910@table @option 9911 9912@item x 9913@item y 9914@item w 9915@item h 9916Specify a rectangular area where to limit the search for motion 9917vectors. 9918If desired the search for motion vectors can be limited to a 9919rectangular area of the frame defined by its top left corner, width 9920and height. These parameters have the same meaning as the drawbox 9921filter which can be used to visualise the position of the bounding 9922box. 9923 9924This is useful when simultaneous movement of subjects within the frame 9925might be confused for camera motion by the motion vector search. 9926 9927If any or all of @var{x}, @var{y}, @var{w} and @var{h} are set to -1 9928then the full frame is used. This allows later options to be set 9929without specifying the bounding box for the motion vector search. 9930 9931Default - search the whole frame. 9932 9933@item rx 9934@item ry 9935Specify the maximum extent of movement in x and y directions in the 9936range 0-64 pixels. Default 16. 9937 9938@item edge 9939Specify how to generate pixels to fill blanks at the edge of the 9940frame. Available values are: 9941@table @samp 9942@item blank, 0 9943Fill zeroes at blank locations 9944@item original, 1 9945Original image at blank locations 9946@item clamp, 2 9947Extruded edge value at blank locations 9948@item mirror, 3 9949Mirrored edge at blank locations 9950@end table 9951Default value is @samp{mirror}. 9952 9953@item blocksize 9954Specify the blocksize to use for motion search. Range 4-128 pixels, 9955default 8. 9956 9957@item contrast 9958Specify the contrast threshold for blocks. Only blocks with more than 9959the specified contrast (difference between darkest and lightest 9960pixels) will be considered. Range 1-255, default 125. 9961 9962@item search 9963Specify the search strategy. Available values are: 9964@table @samp 9965@item exhaustive, 0 9966Set exhaustive search 9967@item less, 1 9968Set less exhaustive search. 9969@end table 9970Default value is @samp{exhaustive}. 9971 9972@item filename 9973If set then a detailed log of the motion search is written to the 9974specified file. 9975 9976@end table 9977 9978@section despill 9979 9980Remove unwanted contamination of foreground colors, caused by reflected color of 9981greenscreen or bluescreen. 9982 9983This filter accepts the following options: 9984 9985@table @option 9986@item type 9987Set what type of despill to use. 9988 9989@item mix 9990Set how spillmap will be generated. 9991 9992@item expand 9993Set how much to get rid of still remaining spill. 9994 9995@item red 9996Controls amount of red in spill area. 9997 9998@item green 9999Controls amount of green in spill area. 10000Should be -1 for greenscreen. 10001 10002@item blue 10003Controls amount of blue in spill area. 10004Should be -1 for bluescreen. 10005 10006@item brightness 10007Controls brightness of spill area, preserving colors. 10008 10009@item alpha 10010Modify alpha from generated spillmap. 10011@end table 10012 10013@subsection Commands 10014 10015This filter supports the all above options as @ref{commands}. 10016 10017@section detelecine 10018 10019Apply an exact inverse of the telecine operation. It requires a predefined 10020pattern specified using the pattern option which must be the same as that passed 10021to the telecine filter. 10022 10023This filter accepts the following options: 10024 10025@table @option 10026@item first_field 10027@table @samp 10028@item top, t 10029top field first 10030@item bottom, b 10031bottom field first 10032The default value is @code{top}. 10033@end table 10034 10035@item pattern 10036A string of numbers representing the pulldown pattern you wish to apply. 10037The default value is @code{23}. 10038 10039@item start_frame 10040A number representing position of the first frame with respect to the telecine 10041pattern. This is to be used if the stream is cut. The default value is @code{0}. 10042@end table 10043 10044@section dilation 10045 10046Apply dilation effect to the video. 10047 10048This filter replaces the pixel by the local(3x3) maximum. 10049 10050It accepts the following options: 10051 10052@table @option 10053@item threshold0 10054@item threshold1 10055@item threshold2 10056@item threshold3 10057Limit the maximum change for each plane, default is 65535. 10058If 0, plane will remain unchanged. 10059 10060@item coordinates 10061Flag which specifies the pixel to refer to. Default is 255 i.e. all eight 10062pixels are used. 10063 10064Flags to local 3x3 coordinates maps like this: 10065 10066 1 2 3 10067 4 5 10068 6 7 8 10069@end table 10070 10071@subsection Commands 10072 10073This filter supports the all above options as @ref{commands}. 10074 10075@section displace 10076 10077Displace pixels as indicated by second and third input stream. 10078 10079It takes three input streams and outputs one stream, the first input is the 10080source, and second and third input are displacement maps. 10081 10082The second input specifies how much to displace pixels along the 10083x-axis, while the third input specifies how much to displace pixels 10084along the y-axis. 10085If one of displacement map streams terminates, last frame from that 10086displacement map will be used. 10087 10088Note that once generated, displacements maps can be reused over and over again. 10089 10090A description of the accepted options follows. 10091 10092@table @option 10093@item edge 10094Set displace behavior for pixels that are out of range. 10095 10096Available values are: 10097@table @samp 10098@item blank 10099Missing pixels are replaced by black pixels. 10100 10101@item smear 10102Adjacent pixels will spread out to replace missing pixels. 10103 10104@item wrap 10105Out of range pixels are wrapped so they point to pixels of other side. 10106 10107@item mirror 10108Out of range pixels will be replaced with mirrored pixels. 10109@end table 10110Default is @samp{smear}. 10111 10112@end table 10113 10114@subsection Examples 10115 10116@itemize 10117@item 10118Add ripple effect to rgb input of video size hd720: 10119@example 10120ffmpeg -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 10121@end example 10122 10123@item 10124Add wave effect to rgb input of video size hd720: 10125@example 10126ffmpeg -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 10127@end example 10128@end itemize 10129 10130@anchor{dnn_processing} 10131@section dnn_processing 10132 10133Do image processing with deep neural networks. It works together with another filter 10134which converts the pixel format of the Frame to what the dnn network requires. 10135 10136The filter accepts the following options: 10137 10138@table @option 10139@item dnn_backend 10140Specify which DNN backend to use for model loading and execution. This option accepts 10141the following values: 10142 10143@table @samp 10144@item native 10145Native implementation of DNN loading and execution. 10146 10147@item tensorflow 10148TensorFlow backend. To enable this backend you 10149need to install the TensorFlow for C library (see 10150@url{https://www.tensorflow.org/install/install_c}) and configure FFmpeg with 10151@code{--enable-libtensorflow} 10152 10153@item openvino 10154OpenVINO backend. To enable this backend you 10155need to build and install the OpenVINO for C library (see 10156@url{https://github.com/openvinotoolkit/openvino/blob/master/build-instruction.md}) and configure FFmpeg with 10157@code{--enable-libopenvino} (--extra-cflags=-I... --extra-ldflags=-L... might 10158be needed if the header files and libraries are not installed into system path) 10159 10160@end table 10161 10162Default value is @samp{native}. 10163 10164@item model 10165Set path to model file specifying network architecture and its parameters. 10166Note that different backends use different file formats. TensorFlow, OpenVINO and native 10167backend can load files for only its format. 10168 10169Native model file (.model) can be generated from TensorFlow model file (.pb) by using tools/python/convert.py 10170 10171@item input 10172Set the input name of the dnn network. 10173 10174@item output 10175Set the output name of the dnn network. 10176 10177@item async 10178use DNN async execution if set (default: set), 10179roll back to sync execution if the backend does not support async. 10180 10181@end table 10182 10183@subsection Examples 10184 10185@itemize 10186@item 10187Remove rain in rgb24 frame with can.pb (see @ref{derain} filter): 10188@example 10189./ffmpeg -i rain.jpg -vf format=rgb24,dnn_processing=dnn_backend=tensorflow:model=can.pb:input=x:output=y derain.jpg 10190@end example 10191 10192@item 10193Halve the pixel value of the frame with format gray32f: 10194@example 10195ffmpeg -i input.jpg -vf format=grayf32,dnn_processing=model=halve_gray_float.model:input=dnn_in:output=dnn_out:dnn_backend=native -y out.native.png 10196@end example 10197 10198@item 10199Handle the Y channel with srcnn.pb (see @ref{sr} filter) for frame with yuv420p (planar YUV formats supported): 10200@example 10201./ffmpeg -i 480p.jpg -vf format=yuv420p,scale=w=iw*2:h=ih*2,dnn_processing=dnn_backend=tensorflow:model=srcnn.pb:input=x:output=y -y srcnn.jpg 10202@end example 10203 10204@item 10205Handle the Y channel with espcn.pb (see @ref{sr} filter), which changes frame size, for format yuv420p (planar YUV formats supported): 10206@example 10207./ffmpeg -i 480p.jpg -vf format=yuv420p,dnn_processing=dnn_backend=tensorflow:model=espcn.pb:input=x:output=y -y tmp.espcn.jpg 10208@end example 10209 10210@end itemize 10211 10212@section drawbox 10213 10214Draw a colored box on the input image. 10215 10216It accepts the following parameters: 10217 10218@table @option 10219@item x 10220@item y 10221The expressions which specify the top left corner coordinates of the box. It defaults to 0. 10222 10223@item width, w 10224@item height, h 10225The expressions which specify the width and height of the box; if 0 they are interpreted as 10226the input width and height. It defaults to 0. 10227 10228@item color, c 10229Specify the color of the box to write. For the general syntax of this option, 10230check the @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}. If the special 10231value @code{invert} is used, the box edge color is the same as the 10232video with inverted luma. 10233 10234@item thickness, t 10235The expression which sets the thickness of the box edge. 10236A value of @code{fill} will create a filled box. Default value is @code{3}. 10237 10238See below for the list of accepted constants. 10239 10240@item replace 10241Applicable if the input has alpha. With value @code{1}, the pixels of the painted box 10242will overwrite the video's color and alpha pixels. 10243Default is @code{0}, which composites the box onto the input, leaving the video's alpha intact. 10244@end table 10245 10246The parameters for @var{x}, @var{y}, @var{w} and @var{h} and @var{t} are expressions containing the 10247following constants: 10248 10249@table @option 10250@item dar 10251The input display aspect ratio, it is the same as (@var{w} / @var{h}) * @var{sar}. 10252 10253@item hsub 10254@item vsub 10255horizontal and vertical chroma subsample values. For example for the 10256pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1. 10257 10258@item in_h, ih 10259@item in_w, iw 10260The input width and height. 10261 10262@item sar 10263The input sample aspect ratio. 10264 10265@item x 10266@item y 10267The x and y offset coordinates where the box is drawn. 10268 10269@item w 10270@item h 10271The width and height of the drawn box. 10272 10273@item t 10274The thickness of the drawn box. 10275 10276These constants allow the @var{x}, @var{y}, @var{w}, @var{h} and @var{t} expressions to refer to 10277each other, so you may for example specify @code{y=x/dar} or @code{h=w/dar}. 10278 10279@end table 10280 10281@subsection Examples 10282 10283@itemize 10284@item 10285Draw a black box around the edge of the input image: 10286@example 10287drawbox 10288@end example 10289 10290@item 10291Draw a box with color red and an opacity of 50%: 10292@example 10293drawbox=10:20:200:60:red@@0.5 10294@end example 10295 10296The previous example can be specified as: 10297@example 10298drawbox=x=10:y=20:w=200:h=60:color=red@@0.5 10299@end example 10300 10301@item 10302Fill the box with pink color: 10303@example 10304drawbox=x=10:y=10:w=100:h=100:color=pink@@0.5:t=fill 10305@end example 10306 10307@item 10308Draw a 2-pixel red 2.40:1 mask: 10309@example 10310drawbox=x=-t:y=0.5*(ih-iw/2.4)-t:w=iw+t*2:h=iw/2.4+t*2:t=2:c=red 10311@end example 10312@end itemize 10313 10314@subsection Commands 10315This filter supports same commands as options. 10316The command accepts the same syntax of the corresponding option. 10317 10318If the specified expression is not valid, it is kept at its current 10319value. 10320 10321@anchor{drawgraph} 10322@section drawgraph 10323Draw a graph using input video metadata. 10324 10325It accepts the following parameters: 10326 10327@table @option 10328@item m1 10329Set 1st frame metadata key from which metadata values will be used to draw a graph. 10330 10331@item fg1 10332Set 1st foreground color expression. 10333 10334@item m2 10335Set 2nd frame metadata key from which metadata values will be used to draw a graph. 10336 10337@item fg2 10338Set 2nd foreground color expression. 10339 10340@item m3 10341Set 3rd frame metadata key from which metadata values will be used to draw a graph. 10342 10343@item fg3 10344Set 3rd foreground color expression. 10345 10346@item m4 10347Set 4th frame metadata key from which metadata values will be used to draw a graph. 10348 10349@item fg4 10350Set 4th foreground color expression. 10351 10352@item min 10353Set minimal value of metadata value. 10354 10355@item max 10356Set maximal value of metadata value. 10357 10358@item bg 10359Set graph background color. Default is white. 10360 10361@item mode 10362Set graph mode. 10363 10364Available values for mode is: 10365@table @samp 10366@item bar 10367@item dot 10368@item line 10369@end table 10370 10371Default is @code{line}. 10372 10373@item slide 10374Set slide mode. 10375 10376Available values for slide is: 10377@table @samp 10378@item frame 10379Draw new frame when right border is reached. 10380 10381@item replace 10382Replace old columns with new ones. 10383 10384@item scroll 10385Scroll from right to left. 10386 10387@item rscroll 10388Scroll from left to right. 10389 10390@item picture 10391Draw single picture. 10392@end table 10393 10394Default is @code{frame}. 10395 10396@item size 10397Set size of graph video. For the syntax of this option, check the 10398@ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}. 10399The default value is @code{900x256}. 10400 10401@item rate, r 10402Set the output frame rate. Default value is @code{25}. 10403 10404The foreground color expressions can use the following variables: 10405@table @option 10406@item MIN 10407Minimal value of metadata value. 10408 10409@item MAX 10410Maximal value of metadata value. 10411 10412@item VAL 10413Current metadata key value. 10414@end table 10415 10416The color is defined as 0xAABBGGRR. 10417@end table 10418 10419Example using metadata from @ref{signalstats} filter: 10420@example 10421signalstats,drawgraph=lavfi.signalstats.YAVG:min=0:max=255 10422@end example 10423 10424Example using metadata from @ref{ebur128} filter: 10425@example 10426ebur128=metadata=1,adrawgraph=lavfi.r128.M:min=-120:max=5 10427@end example 10428 10429@section drawgrid 10430 10431Draw a grid on the input image. 10432 10433It accepts the following parameters: 10434 10435@table @option 10436@item x 10437@item y 10438The expressions which specify the coordinates of some point of grid intersection (meant to configure offset). Both default to 0. 10439 10440@item width, w 10441@item height, h 10442The expressions which specify the width and height of the grid cell, if 0 they are interpreted as the 10443input width and height, respectively, minus @code{thickness}, so image gets 10444framed. Default to 0. 10445 10446@item color, c 10447Specify the color of the grid. For the general syntax of this option, 10448check the @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}. If the special 10449value @code{invert} is used, the grid color is the same as the 10450video with inverted luma. 10451 10452@item thickness, t 10453The expression which sets the thickness of the grid line. Default value is @code{1}. 10454 10455See below for the list of accepted constants. 10456 10457@item replace 10458Applicable if the input has alpha. With @code{1} the pixels of the painted grid 10459will overwrite the video's color and alpha pixels. 10460Default is @code{0}, which composites the grid onto the input, leaving the video's alpha intact. 10461@end table 10462 10463The parameters for @var{x}, @var{y}, @var{w} and @var{h} and @var{t} are expressions containing the 10464following constants: 10465 10466@table @option 10467@item dar 10468The input display aspect ratio, it is the same as (@var{w} / @var{h}) * @var{sar}. 10469 10470@item hsub 10471@item vsub 10472horizontal and vertical chroma subsample values. For example for the 10473pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1. 10474 10475@item in_h, ih 10476@item in_w, iw 10477The input grid cell width and height. 10478 10479@item sar 10480The input sample aspect ratio. 10481 10482@item x 10483@item y 10484The x and y coordinates of some point of grid intersection (meant to configure offset). 10485 10486@item w 10487@item h 10488The width and height of the drawn cell. 10489 10490@item t 10491The thickness of the drawn cell. 10492 10493These constants allow the @var{x}, @var{y}, @var{w}, @var{h} and @var{t} expressions to refer to 10494each other, so you may for example specify @code{y=x/dar} or @code{h=w/dar}. 10495 10496@end table 10497 10498@subsection Examples 10499 10500@itemize 10501@item 10502Draw a grid with cell 100x100 pixels, thickness 2 pixels, with color red and an opacity of 50%: 10503@example 10504drawgrid=width=100:height=100:thickness=2:color=red@@0.5 10505@end example 10506 10507@item 10508Draw a white 3x3 grid with an opacity of 50%: 10509@example 10510drawgrid=w=iw/3:h=ih/3:t=2:c=white@@0.5 10511@end example 10512@end itemize 10513 10514@subsection Commands 10515This filter supports same commands as options. 10516The command accepts the same syntax of the corresponding option. 10517 10518If the specified expression is not valid, it is kept at its current 10519value. 10520 10521@anchor{drawtext} 10522@section drawtext 10523 10524Draw a text string or text from a specified file on top of a video, using the 10525libfreetype library. 10526 10527To enable compilation of this filter, you need to configure FFmpeg with 10528@code{--enable-libfreetype}. 10529To enable default font fallback and the @var{font} option you need to 10530configure FFmpeg with @code{--enable-libfontconfig}. 10531To enable the @var{text_shaping} option, you need to configure FFmpeg with 10532@code{--enable-libfribidi}. 10533 10534@subsection Syntax 10535 10536It accepts the following parameters: 10537 10538@table @option 10539 10540@item box 10541Used to draw a box around text using the background color. 10542The value must be either 1 (enable) or 0 (disable). 10543The default value of @var{box} is 0. 10544 10545@item boxborderw 10546Set the width of the border to be drawn around the box using @var{boxcolor}. 10547The default value of @var{boxborderw} is 0. 10548 10549@item boxcolor 10550The color to be used for drawing box around text. For the syntax of this 10551option, check the @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}. 10552 10553The default value of @var{boxcolor} is "white". 10554 10555@item line_spacing 10556Set the line spacing in pixels of the border to be drawn around the box using @var{box}. 10557The default value of @var{line_spacing} is 0. 10558 10559@item borderw 10560Set the width of the border to be drawn around the text using @var{bordercolor}. 10561The default value of @var{borderw} is 0. 10562 10563@item bordercolor 10564Set the color to be used for drawing border around text. For the syntax of this 10565option, check the @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}. 10566 10567The default value of @var{bordercolor} is "black". 10568 10569@item expansion 10570Select how the @var{text} is expanded. Can be either @code{none}, 10571@code{strftime} (deprecated) or 10572@code{normal} (default). See the @ref{drawtext_expansion, Text expansion} section 10573below for details. 10574 10575@item basetime 10576Set a start time for the count. Value is in microseconds. Only applied 10577in the deprecated strftime expansion mode. To emulate in normal expansion 10578mode use the @code{pts} function, supplying the start time (in seconds) 10579as the second argument. 10580 10581@item fix_bounds 10582If true, check and fix text coords to avoid clipping. 10583 10584@item fontcolor 10585The color to be used for drawing fonts. For the syntax of this option, check 10586the @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}. 10587 10588The default value of @var{fontcolor} is "black". 10589 10590@item fontcolor_expr 10591String which is expanded the same way as @var{text} to obtain dynamic 10592@var{fontcolor} value. By default this option has empty value and is not 10593processed. When this option is set, it overrides @var{fontcolor} option. 10594 10595@item font 10596The font family to be used for drawing text. By default Sans. 10597 10598@item fontfile 10599The font file to be used for drawing text. The path must be included. 10600This parameter is mandatory if the fontconfig support is disabled. 10601 10602@item alpha 10603Draw the text applying alpha blending. The value can 10604be a number between 0.0 and 1.0. 10605The expression accepts the same variables @var{x, y} as well. 10606The default value is 1. 10607Please see @var{fontcolor_expr}. 10608 10609@item fontsize 10610The font size to be used for drawing text. 10611The default value of @var{fontsize} is 16. 10612 10613@item text_shaping 10614If set to 1, attempt to shape the text (for example, reverse the order of 10615right-to-left text and join Arabic characters) before drawing it. 10616Otherwise, just draw the text exactly as given. 10617By default 1 (if supported). 10618 10619@item ft_load_flags 10620The flags to be used for loading the fonts. 10621 10622The flags map the corresponding flags supported by libfreetype, and are 10623a combination of the following values: 10624@table @var 10625@item default 10626@item no_scale 10627@item no_hinting 10628@item render 10629@item no_bitmap 10630@item vertical_layout 10631@item force_autohint 10632@item crop_bitmap 10633@item pedantic 10634@item ignore_global_advance_width 10635@item no_recurse 10636@item ignore_transform 10637@item monochrome 10638@item linear_design 10639@item no_autohint 10640@end table 10641 10642Default value is "default". 10643 10644For more information consult the documentation for the FT_LOAD_* 10645libfreetype flags. 10646 10647@item shadowcolor 10648The color to be used for drawing a shadow behind the drawn text. For the 10649syntax of this option, check the @ref{color syntax,,"Color" section in the 10650ffmpeg-utils manual,ffmpeg-utils}. 10651 10652The default value of @var{shadowcolor} is "black". 10653 10654@item shadowx 10655@item shadowy 10656The x and y offsets for the text shadow position with respect to the 10657position of the text. They can be either positive or negative 10658values. The default value for both is "0". 10659 10660@item start_number 10661The starting frame number for the n/frame_num variable. The default value 10662is "0". 10663 10664@item tabsize 10665The size in number of spaces to use for rendering the tab. 10666Default value is 4. 10667 10668@item timecode 10669Set the initial timecode representation in "hh:mm:ss[:;.]ff" 10670format. It can be used with or without text parameter. @var{timecode_rate} 10671option must be specified. 10672 10673@item timecode_rate, rate, r 10674Set the timecode frame rate (timecode only). Value will be rounded to nearest 10675integer. Minimum value is "1". 10676Drop-frame timecode is supported for frame rates 30 & 60. 10677 10678@item tc24hmax 10679If set to 1, the output of the timecode option will wrap around at 24 hours. 10680Default is 0 (disabled). 10681 10682@item text 10683The text string to be drawn. The text must be a sequence of UTF-8 10684encoded characters. 10685This parameter is mandatory if no file is specified with the parameter 10686@var{textfile}. 10687 10688@item textfile 10689A text file containing text to be drawn. The text must be a sequence 10690of UTF-8 encoded characters. 10691 10692This parameter is mandatory if no text string is specified with the 10693parameter @var{text}. 10694 10695If both @var{text} and @var{textfile} are specified, an error is thrown. 10696 10697@item reload 10698If set to 1, the @var{textfile} will be reloaded before each frame. 10699Be sure to update it atomically, or it may be read partially, or even fail. 10700 10701@item x 10702@item y 10703The expressions which specify the offsets where text will be drawn 10704within the video frame. They are relative to the top/left border of the 10705output image. 10706 10707The default value of @var{x} and @var{y} is "0". 10708 10709See below for the list of accepted constants and functions. 10710@end table 10711 10712The parameters for @var{x} and @var{y} are expressions containing the 10713following constants and functions: 10714 10715@table @option 10716@item dar 10717input display aspect ratio, it is the same as (@var{w} / @var{h}) * @var{sar} 10718 10719@item hsub 10720@item vsub 10721horizontal and vertical chroma subsample values. For example for the 10722pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1. 10723 10724@item line_h, lh 10725the height of each text line 10726 10727@item main_h, h, H 10728the input height 10729 10730@item main_w, w, W 10731the input width 10732 10733@item max_glyph_a, ascent 10734the maximum distance from the baseline to the highest/upper grid 10735coordinate used to place a glyph outline point, for all the rendered 10736glyphs. 10737It is a positive value, due to the grid's orientation with the Y axis 10738upwards. 10739 10740@item max_glyph_d, descent 10741the maximum distance from the baseline to the lowest grid coordinate 10742used to place a glyph outline point, for all the rendered glyphs. 10743This is a negative value, due to the grid's orientation, with the Y axis 10744upwards. 10745 10746@item max_glyph_h 10747maximum glyph height, that is the maximum height for all the glyphs 10748contained in the rendered text, it is equivalent to @var{ascent} - 10749@var{descent}. 10750 10751@item max_glyph_w 10752maximum glyph width, that is the maximum width for all the glyphs 10753contained in the rendered text 10754 10755@item n 10756the number of input frame, starting from 0 10757 10758@item rand(min, max) 10759return a random number included between @var{min} and @var{max} 10760 10761@item sar 10762The input sample aspect ratio. 10763 10764@item t 10765timestamp expressed in seconds, NAN if the input timestamp is unknown 10766 10767@item text_h, th 10768the height of the rendered text 10769 10770@item text_w, tw 10771the width of the rendered text 10772 10773@item x 10774@item y 10775the x and y offset coordinates where the text is drawn. 10776 10777These parameters allow the @var{x} and @var{y} expressions to refer 10778to each other, so you can for example specify @code{y=x/dar}. 10779 10780@item pict_type 10781A one character description of the current frame's picture type. 10782 10783@item pkt_pos 10784The current packet's position in the input file or stream 10785(in bytes, from the start of the input). A value of -1 indicates 10786this info is not available. 10787 10788@item pkt_duration 10789The current packet's duration, in seconds. 10790 10791@item pkt_size 10792The current packet's size (in bytes). 10793@end table 10794 10795@anchor{drawtext_expansion} 10796@subsection Text expansion 10797 10798If @option{expansion} is set to @code{strftime}, 10799the filter recognizes strftime() sequences in the provided text and 10800expands them accordingly. Check the documentation of strftime(). This 10801feature is deprecated. 10802 10803If @option{expansion} is set to @code{none}, the text is printed verbatim. 10804 10805If @option{expansion} is set to @code{normal} (which is the default), 10806the following expansion mechanism is used. 10807 10808The backslash character @samp{\}, followed by any character, always expands to 10809the second character. 10810 10811Sequences of the form @code{%@{...@}} are expanded. The text between the 10812braces is a function name, possibly followed by arguments separated by ':'. 10813If the arguments contain special characters or delimiters (':' or '@}'), 10814they should be escaped. 10815 10816Note that they probably must also be escaped as the value for the 10817@option{text} option in the filter argument string and as the filter 10818argument in the filtergraph description, and possibly also for the shell, 10819that makes up to four levels of escaping; using a text file avoids these 10820problems. 10821 10822The following functions are available: 10823 10824@table @command 10825 10826@item expr, e 10827The expression evaluation result. 10828 10829It must take one argument specifying the expression to be evaluated, 10830which accepts the same constants and functions as the @var{x} and 10831@var{y} values. Note that not all constants should be used, for 10832example the text size is not known when evaluating the expression, so 10833the constants @var{text_w} and @var{text_h} will have an undefined 10834value. 10835 10836@item expr_int_format, eif 10837Evaluate the expression's value and output as formatted integer. 10838 10839The first argument is the expression to be evaluated, just as for the @var{expr} function. 10840The second argument specifies the output format. Allowed values are @samp{x}, 10841@samp{X}, @samp{d} and @samp{u}. They are treated exactly as in the 10842@code{printf} function. 10843The third parameter is optional and sets the number of positions taken by the output. 10844It can be used to add padding with zeros from the left. 10845 10846@item gmtime 10847The time at which the filter is running, expressed in UTC. 10848It can accept an argument: a strftime() format string. 10849 10850@item localtime 10851The time at which the filter is running, expressed in the local time zone. 10852It can accept an argument: a strftime() format string. 10853 10854@item metadata 10855Frame metadata. Takes one or two arguments. 10856 10857The first argument is mandatory and specifies the metadata key. 10858 10859The second argument is optional and specifies a default value, used when the 10860metadata key is not found or empty. 10861 10862Available metadata can be identified by inspecting entries 10863starting with TAG included within each frame section 10864printed by running @code{ffprobe -show_frames}. 10865 10866String metadata generated in filters leading to 10867the drawtext filter are also available. 10868 10869@item n, frame_num 10870The frame number, starting from 0. 10871 10872@item pict_type 10873A one character description of the current picture type. 10874 10875@item pts 10876The timestamp of the current frame. 10877It can take up to three arguments. 10878 10879The first argument is the format of the timestamp; it defaults to @code{flt} 10880for seconds as a decimal number with microsecond accuracy; @code{hms} stands 10881for a formatted @var{[-]HH:MM:SS.mmm} timestamp with millisecond accuracy. 10882@code{gmtime} stands for the timestamp of the frame formatted as UTC time; 10883@code{localtime} stands for the timestamp of the frame formatted as 10884local time zone time. 10885 10886The second argument is an offset added to the timestamp. 10887 10888If the format is set to @code{hms}, a third argument @code{24HH} may be 10889supplied to present the hour part of the formatted timestamp in 24h format 10890(00-23). 10891 10892If the format is set to @code{localtime} or @code{gmtime}, 10893a third argument may be supplied: a strftime() format string. 10894By default, @var{YYYY-MM-DD HH:MM:SS} format will be used. 10895@end table 10896 10897@subsection Commands 10898 10899This filter supports altering parameters via commands: 10900@table @option 10901@item reinit 10902Alter existing filter parameters. 10903 10904Syntax for the argument is the same as for filter invocation, e.g. 10905 10906@example 10907fontsize=56:fontcolor=green:text='Hello World' 10908@end example 10909 10910Full filter invocation with sendcmd would look like this: 10911 10912@example 10913sendcmd=c='56.0 drawtext reinit fontsize=56\:fontcolor=green\:text=Hello\\ World' 10914@end example 10915@end table 10916 10917If the entire argument can't be parsed or applied as valid values then the filter will 10918continue with its existing parameters. 10919 10920@subsection Examples 10921 10922@itemize 10923@item 10924Draw "Test Text" with font FreeSerif, using the default values for the 10925optional parameters. 10926 10927@example 10928drawtext="fontfile=/usr/share/fonts/truetype/freefont/FreeSerif.ttf: text='Test Text'" 10929@end example 10930 10931@item 10932Draw 'Test Text' with font FreeSerif of size 24 at position x=100 10933and y=50 (counting from the top-left corner of the screen), text is 10934yellow with a red box around it. Both the text and the box have an 10935opacity of 20%. 10936 10937@example 10938drawtext="fontfile=/usr/share/fonts/truetype/freefont/FreeSerif.ttf: text='Test Text':\ 10939 x=100: y=50: fontsize=24: fontcolor=yellow@@0.2: box=1: boxcolor=red@@0.2" 10940@end example 10941 10942Note that the double quotes are not necessary if spaces are not used 10943within the parameter list. 10944 10945@item 10946Show the text at the center of the video frame: 10947@example 10948drawtext="fontsize=30:fontfile=FreeSerif.ttf:text='hello world':x=(w-text_w)/2:y=(h-text_h)/2" 10949@end example 10950 10951@item 10952Show the text at a random position, switching to a new position every 30 seconds: 10953@example 10954drawtext="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)" 10955@end example 10956 10957@item 10958Show a text line sliding from right to left in the last row of the video 10959frame. The file @file{LONG_LINE} is assumed to contain a single line 10960with no newlines. 10961@example 10962drawtext="fontsize=15:fontfile=FreeSerif.ttf:text=LONG_LINE:y=h-line_h:x=-50*t" 10963@end example 10964 10965@item 10966Show the content of file @file{CREDITS} off the bottom of the frame and scroll up. 10967@example 10968drawtext="fontsize=20:fontfile=FreeSerif.ttf:textfile=CREDITS:y=h-20*t" 10969@end example 10970 10971@item 10972Draw a single green letter "g", at the center of the input video. 10973The glyph baseline is placed at half screen height. 10974@example 10975drawtext="fontsize=60:fontfile=FreeSerif.ttf:fontcolor=green:text=g:x=(w-max_glyph_w)/2:y=h/2-ascent" 10976@end example 10977 10978@item 10979Show text for 1 second every 3 seconds: 10980@example 10981drawtext="fontfile=FreeSerif.ttf:fontcolor=white:x=100:y=x/dar:enable=lt(mod(t\,3)\,1):text='blink'" 10982@end example 10983 10984@item 10985Use fontconfig to set the font. Note that the colons need to be escaped. 10986@example 10987drawtext='fontfile=Linux Libertine O-40\:style=Semibold:text=FFmpeg' 10988@end example 10989 10990@item 10991Draw "Test Text" with font size dependent on height of the video. 10992@example 10993drawtext="text='Test Text': fontsize=h/30: x=(w-text_w)/2: y=(h-text_h*2)" 10994@end example 10995 10996@item 10997Print the date of a real-time encoding (see strftime(3)): 10998@example 10999drawtext='fontfile=FreeSans.ttf:text=%@{localtime\:%a %b %d %Y@}' 11000@end example 11001 11002@item 11003Show text fading in and out (appearing/disappearing): 11004@example 11005#!/bin/sh 11006DS=1.0 # display start 11007DE=10.0 # display end 11008FID=1.5 # fade in duration 11009FOD=5 # fade out duration 11010ffplay -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 @}" 11011@end example 11012 11013@item 11014Horizontally align multiple separate texts. Note that @option{max_glyph_a} 11015and the @option{fontsize} value are included in the @option{y} offset. 11016@example 11017drawtext=fontfile=FreeSans.ttf:text=DOG:fontsize=24:x=10:y=20+24-max_glyph_a, 11018drawtext=fontfile=FreeSans.ttf:text=cow:fontsize=24:x=80:y=20+24-max_glyph_a 11019@end example 11020 11021@item 11022Plot special @var{lavf.image2dec.source_basename} metadata onto each frame if 11023such metadata exists. Otherwise, plot the string "NA". Note that image2 demuxer 11024must have option @option{-export_path_metadata 1} for the special metadata fields 11025to be available for filters. 11026@example 11027drawtext="fontsize=20:fontcolor=white:fontfile=FreeSans.ttf:text='%@{metadata\:lavf.image2dec.source_basename\:NA@}':x=10:y=10" 11028@end example 11029 11030@end itemize 11031 11032For more information about libfreetype, check: 11033@url{http://www.freetype.org/}. 11034 11035For more information about fontconfig, check: 11036@url{http://freedesktop.org/software/fontconfig/fontconfig-user.html}. 11037 11038For more information about libfribidi, check: 11039@url{http://fribidi.org/}. 11040 11041@section edgedetect 11042 11043Detect and draw edges. The filter uses the Canny Edge Detection algorithm. 11044 11045The filter accepts the following options: 11046 11047@table @option 11048@item low 11049@item high 11050Set low and high threshold values used by the Canny thresholding 11051algorithm. 11052 11053The high threshold selects the "strong" edge pixels, which are then 11054connected through 8-connectivity with the "weak" edge pixels selected 11055by the low threshold. 11056 11057@var{low} and @var{high} threshold values must be chosen in the range 11058[0,1], and @var{low} should be lesser or equal to @var{high}. 11059 11060Default value for @var{low} is @code{20/255}, and default value for @var{high} 11061is @code{50/255}. 11062 11063@item mode 11064Define the drawing mode. 11065 11066@table @samp 11067@item wires 11068Draw white/gray wires on black background. 11069 11070@item colormix 11071Mix the colors to create a paint/cartoon effect. 11072 11073@item canny 11074Apply Canny edge detector on all selected planes. 11075@end table 11076Default value is @var{wires}. 11077 11078@item planes 11079Select planes for filtering. By default all available planes are filtered. 11080@end table 11081 11082@subsection Examples 11083 11084@itemize 11085@item 11086Standard edge detection with custom values for the hysteresis thresholding: 11087@example 11088edgedetect=low=0.1:high=0.4 11089@end example 11090 11091@item 11092Painting effect without thresholding: 11093@example 11094edgedetect=mode=colormix:high=0 11095@end example 11096@end itemize 11097 11098@section elbg 11099 11100Apply a posterize effect using the ELBG (Enhanced LBG) algorithm. 11101 11102For each input image, the filter will compute the optimal mapping from 11103the input to the output given the codebook length, that is the number 11104of distinct output colors. 11105 11106This filter accepts the following options. 11107 11108@table @option 11109@item codebook_length, l 11110Set codebook length. The value must be a positive integer, and 11111represents the number of distinct output colors. Default value is 256. 11112 11113@item nb_steps, n 11114Set the maximum number of iterations to apply for computing the optimal 11115mapping. The higher the value the better the result and the higher the 11116computation time. Default value is 1. 11117 11118@item seed, s 11119Set a random seed, must be an integer included between 0 and 11120UINT32_MAX. If not specified, or if explicitly set to -1, the filter 11121will try to use a good random seed on a best effort basis. 11122 11123@item pal8 11124Set pal8 output pixel format. This option does not work with codebook 11125length greater than 256. 11126@end table 11127 11128@section entropy 11129 11130Measure graylevel entropy in histogram of color channels of video frames. 11131 11132It accepts the following parameters: 11133 11134@table @option 11135@item mode 11136Can be either @var{normal} or @var{diff}. Default is @var{normal}. 11137 11138@var{diff} mode measures entropy of histogram delta values, absolute differences 11139between neighbour histogram values. 11140@end table 11141 11142@section epx 11143Apply the EPX magnification filter which is designed for pixel art. 11144 11145It accepts the following option: 11146 11147@table @option 11148@item n 11149Set the scaling dimension: @code{2} for @code{2xEPX}, @code{3} for 11150@code{3xEPX}. 11151Default is @code{3}. 11152@end table 11153 11154@section eq 11155Set brightness, contrast, saturation and approximate gamma adjustment. 11156 11157The filter accepts the following options: 11158 11159@table @option 11160@item contrast 11161Set the contrast expression. The value must be a float value in range 11162@code{-1000.0} to @code{1000.0}. The default value is "1". 11163 11164@item brightness 11165Set the brightness expression. The value must be a float value in 11166range @code{-1.0} to @code{1.0}. The default value is "0". 11167 11168@item saturation 11169Set the saturation expression. The value must be a float in 11170range @code{0.0} to @code{3.0}. The default value is "1". 11171 11172@item gamma 11173Set the gamma expression. The value must be a float in range 11174@code{0.1} to @code{10.0}. The default value is "1". 11175 11176@item gamma_r 11177Set the gamma expression for red. The value must be a float in 11178range @code{0.1} to @code{10.0}. The default value is "1". 11179 11180@item gamma_g 11181Set the gamma expression for green. The value must be a float in range 11182@code{0.1} to @code{10.0}. The default value is "1". 11183 11184@item gamma_b 11185Set the gamma expression for blue. The value must be a float in range 11186@code{0.1} to @code{10.0}. The default value is "1". 11187 11188@item gamma_weight 11189Set the gamma weight expression. It can be used to reduce the effect 11190of a high gamma value on bright image areas, e.g. keep them from 11191getting overamplified and just plain white. The value must be a float 11192in range @code{0.0} to @code{1.0}. A value of @code{0.0} turns the 11193gamma correction all the way down while @code{1.0} leaves it at its 11194full strength. Default is "1". 11195 11196@item eval 11197Set when the expressions for brightness, contrast, saturation and 11198gamma expressions are evaluated. 11199 11200It accepts the following values: 11201@table @samp 11202@item init 11203only evaluate expressions once during the filter initialization or 11204when a command is processed 11205 11206@item frame 11207evaluate expressions for each incoming frame 11208@end table 11209 11210Default value is @samp{init}. 11211@end table 11212 11213The expressions accept the following parameters: 11214@table @option 11215@item n 11216frame count of the input frame starting from 0 11217 11218@item pos 11219byte position of the corresponding packet in the input file, NAN if 11220unspecified 11221 11222@item r 11223frame rate of the input video, NAN if the input frame rate is unknown 11224 11225@item t 11226timestamp expressed in seconds, NAN if the input timestamp is unknown 11227@end table 11228 11229@subsection Commands 11230The filter supports the following commands: 11231 11232@table @option 11233@item contrast 11234Set the contrast expression. 11235 11236@item brightness 11237Set the brightness expression. 11238 11239@item saturation 11240Set the saturation expression. 11241 11242@item gamma 11243Set the gamma expression. 11244 11245@item gamma_r 11246Set the gamma_r expression. 11247 11248@item gamma_g 11249Set gamma_g expression. 11250 11251@item gamma_b 11252Set gamma_b expression. 11253 11254@item gamma_weight 11255Set gamma_weight expression. 11256 11257The command accepts the same syntax of the corresponding option. 11258 11259If the specified expression is not valid, it is kept at its current 11260value. 11261 11262@end table 11263 11264@section erosion 11265 11266Apply erosion effect to the video. 11267 11268This filter replaces the pixel by the local(3x3) minimum. 11269 11270It accepts the following options: 11271 11272@table @option 11273@item threshold0 11274@item threshold1 11275@item threshold2 11276@item threshold3 11277Limit the maximum change for each plane, default is 65535. 11278If 0, plane will remain unchanged. 11279 11280@item coordinates 11281Flag which specifies the pixel to refer to. Default is 255 i.e. all eight 11282pixels are used. 11283 11284Flags to local 3x3 coordinates maps like this: 11285 11286 1 2 3 11287 4 5 11288 6 7 8 11289@end table 11290 11291@subsection Commands 11292 11293This filter supports the all above options as @ref{commands}. 11294 11295@section estdif 11296 11297Deinterlace the input video ("estdif" stands for "Edge Slope 11298Tracing Deinterlacing Filter"). 11299 11300Spatial only filter that uses edge slope tracing algorithm 11301to interpolate missing lines. 11302It accepts the following parameters: 11303 11304@table @option 11305@item mode 11306The interlacing mode to adopt. It accepts one of the following values: 11307 11308@table @option 11309@item frame 11310Output one frame for each frame. 11311@item field 11312Output one frame for each field. 11313@end table 11314 11315The default value is @code{field}. 11316 11317@item parity 11318The picture field parity assumed for the input interlaced video. It accepts one 11319of the following values: 11320 11321@table @option 11322@item tff 11323Assume the top field is first. 11324@item bff 11325Assume the bottom field is first. 11326@item auto 11327Enable automatic detection of field parity. 11328@end table 11329 11330The default value is @code{auto}. 11331If the interlacing is unknown or the decoder does not export this information, 11332top field first will be assumed. 11333 11334@item deint 11335Specify which frames to deinterlace. Accepts one of the following 11336values: 11337 11338@table @option 11339@item all 11340Deinterlace all frames. 11341@item interlaced 11342Only deinterlace frames marked as interlaced. 11343@end table 11344 11345The default value is @code{all}. 11346 11347@item rslope 11348Specify the search radius for edge slope tracing. Default value is 1. 11349Allowed range is from 1 to 15. 11350 11351@item redge 11352Specify the search radius for best edge matching. Default value is 2. 11353Allowed range is from 0 to 15. 11354 11355@item interp 11356Specify the interpolation used. Default is 4-point interpolation. It accepts one 11357of the following values: 11358 11359@table @option 11360@item 2p 11361Two-point interpolation. 11362@item 4p 11363Four-point interpolation. 11364@item 6p 11365Six-point interpolation. 11366@end table 11367@end table 11368 11369@subsection Commands 11370This filter supports same @ref{commands} as options. 11371 11372@section exposure 11373Adjust exposure of the video stream. 11374 11375The filter accepts the following options: 11376 11377@table @option 11378@item exposure 11379Set the exposure correction in EV. Allowed range is from -3.0 to 3.0 EV 11380Default value is 0 EV. 11381 11382@item black 11383Set the black level correction. Allowed range is from -1.0 to 1.0. 11384Default value is 0. 11385@end table 11386 11387@subsection Commands 11388 11389This filter supports same @ref{commands} as options. 11390 11391@section extractplanes 11392 11393Extract color channel components from input video stream into 11394separate grayscale video streams. 11395 11396The filter accepts the following option: 11397 11398@table @option 11399@item planes 11400Set plane(s) to extract. 11401 11402Available values for planes are: 11403@table @samp 11404@item y 11405@item u 11406@item v 11407@item a 11408@item r 11409@item g 11410@item b 11411@end table 11412 11413Choosing planes not available in the input will result in an error. 11414That means you cannot select @code{r}, @code{g}, @code{b} planes 11415with @code{y}, @code{u}, @code{v} planes at same time. 11416@end table 11417 11418@subsection Examples 11419 11420@itemize 11421@item 11422Extract luma, u and v color channel component from input video frame 11423into 3 grayscale outputs: 11424@example 11425ffmpeg -i video.avi -filter_complex 'extractplanes=y+u+v[y][u][v]' -map '[y]' y.avi -map '[u]' u.avi -map '[v]' v.avi 11426@end example 11427@end itemize 11428 11429@section fade 11430 11431Apply a fade-in/out effect to the input video. 11432 11433It accepts the following parameters: 11434 11435@table @option 11436@item type, t 11437The effect type can be either "in" for a fade-in, or "out" for a fade-out 11438effect. 11439Default is @code{in}. 11440 11441@item start_frame, s 11442Specify the number of the frame to start applying the fade 11443effect at. Default is 0. 11444 11445@item nb_frames, n 11446The number of frames that the fade effect lasts. At the end of the 11447fade-in effect, the output video will have the same intensity as the input video. 11448At the end of the fade-out transition, the output video will be filled with the 11449selected @option{color}. 11450Default is 25. 11451 11452@item alpha 11453If set to 1, fade only alpha channel, if one exists on the input. 11454Default value is 0. 11455 11456@item start_time, st 11457Specify the timestamp (in seconds) of the frame to start to apply the fade 11458effect. If both start_frame and start_time are specified, the fade will start at 11459whichever comes last. Default is 0. 11460 11461@item duration, d 11462The number of seconds for which the fade effect has to last. At the end of the 11463fade-in effect the output video will have the same intensity as the input video, 11464at the end of the fade-out transition the output video will be filled with the 11465selected @option{color}. 11466If both duration and nb_frames are specified, duration is used. Default is 0 11467(nb_frames is used by default). 11468 11469@item color, c 11470Specify the color of the fade. Default is "black". 11471@end table 11472 11473@subsection Examples 11474 11475@itemize 11476@item 11477Fade in the first 30 frames of video: 11478@example 11479fade=in:0:30 11480@end example 11481 11482The command above is equivalent to: 11483@example 11484fade=t=in:s=0:n=30 11485@end example 11486 11487@item 11488Fade out the last 45 frames of a 200-frame video: 11489@example 11490fade=out:155:45 11491fade=type=out:start_frame=155:nb_frames=45 11492@end example 11493 11494@item 11495Fade in the first 25 frames and fade out the last 25 frames of a 1000-frame video: 11496@example 11497fade=in:0:25, fade=out:975:25 11498@end example 11499 11500@item 11501Make the first 5 frames yellow, then fade in from frame 5-24: 11502@example 11503fade=in:5:20:color=yellow 11504@end example 11505 11506@item 11507Fade in alpha over first 25 frames of video: 11508@example 11509fade=in:0:25:alpha=1 11510@end example 11511 11512@item 11513Make the first 5.5 seconds black, then fade in for 0.5 seconds: 11514@example 11515fade=t=in:st=5.5:d=0.5 11516@end example 11517 11518@end itemize 11519 11520@section fftdnoiz 11521Denoise frames using 3D FFT (frequency domain filtering). 11522 11523The filter accepts the following options: 11524 11525@table @option 11526@item sigma 11527Set the noise sigma constant. This sets denoising strength. 11528Default value is 1. Allowed range is from 0 to 30. 11529Using very high sigma with low overlap may give blocking artifacts. 11530 11531@item amount 11532Set amount of denoising. By default all detected noise is reduced. 11533Default value is 1. Allowed range is from 0 to 1. 11534 11535@item block 11536Set size of block, Default is 4, can be 3, 4, 5 or 6. 11537Actual size of block in pixels is 2 to power of @var{block}, so by default 11538block size in pixels is 2^4 which is 16. 11539 11540@item overlap 11541Set block overlap. Default is 0.5. Allowed range is from 0.2 to 0.8. 11542 11543@item prev 11544Set number of previous frames to use for denoising. By default is set to 0. 11545 11546@item next 11547Set number of next frames to to use for denoising. By default is set to 0. 11548 11549@item planes 11550Set planes which will be filtered, by default are all available filtered 11551except alpha. 11552@end table 11553 11554@section fftfilt 11555Apply arbitrary expressions to samples in frequency domain 11556 11557@table @option 11558@item dc_Y 11559Adjust the dc value (gain) of the luma plane of the image. The filter 11560accepts an integer value in range @code{0} to @code{1000}. The default 11561value is set to @code{0}. 11562 11563@item dc_U 11564Adjust the dc value (gain) of the 1st chroma plane of the image. The 11565filter accepts an integer value in range @code{0} to @code{1000}. The 11566default value is set to @code{0}. 11567 11568@item dc_V 11569Adjust the dc value (gain) of the 2nd chroma plane of the image. The 11570filter accepts an integer value in range @code{0} to @code{1000}. The 11571default value is set to @code{0}. 11572 11573@item weight_Y 11574Set the frequency domain weight expression for the luma plane. 11575 11576@item weight_U 11577Set the frequency domain weight expression for the 1st chroma plane. 11578 11579@item weight_V 11580Set the frequency domain weight expression for the 2nd chroma plane. 11581 11582@item eval 11583Set when the expressions are evaluated. 11584 11585It accepts the following values: 11586@table @samp 11587@item init 11588Only evaluate expressions once during the filter initialization. 11589 11590@item frame 11591Evaluate expressions for each incoming frame. 11592@end table 11593 11594Default value is @samp{init}. 11595 11596The filter accepts the following variables: 11597@item X 11598@item Y 11599The coordinates of the current sample. 11600 11601@item W 11602@item H 11603The width and height of the image. 11604 11605@item N 11606The number of input frame, starting from 0. 11607@end table 11608 11609@subsection Examples 11610 11611@itemize 11612@item 11613High-pass: 11614@example 11615fftfilt=dc_Y=128:weight_Y='squish(1-(Y+X)/100)' 11616@end example 11617 11618@item 11619Low-pass: 11620@example 11621fftfilt=dc_Y=0:weight_Y='squish((Y+X)/100-1)' 11622@end example 11623 11624@item 11625Sharpen: 11626@example 11627fftfilt=dc_Y=0:weight_Y='1+squish(1-(Y+X)/100)' 11628@end example 11629 11630@item 11631Blur: 11632@example 11633fftfilt=dc_Y=0:weight_Y='exp(-4 * ((Y+X)/(W+H)))' 11634@end example 11635 11636@end itemize 11637 11638@section field 11639 11640Extract a single field from an interlaced image using stride 11641arithmetic to avoid wasting CPU time. The output frames are marked as 11642non-interlaced. 11643 11644The filter accepts the following options: 11645 11646@table @option 11647@item type 11648Specify whether to extract the top (if the value is @code{0} or 11649@code{top}) or the bottom field (if the value is @code{1} or 11650@code{bottom}). 11651@end table 11652 11653@section fieldhint 11654 11655Create new frames by copying the top and bottom fields from surrounding frames 11656supplied as numbers by the hint file. 11657 11658@table @option 11659@item hint 11660Set file containing hints: absolute/relative frame numbers. 11661 11662There must be one line for each frame in a clip. Each line must contain two 11663numbers separated by the comma, optionally followed by @code{-} or @code{+}. 11664Numbers supplied on each line of file can not be out of [N-1,N+1] where N 11665is current frame number for @code{absolute} mode or out of [-1, 1] range 11666for @code{relative} mode. First number tells from which frame to pick up top 11667field and second number tells from which frame to pick up bottom field. 11668 11669If optionally followed by @code{+} output frame will be marked as interlaced, 11670else if followed by @code{-} output frame will be marked as progressive, else 11671it will be marked same as input frame. 11672If optionally followed by @code{t} output frame will use only top field, or in 11673case of @code{b} it will use only bottom field. 11674If line starts with @code{#} or @code{;} that line is skipped. 11675 11676@item mode 11677Can be item @code{absolute} or @code{relative}. Default is @code{absolute}. 11678@end table 11679 11680Example of first several lines of @code{hint} file for @code{relative} mode: 11681@example 116820,0 - # first frame 116831,0 - # second frame, use third's frame top field and second's frame bottom field 116841,0 - # third frame, use fourth's frame top field and third's frame bottom field 116851,0 - 116860,0 - 116870,0 - 116881,0 - 116891,0 - 116901,0 - 116910,0 - 116920,0 - 116931,0 - 116941,0 - 116951,0 - 116960,0 - 11697@end example 11698 11699@section fieldmatch 11700 11701Field matching filter for inverse telecine. It is meant to reconstruct the 11702progressive frames from a telecined stream. The filter does not drop duplicated 11703frames, so to achieve a complete inverse telecine @code{fieldmatch} needs to be 11704followed by a decimation filter such as @ref{decimate} in the filtergraph. 11705 11706The separation of the field matching and the decimation is notably motivated by 11707the possibility of inserting a de-interlacing filter fallback between the two. 11708If the source has mixed telecined and real interlaced content, 11709@code{fieldmatch} will not be able to match fields for the interlaced parts. 11710But these remaining combed frames will be marked as interlaced, and thus can be 11711de-interlaced by a later filter such as @ref{yadif} before decimation. 11712 11713In addition to the various configuration options, @code{fieldmatch} can take an 11714optional second stream, activated through the @option{ppsrc} option. If 11715enabled, the frames reconstruction will be based on the fields and frames from 11716this second stream. This allows the first input to be pre-processed in order to 11717help the various algorithms of the filter, while keeping the output lossless 11718(assuming the fields are matched properly). Typically, a field-aware denoiser, 11719or brightness/contrast adjustments can help. 11720 11721Note that this filter uses the same algorithms as TIVTC/TFM (AviSynth project) 11722and VIVTC/VFM (VapourSynth project). The later is a light clone of TFM from 11723which @code{fieldmatch} is based on. While the semantic and usage are very 11724close, some behaviour and options names can differ. 11725 11726The @ref{decimate} filter currently only works for constant frame rate input. 11727If your input has mixed telecined (30fps) and progressive content with a lower 11728framerate like 24fps use the following filterchain to produce the necessary cfr 11729stream: @code{dejudder,fps=30000/1001,fieldmatch,decimate}. 11730 11731The filter accepts the following options: 11732 11733@table @option 11734@item order 11735Specify the assumed field order of the input stream. Available values are: 11736 11737@table @samp 11738@item auto 11739Auto detect parity (use FFmpeg's internal parity value). 11740@item bff 11741Assume bottom field first. 11742@item tff 11743Assume top field first. 11744@end table 11745 11746Note that it is sometimes recommended not to trust the parity announced by the 11747stream. 11748 11749Default value is @var{auto}. 11750 11751@item mode 11752Set the matching mode or strategy to use. @option{pc} mode is the safest in the 11753sense that it won't risk creating jerkiness due to duplicate frames when 11754possible, but if there are bad edits or blended fields it will end up 11755outputting combed frames when a good match might actually exist. On the other 11756hand, @option{pcn_ub} mode is the most risky in terms of creating jerkiness, 11757but will almost always find a good frame if there is one. The other values are 11758all somewhere in between @option{pc} and @option{pcn_ub} in terms of risking 11759jerkiness and creating duplicate frames versus finding good matches in sections 11760with bad edits, orphaned fields, blended fields, etc. 11761 11762More details about p/c/n/u/b are available in @ref{p/c/n/u/b meaning} section. 11763 11764Available values are: 11765 11766@table @samp 11767@item pc 117682-way matching (p/c) 11769@item pc_n 117702-way matching, and trying 3rd match if still combed (p/c + n) 11771@item pc_u 117722-way matching, and trying 3rd match (same order) if still combed (p/c + u) 11773@item pc_n_ub 117742-way matching, trying 3rd match if still combed, and trying 4th/5th matches if 11775still combed (p/c + n + u/b) 11776@item pcn 117773-way matching (p/c/n) 11778@item pcn_ub 117793-way matching, and trying 4th/5th matches if all 3 of the original matches are 11780detected as combed (p/c/n + u/b) 11781@end table 11782 11783The parenthesis at the end indicate the matches that would be used for that 11784mode assuming @option{order}=@var{tff} (and @option{field} on @var{auto} or 11785@var{top}). 11786 11787In terms of speed @option{pc} mode is by far the fastest and @option{pcn_ub} is 11788the slowest. 11789 11790Default value is @var{pc_n}. 11791 11792@item ppsrc 11793Mark the main input stream as a pre-processed input, and enable the secondary 11794input stream as the clean source to pick the fields from. See the filter 11795introduction for more details. It is similar to the @option{clip2} feature from 11796VFM/TFM. 11797 11798Default value is @code{0} (disabled). 11799 11800@item field 11801Set the field to match from. It is recommended to set this to the same value as 11802@option{order} unless you experience matching failures with that setting. In 11803certain circumstances changing the field that is used to match from can have a 11804large impact on matching performance. Available values are: 11805 11806@table @samp 11807@item auto 11808Automatic (same value as @option{order}). 11809@item bottom 11810Match from the bottom field. 11811@item top 11812Match from the top field. 11813@end table 11814 11815Default value is @var{auto}. 11816 11817@item mchroma 11818Set whether or not chroma is included during the match comparisons. In most 11819cases it is recommended to leave this enabled. You should set this to @code{0} 11820only if your clip has bad chroma problems such as heavy rainbowing or other 11821artifacts. Setting this to @code{0} could also be used to speed things up at 11822the cost of some accuracy. 11823 11824Default value is @code{1}. 11825 11826@item y0 11827@item y1 11828These define an exclusion band which excludes the lines between @option{y0} and 11829@option{y1} from being included in the field matching decision. An exclusion 11830band can be used to ignore subtitles, a logo, or other things that may 11831interfere with the matching. @option{y0} sets the starting scan line and 11832@option{y1} sets the ending line; all lines in between @option{y0} and 11833@option{y1} (including @option{y0} and @option{y1}) will be ignored. Setting 11834@option{y0} and @option{y1} to the same value will disable the feature. 11835@option{y0} and @option{y1} defaults to @code{0}. 11836 11837@item scthresh 11838Set the scene change detection threshold as a percentage of maximum change on 11839the luma plane. Good values are in the @code{[8.0, 14.0]} range. Scene change 11840detection is only relevant in case @option{combmatch}=@var{sc}. The range for 11841@option{scthresh} is @code{[0.0, 100.0]}. 11842 11843Default value is @code{12.0}. 11844 11845@item combmatch 11846When @option{combatch} is not @var{none}, @code{fieldmatch} will take into 11847account the combed scores of matches when deciding what match to use as the 11848final match. Available values are: 11849 11850@table @samp 11851@item none 11852No final matching based on combed scores. 11853@item sc 11854Combed scores are only used when a scene change is detected. 11855@item full 11856Use combed scores all the time. 11857@end table 11858 11859Default is @var{sc}. 11860 11861@item combdbg 11862Force @code{fieldmatch} to calculate the combed metrics for certain matches and 11863print them. This setting is known as @option{micout} in TFM/VFM vocabulary. 11864Available values are: 11865 11866@table @samp 11867@item none 11868No forced calculation. 11869@item pcn 11870Force p/c/n calculations. 11871@item pcnub 11872Force p/c/n/u/b calculations. 11873@end table 11874 11875Default value is @var{none}. 11876 11877@item cthresh 11878This is the area combing threshold used for combed frame detection. This 11879essentially controls how "strong" or "visible" combing must be to be detected. 11880Larger values mean combing must be more visible and smaller values mean combing 11881can be less visible or strong and still be detected. Valid settings are from 11882@code{-1} (every pixel will be detected as combed) to @code{255} (no pixel will 11883be detected as combed). This is basically a pixel difference value. A good 11884range is @code{[8, 12]}. 11885 11886Default value is @code{9}. 11887 11888@item chroma 11889Sets whether or not chroma is considered in the combed frame decision. Only 11890disable this if your source has chroma problems (rainbowing, etc.) that are 11891causing problems for the combed frame detection with chroma enabled. Actually, 11892using @option{chroma}=@var{0} is usually more reliable, except for the case 11893where there is chroma only combing in the source. 11894 11895Default value is @code{0}. 11896 11897@item blockx 11898@item blocky 11899Respectively set the x-axis and y-axis size of the window used during combed 11900frame detection. This has to do with the size of the area in which 11901@option{combpel} pixels are required to be detected as combed for a frame to be 11902declared combed. See the @option{combpel} parameter description for more info. 11903Possible values are any number that is a power of 2 starting at 4 and going up 11904to 512. 11905 11906Default value is @code{16}. 11907 11908@item combpel 11909The number of combed pixels inside any of the @option{blocky} by 11910@option{blockx} size blocks on the frame for the frame to be detected as 11911combed. While @option{cthresh} controls how "visible" the combing must be, this 11912setting controls "how much" combing there must be in any localized area (a 11913window defined by the @option{blockx} and @option{blocky} settings) on the 11914frame. Minimum value is @code{0} and maximum is @code{blocky x blockx} (at 11915which point no frames will ever be detected as combed). This setting is known 11916as @option{MI} in TFM/VFM vocabulary. 11917 11918Default value is @code{80}. 11919@end table 11920 11921@anchor{p/c/n/u/b meaning} 11922@subsection p/c/n/u/b meaning 11923 11924@subsubsection p/c/n 11925 11926We assume the following telecined stream: 11927 11928@example 11929Top fields: 1 2 2 3 4 11930Bottom fields: 1 2 3 4 4 11931@end example 11932 11933The numbers correspond to the progressive frame the fields relate to. Here, the 11934first two frames are progressive, the 3rd and 4th are combed, and so on. 11935 11936When @code{fieldmatch} is configured to run a matching from bottom 11937(@option{field}=@var{bottom}) this is how this input stream get transformed: 11938 11939@example 11940Input stream: 11941 T 1 2 2 3 4 11942 B 1 2 3 4 4 <-- matching reference 11943 11944Matches: c c n n c 11945 11946Output stream: 11947 T 1 2 3 4 4 11948 B 1 2 3 4 4 11949@end example 11950 11951As a result of the field matching, we can see that some frames get duplicated. 11952To perform a complete inverse telecine, you need to rely on a decimation filter 11953after this operation. See for instance the @ref{decimate} filter. 11954 11955The same operation now matching from top fields (@option{field}=@var{top}) 11956looks like this: 11957 11958@example 11959Input stream: 11960 T 1 2 2 3 4 <-- matching reference 11961 B 1 2 3 4 4 11962 11963Matches: c c p p c 11964 11965Output stream: 11966 T 1 2 2 3 4 11967 B 1 2 2 3 4 11968@end example 11969 11970In these examples, we can see what @var{p}, @var{c} and @var{n} mean; 11971basically, they refer to the frame and field of the opposite parity: 11972 11973@itemize 11974@item @var{p} matches the field of the opposite parity in the previous frame 11975@item @var{c} matches the field of the opposite parity in the current frame 11976@item @var{n} matches the field of the opposite parity in the next frame 11977@end itemize 11978 11979@subsubsection u/b 11980 11981The @var{u} and @var{b} matching are a bit special in the sense that they match 11982from the opposite parity flag. In the following examples, we assume that we are 11983currently matching the 2nd frame (Top:2, bottom:2). According to the match, a 11984'x' is placed above and below each matched fields. 11985 11986With bottom matching (@option{field}=@var{bottom}): 11987@example 11988Match: c p n b u 11989 11990 x x x x x 11991 Top 1 2 2 1 2 2 1 2 2 1 2 2 1 2 2 11992 Bottom 1 2 3 1 2 3 1 2 3 1 2 3 1 2 3 11993 x x x x x 11994 11995Output frames: 11996 2 1 2 2 2 11997 2 2 2 1 3 11998@end example 11999 12000With top matching (@option{field}=@var{top}): 12001@example 12002Match: c p n b u 12003 12004 x x x x x 12005 Top 1 2 2 1 2 2 1 2 2 1 2 2 1 2 2 12006 Bottom 1 2 3 1 2 3 1 2 3 1 2 3 1 2 3 12007 x x x x x 12008 12009Output frames: 12010 2 2 2 1 2 12011 2 1 3 2 2 12012@end example 12013 12014@subsection Examples 12015 12016Simple IVTC of a top field first telecined stream: 12017@example 12018fieldmatch=order=tff:combmatch=none, decimate 12019@end example 12020 12021Advanced IVTC, with fallback on @ref{yadif} for still combed frames: 12022@example 12023fieldmatch=order=tff:combmatch=full, yadif=deint=interlaced, decimate 12024@end example 12025 12026@section fieldorder 12027 12028Transform the field order of the input video. 12029 12030It accepts the following parameters: 12031 12032@table @option 12033 12034@item order 12035The output field order. Valid values are @var{tff} for top field first or @var{bff} 12036for bottom field first. 12037@end table 12038 12039The default value is @samp{tff}. 12040 12041The transformation is done by shifting the picture content up or down 12042by one line, and filling the remaining line with appropriate picture content. 12043This method is consistent with most broadcast field order converters. 12044 12045If the input video is not flagged as being interlaced, or it is already 12046flagged as being of the required output field order, then this filter does 12047not alter the incoming video. 12048 12049It is very useful when converting to or from PAL DV material, 12050which is bottom field first. 12051 12052For example: 12053@example 12054ffmpeg -i in.vob -vf "fieldorder=bff" out.dv 12055@end example 12056 12057@section fifo, afifo 12058 12059Buffer input images and send them when they are requested. 12060 12061It is mainly useful when auto-inserted by the libavfilter 12062framework. 12063 12064It does not take parameters. 12065 12066@section fillborders 12067 12068Fill borders of the input video, without changing video stream dimensions. 12069Sometimes video can have garbage at the four edges and you may not want to 12070crop video input to keep size multiple of some number. 12071 12072This filter accepts the following options: 12073 12074@table @option 12075@item left 12076Number of pixels to fill from left border. 12077 12078@item right 12079Number of pixels to fill from right border. 12080 12081@item top 12082Number of pixels to fill from top border. 12083 12084@item bottom 12085Number of pixels to fill from bottom border. 12086 12087@item mode 12088Set fill mode. 12089 12090It accepts the following values: 12091@table @samp 12092@item smear 12093fill pixels using outermost pixels 12094 12095@item mirror 12096fill pixels using mirroring (half sample symmetric) 12097 12098@item fixed 12099fill pixels with constant value 12100 12101@item reflect 12102fill pixels using reflecting (whole sample symmetric) 12103 12104@item wrap 12105fill pixels using wrapping 12106 12107@item fade 12108fade pixels to constant value 12109@end table 12110 12111Default is @var{smear}. 12112 12113@item color 12114Set color for pixels in fixed or fade mode. Default is @var{black}. 12115@end table 12116 12117@subsection Commands 12118This filter supports same @ref{commands} as options. 12119The command accepts the same syntax of the corresponding option. 12120 12121If the specified expression is not valid, it is kept at its current 12122value. 12123 12124@section find_rect 12125 12126Find a rectangular object 12127 12128It accepts the following options: 12129 12130@table @option 12131@item object 12132Filepath of the object image, needs to be in gray8. 12133 12134@item threshold 12135Detection threshold, default is 0.5. 12136 12137@item mipmaps 12138Number of mipmaps, default is 3. 12139 12140@item xmin, ymin, xmax, ymax 12141Specifies the rectangle in which to search. 12142@end table 12143 12144@subsection Examples 12145 12146@itemize 12147@item 12148Cover a rectangular object by the supplied image of a given video using @command{ffmpeg}: 12149@example 12150ffmpeg -i file.ts -vf find_rect=newref.pgm,cover_rect=cover.jpg:mode=cover new.mkv 12151@end example 12152@end itemize 12153 12154@section floodfill 12155 12156Flood area with values of same pixel components with another values. 12157 12158It accepts the following options: 12159@table @option 12160@item x 12161Set pixel x coordinate. 12162 12163@item y 12164Set pixel y coordinate. 12165 12166@item s0 12167Set source #0 component value. 12168 12169@item s1 12170Set source #1 component value. 12171 12172@item s2 12173Set source #2 component value. 12174 12175@item s3 12176Set source #3 component value. 12177 12178@item d0 12179Set destination #0 component value. 12180 12181@item d1 12182Set destination #1 component value. 12183 12184@item d2 12185Set destination #2 component value. 12186 12187@item d3 12188Set destination #3 component value. 12189@end table 12190 12191@anchor{format} 12192@section format 12193 12194Convert the input video to one of the specified pixel formats. 12195Libavfilter will try to pick one that is suitable as input to 12196the next filter. 12197 12198It accepts the following parameters: 12199@table @option 12200 12201@item pix_fmts 12202A '|'-separated list of pixel format names, such as 12203"pix_fmts=yuv420p|monow|rgb24". 12204 12205@end table 12206 12207@subsection Examples 12208 12209@itemize 12210@item 12211Convert the input video to the @var{yuv420p} format 12212@example 12213format=pix_fmts=yuv420p 12214@end example 12215 12216Convert the input video to any of the formats in the list 12217@example 12218format=pix_fmts=yuv420p|yuv444p|yuv410p 12219@end example 12220@end itemize 12221 12222@anchor{fps} 12223@section fps 12224 12225Convert the video to specified constant frame rate by duplicating or dropping 12226frames as necessary. 12227 12228It accepts the following parameters: 12229@table @option 12230 12231@item fps 12232The desired output frame rate. The default is @code{25}. 12233 12234@item start_time 12235Assume the first PTS should be the given value, in seconds. This allows for 12236padding/trimming at the start of stream. By default, no assumption is made 12237about the first frame's expected PTS, so no padding or trimming is done. 12238For example, this could be set to 0 to pad the beginning with duplicates of 12239the first frame if a video stream starts after the audio stream or to trim any 12240frames with a negative PTS. 12241 12242@item round 12243Timestamp (PTS) rounding method. 12244 12245Possible values are: 12246@table @option 12247@item zero 12248round towards 0 12249@item inf 12250round away from 0 12251@item down 12252round towards -infinity 12253@item up 12254round towards +infinity 12255@item near 12256round to nearest 12257@end table 12258The default is @code{near}. 12259 12260@item eof_action 12261Action performed when reading the last frame. 12262 12263Possible values are: 12264@table @option 12265@item round 12266Use same timestamp rounding method as used for other frames. 12267@item pass 12268Pass through last frame if input duration has not been reached yet. 12269@end table 12270The default is @code{round}. 12271 12272@end table 12273 12274Alternatively, the options can be specified as a flat string: 12275@var{fps}[:@var{start_time}[:@var{round}]]. 12276 12277See also the @ref{setpts} filter. 12278 12279@subsection Examples 12280 12281@itemize 12282@item 12283A typical usage in order to set the fps to 25: 12284@example 12285fps=fps=25 12286@end example 12287 12288@item 12289Sets the fps to 24, using abbreviation and rounding method to round to nearest: 12290@example 12291fps=fps=film:round=near 12292@end example 12293@end itemize 12294 12295@section framepack 12296 12297Pack two different video streams into a stereoscopic video, setting proper 12298metadata on supported codecs. The two views should have the same size and 12299framerate and processing will stop when the shorter video ends. Please note 12300that you may conveniently adjust view properties with the @ref{scale} and 12301@ref{fps} filters. 12302 12303It accepts the following parameters: 12304@table @option 12305 12306@item format 12307The desired packing format. Supported values are: 12308 12309@table @option 12310 12311@item sbs 12312The views are next to each other (default). 12313 12314@item tab 12315The views are on top of each other. 12316 12317@item lines 12318The views are packed by line. 12319 12320@item columns 12321The views are packed by column. 12322 12323@item frameseq 12324The views are temporally interleaved. 12325 12326@end table 12327 12328@end table 12329 12330Some examples: 12331 12332@example 12333# Convert left and right views into a frame-sequential video 12334ffmpeg -i LEFT -i RIGHT -filter_complex framepack=frameseq OUTPUT 12335 12336# Convert views into a side-by-side video with the same output resolution as the input 12337ffmpeg -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 12338@end example 12339 12340@section framerate 12341 12342Change the frame rate by interpolating new video output frames from the source 12343frames. 12344 12345This filter is not designed to function correctly with interlaced media. If 12346you wish to change the frame rate of interlaced media then you are required 12347to deinterlace before this filter and re-interlace after this filter. 12348 12349A description of the accepted options follows. 12350 12351@table @option 12352@item fps 12353Specify the output frames per second. This option can also be specified 12354as a value alone. The default is @code{50}. 12355 12356@item interp_start 12357Specify the start of a range where the output frame will be created as a 12358linear interpolation of two frames. The range is [@code{0}-@code{255}], 12359the default is @code{15}. 12360 12361@item interp_end 12362Specify the end of a range where the output frame will be created as a 12363linear interpolation of two frames. The range is [@code{0}-@code{255}], 12364the default is @code{240}. 12365 12366@item scene 12367Specify the level at which a scene change is detected as a value between 123680 and 100 to indicate a new scene; a low value reflects a low 12369probability for the current frame to introduce a new scene, while a higher 12370value means the current frame is more likely to be one. 12371The default is @code{8.2}. 12372 12373@item flags 12374Specify flags influencing the filter process. 12375 12376Available value for @var{flags} is: 12377 12378@table @option 12379@item scene_change_detect, scd 12380Enable scene change detection using the value of the option @var{scene}. 12381This flag is enabled by default. 12382@end table 12383@end table 12384 12385@section framestep 12386 12387Select one frame every N-th frame. 12388 12389This filter accepts the following option: 12390@table @option 12391@item step 12392Select frame after every @code{step} frames. 12393Allowed values are positive integers higher than 0. Default value is @code{1}. 12394@end table 12395 12396@section freezedetect 12397 12398Detect frozen video. 12399 12400This filter logs a message and sets frame metadata when it detects that the 12401input video has no significant change in content during a specified duration. 12402Video freeze detection calculates the mean average absolute difference of all 12403the components of video frames and compares it to a noise floor. 12404 12405The printed times and duration are expressed in seconds. The 12406@code{lavfi.freezedetect.freeze_start} metadata key is set on the first frame 12407whose timestamp equals or exceeds the detection duration and it contains the 12408timestamp of the first frame of the freeze. The 12409@code{lavfi.freezedetect.freeze_duration} and 12410@code{lavfi.freezedetect.freeze_end} metadata keys are set on the first frame 12411after the freeze. 12412 12413The filter accepts the following options: 12414 12415@table @option 12416@item noise, n 12417Set noise tolerance. Can be specified in dB (in case "dB" is appended to the 12418specified value) or as a difference ratio between 0 and 1. Default is -60dB, or 124190.001. 12420 12421@item duration, d 12422Set freeze duration until notification (default is 2 seconds). 12423@end table 12424 12425@section freezeframes 12426 12427Freeze video frames. 12428 12429This filter freezes video frames using frame from 2nd input. 12430 12431The filter accepts the following options: 12432 12433@table @option 12434@item first 12435Set number of first frame from which to start freeze. 12436 12437@item last 12438Set number of last frame from which to end freeze. 12439 12440@item replace 12441Set number of frame from 2nd input which will be used instead of replaced frames. 12442@end table 12443 12444@anchor{frei0r} 12445@section frei0r 12446 12447Apply a frei0r effect to the input video. 12448 12449To enable the compilation of this filter, you need to install the frei0r 12450header and configure FFmpeg with @code{--enable-frei0r}. 12451 12452It accepts the following parameters: 12453 12454@table @option 12455 12456@item filter_name 12457The name of the frei0r effect to load. If the environment variable 12458@env{FREI0R_PATH} is defined, the frei0r effect is searched for in each of the 12459directories specified by the colon-separated list in @env{FREI0R_PATH}. 12460Otherwise, the standard frei0r paths are searched, in this order: 12461@file{HOME/.frei0r-1/lib/}, @file{/usr/local/lib/frei0r-1/}, 12462@file{/usr/lib/frei0r-1/}. 12463 12464@item filter_params 12465A '|'-separated list of parameters to pass to the frei0r effect. 12466 12467@end table 12468 12469A frei0r effect parameter can be a boolean (its value is either 12470"y" or "n"), a double, a color (specified as 12471@var{R}/@var{G}/@var{B}, where @var{R}, @var{G}, and @var{B} are floating point 12472numbers between 0.0 and 1.0, inclusive) or a color description as specified in the 12473@ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}, 12474a position (specified as @var{X}/@var{Y}, where 12475@var{X} and @var{Y} are floating point numbers) and/or a string. 12476 12477The number and types of parameters depend on the loaded effect. If an 12478effect parameter is not specified, the default value is set. 12479 12480@subsection Examples 12481 12482@itemize 12483@item 12484Apply the distort0r effect, setting the first two double parameters: 12485@example 12486frei0r=filter_name=distort0r:filter_params=0.5|0.01 12487@end example 12488 12489@item 12490Apply the colordistance effect, taking a color as the first parameter: 12491@example 12492frei0r=colordistance:0.2/0.3/0.4 12493frei0r=colordistance:violet 12494frei0r=colordistance:0x112233 12495@end example 12496 12497@item 12498Apply the perspective effect, specifying the top left and top right image 12499positions: 12500@example 12501frei0r=perspective:0.2/0.2|0.8/0.2 12502@end example 12503@end itemize 12504 12505For more information, see 12506@url{http://frei0r.dyne.org} 12507 12508@subsection Commands 12509 12510This filter supports the @option{filter_params} option as @ref{commands}. 12511 12512@section fspp 12513 12514Apply fast and simple postprocessing. It is a faster version of @ref{spp}. 12515 12516It splits (I)DCT into horizontal/vertical passes. Unlike the simple post- 12517processing filter, one of them is performed once per block, not per pixel. 12518This allows for much higher speed. 12519 12520The filter accepts the following options: 12521 12522@table @option 12523@item quality 12524Set quality. This option defines the number of levels for averaging. It accepts 12525an integer in the range 4-5. Default value is @code{4}. 12526 12527@item qp 12528Force a constant quantization parameter. It accepts an integer in range 0-63. 12529If not set, the filter will use the QP from the video stream (if available). 12530 12531@item strength 12532Set filter strength. It accepts an integer in range -15 to 32. Lower values mean 12533more details but also more artifacts, while higher values make the image smoother 12534but also blurrier. Default value is @code{0} − PSNR optimal. 12535 12536@item use_bframe_qp 12537Enable the use of the QP from the B-Frames if set to @code{1}. Using this 12538option may cause flicker since the B-Frames have often larger QP. Default is 12539@code{0} (not enabled). 12540 12541@end table 12542 12543@section gblur 12544 12545Apply Gaussian blur filter. 12546 12547The filter accepts the following options: 12548 12549@table @option 12550@item sigma 12551Set horizontal sigma, standard deviation of Gaussian blur. Default is @code{0.5}. 12552 12553@item steps 12554Set number of steps for Gaussian approximation. Default is @code{1}. 12555 12556@item planes 12557Set which planes to filter. By default all planes are filtered. 12558 12559@item sigmaV 12560Set vertical sigma, if negative it will be same as @code{sigma}. 12561Default is @code{-1}. 12562@end table 12563 12564@subsection Commands 12565This filter supports same commands as options. 12566The command accepts the same syntax of the corresponding option. 12567 12568If the specified expression is not valid, it is kept at its current 12569value. 12570 12571@section geq 12572 12573Apply generic equation to each pixel. 12574 12575The filter accepts the following options: 12576 12577@table @option 12578@item lum_expr, lum 12579Set the luminance expression. 12580@item cb_expr, cb 12581Set the chrominance blue expression. 12582@item cr_expr, cr 12583Set the chrominance red expression. 12584@item alpha_expr, a 12585Set the alpha expression. 12586@item red_expr, r 12587Set the red expression. 12588@item green_expr, g 12589Set the green expression. 12590@item blue_expr, b 12591Set the blue expression. 12592@end table 12593 12594The colorspace is selected according to the specified options. If one 12595of the @option{lum_expr}, @option{cb_expr}, or @option{cr_expr} 12596options is specified, the filter will automatically select a YCbCr 12597colorspace. If one of the @option{red_expr}, @option{green_expr}, or 12598@option{blue_expr} options is specified, it will select an RGB 12599colorspace. 12600 12601If one of the chrominance expression is not defined, it falls back on the other 12602one. If no alpha expression is specified it will evaluate to opaque value. 12603If none of chrominance expressions are specified, they will evaluate 12604to the luminance expression. 12605 12606The expressions can use the following variables and functions: 12607 12608@table @option 12609@item N 12610The sequential number of the filtered frame, starting from @code{0}. 12611 12612@item X 12613@item Y 12614The coordinates of the current sample. 12615 12616@item W 12617@item H 12618The width and height of the image. 12619 12620@item SW 12621@item SH 12622Width and height scale depending on the currently filtered plane. It is the 12623ratio between the corresponding luma plane number of pixels and the current 12624plane ones. E.g. for YUV4:2:0 the values are @code{1,1} for the luma plane, and 12625@code{0.5,0.5} for chroma planes. 12626 12627@item T 12628Time of the current frame, expressed in seconds. 12629 12630@item p(x, y) 12631Return the value of the pixel at location (@var{x},@var{y}) of the current 12632plane. 12633 12634@item lum(x, y) 12635Return the value of the pixel at location (@var{x},@var{y}) of the luminance 12636plane. 12637 12638@item cb(x, y) 12639Return the value of the pixel at location (@var{x},@var{y}) of the 12640blue-difference chroma plane. Return 0 if there is no such plane. 12641 12642@item cr(x, y) 12643Return the value of the pixel at location (@var{x},@var{y}) of the 12644red-difference chroma plane. Return 0 if there is no such plane. 12645 12646@item r(x, y) 12647@item g(x, y) 12648@item b(x, y) 12649Return the value of the pixel at location (@var{x},@var{y}) of the 12650red/green/blue component. Return 0 if there is no such component. 12651 12652@item alpha(x, y) 12653Return the value of the pixel at location (@var{x},@var{y}) of the alpha 12654plane. Return 0 if there is no such plane. 12655 12656@item psum(x,y), lumsum(x, y), cbsum(x,y), crsum(x,y), rsum(x,y), gsum(x,y), bsum(x,y), alphasum(x,y) 12657Sum of sample values in the rectangle from (0,0) to (x,y), this allows obtaining 12658sums of samples within a rectangle. See the functions without the sum postfix. 12659 12660@item interpolation 12661Set one of interpolation methods: 12662@table @option 12663@item nearest, n 12664@item bilinear, b 12665@end table 12666Default is bilinear. 12667@end table 12668 12669For functions, if @var{x} and @var{y} are outside the area, the value will be 12670automatically clipped to the closer edge. 12671 12672Please note that this filter can use multiple threads in which case each slice 12673will have its own expression state. If you want to use only a single expression 12674state because your expressions depend on previous state then you should limit 12675the number of filter threads to 1. 12676 12677@subsection Examples 12678 12679@itemize 12680@item 12681Flip the image horizontally: 12682@example 12683geq=p(W-X\,Y) 12684@end example 12685 12686@item 12687Generate a bidimensional sine wave, with angle @code{PI/3} and a 12688wavelength of 100 pixels: 12689@example 12690geq=128 + 100*sin(2*(PI/100)*(cos(PI/3)*(X-50*T) + sin(PI/3)*Y)):128:128 12691@end example 12692 12693@item 12694Generate a fancy enigmatic moving light: 12695@example 12696nullsrc=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 12697@end example 12698 12699@item 12700Generate a quick emboss effect: 12701@example 12702format=gray,geq=lum_expr='(p(X,Y)+(256-p(X-4,Y-4)))/2' 12703@end example 12704 12705@item 12706Modify RGB components depending on pixel position: 12707@example 12708geq=r='X/W*r(X,Y)':g='(1-X/W)*g(X,Y)':b='(H-Y)/H*b(X,Y)' 12709@end example 12710 12711@item 12712Create a radial gradient that is the same size as the input (also see 12713the @ref{vignette} filter): 12714@example 12715geq=lum=255*gauss((X/W-0.5)*3)*gauss((Y/H-0.5)*3)/gauss(0)/gauss(0),format=gray 12716@end example 12717@end itemize 12718 12719@section gradfun 12720 12721Fix the banding artifacts that are sometimes introduced into nearly flat 12722regions by truncation to 8-bit color depth. 12723Interpolate the gradients that should go where the bands are, and 12724dither them. 12725 12726It is designed for playback only. Do not use it prior to 12727lossy compression, because compression tends to lose the dither and 12728bring back the bands. 12729 12730It accepts the following parameters: 12731 12732@table @option 12733 12734@item strength 12735The maximum amount by which the filter will change any one pixel. This is also 12736the threshold for detecting nearly flat regions. Acceptable values range from 12737.51 to 64; the default value is 1.2. Out-of-range values will be clipped to the 12738valid range. 12739 12740@item radius 12741The neighborhood to fit the gradient to. A larger radius makes for smoother 12742gradients, but also prevents the filter from modifying the pixels near detailed 12743regions. Acceptable values are 8-32; the default value is 16. Out-of-range 12744values will be clipped to the valid range. 12745 12746@end table 12747 12748Alternatively, the options can be specified as a flat string: 12749@var{strength}[:@var{radius}] 12750 12751@subsection Examples 12752 12753@itemize 12754@item 12755Apply the filter with a @code{3.5} strength and radius of @code{8}: 12756@example 12757gradfun=3.5:8 12758@end example 12759 12760@item 12761Specify radius, omitting the strength (which will fall-back to the default 12762value): 12763@example 12764gradfun=radius=8 12765@end example 12766 12767@end itemize 12768 12769@anchor{graphmonitor} 12770@section graphmonitor 12771Show various filtergraph stats. 12772 12773With this filter one can debug complete filtergraph. 12774Especially issues with links filling with queued frames. 12775 12776The filter accepts the following options: 12777 12778@table @option 12779@item size, s 12780Set video output size. Default is @var{hd720}. 12781 12782@item opacity, o 12783Set video opacity. Default is @var{0.9}. Allowed range is from @var{0} to @var{1}. 12784 12785@item mode, m 12786Set output mode, can be @var{fulll} or @var{compact}. 12787In @var{compact} mode only filters with some queued frames have displayed stats. 12788 12789@item flags, f 12790Set flags which enable which stats are shown in video. 12791 12792Available values for flags are: 12793@table @samp 12794@item queue 12795Display number of queued frames in each link. 12796 12797@item frame_count_in 12798Display number of frames taken from filter. 12799 12800@item frame_count_out 12801Display number of frames given out from filter. 12802 12803@item pts 12804Display current filtered frame pts. 12805 12806@item time 12807Display current filtered frame time. 12808 12809@item timebase 12810Display time base for filter link. 12811 12812@item format 12813Display used format for filter link. 12814 12815@item size 12816Display video size or number of audio channels in case of audio used by filter link. 12817 12818@item rate 12819Display video frame rate or sample rate in case of audio used by filter link. 12820 12821@item eof 12822Display link output status. 12823@end table 12824 12825@item rate, r 12826Set upper limit for video rate of output stream, Default value is @var{25}. 12827This guarantee that output video frame rate will not be higher than this value. 12828@end table 12829 12830@section greyedge 12831A color constancy variation filter which estimates scene illumination via grey edge algorithm 12832and corrects the scene colors accordingly. 12833 12834See: @url{https://staff.science.uva.nl/th.gevers/pub/GeversTIP07.pdf} 12835 12836The filter accepts the following options: 12837 12838@table @option 12839@item difford 12840The order of differentiation to be applied on the scene. Must be chosen in the range 12841[0,2] and default value is 1. 12842 12843@item minknorm 12844The Minkowski parameter to be used for calculating the Minkowski distance. Must 12845be chosen in the range [0,20] and default value is 1. Set to 0 for getting 12846max value instead of calculating Minkowski distance. 12847 12848@item sigma 12849The standard deviation of Gaussian blur to be applied on the scene. Must be 12850chosen in the range [0,1024.0] and default value = 1. floor( @var{sigma} * break_off_sigma(3) ) 12851can't be equal to 0 if @var{difford} is greater than 0. 12852@end table 12853 12854@subsection Examples 12855@itemize 12856 12857@item 12858Grey Edge: 12859@example 12860greyedge=difford=1:minknorm=5:sigma=2 12861@end example 12862 12863@item 12864Max Edge: 12865@example 12866greyedge=difford=1:minknorm=0:sigma=2 12867@end example 12868 12869@end itemize 12870 12871@anchor{haldclut} 12872@section haldclut 12873 12874Apply a Hald CLUT to a video stream. 12875 12876First input is the video stream to process, and second one is the Hald CLUT. 12877The Hald CLUT input can be a simple picture or a complete video stream. 12878 12879The filter accepts the following options: 12880 12881@table @option 12882@item shortest 12883Force termination when the shortest input terminates. Default is @code{0}. 12884@item repeatlast 12885Continue applying the last CLUT after the end of the stream. A value of 12886@code{0} disable the filter after the last frame of the CLUT is reached. 12887Default is @code{1}. 12888@end table 12889 12890@code{haldclut} also has the same interpolation options as @ref{lut3d} (both 12891filters share the same internals). 12892 12893This filter also supports the @ref{framesync} options. 12894 12895More information about the Hald CLUT can be found on Eskil Steenberg's website 12896(Hald CLUT author) at @url{http://www.quelsolaar.com/technology/clut.html}. 12897 12898@subsection Commands 12899 12900This filter supports the @code{interp} option as @ref{commands}. 12901 12902@subsection Workflow examples 12903 12904@subsubsection Hald CLUT video stream 12905 12906Generate an identity Hald CLUT stream altered with various effects: 12907@example 12908ffmpeg -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 12909@end example 12910 12911Note: make sure you use a lossless codec. 12912 12913Then use it with @code{haldclut} to apply it on some random stream: 12914@example 12915ffmpeg -f lavfi -i mandelbrot -i clut.nut -filter_complex '[0][1] haldclut' -t 20 mandelclut.mkv 12916@end example 12917 12918The Hald CLUT will be applied to the 10 first seconds (duration of 12919@file{clut.nut}), then the latest picture of that CLUT stream will be applied 12920to the remaining frames of the @code{mandelbrot} stream. 12921 12922@subsubsection Hald CLUT with preview 12923 12924A Hald CLUT is supposed to be a squared image of @code{Level*Level*Level} by 12925@code{Level*Level*Level} pixels. For a given Hald CLUT, FFmpeg will select the 12926biggest possible square starting at the top left of the picture. The remaining 12927padding pixels (bottom or right) will be ignored. This area can be used to add 12928a preview of the Hald CLUT. 12929 12930Typically, the following generated Hald CLUT will be supported by the 12931@code{haldclut} filter: 12932 12933@example 12934ffmpeg -f lavfi -i @ref{haldclutsrc}=8 -vf " 12935 pad=iw+320 [padded_clut]; 12936 smptebars=s=320x256, split [a][b]; 12937 [padded_clut][a] overlay=W-320:h, curves=color_negative [main]; 12938 [main][b] overlay=W-320" -frames:v 1 clut.png 12939@end example 12940 12941It contains the original and a preview of the effect of the CLUT: SMPTE color 12942bars are displayed on the right-top, and below the same color bars processed by 12943the color changes. 12944 12945Then, the effect of this Hald CLUT can be visualized with: 12946@example 12947ffplay input.mkv -vf "movie=clut.png, [in] haldclut" 12948@end example 12949 12950@section hflip 12951 12952Flip the input video horizontally. 12953 12954For example, to horizontally flip the input video with @command{ffmpeg}: 12955@example 12956ffmpeg -i in.avi -vf "hflip" out.avi 12957@end example 12958 12959@section histeq 12960This filter applies a global color histogram equalization on a 12961per-frame basis. 12962 12963It can be used to correct video that has a compressed range of pixel 12964intensities. The filter redistributes the pixel intensities to 12965equalize their distribution across the intensity range. It may be 12966viewed as an "automatically adjusting contrast filter". This filter is 12967useful only for correcting degraded or poorly captured source 12968video. 12969 12970The filter accepts the following options: 12971 12972@table @option 12973@item strength 12974Determine the amount of equalization to be applied. As the strength 12975is reduced, the distribution of pixel intensities more-and-more 12976approaches that of the input frame. The value must be a float number 12977in the range [0,1] and defaults to 0.200. 12978 12979@item intensity 12980Set the maximum intensity that can generated and scale the output 12981values appropriately. The strength should be set as desired and then 12982the intensity can be limited if needed to avoid washing-out. The value 12983must be a float number in the range [0,1] and defaults to 0.210. 12984 12985@item antibanding 12986Set the antibanding level. If enabled the filter will randomly vary 12987the luminance of output pixels by a small amount to avoid banding of 12988the histogram. Possible values are @code{none}, @code{weak} or 12989@code{strong}. It defaults to @code{none}. 12990@end table 12991 12992@anchor{histogram} 12993@section histogram 12994 12995Compute and draw a color distribution histogram for the input video. 12996 12997The computed histogram is a representation of the color component 12998distribution in an image. 12999 13000Standard histogram displays the color components distribution in an image. 13001Displays color graph for each color component. Shows distribution of 13002the Y, U, V, A or R, G, B components, depending on input format, in the 13003current frame. Below each graph a color component scale meter is shown. 13004 13005The filter accepts the following options: 13006 13007@table @option 13008@item level_height 13009Set height of level. Default value is @code{200}. 13010Allowed range is [50, 2048]. 13011 13012@item scale_height 13013Set height of color scale. Default value is @code{12}. 13014Allowed range is [0, 40]. 13015 13016@item display_mode 13017Set display mode. 13018It accepts the following values: 13019@table @samp 13020@item stack 13021Per color component graphs are placed below each other. 13022 13023@item parade 13024Per color component graphs are placed side by side. 13025 13026@item overlay 13027Presents information identical to that in the @code{parade}, except 13028that the graphs representing color components are superimposed directly 13029over one another. 13030@end table 13031Default is @code{stack}. 13032 13033@item levels_mode 13034Set mode. Can be either @code{linear}, or @code{logarithmic}. 13035Default is @code{linear}. 13036 13037@item components 13038Set what color components to display. 13039Default is @code{7}. 13040 13041@item fgopacity 13042Set foreground opacity. Default is @code{0.7}. 13043 13044@item bgopacity 13045Set background opacity. Default is @code{0.5}. 13046@end table 13047 13048@subsection Examples 13049 13050@itemize 13051 13052@item 13053Calculate and draw histogram: 13054@example 13055ffplay -i input -vf histogram 13056@end example 13057 13058@end itemize 13059 13060@anchor{hqdn3d} 13061@section hqdn3d 13062 13063This is a high precision/quality 3d denoise filter. It aims to reduce 13064image noise, producing smooth images and making still images really 13065still. It should enhance compressibility. 13066 13067It accepts the following optional parameters: 13068 13069@table @option 13070@item luma_spatial 13071A non-negative floating point number which specifies spatial luma strength. 13072It defaults to 4.0. 13073 13074@item chroma_spatial 13075A non-negative floating point number which specifies spatial chroma strength. 13076It defaults to 3.0*@var{luma_spatial}/4.0. 13077 13078@item luma_tmp 13079A floating point number which specifies luma temporal strength. It defaults to 130806.0*@var{luma_spatial}/4.0. 13081 13082@item chroma_tmp 13083A floating point number which specifies chroma temporal strength. It defaults to 13084@var{luma_tmp}*@var{chroma_spatial}/@var{luma_spatial}. 13085@end table 13086 13087@subsection Commands 13088This filter supports same @ref{commands} as options. 13089The command accepts the same syntax of the corresponding option. 13090 13091If the specified expression is not valid, it is kept at its current 13092value. 13093 13094@anchor{hwdownload} 13095@section hwdownload 13096 13097Download hardware frames to system memory. 13098 13099The input must be in hardware frames, and the output a non-hardware format. 13100Not all formats will be supported on the output - it may be necessary to insert 13101an additional @option{format} filter immediately following in the graph to get 13102the output in a supported format. 13103 13104@section hwmap 13105 13106Map hardware frames to system memory or to another device. 13107 13108This filter has several different modes of operation; which one is used depends 13109on the input and output formats: 13110@itemize 13111@item 13112Hardware frame input, normal frame output 13113 13114Map the input frames to system memory and pass them to the output. If the 13115original hardware frame is later required (for example, after overlaying 13116something else on part of it), the @option{hwmap} filter can be used again 13117in the next mode to retrieve it. 13118@item 13119Normal frame input, hardware frame output 13120 13121If the input is actually a software-mapped hardware frame, then unmap it - 13122that is, return the original hardware frame. 13123 13124Otherwise, a device must be provided. Create new hardware surfaces on that 13125device for the output, then map them back to the software format at the input 13126and give those frames to the preceding filter. This will then act like the 13127@option{hwupload} filter, but may be able to avoid an additional copy when 13128the input is already in a compatible format. 13129@item 13130Hardware frame input and output 13131 13132A device must be supplied for the output, either directly or with the 13133@option{derive_device} option. The input and output devices must be of 13134different types and compatible - the exact meaning of this is 13135system-dependent, but typically it means that they must refer to the same 13136underlying hardware context (for example, refer to the same graphics card). 13137 13138If the input frames were originally created on the output device, then unmap 13139to retrieve the original frames. 13140 13141Otherwise, map the frames to the output device - create new hardware frames 13142on the output corresponding to the frames on the input. 13143@end itemize 13144 13145The following additional parameters are accepted: 13146 13147@table @option 13148@item mode 13149Set the frame mapping mode. Some combination of: 13150@table @var 13151@item read 13152The mapped frame should be readable. 13153@item write 13154The mapped frame should be writeable. 13155@item overwrite 13156The mapping will always overwrite the entire frame. 13157 13158This may improve performance in some cases, as the original contents of the 13159frame need not be loaded. 13160@item direct 13161The mapping must not involve any copying. 13162 13163Indirect mappings to copies of frames are created in some cases where either 13164direct mapping is not possible or it would have unexpected properties. 13165Setting this flag ensures that the mapping is direct and will fail if that is 13166not possible. 13167@end table 13168Defaults to @var{read+write} if not specified. 13169 13170@item derive_device @var{type} 13171Rather than using the device supplied at initialisation, instead derive a new 13172device of type @var{type} from the device the input frames exist on. 13173 13174@item reverse 13175In a hardware to hardware mapping, map in reverse - create frames in the sink 13176and map them back to the source. This may be necessary in some cases where 13177a mapping in one direction is required but only the opposite direction is 13178supported by the devices being used. 13179 13180This option is dangerous - it may break the preceding filter in undefined 13181ways if there are any additional constraints on that filter's output. 13182Do not use it without fully understanding the implications of its use. 13183@end table 13184 13185@anchor{hwupload} 13186@section hwupload 13187 13188Upload system memory frames to hardware surfaces. 13189 13190The device to upload to must be supplied when the filter is initialised. If 13191using ffmpeg, select the appropriate device with the @option{-filter_hw_device} 13192option or with the @option{derive_device} option. The input and output devices 13193must be of different types and compatible - the exact meaning of this is 13194system-dependent, but typically it means that they must refer to the same 13195underlying hardware context (for example, refer to the same graphics card). 13196 13197The following additional parameters are accepted: 13198 13199@table @option 13200@item derive_device @var{type} 13201Rather than using the device supplied at initialisation, instead derive a new 13202device of type @var{type} from the device the input frames exist on. 13203@end table 13204 13205@anchor{hwupload_cuda} 13206@section hwupload_cuda 13207 13208Upload system memory frames to a CUDA device. 13209 13210It accepts the following optional parameters: 13211 13212@table @option 13213@item device 13214The number of the CUDA device to use 13215@end table 13216 13217@section hqx 13218 13219Apply a high-quality magnification filter designed for pixel art. This filter 13220was originally created by Maxim Stepin. 13221 13222It accepts the following option: 13223 13224@table @option 13225@item n 13226Set the scaling dimension: @code{2} for @code{hq2x}, @code{3} for 13227@code{hq3x} and @code{4} for @code{hq4x}. 13228Default is @code{3}. 13229@end table 13230 13231@section hstack 13232Stack input videos horizontally. 13233 13234All streams must be of same pixel format and of same height. 13235 13236Note that this filter is faster than using @ref{overlay} and @ref{pad} filter 13237to create same output. 13238 13239The filter accepts the following option: 13240 13241@table @option 13242@item inputs 13243Set number of input streams. Default is 2. 13244 13245@item shortest 13246If set to 1, force the output to terminate when the shortest input 13247terminates. Default value is 0. 13248@end table 13249 13250@section hue 13251 13252Modify the hue and/or the saturation of the input. 13253 13254It accepts the following parameters: 13255 13256@table @option 13257@item h 13258Specify the hue angle as a number of degrees. It accepts an expression, 13259and defaults to "0". 13260 13261@item s 13262Specify the saturation in the [-10,10] range. It accepts an expression and 13263defaults to "1". 13264 13265@item H 13266Specify the hue angle as a number of radians. It accepts an 13267expression, and defaults to "0". 13268 13269@item b 13270Specify the brightness in the [-10,10] range. It accepts an expression and 13271defaults to "0". 13272@end table 13273 13274@option{h} and @option{H} are mutually exclusive, and can't be 13275specified at the same time. 13276 13277The @option{b}, @option{h}, @option{H} and @option{s} option values are 13278expressions containing the following constants: 13279 13280@table @option 13281@item n 13282frame count of the input frame starting from 0 13283 13284@item pts 13285presentation timestamp of the input frame expressed in time base units 13286 13287@item r 13288frame rate of the input video, NAN if the input frame rate is unknown 13289 13290@item t 13291timestamp expressed in seconds, NAN if the input timestamp is unknown 13292 13293@item tb 13294time base of the input video 13295@end table 13296 13297@subsection Examples 13298 13299@itemize 13300@item 13301Set the hue to 90 degrees and the saturation to 1.0: 13302@example 13303hue=h=90:s=1 13304@end example 13305 13306@item 13307Same command but expressing the hue in radians: 13308@example 13309hue=H=PI/2:s=1 13310@end example 13311 13312@item 13313Rotate hue and make the saturation swing between 0 13314and 2 over a period of 1 second: 13315@example 13316hue="H=2*PI*t: s=sin(2*PI*t)+1" 13317@end example 13318 13319@item 13320Apply a 3 seconds saturation fade-in effect starting at 0: 13321@example 13322hue="s=min(t/3\,1)" 13323@end example 13324 13325The general fade-in expression can be written as: 13326@example 13327hue="s=min(0\, max((t-START)/DURATION\, 1))" 13328@end example 13329 13330@item 13331Apply a 3 seconds saturation fade-out effect starting at 5 seconds: 13332@example 13333hue="s=max(0\, min(1\, (8-t)/3))" 13334@end example 13335 13336The general fade-out expression can be written as: 13337@example 13338hue="s=max(0\, min(1\, (START+DURATION-t)/DURATION))" 13339@end example 13340 13341@end itemize 13342 13343@subsection Commands 13344 13345This filter supports the following commands: 13346@table @option 13347@item b 13348@item s 13349@item h 13350@item H 13351Modify the hue and/or the saturation and/or brightness of the input video. 13352The command accepts the same syntax of the corresponding option. 13353 13354If the specified expression is not valid, it is kept at its current 13355value. 13356@end table 13357 13358@section hysteresis 13359 13360Grow first stream into second stream by connecting components. 13361This makes it possible to build more robust edge masks. 13362 13363This filter accepts the following options: 13364 13365@table @option 13366@item planes 13367Set which planes will be processed as bitmap, unprocessed planes will be 13368copied from first stream. 13369By default value 0xf, all planes will be processed. 13370 13371@item threshold 13372Set threshold which is used in filtering. If pixel component value is higher than 13373this value filter algorithm for connecting components is activated. 13374By default value is 0. 13375@end table 13376 13377The @code{hysteresis} filter also supports the @ref{framesync} options. 13378 13379@section identity 13380 13381Obtain the identity score between two input videos. 13382 13383This filter takes two input videos. 13384 13385Both input videos must have the same resolution and pixel format for 13386this filter to work correctly. Also it assumes that both inputs 13387have the same number of frames, which are compared one by one. 13388 13389The obtained per component, average, min and max identity score is printed through 13390the logging system. 13391 13392The filter stores the calculated identity scores of each frame in frame metadata. 13393 13394In the below example the input file @file{main.mpg} being processed is compared 13395with the reference file @file{ref.mpg}. 13396 13397@example 13398ffmpeg -i main.mpg -i ref.mpg -lavfi identity -f null - 13399@end example 13400 13401@section idet 13402 13403Detect video interlacing type. 13404 13405This filter tries to detect if the input frames are interlaced, progressive, 13406top or bottom field first. It will also try to detect fields that are 13407repeated between adjacent frames (a sign of telecine). 13408 13409Single frame detection considers only immediately adjacent frames when classifying each frame. 13410Multiple frame detection incorporates the classification history of previous frames. 13411 13412The filter will log these metadata values: 13413 13414@table @option 13415@item single.current_frame 13416Detected type of current frame using single-frame detection. One of: 13417``tff'' (top field first), ``bff'' (bottom field first), 13418``progressive'', or ``undetermined'' 13419 13420@item single.tff 13421Cumulative number of frames detected as top field first using single-frame detection. 13422 13423@item multiple.tff 13424Cumulative number of frames detected as top field first using multiple-frame detection. 13425 13426@item single.bff 13427Cumulative number of frames detected as bottom field first using single-frame detection. 13428 13429@item multiple.current_frame 13430Detected type of current frame using multiple-frame detection. One of: 13431``tff'' (top field first), ``bff'' (bottom field first), 13432``progressive'', or ``undetermined'' 13433 13434@item multiple.bff 13435Cumulative number of frames detected as bottom field first using multiple-frame detection. 13436 13437@item single.progressive 13438Cumulative number of frames detected as progressive using single-frame detection. 13439 13440@item multiple.progressive 13441Cumulative number of frames detected as progressive using multiple-frame detection. 13442 13443@item single.undetermined 13444Cumulative number of frames that could not be classified using single-frame detection. 13445 13446@item multiple.undetermined 13447Cumulative number of frames that could not be classified using multiple-frame detection. 13448 13449@item repeated.current_frame 13450Which field in the current frame is repeated from the last. One of ``neither'', ``top'', or ``bottom''. 13451 13452@item repeated.neither 13453Cumulative number of frames with no repeated field. 13454 13455@item repeated.top 13456Cumulative number of frames with the top field repeated from the previous frame's top field. 13457 13458@item repeated.bottom 13459Cumulative number of frames with the bottom field repeated from the previous frame's bottom field. 13460@end table 13461 13462The filter accepts the following options: 13463 13464@table @option 13465@item intl_thres 13466Set interlacing threshold. 13467@item prog_thres 13468Set progressive threshold. 13469@item rep_thres 13470Threshold for repeated field detection. 13471@item half_life 13472Number of frames after which a given frame's contribution to the 13473statistics is halved (i.e., it contributes only 0.5 to its 13474classification). The default of 0 means that all frames seen are given 13475full weight of 1.0 forever. 13476@item analyze_interlaced_flag 13477When this is not 0 then idet will use the specified number of frames to determine 13478if the interlaced flag is accurate, it will not count undetermined frames. 13479If the flag is found to be accurate it will be used without any further 13480computations, if it is found to be inaccurate it will be cleared without any 13481further computations. This allows inserting the idet filter as a low computational 13482method to clean up the interlaced flag 13483@end table 13484 13485@section il 13486 13487Deinterleave or interleave fields. 13488 13489This filter allows one to process interlaced images fields without 13490deinterlacing them. Deinterleaving splits the input frame into 2 13491fields (so called half pictures). Odd lines are moved to the top 13492half of the output image, even lines to the bottom half. 13493You can process (filter) them independently and then re-interleave them. 13494 13495The filter accepts the following options: 13496 13497@table @option 13498@item luma_mode, l 13499@item chroma_mode, c 13500@item alpha_mode, a 13501Available values for @var{luma_mode}, @var{chroma_mode} and 13502@var{alpha_mode} are: 13503 13504@table @samp 13505@item none 13506Do nothing. 13507 13508@item deinterleave, d 13509Deinterleave fields, placing one above the other. 13510 13511@item interleave, i 13512Interleave fields. Reverse the effect of deinterleaving. 13513@end table 13514Default value is @code{none}. 13515 13516@item luma_swap, ls 13517@item chroma_swap, cs 13518@item alpha_swap, as 13519Swap luma/chroma/alpha fields. Exchange even & odd lines. Default value is @code{0}. 13520@end table 13521 13522@subsection Commands 13523 13524This filter supports the all above options as @ref{commands}. 13525 13526@section inflate 13527 13528Apply inflate effect to the video. 13529 13530This filter replaces the pixel by the local(3x3) average by taking into account 13531only values higher than the pixel. 13532 13533It accepts the following options: 13534 13535@table @option 13536@item threshold0 13537@item threshold1 13538@item threshold2 13539@item threshold3 13540Limit the maximum change for each plane, default is 65535. 13541If 0, plane will remain unchanged. 13542@end table 13543 13544@subsection Commands 13545 13546This filter supports the all above options as @ref{commands}. 13547 13548@section interlace 13549 13550Simple interlacing filter from progressive contents. This interleaves upper (or 13551lower) lines from odd frames with lower (or upper) lines from even frames, 13552halving the frame rate and preserving image height. 13553 13554@example 13555 Original Original New Frame 13556 Frame 'j' Frame 'j+1' (tff) 13557 ========== =========== ================== 13558 Line 0 --------------------> Frame 'j' Line 0 13559 Line 1 Line 1 ----> Frame 'j+1' Line 1 13560 Line 2 ---------------------> Frame 'j' Line 2 13561 Line 3 Line 3 ----> Frame 'j+1' Line 3 13562 ... ... ... 13563New Frame + 1 will be generated by Frame 'j+2' and Frame 'j+3' and so on 13564@end example 13565 13566It accepts the following optional parameters: 13567 13568@table @option 13569@item scan 13570This determines whether the interlaced frame is taken from the even 13571(tff - default) or odd (bff) lines of the progressive frame. 13572 13573@item lowpass 13574Vertical lowpass filter to avoid twitter interlacing and 13575reduce moire patterns. 13576 13577@table @samp 13578@item 0, off 13579Disable vertical lowpass filter 13580 13581@item 1, linear 13582Enable linear filter (default) 13583 13584@item 2, complex 13585Enable complex filter. This will slightly less reduce twitter and moire 13586but better retain detail and subjective sharpness impression. 13587 13588@end table 13589@end table 13590 13591@section kerndeint 13592 13593Deinterlace input video by applying Donald Graft's adaptive kernel 13594deinterling. Work on interlaced parts of a video to produce 13595progressive frames. 13596 13597The description of the accepted parameters follows. 13598 13599@table @option 13600@item thresh 13601Set the threshold which affects the filter's tolerance when 13602determining if a pixel line must be processed. It must be an integer 13603in the range [0,255] and defaults to 10. A value of 0 will result in 13604applying the process on every pixels. 13605 13606@item map 13607Paint pixels exceeding the threshold value to white if set to 1. 13608Default is 0. 13609 13610@item order 13611Set the fields order. Swap fields if set to 1, leave fields alone if 136120. Default is 0. 13613 13614@item sharp 13615Enable additional sharpening if set to 1. Default is 0. 13616 13617@item twoway 13618Enable twoway sharpening if set to 1. Default is 0. 13619@end table 13620 13621@subsection Examples 13622 13623@itemize 13624@item 13625Apply default values: 13626@example 13627kerndeint=thresh=10:map=0:order=0:sharp=0:twoway=0 13628@end example 13629 13630@item 13631Enable additional sharpening: 13632@example 13633kerndeint=sharp=1 13634@end example 13635 13636@item 13637Paint processed pixels in white: 13638@example 13639kerndeint=map=1 13640@end example 13641@end itemize 13642 13643@section kirsch 13644Apply kirsch operator to input video stream. 13645 13646The filter accepts the following option: 13647 13648@table @option 13649@item planes 13650Set which planes will be processed, unprocessed planes will be copied. 13651By default value 0xf, all planes will be processed. 13652 13653@item scale 13654Set value which will be multiplied with filtered result. 13655 13656@item delta 13657Set value which will be added to filtered result. 13658@end table 13659 13660@subsection Commands 13661 13662This filter supports the all above options as @ref{commands}. 13663 13664@section lagfun 13665 13666Slowly update darker pixels. 13667 13668This filter makes short flashes of light appear longer. 13669This filter accepts the following options: 13670 13671@table @option 13672@item decay 13673Set factor for decaying. Default is .95. Allowed range is from 0 to 1. 13674 13675@item planes 13676Set which planes to filter. Default is all. Allowed range is from 0 to 15. 13677@end table 13678 13679@subsection Commands 13680 13681This filter supports the all above options as @ref{commands}. 13682 13683@section lenscorrection 13684 13685Correct radial lens distortion 13686 13687This filter can be used to correct for radial distortion as can result from the use 13688of wide angle lenses, and thereby re-rectify the image. To find the right parameters 13689one can use tools available for example as part of opencv or simply trial-and-error. 13690To use opencv use the calibration sample (under samples/cpp) from the opencv sources 13691and extract the k1 and k2 coefficients from the resulting matrix. 13692 13693Note that effectively the same filter is available in the open-source tools Krita and 13694Digikam from the KDE project. 13695 13696In contrast to the @ref{vignette} filter, which can also be used to compensate lens errors, 13697this filter corrects the distortion of the image, whereas @ref{vignette} corrects the 13698brightness distribution, so you may want to use both filters together in certain 13699cases, though you will have to take care of ordering, i.e. whether vignetting should 13700be applied before or after lens correction. 13701 13702@subsection Options 13703 13704The filter accepts the following options: 13705 13706@table @option 13707@item cx 13708Relative x-coordinate of the focal point of the image, and thereby the center of the 13709distortion. This value has a range [0,1] and is expressed as fractions of the image 13710width. Default is 0.5. 13711@item cy 13712Relative y-coordinate of the focal point of the image, and thereby the center of the 13713distortion. This value has a range [0,1] and is expressed as fractions of the image 13714height. Default is 0.5. 13715@item k1 13716Coefficient of the quadratic correction term. This value has a range [-1,1]. 0 means 13717no correction. Default is 0. 13718@item k2 13719Coefficient of the double quadratic correction term. This value has a range [-1,1]. 137200 means no correction. Default is 0. 13721@item i 13722Set interpolation type. Can be @code{nearest} or @code{bilinear}. 13723Default is @code{nearest}. 13724@item fc 13725Specify the color of the unmapped pixels. For the syntax of this option, 13726check the @ref{color syntax,,"Color" section in the ffmpeg-utils 13727manual,ffmpeg-utils}. Default color is @code{black@@0}. 13728@end table 13729 13730The formula that generates the correction is: 13731 13732@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) 13733 13734where @var{r_0} is halve of the image diagonal and @var{r_src} and @var{r_tgt} are the 13735distances from the focal point in the source and target images, respectively. 13736 13737@subsection Commands 13738 13739This filter supports the all above options as @ref{commands}. 13740 13741@section lensfun 13742 13743Apply lens correction via the lensfun library (@url{http://lensfun.sourceforge.net/}). 13744 13745The @code{lensfun} filter requires the camera make, camera model, and lens model 13746to apply the lens correction. The filter will load the lensfun database and 13747query it to find the corresponding camera and lens entries in the database. As 13748long as these entries can be found with the given options, the filter can 13749perform corrections on frames. Note that incomplete strings will result in the 13750filter choosing the best match with the given options, and the filter will 13751output the chosen camera and lens models (logged with level "info"). You must 13752provide the make, camera model, and lens model as they are required. 13753 13754The filter accepts the following options: 13755 13756@table @option 13757@item make 13758The make of the camera (for example, "Canon"). This option is required. 13759 13760@item model 13761The model of the camera (for example, "Canon EOS 100D"). This option is 13762required. 13763 13764@item lens_model 13765The model of the lens (for example, "Canon EF-S 18-55mm f/3.5-5.6 IS STM"). This 13766option is required. 13767 13768@item mode 13769The type of correction to apply. The following values are valid options: 13770 13771@table @samp 13772@item vignetting 13773Enables fixing lens vignetting. 13774 13775@item geometry 13776Enables fixing lens geometry. This is the default. 13777 13778@item subpixel 13779Enables fixing chromatic aberrations. 13780 13781@item vig_geo 13782Enables fixing lens vignetting and lens geometry. 13783 13784@item vig_subpixel 13785Enables fixing lens vignetting and chromatic aberrations. 13786 13787@item distortion 13788Enables fixing both lens geometry and chromatic aberrations. 13789 13790@item all 13791Enables all possible corrections. 13792 13793@end table 13794@item focal_length 13795The focal length of the image/video (zoom; expected constant for video). For 13796example, a 18--55mm lens has focal length range of [18--55], so a value in that 13797range should be chosen when using that lens. Default 18. 13798 13799@item aperture 13800The aperture of the image/video (expected constant for video). Note that 13801aperture is only used for vignetting correction. Default 3.5. 13802 13803@item focus_distance 13804The focus distance of the image/video (expected constant for video). Note that 13805focus distance is only used for vignetting and only slightly affects the 13806vignetting correction process. If unknown, leave it at the default value (which 13807is 1000). 13808 13809@item scale 13810The scale factor which is applied after transformation. After correction the 13811video is no longer necessarily rectangular. This parameter controls how much of 13812the resulting image is visible. The value 0 means that a value will be chosen 13813automatically such that there is little or no unmapped area in the output 13814image. 1.0 means that no additional scaling is done. Lower values may result 13815in more of the corrected image being visible, while higher values may avoid 13816unmapped areas in the output. 13817 13818@item target_geometry 13819The target geometry of the output image/video. The following values are valid 13820options: 13821 13822@table @samp 13823@item rectilinear (default) 13824@item fisheye 13825@item panoramic 13826@item equirectangular 13827@item fisheye_orthographic 13828@item fisheye_stereographic 13829@item fisheye_equisolid 13830@item fisheye_thoby 13831@end table 13832@item reverse 13833Apply the reverse of image correction (instead of correcting distortion, apply 13834it). 13835 13836@item interpolation 13837The type of interpolation used when correcting distortion. The following values 13838are valid options: 13839 13840@table @samp 13841@item nearest 13842@item linear (default) 13843@item lanczos 13844@end table 13845@end table 13846 13847@subsection Examples 13848 13849@itemize 13850@item 13851Apply lens correction with make "Canon", camera model "Canon EOS 100D", and lens 13852model "Canon EF-S 18-55mm f/3.5-5.6 IS STM" with focal length of "18" and 13853aperture of "8.0". 13854 13855@example 13856ffmpeg -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 13857@end example 13858 13859@item 13860Apply the same as before, but only for the first 5 seconds of video. 13861 13862@example 13863ffmpeg -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 13864@end example 13865 13866@end itemize 13867 13868@section libvmaf 13869 13870Obtain the VMAF (Video Multi-Method Assessment Fusion) 13871score between two input videos. 13872 13873The obtained VMAF score is printed through the logging system. 13874 13875It requires Netflix's vmaf library (libvmaf) as a pre-requisite. 13876After installing the library it can be enabled using: 13877@code{./configure --enable-libvmaf}. 13878If no model path is specified it uses the default model: @code{vmaf_v0.6.1.pkl}. 13879 13880The filter has following options: 13881 13882@table @option 13883@item model_path 13884Set the model path which is to be used for SVM. 13885Default value: @code{"/usr/local/share/model/vmaf_v0.6.1.pkl"} 13886 13887@item log_path 13888Set the file path to be used to store logs. 13889 13890@item log_fmt 13891Set the format of the log file (csv, json or xml). 13892 13893@item enable_transform 13894This option can enable/disable the @code{score_transform} applied to the final predicted VMAF score, 13895if you have specified score_transform option in the input parameter file passed to @code{run_vmaf_training.py} 13896Default value: @code{false} 13897 13898@item phone_model 13899Invokes the phone model which will generate VMAF scores higher than in the 13900regular model, which is more suitable for laptop, TV, etc. viewing conditions. 13901Default value: @code{false} 13902 13903@item psnr 13904Enables computing psnr along with vmaf. 13905Default value: @code{false} 13906 13907@item ssim 13908Enables computing ssim along with vmaf. 13909Default value: @code{false} 13910 13911@item ms_ssim 13912Enables computing ms_ssim along with vmaf. 13913Default value: @code{false} 13914 13915@item pool 13916Set the pool method to be used for computing vmaf. 13917Options are @code{min}, @code{harmonic_mean} or @code{mean} (default). 13918 13919@item n_threads 13920Set number of threads to be used when computing vmaf. 13921Default value: @code{0}, which makes use of all available logical processors. 13922 13923@item n_subsample 13924Set interval for frame subsampling used when computing vmaf. 13925Default value: @code{1} 13926 13927@item enable_conf_interval 13928Enables confidence interval. 13929Default value: @code{false} 13930@end table 13931 13932This filter also supports the @ref{framesync} options. 13933 13934@subsection Examples 13935@itemize 13936@item 13937On the below examples the input file @file{main.mpg} being processed is 13938compared with the reference file @file{ref.mpg}. 13939 13940@example 13941ffmpeg -i main.mpg -i ref.mpg -lavfi libvmaf -f null - 13942@end example 13943 13944@item 13945Example with options: 13946@example 13947ffmpeg -i main.mpg -i ref.mpg -lavfi libvmaf="psnr=1:log_fmt=json" -f null - 13948@end example 13949 13950@item 13951Example with options and different containers: 13952@example 13953ffmpeg -i main.mpg -i ref.mkv -lavfi "[0:v]settb=AVTB,setpts=PTS-STARTPTS[main];[1:v]settb=AVTB,setpts=PTS-STARTPTS[ref];[main][ref]libvmaf=psnr=1:log_fmt=json" -f null - 13954@end example 13955@end itemize 13956 13957@section limiter 13958 13959Limits the pixel components values to the specified range [min, max]. 13960 13961The filter accepts the following options: 13962 13963@table @option 13964@item min 13965Lower bound. Defaults to the lowest allowed value for the input. 13966 13967@item max 13968Upper bound. Defaults to the highest allowed value for the input. 13969 13970@item planes 13971Specify which planes will be processed. Defaults to all available. 13972@end table 13973 13974@subsection Commands 13975 13976This filter supports the all above options as @ref{commands}. 13977 13978@section loop 13979 13980Loop video frames. 13981 13982The filter accepts the following options: 13983 13984@table @option 13985@item loop 13986Set the number of loops. Setting this value to -1 will result in infinite loops. 13987Default is 0. 13988 13989@item size 13990Set maximal size in number of frames. Default is 0. 13991 13992@item start 13993Set first frame of loop. Default is 0. 13994@end table 13995 13996@subsection Examples 13997 13998@itemize 13999@item 14000Loop single first frame infinitely: 14001@example 14002loop=loop=-1:size=1:start=0 14003@end example 14004 14005@item 14006Loop single first frame 10 times: 14007@example 14008loop=loop=10:size=1:start=0 14009@end example 14010 14011@item 14012Loop 10 first frames 5 times: 14013@example 14014loop=loop=5:size=10:start=0 14015@end example 14016@end itemize 14017 14018@section lut1d 14019 14020Apply a 1D LUT to an input video. 14021 14022The filter accepts the following options: 14023 14024@table @option 14025@item file 14026Set the 1D LUT file name. 14027 14028Currently supported formats: 14029@table @samp 14030@item cube 14031Iridas 14032@item csp 14033cineSpace 14034@end table 14035 14036@item interp 14037Select interpolation mode. 14038 14039Available values are: 14040 14041@table @samp 14042@item nearest 14043Use values from the nearest defined point. 14044@item linear 14045Interpolate values using the linear interpolation. 14046@item cosine 14047Interpolate values using the cosine interpolation. 14048@item cubic 14049Interpolate values using the cubic interpolation. 14050@item spline 14051Interpolate values using the spline interpolation. 14052@end table 14053@end table 14054 14055@subsection Commands 14056 14057This filter supports the all above options as @ref{commands}. 14058 14059@anchor{lut3d} 14060@section lut3d 14061 14062Apply a 3D LUT to an input video. 14063 14064The filter accepts the following options: 14065 14066@table @option 14067@item file 14068Set the 3D LUT file name. 14069 14070Currently supported formats: 14071@table @samp 14072@item 3dl 14073AfterEffects 14074@item cube 14075Iridas 14076@item dat 14077DaVinci 14078@item m3d 14079Pandora 14080@item csp 14081cineSpace 14082@end table 14083@item interp 14084Select interpolation mode. 14085 14086Available values are: 14087 14088@table @samp 14089@item nearest 14090Use values from the nearest defined point. 14091@item trilinear 14092Interpolate values using the 8 points defining a cube. 14093@item tetrahedral 14094Interpolate values using a tetrahedron. 14095@item pyramid 14096Interpolate values using a pyramid. 14097@item prism 14098Interpolate values using a prism. 14099@end table 14100@end table 14101 14102@subsection Commands 14103 14104This filter supports the @code{interp} option as @ref{commands}. 14105 14106@section lumakey 14107 14108Turn certain luma values into transparency. 14109 14110The filter accepts the following options: 14111 14112@table @option 14113@item threshold 14114Set the luma which will be used as base for transparency. 14115Default value is @code{0}. 14116 14117@item tolerance 14118Set the range of luma values to be keyed out. 14119Default value is @code{0.01}. 14120 14121@item softness 14122Set the range of softness. Default value is @code{0}. 14123Use this to control gradual transition from zero to full transparency. 14124@end table 14125 14126@subsection Commands 14127This filter supports same @ref{commands} as options. 14128The command accepts the same syntax of the corresponding option. 14129 14130If the specified expression is not valid, it is kept at its current 14131value. 14132 14133@section lut, lutrgb, lutyuv 14134 14135Compute a look-up table for binding each pixel component input value 14136to an output value, and apply it to the input video. 14137 14138@var{lutyuv} applies a lookup table to a YUV input video, @var{lutrgb} 14139to an RGB input video. 14140 14141These filters accept the following parameters: 14142@table @option 14143@item c0 14144set first pixel component expression 14145@item c1 14146set second pixel component expression 14147@item c2 14148set third pixel component expression 14149@item c3 14150set fourth pixel component expression, corresponds to the alpha component 14151 14152@item r 14153set red component expression 14154@item g 14155set green component expression 14156@item b 14157set blue component expression 14158@item a 14159alpha component expression 14160 14161@item y 14162set Y/luminance component expression 14163@item u 14164set U/Cb component expression 14165@item v 14166set V/Cr component expression 14167@end table 14168 14169Each of them specifies the expression to use for computing the lookup table for 14170the corresponding pixel component values. 14171 14172The exact component associated to each of the @var{c*} options depends on the 14173format in input. 14174 14175The @var{lut} filter requires either YUV or RGB pixel formats in input, 14176@var{lutrgb} requires RGB pixel formats in input, and @var{lutyuv} requires YUV. 14177 14178The expressions can contain the following constants and functions: 14179 14180@table @option 14181@item w 14182@item h 14183The input width and height. 14184 14185@item val 14186The input value for the pixel component. 14187 14188@item clipval 14189The input value, clipped to the @var{minval}-@var{maxval} range. 14190 14191@item maxval 14192The maximum value for the pixel component. 14193 14194@item minval 14195The minimum value for the pixel component. 14196 14197@item negval 14198The negated value for the pixel component value, clipped to the 14199@var{minval}-@var{maxval} range; it corresponds to the expression 14200"maxval-clipval+minval". 14201 14202@item clip(val) 14203The computed value in @var{val}, clipped to the 14204@var{minval}-@var{maxval} range. 14205 14206@item gammaval(gamma) 14207The computed gamma correction value of the pixel component value, 14208clipped to the @var{minval}-@var{maxval} range. It corresponds to the 14209expression 14210"pow((clipval-minval)/(maxval-minval)\,@var{gamma})*(maxval-minval)+minval" 14211 14212@end table 14213 14214All expressions default to "val". 14215 14216@subsection Commands 14217 14218This filter supports same @ref{commands} as options. 14219 14220@subsection Examples 14221 14222@itemize 14223@item 14224Negate input video: 14225@example 14226lutrgb="r=maxval+minval-val:g=maxval+minval-val:b=maxval+minval-val" 14227lutyuv="y=maxval+minval-val:u=maxval+minval-val:v=maxval+minval-val" 14228@end example 14229 14230The above is the same as: 14231@example 14232lutrgb="r=negval:g=negval:b=negval" 14233lutyuv="y=negval:u=negval:v=negval" 14234@end example 14235 14236@item 14237Negate luminance: 14238@example 14239lutyuv=y=negval 14240@end example 14241 14242@item 14243Remove chroma components, turning the video into a graytone image: 14244@example 14245lutyuv="u=128:v=128" 14246@end example 14247 14248@item 14249Apply a luma burning effect: 14250@example 14251lutyuv="y=2*val" 14252@end example 14253 14254@item 14255Remove green and blue components: 14256@example 14257lutrgb="g=0:b=0" 14258@end example 14259 14260@item 14261Set a constant alpha channel value on input: 14262@example 14263format=rgba,lutrgb=a="maxval-minval/2" 14264@end example 14265 14266@item 14267Correct luminance gamma by a factor of 0.5: 14268@example 14269lutyuv=y=gammaval(0.5) 14270@end example 14271 14272@item 14273Discard least significant bits of luma: 14274@example 14275lutyuv=y='bitand(val, 128+64+32)' 14276@end example 14277 14278@item 14279Technicolor like effect: 14280@example 14281lutyuv=u='(val-maxval/2)*2+maxval/2':v='(val-maxval/2)*2+maxval/2' 14282@end example 14283@end itemize 14284 14285@section lut2, tlut2 14286 14287The @code{lut2} filter takes two input streams and outputs one 14288stream. 14289 14290The @code{tlut2} (time lut2) filter takes two consecutive frames 14291from one single stream. 14292 14293This filter accepts the following parameters: 14294@table @option 14295@item c0 14296set first pixel component expression 14297@item c1 14298set second pixel component expression 14299@item c2 14300set third pixel component expression 14301@item c3 14302set fourth pixel component expression, corresponds to the alpha component 14303 14304@item d 14305set output bit depth, only available for @code{lut2} filter. By default is 0, 14306which means bit depth is automatically picked from first input format. 14307@end table 14308 14309The @code{lut2} filter also supports the @ref{framesync} options. 14310 14311Each of them specifies the expression to use for computing the lookup table for 14312the corresponding pixel component values. 14313 14314The exact component associated to each of the @var{c*} options depends on the 14315format in inputs. 14316 14317The expressions can contain the following constants: 14318 14319@table @option 14320@item w 14321@item h 14322The input width and height. 14323 14324@item x 14325The first input value for the pixel component. 14326 14327@item y 14328The second input value for the pixel component. 14329 14330@item bdx 14331The first input video bit depth. 14332 14333@item bdy 14334The second input video bit depth. 14335@end table 14336 14337All expressions default to "x". 14338 14339@subsection Commands 14340 14341This filter supports the all above options as @ref{commands} except option @code{d}. 14342 14343@subsection Examples 14344 14345@itemize 14346@item 14347Highlight differences between two RGB video streams: 14348@example 14349lut2='ifnot(x-y,0,pow(2,bdx)-1):ifnot(x-y,0,pow(2,bdx)-1):ifnot(x-y,0,pow(2,bdx)-1)' 14350@end example 14351 14352@item 14353Highlight differences between two YUV video streams: 14354@example 14355lut2='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)' 14356@end example 14357 14358@item 14359Show max difference between two video streams: 14360@example 14361lut2='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)))' 14362@end example 14363@end itemize 14364 14365@section maskedclamp 14366 14367Clamp the first input stream with the second input and third input stream. 14368 14369Returns the value of first stream to be between second input 14370stream - @code{undershoot} and third input stream + @code{overshoot}. 14371 14372This filter accepts the following options: 14373@table @option 14374@item undershoot 14375Default value is @code{0}. 14376 14377@item overshoot 14378Default value is @code{0}. 14379 14380@item planes 14381Set which planes will be processed as bitmap, unprocessed planes will be 14382copied from first stream. 14383By default value 0xf, all planes will be processed. 14384@end table 14385 14386@subsection Commands 14387 14388This filter supports the all above options as @ref{commands}. 14389 14390@section maskedmax 14391 14392Merge the second and third input stream into output stream using absolute differences 14393between second input stream and first input stream and absolute difference between 14394third input stream and first input stream. The picked value will be from second input 14395stream if second absolute difference is greater than first one or from third input stream 14396otherwise. 14397 14398This filter accepts the following options: 14399@table @option 14400@item planes 14401Set which planes will be processed as bitmap, unprocessed planes will be 14402copied from first stream. 14403By default value 0xf, all planes will be processed. 14404@end table 14405 14406@subsection Commands 14407 14408This filter supports the all above options as @ref{commands}. 14409 14410@section maskedmerge 14411 14412Merge the first input stream with the second input stream using per pixel 14413weights in the third input stream. 14414 14415A value of 0 in the third stream pixel component means that pixel component 14416from first stream is returned unchanged, while maximum value (eg. 255 for 144178-bit videos) means that pixel component from second stream is returned 14418unchanged. Intermediate values define the amount of merging between both 14419input stream's pixel components. 14420 14421This filter accepts the following options: 14422@table @option 14423@item planes 14424Set which planes will be processed as bitmap, unprocessed planes will be 14425copied from first stream. 14426By default value 0xf, all planes will be processed. 14427@end table 14428 14429@subsection Commands 14430 14431This filter supports the all above options as @ref{commands}. 14432 14433@section maskedmin 14434 14435Merge the second and third input stream into output stream using absolute differences 14436between second input stream and first input stream and absolute difference between 14437third input stream and first input stream. The picked value will be from second input 14438stream if second absolute difference is less than first one or from third input stream 14439otherwise. 14440 14441This filter accepts the following options: 14442@table @option 14443@item planes 14444Set which planes will be processed as bitmap, unprocessed planes will be 14445copied from first stream. 14446By default value 0xf, all planes will be processed. 14447@end table 14448 14449@subsection Commands 14450 14451This filter supports the all above options as @ref{commands}. 14452 14453@section maskedthreshold 14454Pick pixels comparing absolute difference of two video streams with fixed 14455threshold. 14456 14457If absolute difference between pixel component of first and second video 14458stream is equal or lower than user supplied threshold than pixel component 14459from first video stream is picked, otherwise pixel component from second 14460video stream is picked. 14461 14462This filter accepts the following options: 14463@table @option 14464@item threshold 14465Set threshold used when picking pixels from absolute difference from two input 14466video streams. 14467 14468@item planes 14469Set which planes will be processed as bitmap, unprocessed planes will be 14470copied from second stream. 14471By default value 0xf, all planes will be processed. 14472@end table 14473 14474@subsection Commands 14475 14476This filter supports the all above options as @ref{commands}. 14477 14478@section maskfun 14479Create mask from input video. 14480 14481For example it is useful to create motion masks after @code{tblend} filter. 14482 14483This filter accepts the following options: 14484 14485@table @option 14486@item low 14487Set low threshold. Any pixel component lower or exact than this value will be set to 0. 14488 14489@item high 14490Set high threshold. Any pixel component higher than this value will be set to max value 14491allowed for current pixel format. 14492 14493@item planes 14494Set planes to filter, by default all available planes are filtered. 14495 14496@item fill 14497Fill all frame pixels with this value. 14498 14499@item sum 14500Set max average pixel value for frame. If sum of all pixel components is higher that this 14501average, output frame will be completely filled with value set by @var{fill} option. 14502Typically useful for scene changes when used in combination with @code{tblend} filter. 14503@end table 14504 14505@subsection Commands 14506 14507This filter supports the all above options as @ref{commands}. 14508 14509@section mcdeint 14510 14511Apply motion-compensation deinterlacing. 14512 14513It needs one field per frame as input and must thus be used together 14514with yadif=1/3 or equivalent. 14515 14516This filter accepts the following options: 14517@table @option 14518@item mode 14519Set the deinterlacing mode. 14520 14521It accepts one of the following values: 14522@table @samp 14523@item fast 14524@item medium 14525@item slow 14526use iterative motion estimation 14527@item extra_slow 14528like @samp{slow}, but use multiple reference frames. 14529@end table 14530Default value is @samp{fast}. 14531 14532@item parity 14533Set the picture field parity assumed for the input video. It must be 14534one of the following values: 14535 14536@table @samp 14537@item 0, tff 14538assume top field first 14539@item 1, bff 14540assume bottom field first 14541@end table 14542 14543Default value is @samp{bff}. 14544 14545@item qp 14546Set per-block quantization parameter (QP) used by the internal 14547encoder. 14548 14549Higher values should result in a smoother motion vector field but less 14550optimal individual vectors. Default value is 1. 14551@end table 14552 14553@section median 14554 14555Pick median pixel from certain rectangle defined by radius. 14556 14557This filter accepts the following options: 14558 14559@table @option 14560@item radius 14561Set horizontal radius size. Default value is @code{1}. 14562Allowed range is integer from 1 to 127. 14563 14564@item planes 14565Set which planes to process. Default is @code{15}, which is all available planes. 14566 14567@item radiusV 14568Set vertical radius size. Default value is @code{0}. 14569Allowed range is integer from 0 to 127. 14570If it is 0, value will be picked from horizontal @code{radius} option. 14571 14572@item percentile 14573Set median percentile. Default value is @code{0.5}. 14574Default value of @code{0.5} will pick always median values, while @code{0} will pick 14575minimum values, and @code{1} maximum values. 14576@end table 14577 14578@subsection Commands 14579This filter supports same @ref{commands} as options. 14580The command accepts the same syntax of the corresponding option. 14581 14582If the specified expression is not valid, it is kept at its current 14583value. 14584 14585@section mergeplanes 14586 14587Merge color channel components from several video streams. 14588 14589The filter accepts up to 4 input streams, and merge selected input 14590planes to the output video. 14591 14592This filter accepts the following options: 14593@table @option 14594@item mapping 14595Set input to output plane mapping. Default is @code{0}. 14596 14597The mappings is specified as a bitmap. It should be specified as a 14598hexadecimal number in the form 0xAa[Bb[Cc[Dd]]]. 'Aa' describes the 14599mapping for the first plane of the output stream. 'A' sets the number of 14600the input stream to use (from 0 to 3), and 'a' the plane number of the 14601corresponding input to use (from 0 to 3). The rest of the mappings is 14602similar, 'Bb' describes the mapping for the output stream second 14603plane, 'Cc' describes the mapping for the output stream third plane and 14604'Dd' describes the mapping for the output stream fourth plane. 14605 14606@item format 14607Set output pixel format. Default is @code{yuva444p}. 14608@end table 14609 14610@subsection Examples 14611 14612@itemize 14613@item 14614Merge three gray video streams of same width and height into single video stream: 14615@example 14616[a0][a1][a2]mergeplanes=0x001020:yuv444p 14617@end example 14618 14619@item 14620Merge 1st yuv444p stream and 2nd gray video stream into yuva444p video stream: 14621@example 14622[a0][a1]mergeplanes=0x00010210:yuva444p 14623@end example 14624 14625@item 14626Swap Y and A plane in yuva444p stream: 14627@example 14628format=yuva444p,mergeplanes=0x03010200:yuva444p 14629@end example 14630 14631@item 14632Swap U and V plane in yuv420p stream: 14633@example 14634format=yuv420p,mergeplanes=0x000201:yuv420p 14635@end example 14636 14637@item 14638Cast a rgb24 clip to yuv444p: 14639@example 14640format=rgb24,mergeplanes=0x000102:yuv444p 14641@end example 14642@end itemize 14643 14644@section mestimate 14645 14646Estimate and export motion vectors using block matching algorithms. 14647Motion vectors are stored in frame side data to be used by other filters. 14648 14649This filter accepts the following options: 14650@table @option 14651@item method 14652Specify the motion estimation method. Accepts one of the following values: 14653 14654@table @samp 14655@item esa 14656Exhaustive search algorithm. 14657@item tss 14658Three step search algorithm. 14659@item tdls 14660Two dimensional logarithmic search algorithm. 14661@item ntss 14662New three step search algorithm. 14663@item fss 14664Four step search algorithm. 14665@item ds 14666Diamond search algorithm. 14667@item hexbs 14668Hexagon-based search algorithm. 14669@item epzs 14670Enhanced predictive zonal search algorithm. 14671@item umh 14672Uneven multi-hexagon search algorithm. 14673@end table 14674Default value is @samp{esa}. 14675 14676@item mb_size 14677Macroblock size. Default @code{16}. 14678 14679@item search_param 14680Search parameter. Default @code{7}. 14681@end table 14682 14683@section midequalizer 14684 14685Apply Midway Image Equalization effect using two video streams. 14686 14687Midway Image Equalization adjusts a pair of images to have the same 14688histogram, while maintaining their dynamics as much as possible. It's 14689useful for e.g. matching exposures from a pair of stereo cameras. 14690 14691This filter has two inputs and one output, which must be of same pixel format, but 14692may be of different sizes. The output of filter is first input adjusted with 14693midway histogram of both inputs. 14694 14695This filter accepts the following option: 14696 14697@table @option 14698@item planes 14699Set which planes to process. Default is @code{15}, which is all available planes. 14700@end table 14701 14702@section minterpolate 14703 14704Convert the video to specified frame rate using motion interpolation. 14705 14706This filter accepts the following options: 14707@table @option 14708@item fps 14709Specify 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}. 14710 14711@item mi_mode 14712Motion interpolation mode. Following values are accepted: 14713@table @samp 14714@item dup 14715Duplicate previous or next frame for interpolating new ones. 14716@item blend 14717Blend source frames. Interpolated frame is mean of previous and next frames. 14718@item mci 14719Motion compensated interpolation. Following options are effective when this mode is selected: 14720 14721@table @samp 14722@item mc_mode 14723Motion compensation mode. Following values are accepted: 14724@table @samp 14725@item obmc 14726Overlapped block motion compensation. 14727@item aobmc 14728Adaptive overlapped block motion compensation. Window weighting coefficients are controlled adaptively according to the reliabilities of the neighboring motion vectors to reduce oversmoothing. 14729@end table 14730Default mode is @samp{obmc}. 14731 14732@item me_mode 14733Motion estimation mode. Following values are accepted: 14734@table @samp 14735@item bidir 14736Bidirectional motion estimation. Motion vectors are estimated for each source frame in both forward and backward directions. 14737@item bilat 14738Bilateral motion estimation. Motion vectors are estimated directly for interpolated frame. 14739@end table 14740Default mode is @samp{bilat}. 14741 14742@item me 14743The algorithm to be used for motion estimation. Following values are accepted: 14744@table @samp 14745@item esa 14746Exhaustive search algorithm. 14747@item tss 14748Three step search algorithm. 14749@item tdls 14750Two dimensional logarithmic search algorithm. 14751@item ntss 14752New three step search algorithm. 14753@item fss 14754Four step search algorithm. 14755@item ds 14756Diamond search algorithm. 14757@item hexbs 14758Hexagon-based search algorithm. 14759@item epzs 14760Enhanced predictive zonal search algorithm. 14761@item umh 14762Uneven multi-hexagon search algorithm. 14763@end table 14764Default algorithm is @samp{epzs}. 14765 14766@item mb_size 14767Macroblock size. Default @code{16}. 14768 14769@item search_param 14770Motion estimation search parameter. Default @code{32}. 14771 14772@item vsbmc 14773Enable 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). 14774@end table 14775@end table 14776 14777@item scd 14778Scene 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: 14779@table @samp 14780@item none 14781Disable scene change detection. 14782@item fdiff 14783Frame difference. Corresponding pixel values are compared and if it satisfies @var{scd_threshold} scene change is detected. 14784@end table 14785Default method is @samp{fdiff}. 14786 14787@item scd_threshold 14788Scene change detection threshold. Default is @code{10.}. 14789@end table 14790 14791@section mix 14792 14793Mix several video input streams into one video stream. 14794 14795A description of the accepted options follows. 14796 14797@table @option 14798@item nb_inputs 14799The number of inputs. If unspecified, it defaults to 2. 14800 14801@item weights 14802Specify weight of each input video stream as sequence. 14803Each weight is separated by space. If number of weights 14804is smaller than number of @var{frames} last specified 14805weight will be used for all remaining unset weights. 14806 14807@item scale 14808Specify scale, if it is set it will be multiplied with sum 14809of each weight multiplied with pixel values to give final destination 14810pixel value. By default @var{scale} is auto scaled to sum of weights. 14811 14812@item duration 14813Specify how end of stream is determined. 14814@table @samp 14815@item longest 14816The duration of the longest input. (default) 14817 14818@item shortest 14819The duration of the shortest input. 14820 14821@item first 14822The duration of the first input. 14823@end table 14824@end table 14825 14826@subsection Commands 14827 14828This filter supports the following commands: 14829@table @option 14830@item weights 14831@item scale 14832Syntax is same as option with same name. 14833@end table 14834 14835@section monochrome 14836Convert video to gray using custom color filter. 14837 14838A description of the accepted options follows. 14839 14840@table @option 14841@item cb 14842Set the chroma blue spot. Allowed range is from -1 to 1. 14843Default value is 0. 14844 14845@item cr 14846Set the chroma red spot. Allowed range is from -1 to 1. 14847Default value is 0. 14848 14849@item size 14850Set the color filter size. Allowed range is from .1 to 10. 14851Default value is 1. 14852 14853@item high 14854Set the highlights strength. Allowed range is from 0 to 1. 14855Default value is 0. 14856@end table 14857 14858@subsection Commands 14859 14860This filter supports the all above options as @ref{commands}. 14861 14862@section mpdecimate 14863 14864Drop frames that do not differ greatly from the previous frame in 14865order to reduce frame rate. 14866 14867The main use of this filter is for very-low-bitrate encoding 14868(e.g. streaming over dialup modem), but it could in theory be used for 14869fixing movies that were inverse-telecined incorrectly. 14870 14871A description of the accepted options follows. 14872 14873@table @option 14874@item max 14875Set the maximum number of consecutive frames which can be dropped (if 14876positive), or the minimum interval between dropped frames (if 14877negative). If the value is 0, the frame is dropped disregarding the 14878number of previous sequentially dropped frames. 14879 14880Default value is 0. 14881 14882@item hi 14883@item lo 14884@item frac 14885Set the dropping threshold values. 14886 14887Values for @option{hi} and @option{lo} are for 8x8 pixel blocks and 14888represent actual pixel value differences, so a threshold of 64 14889corresponds to 1 unit of difference for each pixel, or the same spread 14890out differently over the block. 14891 14892A frame is a candidate for dropping if no 8x8 blocks differ by more 14893than a threshold of @option{hi}, and if no more than @option{frac} blocks (1 14894meaning the whole image) differ by more than a threshold of @option{lo}. 14895 14896Default value for @option{hi} is 64*12, default value for @option{lo} is 1489764*5, and default value for @option{frac} is 0.33. 14898@end table 14899 14900@section msad 14901 14902Obtain the MSAD (Mean Sum of Absolute Differences) between two input videos. 14903 14904This filter takes two input videos. 14905 14906Both input videos must have the same resolution and pixel format for 14907this filter to work correctly. Also it assumes that both inputs 14908have the same number of frames, which are compared one by one. 14909 14910The obtained per component, average, min and max MSAD is printed through 14911the logging system. 14912 14913The filter stores the calculated MSAD of each frame in frame metadata. 14914 14915In the below example the input file @file{main.mpg} being processed is compared 14916with the reference file @file{ref.mpg}. 14917 14918@example 14919ffmpeg -i main.mpg -i ref.mpg -lavfi msad -f null - 14920@end example 14921 14922@section negate 14923 14924Negate (invert) the input video. 14925 14926It accepts the following option: 14927 14928@table @option 14929 14930@item negate_alpha 14931With value 1, it negates the alpha component, if present. Default value is 0. 14932@end table 14933 14934@subsection Commands 14935 14936This filter supports same @ref{commands} as options. 14937 14938@anchor{nlmeans} 14939@section nlmeans 14940 14941Denoise frames using Non-Local Means algorithm. 14942 14943Each pixel is adjusted by looking for other pixels with similar contexts. This 14944context similarity is defined by comparing their surrounding patches of size 14945@option{p}x@option{p}. Patches are searched in an area of @option{r}x@option{r} 14946around the pixel. 14947 14948Note that the research area defines centers for patches, which means some 14949patches will be made of pixels outside that research area. 14950 14951The filter accepts the following options. 14952 14953@table @option 14954@item s 14955Set denoising strength. Default is 1.0. Must be in range [1.0, 30.0]. 14956 14957@item p 14958Set patch size. Default is 7. Must be odd number in range [0, 99]. 14959 14960@item pc 14961Same as @option{p} but for chroma planes. 14962 14963The default value is @var{0} and means automatic. 14964 14965@item r 14966Set research size. Default is 15. Must be odd number in range [0, 99]. 14967 14968@item rc 14969Same as @option{r} but for chroma planes. 14970 14971The default value is @var{0} and means automatic. 14972@end table 14973 14974@section nnedi 14975 14976Deinterlace video using neural network edge directed interpolation. 14977 14978This filter accepts the following options: 14979 14980@table @option 14981@item weights 14982Mandatory option, without binary file filter can not work. 14983Currently file can be found here: 14984https://github.com/dubhater/vapoursynth-nnedi3/blob/master/src/nnedi3_weights.bin 14985 14986@item deint 14987Set which frames to deinterlace, by default it is @code{all}. 14988Can be @code{all} or @code{interlaced}. 14989 14990@item field 14991Set mode of operation. 14992 14993Can be one of the following: 14994 14995@table @samp 14996@item af 14997Use frame flags, both fields. 14998@item a 14999Use frame flags, single field. 15000@item t 15001Use top field only. 15002@item b 15003Use bottom field only. 15004@item tf 15005Use both fields, top first. 15006@item bf 15007Use both fields, bottom first. 15008@end table 15009 15010@item planes 15011Set which planes to process, by default filter process all frames. 15012 15013@item nsize 15014Set size of local neighborhood around each pixel, used by the predictor neural 15015network. 15016 15017Can be one of the following: 15018 15019@table @samp 15020@item s8x6 15021@item s16x6 15022@item s32x6 15023@item s48x6 15024@item s8x4 15025@item s16x4 15026@item s32x4 15027@end table 15028 15029@item nns 15030Set the number of neurons in predictor neural network. 15031Can be one of the following: 15032 15033@table @samp 15034@item n16 15035@item n32 15036@item n64 15037@item n128 15038@item n256 15039@end table 15040 15041@item qual 15042Controls the number of different neural network predictions that are blended 15043together to compute the final output value. Can be @code{fast}, default or 15044@code{slow}. 15045 15046@item etype 15047Set which set of weights to use in the predictor. 15048Can be one of the following: 15049 15050@table @samp 15051@item a, abs 15052weights trained to minimize absolute error 15053@item s, mse 15054weights trained to minimize squared error 15055@end table 15056 15057@item pscrn 15058Controls whether or not the prescreener neural network is used to decide 15059which pixels should be processed by the predictor neural network and which 15060can be handled by simple cubic interpolation. 15061The prescreener is trained to know whether cubic interpolation will be 15062sufficient for a pixel or whether it should be predicted by the predictor nn. 15063The computational complexity of the prescreener nn is much less than that of 15064the predictor nn. Since most pixels can be handled by cubic interpolation, 15065using the prescreener generally results in much faster processing. 15066The prescreener is pretty accurate, so the difference between using it and not 15067using it is almost always unnoticeable. 15068 15069Can be one of the following: 15070 15071@table @samp 15072@item none 15073@item original 15074@item new 15075@item new2 15076@item new3 15077@end table 15078 15079Default is @code{new}. 15080@end table 15081 15082@subsection Commands 15083This filter supports same @ref{commands} as options, excluding @var{weights} option. 15084 15085@section noformat 15086 15087Force libavfilter not to use any of the specified pixel formats for the 15088input to the next filter. 15089 15090It accepts the following parameters: 15091@table @option 15092 15093@item pix_fmts 15094A '|'-separated list of pixel format names, such as 15095pix_fmts=yuv420p|monow|rgb24". 15096 15097@end table 15098 15099@subsection Examples 15100 15101@itemize 15102@item 15103Force libavfilter to use a format different from @var{yuv420p} for the 15104input to the vflip filter: 15105@example 15106noformat=pix_fmts=yuv420p,vflip 15107@end example 15108 15109@item 15110Convert the input video to any of the formats not contained in the list: 15111@example 15112noformat=yuv420p|yuv444p|yuv410p 15113@end example 15114@end itemize 15115 15116@section noise 15117 15118Add noise on video input frame. 15119 15120The filter accepts the following options: 15121 15122@table @option 15123@item all_seed 15124@item c0_seed 15125@item c1_seed 15126@item c2_seed 15127@item c3_seed 15128Set noise seed for specific pixel component or all pixel components in case 15129of @var{all_seed}. Default value is @code{123457}. 15130 15131@item all_strength, alls 15132@item c0_strength, c0s 15133@item c1_strength, c1s 15134@item c2_strength, c2s 15135@item c3_strength, c3s 15136Set noise strength for specific pixel component or all pixel components in case 15137@var{all_strength}. Default value is @code{0}. Allowed range is [0, 100]. 15138 15139@item all_flags, allf 15140@item c0_flags, c0f 15141@item c1_flags, c1f 15142@item c2_flags, c2f 15143@item c3_flags, c3f 15144Set pixel component flags or set flags for all components if @var{all_flags}. 15145Available values for component flags are: 15146@table @samp 15147@item a 15148averaged temporal noise (smoother) 15149@item p 15150mix random noise with a (semi)regular pattern 15151@item t 15152temporal noise (noise pattern changes between frames) 15153@item u 15154uniform noise (gaussian otherwise) 15155@end table 15156@end table 15157 15158@subsection Examples 15159 15160Add temporal and uniform noise to input video: 15161@example 15162noise=alls=20:allf=t+u 15163@end example 15164 15165@section normalize 15166 15167Normalize RGB video (aka histogram stretching, contrast stretching). 15168See: https://en.wikipedia.org/wiki/Normalization_(image_processing) 15169 15170For each channel of each frame, the filter computes the input range and maps 15171it linearly to the user-specified output range. The output range defaults 15172to the full dynamic range from pure black to pure white. 15173 15174Temporal smoothing can be used on the input range to reduce flickering (rapid 15175changes in brightness) caused when small dark or bright objects enter or leave 15176the scene. This is similar to the auto-exposure (automatic gain control) on a 15177video camera, and, like a video camera, it may cause a period of over- or 15178under-exposure of the video. 15179 15180The R,G,B channels can be normalized independently, which may cause some 15181color shifting, or linked together as a single channel, which prevents 15182color shifting. Linked normalization preserves hue. Independent normalization 15183does not, so it can be used to remove some color casts. Independent and linked 15184normalization can be combined in any ratio. 15185 15186The normalize filter accepts the following options: 15187 15188@table @option 15189@item blackpt 15190@item whitept 15191Colors which define the output range. The minimum input value is mapped to 15192the @var{blackpt}. The maximum input value is mapped to the @var{whitept}. 15193The defaults are black and white respectively. Specifying white for 15194@var{blackpt} and black for @var{whitept} will give color-inverted, 15195normalized video. Shades of grey can be used to reduce the dynamic range 15196(contrast). Specifying saturated colors here can create some interesting 15197effects. 15198 15199@item smoothing 15200The number of previous frames to use for temporal smoothing. The input range 15201of each channel is smoothed using a rolling average over the current frame 15202and the @var{smoothing} previous frames. The default is 0 (no temporal 15203smoothing). 15204 15205@item independence 15206Controls the ratio of independent (color shifting) channel normalization to 15207linked (color preserving) normalization. 0.0 is fully linked, 1.0 is fully 15208independent. Defaults to 1.0 (fully independent). 15209 15210@item strength 15211Overall strength of the filter. 1.0 is full strength. 0.0 is a rather 15212expensive no-op. Defaults to 1.0 (full strength). 15213 15214@end table 15215 15216@subsection Commands 15217This filter supports same @ref{commands} as options, excluding @var{smoothing} option. 15218The command accepts the same syntax of the corresponding option. 15219 15220If the specified expression is not valid, it is kept at its current 15221value. 15222 15223@subsection Examples 15224 15225Stretch video contrast to use the full dynamic range, with no temporal 15226smoothing; may flicker depending on the source content: 15227@example 15228normalize=blackpt=black:whitept=white:smoothing=0 15229@end example 15230 15231As above, but with 50 frames of temporal smoothing; flicker should be 15232reduced, depending on the source content: 15233@example 15234normalize=blackpt=black:whitept=white:smoothing=50 15235@end example 15236 15237As above, but with hue-preserving linked channel normalization: 15238@example 15239normalize=blackpt=black:whitept=white:smoothing=50:independence=0 15240@end example 15241 15242As above, but with half strength: 15243@example 15244normalize=blackpt=black:whitept=white:smoothing=50:independence=0:strength=0.5 15245@end example 15246 15247Map the darkest input color to red, the brightest input color to cyan: 15248@example 15249normalize=blackpt=red:whitept=cyan 15250@end example 15251 15252@section null 15253 15254Pass the video source unchanged to the output. 15255 15256@section ocr 15257Optical Character Recognition 15258 15259This filter uses Tesseract for optical character recognition. To enable 15260compilation of this filter, you need to configure FFmpeg with 15261@code{--enable-libtesseract}. 15262 15263It accepts the following options: 15264 15265@table @option 15266@item datapath 15267Set datapath to tesseract data. Default is to use whatever was 15268set at installation. 15269 15270@item language 15271Set language, default is "eng". 15272 15273@item whitelist 15274Set character whitelist. 15275 15276@item blacklist 15277Set character blacklist. 15278@end table 15279 15280The filter exports recognized text as the frame metadata @code{lavfi.ocr.text}. 15281The filter exports confidence of recognized words as the frame metadata @code{lavfi.ocr.confidence}. 15282 15283@section ocv 15284 15285Apply a video transform using libopencv. 15286 15287To enable this filter, install the libopencv library and headers and 15288configure FFmpeg with @code{--enable-libopencv}. 15289 15290It accepts the following parameters: 15291 15292@table @option 15293 15294@item filter_name 15295The name of the libopencv filter to apply. 15296 15297@item filter_params 15298The parameters to pass to the libopencv filter. If not specified, the default 15299values are assumed. 15300 15301@end table 15302 15303Refer to the official libopencv documentation for more precise 15304information: 15305@url{http://docs.opencv.org/master/modules/imgproc/doc/filtering.html} 15306 15307Several libopencv filters are supported; see the following subsections. 15308 15309@anchor{dilate} 15310@subsection dilate 15311 15312Dilate an image by using a specific structuring element. 15313It corresponds to the libopencv function @code{cvDilate}. 15314 15315It accepts the parameters: @var{struct_el}|@var{nb_iterations}. 15316 15317@var{struct_el} represents a structuring element, and has the syntax: 15318@var{cols}x@var{rows}+@var{anchor_x}x@var{anchor_y}/@var{shape} 15319 15320@var{cols} and @var{rows} represent the number of columns and rows of 15321the structuring element, @var{anchor_x} and @var{anchor_y} the anchor 15322point, and @var{shape} the shape for the structuring element. @var{shape} 15323must be "rect", "cross", "ellipse", or "custom". 15324 15325If the value for @var{shape} is "custom", it must be followed by a 15326string of the form "=@var{filename}". The file with name 15327@var{filename} is assumed to represent a binary image, with each 15328printable character corresponding to a bright pixel. When a custom 15329@var{shape} is used, @var{cols} and @var{rows} are ignored, the number 15330or columns and rows of the read file are assumed instead. 15331 15332The default value for @var{struct_el} is "3x3+0x0/rect". 15333 15334@var{nb_iterations} specifies the number of times the transform is 15335applied to the image, and defaults to 1. 15336 15337Some examples: 15338@example 15339# Use the default values 15340ocv=dilate 15341 15342# Dilate using a structuring element with a 5x5 cross, iterating two times 15343ocv=filter_name=dilate:filter_params=5x5+2x2/cross|2 15344 15345# Read the shape from the file diamond.shape, iterating two times. 15346# The file diamond.shape may contain a pattern of characters like this 15347# * 15348# *** 15349# ***** 15350# *** 15351# * 15352# The specified columns and rows are ignored 15353# but the anchor point coordinates are not 15354ocv=dilate:0x0+2x2/custom=diamond.shape|2 15355@end example 15356 15357@subsection erode 15358 15359Erode an image by using a specific structuring element. 15360It corresponds to the libopencv function @code{cvErode}. 15361 15362It accepts the parameters: @var{struct_el}:@var{nb_iterations}, 15363with the same syntax and semantics as the @ref{dilate} filter. 15364 15365@subsection smooth 15366 15367Smooth the input video. 15368 15369The filter takes the following parameters: 15370@var{type}|@var{param1}|@var{param2}|@var{param3}|@var{param4}. 15371 15372@var{type} is the type of smooth filter to apply, and must be one of 15373the following values: "blur", "blur_no_scale", "median", "gaussian", 15374or "bilateral". The default value is "gaussian". 15375 15376The meaning of @var{param1}, @var{param2}, @var{param3}, and @var{param4} 15377depends on the smooth type. @var{param1} and 15378@var{param2} accept integer positive values or 0. @var{param3} and 15379@var{param4} accept floating point values. 15380 15381The default value for @var{param1} is 3. The default value for the 15382other parameters is 0. 15383 15384These parameters correspond to the parameters assigned to the 15385libopencv function @code{cvSmooth}. 15386 15387@section oscilloscope 15388 153892D Video Oscilloscope. 15390 15391Useful to measure spatial impulse, step responses, chroma delays, etc. 15392 15393It accepts the following parameters: 15394 15395@table @option 15396@item x 15397Set scope center x position. 15398 15399@item y 15400Set scope center y position. 15401 15402@item s 15403Set scope size, relative to frame diagonal. 15404 15405@item t 15406Set scope tilt/rotation. 15407 15408@item o 15409Set trace opacity. 15410 15411@item tx 15412Set trace center x position. 15413 15414@item ty 15415Set trace center y position. 15416 15417@item tw 15418Set trace width, relative to width of frame. 15419 15420@item th 15421Set trace height, relative to height of frame. 15422 15423@item c 15424Set which components to trace. By default it traces first three components. 15425 15426@item g 15427Draw trace grid. By default is enabled. 15428 15429@item st 15430Draw some statistics. By default is enabled. 15431 15432@item sc 15433Draw scope. By default is enabled. 15434@end table 15435 15436@subsection Commands 15437This filter supports same @ref{commands} as options. 15438The command accepts the same syntax of the corresponding option. 15439 15440If the specified expression is not valid, it is kept at its current 15441value. 15442 15443@subsection Examples 15444 15445@itemize 15446@item 15447Inspect full first row of video frame. 15448@example 15449oscilloscope=x=0.5:y=0:s=1 15450@end example 15451 15452@item 15453Inspect full last row of video frame. 15454@example 15455oscilloscope=x=0.5:y=1:s=1 15456@end example 15457 15458@item 15459Inspect full 5th line of video frame of height 1080. 15460@example 15461oscilloscope=x=0.5:y=5/1080:s=1 15462@end example 15463 15464@item 15465Inspect full last column of video frame. 15466@example 15467oscilloscope=x=1:y=0.5:s=1:t=1 15468@end example 15469 15470@end itemize 15471 15472@anchor{overlay} 15473@section overlay 15474 15475Overlay one video on top of another. 15476 15477It takes two inputs and has one output. The first input is the "main" 15478video on which the second input is overlaid. 15479 15480It accepts the following parameters: 15481 15482A description of the accepted options follows. 15483 15484@table @option 15485@item x 15486@item y 15487Set the expression for the x and y coordinates of the overlaid video 15488on the main video. Default value is "0" for both expressions. In case 15489the expression is invalid, it is set to a huge value (meaning that the 15490overlay will not be displayed within the output visible area). 15491 15492@item eof_action 15493See @ref{framesync}. 15494 15495@item eval 15496Set when the expressions for @option{x}, and @option{y} are evaluated. 15497 15498It accepts the following values: 15499@table @samp 15500@item init 15501only evaluate expressions once during the filter initialization or 15502when a command is processed 15503 15504@item frame 15505evaluate expressions for each incoming frame 15506@end table 15507 15508Default value is @samp{frame}. 15509 15510@item shortest 15511See @ref{framesync}. 15512 15513@item format 15514Set the format for the output video. 15515 15516It accepts the following values: 15517@table @samp 15518@item yuv420 15519force YUV420 output 15520 15521@item yuv420p10 15522force YUV420p10 output 15523 15524@item yuv422 15525force YUV422 output 15526 15527@item yuv422p10 15528force YUV422p10 output 15529 15530@item yuv444 15531force YUV444 output 15532 15533@item rgb 15534force packed RGB output 15535 15536@item gbrp 15537force planar RGB output 15538 15539@item auto 15540automatically pick format 15541@end table 15542 15543Default value is @samp{yuv420}. 15544 15545@item repeatlast 15546See @ref{framesync}. 15547 15548@item alpha 15549Set format of alpha of the overlaid video, it can be @var{straight} or 15550@var{premultiplied}. Default is @var{straight}. 15551@end table 15552 15553The @option{x}, and @option{y} expressions can contain the following 15554parameters. 15555 15556@table @option 15557@item main_w, W 15558@item main_h, H 15559The main input width and height. 15560 15561@item overlay_w, w 15562@item overlay_h, h 15563The overlay input width and height. 15564 15565@item x 15566@item y 15567The computed values for @var{x} and @var{y}. They are evaluated for 15568each new frame. 15569 15570@item hsub 15571@item vsub 15572horizontal and vertical chroma subsample values of the output 15573format. For example for the pixel format "yuv422p" @var{hsub} is 2 and 15574@var{vsub} is 1. 15575 15576@item n 15577the number of input frame, starting from 0 15578 15579@item pos 15580the position in the file of the input frame, NAN if unknown 15581 15582@item t 15583The timestamp, expressed in seconds. It's NAN if the input timestamp is unknown. 15584 15585@end table 15586 15587This filter also supports the @ref{framesync} options. 15588 15589Note that the @var{n}, @var{pos}, @var{t} variables are available only 15590when evaluation is done @emph{per frame}, and will evaluate to NAN 15591when @option{eval} is set to @samp{init}. 15592 15593Be aware that frames are taken from each input video in timestamp 15594order, hence, if their initial timestamps differ, it is a good idea 15595to pass the two inputs through a @var{setpts=PTS-STARTPTS} filter to 15596have them begin in the same zero timestamp, as the example for 15597the @var{movie} filter does. 15598 15599You can chain together more overlays but you should test the 15600efficiency of such approach. 15601 15602@subsection Commands 15603 15604This filter supports the following commands: 15605@table @option 15606@item x 15607@item y 15608Modify the x and y of the overlay input. 15609The command accepts the same syntax of the corresponding option. 15610 15611If the specified expression is not valid, it is kept at its current 15612value. 15613@end table 15614 15615@subsection Examples 15616 15617@itemize 15618@item 15619Draw the overlay at 10 pixels from the bottom right corner of the main 15620video: 15621@example 15622overlay=main_w-overlay_w-10:main_h-overlay_h-10 15623@end example 15624 15625Using named options the example above becomes: 15626@example 15627overlay=x=main_w-overlay_w-10:y=main_h-overlay_h-10 15628@end example 15629 15630@item 15631Insert a transparent PNG logo in the bottom left corner of the input, 15632using the @command{ffmpeg} tool with the @code{-filter_complex} option: 15633@example 15634ffmpeg -i input -i logo -filter_complex 'overlay=10:main_h-overlay_h-10' output 15635@end example 15636 15637@item 15638Insert 2 different transparent PNG logos (second logo on bottom 15639right corner) using the @command{ffmpeg} tool: 15640@example 15641ffmpeg -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 15642@end example 15643 15644@item 15645Add a transparent color layer on top of the main video; @code{WxH} 15646must specify the size of the main input to the overlay filter: 15647@example 15648color=color=red@@.3:size=WxH [over]; [in][over] overlay [out] 15649@end example 15650 15651@item 15652Play an original video and a filtered version (here with the deshake 15653filter) side by side using the @command{ffplay} tool: 15654@example 15655ffplay input.avi -vf 'split[a][b]; [a]pad=iw*2:ih[src]; [b]deshake[filt]; [src][filt]overlay=w' 15656@end example 15657 15658The above command is the same as: 15659@example 15660ffplay input.avi -vf 'split[b], pad=iw*2[src], [b]deshake, [src]overlay=w' 15661@end example 15662 15663@item 15664Make a sliding overlay appearing from the left to the right top part of the 15665screen starting since time 2: 15666@example 15667overlay=x='if(gte(t,2), -w+(t-2)*20, NAN)':y=0 15668@end example 15669 15670@item 15671Compose output by putting two input videos side to side: 15672@example 15673ffmpeg -i left.avi -i right.avi -filter_complex " 15674nullsrc=size=200x100 [background]; 15675[0:v] setpts=PTS-STARTPTS, scale=100x100 [left]; 15676[1:v] setpts=PTS-STARTPTS, scale=100x100 [right]; 15677[background][left] overlay=shortest=1 [background+left]; 15678[background+left][right] overlay=shortest=1:x=100 [left+right] 15679" 15680@end example 15681 15682@item 15683Mask 10-20 seconds of a video by applying the delogo filter to a section 15684@example 15685ffmpeg -i test.avi -codec:v:0 wmv2 -ar 11025 -b:v 9000k 15686-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]' 15687masked.avi 15688@end example 15689 15690@item 15691Chain several overlays in cascade: 15692@example 15693nullsrc=s=200x200 [bg]; 15694testsrc=s=100x100, split=4 [in0][in1][in2][in3]; 15695[in0] lutrgb=r=0, [bg] overlay=0:0 [mid0]; 15696[in1] lutrgb=g=0, [mid0] overlay=100:0 [mid1]; 15697[in2] lutrgb=b=0, [mid1] overlay=0:100 [mid2]; 15698[in3] null, [mid2] overlay=100:100 [out0] 15699@end example 15700 15701@end itemize 15702 15703@anchor{overlay_cuda} 15704@section overlay_cuda 15705 15706Overlay one video on top of another. 15707 15708This is the CUDA variant of the @ref{overlay} filter. 15709It only accepts CUDA frames. The underlying input pixel formats have to match. 15710 15711It takes two inputs and has one output. The first input is the "main" 15712video on which the second input is overlaid. 15713 15714It accepts the following parameters: 15715 15716@table @option 15717@item x 15718@item y 15719Set the x and y coordinates of the overlaid video on the main video. 15720Default value is "0" for both expressions. 15721 15722@item eof_action 15723See @ref{framesync}. 15724 15725@item shortest 15726See @ref{framesync}. 15727 15728@item repeatlast 15729See @ref{framesync}. 15730 15731@end table 15732 15733This filter also supports the @ref{framesync} options. 15734 15735@section owdenoise 15736 15737Apply Overcomplete Wavelet denoiser. 15738 15739The filter accepts the following options: 15740 15741@table @option 15742@item depth 15743Set depth. 15744 15745Larger depth values will denoise lower frequency components more, but 15746slow down filtering. 15747 15748Must be an int in the range 8-16, default is @code{8}. 15749 15750@item luma_strength, ls 15751Set luma strength. 15752 15753Must be a double value in the range 0-1000, default is @code{1.0}. 15754 15755@item chroma_strength, cs 15756Set chroma strength. 15757 15758Must be a double value in the range 0-1000, default is @code{1.0}. 15759@end table 15760 15761@anchor{pad} 15762@section pad 15763 15764Add paddings to the input image, and place the original input at the 15765provided @var{x}, @var{y} coordinates. 15766 15767It accepts the following parameters: 15768 15769@table @option 15770@item width, w 15771@item height, h 15772Specify an expression for the size of the output image with the 15773paddings added. If the value for @var{width} or @var{height} is 0, the 15774corresponding input size is used for the output. 15775 15776The @var{width} expression can reference the value set by the 15777@var{height} expression, and vice versa. 15778 15779The default value of @var{width} and @var{height} is 0. 15780 15781@item x 15782@item y 15783Specify the offsets to place the input image at within the padded area, 15784with respect to the top/left border of the output image. 15785 15786The @var{x} expression can reference the value set by the @var{y} 15787expression, and vice versa. 15788 15789The default value of @var{x} and @var{y} is 0. 15790 15791If @var{x} or @var{y} evaluate to a negative number, they'll be changed 15792so the input image is centered on the padded area. 15793 15794@item color 15795Specify the color of the padded area. For the syntax of this option, 15796check the @ref{color syntax,,"Color" section in the ffmpeg-utils 15797manual,ffmpeg-utils}. 15798 15799The default value of @var{color} is "black". 15800 15801@item eval 15802Specify when to evaluate @var{width}, @var{height}, @var{x} and @var{y} expression. 15803 15804It accepts the following values: 15805 15806@table @samp 15807@item init 15808Only evaluate expressions once during the filter initialization or when 15809a command is processed. 15810 15811@item frame 15812Evaluate expressions for each incoming frame. 15813 15814@end table 15815 15816Default value is @samp{init}. 15817 15818@item aspect 15819Pad to aspect instead to a resolution. 15820 15821@end table 15822 15823The value for the @var{width}, @var{height}, @var{x}, and @var{y} 15824options are expressions containing the following constants: 15825 15826@table @option 15827@item in_w 15828@item in_h 15829The input video width and height. 15830 15831@item iw 15832@item ih 15833These are the same as @var{in_w} and @var{in_h}. 15834 15835@item out_w 15836@item out_h 15837The output width and height (the size of the padded area), as 15838specified by the @var{width} and @var{height} expressions. 15839 15840@item ow 15841@item oh 15842These are the same as @var{out_w} and @var{out_h}. 15843 15844@item x 15845@item y 15846The x and y offsets as specified by the @var{x} and @var{y} 15847expressions, or NAN if not yet specified. 15848 15849@item a 15850same as @var{iw} / @var{ih} 15851 15852@item sar 15853input sample aspect ratio 15854 15855@item dar 15856input display aspect ratio, it is the same as (@var{iw} / @var{ih}) * @var{sar} 15857 15858@item hsub 15859@item vsub 15860The horizontal and vertical chroma subsample values. For example for the 15861pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1. 15862@end table 15863 15864@subsection Examples 15865 15866@itemize 15867@item 15868Add paddings with the color "violet" to the input video. The output video 15869size is 640x480, and the top-left corner of the input video is placed at 15870column 0, row 40 15871@example 15872pad=640:480:0:40:violet 15873@end example 15874 15875The example above is equivalent to the following command: 15876@example 15877pad=width=640:height=480:x=0:y=40:color=violet 15878@end example 15879 15880@item 15881Pad the input to get an output with dimensions increased by 3/2, 15882and put the input video at the center of the padded area: 15883@example 15884pad="3/2*iw:3/2*ih:(ow-iw)/2:(oh-ih)/2" 15885@end example 15886 15887@item 15888Pad the input to get a squared output with size equal to the maximum 15889value between the input width and height, and put the input video at 15890the center of the padded area: 15891@example 15892pad="max(iw\,ih):ow:(ow-iw)/2:(oh-ih)/2" 15893@end example 15894 15895@item 15896Pad the input to get a final w/h ratio of 16:9: 15897@example 15898pad="ih*16/9:ih:(ow-iw)/2:(oh-ih)/2" 15899@end example 15900 15901@item 15902In case of anamorphic video, in order to set the output display aspect 15903correctly, it is necessary to use @var{sar} in the expression, 15904according to the relation: 15905@example 15906(ih * X / ih) * sar = output_dar 15907X = output_dar / sar 15908@end example 15909 15910Thus the previous example needs to be modified to: 15911@example 15912pad="ih*16/9/sar:ih:(ow-iw)/2:(oh-ih)/2" 15913@end example 15914 15915@item 15916Double the output size and put the input video in the bottom-right 15917corner of the output padded area: 15918@example 15919pad="2*iw:2*ih:ow-iw:oh-ih" 15920@end example 15921@end itemize 15922 15923@anchor{palettegen} 15924@section palettegen 15925 15926Generate one palette for a whole video stream. 15927 15928It accepts the following options: 15929 15930@table @option 15931@item max_colors 15932Set the maximum number of colors to quantize in the palette. 15933Note: the palette will still contain 256 colors; the unused palette entries 15934will be black. 15935 15936@item reserve_transparent 15937Create a palette of 255 colors maximum and reserve the last one for 15938transparency. Reserving the transparency color is useful for GIF optimization. 15939If not set, the maximum of colors in the palette will be 256. You probably want 15940to disable this option for a standalone image. 15941Set by default. 15942 15943@item transparency_color 15944Set the color that will be used as background for transparency. 15945 15946@item stats_mode 15947Set statistics mode. 15948 15949It accepts the following values: 15950@table @samp 15951@item full 15952Compute full frame histograms. 15953@item diff 15954Compute histograms only for the part that differs from previous frame. This 15955might be relevant to give more importance to the moving part of your input if 15956the background is static. 15957@item single 15958Compute new histogram for each frame. 15959@end table 15960 15961Default value is @var{full}. 15962@end table 15963 15964The filter also exports the frame metadata @code{lavfi.color_quant_ratio} 15965(@code{nb_color_in / nb_color_out}) which you can use to evaluate the degree of 15966color quantization of the palette. This information is also visible at 15967@var{info} logging level. 15968 15969@subsection Examples 15970 15971@itemize 15972@item 15973Generate a representative palette of a given video using @command{ffmpeg}: 15974@example 15975ffmpeg -i input.mkv -vf palettegen palette.png 15976@end example 15977@end itemize 15978 15979@section paletteuse 15980 15981Use a palette to downsample an input video stream. 15982 15983The filter takes two inputs: one video stream and a palette. The palette must 15984be a 256 pixels image. 15985 15986It accepts the following options: 15987 15988@table @option 15989@item dither 15990Select dithering mode. Available algorithms are: 15991@table @samp 15992@item bayer 15993Ordered 8x8 bayer dithering (deterministic) 15994@item heckbert 15995Dithering as defined by Paul Heckbert in 1982 (simple error diffusion). 15996Note: this dithering is sometimes considered "wrong" and is included as a 15997reference. 15998@item floyd_steinberg 15999Floyd and Steingberg dithering (error diffusion) 16000@item sierra2 16001Frankie Sierra dithering v2 (error diffusion) 16002@item sierra2_4a 16003Frankie Sierra dithering v2 "Lite" (error diffusion) 16004@end table 16005 16006Default is @var{sierra2_4a}. 16007 16008@item bayer_scale 16009When @var{bayer} dithering is selected, this option defines the scale of the 16010pattern (how much the crosshatch pattern is visible). A low value means more 16011visible pattern for less banding, and higher value means less visible pattern 16012at the cost of more banding. 16013 16014The option must be an integer value in the range [0,5]. Default is @var{2}. 16015 16016@item diff_mode 16017If set, define the zone to process 16018 16019@table @samp 16020@item rectangle 16021Only the changing rectangle will be reprocessed. This is similar to GIF 16022cropping/offsetting compression mechanism. This option can be useful for speed 16023if only a part of the image is changing, and has use cases such as limiting the 16024scope of the error diffusal @option{dither} to the rectangle that bounds the 16025moving scene (it leads to more deterministic output if the scene doesn't change 16026much, and as a result less moving noise and better GIF compression). 16027@end table 16028 16029Default is @var{none}. 16030 16031@item new 16032Take new palette for each output frame. 16033 16034@item alpha_threshold 16035Sets the alpha threshold for transparency. Alpha values above this threshold 16036will be treated as completely opaque, and values below this threshold will be 16037treated as completely transparent. 16038 16039The option must be an integer value in the range [0,255]. Default is @var{128}. 16040@end table 16041 16042@subsection Examples 16043 16044@itemize 16045@item 16046Use a palette (generated for example with @ref{palettegen}) to encode a GIF 16047using @command{ffmpeg}: 16048@example 16049ffmpeg -i input.mkv -i palette.png -lavfi paletteuse output.gif 16050@end example 16051@end itemize 16052 16053@section perspective 16054 16055Correct perspective of video not recorded perpendicular to the screen. 16056 16057A description of the accepted parameters follows. 16058 16059@table @option 16060@item x0 16061@item y0 16062@item x1 16063@item y1 16064@item x2 16065@item y2 16066@item x3 16067@item y3 16068Set coordinates expression for top left, top right, bottom left and bottom right corners. 16069Default values are @code{0:0:W:0:0:H:W:H} with which perspective will remain unchanged. 16070If the @code{sense} option is set to @code{source}, then the specified points will be sent 16071to the corners of the destination. If the @code{sense} option is set to @code{destination}, 16072then the corners of the source will be sent to the specified coordinates. 16073 16074The expressions can use the following variables: 16075 16076@table @option 16077@item W 16078@item H 16079the width and height of video frame. 16080@item in 16081Input frame count. 16082@item on 16083Output frame count. 16084@end table 16085 16086@item interpolation 16087Set interpolation for perspective correction. 16088 16089It accepts the following values: 16090@table @samp 16091@item linear 16092@item cubic 16093@end table 16094 16095Default value is @samp{linear}. 16096 16097@item sense 16098Set interpretation of coordinate options. 16099 16100It accepts the following values: 16101@table @samp 16102@item 0, source 16103 16104Send point in the source specified by the given coordinates to 16105the corners of the destination. 16106 16107@item 1, destination 16108 16109Send the corners of the source to the point in the destination specified 16110by the given coordinates. 16111 16112Default value is @samp{source}. 16113@end table 16114 16115@item eval 16116Set when the expressions for coordinates @option{x0,y0,...x3,y3} are evaluated. 16117 16118It accepts the following values: 16119@table @samp 16120@item init 16121only evaluate expressions once during the filter initialization or 16122when a command is processed 16123 16124@item frame 16125evaluate expressions for each incoming frame 16126@end table 16127 16128Default value is @samp{init}. 16129@end table 16130 16131@section phase 16132 16133Delay interlaced video by one field time so that the field order changes. 16134 16135The intended use is to fix PAL movies that have been captured with the 16136opposite field order to the film-to-video transfer. 16137 16138A description of the accepted parameters follows. 16139 16140@table @option 16141@item mode 16142Set phase mode. 16143 16144It accepts the following values: 16145@table @samp 16146@item t 16147Capture field order top-first, transfer bottom-first. 16148Filter will delay the bottom field. 16149 16150@item b 16151Capture field order bottom-first, transfer top-first. 16152Filter will delay the top field. 16153 16154@item p 16155Capture and transfer with the same field order. This mode only exists 16156for the documentation of the other options to refer to, but if you 16157actually select it, the filter will faithfully do nothing. 16158 16159@item a 16160Capture field order determined automatically by field flags, transfer 16161opposite. 16162Filter selects among @samp{t} and @samp{b} modes on a frame by frame 16163basis using field flags. If no field information is available, 16164then this works just like @samp{u}. 16165 16166@item u 16167Capture unknown or varying, transfer opposite. 16168Filter selects among @samp{t} and @samp{b} on a frame by frame basis by 16169analyzing the images and selecting the alternative that produces best 16170match between the fields. 16171 16172@item T 16173Capture top-first, transfer unknown or varying. 16174Filter selects among @samp{t} and @samp{p} using image analysis. 16175 16176@item B 16177Capture bottom-first, transfer unknown or varying. 16178Filter selects among @samp{b} and @samp{p} using image analysis. 16179 16180@item A 16181Capture determined by field flags, transfer unknown or varying. 16182Filter selects among @samp{t}, @samp{b} and @samp{p} using field flags and 16183image analysis. If no field information is available, then this works just 16184like @samp{U}. This is the default mode. 16185 16186@item U 16187Both capture and transfer unknown or varying. 16188Filter selects among @samp{t}, @samp{b} and @samp{p} using image analysis only. 16189@end table 16190@end table 16191 16192@subsection Commands 16193 16194This filter supports the all above options as @ref{commands}. 16195 16196@section photosensitivity 16197Reduce various flashes in video, so to help users with epilepsy. 16198 16199It accepts the following options: 16200@table @option 16201@item frames, f 16202Set how many frames to use when filtering. Default is 30. 16203 16204@item threshold, t 16205Set detection threshold factor. Default is 1. 16206Lower is stricter. 16207 16208@item skip 16209Set how many pixels to skip when sampling frames. Default is 1. 16210Allowed range is from 1 to 1024. 16211 16212@item bypass 16213Leave frames unchanged. Default is disabled. 16214@end table 16215 16216@section pixdesctest 16217 16218Pixel format descriptor test filter, mainly useful for internal 16219testing. The output video should be equal to the input video. 16220 16221For example: 16222@example 16223format=monow, pixdesctest 16224@end example 16225 16226can be used to test the monowhite pixel format descriptor definition. 16227 16228@section pixscope 16229 16230Display sample values of color channels. Mainly useful for checking color 16231and levels. Minimum supported resolution is 640x480. 16232 16233The filters accept the following options: 16234 16235@table @option 16236@item x 16237Set scope X position, relative offset on X axis. 16238 16239@item y 16240Set scope Y position, relative offset on Y axis. 16241 16242@item w 16243Set scope width. 16244 16245@item h 16246Set scope height. 16247 16248@item o 16249Set window opacity. This window also holds statistics about pixel area. 16250 16251@item wx 16252Set window X position, relative offset on X axis. 16253 16254@item wy 16255Set window Y position, relative offset on Y axis. 16256@end table 16257 16258@subsection Commands 16259 16260This filter supports same @ref{commands} as options. 16261 16262@section pp 16263 16264Enable the specified chain of postprocessing subfilters using libpostproc. This 16265library should be automatically selected with a GPL build (@code{--enable-gpl}). 16266Subfilters must be separated by '/' and can be disabled by prepending a '-'. 16267Each subfilter and some options have a short and a long name that can be used 16268interchangeably, i.e. dr/dering are the same. 16269 16270The filters accept the following options: 16271 16272@table @option 16273@item subfilters 16274Set postprocessing subfilters string. 16275@end table 16276 16277All subfilters share common options to determine their scope: 16278 16279@table @option 16280@item a/autoq 16281Honor the quality commands for this subfilter. 16282 16283@item c/chrom 16284Do chrominance filtering, too (default). 16285 16286@item y/nochrom 16287Do luminance filtering only (no chrominance). 16288 16289@item n/noluma 16290Do chrominance filtering only (no luminance). 16291@end table 16292 16293These options can be appended after the subfilter name, separated by a '|'. 16294 16295Available subfilters are: 16296 16297@table @option 16298@item hb/hdeblock[|difference[|flatness]] 16299Horizontal deblocking filter 16300@table @option 16301@item difference 16302Difference factor where higher values mean more deblocking (default: @code{32}). 16303@item flatness 16304Flatness threshold where lower values mean more deblocking (default: @code{39}). 16305@end table 16306 16307@item vb/vdeblock[|difference[|flatness]] 16308Vertical deblocking filter 16309@table @option 16310@item difference 16311Difference factor where higher values mean more deblocking (default: @code{32}). 16312@item flatness 16313Flatness threshold where lower values mean more deblocking (default: @code{39}). 16314@end table 16315 16316@item ha/hadeblock[|difference[|flatness]] 16317Accurate horizontal deblocking filter 16318@table @option 16319@item difference 16320Difference factor where higher values mean more deblocking (default: @code{32}). 16321@item flatness 16322Flatness threshold where lower values mean more deblocking (default: @code{39}). 16323@end table 16324 16325@item va/vadeblock[|difference[|flatness]] 16326Accurate vertical deblocking filter 16327@table @option 16328@item difference 16329Difference factor where higher values mean more deblocking (default: @code{32}). 16330@item flatness 16331Flatness threshold where lower values mean more deblocking (default: @code{39}). 16332@end table 16333@end table 16334 16335The horizontal and vertical deblocking filters share the difference and 16336flatness values so you cannot set different horizontal and vertical 16337thresholds. 16338 16339@table @option 16340@item h1/x1hdeblock 16341Experimental horizontal deblocking filter 16342 16343@item v1/x1vdeblock 16344Experimental vertical deblocking filter 16345 16346@item dr/dering 16347Deringing filter 16348 16349@item tn/tmpnoise[|threshold1[|threshold2[|threshold3]]], temporal noise reducer 16350@table @option 16351@item threshold1 16352larger -> stronger filtering 16353@item threshold2 16354larger -> stronger filtering 16355@item threshold3 16356larger -> stronger filtering 16357@end table 16358 16359@item al/autolevels[:f/fullyrange], automatic brightness / contrast correction 16360@table @option 16361@item f/fullyrange 16362Stretch luminance to @code{0-255}. 16363@end table 16364 16365@item lb/linblenddeint 16366Linear blend deinterlacing filter that deinterlaces the given block by 16367filtering all lines with a @code{(1 2 1)} filter. 16368 16369@item li/linipoldeint 16370Linear interpolating deinterlacing filter that deinterlaces the given block by 16371linearly interpolating every second line. 16372 16373@item ci/cubicipoldeint 16374Cubic interpolating deinterlacing filter deinterlaces the given block by 16375cubically interpolating every second line. 16376 16377@item md/mediandeint 16378Median deinterlacing filter that deinterlaces the given block by applying a 16379median filter to every second line. 16380 16381@item fd/ffmpegdeint 16382FFmpeg deinterlacing filter that deinterlaces the given block by filtering every 16383second line with a @code{(-1 4 2 4 -1)} filter. 16384 16385@item l5/lowpass5 16386Vertically applied FIR lowpass deinterlacing filter that deinterlaces the given 16387block by filtering all lines with a @code{(-1 2 6 2 -1)} filter. 16388 16389@item fq/forceQuant[|quantizer] 16390Overrides the quantizer table from the input with the constant quantizer you 16391specify. 16392@table @option 16393@item quantizer 16394Quantizer to use 16395@end table 16396 16397@item de/default 16398Default pp filter combination (@code{hb|a,vb|a,dr|a}) 16399 16400@item fa/fast 16401Fast pp filter combination (@code{h1|a,v1|a,dr|a}) 16402 16403@item ac 16404High quality pp filter combination (@code{ha|a|128|7,va|a,dr|a}) 16405@end table 16406 16407@subsection Examples 16408 16409@itemize 16410@item 16411Apply horizontal and vertical deblocking, deringing and automatic 16412brightness/contrast: 16413@example 16414pp=hb/vb/dr/al 16415@end example 16416 16417@item 16418Apply default filters without brightness/contrast correction: 16419@example 16420pp=de/-al 16421@end example 16422 16423@item 16424Apply default filters and temporal denoiser: 16425@example 16426pp=default/tmpnoise|1|2|3 16427@end example 16428 16429@item 16430Apply deblocking on luminance only, and switch vertical deblocking on or off 16431automatically depending on available CPU time: 16432@example 16433pp=hb|y/vb|a 16434@end example 16435@end itemize 16436 16437@section pp7 16438Apply Postprocessing filter 7. It is variant of the @ref{spp} filter, 16439similar to spp = 6 with 7 point DCT, where only the center sample is 16440used after IDCT. 16441 16442The filter accepts the following options: 16443 16444@table @option 16445@item qp 16446Force a constant quantization parameter. It accepts an integer in range 164470 to 63. If not set, the filter will use the QP from the video stream 16448(if available). 16449 16450@item mode 16451Set thresholding mode. Available modes are: 16452 16453@table @samp 16454@item hard 16455Set hard thresholding. 16456@item soft 16457Set soft thresholding (better de-ringing effect, but likely blurrier). 16458@item medium 16459Set medium thresholding (good results, default). 16460@end table 16461@end table 16462 16463@section premultiply 16464Apply alpha premultiply effect to input video stream using first plane 16465of second stream as alpha. 16466 16467Both streams must have same dimensions and same pixel format. 16468 16469The filter accepts the following option: 16470 16471@table @option 16472@item planes 16473Set which planes will be processed, unprocessed planes will be copied. 16474By default value 0xf, all planes will be processed. 16475 16476@item inplace 16477Do not require 2nd input for processing, instead use alpha plane from input stream. 16478@end table 16479 16480@section prewitt 16481Apply prewitt operator to input video stream. 16482 16483The filter accepts the following option: 16484 16485@table @option 16486@item planes 16487Set which planes will be processed, unprocessed planes will be copied. 16488By default value 0xf, all planes will be processed. 16489 16490@item scale 16491Set value which will be multiplied with filtered result. 16492 16493@item delta 16494Set value which will be added to filtered result. 16495@end table 16496 16497@subsection Commands 16498 16499This filter supports the all above options as @ref{commands}. 16500 16501@section pseudocolor 16502 16503Alter frame colors in video with pseudocolors. 16504 16505This filter accepts the following options: 16506 16507@table @option 16508@item c0 16509set pixel first component expression 16510 16511@item c1 16512set pixel second component expression 16513 16514@item c2 16515set pixel third component expression 16516 16517@item c3 16518set pixel fourth component expression, corresponds to the alpha component 16519 16520@item index, i 16521set component to use as base for altering colors 16522 16523@item preset, p 16524Pick one of built-in LUTs. By default is set to none. 16525 16526Available LUTs: 16527@table @samp 16528@item magma 16529@item inferno 16530@item plasma 16531@item viridis 16532@item turbo 16533@item cividis 16534@item range1 16535@item range2 16536@item shadows 16537@item highlights 16538@end table 16539 16540@item opacity 16541Set opacity of output colors. Allowed range is from 0 to 1. 16542Default value is set to 1. 16543@end table 16544 16545Each of the expression options specifies the expression to use for computing 16546the lookup table for the corresponding pixel component values. 16547 16548The expressions can contain the following constants and functions: 16549 16550@table @option 16551@item w 16552@item h 16553The input width and height. 16554 16555@item val 16556The input value for the pixel component. 16557 16558@item ymin, umin, vmin, amin 16559The minimum allowed component value. 16560 16561@item ymax, umax, vmax, amax 16562The maximum allowed component value. 16563@end table 16564 16565All expressions default to "val". 16566 16567@subsection Commands 16568 16569This filter supports the all above options as @ref{commands}. 16570 16571@subsection Examples 16572 16573@itemize 16574@item 16575Change too high luma values to gradient: 16576@example 16577pseudocolor="'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'" 16578@end example 16579@end itemize 16580 16581@section psnr 16582 16583Obtain the average, maximum and minimum PSNR (Peak Signal to Noise 16584Ratio) between two input videos. 16585 16586This filter takes in input two input videos, the first input is 16587considered the "main" source and is passed unchanged to the 16588output. The second input is used as a "reference" video for computing 16589the PSNR. 16590 16591Both video inputs must have the same resolution and pixel format for 16592this filter to work correctly. Also it assumes that both inputs 16593have the same number of frames, which are compared one by one. 16594 16595The obtained average PSNR is printed through the logging system. 16596 16597The filter stores the accumulated MSE (mean squared error) of each 16598frame, and at the end of the processing it is averaged across all frames 16599equally, and the following formula is applied to obtain the PSNR: 16600 16601@example 16602PSNR = 10*log10(MAX^2/MSE) 16603@end example 16604 16605Where MAX is the average of the maximum values of each component of the 16606image. 16607 16608The description of the accepted parameters follows. 16609 16610@table @option 16611@item stats_file, f 16612If specified the filter will use the named file to save the PSNR of 16613each individual frame. When filename equals "-" the data is sent to 16614standard output. 16615 16616@item stats_version 16617Specifies which version of the stats file format to use. Details of 16618each format are written below. 16619Default value is 1. 16620 16621@item stats_add_max 16622Determines whether the max value is output to the stats log. 16623Default value is 0. 16624Requires stats_version >= 2. If this is set and stats_version < 2, 16625the filter will return an error. 16626@end table 16627 16628This filter also supports the @ref{framesync} options. 16629 16630The file printed if @var{stats_file} is selected, contains a sequence of 16631key/value pairs of the form @var{key}:@var{value} for each compared 16632couple of frames. 16633 16634If a @var{stats_version} greater than 1 is specified, a header line precedes 16635the list of per-frame-pair stats, with key value pairs following the frame 16636format with the following parameters: 16637 16638@table @option 16639@item psnr_log_version 16640The version of the log file format. Will match @var{stats_version}. 16641 16642@item fields 16643A comma separated list of the per-frame-pair parameters included in 16644the log. 16645@end table 16646 16647A description of each shown per-frame-pair parameter follows: 16648 16649@table @option 16650@item n 16651sequential number of the input frame, starting from 1 16652 16653@item mse_avg 16654Mean Square Error pixel-by-pixel average difference of the compared 16655frames, averaged over all the image components. 16656 16657@item mse_y, mse_u, mse_v, mse_r, mse_g, mse_b, mse_a 16658Mean Square Error pixel-by-pixel average difference of the compared 16659frames for the component specified by the suffix. 16660 16661@item psnr_y, psnr_u, psnr_v, psnr_r, psnr_g, psnr_b, psnr_a 16662Peak Signal to Noise ratio of the compared frames for the component 16663specified by the suffix. 16664 16665@item max_avg, max_y, max_u, max_v 16666Maximum allowed value for each channel, and average over all 16667channels. 16668@end table 16669 16670@subsection Examples 16671@itemize 16672@item 16673For example: 16674@example 16675movie=ref_movie.mpg, setpts=PTS-STARTPTS [main]; 16676[main][ref] psnr="stats_file=stats.log" [out] 16677@end example 16678 16679On this example the input file being processed is compared with the 16680reference file @file{ref_movie.mpg}. The PSNR of each individual frame 16681is stored in @file{stats.log}. 16682 16683@item 16684Another example with different containers: 16685@example 16686ffmpeg -i main.mpg -i ref.mkv -lavfi "[0:v]settb=AVTB,setpts=PTS-STARTPTS[main];[1:v]settb=AVTB,setpts=PTS-STARTPTS[ref];[main][ref]psnr" -f null - 16687@end example 16688@end itemize 16689 16690@anchor{pullup} 16691@section pullup 16692 16693Pulldown reversal (inverse telecine) filter, capable of handling mixed 16694hard-telecine, 24000/1001 fps progressive, and 30000/1001 fps progressive 16695content. 16696 16697The pullup filter is designed to take advantage of future context in making 16698its decisions. This filter is stateless in the sense that it does not lock 16699onto a pattern to follow, but it instead looks forward to the following 16700fields in order to identify matches and rebuild progressive frames. 16701 16702To produce content with an even framerate, insert the fps filter after 16703pullup, use @code{fps=24000/1001} if the input frame rate is 29.97fps, 16704@code{fps=24} for 30fps and the (rare) telecined 25fps input. 16705 16706The filter accepts the following options: 16707 16708@table @option 16709@item jl 16710@item jr 16711@item jt 16712@item jb 16713These options set the amount of "junk" to ignore at the left, right, top, and 16714bottom of the image, respectively. Left and right are in units of 8 pixels, 16715while top and bottom are in units of 2 lines. 16716The default is 8 pixels on each side. 16717 16718@item sb 16719Set the strict breaks. Setting this option to 1 will reduce the chances of 16720filter generating an occasional mismatched frame, but it may also cause an 16721excessive number of frames to be dropped during high motion sequences. 16722Conversely, setting it to -1 will make filter match fields more easily. 16723This may help processing of video where there is slight blurring between 16724the fields, but may also cause there to be interlaced frames in the output. 16725Default value is @code{0}. 16726 16727@item mp 16728Set the metric plane to use. It accepts the following values: 16729@table @samp 16730@item l 16731Use luma plane. 16732 16733@item u 16734Use chroma blue plane. 16735 16736@item v 16737Use chroma red plane. 16738@end table 16739 16740This option may be set to use chroma plane instead of the default luma plane 16741for doing filter's computations. This may improve accuracy on very clean 16742source material, but more likely will decrease accuracy, especially if there 16743is chroma noise (rainbow effect) or any grayscale video. 16744The main purpose of setting @option{mp} to a chroma plane is to reduce CPU 16745load and make pullup usable in realtime on slow machines. 16746@end table 16747 16748For best results (without duplicated frames in the output file) it is 16749necessary to change the output frame rate. For example, to inverse 16750telecine NTSC input: 16751@example 16752ffmpeg -i input -vf pullup -r 24000/1001 ... 16753@end example 16754 16755@section qp 16756 16757Change video quantization parameters (QP). 16758 16759The filter accepts the following option: 16760 16761@table @option 16762@item qp 16763Set expression for quantization parameter. 16764@end table 16765 16766The expression is evaluated through the eval API and can contain, among others, 16767the following constants: 16768 16769@table @var 16770@item known 167711 if index is not 129, 0 otherwise. 16772 16773@item qp 16774Sequential index starting from -129 to 128. 16775@end table 16776 16777@subsection Examples 16778 16779@itemize 16780@item 16781Some equation like: 16782@example 16783qp=2+2*sin(PI*qp) 16784@end example 16785@end itemize 16786 16787@section random 16788 16789Flush video frames from internal cache of frames into a random order. 16790No frame is discarded. 16791Inspired by @ref{frei0r} nervous filter. 16792 16793@table @option 16794@item frames 16795Set size in number of frames of internal cache, in range from @code{2} to 16796@code{512}. Default is @code{30}. 16797 16798@item seed 16799Set seed for random number generator, must be an integer included between 16800@code{0} and @code{UINT32_MAX}. If not specified, or if explicitly set to 16801less than @code{0}, the filter will try to use a good random seed on a 16802best effort basis. 16803@end table 16804 16805@section readeia608 16806 16807Read closed captioning (EIA-608) information from the top lines of a video frame. 16808 16809This filter adds frame metadata for @code{lavfi.readeia608.X.cc} and 16810@code{lavfi.readeia608.X.line}, where @code{X} is the number of the identified line 16811with EIA-608 data (starting from 0). A description of each metadata value follows: 16812 16813@table @option 16814@item lavfi.readeia608.X.cc 16815The two bytes stored as EIA-608 data (printed in hexadecimal). 16816 16817@item lavfi.readeia608.X.line 16818The number of the line on which the EIA-608 data was identified and read. 16819@end table 16820 16821This filter accepts the following options: 16822 16823@table @option 16824@item scan_min 16825Set the line to start scanning for EIA-608 data. Default is @code{0}. 16826 16827@item scan_max 16828Set the line to end scanning for EIA-608 data. Default is @code{29}. 16829 16830@item spw 16831Set the ratio of width reserved for sync code detection. 16832Default is @code{0.27}. Allowed range is @code{[0.1 - 0.7]}. 16833 16834@item chp 16835Enable checking the parity bit. In the event of a parity error, the filter will output 16836@code{0x00} for that character. Default is false. 16837 16838@item lp 16839Lowpass lines prior to further processing. Default is enabled. 16840@end table 16841 16842@subsection Commands 16843 16844This filter supports the all above options as @ref{commands}. 16845 16846@subsection Examples 16847 16848@itemize 16849@item 16850Output a csv with presentation time and the first two lines of identified EIA-608 captioning data. 16851@example 16852ffprobe -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 16853@end example 16854@end itemize 16855 16856@section readvitc 16857 16858Read vertical interval timecode (VITC) information from the top lines of a 16859video frame. 16860 16861The filter adds frame metadata key @code{lavfi.readvitc.tc_str} with the 16862timecode value, if a valid timecode has been detected. Further metadata key 16863@code{lavfi.readvitc.found} is set to 0/1 depending on whether 16864timecode data has been found or not. 16865 16866This filter accepts the following options: 16867 16868@table @option 16869@item scan_max 16870Set the maximum number of lines to scan for VITC data. If the value is set to 16871@code{-1} the full video frame is scanned. Default is @code{45}. 16872 16873@item thr_b 16874Set the luma threshold for black. Accepts float numbers in the range [0.0,1.0], 16875default value is @code{0.2}. The value must be equal or less than @code{thr_w}. 16876 16877@item thr_w 16878Set the luma threshold for white. Accepts float numbers in the range [0.0,1.0], 16879default value is @code{0.6}. The value must be equal or greater than @code{thr_b}. 16880@end table 16881 16882@subsection Examples 16883 16884@itemize 16885@item 16886Detect and draw VITC data onto the video frame; if no valid VITC is detected, 16887draw @code{--:--:--:--} as a placeholder: 16888@example 16889ffmpeg -i input.avi -filter:v 'readvitc,drawtext=fontfile=FreeMono.ttf:text=%@{metadata\\:lavfi.readvitc.tc_str\\:--\\\\\\:--\\\\\\:--\\\\\\:--@}:x=(w-tw)/2:y=400-ascent' 16890@end example 16891@end itemize 16892 16893@section remap 16894 16895Remap pixels using 2nd: Xmap and 3rd: Ymap input video stream. 16896 16897Destination pixel at position (X, Y) will be picked from source (x, y) position 16898where x = Xmap(X, Y) and y = Ymap(X, Y). If mapping values are out of range, zero 16899value for pixel will be used for destination pixel. 16900 16901Xmap and Ymap input video streams must be of same dimensions. Output video stream 16902will have Xmap/Ymap video stream dimensions. 16903Xmap and Ymap input video streams are 16bit depth, single channel. 16904 16905@table @option 16906@item format 16907Specify pixel format of output from this filter. Can be @code{color} or @code{gray}. 16908Default is @code{color}. 16909 16910@item fill 16911Specify the color of the unmapped pixels. For the syntax of this option, 16912check the @ref{color syntax,,"Color" section in the ffmpeg-utils 16913manual,ffmpeg-utils}. Default color is @code{black}. 16914@end table 16915 16916@section removegrain 16917 16918The removegrain filter is a spatial denoiser for progressive video. 16919 16920@table @option 16921@item m0 16922Set mode for the first plane. 16923 16924@item m1 16925Set mode for the second plane. 16926 16927@item m2 16928Set mode for the third plane. 16929 16930@item m3 16931Set mode for the fourth plane. 16932@end table 16933 16934Range of mode is from 0 to 24. Description of each mode follows: 16935 16936@table @var 16937@item 0 16938Leave input plane unchanged. Default. 16939 16940@item 1 16941Clips the pixel with the minimum and maximum of the 8 neighbour pixels. 16942 16943@item 2 16944Clips the pixel with the second minimum and maximum of the 8 neighbour pixels. 16945 16946@item 3 16947Clips the pixel with the third minimum and maximum of the 8 neighbour pixels. 16948 16949@item 4 16950Clips the pixel with the fourth minimum and maximum of the 8 neighbour pixels. 16951This is equivalent to a median filter. 16952 16953@item 5 16954Line-sensitive clipping giving the minimal change. 16955 16956@item 6 16957Line-sensitive clipping, intermediate. 16958 16959@item 7 16960Line-sensitive clipping, intermediate. 16961 16962@item 8 16963Line-sensitive clipping, intermediate. 16964 16965@item 9 16966Line-sensitive clipping on a line where the neighbours pixels are the closest. 16967 16968@item 10 16969Replaces the target pixel with the closest neighbour. 16970 16971@item 11 16972[1 2 1] horizontal and vertical kernel blur. 16973 16974@item 12 16975Same as mode 11. 16976 16977@item 13 16978Bob mode, interpolates top field from the line where the neighbours 16979pixels are the closest. 16980 16981@item 14 16982Bob mode, interpolates bottom field from the line where the neighbours 16983pixels are the closest. 16984 16985@item 15 16986Bob mode, interpolates top field. Same as 13 but with a more complicated 16987interpolation formula. 16988 16989@item 16 16990Bob mode, interpolates bottom field. Same as 14 but with a more complicated 16991interpolation formula. 16992 16993@item 17 16994Clips the pixel with the minimum and maximum of respectively the maximum and 16995minimum of each pair of opposite neighbour pixels. 16996 16997@item 18 16998Line-sensitive clipping using opposite neighbours whose greatest distance from 16999the current pixel is minimal. 17000 17001@item 19 17002Replaces the pixel with the average of its 8 neighbours. 17003 17004@item 20 17005Averages the 9 pixels ([1 1 1] horizontal and vertical blur). 17006 17007@item 21 17008Clips pixels using the averages of opposite neighbour. 17009 17010@item 22 17011Same as mode 21 but simpler and faster. 17012 17013@item 23 17014Small edge and halo removal, but reputed useless. 17015 17016@item 24 17017Similar as 23. 17018@end table 17019 17020@section removelogo 17021 17022Suppress a TV station logo, using an image file to determine which 17023pixels comprise the logo. It works by filling in the pixels that 17024comprise the logo with neighboring pixels. 17025 17026The filter accepts the following options: 17027 17028@table @option 17029@item filename, f 17030Set the filter bitmap file, which can be any image format supported by 17031libavformat. The width and height of the image file must match those of the 17032video stream being processed. 17033@end table 17034 17035Pixels in the provided bitmap image with a value of zero are not 17036considered part of the logo, non-zero pixels are considered part of 17037the logo. If you use white (255) for the logo and black (0) for the 17038rest, you will be safe. For making the filter bitmap, it is 17039recommended to take a screen capture of a black frame with the logo 17040visible, and then using a threshold filter followed by the erode 17041filter once or twice. 17042 17043If needed, little splotches can be fixed manually. Remember that if 17044logo pixels are not covered, the filter quality will be much 17045reduced. Marking too many pixels as part of the logo does not hurt as 17046much, but it will increase the amount of blurring needed to cover over 17047the image and will destroy more information than necessary, and extra 17048pixels will slow things down on a large logo. 17049 17050@section repeatfields 17051 17052This filter uses the repeat_field flag from the Video ES headers and hard repeats 17053fields based on its value. 17054 17055@section reverse 17056 17057Reverse a video clip. 17058 17059Warning: This filter requires memory to buffer the entire clip, so trimming 17060is suggested. 17061 17062@subsection Examples 17063 17064@itemize 17065@item 17066Take the first 5 seconds of a clip, and reverse it. 17067@example 17068trim=end=5,reverse 17069@end example 17070@end itemize 17071 17072@section rgbashift 17073Shift R/G/B/A pixels horizontally and/or vertically. 17074 17075The filter accepts the following options: 17076@table @option 17077@item rh 17078Set amount to shift red horizontally. 17079@item rv 17080Set amount to shift red vertically. 17081@item gh 17082Set amount to shift green horizontally. 17083@item gv 17084Set amount to shift green vertically. 17085@item bh 17086Set amount to shift blue horizontally. 17087@item bv 17088Set amount to shift blue vertically. 17089@item ah 17090Set amount to shift alpha horizontally. 17091@item av 17092Set amount to shift alpha vertically. 17093@item edge 17094Set edge mode, can be @var{smear}, default, or @var{warp}. 17095@end table 17096 17097@subsection Commands 17098 17099This filter supports the all above options as @ref{commands}. 17100 17101@section roberts 17102Apply roberts cross operator to input video stream. 17103 17104The filter accepts the following option: 17105 17106@table @option 17107@item planes 17108Set which planes will be processed, unprocessed planes will be copied. 17109By default value 0xf, all planes will be processed. 17110 17111@item scale 17112Set value which will be multiplied with filtered result. 17113 17114@item delta 17115Set value which will be added to filtered result. 17116@end table 17117 17118@subsection Commands 17119 17120This filter supports the all above options as @ref{commands}. 17121 17122@section rotate 17123 17124Rotate video by an arbitrary angle expressed in radians. 17125 17126The filter accepts the following options: 17127 17128A description of the optional parameters follows. 17129@table @option 17130@item angle, a 17131Set an expression for the angle by which to rotate the input video 17132clockwise, expressed as a number of radians. A negative value will 17133result in a counter-clockwise rotation. By default it is set to "0". 17134 17135This expression is evaluated for each frame. 17136 17137@item out_w, ow 17138Set the output width expression, default value is "iw". 17139This expression is evaluated just once during configuration. 17140 17141@item out_h, oh 17142Set the output height expression, default value is "ih". 17143This expression is evaluated just once during configuration. 17144 17145@item bilinear 17146Enable bilinear interpolation if set to 1, a value of 0 disables 17147it. Default value is 1. 17148 17149@item fillcolor, c 17150Set the color used to fill the output area not covered by the rotated 17151image. For the general syntax of this option, check the 17152@ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}. 17153If the special value "none" is selected then no 17154background is printed (useful for example if the background is never shown). 17155 17156Default value is "black". 17157@end table 17158 17159The expressions for the angle and the output size can contain the 17160following constants and functions: 17161 17162@table @option 17163@item n 17164sequential number of the input frame, starting from 0. It is always NAN 17165before the first frame is filtered. 17166 17167@item t 17168time in seconds of the input frame, it is set to 0 when the filter is 17169configured. It is always NAN before the first frame is filtered. 17170 17171@item hsub 17172@item vsub 17173horizontal and vertical chroma subsample values. For example for the 17174pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1. 17175 17176@item in_w, iw 17177@item in_h, ih 17178the input video width and height 17179 17180@item out_w, ow 17181@item out_h, oh 17182the output width and height, that is the size of the padded area as 17183specified by the @var{width} and @var{height} expressions 17184 17185@item rotw(a) 17186@item roth(a) 17187the minimal width/height required for completely containing the input 17188video rotated by @var{a} radians. 17189 17190These are only available when computing the @option{out_w} and 17191@option{out_h} expressions. 17192@end table 17193 17194@subsection Examples 17195 17196@itemize 17197@item 17198Rotate the input by PI/6 radians clockwise: 17199@example 17200rotate=PI/6 17201@end example 17202 17203@item 17204Rotate the input by PI/6 radians counter-clockwise: 17205@example 17206rotate=-PI/6 17207@end example 17208 17209@item 17210Rotate the input by 45 degrees clockwise: 17211@example 17212rotate=45*PI/180 17213@end example 17214 17215@item 17216Apply a constant rotation with period T, starting from an angle of PI/3: 17217@example 17218rotate=PI/3+2*PI*t/T 17219@end example 17220 17221@item 17222Make the input video rotation oscillating with a period of T 17223seconds and an amplitude of A radians: 17224@example 17225rotate=A*sin(2*PI/T*t) 17226@end example 17227 17228@item 17229Rotate the video, output size is chosen so that the whole rotating 17230input video is always completely contained in the output: 17231@example 17232rotate='2*PI*t:ow=hypot(iw,ih):oh=ow' 17233@end example 17234 17235@item 17236Rotate the video, reduce the output size so that no background is ever 17237shown: 17238@example 17239rotate=2*PI*t:ow='min(iw,ih)/sqrt(2)':oh=ow:c=none 17240@end example 17241@end itemize 17242 17243@subsection Commands 17244 17245The filter supports the following commands: 17246 17247@table @option 17248@item a, angle 17249Set the angle expression. 17250The command accepts the same syntax of the corresponding option. 17251 17252If the specified expression is not valid, it is kept at its current 17253value. 17254@end table 17255 17256@section sab 17257 17258Apply Shape Adaptive Blur. 17259 17260The filter accepts the following options: 17261 17262@table @option 17263@item luma_radius, lr 17264Set luma blur filter strength, must be a value in range 0.1-4.0, default 17265value is 1.0. A greater value will result in a more blurred image, and 17266in slower processing. 17267 17268@item luma_pre_filter_radius, lpfr 17269Set luma pre-filter radius, must be a value in the 0.1-2.0 range, default 17270value is 1.0. 17271 17272@item luma_strength, ls 17273Set luma maximum difference between pixels to still be considered, must 17274be a value in the 0.1-100.0 range, default value is 1.0. 17275 17276@item chroma_radius, cr 17277Set chroma blur filter strength, must be a value in range -0.9-4.0. A 17278greater value will result in a more blurred image, and in slower 17279processing. 17280 17281@item chroma_pre_filter_radius, cpfr 17282Set chroma pre-filter radius, must be a value in the -0.9-2.0 range. 17283 17284@item chroma_strength, cs 17285Set chroma maximum difference between pixels to still be considered, 17286must be a value in the -0.9-100.0 range. 17287@end table 17288 17289Each chroma option value, if not explicitly specified, is set to the 17290corresponding luma option value. 17291 17292@anchor{scale} 17293@section scale 17294 17295Scale (resize) the input video, using the libswscale library. 17296 17297The scale filter forces the output display aspect ratio to be the same 17298of the input, by changing the output sample aspect ratio. 17299 17300If the input image format is different from the format requested by 17301the next filter, the scale filter will convert the input to the 17302requested format. 17303 17304@subsection Options 17305The filter accepts the following options, or any of the options 17306supported by the libswscale scaler. 17307 17308See @ref{scaler_options,,the ffmpeg-scaler manual,ffmpeg-scaler} for 17309the complete list of scaler options. 17310 17311@table @option 17312@item width, w 17313@item height, h 17314Set the output video dimension expression. Default value is the input 17315dimension. 17316 17317If the @var{width} or @var{w} value is 0, the input width is used for 17318the output. If the @var{height} or @var{h} value is 0, the input height 17319is used for the output. 17320 17321If one and only one of the values is -n with n >= 1, the scale filter 17322will use a value that maintains the aspect ratio of the input image, 17323calculated from the other specified dimension. After that it will, 17324however, make sure that the calculated dimension is divisible by n and 17325adjust the value if necessary. 17326 17327If both values are -n with n >= 1, the behavior will be identical to 17328both values being set to 0 as previously detailed. 17329 17330See below for the list of accepted constants for use in the dimension 17331expression. 17332 17333@item eval 17334Specify when to evaluate @var{width} and @var{height} expression. It accepts the following values: 17335 17336@table @samp 17337@item init 17338Only evaluate expressions once during the filter initialization or when a command is processed. 17339 17340@item frame 17341Evaluate expressions for each incoming frame. 17342 17343@end table 17344 17345Default value is @samp{init}. 17346 17347 17348@item interl 17349Set the interlacing mode. It accepts the following values: 17350 17351@table @samp 17352@item 1 17353Force interlaced aware scaling. 17354 17355@item 0 17356Do not apply interlaced scaling. 17357 17358@item -1 17359Select interlaced aware scaling depending on whether the source frames 17360are flagged as interlaced or not. 17361@end table 17362 17363Default value is @samp{0}. 17364 17365@item flags 17366Set libswscale scaling flags. See 17367@ref{sws_flags,,the ffmpeg-scaler manual,ffmpeg-scaler} for the 17368complete list of values. If not explicitly specified the filter applies 17369the default flags. 17370 17371 17372@item param0, param1 17373Set libswscale input parameters for scaling algorithms that need them. See 17374@ref{sws_params,,the ffmpeg-scaler manual,ffmpeg-scaler} for the 17375complete documentation. If not explicitly specified the filter applies 17376empty parameters. 17377 17378 17379 17380@item size, s 17381Set the video size. For the syntax of this option, check the 17382@ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}. 17383 17384@item in_color_matrix 17385@item out_color_matrix 17386Set in/output YCbCr color space type. 17387 17388This allows the autodetected value to be overridden as well as allows forcing 17389a specific value used for the output and encoder. 17390 17391If not specified, the color space type depends on the pixel format. 17392 17393Possible values: 17394 17395@table @samp 17396@item auto 17397Choose automatically. 17398 17399@item bt709 17400Format conforming to International Telecommunication Union (ITU) 17401Recommendation BT.709. 17402 17403@item fcc 17404Set color space conforming to the United States Federal Communications 17405Commission (FCC) Code of Federal Regulations (CFR) Title 47 (2003) 73.682 (a). 17406 17407@item bt601 17408@item bt470 17409@item smpte170m 17410Set color space conforming to: 17411 17412@itemize 17413@item 17414ITU Radiocommunication Sector (ITU-R) Recommendation BT.601 17415 17416@item 17417ITU-R Rec. BT.470-6 (1998) Systems B, B1, and G 17418 17419@item 17420Society of Motion Picture and Television Engineers (SMPTE) ST 170:2004 17421 17422@end itemize 17423 17424@item smpte240m 17425Set color space conforming to SMPTE ST 240:1999. 17426 17427@item bt2020 17428Set color space conforming to ITU-R BT.2020 non-constant luminance system. 17429@end table 17430 17431@item in_range 17432@item out_range 17433Set in/output YCbCr sample range. 17434 17435This allows the autodetected value to be overridden as well as allows forcing 17436a specific value used for the output and encoder. If not specified, the 17437range depends on the pixel format. Possible values: 17438 17439@table @samp 17440@item auto/unknown 17441Choose automatically. 17442 17443@item jpeg/full/pc 17444Set full range (0-255 in case of 8-bit luma). 17445 17446@item mpeg/limited/tv 17447Set "MPEG" range (16-235 in case of 8-bit luma). 17448@end table 17449 17450@item force_original_aspect_ratio 17451Enable decreasing or increasing output video width or height if necessary to 17452keep the original aspect ratio. Possible values: 17453 17454@table @samp 17455@item disable 17456Scale the video as specified and disable this feature. 17457 17458@item decrease 17459The output video dimensions will automatically be decreased if needed. 17460 17461@item increase 17462The output video dimensions will automatically be increased if needed. 17463 17464@end table 17465 17466One useful instance of this option is that when you know a specific device's 17467maximum allowed resolution, you can use this to limit the output video to 17468that, while retaining the aspect ratio. For example, device A allows 174691280x720 playback, and your video is 1920x800. Using this option (set it to 17470decrease) and specifying 1280x720 to the command line makes the output 174711280x533. 17472 17473Please note that this is a different thing than specifying -1 for @option{w} 17474or @option{h}, you still need to specify the output resolution for this option 17475to work. 17476 17477@item force_divisible_by 17478Ensures that both the output dimensions, width and height, are divisible by the 17479given integer when used together with @option{force_original_aspect_ratio}. This 17480works similar to using @code{-n} in the @option{w} and @option{h} options. 17481 17482This option respects the value set for @option{force_original_aspect_ratio}, 17483increasing or decreasing the resolution accordingly. The video's aspect ratio 17484may be slightly modified. 17485 17486This option can be handy if you need to have a video fit within or exceed 17487a defined resolution using @option{force_original_aspect_ratio} but also have 17488encoder restrictions on width or height divisibility. 17489 17490@end table 17491 17492The values of the @option{w} and @option{h} options are expressions 17493containing the following constants: 17494 17495@table @var 17496@item in_w 17497@item in_h 17498The input width and height 17499 17500@item iw 17501@item ih 17502These are the same as @var{in_w} and @var{in_h}. 17503 17504@item out_w 17505@item out_h 17506The output (scaled) width and height 17507 17508@item ow 17509@item oh 17510These are the same as @var{out_w} and @var{out_h} 17511 17512@item a 17513The same as @var{iw} / @var{ih} 17514 17515@item sar 17516input sample aspect ratio 17517 17518@item dar 17519The input display aspect ratio. Calculated from @code{(iw / ih) * sar}. 17520 17521@item hsub 17522@item vsub 17523horizontal and vertical input chroma subsample values. For example for the 17524pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1. 17525 17526@item ohsub 17527@item ovsub 17528horizontal and vertical output chroma subsample values. For example for the 17529pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1. 17530 17531@item n 17532The (sequential) number of the input frame, starting from 0. 17533Only available with @code{eval=frame}. 17534 17535@item t 17536The presentation timestamp of the input frame, expressed as a number of 17537seconds. Only available with @code{eval=frame}. 17538 17539@item pos 17540The position (byte offset) of the frame in the input stream, or NaN if 17541this information is unavailable and/or meaningless (for example in case of synthetic video). 17542Only available with @code{eval=frame}. 17543@end table 17544 17545@subsection Examples 17546 17547@itemize 17548@item 17549Scale the input video to a size of 200x100 17550@example 17551scale=w=200:h=100 17552@end example 17553 17554This is equivalent to: 17555@example 17556scale=200:100 17557@end example 17558 17559or: 17560@example 17561scale=200x100 17562@end example 17563 17564@item 17565Specify a size abbreviation for the output size: 17566@example 17567scale=qcif 17568@end example 17569 17570which can also be written as: 17571@example 17572scale=size=qcif 17573@end example 17574 17575@item 17576Scale the input to 2x: 17577@example 17578scale=w=2*iw:h=2*ih 17579@end example 17580 17581@item 17582The above is the same as: 17583@example 17584scale=2*in_w:2*in_h 17585@end example 17586 17587@item 17588Scale the input to 2x with forced interlaced scaling: 17589@example 17590scale=2*iw:2*ih:interl=1 17591@end example 17592 17593@item 17594Scale the input to half size: 17595@example 17596scale=w=iw/2:h=ih/2 17597@end example 17598 17599@item 17600Increase the width, and set the height to the same size: 17601@example 17602scale=3/2*iw:ow 17603@end example 17604 17605@item 17606Seek Greek harmony: 17607@example 17608scale=iw:1/PHI*iw 17609scale=ih*PHI:ih 17610@end example 17611 17612@item 17613Increase the height, and set the width to 3/2 of the height: 17614@example 17615scale=w=3/2*oh:h=3/5*ih 17616@end example 17617 17618@item 17619Increase the size, making the size a multiple of the chroma 17620subsample values: 17621@example 17622scale="trunc(3/2*iw/hsub)*hsub:trunc(3/2*ih/vsub)*vsub" 17623@end example 17624 17625@item 17626Increase the width to a maximum of 500 pixels, 17627keeping the same aspect ratio as the input: 17628@example 17629scale=w='min(500\, iw*3/2):h=-1' 17630@end example 17631 17632@item 17633Make pixels square by combining scale and setsar: 17634@example 17635scale='trunc(ih*dar):ih',setsar=1/1 17636@end example 17637 17638@item 17639Make pixels square by combining scale and setsar, 17640making sure the resulting resolution is even (required by some codecs): 17641@example 17642scale='trunc(ih*dar/2)*2:trunc(ih/2)*2',setsar=1/1 17643@end example 17644@end itemize 17645 17646@subsection Commands 17647 17648This filter supports the following commands: 17649@table @option 17650@item width, w 17651@item height, h 17652Set the output video dimension expression. 17653The command accepts the same syntax of the corresponding option. 17654 17655If the specified expression is not valid, it is kept at its current 17656value. 17657@end table 17658 17659@section scale_npp 17660 17661Use the NVIDIA Performance Primitives (libnpp) to perform scaling and/or pixel 17662format conversion on CUDA video frames. Setting the output width and height 17663works in the same way as for the @var{scale} filter. 17664 17665The following additional options are accepted: 17666@table @option 17667@item format 17668The pixel format of the output CUDA frames. If set to the string "same" (the 17669default), the input format will be kept. Note that automatic format negotiation 17670and conversion is not yet supported for hardware frames 17671 17672@item interp_algo 17673The interpolation algorithm used for resizing. One of the following: 17674@table @option 17675@item nn 17676Nearest neighbour. 17677 17678@item linear 17679@item cubic 17680@item cubic2p_bspline 176812-parameter cubic (B=1, C=0) 17682 17683@item cubic2p_catmullrom 176842-parameter cubic (B=0, C=1/2) 17685 17686@item cubic2p_b05c03 176872-parameter cubic (B=1/2, C=3/10) 17688 17689@item super 17690Supersampling 17691 17692@item lanczos 17693@end table 17694 17695@item force_original_aspect_ratio 17696Enable decreasing or increasing output video width or height if necessary to 17697keep the original aspect ratio. Possible values: 17698 17699@table @samp 17700@item disable 17701Scale the video as specified and disable this feature. 17702 17703@item decrease 17704The output video dimensions will automatically be decreased if needed. 17705 17706@item increase 17707The output video dimensions will automatically be increased if needed. 17708 17709@end table 17710 17711One useful instance of this option is that when you know a specific device's 17712maximum allowed resolution, you can use this to limit the output video to 17713that, while retaining the aspect ratio. For example, device A allows 177141280x720 playback, and your video is 1920x800. Using this option (set it to 17715decrease) and specifying 1280x720 to the command line makes the output 177161280x533. 17717 17718Please note that this is a different thing than specifying -1 for @option{w} 17719or @option{h}, you still need to specify the output resolution for this option 17720to work. 17721 17722@item force_divisible_by 17723Ensures that both the output dimensions, width and height, are divisible by the 17724given integer when used together with @option{force_original_aspect_ratio}. This 17725works similar to using @code{-n} in the @option{w} and @option{h} options. 17726 17727This option respects the value set for @option{force_original_aspect_ratio}, 17728increasing or decreasing the resolution accordingly. The video's aspect ratio 17729may be slightly modified. 17730 17731This option can be handy if you need to have a video fit within or exceed 17732a defined resolution using @option{force_original_aspect_ratio} but also have 17733encoder restrictions on width or height divisibility. 17734 17735@end table 17736 17737@section scale2ref 17738 17739Scale (resize) the input video, based on a reference video. 17740 17741See the scale filter for available options, scale2ref supports the same but 17742uses the reference video instead of the main input as basis. scale2ref also 17743supports the following additional constants for the @option{w} and 17744@option{h} options: 17745 17746@table @var 17747@item main_w 17748@item main_h 17749The main input video's width and height 17750 17751@item main_a 17752The same as @var{main_w} / @var{main_h} 17753 17754@item main_sar 17755The main input video's sample aspect ratio 17756 17757@item main_dar, mdar 17758The main input video's display aspect ratio. Calculated from 17759@code{(main_w / main_h) * main_sar}. 17760 17761@item main_hsub 17762@item main_vsub 17763The main input video's horizontal and vertical chroma subsample values. 17764For example for the pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} 17765is 1. 17766 17767@item main_n 17768The (sequential) number of the main input frame, starting from 0. 17769Only available with @code{eval=frame}. 17770 17771@item main_t 17772The presentation timestamp of the main input frame, expressed as a number of 17773seconds. Only available with @code{eval=frame}. 17774 17775@item main_pos 17776The position (byte offset) of the frame in the main input stream, or NaN if 17777this information is unavailable and/or meaningless (for example in case of synthetic video). 17778Only available with @code{eval=frame}. 17779@end table 17780 17781@subsection Examples 17782 17783@itemize 17784@item 17785Scale a subtitle stream (b) to match the main video (a) in size before overlaying 17786@example 17787'scale2ref[b][a];[a][b]overlay' 17788@end example 17789 17790@item 17791Scale a logo to 1/10th the height of a video, while preserving its display aspect ratio. 17792@example 17793[logo-in][video-in]scale2ref=w=oh*mdar:h=ih/10[logo-out][video-out] 17794@end example 17795@end itemize 17796 17797@subsection Commands 17798 17799This filter supports the following commands: 17800@table @option 17801@item width, w 17802@item height, h 17803Set the output video dimension expression. 17804The command accepts the same syntax of the corresponding option. 17805 17806If the specified expression is not valid, it is kept at its current 17807value. 17808@end table 17809 17810@section scroll 17811Scroll input video horizontally and/or vertically by constant speed. 17812 17813The filter accepts the following options: 17814@table @option 17815@item horizontal, h 17816Set the horizontal scrolling speed. Default is 0. Allowed range is from -1 to 1. 17817Negative values changes scrolling direction. 17818 17819@item vertical, v 17820Set the vertical scrolling speed. Default is 0. Allowed range is from -1 to 1. 17821Negative values changes scrolling direction. 17822 17823@item hpos 17824Set the initial horizontal scrolling position. Default is 0. Allowed range is from 0 to 1. 17825 17826@item vpos 17827Set the initial vertical scrolling position. Default is 0. Allowed range is from 0 to 1. 17828@end table 17829 17830@subsection Commands 17831 17832This filter supports the following @ref{commands}: 17833@table @option 17834@item horizontal, h 17835Set the horizontal scrolling speed. 17836@item vertical, v 17837Set the vertical scrolling speed. 17838@end table 17839 17840@anchor{scdet} 17841@section scdet 17842 17843Detect video scene change. 17844 17845This filter sets frame metadata with mafd between frame, the scene score, and 17846forward the frame to the next filter, so they can use these metadata to detect 17847scene change or others. 17848 17849In addition, this filter logs a message and sets frame metadata when it detects 17850a scene change by @option{threshold}. 17851 17852@code{lavfi.scd.mafd} metadata keys are set with mafd for every frame. 17853 17854@code{lavfi.scd.score} metadata keys are set with scene change score for every frame 17855to detect scene change. 17856 17857@code{lavfi.scd.time} metadata keys are set with current filtered frame time which 17858detect scene change with @option{threshold}. 17859 17860The filter accepts the following options: 17861 17862@table @option 17863@item threshold, t 17864Set the scene change detection threshold as a percentage of maximum change. Good 17865values are in the @code{[8.0, 14.0]} range. The range for @option{threshold} is 17866@code{[0., 100.]}. 17867 17868Default value is @code{10.}. 17869 17870@item sc_pass, s 17871Set the flag to pass scene change frames to the next filter. Default value is @code{0} 17872You can enable it if you want to get snapshot of scene change frames only. 17873@end table 17874 17875@anchor{selectivecolor} 17876@section selectivecolor 17877 17878Adjust cyan, magenta, yellow and black (CMYK) to certain ranges of colors (such 17879as "reds", "yellows", "greens", "cyans", ...). The adjustment range is defined 17880by the "purity" of the color (that is, how saturated it already is). 17881 17882This filter is similar to the Adobe Photoshop Selective Color tool. 17883 17884The filter accepts the following options: 17885 17886@table @option 17887@item correction_method 17888Select color correction method. 17889 17890Available values are: 17891@table @samp 17892@item absolute 17893Specified adjustments are applied "as-is" (added/subtracted to original pixel 17894component value). 17895@item relative 17896Specified adjustments are relative to the original component value. 17897@end table 17898Default is @code{absolute}. 17899@item reds 17900Adjustments for red pixels (pixels where the red component is the maximum) 17901@item yellows 17902Adjustments for yellow pixels (pixels where the blue component is the minimum) 17903@item greens 17904Adjustments for green pixels (pixels where the green component is the maximum) 17905@item cyans 17906Adjustments for cyan pixels (pixels where the red component is the minimum) 17907@item blues 17908Adjustments for blue pixels (pixels where the blue component is the maximum) 17909@item magentas 17910Adjustments for magenta pixels (pixels where the green component is the minimum) 17911@item whites 17912Adjustments for white pixels (pixels where all components are greater than 128) 17913@item neutrals 17914Adjustments for all pixels except pure black and pure white 17915@item blacks 17916Adjustments for black pixels (pixels where all components are lesser than 128) 17917@item psfile 17918Specify a Photoshop selective color file (@code{.asv}) to import the settings from. 17919@end table 17920 17921All the adjustment settings (@option{reds}, @option{yellows}, ...) accept up to 179224 space separated floating point adjustment values in the [-1,1] range, 17923respectively to adjust the amount of cyan, magenta, yellow and black for the 17924pixels of its range. 17925 17926@subsection Examples 17927 17928@itemize 17929@item 17930Increase cyan by 50% and reduce yellow by 33% in every green areas, and 17931increase magenta by 27% in blue areas: 17932@example 17933selectivecolor=greens=.5 0 -.33 0:blues=0 .27 17934@end example 17935 17936@item 17937Use a Photoshop selective color preset: 17938@example 17939selectivecolor=psfile=MySelectiveColorPresets/Misty.asv 17940@end example 17941@end itemize 17942 17943@anchor{separatefields} 17944@section separatefields 17945 17946The @code{separatefields} takes a frame-based video input and splits 17947each frame into its components fields, producing a new half height clip 17948with twice the frame rate and twice the frame count. 17949 17950This filter use field-dominance information in frame to decide which 17951of each pair of fields to place first in the output. 17952If it gets it wrong use @ref{setfield} filter before @code{separatefields} filter. 17953 17954@section setdar, setsar 17955 17956The @code{setdar} filter sets the Display Aspect Ratio for the filter 17957output video. 17958 17959This is done by changing the specified Sample (aka Pixel) Aspect 17960Ratio, according to the following equation: 17961@example 17962@var{DAR} = @var{HORIZONTAL_RESOLUTION} / @var{VERTICAL_RESOLUTION} * @var{SAR} 17963@end example 17964 17965Keep in mind that the @code{setdar} filter does not modify the pixel 17966dimensions of the video frame. Also, the display aspect ratio set by 17967this filter may be changed by later filters in the filterchain, 17968e.g. in case of scaling or if another "setdar" or a "setsar" filter is 17969applied. 17970 17971The @code{setsar} filter sets the Sample (aka Pixel) Aspect Ratio for 17972the filter output video. 17973 17974Note that as a consequence of the application of this filter, the 17975output display aspect ratio will change according to the equation 17976above. 17977 17978Keep in mind that the sample aspect ratio set by the @code{setsar} 17979filter may be changed by later filters in the filterchain, e.g. if 17980another "setsar" or a "setdar" filter is applied. 17981 17982It accepts the following parameters: 17983 17984@table @option 17985@item r, ratio, dar (@code{setdar} only), sar (@code{setsar} only) 17986Set the aspect ratio used by the filter. 17987 17988The parameter can be a floating point number string, an expression, or 17989a string of the form @var{num}:@var{den}, where @var{num} and 17990@var{den} are the numerator and denominator of the aspect ratio. If 17991the parameter is not specified, it is assumed the value "0". 17992In case the form "@var{num}:@var{den}" is used, the @code{:} character 17993should be escaped. 17994 17995@item max 17996Set the maximum integer value to use for expressing numerator and 17997denominator when reducing the expressed aspect ratio to a rational. 17998Default value is @code{100}. 17999 18000@end table 18001 18002The parameter @var{sar} is an expression containing 18003the following constants: 18004 18005@table @option 18006@item E, PI, PHI 18007These are approximated values for the mathematical constants e 18008(Euler's number), pi (Greek pi), and phi (the golden ratio). 18009 18010@item w, h 18011The input width and height. 18012 18013@item a 18014These are the same as @var{w} / @var{h}. 18015 18016@item sar 18017The input sample aspect ratio. 18018 18019@item dar 18020The input display aspect ratio. It is the same as 18021(@var{w} / @var{h}) * @var{sar}. 18022 18023@item hsub, vsub 18024Horizontal and vertical chroma subsample values. For example, for the 18025pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1. 18026@end table 18027 18028@subsection Examples 18029 18030@itemize 18031 18032@item 18033To change the display aspect ratio to 16:9, specify one of the following: 18034@example 18035setdar=dar=1.77777 18036setdar=dar=16/9 18037@end example 18038 18039@item 18040To change the sample aspect ratio to 10:11, specify: 18041@example 18042setsar=sar=10/11 18043@end example 18044 18045@item 18046To set a display aspect ratio of 16:9, and specify a maximum integer value of 180471000 in the aspect ratio reduction, use the command: 18048@example 18049setdar=ratio=16/9:max=1000 18050@end example 18051 18052@end itemize 18053 18054@anchor{setfield} 18055@section setfield 18056 18057Force field for the output video frame. 18058 18059The @code{setfield} filter marks the interlace type field for the 18060output frames. It does not change the input frame, but only sets the 18061corresponding property, which affects how the frame is treated by 18062following filters (e.g. @code{fieldorder} or @code{yadif}). 18063 18064The filter accepts the following options: 18065 18066@table @option 18067 18068@item mode 18069Available values are: 18070 18071@table @samp 18072@item auto 18073Keep the same field property. 18074 18075@item bff 18076Mark the frame as bottom-field-first. 18077 18078@item tff 18079Mark the frame as top-field-first. 18080 18081@item prog 18082Mark the frame as progressive. 18083@end table 18084@end table 18085 18086@anchor{setparams} 18087@section setparams 18088 18089Force frame parameter for the output video frame. 18090 18091The @code{setparams} filter marks interlace and color range for the 18092output frames. It does not change the input frame, but only sets the 18093corresponding property, which affects how the frame is treated by 18094filters/encoders. 18095 18096@table @option 18097@item field_mode 18098Available values are: 18099 18100@table @samp 18101@item auto 18102Keep the same field property (default). 18103 18104@item bff 18105Mark the frame as bottom-field-first. 18106 18107@item tff 18108Mark the frame as top-field-first. 18109 18110@item prog 18111Mark the frame as progressive. 18112@end table 18113 18114@item range 18115Available values are: 18116 18117@table @samp 18118@item auto 18119Keep the same color range property (default). 18120 18121@item unspecified, unknown 18122Mark the frame as unspecified color range. 18123 18124@item limited, tv, mpeg 18125Mark the frame as limited range. 18126 18127@item full, pc, jpeg 18128Mark the frame as full range. 18129@end table 18130 18131@item color_primaries 18132Set the color primaries. 18133Available values are: 18134 18135@table @samp 18136@item auto 18137Keep the same color primaries property (default). 18138 18139@item bt709 18140@item unknown 18141@item bt470m 18142@item bt470bg 18143@item smpte170m 18144@item smpte240m 18145@item film 18146@item bt2020 18147@item smpte428 18148@item smpte431 18149@item smpte432 18150@item jedec-p22 18151@end table 18152 18153@item color_trc 18154Set the color transfer. 18155Available values are: 18156 18157@table @samp 18158@item auto 18159Keep the same color trc property (default). 18160 18161@item bt709 18162@item unknown 18163@item bt470m 18164@item bt470bg 18165@item smpte170m 18166@item smpte240m 18167@item linear 18168@item log100 18169@item log316 18170@item iec61966-2-4 18171@item bt1361e 18172@item iec61966-2-1 18173@item bt2020-10 18174@item bt2020-12 18175@item smpte2084 18176@item smpte428 18177@item arib-std-b67 18178@end table 18179 18180@item colorspace 18181Set the colorspace. 18182Available values are: 18183 18184@table @samp 18185@item auto 18186Keep the same colorspace property (default). 18187 18188@item gbr 18189@item bt709 18190@item unknown 18191@item fcc 18192@item bt470bg 18193@item smpte170m 18194@item smpte240m 18195@item ycgco 18196@item bt2020nc 18197@item bt2020c 18198@item smpte2085 18199@item chroma-derived-nc 18200@item chroma-derived-c 18201@item ictcp 18202@end table 18203@end table 18204 18205@section shear 18206Apply shear transform to input video. 18207 18208This filter supports the following options: 18209 18210@table @option 18211@item shx 18212Shear factor in X-direction. Default value is 0. 18213Allowed range is from -2 to 2. 18214 18215@item shy 18216Shear factor in Y-direction. Default value is 0. 18217Allowed range is from -2 to 2. 18218 18219@item fillcolor, c 18220Set the color used to fill the output area not covered by the transformed 18221video. For the general syntax of this option, check the 18222@ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}. 18223If the special value "none" is selected then no 18224background is printed (useful for example if the background is never shown). 18225 18226Default value is "black". 18227 18228@item interp 18229Set interpolation type. Can be @code{bilinear} or @code{nearest}. Default is @code{bilinear}. 18230@end table 18231 18232@subsection Commands 18233 18234This filter supports the all above options as @ref{commands}. 18235 18236@section showinfo 18237 18238Show a line containing various information for each input video frame. 18239The input video is not modified. 18240 18241This filter supports the following options: 18242 18243@table @option 18244@item checksum 18245Calculate checksums of each plane. By default enabled. 18246@end table 18247 18248The shown line contains a sequence of key/value pairs of the form 18249@var{key}:@var{value}. 18250 18251The following values are shown in the output: 18252 18253@table @option 18254@item n 18255The (sequential) number of the input frame, starting from 0. 18256 18257@item pts 18258The Presentation TimeStamp of the input frame, expressed as a number of 18259time base units. The time base unit depends on the filter input pad. 18260 18261@item pts_time 18262The Presentation TimeStamp of the input frame, expressed as a number of 18263seconds. 18264 18265@item pos 18266The position of the frame in the input stream, or -1 if this information is 18267unavailable and/or meaningless (for example in case of synthetic video). 18268 18269@item fmt 18270The pixel format name. 18271 18272@item sar 18273The sample aspect ratio of the input frame, expressed in the form 18274@var{num}/@var{den}. 18275 18276@item s 18277The size of the input frame. For the syntax of this option, check the 18278@ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}. 18279 18280@item i 18281The type of interlaced mode ("P" for "progressive", "T" for top field first, "B" 18282for bottom field first). 18283 18284@item iskey 18285This is 1 if the frame is a key frame, 0 otherwise. 18286 18287@item type 18288The picture type of the input frame ("I" for an I-frame, "P" for a 18289P-frame, "B" for a B-frame, or "?" for an unknown type). 18290Also refer to the documentation of the @code{AVPictureType} enum and of 18291the @code{av_get_picture_type_char} function defined in 18292@file{libavutil/avutil.h}. 18293 18294@item checksum 18295The Adler-32 checksum (printed in hexadecimal) of all the planes of the input frame. 18296 18297@item plane_checksum 18298The Adler-32 checksum (printed in hexadecimal) of each plane of the input frame, 18299expressed in the form "[@var{c0} @var{c1} @var{c2} @var{c3}]". 18300 18301@item mean 18302The mean value of pixels in each plane of the input frame, expressed in the form 18303"[@var{mean0} @var{mean1} @var{mean2} @var{mean3}]". 18304 18305@item stdev 18306The standard deviation of pixel values in each plane of the input frame, expressed 18307in the form "[@var{stdev0} @var{stdev1} @var{stdev2} @var{stdev3}]". 18308 18309@end table 18310 18311@section showpalette 18312 18313Displays the 256 colors palette of each frame. This filter is only relevant for 18314@var{pal8} pixel format frames. 18315 18316It accepts the following option: 18317 18318@table @option 18319@item s 18320Set the size of the box used to represent one palette color entry. Default is 18321@code{30} (for a @code{30x30} pixel box). 18322@end table 18323 18324@section shuffleframes 18325 18326Reorder and/or duplicate and/or drop video frames. 18327 18328It accepts the following parameters: 18329 18330@table @option 18331@item mapping 18332Set the destination indexes of input frames. 18333This is space or '|' separated list of indexes that maps input frames to output 18334frames. Number of indexes also sets maximal value that each index may have. 18335'-1' index have special meaning and that is to drop frame. 18336@end table 18337 18338The first frame has the index 0. The default is to keep the input unchanged. 18339 18340@subsection Examples 18341 18342@itemize 18343@item 18344Swap second and third frame of every three frames of the input: 18345@example 18346ffmpeg -i INPUT -vf "shuffleframes=0 2 1" OUTPUT 18347@end example 18348 18349@item 18350Swap 10th and 1st frame of every ten frames of the input: 18351@example 18352ffmpeg -i INPUT -vf "shuffleframes=9 1 2 3 4 5 6 7 8 0" OUTPUT 18353@end example 18354@end itemize 18355 18356@section shufflepixels 18357 18358Reorder pixels in video frames. 18359 18360This filter accepts the following options: 18361 18362@table @option 18363@item direction, d 18364Set shuffle direction. Can be forward or inverse direction. 18365Default direction is forward. 18366 18367@item mode, m 18368Set shuffle mode. Can be horizontal, vertical or block mode. 18369 18370@item width, w 18371@item height, h 18372Set shuffle block_size. In case of horizontal shuffle mode only width 18373part of size is used, and in case of vertical shuffle mode only height 18374part of size is used. 18375 18376@item seed, s 18377Set random seed used with shuffling pixels. Mainly useful to set to be able 18378to reverse filtering process to get original input. 18379For example, to reverse forward shuffle you need to use same parameters 18380and exact same seed and to set direction to inverse. 18381@end table 18382 18383@section shuffleplanes 18384 18385Reorder and/or duplicate video planes. 18386 18387It accepts the following parameters: 18388 18389@table @option 18390 18391@item map0 18392The index of the input plane to be used as the first output plane. 18393 18394@item map1 18395The index of the input plane to be used as the second output plane. 18396 18397@item map2 18398The index of the input plane to be used as the third output plane. 18399 18400@item map3 18401The index of the input plane to be used as the fourth output plane. 18402 18403@end table 18404 18405The first plane has the index 0. The default is to keep the input unchanged. 18406 18407@subsection Examples 18408 18409@itemize 18410@item 18411Swap the second and third planes of the input: 18412@example 18413ffmpeg -i INPUT -vf shuffleplanes=0:2:1:3 OUTPUT 18414@end example 18415@end itemize 18416 18417@anchor{signalstats} 18418@section signalstats 18419Evaluate various visual metrics that assist in determining issues associated 18420with the digitization of analog video media. 18421 18422By default the filter will log these metadata values: 18423 18424@table @option 18425@item YMIN 18426Display the minimal Y value contained within the input frame. Expressed in 18427range of [0-255]. 18428 18429@item YLOW 18430Display the Y value at the 10% percentile within the input frame. Expressed in 18431range of [0-255]. 18432 18433@item YAVG 18434Display the average Y value within the input frame. Expressed in range of 18435[0-255]. 18436 18437@item YHIGH 18438Display the Y value at the 90% percentile within the input frame. Expressed in 18439range of [0-255]. 18440 18441@item YMAX 18442Display the maximum Y value contained within the input frame. Expressed in 18443range of [0-255]. 18444 18445@item UMIN 18446Display the minimal U value contained within the input frame. Expressed in 18447range of [0-255]. 18448 18449@item ULOW 18450Display the U value at the 10% percentile within the input frame. Expressed in 18451range of [0-255]. 18452 18453@item UAVG 18454Display the average U value within the input frame. Expressed in range of 18455[0-255]. 18456 18457@item UHIGH 18458Display the U value at the 90% percentile within the input frame. Expressed in 18459range of [0-255]. 18460 18461@item UMAX 18462Display the maximum U value contained within the input frame. Expressed in 18463range of [0-255]. 18464 18465@item VMIN 18466Display the minimal V value contained within the input frame. Expressed in 18467range of [0-255]. 18468 18469@item VLOW 18470Display the V value at the 10% percentile within the input frame. Expressed in 18471range of [0-255]. 18472 18473@item VAVG 18474Display the average V value within the input frame. Expressed in range of 18475[0-255]. 18476 18477@item VHIGH 18478Display the V value at the 90% percentile within the input frame. Expressed in 18479range of [0-255]. 18480 18481@item VMAX 18482Display the maximum V value contained within the input frame. Expressed in 18483range of [0-255]. 18484 18485@item SATMIN 18486Display the minimal saturation value contained within the input frame. 18487Expressed in range of [0-~181.02]. 18488 18489@item SATLOW 18490Display the saturation value at the 10% percentile within the input frame. 18491Expressed in range of [0-~181.02]. 18492 18493@item SATAVG 18494Display the average saturation value within the input frame. Expressed in range 18495of [0-~181.02]. 18496 18497@item SATHIGH 18498Display the saturation value at the 90% percentile within the input frame. 18499Expressed in range of [0-~181.02]. 18500 18501@item SATMAX 18502Display the maximum saturation value contained within the input frame. 18503Expressed in range of [0-~181.02]. 18504 18505@item HUEMED 18506Display the median value for hue within the input frame. Expressed in range of 18507[0-360]. 18508 18509@item HUEAVG 18510Display the average value for hue within the input frame. Expressed in range of 18511[0-360]. 18512 18513@item YDIF 18514Display the average of sample value difference between all values of the Y 18515plane in the current frame and corresponding values of the previous input frame. 18516Expressed in range of [0-255]. 18517 18518@item UDIF 18519Display the average of sample value difference between all values of the U 18520plane in the current frame and corresponding values of the previous input frame. 18521Expressed in range of [0-255]. 18522 18523@item VDIF 18524Display the average of sample value difference between all values of the V 18525plane in the current frame and corresponding values of the previous input frame. 18526Expressed in range of [0-255]. 18527 18528@item YBITDEPTH 18529Display bit depth of Y plane in current frame. 18530Expressed in range of [0-16]. 18531 18532@item UBITDEPTH 18533Display bit depth of U plane in current frame. 18534Expressed in range of [0-16]. 18535 18536@item VBITDEPTH 18537Display bit depth of V plane in current frame. 18538Expressed in range of [0-16]. 18539@end table 18540 18541The filter accepts the following options: 18542 18543@table @option 18544@item stat 18545@item out 18546 18547@option{stat} specify an additional form of image analysis. 18548@option{out} output video with the specified type of pixel highlighted. 18549 18550Both options accept the following values: 18551 18552@table @samp 18553@item tout 18554Identify @var{temporal outliers} pixels. A @var{temporal outlier} is a pixel 18555unlike the neighboring pixels of the same field. Examples of temporal outliers 18556include the results of video dropouts, head clogs, or tape tracking issues. 18557 18558@item vrep 18559Identify @var{vertical line repetition}. Vertical line repetition includes 18560similar rows of pixels within a frame. In born-digital video vertical line 18561repetition is common, but this pattern is uncommon in video digitized from an 18562analog source. When it occurs in video that results from the digitization of an 18563analog source it can indicate concealment from a dropout compensator. 18564 18565@item brng 18566Identify pixels that fall outside of legal broadcast range. 18567@end table 18568 18569@item color, c 18570Set the highlight color for the @option{out} option. The default color is 18571yellow. 18572@end table 18573 18574@subsection Examples 18575 18576@itemize 18577@item 18578Output data of various video metrics: 18579@example 18580ffprobe -f lavfi movie=example.mov,signalstats="stat=tout+vrep+brng" -show_frames 18581@end example 18582 18583@item 18584Output specific data about the minimum and maximum values of the Y plane per frame: 18585@example 18586ffprobe -f lavfi movie=example.mov,signalstats -show_entries frame_tags=lavfi.signalstats.YMAX,lavfi.signalstats.YMIN 18587@end example 18588 18589@item 18590Playback video while highlighting pixels that are outside of broadcast range in red. 18591@example 18592ffplay example.mov -vf signalstats="out=brng:color=red" 18593@end example 18594 18595@item 18596Playback video with signalstats metadata drawn over the frame. 18597@example 18598ffplay example.mov -vf signalstats=stat=brng+vrep+tout,drawtext=fontfile=FreeSerif.ttf:textfile=signalstat_drawtext.txt 18599@end example 18600 18601The contents of signalstat_drawtext.txt used in the command are: 18602@example 18603time %@{pts:hms@} 18604Y (%@{metadata:lavfi.signalstats.YMIN@}-%@{metadata:lavfi.signalstats.YMAX@}) 18605U (%@{metadata:lavfi.signalstats.UMIN@}-%@{metadata:lavfi.signalstats.UMAX@}) 18606V (%@{metadata:lavfi.signalstats.VMIN@}-%@{metadata:lavfi.signalstats.VMAX@}) 18607saturation maximum: %@{metadata:lavfi.signalstats.SATMAX@} 18608 18609@end example 18610@end itemize 18611 18612@anchor{signature} 18613@section signature 18614 18615Calculates the MPEG-7 Video Signature. The filter can handle more than one 18616input. In this case the matching between the inputs can be calculated additionally. 18617The filter always passes through the first input. The signature of each stream can 18618be written into a file. 18619 18620It accepts the following options: 18621 18622@table @option 18623@item detectmode 18624Enable or disable the matching process. 18625 18626Available values are: 18627 18628@table @samp 18629@item off 18630Disable the calculation of a matching (default). 18631@item full 18632Calculate the matching for the whole video and output whether the whole video 18633matches or only parts. 18634@item fast 18635Calculate only until a matching is found or the video ends. Should be faster in 18636some cases. 18637@end table 18638 18639@item nb_inputs 18640Set the number of inputs. The option value must be a non negative integer. 18641Default value is 1. 18642 18643@item filename 18644Set the path to which the output is written. If there is more than one input, 18645the path must be a prototype, i.e. must contain %d or %0nd (where n is a positive 18646integer), that will be replaced with the input number. If no filename is 18647specified, no output will be written. This is the default. 18648 18649@item format 18650Choose the output format. 18651 18652Available values are: 18653 18654@table @samp 18655@item binary 18656Use the specified binary representation (default). 18657@item xml 18658Use the specified xml representation. 18659@end table 18660 18661@item th_d 18662Set threshold to detect one word as similar. The option value must be an integer 18663greater than zero. The default value is 9000. 18664 18665@item th_dc 18666Set threshold to detect all words as similar. The option value must be an integer 18667greater than zero. The default value is 60000. 18668 18669@item th_xh 18670Set threshold to detect frames as similar. The option value must be an integer 18671greater than zero. The default value is 116. 18672 18673@item th_di 18674Set the minimum length of a sequence in frames to recognize it as matching 18675sequence. The option value must be a non negative integer value. 18676The default value is 0. 18677 18678@item th_it 18679Set the minimum relation, that matching frames to all frames must have. 18680The option value must be a double value between 0 and 1. The default value is 0.5. 18681@end table 18682 18683@subsection Examples 18684 18685@itemize 18686@item 18687To calculate the signature of an input video and store it in signature.bin: 18688@example 18689ffmpeg -i input.mkv -vf signature=filename=signature.bin -map 0:v -f null - 18690@end example 18691 18692@item 18693To detect whether two videos match and store the signatures in XML format in 18694signature0.xml and signature1.xml: 18695@example 18696ffmpeg -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 - 18697@end example 18698 18699@end itemize 18700 18701@anchor{smartblur} 18702@section smartblur 18703 18704Blur the input video without impacting the outlines. 18705 18706It accepts the following options: 18707 18708@table @option 18709@item luma_radius, lr 18710Set the luma radius. The option value must be a float number in 18711the range [0.1,5.0] that specifies the variance of the gaussian filter 18712used to blur the image (slower if larger). Default value is 1.0. 18713 18714@item luma_strength, ls 18715Set the luma strength. The option value must be a float number 18716in the range [-1.0,1.0] that configures the blurring. A value included 18717in [0.0,1.0] will blur the image whereas a value included in 18718[-1.0,0.0] will sharpen the image. Default value is 1.0. 18719 18720@item luma_threshold, lt 18721Set the luma threshold used as a coefficient to determine 18722whether a pixel should be blurred or not. The option value must be an 18723integer in the range [-30,30]. A value of 0 will filter all the image, 18724a value included in [0,30] will filter flat areas and a value included 18725in [-30,0] will filter edges. Default value is 0. 18726 18727@item chroma_radius, cr 18728Set the chroma radius. The option value must be a float number in 18729the range [0.1,5.0] that specifies the variance of the gaussian filter 18730used to blur the image (slower if larger). Default value is @option{luma_radius}. 18731 18732@item chroma_strength, cs 18733Set the chroma strength. The option value must be a float number 18734in the range [-1.0,1.0] that configures the blurring. A value included 18735in [0.0,1.0] will blur the image whereas a value included in 18736[-1.0,0.0] will sharpen the image. Default value is @option{luma_strength}. 18737 18738@item chroma_threshold, ct 18739Set the chroma threshold used as a coefficient to determine 18740whether a pixel should be blurred or not. The option value must be an 18741integer in the range [-30,30]. A value of 0 will filter all the image, 18742a value included in [0,30] will filter flat areas and a value included 18743in [-30,0] will filter edges. Default value is @option{luma_threshold}. 18744@end table 18745 18746If a chroma option is not explicitly set, the corresponding luma value 18747is set. 18748 18749@section sobel 18750Apply sobel operator to input video stream. 18751 18752The filter accepts the following option: 18753 18754@table @option 18755@item planes 18756Set which planes will be processed, unprocessed planes will be copied. 18757By default value 0xf, all planes will be processed. 18758 18759@item scale 18760Set value which will be multiplied with filtered result. 18761 18762@item delta 18763Set value which will be added to filtered result. 18764@end table 18765 18766@subsection Commands 18767 18768This filter supports the all above options as @ref{commands}. 18769 18770@anchor{spp} 18771@section spp 18772 18773Apply a simple postprocessing filter that compresses and decompresses the image 18774at several (or - in the case of @option{quality} level @code{6} - all) shifts 18775and average the results. 18776 18777The filter accepts the following options: 18778 18779@table @option 18780@item quality 18781Set quality. This option defines the number of levels for averaging. It accepts 18782an integer in the range 0-6. If set to @code{0}, the filter will have no 18783effect. A value of @code{6} means the higher quality. For each increment of 18784that value the speed drops by a factor of approximately 2. Default value is 18785@code{3}. 18786 18787@item qp 18788Force a constant quantization parameter. If not set, the filter will use the QP 18789from the video stream (if available). 18790 18791@item mode 18792Set thresholding mode. Available modes are: 18793 18794@table @samp 18795@item hard 18796Set hard thresholding (default). 18797@item soft 18798Set soft thresholding (better de-ringing effect, but likely blurrier). 18799@end table 18800 18801@item use_bframe_qp 18802Enable the use of the QP from the B-Frames if set to @code{1}. Using this 18803option may cause flicker since the B-Frames have often larger QP. Default is 18804@code{0} (not enabled). 18805@end table 18806 18807@subsection Commands 18808 18809This filter supports the following commands: 18810@table @option 18811@item quality, level 18812Set quality level. The value @code{max} can be used to set the maximum level, 18813currently @code{6}. 18814@end table 18815 18816@anchor{sr} 18817@section sr 18818 18819Scale the input by applying one of the super-resolution methods based on 18820convolutional neural networks. Supported models: 18821 18822@itemize 18823@item 18824Super-Resolution Convolutional Neural Network model (SRCNN). 18825See @url{https://arxiv.org/abs/1501.00092}. 18826 18827@item 18828Efficient Sub-Pixel Convolutional Neural Network model (ESPCN). 18829See @url{https://arxiv.org/abs/1609.05158}. 18830@end itemize 18831 18832Training scripts as well as scripts for model file (.pb) saving can be found at 18833@url{https://github.com/XueweiMeng/sr/tree/sr_dnn_native}. Original repository 18834is at @url{https://github.com/HighVoltageRocknRoll/sr.git}. 18835 18836Native model files (.model) can be generated from TensorFlow model 18837files (.pb) by using tools/python/convert.py 18838 18839The filter accepts the following options: 18840 18841@table @option 18842@item dnn_backend 18843Specify which DNN backend to use for model loading and execution. This option accepts 18844the following values: 18845 18846@table @samp 18847@item native 18848Native implementation of DNN loading and execution. 18849 18850@item tensorflow 18851TensorFlow backend. To enable this backend you 18852need to install the TensorFlow for C library (see 18853@url{https://www.tensorflow.org/install/install_c}) and configure FFmpeg with 18854@code{--enable-libtensorflow} 18855@end table 18856 18857Default value is @samp{native}. 18858 18859@item model 18860Set path to model file specifying network architecture and its parameters. 18861Note that different backends use different file formats. TensorFlow backend 18862can load files for both formats, while native backend can load files for only 18863its format. 18864 18865@item scale_factor 18866Set scale factor for SRCNN model. Allowed values are @code{2}, @code{3} and @code{4}. 18867Default value is @code{2}. Scale factor is necessary for SRCNN model, because it accepts 18868input upscaled using bicubic upscaling with proper scale factor. 18869@end table 18870 18871This feature can also be finished with @ref{dnn_processing} filter. 18872 18873@section ssim 18874 18875Obtain the SSIM (Structural SImilarity Metric) between two input videos. 18876 18877This filter takes in input two input videos, the first input is 18878considered the "main" source and is passed unchanged to the 18879output. The second input is used as a "reference" video for computing 18880the SSIM. 18881 18882Both video inputs must have the same resolution and pixel format for 18883this filter to work correctly. Also it assumes that both inputs 18884have the same number of frames, which are compared one by one. 18885 18886The filter stores the calculated SSIM of each frame. 18887 18888The description of the accepted parameters follows. 18889 18890@table @option 18891@item stats_file, f 18892If specified the filter will use the named file to save the SSIM of 18893each individual frame. When filename equals "-" the data is sent to 18894standard output. 18895@end table 18896 18897The file printed if @var{stats_file} is selected, contains a sequence of 18898key/value pairs of the form @var{key}:@var{value} for each compared 18899couple of frames. 18900 18901A description of each shown parameter follows: 18902 18903@table @option 18904@item n 18905sequential number of the input frame, starting from 1 18906 18907@item Y, U, V, R, G, B 18908SSIM of the compared frames for the component specified by the suffix. 18909 18910@item All 18911SSIM of the compared frames for the whole frame. 18912 18913@item dB 18914Same as above but in dB representation. 18915@end table 18916 18917This filter also supports the @ref{framesync} options. 18918 18919@subsection Examples 18920@itemize 18921@item 18922For example: 18923@example 18924movie=ref_movie.mpg, setpts=PTS-STARTPTS [main]; 18925[main][ref] ssim="stats_file=stats.log" [out] 18926@end example 18927 18928On this example the input file being processed is compared with the 18929reference file @file{ref_movie.mpg}. The SSIM of each individual frame 18930is stored in @file{stats.log}. 18931 18932@item 18933Another example with both psnr and ssim at same time: 18934@example 18935ffmpeg -i main.mpg -i ref.mpg -lavfi "ssim;[0:v][1:v]psnr" -f null - 18936@end example 18937 18938@item 18939Another example with different containers: 18940@example 18941ffmpeg -i main.mpg -i ref.mkv -lavfi "[0:v]settb=AVTB,setpts=PTS-STARTPTS[main];[1:v]settb=AVTB,setpts=PTS-STARTPTS[ref];[main][ref]ssim" -f null - 18942@end example 18943@end itemize 18944 18945@section stereo3d 18946 18947Convert between different stereoscopic image formats. 18948 18949The filters accept the following options: 18950 18951@table @option 18952@item in 18953Set stereoscopic image format of input. 18954 18955Available values for input image formats are: 18956@table @samp 18957@item sbsl 18958side by side parallel (left eye left, right eye right) 18959 18960@item sbsr 18961side by side crosseye (right eye left, left eye right) 18962 18963@item sbs2l 18964side by side parallel with half width resolution 18965(left eye left, right eye right) 18966 18967@item sbs2r 18968side by side crosseye with half width resolution 18969(right eye left, left eye right) 18970 18971@item abl 18972@item tbl 18973above-below (left eye above, right eye below) 18974 18975@item abr 18976@item tbr 18977above-below (right eye above, left eye below) 18978 18979@item ab2l 18980@item tb2l 18981above-below with half height resolution 18982(left eye above, right eye below) 18983 18984@item ab2r 18985@item tb2r 18986above-below with half height resolution 18987(right eye above, left eye below) 18988 18989@item al 18990alternating frames (left eye first, right eye second) 18991 18992@item ar 18993alternating frames (right eye first, left eye second) 18994 18995@item irl 18996interleaved rows (left eye has top row, right eye starts on next row) 18997 18998@item irr 18999interleaved rows (right eye has top row, left eye starts on next row) 19000 19001@item icl 19002interleaved columns, left eye first 19003 19004@item icr 19005interleaved columns, right eye first 19006 19007Default value is @samp{sbsl}. 19008@end table 19009 19010@item out 19011Set stereoscopic image format of output. 19012 19013@table @samp 19014@item sbsl 19015side by side parallel (left eye left, right eye right) 19016 19017@item sbsr 19018side by side crosseye (right eye left, left eye right) 19019 19020@item sbs2l 19021side by side parallel with half width resolution 19022(left eye left, right eye right) 19023 19024@item sbs2r 19025side by side crosseye with half width resolution 19026(right eye left, left eye right) 19027 19028@item abl 19029@item tbl 19030above-below (left eye above, right eye below) 19031 19032@item abr 19033@item tbr 19034above-below (right eye above, left eye below) 19035 19036@item ab2l 19037@item tb2l 19038above-below with half height resolution 19039(left eye above, right eye below) 19040 19041@item ab2r 19042@item tb2r 19043above-below with half height resolution 19044(right eye above, left eye below) 19045 19046@item al 19047alternating frames (left eye first, right eye second) 19048 19049@item ar 19050alternating frames (right eye first, left eye second) 19051 19052@item irl 19053interleaved rows (left eye has top row, right eye starts on next row) 19054 19055@item irr 19056interleaved rows (right eye has top row, left eye starts on next row) 19057 19058@item arbg 19059anaglyph red/blue gray 19060(red filter on left eye, blue filter on right eye) 19061 19062@item argg 19063anaglyph red/green gray 19064(red filter on left eye, green filter on right eye) 19065 19066@item arcg 19067anaglyph red/cyan gray 19068(red filter on left eye, cyan filter on right eye) 19069 19070@item arch 19071anaglyph red/cyan half colored 19072(red filter on left eye, cyan filter on right eye) 19073 19074@item arcc 19075anaglyph red/cyan color 19076(red filter on left eye, cyan filter on right eye) 19077 19078@item arcd 19079anaglyph red/cyan color optimized with the least squares projection of dubois 19080(red filter on left eye, cyan filter on right eye) 19081 19082@item agmg 19083anaglyph green/magenta gray 19084(green filter on left eye, magenta filter on right eye) 19085 19086@item agmh 19087anaglyph green/magenta half colored 19088(green filter on left eye, magenta filter on right eye) 19089 19090@item agmc 19091anaglyph green/magenta colored 19092(green filter on left eye, magenta filter on right eye) 19093 19094@item agmd 19095anaglyph green/magenta color optimized with the least squares projection of dubois 19096(green filter on left eye, magenta filter on right eye) 19097 19098@item aybg 19099anaglyph yellow/blue gray 19100(yellow filter on left eye, blue filter on right eye) 19101 19102@item aybh 19103anaglyph yellow/blue half colored 19104(yellow filter on left eye, blue filter on right eye) 19105 19106@item aybc 19107anaglyph yellow/blue colored 19108(yellow filter on left eye, blue filter on right eye) 19109 19110@item aybd 19111anaglyph yellow/blue color optimized with the least squares projection of dubois 19112(yellow filter on left eye, blue filter on right eye) 19113 19114@item ml 19115mono output (left eye only) 19116 19117@item mr 19118mono output (right eye only) 19119 19120@item chl 19121checkerboard, left eye first 19122 19123@item chr 19124checkerboard, right eye first 19125 19126@item icl 19127interleaved columns, left eye first 19128 19129@item icr 19130interleaved columns, right eye first 19131 19132@item hdmi 19133HDMI frame pack 19134@end table 19135 19136Default value is @samp{arcd}. 19137@end table 19138 19139@subsection Examples 19140 19141@itemize 19142@item 19143Convert input video from side by side parallel to anaglyph yellow/blue dubois: 19144@example 19145stereo3d=sbsl:aybd 19146@end example 19147 19148@item 19149Convert input video from above below (left eye above, right eye below) to side by side crosseye. 19150@example 19151stereo3d=abl:sbsr 19152@end example 19153@end itemize 19154 19155@section streamselect, astreamselect 19156Select video or audio streams. 19157 19158The filter accepts the following options: 19159 19160@table @option 19161@item inputs 19162Set number of inputs. Default is 2. 19163 19164@item map 19165Set input indexes to remap to outputs. 19166@end table 19167 19168@subsection Commands 19169 19170The @code{streamselect} and @code{astreamselect} filter supports the following 19171commands: 19172 19173@table @option 19174@item map 19175Set input indexes to remap to outputs. 19176@end table 19177 19178@subsection Examples 19179 19180@itemize 19181@item 19182Select first 5 seconds 1st stream and rest of time 2nd stream: 19183@example 19184sendcmd='5.0 streamselect map 1',streamselect=inputs=2:map=0 19185@end example 19186 19187@item 19188Same as above, but for audio: 19189@example 19190asendcmd='5.0 astreamselect map 1',astreamselect=inputs=2:map=0 19191@end example 19192@end itemize 19193 19194@anchor{subtitles} 19195@section subtitles 19196 19197Draw subtitles on top of input video using the libass library. 19198 19199To enable compilation of this filter you need to configure FFmpeg with 19200@code{--enable-libass}. This filter also requires a build with libavcodec and 19201libavformat to convert the passed subtitles file to ASS (Advanced Substation 19202Alpha) subtitles format. 19203 19204The filter accepts the following options: 19205 19206@table @option 19207@item filename, f 19208Set the filename of the subtitle file to read. It must be specified. 19209 19210@item original_size 19211Specify the size of the original video, the video for which the ASS file 19212was composed. For the syntax of this option, check the 19213@ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}. 19214Due to a misdesign in ASS aspect ratio arithmetic, this is necessary to 19215correctly scale the fonts if the aspect ratio has been changed. 19216 19217@item fontsdir 19218Set a directory path containing fonts that can be used by the filter. 19219These fonts will be used in addition to whatever the font provider uses. 19220 19221@item alpha 19222Process alpha channel, by default alpha channel is untouched. 19223 19224@item charenc 19225Set subtitles input character encoding. @code{subtitles} filter only. Only 19226useful if not UTF-8. 19227 19228@item stream_index, si 19229Set subtitles stream index. @code{subtitles} filter only. 19230 19231@item force_style 19232Override default style or script info parameters of the subtitles. It accepts a 19233string containing ASS style format @code{KEY=VALUE} couples separated by ",". 19234@end table 19235 19236If the first key is not specified, it is assumed that the first value 19237specifies the @option{filename}. 19238 19239For example, to render the file @file{sub.srt} on top of the input 19240video, use the command: 19241@example 19242subtitles=sub.srt 19243@end example 19244 19245which is equivalent to: 19246@example 19247subtitles=filename=sub.srt 19248@end example 19249 19250To render the default subtitles stream from file @file{video.mkv}, use: 19251@example 19252subtitles=video.mkv 19253@end example 19254 19255To render the second subtitles stream from that file, use: 19256@example 19257subtitles=video.mkv:si=1 19258@end example 19259 19260To make the subtitles stream from @file{sub.srt} appear in 80% transparent blue 19261@code{DejaVu Serif}, use: 19262@example 19263subtitles=sub.srt:force_style='Fontname=DejaVu Serif,PrimaryColour=&HCCFF0000' 19264@end example 19265 19266@section super2xsai 19267 19268Scale the input by 2x and smooth using the Super2xSaI (Scale and 19269Interpolate) pixel art scaling algorithm. 19270 19271Useful for enlarging pixel art images without reducing sharpness. 19272 19273@section swaprect 19274 19275Swap two rectangular objects in video. 19276 19277This filter accepts the following options: 19278 19279@table @option 19280@item w 19281Set object width. 19282 19283@item h 19284Set object height. 19285 19286@item x1 19287Set 1st rect x coordinate. 19288 19289@item y1 19290Set 1st rect y coordinate. 19291 19292@item x2 19293Set 2nd rect x coordinate. 19294 19295@item y2 19296Set 2nd rect y coordinate. 19297 19298All expressions are evaluated once for each frame. 19299@end table 19300 19301The all options are expressions containing the following constants: 19302 19303@table @option 19304@item w 19305@item h 19306The input width and height. 19307 19308@item a 19309same as @var{w} / @var{h} 19310 19311@item sar 19312input sample aspect ratio 19313 19314@item dar 19315input display aspect ratio, it is the same as (@var{w} / @var{h}) * @var{sar} 19316 19317@item n 19318The number of the input frame, starting from 0. 19319 19320@item t 19321The timestamp expressed in seconds. It's NAN if the input timestamp is unknown. 19322 19323@item pos 19324the position in the file of the input frame, NAN if unknown 19325@end table 19326 19327@subsection Commands 19328 19329This filter supports the all above options as @ref{commands}. 19330 19331@section swapuv 19332Swap U & V plane. 19333 19334@section tblend 19335Blend successive video frames. 19336 19337See @ref{blend} 19338 19339@section telecine 19340 19341Apply telecine process to the video. 19342 19343This filter accepts the following options: 19344 19345@table @option 19346@item first_field 19347@table @samp 19348@item top, t 19349top field first 19350@item bottom, b 19351bottom field first 19352The default value is @code{top}. 19353@end table 19354 19355@item pattern 19356A string of numbers representing the pulldown pattern you wish to apply. 19357The default value is @code{23}. 19358@end table 19359 19360@example 19361Some typical patterns: 19362 19363NTSC output (30i): 1936427.5p: 32222 1936524p: 23 (classic) 1936624p: 2332 (preferred) 1936720p: 33 1936818p: 334 1936916p: 3444 19370 19371PAL output (25i): 1937227.5p: 12222 1937324p: 222222222223 ("Euro pulldown") 1937416.67p: 33 1937516p: 33333334 19376@end example 19377 19378@section thistogram 19379 19380Compute and draw a color distribution histogram for the input video across time. 19381 19382Unlike @ref{histogram} video filter which only shows histogram of single input frame 19383at certain time, this filter shows also past histograms of number of frames defined 19384by @code{width} option. 19385 19386The computed histogram is a representation of the color component 19387distribution in an image. 19388 19389The filter accepts the following options: 19390 19391@table @option 19392@item width, w 19393Set width of single color component output. Default value is @code{0}. 19394Value of @code{0} means width will be picked from input video. 19395This also set number of passed histograms to keep. 19396Allowed range is [0, 8192]. 19397 19398@item display_mode, d 19399Set display mode. 19400It accepts the following values: 19401@table @samp 19402@item stack 19403Per color component graphs are placed below each other. 19404 19405@item parade 19406Per color component graphs are placed side by side. 19407 19408@item overlay 19409Presents information identical to that in the @code{parade}, except 19410that the graphs representing color components are superimposed directly 19411over one another. 19412@end table 19413Default is @code{stack}. 19414 19415@item levels_mode, m 19416Set mode. Can be either @code{linear}, or @code{logarithmic}. 19417Default is @code{linear}. 19418 19419@item components, c 19420Set what color components to display. 19421Default is @code{7}. 19422 19423@item bgopacity, b 19424Set background opacity. Default is @code{0.9}. 19425 19426@item envelope, e 19427Show envelope. Default is disabled. 19428 19429@item ecolor, ec 19430Set envelope color. Default is @code{gold}. 19431 19432@item slide 19433Set slide mode. 19434 19435Available values for slide is: 19436@table @samp 19437@item frame 19438Draw new frame when right border is reached. 19439 19440@item replace 19441Replace old columns with new ones. 19442 19443@item scroll 19444Scroll from right to left. 19445 19446@item rscroll 19447Scroll from left to right. 19448 19449@item picture 19450Draw single picture. 19451@end table 19452 19453Default is @code{replace}. 19454@end table 19455 19456@section threshold 19457 19458Apply threshold effect to video stream. 19459 19460This filter needs four video streams to perform thresholding. 19461First stream is stream we are filtering. 19462Second stream is holding threshold values, third stream is holding min values, 19463and last, fourth stream is holding max values. 19464 19465The filter accepts the following option: 19466 19467@table @option 19468@item planes 19469Set which planes will be processed, unprocessed planes will be copied. 19470By default value 0xf, all planes will be processed. 19471@end table 19472 19473For example if first stream pixel's component value is less then threshold value 19474of pixel component from 2nd threshold stream, third stream value will picked, 19475otherwise fourth stream pixel component value will be picked. 19476 19477Using color source filter one can perform various types of thresholding: 19478 19479@subsection Examples 19480 19481@itemize 19482@item 19483Binary threshold, using gray color as threshold: 19484@example 19485ffmpeg -i 320x240.avi -f lavfi -i color=gray -f lavfi -i color=black -f lavfi -i color=white -lavfi threshold output.avi 19486@end example 19487 19488@item 19489Inverted binary threshold, using gray color as threshold: 19490@example 19491ffmpeg -i 320x240.avi -f lavfi -i color=gray -f lavfi -i color=white -f lavfi -i color=black -lavfi threshold output.avi 19492@end example 19493 19494@item 19495Truncate binary threshold, using gray color as threshold: 19496@example 19497ffmpeg -i 320x240.avi -f lavfi -i color=gray -i 320x240.avi -f lavfi -i color=gray -lavfi threshold output.avi 19498@end example 19499 19500@item 19501Threshold to zero, using gray color as threshold: 19502@example 19503ffmpeg -i 320x240.avi -f lavfi -i color=gray -f lavfi -i color=white -i 320x240.avi -lavfi threshold output.avi 19504@end example 19505 19506@item 19507Inverted threshold to zero, using gray color as threshold: 19508@example 19509ffmpeg -i 320x240.avi -f lavfi -i color=gray -i 320x240.avi -f lavfi -i color=white -lavfi threshold output.avi 19510@end example 19511@end itemize 19512 19513@section thumbnail 19514Select the most representative frame in a given sequence of consecutive frames. 19515 19516The filter accepts the following options: 19517 19518@table @option 19519@item n 19520Set the frames batch size to analyze; in a set of @var{n} frames, the filter 19521will pick one of them, and then handle the next batch of @var{n} frames until 19522the end. Default is @code{100}. 19523@end table 19524 19525Since the filter keeps track of the whole frames sequence, a bigger @var{n} 19526value will result in a higher memory usage, so a high value is not recommended. 19527 19528@subsection Examples 19529 19530@itemize 19531@item 19532Extract one picture each 50 frames: 19533@example 19534thumbnail=50 19535@end example 19536 19537@item 19538Complete example of a thumbnail creation with @command{ffmpeg}: 19539@example 19540ffmpeg -i in.avi -vf thumbnail,scale=300:200 -frames:v 1 out.png 19541@end example 19542@end itemize 19543 19544@anchor{tile} 19545@section tile 19546 19547Tile several successive frames together. 19548 19549The @ref{untile} filter can do the reverse. 19550 19551The filter accepts the following options: 19552 19553@table @option 19554 19555@item layout 19556Set the grid size (i.e. the number of lines and columns). For the syntax of 19557this option, check the 19558@ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}. 19559 19560@item nb_frames 19561Set the maximum number of frames to render in the given area. It must be less 19562than or equal to @var{w}x@var{h}. The default value is @code{0}, meaning all 19563the area will be used. 19564 19565@item margin 19566Set the outer border margin in pixels. 19567 19568@item padding 19569Set the inner border thickness (i.e. the number of pixels between frames). For 19570more advanced padding options (such as having different values for the edges), 19571refer to the pad video filter. 19572 19573@item color 19574Specify the color of the unused area. For the syntax of this option, check the 19575@ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}. 19576The default value of @var{color} is "black". 19577 19578@item overlap 19579Set the number of frames to overlap when tiling several successive frames together. 19580The value must be between @code{0} and @var{nb_frames - 1}. 19581 19582@item init_padding 19583Set the number of frames to initially be empty before displaying first output frame. 19584This controls how soon will one get first output frame. 19585The value must be between @code{0} and @var{nb_frames - 1}. 19586@end table 19587 19588@subsection Examples 19589 19590@itemize 19591@item 19592Produce 8x8 PNG tiles of all keyframes (@option{-skip_frame nokey}) in a movie: 19593@example 19594ffmpeg -skip_frame nokey -i file.avi -vf 'scale=128:72,tile=8x8' -an -vsync 0 keyframes%03d.png 19595@end example 19596The @option{-vsync 0} is necessary to prevent @command{ffmpeg} from 19597duplicating each output frame to accommodate the originally detected frame 19598rate. 19599 19600@item 19601Display @code{5} pictures in an area of @code{3x2} frames, 19602with @code{7} pixels between them, and @code{2} pixels of initial margin, using 19603mixed flat and named options: 19604@example 19605tile=3x2:nb_frames=5:padding=7:margin=2 19606@end example 19607@end itemize 19608 19609@section tinterlace 19610 19611Perform various types of temporal field interlacing. 19612 19613Frames are counted starting from 1, so the first input frame is 19614considered odd. 19615 19616The filter accepts the following options: 19617 19618@table @option 19619 19620@item mode 19621Specify the mode of the interlacing. This option can also be specified 19622as a value alone. See below for a list of values for this option. 19623 19624Available values are: 19625 19626@table @samp 19627@item merge, 0 19628Move odd frames into the upper field, even into the lower field, 19629generating a double height frame at half frame rate. 19630@example 19631 ------> time 19632Input: 19633Frame 1 Frame 2 Frame 3 Frame 4 19634 1963511111 22222 33333 44444 1963611111 22222 33333 44444 1963711111 22222 33333 44444 1963811111 22222 33333 44444 19639 19640Output: 1964111111 33333 1964222222 44444 1964311111 33333 1964422222 44444 1964511111 33333 1964622222 44444 1964711111 33333 1964822222 44444 19649@end example 19650 19651@item drop_even, 1 19652Only output odd frames, even frames are dropped, generating a frame with 19653unchanged height at half frame rate. 19654 19655@example 19656 ------> time 19657Input: 19658Frame 1 Frame 2 Frame 3 Frame 4 19659 1966011111 22222 33333 44444 1966111111 22222 33333 44444 1966211111 22222 33333 44444 1966311111 22222 33333 44444 19664 19665Output: 1966611111 33333 1966711111 33333 1966811111 33333 1966911111 33333 19670@end example 19671 19672@item drop_odd, 2 19673Only output even frames, odd frames are dropped, generating a frame with 19674unchanged height at half frame rate. 19675 19676@example 19677 ------> time 19678Input: 19679Frame 1 Frame 2 Frame 3 Frame 4 19680 1968111111 22222 33333 44444 1968211111 22222 33333 44444 1968311111 22222 33333 44444 1968411111 22222 33333 44444 19685 19686Output: 19687 22222 44444 19688 22222 44444 19689 22222 44444 19690 22222 44444 19691@end example 19692 19693@item pad, 3 19694Expand each frame to full height, but pad alternate lines with black, 19695generating a frame with double height at the same input frame rate. 19696 19697@example 19698 ------> time 19699Input: 19700Frame 1 Frame 2 Frame 3 Frame 4 19701 1970211111 22222 33333 44444 1970311111 22222 33333 44444 1970411111 22222 33333 44444 1970511111 22222 33333 44444 19706 19707Output: 1970811111 ..... 33333 ..... 19709..... 22222 ..... 44444 1971011111 ..... 33333 ..... 19711..... 22222 ..... 44444 1971211111 ..... 33333 ..... 19713..... 22222 ..... 44444 1971411111 ..... 33333 ..... 19715..... 22222 ..... 44444 19716@end example 19717 19718 19719@item interleave_top, 4 19720Interleave the upper field from odd frames with the lower field from 19721even frames, generating a frame with unchanged height at half frame rate. 19722 19723@example 19724 ------> time 19725Input: 19726Frame 1 Frame 2 Frame 3 Frame 4 19727 1972811111<- 22222 33333<- 44444 1972911111 22222<- 33333 44444<- 1973011111<- 22222 33333<- 44444 1973111111 22222<- 33333 44444<- 19732 19733Output: 1973411111 33333 1973522222 44444 1973611111 33333 1973722222 44444 19738@end example 19739 19740 19741@item interleave_bottom, 5 19742Interleave the lower field from odd frames with the upper field from 19743even frames, generating a frame with unchanged height at half frame rate. 19744 19745@example 19746 ------> time 19747Input: 19748Frame 1 Frame 2 Frame 3 Frame 4 19749 1975011111 22222<- 33333 44444<- 1975111111<- 22222 33333<- 44444 1975211111 22222<- 33333 44444<- 1975311111<- 22222 33333<- 44444 19754 19755Output: 1975622222 44444 1975711111 33333 1975822222 44444 1975911111 33333 19760@end example 19761 19762 19763@item interlacex2, 6 19764Double frame rate with unchanged height. Frames are inserted each 19765containing the second temporal field from the previous input frame and 19766the first temporal field from the next input frame. This mode relies on 19767the top_field_first flag. Useful for interlaced video displays with no 19768field synchronisation. 19769 19770@example 19771 ------> time 19772Input: 19773Frame 1 Frame 2 Frame 3 Frame 4 19774 1977511111 22222 33333 44444 19776 11111 22222 33333 44444 1977711111 22222 33333 44444 19778 11111 22222 33333 44444 19779 19780Output: 1978111111 22222 22222 33333 33333 44444 44444 19782 11111 11111 22222 22222 33333 33333 44444 1978311111 22222 22222 33333 33333 44444 44444 19784 11111 11111 22222 22222 33333 33333 44444 19785@end example 19786 19787 19788@item mergex2, 7 19789Move odd frames into the upper field, even into the lower field, 19790generating a double height frame at same frame rate. 19791 19792@example 19793 ------> time 19794Input: 19795Frame 1 Frame 2 Frame 3 Frame 4 19796 1979711111 22222 33333 44444 1979811111 22222 33333 44444 1979911111 22222 33333 44444 1980011111 22222 33333 44444 19801 19802Output: 1980311111 33333 33333 55555 1980422222 22222 44444 44444 1980511111 33333 33333 55555 1980622222 22222 44444 44444 1980711111 33333 33333 55555 1980822222 22222 44444 44444 1980911111 33333 33333 55555 1981022222 22222 44444 44444 19811@end example 19812 19813@end table 19814 19815Numeric values are deprecated but are accepted for backward 19816compatibility reasons. 19817 19818Default mode is @code{merge}. 19819 19820@item flags 19821Specify flags influencing the filter process. 19822 19823Available value for @var{flags} is: 19824 19825@table @option 19826@item low_pass_filter, vlpf 19827Enable linear vertical low-pass filtering in the filter. 19828Vertical low-pass filtering is required when creating an interlaced 19829destination from a progressive source which contains high-frequency 19830vertical detail. Filtering will reduce interlace 'twitter' and Moire 19831patterning. 19832 19833@item complex_filter, cvlpf 19834Enable complex vertical low-pass filtering. 19835This will slightly less reduce interlace 'twitter' and Moire 19836patterning but better retain detail and subjective sharpness impression. 19837 19838@item bypass_il 19839Bypass already interlaced frames, only adjust the frame rate. 19840@end table 19841 19842Vertical low-pass filtering and bypassing already interlaced frames can only be 19843enabled for @option{mode} @var{interleave_top} and @var{interleave_bottom}. 19844 19845@end table 19846 19847@section tmedian 19848Pick median pixels from several successive input video frames. 19849 19850The filter accepts the following options: 19851 19852@table @option 19853@item radius 19854Set radius of median filter. 19855Default is 1. Allowed range is from 1 to 127. 19856 19857@item planes 19858Set which planes to filter. Default value is @code{15}, by which all planes are processed. 19859 19860@item percentile 19861Set median percentile. Default value is @code{0.5}. 19862Default value of @code{0.5} will pick always median values, while @code{0} will pick 19863minimum values, and @code{1} maximum values. 19864@end table 19865 19866@subsection Commands 19867 19868This filter supports all above options as @ref{commands}, excluding option @code{radius}. 19869 19870@section tmidequalizer 19871 19872Apply Temporal Midway Video Equalization effect. 19873 19874Midway Video Equalization adjusts a sequence of video frames to have the same 19875histograms, while maintaining their dynamics as much as possible. It's 19876useful for e.g. matching exposures from a video frames sequence. 19877 19878This filter accepts the following option: 19879 19880@table @option 19881@item radius 19882Set filtering radius. Default is @code{5}. Allowed range is from 1 to 127. 19883 19884@item sigma 19885Set filtering sigma. Default is @code{0.5}. This controls strength of filtering. 19886Setting this option to 0 effectively does nothing. 19887 19888@item planes 19889Set which planes to process. Default is @code{15}, which is all available planes. 19890@end table 19891 19892@section tmix 19893 19894Mix successive video frames. 19895 19896A description of the accepted options follows. 19897 19898@table @option 19899@item frames 19900The number of successive frames to mix. If unspecified, it defaults to 3. 19901 19902@item weights 19903Specify weight of each input video frame. 19904Each weight is separated by space. If number of weights is smaller than 19905number of @var{frames} last specified weight will be used for all remaining 19906unset weights. 19907 19908@item scale 19909Specify scale, if it is set it will be multiplied with sum 19910of each weight multiplied with pixel values to give final destination 19911pixel value. By default @var{scale} is auto scaled to sum of weights. 19912@end table 19913 19914@subsection Examples 19915 19916@itemize 19917@item 19918Average 7 successive frames: 19919@example 19920tmix=frames=7:weights="1 1 1 1 1 1 1" 19921@end example 19922 19923@item 19924Apply simple temporal convolution: 19925@example 19926tmix=frames=3:weights="-1 3 -1" 19927@end example 19928 19929@item 19930Similar as above but only showing temporal differences: 19931@example 19932tmix=frames=3:weights="-1 2 -1":scale=1 19933@end example 19934@end itemize 19935 19936@subsection Commands 19937 19938This filter supports the following commands: 19939@table @option 19940@item weights 19941@item scale 19942Syntax is same as option with same name. 19943@end table 19944 19945@anchor{tonemap} 19946@section tonemap 19947Tone map colors from different dynamic ranges. 19948 19949This filter expects data in single precision floating point, as it needs to 19950operate on (and can output) out-of-range values. Another filter, such as 19951@ref{zscale}, is needed to convert the resulting frame to a usable format. 19952 19953The tonemapping algorithms implemented only work on linear light, so input 19954data should be linearized beforehand (and possibly correctly tagged). 19955 19956@example 19957ffmpeg -i INPUT -vf zscale=transfer=linear,tonemap=clip,zscale=transfer=bt709,format=yuv420p OUTPUT 19958@end example 19959 19960@subsection Options 19961The filter accepts the following options. 19962 19963@table @option 19964@item tonemap 19965Set the tone map algorithm to use. 19966 19967Possible values are: 19968@table @var 19969@item none 19970Do not apply any tone map, only desaturate overbright pixels. 19971 19972@item clip 19973Hard-clip any out-of-range values. Use it for perfect color accuracy for 19974in-range values, while distorting out-of-range values. 19975 19976@item linear 19977Stretch the entire reference gamut to a linear multiple of the display. 19978 19979@item gamma 19980Fit a logarithmic transfer between the tone curves. 19981 19982@item reinhard 19983Preserve overall image brightness with a simple curve, using nonlinear 19984contrast, which results in flattening details and degrading color accuracy. 19985 19986@item hable 19987Preserve both dark and bright details better than @var{reinhard}, at the cost 19988of slightly darkening everything. Use it when detail preservation is more 19989important than color and brightness accuracy. 19990 19991@item mobius 19992Smoothly map out-of-range values, while retaining contrast and colors for 19993in-range material as much as possible. Use it when color accuracy is more 19994important than detail preservation. 19995@end table 19996 19997Default is none. 19998 19999@item param 20000Tune the tone mapping algorithm. 20001 20002This affects the following algorithms: 20003@table @var 20004@item none 20005Ignored. 20006 20007@item linear 20008Specifies the scale factor to use while stretching. 20009Default to 1.0. 20010 20011@item gamma 20012Specifies the exponent of the function. 20013Default to 1.8. 20014 20015@item clip 20016Specify an extra linear coefficient to multiply into the signal before clipping. 20017Default to 1.0. 20018 20019@item reinhard 20020Specify the local contrast coefficient at the display peak. 20021Default to 0.5, which means that in-gamut values will be about half as bright 20022as when clipping. 20023 20024@item hable 20025Ignored. 20026 20027@item mobius 20028Specify the transition point from linear to mobius transform. Every value 20029below this point is guaranteed to be mapped 1:1. The higher the value, the 20030more accurate the result will be, at the cost of losing bright details. 20031Default to 0.3, which due to the steep initial slope still preserves in-range 20032colors fairly accurately. 20033@end table 20034 20035@item desat 20036Apply desaturation for highlights that exceed this level of brightness. The 20037higher the parameter, the more color information will be preserved. This 20038setting helps prevent unnaturally blown-out colors for super-highlights, by 20039(smoothly) turning into white instead. This makes images feel more natural, 20040at the cost of reducing information about out-of-range colors. 20041 20042The default of 2.0 is somewhat conservative and will mostly just apply to 20043skies or directly sunlit surfaces. A setting of 0.0 disables this option. 20044 20045This option works only if the input frame has a supported color tag. 20046 20047@item peak 20048Override signal/nominal/reference peak with this value. Useful when the 20049embedded peak information in display metadata is not reliable or when tone 20050mapping from a lower range to a higher range. 20051@end table 20052 20053@section tpad 20054 20055Temporarily pad video frames. 20056 20057The filter accepts the following options: 20058 20059@table @option 20060@item start 20061Specify number of delay frames before input video stream. Default is 0. 20062 20063@item stop 20064Specify number of padding frames after input video stream. 20065Set to -1 to pad indefinitely. Default is 0. 20066 20067@item start_mode 20068Set kind of frames added to beginning of stream. 20069Can be either @var{add} or @var{clone}. 20070With @var{add} frames of solid-color are added. 20071With @var{clone} frames are clones of first frame. 20072Default is @var{add}. 20073 20074@item stop_mode 20075Set kind of frames added to end of stream. 20076Can be either @var{add} or @var{clone}. 20077With @var{add} frames of solid-color are added. 20078With @var{clone} frames are clones of last frame. 20079Default is @var{add}. 20080 20081@item start_duration, stop_duration 20082Specify the duration of the start/stop delay. See 20083@ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils} 20084for the accepted syntax. 20085These options override @var{start} and @var{stop}. Default is 0. 20086 20087@item color 20088Specify the color of the padded area. For the syntax of this option, 20089check the @ref{color syntax,,"Color" section in the ffmpeg-utils 20090manual,ffmpeg-utils}. 20091 20092The default value of @var{color} is "black". 20093@end table 20094 20095@anchor{transpose} 20096@section transpose 20097 20098Transpose rows with columns in the input video and optionally flip it. 20099 20100It accepts the following parameters: 20101 20102@table @option 20103 20104@item dir 20105Specify the transposition direction. 20106 20107Can assume the following values: 20108@table @samp 20109@item 0, 4, cclock_flip 20110Rotate by 90 degrees counterclockwise and vertically flip (default), that is: 20111@example 20112L.R L.l 20113. . -> . . 20114l.r R.r 20115@end example 20116 20117@item 1, 5, clock 20118Rotate by 90 degrees clockwise, that is: 20119@example 20120L.R l.L 20121. . -> . . 20122l.r r.R 20123@end example 20124 20125@item 2, 6, cclock 20126Rotate by 90 degrees counterclockwise, that is: 20127@example 20128L.R R.r 20129. . -> . . 20130l.r L.l 20131@end example 20132 20133@item 3, 7, clock_flip 20134Rotate by 90 degrees clockwise and vertically flip, that is: 20135@example 20136L.R r.R 20137. . -> . . 20138l.r l.L 20139@end example 20140@end table 20141 20142For values between 4-7, the transposition is only done if the input 20143video geometry is portrait and not landscape. These values are 20144deprecated, the @code{passthrough} option should be used instead. 20145 20146Numerical values are deprecated, and should be dropped in favor of 20147symbolic constants. 20148 20149@item passthrough 20150Do not apply the transposition if the input geometry matches the one 20151specified by the specified value. It accepts the following values: 20152@table @samp 20153@item none 20154Always apply transposition. 20155@item portrait 20156Preserve portrait geometry (when @var{height} >= @var{width}). 20157@item landscape 20158Preserve landscape geometry (when @var{width} >= @var{height}). 20159@end table 20160 20161Default value is @code{none}. 20162@end table 20163 20164For example to rotate by 90 degrees clockwise and preserve portrait 20165layout: 20166@example 20167transpose=dir=1:passthrough=portrait 20168@end example 20169 20170The command above can also be specified as: 20171@example 20172transpose=1:portrait 20173@end example 20174 20175@section transpose_npp 20176 20177Transpose rows with columns in the input video and optionally flip it. 20178For more in depth examples see the @ref{transpose} video filter, which shares mostly the same options. 20179 20180It accepts the following parameters: 20181 20182@table @option 20183 20184@item dir 20185Specify the transposition direction. 20186 20187Can assume the following values: 20188@table @samp 20189@item cclock_flip 20190Rotate by 90 degrees counterclockwise and vertically flip. (default) 20191 20192@item clock 20193Rotate by 90 degrees clockwise. 20194 20195@item cclock 20196Rotate by 90 degrees counterclockwise. 20197 20198@item clock_flip 20199Rotate by 90 degrees clockwise and vertically flip. 20200@end table 20201 20202@item passthrough 20203Do not apply the transposition if the input geometry matches the one 20204specified by the specified value. It accepts the following values: 20205@table @samp 20206@item none 20207Always apply transposition. (default) 20208@item portrait 20209Preserve portrait geometry (when @var{height} >= @var{width}). 20210@item landscape 20211Preserve landscape geometry (when @var{width} >= @var{height}). 20212@end table 20213 20214@end table 20215 20216@section trim 20217Trim the input so that the output contains one continuous subpart of the input. 20218 20219It accepts the following parameters: 20220@table @option 20221@item start 20222Specify the time of the start of the kept section, i.e. the frame with the 20223timestamp @var{start} will be the first frame in the output. 20224 20225@item end 20226Specify the time of the first frame that will be dropped, i.e. the frame 20227immediately preceding the one with the timestamp @var{end} will be the last 20228frame in the output. 20229 20230@item start_pts 20231This is the same as @var{start}, except this option sets the start timestamp 20232in timebase units instead of seconds. 20233 20234@item end_pts 20235This is the same as @var{end}, except this option sets the end timestamp 20236in timebase units instead of seconds. 20237 20238@item duration 20239The maximum duration of the output in seconds. 20240 20241@item start_frame 20242The number of the first frame that should be passed to the output. 20243 20244@item end_frame 20245The number of the first frame that should be dropped. 20246@end table 20247 20248@option{start}, @option{end}, and @option{duration} are expressed as time 20249duration specifications; see 20250@ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils} 20251for the accepted syntax. 20252 20253Note that the first two sets of the start/end options and the @option{duration} 20254option look at the frame timestamp, while the _frame variants simply count the 20255frames that pass through the filter. Also note that this filter does not modify 20256the timestamps. If you wish for the output timestamps to start at zero, insert a 20257setpts filter after the trim filter. 20258 20259If multiple start or end options are set, this filter tries to be greedy and 20260keep all the frames that match at least one of the specified constraints. To keep 20261only the part that matches all the constraints at once, chain multiple trim 20262filters. 20263 20264The defaults are such that all the input is kept. So it is possible to set e.g. 20265just the end values to keep everything before the specified time. 20266 20267Examples: 20268@itemize 20269@item 20270Drop everything except the second minute of input: 20271@example 20272ffmpeg -i INPUT -vf trim=60:120 20273@end example 20274 20275@item 20276Keep only the first second: 20277@example 20278ffmpeg -i INPUT -vf trim=duration=1 20279@end example 20280 20281@end itemize 20282 20283@section unpremultiply 20284Apply alpha unpremultiply effect to input video stream using first plane 20285of second stream as alpha. 20286 20287Both streams must have same dimensions and same pixel format. 20288 20289The filter accepts the following option: 20290 20291@table @option 20292@item planes 20293Set which planes will be processed, unprocessed planes will be copied. 20294By default value 0xf, all planes will be processed. 20295 20296If the format has 1 or 2 components, then luma is bit 0. 20297If the format has 3 or 4 components: 20298for RGB formats bit 0 is green, bit 1 is blue and bit 2 is red; 20299for YUV formats bit 0 is luma, bit 1 is chroma-U and bit 2 is chroma-V. 20300If present, the alpha channel is always the last bit. 20301 20302@item inplace 20303Do not require 2nd input for processing, instead use alpha plane from input stream. 20304@end table 20305 20306@anchor{unsharp} 20307@section unsharp 20308 20309Sharpen or blur the input video. 20310 20311It accepts the following parameters: 20312 20313@table @option 20314@item luma_msize_x, lx 20315Set the luma matrix horizontal size. It must be an odd integer between 203163 and 23. The default value is 5. 20317 20318@item luma_msize_y, ly 20319Set the luma matrix vertical size. It must be an odd integer between 3 20320and 23. The default value is 5. 20321 20322@item luma_amount, la 20323Set the luma effect strength. It must be a floating point number, reasonable 20324values lay between -1.5 and 1.5. 20325 20326Negative values will blur the input video, while positive values will 20327sharpen it, a value of zero will disable the effect. 20328 20329Default value is 1.0. 20330 20331@item chroma_msize_x, cx 20332Set the chroma matrix horizontal size. It must be an odd integer 20333between 3 and 23. The default value is 5. 20334 20335@item chroma_msize_y, cy 20336Set the chroma matrix vertical size. It must be an odd integer 20337between 3 and 23. The default value is 5. 20338 20339@item chroma_amount, ca 20340Set the chroma effect strength. It must be a floating point number, reasonable 20341values lay between -1.5 and 1.5. 20342 20343Negative values will blur the input video, while positive values will 20344sharpen it, a value of zero will disable the effect. 20345 20346Default value is 0.0. 20347 20348@end table 20349 20350All parameters are optional and default to the equivalent of the 20351string '5:5:1.0:5:5:0.0'. 20352 20353@subsection Examples 20354 20355@itemize 20356@item 20357Apply strong luma sharpen effect: 20358@example 20359unsharp=luma_msize_x=7:luma_msize_y=7:luma_amount=2.5 20360@end example 20361 20362@item 20363Apply a strong blur of both luma and chroma parameters: 20364@example 20365unsharp=7:7:-2:7:7:-2 20366@end example 20367@end itemize 20368 20369@anchor{untile} 20370@section untile 20371 20372Decompose a video made of tiled images into the individual images. 20373 20374The frame rate of the output video is the frame rate of the input video 20375multiplied by the number of tiles. 20376 20377This filter does the reverse of @ref{tile}. 20378 20379The filter accepts the following options: 20380 20381@table @option 20382 20383@item layout 20384Set the grid size (i.e. the number of lines and columns). For the syntax of 20385this option, check the 20386@ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}. 20387@end table 20388 20389@subsection Examples 20390 20391@itemize 20392@item 20393Produce a 1-second video from a still image file made of 25 frames stacked 20394vertically, like an analogic film reel: 20395@example 20396ffmpeg -r 1 -i image.jpg -vf untile=1x25 movie.mkv 20397@end example 20398@end itemize 20399 20400@section uspp 20401 20402Apply ultra slow/simple postprocessing filter that compresses and decompresses 20403the image at several (or - in the case of @option{quality} level @code{8} - all) 20404shifts and average the results. 20405 20406The way this differs from the behavior of spp is that uspp actually encodes & 20407decodes each case with libavcodec Snow, whereas spp uses a simplified intra only 8x8 20408DCT similar to MJPEG. 20409 20410The filter accepts the following options: 20411 20412@table @option 20413@item quality 20414Set quality. This option defines the number of levels for averaging. It accepts 20415an integer in the range 0-8. If set to @code{0}, the filter will have no 20416effect. A value of @code{8} means the higher quality. For each increment of 20417that value the speed drops by a factor of approximately 2. Default value is 20418@code{3}. 20419 20420@item qp 20421Force a constant quantization parameter. If not set, the filter will use the QP 20422from the video stream (if available). 20423@end table 20424 20425@section v360 20426 20427Convert 360 videos between various formats. 20428 20429The filter accepts the following options: 20430 20431@table @option 20432 20433@item input 20434@item output 20435Set format of the input/output video. 20436 20437Available formats: 20438 20439@table @samp 20440 20441@item e 20442@item equirect 20443Equirectangular projection. 20444 20445@item c3x2 20446@item c6x1 20447@item c1x6 20448Cubemap with 3x2/6x1/1x6 layout. 20449 20450Format specific options: 20451 20452@table @option 20453@item in_pad 20454@item out_pad 20455Set padding proportion for the input/output cubemap. Values in decimals. 20456 20457Example values: 20458@table @samp 20459@item 0 20460No padding. 20461@item 0.01 204621% of face is padding. For example, with 1920x1280 resolution face size would be 640x640 and padding would be 3 pixels from each side. (640 * 0.01 = 6 pixels) 20463@end table 20464 20465Default value is @b{@samp{0}}. 20466Maximum value is @b{@samp{0.1}}. 20467 20468@item fin_pad 20469@item fout_pad 20470Set fixed padding for the input/output cubemap. Values in pixels. 20471 20472Default value is @b{@samp{0}}. If greater than zero it overrides other padding options. 20473 20474@item in_forder 20475@item out_forder 20476Set order of faces for the input/output cubemap. Choose one direction for each position. 20477 20478Designation of directions: 20479@table @samp 20480@item r 20481right 20482@item l 20483left 20484@item u 20485up 20486@item d 20487down 20488@item f 20489forward 20490@item b 20491back 20492@end table 20493 20494Default value is @b{@samp{rludfb}}. 20495 20496@item in_frot 20497@item out_frot 20498Set rotation of faces for the input/output cubemap. Choose one angle for each position. 20499 20500Designation of angles: 20501@table @samp 20502@item 0 205030 degrees clockwise 20504@item 1 2050590 degrees clockwise 20506@item 2 20507180 degrees clockwise 20508@item 3 20509270 degrees clockwise 20510@end table 20511 20512Default value is @b{@samp{000000}}. 20513@end table 20514 20515@item eac 20516Equi-Angular Cubemap. 20517 20518@item flat 20519@item gnomonic 20520@item rectilinear 20521Regular video. 20522 20523Format specific options: 20524@table @option 20525@item h_fov 20526@item v_fov 20527@item d_fov 20528Set output horizontal/vertical/diagonal field of view. Values in degrees. 20529 20530If diagonal field of view is set it overrides horizontal and vertical field of view. 20531 20532@item ih_fov 20533@item iv_fov 20534@item id_fov 20535Set input horizontal/vertical/diagonal field of view. Values in degrees. 20536 20537If diagonal field of view is set it overrides horizontal and vertical field of view. 20538@end table 20539 20540@item dfisheye 20541Dual fisheye. 20542 20543Format specific options: 20544@table @option 20545@item h_fov 20546@item v_fov 20547@item d_fov 20548Set output horizontal/vertical/diagonal field of view. Values in degrees. 20549 20550If diagonal field of view is set it overrides horizontal and vertical field of view. 20551 20552@item ih_fov 20553@item iv_fov 20554@item id_fov 20555Set input horizontal/vertical/diagonal field of view. Values in degrees. 20556 20557If diagonal field of view is set it overrides horizontal and vertical field of view. 20558@end table 20559 20560@item barrel 20561@item fb 20562@item barrelsplit 20563Facebook's 360 formats. 20564 20565@item sg 20566Stereographic format. 20567 20568Format specific options: 20569@table @option 20570@item h_fov 20571@item v_fov 20572@item d_fov 20573Set output horizontal/vertical/diagonal field of view. Values in degrees. 20574 20575If diagonal field of view is set it overrides horizontal and vertical field of view. 20576 20577@item ih_fov 20578@item iv_fov 20579@item id_fov 20580Set input horizontal/vertical/diagonal field of view. Values in degrees. 20581 20582If diagonal field of view is set it overrides horizontal and vertical field of view. 20583@end table 20584 20585@item mercator 20586Mercator format. 20587 20588@item ball 20589Ball format, gives significant distortion toward the back. 20590 20591@item hammer 20592Hammer-Aitoff map projection format. 20593 20594@item sinusoidal 20595Sinusoidal map projection format. 20596 20597@item fisheye 20598Fisheye projection. 20599 20600Format specific options: 20601@table @option 20602@item h_fov 20603@item v_fov 20604@item d_fov 20605Set output horizontal/vertical/diagonal field of view. Values in degrees. 20606 20607If diagonal field of view is set it overrides horizontal and vertical field of view. 20608 20609@item ih_fov 20610@item iv_fov 20611@item id_fov 20612Set input horizontal/vertical/diagonal field of view. Values in degrees. 20613 20614If diagonal field of view is set it overrides horizontal and vertical field of view. 20615@end table 20616 20617@item pannini 20618Pannini projection. 20619 20620Format specific options: 20621@table @option 20622@item h_fov 20623Set output pannini parameter. 20624 20625@item ih_fov 20626Set input pannini parameter. 20627@end table 20628 20629@item cylindrical 20630Cylindrical projection. 20631 20632Format specific options: 20633@table @option 20634@item h_fov 20635@item v_fov 20636@item d_fov 20637Set output horizontal/vertical/diagonal field of view. Values in degrees. 20638 20639If diagonal field of view is set it overrides horizontal and vertical field of view. 20640 20641@item ih_fov 20642@item iv_fov 20643@item id_fov 20644Set input horizontal/vertical/diagonal field of view. Values in degrees. 20645 20646If diagonal field of view is set it overrides horizontal and vertical field of view. 20647@end table 20648 20649@item perspective 20650Perspective projection. @i{(output only)} 20651 20652Format specific options: 20653@table @option 20654@item v_fov 20655Set perspective parameter. 20656@end table 20657 20658@item tetrahedron 20659Tetrahedron projection. 20660 20661@item tsp 20662Truncated square pyramid projection. 20663 20664@item he 20665@item hequirect 20666Half equirectangular projection. 20667 20668@item equisolid 20669Equisolid format. 20670 20671Format specific options: 20672@table @option 20673@item h_fov 20674@item v_fov 20675@item d_fov 20676Set output horizontal/vertical/diagonal field of view. Values in degrees. 20677 20678If diagonal field of view is set it overrides horizontal and vertical field of view. 20679 20680@item ih_fov 20681@item iv_fov 20682@item id_fov 20683Set input horizontal/vertical/diagonal field of view. Values in degrees. 20684 20685If diagonal field of view is set it overrides horizontal and vertical field of view. 20686@end table 20687 20688@item og 20689Orthographic format. 20690 20691Format specific options: 20692@table @option 20693@item h_fov 20694@item v_fov 20695@item d_fov 20696Set output horizontal/vertical/diagonal field of view. Values in degrees. 20697 20698If diagonal field of view is set it overrides horizontal and vertical field of view. 20699 20700@item ih_fov 20701@item iv_fov 20702@item id_fov 20703Set input horizontal/vertical/diagonal field of view. Values in degrees. 20704 20705If diagonal field of view is set it overrides horizontal and vertical field of view. 20706@end table 20707 20708@item octahedron 20709Octahedron projection. 20710@end table 20711 20712@item interp 20713Set interpolation method.@* 20714@i{Note: more complex interpolation methods require much more memory to run.} 20715 20716Available methods: 20717 20718@table @samp 20719@item near 20720@item nearest 20721Nearest neighbour. 20722@item line 20723@item linear 20724Bilinear interpolation. 20725@item lagrange9 20726Lagrange9 interpolation. 20727@item cube 20728@item cubic 20729Bicubic interpolation. 20730@item lanc 20731@item lanczos 20732Lanczos interpolation. 20733@item sp16 20734@item spline16 20735Spline16 interpolation. 20736@item gauss 20737@item gaussian 20738Gaussian interpolation. 20739@item mitchell 20740Mitchell interpolation. 20741@end table 20742 20743Default value is @b{@samp{line}}. 20744 20745@item w 20746@item h 20747Set the output video resolution. 20748 20749Default resolution depends on formats. 20750 20751@item in_stereo 20752@item out_stereo 20753Set the input/output stereo format. 20754 20755@table @samp 20756@item 2d 207572D mono 20758@item sbs 20759Side by side 20760@item tb 20761Top bottom 20762@end table 20763 20764Default value is @b{@samp{2d}} for input and output format. 20765 20766@item yaw 20767@item pitch 20768@item roll 20769Set rotation for the output video. Values in degrees. 20770 20771@item rorder 20772Set rotation order for the output video. Choose one item for each position. 20773 20774@table @samp 20775@item y, Y 20776yaw 20777@item p, P 20778pitch 20779@item r, R 20780roll 20781@end table 20782 20783Default value is @b{@samp{ypr}}. 20784 20785@item h_flip 20786@item v_flip 20787@item d_flip 20788Flip the output video horizontally(swaps left-right)/vertically(swaps up-down)/in-depth(swaps back-forward). Boolean values. 20789 20790@item ih_flip 20791@item iv_flip 20792Set if input video is flipped horizontally/vertically. Boolean values. 20793 20794@item in_trans 20795Set if input video is transposed. Boolean value, by default disabled. 20796 20797@item out_trans 20798Set if output video needs to be transposed. Boolean value, by default disabled. 20799 20800@item alpha_mask 20801Build mask in alpha plane for all unmapped pixels by marking them fully transparent. Boolean value, by default disabled. 20802@end table 20803 20804@subsection Examples 20805 20806@itemize 20807@item 20808Convert equirectangular video to cubemap with 3x2 layout and 1% padding using bicubic interpolation: 20809@example 20810ffmpeg -i input.mkv -vf v360=e:c3x2:cubic:out_pad=0.01 output.mkv 20811@end example 20812@item 20813Extract back view of Equi-Angular Cubemap: 20814@example 20815ffmpeg -i input.mkv -vf v360=eac:flat:yaw=180 output.mkv 20816@end example 20817@item 20818Convert transposed and horizontally flipped Equi-Angular Cubemap in side-by-side stereo format to equirectangular top-bottom stereo format: 20819@example 20820v360=eac:equirect:in_stereo=sbs:in_trans=1:ih_flip=1:out_stereo=tb 20821@end example 20822@end itemize 20823 20824@subsection Commands 20825 20826This filter supports subset of above options as @ref{commands}. 20827 20828@section vaguedenoiser 20829 20830Apply a wavelet based denoiser. 20831 20832It transforms each frame from the video input into the wavelet domain, 20833using Cohen-Daubechies-Feauveau 9/7. Then it applies some filtering to 20834the obtained coefficients. It does an inverse wavelet transform after. 20835Due to wavelet properties, it should give a nice smoothed result, and 20836reduced noise, without blurring picture features. 20837 20838This filter accepts the following options: 20839 20840@table @option 20841@item threshold 20842The filtering strength. The higher, the more filtered the video will be. 20843Hard thresholding can use a higher threshold than soft thresholding 20844before the video looks overfiltered. Default value is 2. 20845 20846@item method 20847The filtering method the filter will use. 20848 20849It accepts the following values: 20850@table @samp 20851@item hard 20852All values under the threshold will be zeroed. 20853 20854@item soft 20855All values under the threshold will be zeroed. All values above will be 20856reduced by the threshold. 20857 20858@item garrote 20859Scales or nullifies coefficients - intermediary between (more) soft and 20860(less) hard thresholding. 20861@end table 20862 20863Default is garrote. 20864 20865@item nsteps 20866Number of times, the wavelet will decompose the picture. Picture can't 20867be decomposed beyond a particular point (typically, 8 for a 640x480 20868frame - as 2^9 = 512 > 480). Valid values are integers between 1 and 32. Default value is 6. 20869 20870@item percent 20871Partial of full denoising (limited coefficients shrinking), from 0 to 100. Default value is 85. 20872 20873@item planes 20874A list of the planes to process. By default all planes are processed. 20875 20876@item type 20877The threshold type the filter will use. 20878 20879It accepts the following values: 20880@table @samp 20881@item universal 20882Threshold used is same for all decompositions. 20883 20884@item bayes 20885Threshold used depends also on each decomposition coefficients. 20886@end table 20887 20888Default is universal. 20889@end table 20890 20891@section vectorscope 20892 20893Display 2 color component values in the two dimensional graph (which is called 20894a vectorscope). 20895 20896This filter accepts the following options: 20897 20898@table @option 20899@item mode, m 20900Set vectorscope mode. 20901 20902It accepts the following values: 20903@table @samp 20904@item gray 20905@item tint 20906Gray values are displayed on graph, higher brightness means more pixels have 20907same component color value on location in graph. This is the default mode. 20908 20909@item color 20910Gray values are displayed on graph. Surrounding pixels values which are not 20911present in video frame are drawn in gradient of 2 color components which are 20912set by option @code{x} and @code{y}. The 3rd color component is static. 20913 20914@item color2 20915Actual color components values present in video frame are displayed on graph. 20916 20917@item color3 20918Similar as color2 but higher frequency of same values @code{x} and @code{y} 20919on graph increases value of another color component, which is luminance by 20920default values of @code{x} and @code{y}. 20921 20922@item color4 20923Actual colors present in video frame are displayed on graph. If two different 20924colors map to same position on graph then color with higher value of component 20925not present in graph is picked. 20926 20927@item color5 20928Gray values are displayed on graph. Similar to @code{color} but with 3rd color 20929component picked from radial gradient. 20930@end table 20931 20932@item x 20933Set which color component will be represented on X-axis. Default is @code{1}. 20934 20935@item y 20936Set which color component will be represented on Y-axis. Default is @code{2}. 20937 20938@item intensity, i 20939Set intensity, used by modes: gray, color, color3 and color5 for increasing brightness 20940of color component which represents frequency of (X, Y) location in graph. 20941 20942@item envelope, e 20943@table @samp 20944@item none 20945No envelope, this is default. 20946 20947@item instant 20948Instant envelope, even darkest single pixel will be clearly highlighted. 20949 20950@item peak 20951Hold maximum and minimum values presented in graph over time. This way you 20952can still spot out of range values without constantly looking at vectorscope. 20953 20954@item peak+instant 20955Peak and instant envelope combined together. 20956@end table 20957 20958@item graticule, g 20959Set what kind of graticule to draw. 20960@table @samp 20961@item none 20962@item green 20963@item color 20964@item invert 20965@end table 20966 20967@item opacity, o 20968Set graticule opacity. 20969 20970@item flags, f 20971Set graticule flags. 20972 20973@table @samp 20974@item white 20975Draw graticule for white point. 20976 20977@item black 20978Draw graticule for black point. 20979 20980@item name 20981Draw color points short names. 20982@end table 20983 20984@item bgopacity, b 20985Set background opacity. 20986 20987@item lthreshold, l 20988Set low threshold for color component not represented on X or Y axis. 20989Values lower than this value will be ignored. Default is 0. 20990Note this value is multiplied with actual max possible value one pixel component 20991can have. So for 8-bit input and low threshold value of 0.1 actual threshold 20992is 0.1 * 255 = 25. 20993 20994@item hthreshold, h 20995Set high threshold for color component not represented on X or Y axis. 20996Values higher than this value will be ignored. Default is 1. 20997Note this value is multiplied with actual max possible value one pixel component 20998can have. So for 8-bit input and high threshold value of 0.9 actual threshold 20999is 0.9 * 255 = 230. 21000 21001@item colorspace, c 21002Set what kind of colorspace to use when drawing graticule. 21003@table @samp 21004@item auto 21005@item 601 21006@item 709 21007@end table 21008Default is auto. 21009 21010@item tint0, t0 21011@item tint1, t1 21012Set color tint for gray/tint vectorscope mode. By default both options are zero. 21013This means no tint, and output will remain gray. 21014@end table 21015 21016@anchor{vidstabdetect} 21017@section vidstabdetect 21018 21019Analyze video stabilization/deshaking. Perform pass 1 of 2, see 21020@ref{vidstabtransform} for pass 2. 21021 21022This filter generates a file with relative translation and rotation 21023transform information about subsequent frames, which is then used by 21024the @ref{vidstabtransform} filter. 21025 21026To enable compilation of this filter you need to configure FFmpeg with 21027@code{--enable-libvidstab}. 21028 21029This filter accepts the following options: 21030 21031@table @option 21032@item result 21033Set the path to the file used to write the transforms information. 21034Default value is @file{transforms.trf}. 21035 21036@item shakiness 21037Set how shaky the video is and how quick the camera is. It accepts an 21038integer in the range 1-10, a value of 1 means little shakiness, a 21039value of 10 means strong shakiness. Default value is 5. 21040 21041@item accuracy 21042Set the accuracy of the detection process. It must be a value in the 21043range 1-15. A value of 1 means low accuracy, a value of 15 means high 21044accuracy. Default value is 15. 21045 21046@item stepsize 21047Set stepsize of the search process. The region around minimum is 21048scanned with 1 pixel resolution. Default value is 6. 21049 21050@item mincontrast 21051Set minimum contrast. Below this value a local measurement field is 21052discarded. Must be a floating point value in the range 0-1. Default 21053value is 0.3. 21054 21055@item tripod 21056Set reference frame number for tripod mode. 21057 21058If enabled, the motion of the frames is compared to a reference frame 21059in the filtered stream, identified by the specified number. The idea 21060is to compensate all movements in a more-or-less static scene and keep 21061the camera view absolutely still. 21062 21063If set to 0, it is disabled. The frames are counted starting from 1. 21064 21065@item show 21066Show fields and transforms in the resulting frames. It accepts an 21067integer in the range 0-2. Default value is 0, which disables any 21068visualization. 21069@end table 21070 21071@subsection Examples 21072 21073@itemize 21074@item 21075Use default values: 21076@example 21077vidstabdetect 21078@end example 21079 21080@item 21081Analyze strongly shaky movie and put the results in file 21082@file{mytransforms.trf}: 21083@example 21084vidstabdetect=shakiness=10:accuracy=15:result="mytransforms.trf" 21085@end example 21086 21087@item 21088Visualize the result of internal transformations in the resulting 21089video: 21090@example 21091vidstabdetect=show=1 21092@end example 21093 21094@item 21095Analyze a video with medium shakiness using @command{ffmpeg}: 21096@example 21097ffmpeg -i input -vf vidstabdetect=shakiness=5:show=1 dummy.avi 21098@end example 21099@end itemize 21100 21101@anchor{vidstabtransform} 21102@section vidstabtransform 21103 21104Video stabilization/deshaking: pass 2 of 2, 21105see @ref{vidstabdetect} for pass 1. 21106 21107Read a file with transform information for each frame and 21108apply/compensate them. Together with the @ref{vidstabdetect} 21109filter this can be used to deshake videos. See also 21110@url{http://public.hronopik.de/vid.stab}. It is important to also use 21111the @ref{unsharp} filter, see below. 21112 21113To enable compilation of this filter you need to configure FFmpeg with 21114@code{--enable-libvidstab}. 21115 21116@subsection Options 21117 21118@table @option 21119@item input 21120Set path to the file used to read the transforms. Default value is 21121@file{transforms.trf}. 21122 21123@item smoothing 21124Set the number of frames (value*2 + 1) used for lowpass filtering the 21125camera movements. Default value is 10. 21126 21127For example a number of 10 means that 21 frames are used (10 in the 21128past and 10 in the future) to smoothen the motion in the video. A 21129larger value leads to a smoother video, but limits the acceleration of 21130the camera (pan/tilt movements). 0 is a special case where a static 21131camera is simulated. 21132 21133@item optalgo 21134Set the camera path optimization algorithm. 21135 21136Accepted values are: 21137@table @samp 21138@item gauss 21139gaussian kernel low-pass filter on camera motion (default) 21140@item avg 21141averaging on transformations 21142@end table 21143 21144@item maxshift 21145Set maximal number of pixels to translate frames. Default value is -1, 21146meaning no limit. 21147 21148@item maxangle 21149Set maximal angle in radians (degree*PI/180) to rotate frames. Default 21150value is -1, meaning no limit. 21151 21152@item crop 21153Specify how to deal with borders that may be visible due to movement 21154compensation. 21155 21156Available values are: 21157@table @samp 21158@item keep 21159keep image information from previous frame (default) 21160@item black 21161fill the border black 21162@end table 21163 21164@item invert 21165Invert transforms if set to 1. Default value is 0. 21166 21167@item relative 21168Consider transforms as relative to previous frame if set to 1, 21169absolute if set to 0. Default value is 0. 21170 21171@item zoom 21172Set percentage to zoom. A positive value will result in a zoom-in 21173effect, a negative value in a zoom-out effect. Default value is 0 (no 21174zoom). 21175 21176@item optzoom 21177Set optimal zooming to avoid borders. 21178 21179Accepted values are: 21180@table @samp 21181@item 0 21182disabled 21183@item 1 21184optimal static zoom value is determined (only very strong movements 21185will lead to visible borders) (default) 21186@item 2 21187optimal adaptive zoom value is determined (no borders will be 21188visible), see @option{zoomspeed} 21189@end table 21190 21191Note that the value given at zoom is added to the one calculated here. 21192 21193@item zoomspeed 21194Set percent to zoom maximally each frame (enabled when 21195@option{optzoom} is set to 2). Range is from 0 to 5, default value is 211960.25. 21197 21198@item interpol 21199Specify type of interpolation. 21200 21201Available values are: 21202@table @samp 21203@item no 21204no interpolation 21205@item linear 21206linear only horizontal 21207@item bilinear 21208linear in both directions (default) 21209@item bicubic 21210cubic in both directions (slow) 21211@end table 21212 21213@item tripod 21214Enable virtual tripod mode if set to 1, which is equivalent to 21215@code{relative=0:smoothing=0}. Default value is 0. 21216 21217Use also @code{tripod} option of @ref{vidstabdetect}. 21218 21219@item debug 21220Increase log verbosity if set to 1. Also the detected global motions 21221are written to the temporary file @file{global_motions.trf}. Default 21222value is 0. 21223@end table 21224 21225@subsection Examples 21226 21227@itemize 21228@item 21229Use @command{ffmpeg} for a typical stabilization with default values: 21230@example 21231ffmpeg -i inp.mpeg -vf vidstabtransform,unsharp=5:5:0.8:3:3:0.4 inp_stabilized.mpeg 21232@end example 21233 21234Note the use of the @ref{unsharp} filter which is always recommended. 21235 21236@item 21237Zoom in a bit more and load transform data from a given file: 21238@example 21239vidstabtransform=zoom=5:input="mytransforms.trf" 21240@end example 21241 21242@item 21243Smoothen the video even more: 21244@example 21245vidstabtransform=smoothing=30 21246@end example 21247@end itemize 21248 21249@section vflip 21250 21251Flip the input video vertically. 21252 21253For example, to vertically flip a video with @command{ffmpeg}: 21254@example 21255ffmpeg -i in.avi -vf "vflip" out.avi 21256@end example 21257 21258@section vfrdet 21259 21260Detect variable frame rate video. 21261 21262This filter tries to detect if the input is variable or constant frame rate. 21263 21264At end it will output number of frames detected as having variable delta pts, 21265and ones with constant delta pts. 21266If there was frames with variable delta, than it will also show min, max and 21267average delta encountered. 21268 21269@section vibrance 21270 21271Boost or alter saturation. 21272 21273The filter accepts the following options: 21274@table @option 21275@item intensity 21276Set strength of boost if positive value or strength of alter if negative value. 21277Default is 0. Allowed range is from -2 to 2. 21278 21279@item rbal 21280Set the red balance. Default is 1. Allowed range is from -10 to 10. 21281 21282@item gbal 21283Set the green balance. Default is 1. Allowed range is from -10 to 10. 21284 21285@item bbal 21286Set the blue balance. Default is 1. Allowed range is from -10 to 10. 21287 21288@item rlum 21289Set the red luma coefficient. 21290 21291@item glum 21292Set the green luma coefficient. 21293 21294@item blum 21295Set the blue luma coefficient. 21296 21297@item alternate 21298If @code{intensity} is negative and this is set to 1, colors will change, 21299otherwise colors will be less saturated, more towards gray. 21300@end table 21301 21302@subsection Commands 21303 21304This filter supports the all above options as @ref{commands}. 21305 21306@section vif 21307 21308Obtain the average VIF (Visual Information Fidelity) between two input videos. 21309 21310This filter takes two input videos. 21311 21312Both input videos must have the same resolution and pixel format for 21313this filter to work correctly. Also it assumes that both inputs 21314have the same number of frames, which are compared one by one. 21315 21316The obtained average VIF score is printed through the logging system. 21317 21318The filter stores the calculated VIF score of each frame. 21319 21320In the below example the input file @file{main.mpg} being processed is compared 21321with the reference file @file{ref.mpg}. 21322 21323@example 21324ffmpeg -i main.mpg -i ref.mpg -lavfi vif -f null - 21325@end example 21326 21327@anchor{vignette} 21328@section vignette 21329 21330Make or reverse a natural vignetting effect. 21331 21332The filter accepts the following options: 21333 21334@table @option 21335@item angle, a 21336Set lens angle expression as a number of radians. 21337 21338The value is clipped in the @code{[0,PI/2]} range. 21339 21340Default value: @code{"PI/5"} 21341 21342@item x0 21343@item y0 21344Set center coordinates expressions. Respectively @code{"w/2"} and @code{"h/2"} 21345by default. 21346 21347@item mode 21348Set forward/backward mode. 21349 21350Available modes are: 21351@table @samp 21352@item forward 21353The larger the distance from the central point, the darker the image becomes. 21354 21355@item backward 21356The larger the distance from the central point, the brighter the image becomes. 21357This can be used to reverse a vignette effect, though there is no automatic 21358detection to extract the lens @option{angle} and other settings (yet). It can 21359also be used to create a burning effect. 21360@end table 21361 21362Default value is @samp{forward}. 21363 21364@item eval 21365Set evaluation mode for the expressions (@option{angle}, @option{x0}, @option{y0}). 21366 21367It accepts the following values: 21368@table @samp 21369@item init 21370Evaluate expressions only once during the filter initialization. 21371 21372@item frame 21373Evaluate expressions for each incoming frame. This is way slower than the 21374@samp{init} mode since it requires all the scalers to be re-computed, but it 21375allows advanced dynamic expressions. 21376@end table 21377 21378Default value is @samp{init}. 21379 21380@item dither 21381Set dithering to reduce the circular banding effects. Default is @code{1} 21382(enabled). 21383 21384@item aspect 21385Set vignette aspect. This setting allows one to adjust the shape of the vignette. 21386Setting this value to the SAR of the input will make a rectangular vignetting 21387following the dimensions of the video. 21388 21389Default is @code{1/1}. 21390@end table 21391 21392@subsection Expressions 21393 21394The @option{alpha}, @option{x0} and @option{y0} expressions can contain the 21395following parameters. 21396 21397@table @option 21398@item w 21399@item h 21400input width and height 21401 21402@item n 21403the number of input frame, starting from 0 21404 21405@item pts 21406the PTS (Presentation TimeStamp) time of the filtered video frame, expressed in 21407@var{TB} units, NAN if undefined 21408 21409@item r 21410frame rate of the input video, NAN if the input frame rate is unknown 21411 21412@item t 21413the PTS (Presentation TimeStamp) of the filtered video frame, 21414expressed in seconds, NAN if undefined 21415 21416@item tb 21417time base of the input video 21418@end table 21419 21420 21421@subsection Examples 21422 21423@itemize 21424@item 21425Apply simple strong vignetting effect: 21426@example 21427vignette=PI/4 21428@end example 21429 21430@item 21431Make a flickering vignetting: 21432@example 21433vignette='PI/4+random(1)*PI/50':eval=frame 21434@end example 21435 21436@end itemize 21437 21438@section vmafmotion 21439 21440Obtain the average VMAF motion score of a video. 21441It is one of the component metrics of VMAF. 21442 21443The obtained average motion score is printed through the logging system. 21444 21445The filter accepts the following options: 21446 21447@table @option 21448@item stats_file 21449If specified, the filter will use the named file to save the motion score of 21450each frame with respect to the previous frame. 21451When filename equals "-" the data is sent to standard output. 21452@end table 21453 21454Example: 21455@example 21456ffmpeg -i ref.mpg -vf vmafmotion -f null - 21457@end example 21458 21459@section vstack 21460Stack input videos vertically. 21461 21462All streams must be of same pixel format and of same width. 21463 21464Note that this filter is faster than using @ref{overlay} and @ref{pad} filter 21465to create same output. 21466 21467The filter accepts the following options: 21468 21469@table @option 21470@item inputs 21471Set number of input streams. Default is 2. 21472 21473@item shortest 21474If set to 1, force the output to terminate when the shortest input 21475terminates. Default value is 0. 21476@end table 21477 21478@section w3fdif 21479 21480Deinterlace the input video ("w3fdif" stands for "Weston 3 Field 21481Deinterlacing Filter"). 21482 21483Based on the process described by Martin Weston for BBC R&D, and 21484implemented based on the de-interlace algorithm written by Jim 21485Easterbrook for BBC R&D, the Weston 3 field deinterlacing filter 21486uses filter coefficients calculated by BBC R&D. 21487 21488This filter uses field-dominance information in frame to decide which 21489of each pair of fields to place first in the output. 21490If it gets it wrong use @ref{setfield} filter before @code{w3fdif} filter. 21491 21492There are two sets of filter coefficients, so called "simple" 21493and "complex". Which set of filter coefficients is used can 21494be set by passing an optional parameter: 21495 21496@table @option 21497@item filter 21498Set the interlacing filter coefficients. Accepts one of the following values: 21499 21500@table @samp 21501@item simple 21502Simple filter coefficient set. 21503@item complex 21504More-complex filter coefficient set. 21505@end table 21506Default value is @samp{complex}. 21507 21508@item mode 21509The interlacing mode to adopt. It accepts one of the following values: 21510 21511@table @option 21512@item frame 21513Output one frame for each frame. 21514@item field 21515Output one frame for each field. 21516@end table 21517 21518The default value is @code{field}. 21519 21520@item parity 21521The picture field parity assumed for the input interlaced video. It accepts one 21522of the following values: 21523 21524@table @option 21525@item tff 21526Assume the top field is first. 21527@item bff 21528Assume the bottom field is first. 21529@item auto 21530Enable automatic detection of field parity. 21531@end table 21532 21533The default value is @code{auto}. 21534If the interlacing is unknown or the decoder does not export this information, 21535top field first will be assumed. 21536 21537@item deint 21538Specify which frames to deinterlace. Accepts one of the following values: 21539 21540@table @samp 21541@item all 21542Deinterlace all frames, 21543@item interlaced 21544Only deinterlace frames marked as interlaced. 21545@end table 21546 21547Default value is @samp{all}. 21548@end table 21549 21550@subsection Commands 21551This filter supports same @ref{commands} as options. 21552 21553@section waveform 21554Video waveform monitor. 21555 21556The waveform monitor plots color component intensity. By default luminance 21557only. Each column of the waveform corresponds to a column of pixels in the 21558source video. 21559 21560It accepts the following options: 21561 21562@table @option 21563@item mode, m 21564Can be either @code{row}, or @code{column}. Default is @code{column}. 21565In row mode, the graph on the left side represents color component value 0 and 21566the right side represents value = 255. In column mode, the top side represents 21567color component value = 0 and bottom side represents value = 255. 21568 21569@item intensity, i 21570Set intensity. Smaller values are useful to find out how many values of the same 21571luminance are distributed across input rows/columns. 21572Default value is @code{0.04}. Allowed range is [0, 1]. 21573 21574@item mirror, r 21575Set mirroring mode. @code{0} means unmirrored, @code{1} means mirrored. 21576In mirrored mode, higher values will be represented on the left 21577side for @code{row} mode and at the top for @code{column} mode. Default is 21578@code{1} (mirrored). 21579 21580@item display, d 21581Set display mode. 21582It accepts the following values: 21583@table @samp 21584@item overlay 21585Presents information identical to that in the @code{parade}, except 21586that the graphs representing color components are superimposed directly 21587over one another. 21588 21589This display mode makes it easier to spot relative differences or similarities 21590in overlapping areas of the color components that are supposed to be identical, 21591such as neutral whites, grays, or blacks. 21592 21593@item stack 21594Display separate graph for the color components side by side in 21595@code{row} mode or one below the other in @code{column} mode. 21596 21597@item parade 21598Display separate graph for the color components side by side in 21599@code{column} mode or one below the other in @code{row} mode. 21600 21601Using this display mode makes it easy to spot color casts in the highlights 21602and shadows of an image, by comparing the contours of the top and the bottom 21603graphs of each waveform. Since whites, grays, and blacks are characterized 21604by exactly equal amounts of red, green, and blue, neutral areas of the picture 21605should display three waveforms of roughly equal width/height. If not, the 21606correction is easy to perform by making level adjustments the three waveforms. 21607@end table 21608Default is @code{stack}. 21609 21610@item components, c 21611Set which color components to display. Default is 1, which means only luminance 21612or red color component if input is in RGB colorspace. If is set for example to 216137 it will display all 3 (if) available color components. 21614 21615@item envelope, e 21616@table @samp 21617@item none 21618No envelope, this is default. 21619 21620@item instant 21621Instant envelope, minimum and maximum values presented in graph will be easily 21622visible even with small @code{step} value. 21623 21624@item peak 21625Hold minimum and maximum values presented in graph across time. This way you 21626can still spot out of range values without constantly looking at waveforms. 21627 21628@item peak+instant 21629Peak and instant envelope combined together. 21630@end table 21631 21632@item filter, f 21633@table @samp 21634@item lowpass 21635No filtering, this is default. 21636 21637@item flat 21638Luma and chroma combined together. 21639 21640@item aflat 21641Similar as above, but shows difference between blue and red chroma. 21642 21643@item xflat 21644Similar as above, but use different colors. 21645 21646@item yflat 21647Similar as above, but again with different colors. 21648 21649@item chroma 21650Displays only chroma. 21651 21652@item color 21653Displays actual color value on waveform. 21654 21655@item acolor 21656Similar as above, but with luma showing frequency of chroma values. 21657@end table 21658 21659@item graticule, g 21660Set which graticule to display. 21661 21662@table @samp 21663@item none 21664Do not display graticule. 21665 21666@item green 21667Display green graticule showing legal broadcast ranges. 21668 21669@item orange 21670Display orange graticule showing legal broadcast ranges. 21671 21672@item invert 21673Display invert graticule showing legal broadcast ranges. 21674@end table 21675 21676@item opacity, o 21677Set graticule opacity. 21678 21679@item flags, fl 21680Set graticule flags. 21681 21682@table @samp 21683@item numbers 21684Draw numbers above lines. By default enabled. 21685 21686@item dots 21687Draw dots instead of lines. 21688@end table 21689 21690@item scale, s 21691Set scale used for displaying graticule. 21692 21693@table @samp 21694@item digital 21695@item millivolts 21696@item ire 21697@end table 21698Default is digital. 21699 21700@item bgopacity, b 21701Set background opacity. 21702 21703@item tint0, t0 21704@item tint1, t1 21705Set tint for output. 21706Only used with lowpass filter and when display is not overlay and input 21707pixel formats are not RGB. 21708@end table 21709 21710@section weave, doubleweave 21711 21712The @code{weave} takes a field-based video input and join 21713each two sequential fields into single frame, producing a new double 21714height clip with half the frame rate and half the frame count. 21715 21716The @code{doubleweave} works same as @code{weave} but without 21717halving frame rate and frame count. 21718 21719It accepts the following option: 21720 21721@table @option 21722@item first_field 21723Set first field. Available values are: 21724 21725@table @samp 21726@item top, t 21727Set the frame as top-field-first. 21728 21729@item bottom, b 21730Set the frame as bottom-field-first. 21731@end table 21732@end table 21733 21734@subsection Examples 21735 21736@itemize 21737@item 21738Interlace video using @ref{select} and @ref{separatefields} filter: 21739@example 21740separatefields,select=eq(mod(n,4),0)+eq(mod(n,4),3),weave 21741@end example 21742@end itemize 21743 21744@section xbr 21745Apply the xBR high-quality magnification filter which is designed for pixel 21746art. It follows a set of edge-detection rules, see 21747@url{https://forums.libretro.com/t/xbr-algorithm-tutorial/123}. 21748 21749It accepts the following option: 21750 21751@table @option 21752@item n 21753Set the scaling dimension: @code{2} for @code{2xBR}, @code{3} for 21754@code{3xBR} and @code{4} for @code{4xBR}. 21755Default is @code{3}. 21756@end table 21757 21758@section xfade 21759 21760Apply cross fade from one input video stream to another input video stream. 21761The cross fade is applied for specified duration. 21762 21763The filter accepts the following options: 21764 21765@table @option 21766@item transition 21767Set one of available transition effects: 21768 21769@table @samp 21770@item custom 21771@item fade 21772@item wipeleft 21773@item wiperight 21774@item wipeup 21775@item wipedown 21776@item slideleft 21777@item slideright 21778@item slideup 21779@item slidedown 21780@item circlecrop 21781@item rectcrop 21782@item distance 21783@item fadeblack 21784@item fadewhite 21785@item radial 21786@item smoothleft 21787@item smoothright 21788@item smoothup 21789@item smoothdown 21790@item circleopen 21791@item circleclose 21792@item vertopen 21793@item vertclose 21794@item horzopen 21795@item horzclose 21796@item dissolve 21797@item pixelize 21798@item diagtl 21799@item diagtr 21800@item diagbl 21801@item diagbr 21802@item hlslice 21803@item hrslice 21804@item vuslice 21805@item vdslice 21806@item hblur 21807@item fadegrays 21808@item wipetl 21809@item wipetr 21810@item wipebl 21811@item wipebr 21812@item squeezeh 21813@item squeezev 21814@end table 21815Default transition effect is fade. 21816 21817@item duration 21818Set cross fade duration in seconds. 21819Default duration is 1 second. 21820 21821@item offset 21822Set cross fade start relative to first input stream in seconds. 21823Default offset is 0. 21824 21825@item expr 21826Set expression for custom transition effect. 21827 21828The expressions can use the following variables and functions: 21829 21830@table @option 21831@item X 21832@item Y 21833The coordinates of the current sample. 21834 21835@item W 21836@item H 21837The width and height of the image. 21838 21839@item P 21840Progress of transition effect. 21841 21842@item PLANE 21843Currently processed plane. 21844 21845@item A 21846Return value of first input at current location and plane. 21847 21848@item B 21849Return value of second input at current location and plane. 21850 21851@item a0(x, y) 21852@item a1(x, y) 21853@item a2(x, y) 21854@item a3(x, y) 21855Return the value of the pixel at location (@var{x},@var{y}) of the 21856first/second/third/fourth component of first input. 21857 21858@item b0(x, y) 21859@item b1(x, y) 21860@item b2(x, y) 21861@item b3(x, y) 21862Return the value of the pixel at location (@var{x},@var{y}) of the 21863first/second/third/fourth component of second input. 21864@end table 21865@end table 21866 21867@subsection Examples 21868 21869@itemize 21870@item 21871Cross fade from one input video to another input video, with fade transition and duration of transition 21872of 2 seconds starting at offset of 5 seconds: 21873@example 21874ffmpeg -i first.mp4 -i second.mp4 -filter_complex xfade=transition=fade:duration=2:offset=5 output.mp4 21875@end example 21876@end itemize 21877 21878@section xmedian 21879Pick median pixels from several input videos. 21880 21881The filter accepts the following options: 21882 21883@table @option 21884@item inputs 21885Set number of inputs. 21886Default is 3. Allowed range is from 3 to 255. 21887If number of inputs is even number, than result will be mean value between two median values. 21888 21889@item planes 21890Set which planes to filter. Default value is @code{15}, by which all planes are processed. 21891 21892@item percentile 21893Set median percentile. Default value is @code{0.5}. 21894Default value of @code{0.5} will pick always median values, while @code{0} will pick 21895minimum values, and @code{1} maximum values. 21896@end table 21897 21898@subsection Commands 21899 21900This filter supports all above options as @ref{commands}, excluding option @code{inputs}. 21901 21902@section xstack 21903Stack video inputs into custom layout. 21904 21905All streams must be of same pixel format. 21906 21907The filter accepts the following options: 21908 21909@table @option 21910@item inputs 21911Set number of input streams. Default is 2. 21912 21913@item layout 21914Specify layout of inputs. 21915This option requires the desired layout configuration to be explicitly set by the user. 21916This sets position of each video input in output. Each input 21917is separated by '|'. 21918The first number represents the column, and the second number represents the row. 21919Numbers start at 0 and are separated by '_'. Optionally one can use wX and hX, 21920where X is video input from which to take width or height. 21921Multiple values can be used when separated by '+'. In such 21922case values are summed together. 21923 21924Note that if inputs are of different sizes gaps may appear, as not all of 21925the output video frame will be filled. Similarly, videos can overlap each 21926other if their position doesn't leave enough space for the full frame of 21927adjoining videos. 21928 21929For 2 inputs, a default layout of @code{0_0|w0_0} is set. In all other cases, 21930a layout must be set by the user. 21931 21932@item shortest 21933If set to 1, force the output to terminate when the shortest input 21934terminates. Default value is 0. 21935 21936@item fill 21937If set to valid color, all unused pixels will be filled with that color. 21938By default fill is set to none, so it is disabled. 21939@end table 21940 21941@subsection Examples 21942 21943@itemize 21944@item 21945Display 4 inputs into 2x2 grid. 21946 21947Layout: 21948@example 21949input1(0, 0) | input3(w0, 0) 21950input2(0, h0) | input4(w0, h0) 21951@end example 21952 21953@example 21954xstack=inputs=4:layout=0_0|0_h0|w0_0|w0_h0 21955@end example 21956 21957Note that if inputs are of different sizes, gaps or overlaps may occur. 21958 21959@item 21960Display 4 inputs into 1x4 grid. 21961 21962Layout: 21963@example 21964input1(0, 0) 21965input2(0, h0) 21966input3(0, h0+h1) 21967input4(0, h0+h1+h2) 21968@end example 21969 21970@example 21971xstack=inputs=4:layout=0_0|0_h0|0_h0+h1|0_h0+h1+h2 21972@end example 21973 21974Note that if inputs are of different widths, unused space will appear. 21975 21976@item 21977Display 9 inputs into 3x3 grid. 21978 21979Layout: 21980@example 21981input1(0, 0) | input4(w0, 0) | input7(w0+w3, 0) 21982input2(0, h0) | input5(w0, h0) | input8(w0+w3, h0) 21983input3(0, h0+h1) | input6(w0, h0+h1) | input9(w0+w3, h0+h1) 21984@end example 21985 21986@example 21987xstack=inputs=9:layout=0_0|0_h0|0_h0+h1|w0_0|w0_h0|w0_h0+h1|w0+w3_0|w0+w3_h0|w0+w3_h0+h1 21988@end example 21989 21990Note that if inputs are of different sizes, gaps or overlaps may occur. 21991 21992@item 21993Display 16 inputs into 4x4 grid. 21994 21995Layout: 21996@example 21997input1(0, 0) | input5(w0, 0) | input9 (w0+w4, 0) | input13(w0+w4+w8, 0) 21998input2(0, h0) | input6(w0, h0) | input10(w0+w4, h0) | input14(w0+w4+w8, h0) 21999input3(0, h0+h1) | input7(w0, h0+h1) | input11(w0+w4, h0+h1) | input15(w0+w4+w8, h0+h1) 22000input4(0, h0+h1+h2)| input8(w0, h0+h1+h2)| input12(w0+w4, h0+h1+h2)| input16(w0+w4+w8, h0+h1+h2) 22001@end example 22002 22003@example 22004xstack=inputs=16:layout=0_0|0_h0|0_h0+h1|0_h0+h1+h2|w0_0|w0_h0|w0_h0+h1|w0_h0+h1+h2|w0+w4_0| 22005w0+w4_h0|w0+w4_h0+h1|w0+w4_h0+h1+h2|w0+w4+w8_0|w0+w4+w8_h0|w0+w4+w8_h0+h1|w0+w4+w8_h0+h1+h2 22006@end example 22007 22008Note that if inputs are of different sizes, gaps or overlaps may occur. 22009 22010@end itemize 22011 22012@anchor{yadif} 22013@section yadif 22014 22015Deinterlace the input video ("yadif" means "yet another deinterlacing 22016filter"). 22017 22018It accepts the following parameters: 22019 22020 22021@table @option 22022 22023@item mode 22024The interlacing mode to adopt. It accepts one of the following values: 22025 22026@table @option 22027@item 0, send_frame 22028Output one frame for each frame. 22029@item 1, send_field 22030Output one frame for each field. 22031@item 2, send_frame_nospatial 22032Like @code{send_frame}, but it skips the spatial interlacing check. 22033@item 3, send_field_nospatial 22034Like @code{send_field}, but it skips the spatial interlacing check. 22035@end table 22036 22037The default value is @code{send_frame}. 22038 22039@item parity 22040The picture field parity assumed for the input interlaced video. It accepts one 22041of the following values: 22042 22043@table @option 22044@item 0, tff 22045Assume the top field is first. 22046@item 1, bff 22047Assume the bottom field is first. 22048@item -1, auto 22049Enable automatic detection of field parity. 22050@end table 22051 22052The default value is @code{auto}. 22053If the interlacing is unknown or the decoder does not export this information, 22054top field first will be assumed. 22055 22056@item deint 22057Specify which frames to deinterlace. Accepts one of the following 22058values: 22059 22060@table @option 22061@item 0, all 22062Deinterlace all frames. 22063@item 1, interlaced 22064Only deinterlace frames marked as interlaced. 22065@end table 22066 22067The default value is @code{all}. 22068@end table 22069 22070@section yadif_cuda 22071 22072Deinterlace the input video using the @ref{yadif} algorithm, but implemented 22073in CUDA so that it can work as part of a GPU accelerated pipeline with nvdec 22074and/or nvenc. 22075 22076It accepts the following parameters: 22077 22078 22079@table @option 22080 22081@item mode 22082The interlacing mode to adopt. It accepts one of the following values: 22083 22084@table @option 22085@item 0, send_frame 22086Output one frame for each frame. 22087@item 1, send_field 22088Output one frame for each field. 22089@item 2, send_frame_nospatial 22090Like @code{send_frame}, but it skips the spatial interlacing check. 22091@item 3, send_field_nospatial 22092Like @code{send_field}, but it skips the spatial interlacing check. 22093@end table 22094 22095The default value is @code{send_frame}. 22096 22097@item parity 22098The picture field parity assumed for the input interlaced video. It accepts one 22099of the following values: 22100 22101@table @option 22102@item 0, tff 22103Assume the top field is first. 22104@item 1, bff 22105Assume the bottom field is first. 22106@item -1, auto 22107Enable automatic detection of field parity. 22108@end table 22109 22110The default value is @code{auto}. 22111If the interlacing is unknown or the decoder does not export this information, 22112top field first will be assumed. 22113 22114@item deint 22115Specify which frames to deinterlace. Accepts one of the following 22116values: 22117 22118@table @option 22119@item 0, all 22120Deinterlace all frames. 22121@item 1, interlaced 22122Only deinterlace frames marked as interlaced. 22123@end table 22124 22125The default value is @code{all}. 22126@end table 22127 22128@section yaepblur 22129 22130Apply blur filter while preserving edges ("yaepblur" means "yet another edge preserving blur filter"). 22131The algorithm is described in 22132"J. S. Lee, Digital image enhancement and noise filtering by use of local statistics, IEEE Trans. Pattern Anal. Mach. Intell. PAMI-2, 1980." 22133 22134It accepts the following parameters: 22135 22136@table @option 22137@item radius, r 22138Set the window radius. Default value is 3. 22139 22140@item planes, p 22141Set which planes to filter. Default is only the first plane. 22142 22143@item sigma, s 22144Set blur strength. Default value is 128. 22145@end table 22146 22147@subsection Commands 22148This filter supports same @ref{commands} as options. 22149 22150@section zoompan 22151 22152Apply Zoom & Pan effect. 22153 22154This filter accepts the following options: 22155 22156@table @option 22157@item zoom, z 22158Set the zoom expression. Range is 1-10. Default is 1. 22159 22160@item x 22161@item y 22162Set the x and y expression. Default is 0. 22163 22164@item d 22165Set the duration expression in number of frames. 22166This sets for how many number of frames effect will last for 22167single input image. Default is 90. 22168 22169@item s 22170Set the output image size, default is 'hd720'. 22171 22172@item fps 22173Set the output frame rate, default is '25'. 22174@end table 22175 22176Each expression can contain the following constants: 22177 22178@table @option 22179@item in_w, iw 22180Input width. 22181 22182@item in_h, ih 22183Input height. 22184 22185@item out_w, ow 22186Output width. 22187 22188@item out_h, oh 22189Output height. 22190 22191@item in 22192Input frame count. 22193 22194@item on 22195Output frame count. 22196 22197@item in_time, it 22198The input timestamp expressed in seconds. It's NAN if the input timestamp is unknown. 22199 22200@item out_time, time, ot 22201The output timestamp expressed in seconds. 22202 22203@item x 22204@item y 22205Last calculated 'x' and 'y' position from 'x' and 'y' expression 22206for current input frame. 22207 22208@item px 22209@item py 22210'x' and 'y' of last output frame of previous input frame or 0 when there was 22211not yet such frame (first input frame). 22212 22213@item zoom 22214Last calculated zoom from 'z' expression for current input frame. 22215 22216@item pzoom 22217Last calculated zoom of last output frame of previous input frame. 22218 22219@item duration 22220Number of output frames for current input frame. Calculated from 'd' expression 22221for each input frame. 22222 22223@item pduration 22224number of output frames created for previous input frame 22225 22226@item a 22227Rational number: input width / input height 22228 22229@item sar 22230sample aspect ratio 22231 22232@item dar 22233display aspect ratio 22234 22235@end table 22236 22237@subsection Examples 22238 22239@itemize 22240@item 22241Zoom in up to 1.5x and pan at same time to some spot near center of picture: 22242@example 22243zoompan=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 22244@end example 22245 22246@item 22247Zoom in up to 1.5x and pan always at center of picture: 22248@example 22249zoompan=z='min(zoom+0.0015,1.5)':d=700:x='iw/2-(iw/zoom/2)':y='ih/2-(ih/zoom/2)' 22250@end example 22251 22252@item 22253Same as above but without pausing: 22254@example 22255zoompan=z='min(max(zoom,pzoom)+0.0015,1.5)':d=1:x='iw/2-(iw/zoom/2)':y='ih/2-(ih/zoom/2)' 22256@end example 22257 22258@item 22259Zoom in 2x into center of picture only for the first second of the input video: 22260@example 22261zoompan=z='if(between(in_time,0,1),2,1)':d=1:x='iw/2-(iw/zoom/2)':y='ih/2-(ih/zoom/2)' 22262@end example 22263 22264@end itemize 22265 22266@anchor{zscale} 22267@section zscale 22268Scale (resize) the input video, using the z.lib library: 22269@url{https://github.com/sekrit-twc/zimg}. To enable compilation of this 22270filter, you need to configure FFmpeg with @code{--enable-libzimg}. 22271 22272The zscale filter forces the output display aspect ratio to be the same 22273as the input, by changing the output sample aspect ratio. 22274 22275If the input image format is different from the format requested by 22276the next filter, the zscale filter will convert the input to the 22277requested format. 22278 22279@subsection Options 22280The filter accepts the following options. 22281 22282@table @option 22283@item width, w 22284@item height, h 22285Set the output video dimension expression. Default value is the input 22286dimension. 22287 22288If the @var{width} or @var{w} value is 0, the input width is used for 22289the output. If the @var{height} or @var{h} value is 0, the input height 22290is used for the output. 22291 22292If one and only one of the values is -n with n >= 1, the zscale filter 22293will use a value that maintains the aspect ratio of the input image, 22294calculated from the other specified dimension. After that it will, 22295however, make sure that the calculated dimension is divisible by n and 22296adjust the value if necessary. 22297 22298If both values are -n with n >= 1, the behavior will be identical to 22299both values being set to 0 as previously detailed. 22300 22301See below for the list of accepted constants for use in the dimension 22302expression. 22303 22304@item size, s 22305Set the video size. For the syntax of this option, check the 22306@ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}. 22307 22308@item dither, d 22309Set the dither type. 22310 22311Possible values are: 22312@table @var 22313@item none 22314@item ordered 22315@item random 22316@item error_diffusion 22317@end table 22318 22319Default is none. 22320 22321@item filter, f 22322Set the resize filter type. 22323 22324Possible values are: 22325@table @var 22326@item point 22327@item bilinear 22328@item bicubic 22329@item spline16 22330@item spline36 22331@item lanczos 22332@end table 22333 22334Default is bilinear. 22335 22336@item range, r 22337Set the color range. 22338 22339Possible values are: 22340@table @var 22341@item input 22342@item limited 22343@item full 22344@end table 22345 22346Default is same as input. 22347 22348@item primaries, p 22349Set the color primaries. 22350 22351Possible values are: 22352@table @var 22353@item input 22354@item 709 22355@item unspecified 22356@item 170m 22357@item 240m 22358@item 2020 22359@end table 22360 22361Default is same as input. 22362 22363@item transfer, t 22364Set the transfer characteristics. 22365 22366Possible values are: 22367@table @var 22368@item input 22369@item 709 22370@item unspecified 22371@item 601 22372@item linear 22373@item 2020_10 22374@item 2020_12 22375@item smpte2084 22376@item iec61966-2-1 22377@item arib-std-b67 22378@end table 22379 22380Default is same as input. 22381 22382@item matrix, m 22383Set the colorspace matrix. 22384 22385Possible value are: 22386@table @var 22387@item input 22388@item 709 22389@item unspecified 22390@item 470bg 22391@item 170m 22392@item 2020_ncl 22393@item 2020_cl 22394@end table 22395 22396Default is same as input. 22397 22398@item rangein, rin 22399Set the input color range. 22400 22401Possible values are: 22402@table @var 22403@item input 22404@item limited 22405@item full 22406@end table 22407 22408Default is same as input. 22409 22410@item primariesin, pin 22411Set the input color primaries. 22412 22413Possible values are: 22414@table @var 22415@item input 22416@item 709 22417@item unspecified 22418@item 170m 22419@item 240m 22420@item 2020 22421@end table 22422 22423Default is same as input. 22424 22425@item transferin, tin 22426Set the input transfer characteristics. 22427 22428Possible values are: 22429@table @var 22430@item input 22431@item 709 22432@item unspecified 22433@item 601 22434@item linear 22435@item 2020_10 22436@item 2020_12 22437@end table 22438 22439Default is same as input. 22440 22441@item matrixin, min 22442Set the input colorspace matrix. 22443 22444Possible value are: 22445@table @var 22446@item input 22447@item 709 22448@item unspecified 22449@item 470bg 22450@item 170m 22451@item 2020_ncl 22452@item 2020_cl 22453@end table 22454 22455@item chromal, c 22456Set the output chroma location. 22457 22458Possible values are: 22459@table @var 22460@item input 22461@item left 22462@item center 22463@item topleft 22464@item top 22465@item bottomleft 22466@item bottom 22467@end table 22468 22469@item chromalin, cin 22470Set the input chroma location. 22471 22472Possible values are: 22473@table @var 22474@item input 22475@item left 22476@item center 22477@item topleft 22478@item top 22479@item bottomleft 22480@item bottom 22481@end table 22482 22483@item npl 22484Set the nominal peak luminance. 22485 22486@item param_a 22487Parameter A for scaling filters. Parameter "b" for bicubic, and the number of 22488filter taps for lanczos. 22489 22490@item param_b 22491Parameter B for scaling filters. Parameter "c" for bicubic. 22492@end table 22493 22494The values of the @option{w} and @option{h} options are expressions 22495containing the following constants: 22496 22497@table @var 22498@item in_w 22499@item in_h 22500The input width and height 22501 22502@item iw 22503@item ih 22504These are the same as @var{in_w} and @var{in_h}. 22505 22506@item out_w 22507@item out_h 22508The output (scaled) width and height 22509 22510@item ow 22511@item oh 22512These are the same as @var{out_w} and @var{out_h} 22513 22514@item a 22515The same as @var{iw} / @var{ih} 22516 22517@item sar 22518input sample aspect ratio 22519 22520@item dar 22521The input display aspect ratio. Calculated from @code{(iw / ih) * sar}. 22522 22523@item hsub 22524@item vsub 22525horizontal and vertical input chroma subsample values. For example for the 22526pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1. 22527 22528@item ohsub 22529@item ovsub 22530horizontal and vertical output chroma subsample values. For example for the 22531pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1. 22532@end table 22533 22534@subsection Commands 22535 22536This filter supports the following commands: 22537@table @option 22538@item width, w 22539@item height, h 22540Set the output video dimension expression. 22541The command accepts the same syntax of the corresponding option. 22542 22543If the specified expression is not valid, it is kept at its current 22544value. 22545@end table 22546 22547@c man end VIDEO FILTERS 22548 22549@chapter OpenCL Video Filters 22550@c man begin OPENCL VIDEO FILTERS 22551 22552Below is a description of the currently available OpenCL video filters. 22553 22554To enable compilation of these filters you need to configure FFmpeg with 22555@code{--enable-opencl}. 22556 22557Running OpenCL filters requires you to initialize a hardware device and to pass that device to all filters in any filter graph. 22558@table @option 22559 22560@item -init_hw_device opencl[=@var{name}][:@var{device}[,@var{key=value}...]] 22561Initialise a new hardware device of type @var{opencl} called @var{name}, using the 22562given device parameters. 22563 22564@item -filter_hw_device @var{name} 22565Pass the hardware device called @var{name} to all filters in any filter graph. 22566 22567@end table 22568 22569For more detailed information see @url{https://www.ffmpeg.org/ffmpeg.html#Advanced-Video-options} 22570 22571@itemize 22572@item 22573Example of choosing the first device on the second platform and running avgblur_opencl filter with default parameters on it. 22574@example 22575-init_hw_device opencl=gpu:1.0 -filter_hw_device gpu -i INPUT -vf "hwupload, avgblur_opencl, hwdownload" OUTPUT 22576@end example 22577@end itemize 22578 22579Since OpenCL filters are not able to access frame data in normal memory, all frame data needs to be uploaded(@ref{hwupload}) to hardware surfaces connected to the appropriate device before being used and then downloaded(@ref{hwdownload}) back to normal memory. Note that @ref{hwupload} will upload to a surface with the same layout as the software frame, so it may be necessary to add a @ref{format} filter immediately before to get the input into the right format and @ref{hwdownload} does not support all formats on the output - it may be necessary to insert an additional @ref{format} filter immediately following in the graph to get the output in a supported format. 22580 22581@section avgblur_opencl 22582 22583Apply average blur filter. 22584 22585The filter accepts the following options: 22586 22587@table @option 22588@item sizeX 22589Set horizontal radius size. 22590Range is @code{[1, 1024]} and default value is @code{1}. 22591 22592@item planes 22593Set which planes to filter. Default value is @code{0xf}, by which all planes are processed. 22594 22595@item sizeY 22596Set vertical radius size. Range is @code{[1, 1024]} and default value is @code{0}. If zero, @code{sizeX} value will be used. 22597@end table 22598 22599@subsection Example 22600 22601@itemize 22602@item 22603Apply average blur filter with horizontal and vertical size of 3, setting each pixel of the output to the average value of the 7x7 region centered on it in the input. For pixels on the edges of the image, the region does not extend beyond the image boundaries, and so out-of-range coordinates are not used in the calculations. 22604@example 22605-i INPUT -vf "hwupload, avgblur_opencl=3, hwdownload" OUTPUT 22606@end example 22607@end itemize 22608 22609@section boxblur_opencl 22610 22611Apply a boxblur algorithm to the input video. 22612 22613It accepts the following parameters: 22614 22615@table @option 22616 22617@item luma_radius, lr 22618@item luma_power, lp 22619@item chroma_radius, cr 22620@item chroma_power, cp 22621@item alpha_radius, ar 22622@item alpha_power, ap 22623 22624@end table 22625 22626A description of the accepted options follows. 22627 22628@table @option 22629@item luma_radius, lr 22630@item chroma_radius, cr 22631@item alpha_radius, ar 22632Set an expression for the box radius in pixels used for blurring the 22633corresponding input plane. 22634 22635The radius value must be a non-negative number, and must not be 22636greater than the value of the expression @code{min(w,h)/2} for the 22637luma and alpha planes, and of @code{min(cw,ch)/2} for the chroma 22638planes. 22639 22640Default value for @option{luma_radius} is "2". If not specified, 22641@option{chroma_radius} and @option{alpha_radius} default to the 22642corresponding value set for @option{luma_radius}. 22643 22644The expressions can contain the following constants: 22645@table @option 22646@item w 22647@item h 22648The input width and height in pixels. 22649 22650@item cw 22651@item ch 22652The input chroma image width and height in pixels. 22653 22654@item hsub 22655@item vsub 22656The horizontal and vertical chroma subsample values. For example, for the 22657pixel format "yuv422p", @var{hsub} is 2 and @var{vsub} is 1. 22658@end table 22659 22660@item luma_power, lp 22661@item chroma_power, cp 22662@item alpha_power, ap 22663Specify how many times the boxblur filter is applied to the 22664corresponding plane. 22665 22666Default value for @option{luma_power} is 2. If not specified, 22667@option{chroma_power} and @option{alpha_power} default to the 22668corresponding value set for @option{luma_power}. 22669 22670A value of 0 will disable the effect. 22671@end table 22672 22673@subsection Examples 22674 22675Apply boxblur filter, setting each pixel of the output to the average value of box-radiuses @var{luma_radius}, @var{chroma_radius}, @var{alpha_radius} for each plane respectively. The filter will apply @var{luma_power}, @var{chroma_power}, @var{alpha_power} times onto the corresponding plane. For pixels on the edges of the image, the radius does not extend beyond the image boundaries, and so out-of-range coordinates are not used in the calculations. 22676 22677@itemize 22678@item 22679Apply a boxblur filter with the luma, chroma, and alpha radius 22680set to 2 and luma, chroma, and alpha power set to 3. The filter will run 3 times with box-radius set to 2 for every plane of the image. 22681@example 22682-i INPUT -vf "hwupload, boxblur_opencl=luma_radius=2:luma_power=3, hwdownload" OUTPUT 22683-i INPUT -vf "hwupload, boxblur_opencl=2:3, hwdownload" OUTPUT 22684@end example 22685 22686@item 22687Apply a boxblur filter with luma radius set to 2, luma_power to 1, chroma_radius to 4, chroma_power to 5, alpha_radius to 3 and alpha_power to 7. 22688 22689For the luma plane, a 2x2 box radius will be run once. 22690 22691For the chroma plane, a 4x4 box radius will be run 5 times. 22692 22693For the alpha plane, a 3x3 box radius will be run 7 times. 22694@example 22695-i INPUT -vf "hwupload, boxblur_opencl=2:1:4:5:3:7, hwdownload" OUTPUT 22696@end example 22697@end itemize 22698 22699@section colorkey_opencl 22700RGB colorspace color keying. 22701 22702The filter accepts the following options: 22703 22704@table @option 22705@item color 22706The color which will be replaced with transparency. 22707 22708@item similarity 22709Similarity percentage with the key color. 22710 227110.01 matches only the exact key color, while 1.0 matches everything. 22712 22713@item blend 22714Blend percentage. 22715 227160.0 makes pixels either fully transparent, or not transparent at all. 22717 22718Higher values result in semi-transparent pixels, with a higher transparency 22719the more similar the pixels color is to the key color. 22720@end table 22721 22722@subsection Examples 22723 22724@itemize 22725@item 22726Make every semi-green pixel in the input transparent with some slight blending: 22727@example 22728-i INPUT -vf "hwupload, colorkey_opencl=green:0.3:0.1, hwdownload" OUTPUT 22729@end example 22730@end itemize 22731 22732@section convolution_opencl 22733 22734Apply convolution of 3x3, 5x5, 7x7 matrix. 22735 22736The filter accepts the following options: 22737 22738@table @option 22739@item 0m 22740@item 1m 22741@item 2m 22742@item 3m 22743Set matrix for each plane. 22744Matrix is sequence of 9, 25 or 49 signed numbers. 22745Default value for each plane is @code{0 0 0 0 1 0 0 0 0}. 22746 22747@item 0rdiv 22748@item 1rdiv 22749@item 2rdiv 22750@item 3rdiv 22751Set multiplier for calculated value for each plane. 22752If unset or 0, it will be sum of all matrix elements. 22753The option value must be a float number greater or equal to @code{0.0}. Default value is @code{1.0}. 22754 22755@item 0bias 22756@item 1bias 22757@item 2bias 22758@item 3bias 22759Set bias for each plane. This value is added to the result of the multiplication. 22760Useful for making the overall image brighter or darker. 22761The option value must be a float number greater or equal to @code{0.0}. Default value is @code{0.0}. 22762 22763@end table 22764 22765@subsection Examples 22766 22767@itemize 22768@item 22769Apply sharpen: 22770@example 22771-i INPUT -vf "hwupload, convolution_opencl=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, hwdownload" OUTPUT 22772@end example 22773 22774@item 22775Apply blur: 22776@example 22777-i INPUT -vf "hwupload, convolution_opencl=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, hwdownload" OUTPUT 22778@end example 22779 22780@item 22781Apply edge enhance: 22782@example 22783-i INPUT -vf "hwupload, convolution_opencl=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, hwdownload" OUTPUT 22784@end example 22785 22786@item 22787Apply edge detect: 22788@example 22789-i INPUT -vf "hwupload, convolution_opencl=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, hwdownload" OUTPUT 22790@end example 22791 22792@item 22793Apply laplacian edge detector which includes diagonals: 22794@example 22795-i INPUT -vf "hwupload, convolution_opencl=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, hwdownload" OUTPUT 22796@end example 22797 22798@item 22799Apply emboss: 22800@example 22801-i INPUT -vf "hwupload, convolution_opencl=-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, hwdownload" OUTPUT 22802@end example 22803@end itemize 22804 22805@section erosion_opencl 22806 22807Apply erosion effect to the video. 22808 22809This filter replaces the pixel by the local(3x3) minimum. 22810 22811It accepts the following options: 22812 22813@table @option 22814@item threshold0 22815@item threshold1 22816@item threshold2 22817@item threshold3 22818Limit the maximum change for each plane. Range is @code{[0, 65535]} and default value is @code{65535}. 22819If @code{0}, plane will remain unchanged. 22820 22821@item coordinates 22822Flag which specifies the pixel to refer to. 22823Range is @code{[0, 255]} and default value is @code{255}, i.e. all eight pixels are used. 22824 22825Flags to local 3x3 coordinates region centered on @code{x}: 22826 22827 1 2 3 22828 22829 4 x 5 22830 22831 6 7 8 22832@end table 22833 22834@subsection Example 22835 22836@itemize 22837@item 22838Apply erosion filter with threshold0 set to 30, threshold1 set 40, threshold2 set to 50 and coordinates set to 231, setting each pixel of the output to the local minimum between pixels: 1, 2, 3, 6, 7, 8 of the 3x3 region centered on it in the input. If the difference between input pixel and local minimum is more then threshold of the corresponding plane, output pixel will be set to input pixel - threshold of corresponding plane. 22839@example 22840-i INPUT -vf "hwupload, erosion_opencl=30:40:50:coordinates=231, hwdownload" OUTPUT 22841@end example 22842@end itemize 22843 22844@section deshake_opencl 22845Feature-point based video stabilization filter. 22846 22847The filter accepts the following options: 22848 22849@table @option 22850@item tripod 22851Simulates a tripod by preventing any camera movement whatsoever from the original frame. Defaults to @code{0}. 22852 22853@item debug 22854Whether or not additional debug info should be displayed, both in the processed output and in the console. 22855 22856Note that in order to see console debug output you will also need to pass @code{-v verbose} to ffmpeg. 22857 22858Viewing point matches in the output video is only supported for RGB input. 22859 22860Defaults to @code{0}. 22861 22862@item adaptive_crop 22863Whether or not to do a tiny bit of cropping at the borders to cut down on the amount of mirrored pixels. 22864 22865Defaults to @code{1}. 22866 22867@item refine_features 22868Whether or not feature points should be refined at a sub-pixel level. 22869 22870This can be turned off for a slight performance gain at the cost of precision. 22871 22872Defaults to @code{1}. 22873 22874@item smooth_strength 22875The strength of the smoothing applied to the camera path from @code{0.0} to @code{1.0}. 22876 22877@code{1.0} is the maximum smoothing strength while values less than that result in less smoothing. 22878 22879@code{0.0} causes the filter to adaptively choose a smoothing strength on a per-frame basis. 22880 22881Defaults to @code{0.0}. 22882 22883@item smooth_window_multiplier 22884Controls the size of the smoothing window (the number of frames buffered to determine motion information from). 22885 22886The size of the smoothing window is determined by multiplying the framerate of the video by this number. 22887 22888Acceptable values range from @code{0.1} to @code{10.0}. 22889 22890Larger values increase the amount of motion data available for determining how to smooth the camera path, 22891potentially improving smoothness, but also increase latency and memory usage. 22892 22893Defaults to @code{2.0}. 22894 22895@end table 22896 22897@subsection Examples 22898 22899@itemize 22900@item 22901Stabilize a video with a fixed, medium smoothing strength: 22902@example 22903-i INPUT -vf "hwupload, deshake_opencl=smooth_strength=0.5, hwdownload" OUTPUT 22904@end example 22905 22906@item 22907Stabilize a video with debugging (both in console and in rendered video): 22908@example 22909-i INPUT -filter_complex "[0:v]format=rgba, hwupload, deshake_opencl=debug=1, hwdownload, format=rgba, format=yuv420p" -v verbose OUTPUT 22910@end example 22911@end itemize 22912 22913@section dilation_opencl 22914 22915Apply dilation effect to the video. 22916 22917This filter replaces the pixel by the local(3x3) maximum. 22918 22919It accepts the following options: 22920 22921@table @option 22922@item threshold0 22923@item threshold1 22924@item threshold2 22925@item threshold3 22926Limit the maximum change for each plane. Range is @code{[0, 65535]} and default value is @code{65535}. 22927If @code{0}, plane will remain unchanged. 22928 22929@item coordinates 22930Flag which specifies the pixel to refer to. 22931Range is @code{[0, 255]} and default value is @code{255}, i.e. all eight pixels are used. 22932 22933Flags to local 3x3 coordinates region centered on @code{x}: 22934 22935 1 2 3 22936 22937 4 x 5 22938 22939 6 7 8 22940@end table 22941 22942@subsection Example 22943 22944@itemize 22945@item 22946Apply dilation filter with threshold0 set to 30, threshold1 set 40, threshold2 set to 50 and coordinates set to 231, setting each pixel of the output to the local maximum between pixels: 1, 2, 3, 6, 7, 8 of the 3x3 region centered on it in the input. If the difference between input pixel and local maximum is more then threshold of the corresponding plane, output pixel will be set to input pixel + threshold of corresponding plane. 22947@example 22948-i INPUT -vf "hwupload, dilation_opencl=30:40:50:coordinates=231, hwdownload" OUTPUT 22949@end example 22950@end itemize 22951 22952@section nlmeans_opencl 22953 22954Non-local Means denoise filter through OpenCL, this filter accepts same options as @ref{nlmeans}. 22955 22956@section overlay_opencl 22957 22958Overlay one video on top of another. 22959 22960It takes two inputs and has one output. The first input is the "main" video on which the second input is overlaid. 22961This filter requires same memory layout for all the inputs. So, format conversion may be needed. 22962 22963The filter accepts the following options: 22964 22965@table @option 22966 22967@item x 22968Set the x coordinate of the overlaid video on the main video. 22969Default value is @code{0}. 22970 22971@item y 22972Set the y coordinate of the overlaid video on the main video. 22973Default value is @code{0}. 22974 22975@end table 22976 22977@subsection Examples 22978 22979@itemize 22980@item 22981Overlay an image LOGO at the top-left corner of the INPUT video. Both inputs are yuv420p format. 22982@example 22983-i INPUT -i LOGO -filter_complex "[0:v]hwupload[a], [1:v]format=yuv420p, hwupload[b], [a][b]overlay_opencl, hwdownload" OUTPUT 22984@end example 22985@item 22986The inputs have same memory layout for color channels , the overlay has additional alpha plane, like INPUT is yuv420p, and the LOGO is yuva420p. 22987@example 22988-i INPUT -i LOGO -filter_complex "[0:v]hwupload[a], [1:v]format=yuva420p, hwupload[b], [a][b]overlay_opencl, hwdownload" OUTPUT 22989@end example 22990 22991@end itemize 22992 22993@section pad_opencl 22994 22995Add paddings to the input image, and place the original input at the 22996provided @var{x}, @var{y} coordinates. 22997 22998It accepts the following options: 22999 23000@table @option 23001@item width, w 23002@item height, h 23003Specify an expression for the size of the output image with the 23004paddings added. If the value for @var{width} or @var{height} is 0, the 23005corresponding input size is used for the output. 23006 23007The @var{width} expression can reference the value set by the 23008@var{height} expression, and vice versa. 23009 23010The default value of @var{width} and @var{height} is 0. 23011 23012@item x 23013@item y 23014Specify the offsets to place the input image at within the padded area, 23015with respect to the top/left border of the output image. 23016 23017The @var{x} expression can reference the value set by the @var{y} 23018expression, and vice versa. 23019 23020The default value of @var{x} and @var{y} is 0. 23021 23022If @var{x} or @var{y} evaluate to a negative number, they'll be changed 23023so the input image is centered on the padded area. 23024 23025@item color 23026Specify the color of the padded area. For the syntax of this option, 23027check the @ref{color syntax,,"Color" section in the ffmpeg-utils 23028manual,ffmpeg-utils}. 23029 23030@item aspect 23031Pad to an aspect instead to a resolution. 23032@end table 23033 23034The value for the @var{width}, @var{height}, @var{x}, and @var{y} 23035options are expressions containing the following constants: 23036 23037@table @option 23038@item in_w 23039@item in_h 23040The input video width and height. 23041 23042@item iw 23043@item ih 23044These are the same as @var{in_w} and @var{in_h}. 23045 23046@item out_w 23047@item out_h 23048The output width and height (the size of the padded area), as 23049specified by the @var{width} and @var{height} expressions. 23050 23051@item ow 23052@item oh 23053These are the same as @var{out_w} and @var{out_h}. 23054 23055@item x 23056@item y 23057The x and y offsets as specified by the @var{x} and @var{y} 23058expressions, or NAN if not yet specified. 23059 23060@item a 23061same as @var{iw} / @var{ih} 23062 23063@item sar 23064input sample aspect ratio 23065 23066@item dar 23067input display aspect ratio, it is the same as (@var{iw} / @var{ih}) * @var{sar} 23068@end table 23069 23070@section prewitt_opencl 23071 23072Apply the Prewitt operator (@url{https://en.wikipedia.org/wiki/Prewitt_operator}) to input video stream. 23073 23074The filter accepts the following option: 23075 23076@table @option 23077@item planes 23078Set which planes to filter. Default value is @code{0xf}, by which all planes are processed. 23079 23080@item scale 23081Set value which will be multiplied with filtered result. 23082Range is @code{[0.0, 65535]} and default value is @code{1.0}. 23083 23084@item delta 23085Set value which will be added to filtered result. 23086Range is @code{[-65535, 65535]} and default value is @code{0.0}. 23087@end table 23088 23089@subsection Example 23090 23091@itemize 23092@item 23093Apply the Prewitt operator with scale set to 2 and delta set to 10. 23094@example 23095-i INPUT -vf "hwupload, prewitt_opencl=scale=2:delta=10, hwdownload" OUTPUT 23096@end example 23097@end itemize 23098 23099@anchor{program_opencl} 23100@section program_opencl 23101 23102Filter video using an OpenCL program. 23103 23104@table @option 23105 23106@item source 23107OpenCL program source file. 23108 23109@item kernel 23110Kernel name in program. 23111 23112@item inputs 23113Number of inputs to the filter. Defaults to 1. 23114 23115@item size, s 23116Size of output frames. Defaults to the same as the first input. 23117 23118@end table 23119 23120The @code{program_opencl} filter also supports the @ref{framesync} options. 23121 23122The program source file must contain a kernel function with the given name, 23123which will be run once for each plane of the output. Each run on a plane 23124gets enqueued as a separate 2D global NDRange with one work-item for each 23125pixel to be generated. The global ID offset for each work-item is therefore 23126the coordinates of a pixel in the destination image. 23127 23128The kernel function needs to take the following arguments: 23129@itemize 23130@item 23131Destination image, @var{__write_only image2d_t}. 23132 23133This image will become the output; the kernel should write all of it. 23134@item 23135Frame index, @var{unsigned int}. 23136 23137This is a counter starting from zero and increasing by one for each frame. 23138@item 23139Source images, @var{__read_only image2d_t}. 23140 23141These are the most recent images on each input. The kernel may read from 23142them to generate the output, but they can't be written to. 23143@end itemize 23144 23145Example programs: 23146 23147@itemize 23148@item 23149Copy the input to the output (output must be the same size as the input). 23150@verbatim 23151__kernel void copy(__write_only image2d_t destination, 23152 unsigned int index, 23153 __read_only image2d_t source) 23154{ 23155 const sampler_t sampler = CLK_NORMALIZED_COORDS_FALSE; 23156 23157 int2 location = (int2)(get_global_id(0), get_global_id(1)); 23158 23159 float4 value = read_imagef(source, sampler, location); 23160 23161 write_imagef(destination, location, value); 23162} 23163@end verbatim 23164 23165@item 23166Apply a simple transformation, rotating the input by an amount increasing 23167with the index counter. Pixel values are linearly interpolated by the 23168sampler, and the output need not have the same dimensions as the input. 23169@verbatim 23170__kernel void rotate_image(__write_only image2d_t dst, 23171 unsigned int index, 23172 __read_only image2d_t src) 23173{ 23174 const sampler_t sampler = (CLK_NORMALIZED_COORDS_FALSE | 23175 CLK_FILTER_LINEAR); 23176 23177 float angle = (float)index / 100.0f; 23178 23179 float2 dst_dim = convert_float2(get_image_dim(dst)); 23180 float2 src_dim = convert_float2(get_image_dim(src)); 23181 23182 float2 dst_cen = dst_dim / 2.0f; 23183 float2 src_cen = src_dim / 2.0f; 23184 23185 int2 dst_loc = (int2)(get_global_id(0), get_global_id(1)); 23186 23187 float2 dst_pos = convert_float2(dst_loc) - dst_cen; 23188 float2 src_pos = { 23189 cos(angle) * dst_pos.x - sin(angle) * dst_pos.y, 23190 sin(angle) * dst_pos.x + cos(angle) * dst_pos.y 23191 }; 23192 src_pos = src_pos * src_dim / dst_dim; 23193 23194 float2 src_loc = src_pos + src_cen; 23195 23196 if (src_loc.x < 0.0f || src_loc.y < 0.0f || 23197 src_loc.x > src_dim.x || src_loc.y > src_dim.y) 23198 write_imagef(dst, dst_loc, 0.5f); 23199 else 23200 write_imagef(dst, dst_loc, read_imagef(src, sampler, src_loc)); 23201} 23202@end verbatim 23203 23204@item 23205Blend two inputs together, with the amount of each input used varying 23206with the index counter. 23207@verbatim 23208__kernel void blend_images(__write_only image2d_t dst, 23209 unsigned int index, 23210 __read_only image2d_t src1, 23211 __read_only image2d_t src2) 23212{ 23213 const sampler_t sampler = (CLK_NORMALIZED_COORDS_FALSE | 23214 CLK_FILTER_LINEAR); 23215 23216 float blend = (cos((float)index / 50.0f) + 1.0f) / 2.0f; 23217 23218 int2 dst_loc = (int2)(get_global_id(0), get_global_id(1)); 23219 int2 src1_loc = dst_loc * get_image_dim(src1) / get_image_dim(dst); 23220 int2 src2_loc = dst_loc * get_image_dim(src2) / get_image_dim(dst); 23221 23222 float4 val1 = read_imagef(src1, sampler, src1_loc); 23223 float4 val2 = read_imagef(src2, sampler, src2_loc); 23224 23225 write_imagef(dst, dst_loc, val1 * blend + val2 * (1.0f - blend)); 23226} 23227@end verbatim 23228 23229@end itemize 23230 23231@section roberts_opencl 23232Apply the Roberts cross operator (@url{https://en.wikipedia.org/wiki/Roberts_cross}) to input video stream. 23233 23234The filter accepts the following option: 23235 23236@table @option 23237@item planes 23238Set which planes to filter. Default value is @code{0xf}, by which all planes are processed. 23239 23240@item scale 23241Set value which will be multiplied with filtered result. 23242Range is @code{[0.0, 65535]} and default value is @code{1.0}. 23243 23244@item delta 23245Set value which will be added to filtered result. 23246Range is @code{[-65535, 65535]} and default value is @code{0.0}. 23247@end table 23248 23249@subsection Example 23250 23251@itemize 23252@item 23253Apply the Roberts cross operator with scale set to 2 and delta set to 10 23254@example 23255-i INPUT -vf "hwupload, roberts_opencl=scale=2:delta=10, hwdownload" OUTPUT 23256@end example 23257@end itemize 23258 23259@section sobel_opencl 23260 23261Apply the Sobel operator (@url{https://en.wikipedia.org/wiki/Sobel_operator}) to input video stream. 23262 23263The filter accepts the following option: 23264 23265@table @option 23266@item planes 23267Set which planes to filter. Default value is @code{0xf}, by which all planes are processed. 23268 23269@item scale 23270Set value which will be multiplied with filtered result. 23271Range is @code{[0.0, 65535]} and default value is @code{1.0}. 23272 23273@item delta 23274Set value which will be added to filtered result. 23275Range is @code{[-65535, 65535]} and default value is @code{0.0}. 23276@end table 23277 23278@subsection Example 23279 23280@itemize 23281@item 23282Apply sobel operator with scale set to 2 and delta set to 10 23283@example 23284-i INPUT -vf "hwupload, sobel_opencl=scale=2:delta=10, hwdownload" OUTPUT 23285@end example 23286@end itemize 23287 23288@section tonemap_opencl 23289 23290Perform HDR(PQ/HLG) to SDR conversion with tone-mapping. 23291 23292It accepts the following parameters: 23293 23294@table @option 23295@item tonemap 23296Specify the tone-mapping operator to be used. Same as tonemap option in @ref{tonemap}. 23297 23298@item param 23299Tune the tone mapping algorithm. same as param option in @ref{tonemap}. 23300 23301@item desat 23302Apply desaturation for highlights that exceed this level of brightness. The 23303higher the parameter, the more color information will be preserved. This 23304setting helps prevent unnaturally blown-out colors for super-highlights, by 23305(smoothly) turning into white instead. This makes images feel more natural, 23306at the cost of reducing information about out-of-range colors. 23307 23308The default value is 0.5, and the algorithm here is a little different from 23309the cpu version tonemap currently. A setting of 0.0 disables this option. 23310 23311@item threshold 23312The tonemapping algorithm parameters is fine-tuned per each scene. And a threshold 23313is used to detect whether the scene has changed or not. If the distance between 23314the current frame average brightness and the current running average exceeds 23315a threshold value, we would re-calculate scene average and peak brightness. 23316The default value is 0.2. 23317 23318@item format 23319Specify the output pixel format. 23320 23321Currently supported formats are: 23322@table @var 23323@item p010 23324@item nv12 23325@end table 23326 23327@item range, r 23328Set the output color range. 23329 23330Possible values are: 23331@table @var 23332@item tv/mpeg 23333@item pc/jpeg 23334@end table 23335 23336Default is same as input. 23337 23338@item primaries, p 23339Set the output color primaries. 23340 23341Possible values are: 23342@table @var 23343@item bt709 23344@item bt2020 23345@end table 23346 23347Default is same as input. 23348 23349@item transfer, t 23350Set the output transfer characteristics. 23351 23352Possible values are: 23353@table @var 23354@item bt709 23355@item bt2020 23356@end table 23357 23358Default is bt709. 23359 23360@item matrix, m 23361Set the output colorspace matrix. 23362 23363Possible value are: 23364@table @var 23365@item bt709 23366@item bt2020 23367@end table 23368 23369Default is same as input. 23370 23371@end table 23372 23373@subsection Example 23374 23375@itemize 23376@item 23377Convert HDR(PQ/HLG) video to bt2020-transfer-characteristic p010 format using linear operator. 23378@example 23379-i INPUT -vf "format=p010,hwupload,tonemap_opencl=t=bt2020:tonemap=linear:format=p010,hwdownload,format=p010" OUTPUT 23380@end example 23381@end itemize 23382 23383@section unsharp_opencl 23384 23385Sharpen or blur the input video. 23386 23387It accepts the following parameters: 23388 23389@table @option 23390@item luma_msize_x, lx 23391Set the luma matrix horizontal size. 23392Range is @code{[1, 23]} and default value is @code{5}. 23393 23394@item luma_msize_y, ly 23395Set the luma matrix vertical size. 23396Range is @code{[1, 23]} and default value is @code{5}. 23397 23398@item luma_amount, la 23399Set the luma effect strength. 23400Range is @code{[-10, 10]} and default value is @code{1.0}. 23401 23402Negative values will blur the input video, while positive values will 23403sharpen it, a value of zero will disable the effect. 23404 23405@item chroma_msize_x, cx 23406Set the chroma matrix horizontal size. 23407Range is @code{[1, 23]} and default value is @code{5}. 23408 23409@item chroma_msize_y, cy 23410Set the chroma matrix vertical size. 23411Range is @code{[1, 23]} and default value is @code{5}. 23412 23413@item chroma_amount, ca 23414Set the chroma effect strength. 23415Range is @code{[-10, 10]} and default value is @code{0.0}. 23416 23417Negative values will blur the input video, while positive values will 23418sharpen it, a value of zero will disable the effect. 23419 23420@end table 23421 23422All parameters are optional and default to the equivalent of the 23423string '5:5:1.0:5:5:0.0'. 23424 23425@subsection Examples 23426 23427@itemize 23428@item 23429Apply strong luma sharpen effect: 23430@example 23431-i INPUT -vf "hwupload, unsharp_opencl=luma_msize_x=7:luma_msize_y=7:luma_amount=2.5, hwdownload" OUTPUT 23432@end example 23433 23434@item 23435Apply a strong blur of both luma and chroma parameters: 23436@example 23437-i INPUT -vf "hwupload, unsharp_opencl=7:7:-2:7:7:-2, hwdownload" OUTPUT 23438@end example 23439@end itemize 23440 23441@section xfade_opencl 23442 23443Cross fade two videos with custom transition effect by using OpenCL. 23444 23445It accepts the following options: 23446 23447@table @option 23448@item transition 23449Set one of possible transition effects. 23450 23451@table @option 23452@item custom 23453Select custom transition effect, the actual transition description 23454will be picked from source and kernel options. 23455 23456@item fade 23457@item wipeleft 23458@item wiperight 23459@item wipeup 23460@item wipedown 23461@item slideleft 23462@item slideright 23463@item slideup 23464@item slidedown 23465 23466Default transition is fade. 23467@end table 23468 23469@item source 23470OpenCL program source file for custom transition. 23471 23472@item kernel 23473Set name of kernel to use for custom transition from program source file. 23474 23475@item duration 23476Set duration of video transition. 23477 23478@item offset 23479Set time of start of transition relative to first video. 23480@end table 23481 23482The program source file must contain a kernel function with the given name, 23483which will be run once for each plane of the output. Each run on a plane 23484gets enqueued as a separate 2D global NDRange with one work-item for each 23485pixel to be generated. The global ID offset for each work-item is therefore 23486the coordinates of a pixel in the destination image. 23487 23488The kernel function needs to take the following arguments: 23489@itemize 23490@item 23491Destination image, @var{__write_only image2d_t}. 23492 23493This image will become the output; the kernel should write all of it. 23494 23495@item 23496First Source image, @var{__read_only image2d_t}. 23497Second Source image, @var{__read_only image2d_t}. 23498 23499These are the most recent images on each input. The kernel may read from 23500them to generate the output, but they can't be written to. 23501 23502@item 23503Transition progress, @var{float}. This value is always between 0 and 1 inclusive. 23504@end itemize 23505 23506Example programs: 23507 23508@itemize 23509@item 23510Apply dots curtain transition effect: 23511@verbatim 23512__kernel void blend_images(__write_only image2d_t dst, 23513 __read_only image2d_t src1, 23514 __read_only image2d_t src2, 23515 float progress) 23516{ 23517 const sampler_t sampler = (CLK_NORMALIZED_COORDS_FALSE | 23518 CLK_FILTER_LINEAR); 23519 int2 p = (int2)(get_global_id(0), get_global_id(1)); 23520 float2 rp = (float2)(get_global_id(0), get_global_id(1)); 23521 float2 dim = (float2)(get_image_dim(src1).x, get_image_dim(src1).y); 23522 rp = rp / dim; 23523 23524 float2 dots = (float2)(20.0, 20.0); 23525 float2 center = (float2)(0,0); 23526 float2 unused; 23527 23528 float4 val1 = read_imagef(src1, sampler, p); 23529 float4 val2 = read_imagef(src2, sampler, p); 23530 bool next = distance(fract(rp * dots, &unused), (float2)(0.5, 0.5)) < (progress / distance(rp, center)); 23531 23532 write_imagef(dst, p, next ? val1 : val2); 23533} 23534@end verbatim 23535 23536@end itemize 23537 23538@c man end OPENCL VIDEO FILTERS 23539 23540@chapter VAAPI Video Filters 23541@c man begin VAAPI VIDEO FILTERS 23542 23543VAAPI Video filters are usually used with VAAPI decoder and VAAPI encoder. Below is a description of VAAPI video filters. 23544 23545To enable compilation of these filters you need to configure FFmpeg with 23546@code{--enable-vaapi}. 23547 23548To use vaapi filters, you need to setup the vaapi device correctly. For more information, please read @url{https://trac.ffmpeg.org/wiki/Hardware/VAAPI} 23549 23550@section tonemap_vaapi 23551 23552Perform HDR(High Dynamic Range) to SDR(Standard Dynamic Range) conversion with tone-mapping. 23553It maps the dynamic range of HDR10 content to the SDR content. 23554It currently only accepts HDR10 as input. 23555 23556It accepts the following parameters: 23557 23558@table @option 23559@item format 23560Specify the output pixel format. 23561 23562Currently supported formats are: 23563@table @var 23564@item p010 23565@item nv12 23566@end table 23567 23568Default is nv12. 23569 23570@item primaries, p 23571Set the output color primaries. 23572 23573Default is same as input. 23574 23575@item transfer, t 23576Set the output transfer characteristics. 23577 23578Default is bt709. 23579 23580@item matrix, m 23581Set the output colorspace matrix. 23582 23583Default is same as input. 23584 23585@end table 23586 23587@subsection Example 23588 23589@itemize 23590@item 23591Convert HDR(HDR10) video to bt2020-transfer-characteristic p010 format 23592@example 23593tonemap_vaapi=format=p010:t=bt2020-10 23594@end example 23595@end itemize 23596 23597@c man end VAAPI VIDEO FILTERS 23598 23599@chapter Video Sources 23600@c man begin VIDEO SOURCES 23601 23602Below is a description of the currently available video sources. 23603 23604@section buffer 23605 23606Buffer video frames, and make them available to the filter chain. 23607 23608This source is mainly intended for a programmatic use, in particular 23609through the interface defined in @file{libavfilter/buffersrc.h}. 23610 23611It accepts the following parameters: 23612 23613@table @option 23614 23615@item video_size 23616Specify the size (width and height) of the buffered video frames. For the 23617syntax of this option, check the 23618@ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}. 23619 23620@item width 23621The input video width. 23622 23623@item height 23624The input video height. 23625 23626@item pix_fmt 23627A string representing the pixel format of the buffered video frames. 23628It may be a number corresponding to a pixel format, or a pixel format 23629name. 23630 23631@item time_base 23632Specify the timebase assumed by the timestamps of the buffered frames. 23633 23634@item frame_rate 23635Specify the frame rate expected for the video stream. 23636 23637@item pixel_aspect, sar 23638The sample (pixel) aspect ratio of the input video. 23639 23640@item sws_param 23641This option is deprecated and ignored. Prepend @code{sws_flags=@var{flags};} 23642to the filtergraph description to specify swscale flags for automatically 23643inserted scalers. See @ref{Filtergraph syntax}. 23644 23645@item hw_frames_ctx 23646When using a hardware pixel format, this should be a reference to an 23647AVHWFramesContext describing input frames. 23648@end table 23649 23650For example: 23651@example 23652buffer=width=320:height=240:pix_fmt=yuv410p:time_base=1/24:sar=1 23653@end example 23654 23655will instruct the source to accept video frames with size 320x240 and 23656with format "yuv410p", assuming 1/24 as the timestamps timebase and 23657square pixels (1:1 sample aspect ratio). 23658Since the pixel format with name "yuv410p" corresponds to the number 6 23659(check the enum AVPixelFormat definition in @file{libavutil/pixfmt.h}), 23660this example corresponds to: 23661@example 23662buffer=size=320x240:pixfmt=6:time_base=1/24:pixel_aspect=1/1 23663@end example 23664 23665Alternatively, the options can be specified as a flat string, but this 23666syntax is deprecated: 23667 23668@var{width}:@var{height}:@var{pix_fmt}:@var{time_base.num}:@var{time_base.den}:@var{pixel_aspect.num}:@var{pixel_aspect.den} 23669 23670@section cellauto 23671 23672Create a pattern generated by an elementary cellular automaton. 23673 23674The initial state of the cellular automaton can be defined through the 23675@option{filename} and @option{pattern} options. If such options are 23676not specified an initial state is created randomly. 23677 23678At each new frame a new row in the video is filled with the result of 23679the cellular automaton next generation. The behavior when the whole 23680frame is filled is defined by the @option{scroll} option. 23681 23682This source accepts the following options: 23683 23684@table @option 23685@item filename, f 23686Read the initial cellular automaton state, i.e. the starting row, from 23687the specified file. 23688In the file, each non-whitespace character is considered an alive 23689cell, a newline will terminate the row, and further characters in the 23690file will be ignored. 23691 23692@item pattern, p 23693Read the initial cellular automaton state, i.e. the starting row, from 23694the specified string. 23695 23696Each non-whitespace character in the string is considered an alive 23697cell, a newline will terminate the row, and further characters in the 23698string will be ignored. 23699 23700@item rate, r 23701Set the video rate, that is the number of frames generated per second. 23702Default is 25. 23703 23704@item random_fill_ratio, ratio 23705Set the random fill ratio for the initial cellular automaton row. It 23706is a floating point number value ranging from 0 to 1, defaults to 237071/PHI. 23708 23709This option is ignored when a file or a pattern is specified. 23710 23711@item random_seed, seed 23712Set the seed for filling randomly the initial row, must be an integer 23713included between 0 and UINT32_MAX. If not specified, or if explicitly 23714set to -1, the filter will try to use a good random seed on a best 23715effort basis. 23716 23717@item rule 23718Set the cellular automaton rule, it is a number ranging from 0 to 255. 23719Default value is 110. 23720 23721@item size, s 23722Set the size of the output video. For the syntax of this option, check the 23723@ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}. 23724 23725If @option{filename} or @option{pattern} is specified, the size is set 23726by default to the width of the specified initial state row, and the 23727height is set to @var{width} * PHI. 23728 23729If @option{size} is set, it must contain the width of the specified 23730pattern string, and the specified pattern will be centered in the 23731larger row. 23732 23733If a filename or a pattern string is not specified, the size value 23734defaults to "320x518" (used for a randomly generated initial state). 23735 23736@item scroll 23737If set to 1, scroll the output upward when all the rows in the output 23738have been already filled. If set to 0, the new generated row will be 23739written over the top row just after the bottom row is filled. 23740Defaults to 1. 23741 23742@item start_full, full 23743If set to 1, completely fill the output with generated rows before 23744outputting the first frame. 23745This is the default behavior, for disabling set the value to 0. 23746 23747@item stitch 23748If set to 1, stitch the left and right row edges together. 23749This is the default behavior, for disabling set the value to 0. 23750@end table 23751 23752@subsection Examples 23753 23754@itemize 23755@item 23756Read the initial state from @file{pattern}, and specify an output of 23757size 200x400. 23758@example 23759cellauto=f=pattern:s=200x400 23760@end example 23761 23762@item 23763Generate a random initial row with a width of 200 cells, with a fill 23764ratio of 2/3: 23765@example 23766cellauto=ratio=2/3:s=200x200 23767@end example 23768 23769@item 23770Create a pattern generated by rule 18 starting by a single alive cell 23771centered on an initial row with width 100: 23772@example 23773cellauto=p=@@:s=100x400:full=0:rule=18 23774@end example 23775 23776@item 23777Specify a more elaborated initial pattern: 23778@example 23779cellauto=p='@@@@ @@ @@@@':s=100x400:full=0:rule=18 23780@end example 23781 23782@end itemize 23783 23784@anchor{coreimagesrc} 23785@section coreimagesrc 23786Video source generated on GPU using Apple's CoreImage API on OSX. 23787 23788This video source is a specialized version of the @ref{coreimage} video filter. 23789Use a core image generator at the beginning of the applied filterchain to 23790generate the content. 23791 23792The coreimagesrc video source accepts the following options: 23793@table @option 23794@item list_generators 23795List all available generators along with all their respective options as well as 23796possible minimum and maximum values along with the default values. 23797@example 23798list_generators=true 23799@end example 23800 23801@item size, s 23802Specify the size of the sourced video. For the syntax of this option, check the 23803@ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}. 23804The default value is @code{320x240}. 23805 23806@item rate, r 23807Specify the frame rate of the sourced video, as the number of frames 23808generated per second. It has to be a string in the format 23809@var{frame_rate_num}/@var{frame_rate_den}, an integer number, a floating point 23810number or a valid video frame rate abbreviation. The default value is 23811"25". 23812 23813@item sar 23814Set the sample aspect ratio of the sourced video. 23815 23816@item duration, d 23817Set the duration of the sourced video. See 23818@ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils} 23819for the accepted syntax. 23820 23821If not specified, or the expressed duration is negative, the video is 23822supposed to be generated forever. 23823@end table 23824 23825Additionally, all options of the @ref{coreimage} video filter are accepted. 23826A complete filterchain can be used for further processing of the 23827generated input without CPU-HOST transfer. See @ref{coreimage} documentation 23828and examples for details. 23829 23830@subsection Examples 23831 23832@itemize 23833 23834@item 23835Use CIQRCodeGenerator to create a QR code for the FFmpeg homepage, 23836given as complete and escaped command-line for Apple's standard bash shell: 23837@example 23838ffmpeg -f lavfi -i coreimagesrc=s=100x100:filter=CIQRCodeGenerator@@inputMessage=https\\\\\://FFmpeg.org/@@inputCorrectionLevel=H -frames:v 1 QRCode.png 23839@end example 23840This example is equivalent to the QRCode example of @ref{coreimage} without the 23841need for a nullsrc video source. 23842@end itemize 23843 23844 23845@section gradients 23846Generate several gradients. 23847 23848@table @option 23849@item size, s 23850Set frame size. For the syntax of this option, check the @ref{video size syntax,,"Video 23851size" section in the ffmpeg-utils manual,ffmpeg-utils}. Default value is "640x480". 23852 23853@item rate, r 23854Set frame rate, expressed as number of frames per second. Default 23855value is "25". 23856 23857@item c0, c1, c2, c3, c4, c5, c6, c7 23858Set 8 colors. Default values for colors is to pick random one. 23859 23860@item x0, y0, y0, y1 23861Set gradient line source and destination points. If negative or out of range, random ones 23862are picked. 23863 23864@item nb_colors, n 23865Set number of colors to use at once. Allowed range is from 2 to 8. Default value is 2. 23866 23867@item seed 23868Set seed for picking gradient line points. 23869 23870@item duration, d 23871Set the duration of the sourced video. See 23872@ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils} 23873for the accepted syntax. 23874 23875If not specified, or the expressed duration is negative, the video is 23876supposed to be generated forever. 23877 23878@item speed 23879Set speed of gradients rotation. 23880@end table 23881 23882 23883@section mandelbrot 23884 23885Generate a Mandelbrot set fractal, and progressively zoom towards the 23886point specified with @var{start_x} and @var{start_y}. 23887 23888This source accepts the following options: 23889 23890@table @option 23891 23892@item end_pts 23893Set the terminal pts value. Default value is 400. 23894 23895@item end_scale 23896Set the terminal scale value. 23897Must be a floating point value. Default value is 0.3. 23898 23899@item inner 23900Set the inner coloring mode, that is the algorithm used to draw the 23901Mandelbrot fractal internal region. 23902 23903It shall assume one of the following values: 23904@table @option 23905@item black 23906Set black mode. 23907@item convergence 23908Show time until convergence. 23909@item mincol 23910Set color based on point closest to the origin of the iterations. 23911@item period 23912Set period mode. 23913@end table 23914 23915Default value is @var{mincol}. 23916 23917@item bailout 23918Set the bailout value. Default value is 10.0. 23919 23920@item maxiter 23921Set the maximum of iterations performed by the rendering 23922algorithm. Default value is 7189. 23923 23924@item outer 23925Set outer coloring mode. 23926It shall assume one of following values: 23927@table @option 23928@item iteration_count 23929Set iteration count mode. 23930@item normalized_iteration_count 23931set normalized iteration count mode. 23932@end table 23933Default value is @var{normalized_iteration_count}. 23934 23935@item rate, r 23936Set frame rate, expressed as number of frames per second. Default 23937value is "25". 23938 23939@item size, s 23940Set frame size. For the syntax of this option, check the @ref{video size syntax,,"Video 23941size" section in the ffmpeg-utils manual,ffmpeg-utils}. Default value is "640x480". 23942 23943@item start_scale 23944Set the initial scale value. Default value is 3.0. 23945 23946@item start_x 23947Set the initial x position. Must be a floating point value between 23948-100 and 100. Default value is -0.743643887037158704752191506114774. 23949 23950@item start_y 23951Set the initial y position. Must be a floating point value between 23952-100 and 100. Default value is -0.131825904205311970493132056385139. 23953@end table 23954 23955@section mptestsrc 23956 23957Generate various test patterns, as generated by the MPlayer test filter. 23958 23959The size of the generated video is fixed, and is 256x256. 23960This source is useful in particular for testing encoding features. 23961 23962This source accepts the following options: 23963 23964@table @option 23965 23966@item rate, r 23967Specify the frame rate of the sourced video, as the number of frames 23968generated per second. It has to be a string in the format 23969@var{frame_rate_num}/@var{frame_rate_den}, an integer number, a floating point 23970number or a valid video frame rate abbreviation. The default value is 23971"25". 23972 23973@item duration, d 23974Set the duration of the sourced video. See 23975@ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils} 23976for the accepted syntax. 23977 23978If not specified, or the expressed duration is negative, the video is 23979supposed to be generated forever. 23980 23981@item test, t 23982 23983Set the number or the name of the test to perform. Supported tests are: 23984@table @option 23985@item dc_luma 23986@item dc_chroma 23987@item freq_luma 23988@item freq_chroma 23989@item amp_luma 23990@item amp_chroma 23991@item cbp 23992@item mv 23993@item ring1 23994@item ring2 23995@item all 23996 23997@item max_frames, m 23998Set the maximum number of frames generated for each test, default value is 30. 23999 24000@end table 24001 24002Default value is "all", which will cycle through the list of all tests. 24003@end table 24004 24005Some examples: 24006@example 24007mptestsrc=t=dc_luma 24008@end example 24009 24010will generate a "dc_luma" test pattern. 24011 24012@section frei0r_src 24013 24014Provide a frei0r source. 24015 24016To enable compilation of this filter you need to install the frei0r 24017header and configure FFmpeg with @code{--enable-frei0r}. 24018 24019This source accepts the following parameters: 24020 24021@table @option 24022 24023@item size 24024The size of the video to generate. For the syntax of this option, check the 24025@ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}. 24026 24027@item framerate 24028The framerate of the generated video. It may be a string of the form 24029@var{num}/@var{den} or a frame rate abbreviation. 24030 24031@item filter_name 24032The name to the frei0r source to load. For more information regarding frei0r and 24033how to set the parameters, read the @ref{frei0r} section in the video filters 24034documentation. 24035 24036@item filter_params 24037A '|'-separated list of parameters to pass to the frei0r source. 24038 24039@end table 24040 24041For example, to generate a frei0r partik0l source with size 200x200 24042and frame rate 10 which is overlaid on the overlay filter main input: 24043@example 24044frei0r_src=size=200x200:framerate=10:filter_name=partik0l:filter_params=1234 [overlay]; [in][overlay] overlay 24045@end example 24046 24047@section life 24048 24049Generate a life pattern. 24050 24051This source is based on a generalization of John Conway's life game. 24052 24053The sourced input represents a life grid, each pixel represents a cell 24054which can be in one of two possible states, alive or dead. Every cell 24055interacts with its eight neighbours, which are the cells that are 24056horizontally, vertically, or diagonally adjacent. 24057 24058At each interaction the grid evolves according to the adopted rule, 24059which specifies the number of neighbor alive cells which will make a 24060cell stay alive or born. The @option{rule} option allows one to specify 24061the rule to adopt. 24062 24063This source accepts the following options: 24064 24065@table @option 24066@item filename, f 24067Set the file from which to read the initial grid state. In the file, 24068each non-whitespace character is considered an alive cell, and newline 24069is used to delimit the end of each row. 24070 24071If this option is not specified, the initial grid is generated 24072randomly. 24073 24074@item rate, r 24075Set the video rate, that is the number of frames generated per second. 24076Default is 25. 24077 24078@item random_fill_ratio, ratio 24079Set the random fill ratio for the initial random grid. It is a 24080floating point number value ranging from 0 to 1, defaults to 1/PHI. 24081It is ignored when a file is specified. 24082 24083@item random_seed, seed 24084Set the seed for filling the initial random grid, must be an integer 24085included between 0 and UINT32_MAX. If not specified, or if explicitly 24086set to -1, the filter will try to use a good random seed on a best 24087effort basis. 24088 24089@item rule 24090Set the life rule. 24091 24092A rule can be specified with a code of the kind "S@var{NS}/B@var{NB}", 24093where @var{NS} and @var{NB} are sequences of numbers in the range 0-8, 24094@var{NS} specifies the number of alive neighbor cells which make a 24095live cell stay alive, and @var{NB} the number of alive neighbor cells 24096which make a dead cell to become alive (i.e. to "born"). 24097"s" and "b" can be used in place of "S" and "B", respectively. 24098 24099Alternatively a rule can be specified by an 18-bits integer. The 9 24100high order bits are used to encode the next cell state if it is alive 24101for each number of neighbor alive cells, the low order bits specify 24102the rule for "borning" new cells. Higher order bits encode for an 24103higher number of neighbor cells. 24104For example the number 6153 = @code{(12<<9)+9} specifies a stay alive 24105rule of 12 and a born rule of 9, which corresponds to "S23/B03". 24106 24107Default value is "S23/B3", which is the original Conway's game of life 24108rule, and will keep a cell alive if it has 2 or 3 neighbor alive 24109cells, and will born a new cell if there are three alive cells around 24110a dead cell. 24111 24112@item size, s 24113Set the size of the output video. For the syntax of this option, check the 24114@ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}. 24115 24116If @option{filename} is specified, the size is set by default to the 24117same size of the input file. If @option{size} is set, it must contain 24118the size specified in the input file, and the initial grid defined in 24119that file is centered in the larger resulting area. 24120 24121If a filename is not specified, the size value defaults to "320x240" 24122(used for a randomly generated initial grid). 24123 24124@item stitch 24125If set to 1, stitch the left and right grid edges together, and the 24126top and bottom edges also. Defaults to 1. 24127 24128@item mold 24129Set cell mold speed. If set, a dead cell will go from @option{death_color} to 24130@option{mold_color} with a step of @option{mold}. @option{mold} can have a 24131value from 0 to 255. 24132 24133@item life_color 24134Set the color of living (or new born) cells. 24135 24136@item death_color 24137Set the color of dead cells. If @option{mold} is set, this is the first color 24138used to represent a dead cell. 24139 24140@item mold_color 24141Set mold color, for definitely dead and moldy cells. 24142 24143For the syntax of these 3 color options, check the @ref{color syntax,,"Color" section in the 24144ffmpeg-utils manual,ffmpeg-utils}. 24145@end table 24146 24147@subsection Examples 24148 24149@itemize 24150@item 24151Read a grid from @file{pattern}, and center it on a grid of size 24152300x300 pixels: 24153@example 24154life=f=pattern:s=300x300 24155@end example 24156 24157@item 24158Generate a random grid of size 200x200, with a fill ratio of 2/3: 24159@example 24160life=ratio=2/3:s=200x200 24161@end example 24162 24163@item 24164Specify a custom rule for evolving a randomly generated grid: 24165@example 24166life=rule=S14/B34 24167@end example 24168 24169@item 24170Full example with slow death effect (mold) using @command{ffplay}: 24171@example 24172ffplay -f lavfi life=s=300x200:mold=10:r=60:ratio=0.1:death_color=#C83232:life_color=#00ff00,scale=1200:800:flags=16 24173@end example 24174@end itemize 24175 24176@anchor{allrgb} 24177@anchor{allyuv} 24178@anchor{color} 24179@anchor{haldclutsrc} 24180@anchor{nullsrc} 24181@anchor{pal75bars} 24182@anchor{pal100bars} 24183@anchor{rgbtestsrc} 24184@anchor{smptebars} 24185@anchor{smptehdbars} 24186@anchor{testsrc} 24187@anchor{testsrc2} 24188@anchor{yuvtestsrc} 24189@section allrgb, allyuv, color, haldclutsrc, nullsrc, pal75bars, pal100bars, rgbtestsrc, smptebars, smptehdbars, testsrc, testsrc2, yuvtestsrc 24190 24191The @code{allrgb} source returns frames of size 4096x4096 of all rgb colors. 24192 24193The @code{allyuv} source returns frames of size 4096x4096 of all yuv colors. 24194 24195The @code{color} source provides an uniformly colored input. 24196 24197The @code{haldclutsrc} source provides an identity Hald CLUT. See also 24198@ref{haldclut} filter. 24199 24200The @code{nullsrc} source returns unprocessed video frames. It is 24201mainly useful to be employed in analysis / debugging tools, or as the 24202source for filters which ignore the input data. 24203 24204The @code{pal75bars} source generates a color bars pattern, based on 24205EBU PAL recommendations with 75% color levels. 24206 24207The @code{pal100bars} source generates a color bars pattern, based on 24208EBU PAL recommendations with 100% color levels. 24209 24210The @code{rgbtestsrc} source generates an RGB test pattern useful for 24211detecting RGB vs BGR issues. You should see a red, green and blue 24212stripe from top to bottom. 24213 24214The @code{smptebars} source generates a color bars pattern, based on 24215the SMPTE Engineering Guideline EG 1-1990. 24216 24217The @code{smptehdbars} source generates a color bars pattern, based on 24218the SMPTE RP 219-2002. 24219 24220The @code{testsrc} source generates a test video pattern, showing a 24221color pattern, a scrolling gradient and a timestamp. This is mainly 24222intended for testing purposes. 24223 24224The @code{testsrc2} source is similar to testsrc, but supports more 24225pixel formats instead of just @code{rgb24}. This allows using it as an 24226input for other tests without requiring a format conversion. 24227 24228The @code{yuvtestsrc} source generates an YUV test pattern. You should 24229see a y, cb and cr stripe from top to bottom. 24230 24231The sources accept the following parameters: 24232 24233@table @option 24234 24235@item level 24236Specify the level of the Hald CLUT, only available in the @code{haldclutsrc} 24237source. A level of @code{N} generates a picture of @code{N*N*N} by @code{N*N*N} 24238pixels to be used as identity matrix for 3D lookup tables. Each component is 24239coded on a @code{1/(N*N)} scale. 24240 24241@item color, c 24242Specify the color of the source, only available in the @code{color} 24243source. For the syntax of this option, check the 24244@ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}. 24245 24246@item size, s 24247Specify the size of the sourced video. For the syntax of this option, check the 24248@ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}. 24249The default value is @code{320x240}. 24250 24251This option is not available with the @code{allrgb}, @code{allyuv}, and 24252@code{haldclutsrc} filters. 24253 24254@item rate, r 24255Specify the frame rate of the sourced video, as the number of frames 24256generated per second. It has to be a string in the format 24257@var{frame_rate_num}/@var{frame_rate_den}, an integer number, a floating point 24258number or a valid video frame rate abbreviation. The default value is 24259"25". 24260 24261@item duration, d 24262Set the duration of the sourced video. See 24263@ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils} 24264for the accepted syntax. 24265 24266If not specified, or the expressed duration is negative, the video is 24267supposed to be generated forever. 24268 24269Since the frame rate is used as time base, all frames including the last one 24270will have their full duration. If the specified duration is not a multiple 24271of the frame duration, it will be rounded up. 24272 24273@item sar 24274Set the sample aspect ratio of the sourced video. 24275 24276@item alpha 24277Specify the alpha (opacity) of the background, only available in the 24278@code{testsrc2} source. The value must be between 0 (fully transparent) and 24279255 (fully opaque, the default). 24280 24281@item decimals, n 24282Set the number of decimals to show in the timestamp, only available in the 24283@code{testsrc} source. 24284 24285The displayed timestamp value will correspond to the original 24286timestamp value multiplied by the power of 10 of the specified 24287value. Default value is 0. 24288@end table 24289 24290@subsection Examples 24291 24292@itemize 24293@item 24294Generate a video with a duration of 5.3 seconds, with size 24295176x144 and a frame rate of 10 frames per second: 24296@example 24297testsrc=duration=5.3:size=qcif:rate=10 24298@end example 24299 24300@item 24301The following graph description will generate a red source 24302with an opacity of 0.2, with size "qcif" and a frame rate of 10 24303frames per second: 24304@example 24305color=c=red@@0.2:s=qcif:r=10 24306@end example 24307 24308@item 24309If the input content is to be ignored, @code{nullsrc} can be used. The 24310following command generates noise in the luminance plane by employing 24311the @code{geq} filter: 24312@example 24313nullsrc=s=256x256, geq=random(1)*255:128:128 24314@end example 24315@end itemize 24316 24317@subsection Commands 24318 24319The @code{color} source supports the following commands: 24320 24321@table @option 24322@item c, color 24323Set the color of the created image. Accepts the same syntax of the 24324corresponding @option{color} option. 24325@end table 24326 24327@section openclsrc 24328 24329Generate video using an OpenCL program. 24330 24331@table @option 24332 24333@item source 24334OpenCL program source file. 24335 24336@item kernel 24337Kernel name in program. 24338 24339@item size, s 24340Size of frames to generate. This must be set. 24341 24342@item format 24343Pixel format to use for the generated frames. This must be set. 24344 24345@item rate, r 24346Number of frames generated every second. Default value is '25'. 24347 24348@end table 24349 24350For details of how the program loading works, see the @ref{program_opencl} 24351filter. 24352 24353Example programs: 24354 24355@itemize 24356@item 24357Generate a colour ramp by setting pixel values from the position of the pixel 24358in the output image. (Note that this will work with all pixel formats, but 24359the generated output will not be the same.) 24360@verbatim 24361__kernel void ramp(__write_only image2d_t dst, 24362 unsigned int index) 24363{ 24364 int2 loc = (int2)(get_global_id(0), get_global_id(1)); 24365 24366 float4 val; 24367 val.xy = val.zw = convert_float2(loc) / convert_float2(get_image_dim(dst)); 24368 24369 write_imagef(dst, loc, val); 24370} 24371@end verbatim 24372 24373@item 24374Generate a Sierpinski carpet pattern, panning by a single pixel each frame. 24375@verbatim 24376__kernel void sierpinski_carpet(__write_only image2d_t dst, 24377 unsigned int index) 24378{ 24379 int2 loc = (int2)(get_global_id(0), get_global_id(1)); 24380 24381 float4 value = 0.0f; 24382 int x = loc.x + index; 24383 int y = loc.y + index; 24384 while (x > 0 || y > 0) { 24385 if (x % 3 == 1 && y % 3 == 1) { 24386 value = 1.0f; 24387 break; 24388 } 24389 x /= 3; 24390 y /= 3; 24391 } 24392 24393 write_imagef(dst, loc, value); 24394} 24395@end verbatim 24396 24397@end itemize 24398 24399@section sierpinski 24400 24401Generate a Sierpinski carpet/triangle fractal, and randomly pan around. 24402 24403This source accepts the following options: 24404 24405@table @option 24406@item size, s 24407Set frame size. For the syntax of this option, check the @ref{video size syntax,,"Video 24408size" section in the ffmpeg-utils manual,ffmpeg-utils}. Default value is "640x480". 24409 24410@item rate, r 24411Set frame rate, expressed as number of frames per second. Default 24412value is "25". 24413 24414@item seed 24415Set seed which is used for random panning. 24416 24417@item jump 24418Set max jump for single pan destination. Allowed range is from 1 to 10000. 24419 24420@item type 24421Set fractal type, can be default @code{carpet} or @code{triangle}. 24422@end table 24423 24424@c man end VIDEO SOURCES 24425 24426@chapter Video Sinks 24427@c man begin VIDEO SINKS 24428 24429Below is a description of the currently available video sinks. 24430 24431@section buffersink 24432 24433Buffer video frames, and make them available to the end of the filter 24434graph. 24435 24436This sink is mainly intended for programmatic use, in particular 24437through the interface defined in @file{libavfilter/buffersink.h} 24438or the options system. 24439 24440It accepts a pointer to an AVBufferSinkContext structure, which 24441defines the incoming buffers' formats, to be passed as the opaque 24442parameter to @code{avfilter_init_filter} for initialization. 24443 24444@section nullsink 24445 24446Null video sink: do absolutely nothing with the input video. It is 24447mainly useful as a template and for use in analysis / debugging 24448tools. 24449 24450@c man end VIDEO SINKS 24451 24452@chapter Multimedia Filters 24453@c man begin MULTIMEDIA FILTERS 24454 24455Below is a description of the currently available multimedia filters. 24456 24457@section abitscope 24458 24459Convert input audio to a video output, displaying the audio bit scope. 24460 24461The filter accepts the following options: 24462 24463@table @option 24464@item rate, r 24465Set frame rate, expressed as number of frames per second. Default 24466value is "25". 24467 24468@item size, s 24469Specify the video size for the output. For the syntax of this option, check the 24470@ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}. 24471Default value is @code{1024x256}. 24472 24473@item colors 24474Specify list of colors separated by space or by '|' which will be used to 24475draw channels. Unrecognized or missing colors will be replaced 24476by white color. 24477@end table 24478 24479@section adrawgraph 24480Draw a graph using input audio metadata. 24481 24482See @ref{drawgraph} 24483 24484@section agraphmonitor 24485 24486See @ref{graphmonitor}. 24487 24488@section ahistogram 24489 24490Convert input audio to a video output, displaying the volume histogram. 24491 24492The filter accepts the following options: 24493 24494@table @option 24495@item dmode 24496Specify how histogram is calculated. 24497 24498It accepts the following values: 24499@table @samp 24500@item single 24501Use single histogram for all channels. 24502@item separate 24503Use separate histogram for each channel. 24504@end table 24505Default is @code{single}. 24506 24507@item rate, r 24508Set frame rate, expressed as number of frames per second. Default 24509value is "25". 24510 24511@item size, s 24512Specify the video size for the output. For the syntax of this option, check the 24513@ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}. 24514Default value is @code{hd720}. 24515 24516@item scale 24517Set display scale. 24518 24519It accepts the following values: 24520@table @samp 24521@item log 24522logarithmic 24523@item sqrt 24524square root 24525@item cbrt 24526cubic root 24527@item lin 24528linear 24529@item rlog 24530reverse logarithmic 24531@end table 24532Default is @code{log}. 24533 24534@item ascale 24535Set amplitude scale. 24536 24537It accepts the following values: 24538@table @samp 24539@item log 24540logarithmic 24541@item lin 24542linear 24543@end table 24544Default is @code{log}. 24545 24546@item acount 24547Set how much frames to accumulate in histogram. 24548Default is 1. Setting this to -1 accumulates all frames. 24549 24550@item rheight 24551Set histogram ratio of window height. 24552 24553@item slide 24554Set sonogram sliding. 24555 24556It accepts the following values: 24557@table @samp 24558@item replace 24559replace old rows with new ones. 24560@item scroll 24561scroll from top to bottom. 24562@end table 24563Default is @code{replace}. 24564@end table 24565 24566@section aphasemeter 24567 24568Measures phase of input audio, which is exported as metadata @code{lavfi.aphasemeter.phase}, 24569representing mean phase of current audio frame. A video output can also be produced and is 24570enabled by default. The audio is passed through as first output. 24571 24572Audio will be rematrixed to stereo if it has a different channel layout. Phase value is in 24573range @code{[-1, 1]} where @code{-1} means left and right channels are completely out of phase 24574and @code{1} means channels are in phase. 24575 24576The filter accepts the following options, all related to its video output: 24577 24578@table @option 24579@item rate, r 24580Set the output frame rate. Default value is @code{25}. 24581 24582@item size, s 24583Set the video size for the output. For the syntax of this option, check the 24584@ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}. 24585Default value is @code{800x400}. 24586 24587@item rc 24588@item gc 24589@item bc 24590Specify the red, green, blue contrast. Default values are @code{2}, 24591@code{7} and @code{1}. 24592Allowed range is @code{[0, 255]}. 24593 24594@item mpc 24595Set color which will be used for drawing median phase. If color is 24596@code{none} which is default, no median phase value will be drawn. 24597 24598@item video 24599Enable video output. Default is enabled. 24600@end table 24601 24602@subsection phasing detection 24603 24604The filter also detects out of phase and mono sequences in stereo streams. 24605It logs the sequence start, end and duration when it lasts longer or as long as the minimum set. 24606 24607The filter accepts the following options for this detection: 24608 24609@table @option 24610@item phasing 24611Enable mono and out of phase detection. Default is disabled. 24612 24613@item tolerance, t 24614Set phase tolerance for mono detection, in amplitude ratio. Default is @code{0}. 24615Allowed range is @code{[0, 1]}. 24616 24617@item angle, a 24618Set angle threshold for out of phase detection, in degree. Default is @code{170}. 24619Allowed range is @code{[90, 180]}. 24620 24621@item duration, d 24622Set mono or out of phase duration until notification, expressed in seconds. Default is @code{2}. 24623@end table 24624 24625@subsection Examples 24626 24627@itemize 24628@item 24629Complete example with @command{ffmpeg} to detect 1 second of mono with 0.001 phase tolerance: 24630@example 24631ffmpeg -i stereo.wav -af aphasemeter=video=0:phasing=1:duration=1:tolerance=0.001 -f null - 24632@end example 24633@end itemize 24634 24635@section avectorscope 24636 24637Convert input audio to a video output, representing the audio vector 24638scope. 24639 24640The filter is used to measure the difference between channels of stereo 24641audio stream. A monaural signal, consisting of identical left and right 24642signal, results in straight vertical line. Any stereo separation is visible 24643as a deviation from this line, creating a Lissajous figure. 24644If the straight (or deviation from it) but horizontal line appears this 24645indicates that the left and right channels are out of phase. 24646 24647The filter accepts the following options: 24648 24649@table @option 24650@item mode, m 24651Set the vectorscope mode. 24652 24653Available values are: 24654@table @samp 24655@item lissajous 24656Lissajous rotated by 45 degrees. 24657 24658@item lissajous_xy 24659Same as above but not rotated. 24660 24661@item polar 24662Shape resembling half of circle. 24663@end table 24664 24665Default value is @samp{lissajous}. 24666 24667@item size, s 24668Set the video size for the output. For the syntax of this option, check the 24669@ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}. 24670Default value is @code{400x400}. 24671 24672@item rate, r 24673Set the output frame rate. Default value is @code{25}. 24674 24675@item rc 24676@item gc 24677@item bc 24678@item ac 24679Specify the red, green, blue and alpha contrast. Default values are @code{40}, 24680@code{160}, @code{80} and @code{255}. 24681Allowed range is @code{[0, 255]}. 24682 24683@item rf 24684@item gf 24685@item bf 24686@item af 24687Specify the red, green, blue and alpha fade. Default values are @code{15}, 24688@code{10}, @code{5} and @code{5}. 24689Allowed range is @code{[0, 255]}. 24690 24691@item zoom 24692Set the zoom factor. Default value is @code{1}. Allowed range is @code{[0, 10]}. 24693Values lower than @var{1} will auto adjust zoom factor to maximal possible value. 24694 24695@item draw 24696Set the vectorscope drawing mode. 24697 24698Available values are: 24699@table @samp 24700@item dot 24701Draw dot for each sample. 24702 24703@item line 24704Draw line between previous and current sample. 24705@end table 24706 24707Default value is @samp{dot}. 24708 24709@item scale 24710Specify amplitude scale of audio samples. 24711 24712Available values are: 24713@table @samp 24714@item lin 24715Linear. 24716 24717@item sqrt 24718Square root. 24719 24720@item cbrt 24721Cubic root. 24722 24723@item log 24724Logarithmic. 24725@end table 24726 24727@item swap 24728Swap left channel axis with right channel axis. 24729 24730@item mirror 24731Mirror axis. 24732 24733@table @samp 24734@item none 24735No mirror. 24736 24737@item x 24738Mirror only x axis. 24739 24740@item y 24741Mirror only y axis. 24742 24743@item xy 24744Mirror both axis. 24745@end table 24746 24747@end table 24748 24749@subsection Examples 24750 24751@itemize 24752@item 24753Complete example using @command{ffplay}: 24754@example 24755ffplay -f lavfi 'amovie=input.mp3, asplit [a][out1]; 24756 [a] avectorscope=zoom=1.3:rc=2:gc=200:bc=10:rf=1:gf=8:bf=7 [out0]' 24757@end example 24758@end itemize 24759 24760@section bench, abench 24761 24762Benchmark part of a filtergraph. 24763 24764The filter accepts the following options: 24765 24766@table @option 24767@item action 24768Start or stop a timer. 24769 24770Available values are: 24771@table @samp 24772@item start 24773Get the current time, set it as frame metadata (using the key 24774@code{lavfi.bench.start_time}), and forward the frame to the next filter. 24775 24776@item stop 24777Get the current time and fetch the @code{lavfi.bench.start_time} metadata from 24778the input frame metadata to get the time difference. Time difference, average, 24779maximum and minimum time (respectively @code{t}, @code{avg}, @code{max} and 24780@code{min}) are then printed. The timestamps are expressed in seconds. 24781@end table 24782@end table 24783 24784@subsection Examples 24785 24786@itemize 24787@item 24788Benchmark @ref{selectivecolor} filter: 24789@example 24790bench=start,selectivecolor=reds=-.2 .12 -.49,bench=stop 24791@end example 24792@end itemize 24793 24794@section concat 24795 24796Concatenate audio and video streams, joining them together one after the 24797other. 24798 24799The filter works on segments of synchronized video and audio streams. All 24800segments must have the same number of streams of each type, and that will 24801also be the number of streams at output. 24802 24803The filter accepts the following options: 24804 24805@table @option 24806 24807@item n 24808Set the number of segments. Default is 2. 24809 24810@item v 24811Set the number of output video streams, that is also the number of video 24812streams in each segment. Default is 1. 24813 24814@item a 24815Set the number of output audio streams, that is also the number of audio 24816streams in each segment. Default is 0. 24817 24818@item unsafe 24819Activate unsafe mode: do not fail if segments have a different format. 24820 24821@end table 24822 24823The filter has @var{v}+@var{a} outputs: first @var{v} video outputs, then 24824@var{a} audio outputs. 24825 24826There are @var{n}x(@var{v}+@var{a}) inputs: first the inputs for the first 24827segment, in the same order as the outputs, then the inputs for the second 24828segment, etc. 24829 24830Related streams do not always have exactly the same duration, for various 24831reasons including codec frame size or sloppy authoring. For that reason, 24832related synchronized streams (e.g. a video and its audio track) should be 24833concatenated at once. The concat filter will use the duration of the longest 24834stream in each segment (except the last one), and if necessary pad shorter 24835audio streams with silence. 24836 24837For this filter to work correctly, all segments must start at timestamp 0. 24838 24839All corresponding streams must have the same parameters in all segments; the 24840filtering system will automatically select a common pixel format for video 24841streams, and a common sample format, sample rate and channel layout for 24842audio streams, but other settings, such as resolution, must be converted 24843explicitly by the user. 24844 24845Different frame rates are acceptable but will result in variable frame rate 24846at output; be sure to configure the output file to handle it. 24847 24848@subsection Examples 24849 24850@itemize 24851@item 24852Concatenate an opening, an episode and an ending, all in bilingual version 24853(video in stream 0, audio in streams 1 and 2): 24854@example 24855ffmpeg -i opening.mkv -i episode.mkv -i ending.mkv -filter_complex \ 24856 '[0:0] [0:1] [0:2] [1:0] [1:1] [1:2] [2:0] [2:1] [2:2] 24857 concat=n=3:v=1:a=2 [v] [a1] [a2]' \ 24858 -map '[v]' -map '[a1]' -map '[a2]' output.mkv 24859@end example 24860 24861@item 24862Concatenate two parts, handling audio and video separately, using the 24863(a)movie sources, and adjusting the resolution: 24864@example 24865movie=part1.mp4, scale=512:288 [v1] ; amovie=part1.mp4 [a1] ; 24866movie=part2.mp4, scale=512:288 [v2] ; amovie=part2.mp4 [a2] ; 24867[v1] [v2] concat [outv] ; [a1] [a2] concat=v=0:a=1 [outa] 24868@end example 24869Note that a desync will happen at the stitch if the audio and video streams 24870do not have exactly the same duration in the first file. 24871 24872@end itemize 24873 24874@subsection Commands 24875 24876This filter supports the following commands: 24877@table @option 24878@item next 24879Close the current segment and step to the next one 24880@end table 24881 24882@anchor{ebur128} 24883@section ebur128 24884 24885EBU R128 scanner filter. This filter takes an audio stream and analyzes its loudness 24886level. By default, it logs a message at a frequency of 10Hz with the 24887Momentary loudness (identified by @code{M}), Short-term loudness (@code{S}), 24888Integrated loudness (@code{I}) and Loudness Range (@code{LRA}). 24889 24890The filter can only analyze streams which have a sampling rate of 48000 Hz and whose 24891sample format is double-precision floating point. The input stream will be converted to 24892this specification, if needed. Users may need to insert aformat and/or aresample filters 24893after this filter to obtain the original parameters. 24894 24895The filter also has a video output (see the @var{video} option) with a real 24896time graph to observe the loudness evolution. The graphic contains the logged 24897message mentioned above, so it is not printed anymore when this option is set, 24898unless the verbose logging is set. The main graphing area contains the 24899short-term loudness (3 seconds of analysis), and the gauge on the right is for 24900the momentary loudness (400 milliseconds), but can optionally be configured 24901to instead display short-term loudness (see @var{gauge}). 24902 24903The green area marks a +/- 1LU target range around the target loudness 24904(-23LUFS by default, unless modified through @var{target}). 24905 24906More information about the Loudness Recommendation EBU R128 on 24907@url{http://tech.ebu.ch/loudness}. 24908 24909The filter accepts the following options: 24910 24911@table @option 24912 24913@item video 24914Activate the video output. The audio stream is passed unchanged whether this 24915option is set or no. The video stream will be the first output stream if 24916activated. Default is @code{0}. 24917 24918@item size 24919Set the video size. This option is for video only. For the syntax of this 24920option, check the 24921@ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}. 24922Default and minimum resolution is @code{640x480}. 24923 24924@item meter 24925Set the EBU scale meter. Default is @code{9}. Common values are @code{9} and 24926@code{18}, respectively for EBU scale meter +9 and EBU scale meter +18. Any 24927other integer value between this range is allowed. 24928 24929@item metadata 24930Set metadata injection. If set to @code{1}, the audio input will be segmented 24931into 100ms output frames, each of them containing various loudness information 24932in metadata. All the metadata keys are prefixed with @code{lavfi.r128.}. 24933 24934Default is @code{0}. 24935 24936@item framelog 24937Force the frame logging level. 24938 24939Available values are: 24940@table @samp 24941@item info 24942information logging level 24943@item verbose 24944verbose logging level 24945@end table 24946 24947By default, the logging level is set to @var{info}. If the @option{video} or 24948the @option{metadata} options are set, it switches to @var{verbose}. 24949 24950@item peak 24951Set peak mode(s). 24952 24953Available modes can be cumulated (the option is a @code{flag} type). Possible 24954values are: 24955@table @samp 24956@item none 24957Disable any peak mode (default). 24958@item sample 24959Enable sample-peak mode. 24960 24961Simple peak mode looking for the higher sample value. It logs a message 24962for sample-peak (identified by @code{SPK}). 24963@item true 24964Enable true-peak mode. 24965 24966If enabled, the peak lookup is done on an over-sampled version of the input 24967stream for better peak accuracy. It logs a message for true-peak. 24968(identified by @code{TPK}) and true-peak per frame (identified by @code{FTPK}). 24969This mode requires a build with @code{libswresample}. 24970@end table 24971 24972@item dualmono 24973Treat mono input files as "dual mono". If a mono file is intended for playback 24974on a stereo system, its EBU R128 measurement will be perceptually incorrect. 24975If set to @code{true}, this option will compensate for this effect. 24976Multi-channel input files are not affected by this option. 24977 24978@item panlaw 24979Set a specific pan law to be used for the measurement of dual mono files. 24980This parameter is optional, and has a default value of -3.01dB. 24981 24982@item target 24983Set a specific target level (in LUFS) used as relative zero in the visualization. 24984This parameter is optional and has a default value of -23LUFS as specified 24985by EBU R128. However, material published online may prefer a level of -16LUFS 24986(e.g. for use with podcasts or video platforms). 24987 24988@item gauge 24989Set the value displayed by the gauge. Valid values are @code{momentary} and s 24990@code{shortterm}. By default the momentary value will be used, but in certain 24991scenarios it may be more useful to observe the short term value instead (e.g. 24992live mixing). 24993 24994@item scale 24995Sets the display scale for the loudness. Valid parameters are @code{absolute} 24996(in LUFS) or @code{relative} (LU) relative to the target. This only affects the 24997video output, not the summary or continuous log output. 24998@end table 24999 25000@subsection Examples 25001 25002@itemize 25003@item 25004Real-time graph using @command{ffplay}, with a EBU scale meter +18: 25005@example 25006ffplay -f lavfi -i "amovie=input.mp3,ebur128=video=1:meter=18 [out0][out1]" 25007@end example 25008 25009@item 25010Run an analysis with @command{ffmpeg}: 25011@example 25012ffmpeg -nostats -i input.mp3 -filter_complex ebur128 -f null - 25013@end example 25014@end itemize 25015 25016@section interleave, ainterleave 25017 25018Temporally interleave frames from several inputs. 25019 25020@code{interleave} works with video inputs, @code{ainterleave} with audio. 25021 25022These filters read frames from several inputs and send the oldest 25023queued frame to the output. 25024 25025Input streams must have well defined, monotonically increasing frame 25026timestamp values. 25027 25028In order to submit one frame to output, these filters need to enqueue 25029at least one frame for each input, so they cannot work in case one 25030input is not yet terminated and will not receive incoming frames. 25031 25032For example consider the case when one input is a @code{select} filter 25033which always drops input frames. The @code{interleave} filter will keep 25034reading from that input, but it will never be able to send new frames 25035to output until the input sends an end-of-stream signal. 25036 25037Also, depending on inputs synchronization, the filters will drop 25038frames in case one input receives more frames than the other ones, and 25039the queue is already filled. 25040 25041These filters accept the following options: 25042 25043@table @option 25044@item nb_inputs, n 25045Set the number of different inputs, it is 2 by default. 25046 25047@item duration 25048How to determine the end-of-stream. 25049 25050@table @option 25051@item longest 25052The duration of the longest input. (default) 25053 25054@item shortest 25055The duration of the shortest input. 25056 25057@item first 25058The duration of the first input. 25059@end table 25060 25061@end table 25062 25063@subsection Examples 25064 25065@itemize 25066@item 25067Interleave frames belonging to different streams using @command{ffmpeg}: 25068@example 25069ffmpeg -i bambi.avi -i pr0n.mkv -filter_complex "[0:v][1:v] interleave" out.avi 25070@end example 25071 25072@item 25073Add flickering blur effect: 25074@example 25075select='if(gt(random(0), 0.2), 1, 2)':n=2 [tmp], boxblur=2:2, [tmp] interleave 25076@end example 25077@end itemize 25078 25079@section metadata, ametadata 25080 25081Manipulate frame metadata. 25082 25083This filter accepts the following options: 25084 25085@table @option 25086@item mode 25087Set mode of operation of the filter. 25088 25089Can be one of the following: 25090 25091@table @samp 25092@item select 25093If both @code{value} and @code{key} is set, select frames 25094which have such metadata. If only @code{key} is set, select 25095every frame that has such key in metadata. 25096 25097@item add 25098Add new metadata @code{key} and @code{value}. If key is already available 25099do nothing. 25100 25101@item modify 25102Modify value of already present key. 25103 25104@item delete 25105If @code{value} is set, delete only keys that have such value. 25106Otherwise, delete key. If @code{key} is not set, delete all metadata values in 25107the frame. 25108 25109@item print 25110Print key and its value if metadata was found. If @code{key} is not set print all 25111metadata values available in frame. 25112@end table 25113 25114@item key 25115Set key used with all modes. Must be set for all modes except @code{print} and @code{delete}. 25116 25117@item value 25118Set metadata value which will be used. This option is mandatory for 25119@code{modify} and @code{add} mode. 25120 25121@item function 25122Which function to use when comparing metadata value and @code{value}. 25123 25124Can be one of following: 25125 25126@table @samp 25127@item same_str 25128Values are interpreted as strings, returns true if metadata value is same as @code{value}. 25129 25130@item starts_with 25131Values are interpreted as strings, returns true if metadata value starts with 25132the @code{value} option string. 25133 25134@item less 25135Values are interpreted as floats, returns true if metadata value is less than @code{value}. 25136 25137@item equal 25138Values are interpreted as floats, returns true if @code{value} is equal with metadata value. 25139 25140@item greater 25141Values are interpreted as floats, returns true if metadata value is greater than @code{value}. 25142 25143@item expr 25144Values are interpreted as floats, returns true if expression from option @code{expr} 25145evaluates to true. 25146 25147@item ends_with 25148Values are interpreted as strings, returns true if metadata value ends with 25149the @code{value} option string. 25150@end table 25151 25152@item expr 25153Set expression which is used when @code{function} is set to @code{expr}. 25154The expression is evaluated through the eval API and can contain the following 25155constants: 25156 25157@table @option 25158@item VALUE1 25159Float representation of @code{value} from metadata key. 25160 25161@item VALUE2 25162Float representation of @code{value} as supplied by user in @code{value} option. 25163@end table 25164 25165@item file 25166If specified in @code{print} mode, output is written to the named file. Instead of 25167plain filename any writable url can be specified. Filename ``-'' is a shorthand 25168for standard output. If @code{file} option is not set, output is written to the log 25169with AV_LOG_INFO loglevel. 25170 25171@item direct 25172Reduces buffering in print mode when output is written to a URL set using @var{file}. 25173 25174@end table 25175 25176@subsection Examples 25177 25178@itemize 25179@item 25180Print all metadata values for frames with key @code{lavfi.signalstats.YDIF} with values 25181between 0 and 1. 25182@example 25183signalstats,metadata=print:key=lavfi.signalstats.YDIF:value=0:function=expr:expr='between(VALUE1,0,1)' 25184@end example 25185@item 25186Print silencedetect output to file @file{metadata.txt}. 25187@example 25188silencedetect,ametadata=mode=print:file=metadata.txt 25189@end example 25190@item 25191Direct all metadata to a pipe with file descriptor 4. 25192@example 25193metadata=mode=print:file='pipe\:4' 25194@end example 25195@end itemize 25196 25197@section perms, aperms 25198 25199Set read/write permissions for the output frames. 25200 25201These filters are mainly aimed at developers to test direct path in the 25202following filter in the filtergraph. 25203 25204The filters accept the following options: 25205 25206@table @option 25207@item mode 25208Select the permissions mode. 25209 25210It accepts the following values: 25211@table @samp 25212@item none 25213Do nothing. This is the default. 25214@item ro 25215Set all the output frames read-only. 25216@item rw 25217Set all the output frames directly writable. 25218@item toggle 25219Make the frame read-only if writable, and writable if read-only. 25220@item random 25221Set each output frame read-only or writable randomly. 25222@end table 25223 25224@item seed 25225Set the seed for the @var{random} mode, must be an integer included between 25226@code{0} and @code{UINT32_MAX}. If not specified, or if explicitly set to 25227@code{-1}, the filter will try to use a good random seed on a best effort 25228basis. 25229@end table 25230 25231Note: in case of auto-inserted filter between the permission filter and the 25232following one, the permission might not be received as expected in that 25233following filter. Inserting a @ref{format} or @ref{aformat} filter before the 25234perms/aperms filter can avoid this problem. 25235 25236@section realtime, arealtime 25237 25238Slow down filtering to match real time approximately. 25239 25240These filters will pause the filtering for a variable amount of time to 25241match the output rate with the input timestamps. 25242They are similar to the @option{re} option to @code{ffmpeg}. 25243 25244They accept the following options: 25245 25246@table @option 25247@item limit 25248Time limit for the pauses. Any pause longer than that will be considered 25249a timestamp discontinuity and reset the timer. Default is 2 seconds. 25250@item speed 25251Speed factor for processing. The value must be a float larger than zero. 25252Values larger than 1.0 will result in faster than realtime processing, 25253smaller will slow processing down. The @var{limit} is automatically adapted 25254accordingly. Default is 1.0. 25255 25256A processing speed faster than what is possible without these filters cannot 25257be achieved. 25258@end table 25259 25260@anchor{select} 25261@section select, aselect 25262 25263Select frames to pass in output. 25264 25265This filter accepts the following options: 25266 25267@table @option 25268 25269@item expr, e 25270Set expression, which is evaluated for each input frame. 25271 25272If the expression is evaluated to zero, the frame is discarded. 25273 25274If the evaluation result is negative or NaN, the frame is sent to the 25275first output; otherwise it is sent to the output with index 25276@code{ceil(val)-1}, assuming that the input index starts from 0. 25277 25278For example a value of @code{1.2} corresponds to the output with index 25279@code{ceil(1.2)-1 = 2-1 = 1}, that is the second output. 25280 25281@item outputs, n 25282Set the number of outputs. The output to which to send the selected 25283frame is based on the result of the evaluation. Default value is 1. 25284@end table 25285 25286The expression can contain the following constants: 25287 25288@table @option 25289@item n 25290The (sequential) number of the filtered frame, starting from 0. 25291 25292@item selected_n 25293The (sequential) number of the selected frame, starting from 0. 25294 25295@item prev_selected_n 25296The sequential number of the last selected frame. It's NAN if undefined. 25297 25298@item TB 25299The timebase of the input timestamps. 25300 25301@item pts 25302The PTS (Presentation TimeStamp) of the filtered video frame, 25303expressed in @var{TB} units. It's NAN if undefined. 25304 25305@item t 25306The PTS of the filtered video frame, 25307expressed in seconds. It's NAN if undefined. 25308 25309@item prev_pts 25310The PTS of the previously filtered video frame. It's NAN if undefined. 25311 25312@item prev_selected_pts 25313The PTS of the last previously filtered video frame. It's NAN if undefined. 25314 25315@item prev_selected_t 25316The PTS of the last previously selected video frame, expressed in seconds. It's NAN if undefined. 25317 25318@item start_pts 25319The PTS of the first video frame in the video. It's NAN if undefined. 25320 25321@item start_t 25322The time of the first video frame in the video. It's NAN if undefined. 25323 25324@item pict_type @emph{(video only)} 25325The type of the filtered frame. It can assume one of the following 25326values: 25327@table @option 25328@item I 25329@item P 25330@item B 25331@item S 25332@item SI 25333@item SP 25334@item BI 25335@end table 25336 25337@item interlace_type @emph{(video only)} 25338The frame interlace type. It can assume one of the following values: 25339@table @option 25340@item PROGRESSIVE 25341The frame is progressive (not interlaced). 25342@item TOPFIRST 25343The frame is top-field-first. 25344@item BOTTOMFIRST 25345The frame is bottom-field-first. 25346@end table 25347 25348@item consumed_sample_n @emph{(audio only)} 25349the number of selected samples before the current frame 25350 25351@item samples_n @emph{(audio only)} 25352the number of samples in the current frame 25353 25354@item sample_rate @emph{(audio only)} 25355the input sample rate 25356 25357@item key 25358This is 1 if the filtered frame is a key-frame, 0 otherwise. 25359 25360@item pos 25361the position in the file of the filtered frame, -1 if the information 25362is not available (e.g. for synthetic video) 25363 25364@item scene @emph{(video only)} 25365value between 0 and 1 to indicate a new scene; a low value reflects a low 25366probability for the current frame to introduce a new scene, while a higher 25367value means the current frame is more likely to be one (see the example below) 25368 25369@item concatdec_select 25370The concat demuxer can select only part of a concat input file by setting an 25371inpoint and an outpoint, but the output packets may not be entirely contained 25372in the selected interval. By using this variable, it is possible to skip frames 25373generated by the concat demuxer which are not exactly contained in the selected 25374interval. 25375 25376This works by comparing the frame pts against the @var{lavf.concat.start_time} 25377and the @var{lavf.concat.duration} packet metadata values which are also 25378present in the decoded frames. 25379 25380The @var{concatdec_select} variable is -1 if the frame pts is at least 25381start_time and either the duration metadata is missing or the frame pts is less 25382than start_time + duration, 0 otherwise, and NaN if the start_time metadata is 25383missing. 25384 25385That basically means that an input frame is selected if its pts is within the 25386interval set by the concat demuxer. 25387 25388@end table 25389 25390The default value of the select expression is "1". 25391 25392@subsection Examples 25393 25394@itemize 25395@item 25396Select all frames in input: 25397@example 25398select 25399@end example 25400 25401The example above is the same as: 25402@example 25403select=1 25404@end example 25405 25406@item 25407Skip all frames: 25408@example 25409select=0 25410@end example 25411 25412@item 25413Select only I-frames: 25414@example 25415select='eq(pict_type\,I)' 25416@end example 25417 25418@item 25419Select one frame every 100: 25420@example 25421select='not(mod(n\,100))' 25422@end example 25423 25424@item 25425Select only frames contained in the 10-20 time interval: 25426@example 25427select=between(t\,10\,20) 25428@end example 25429 25430@item 25431Select only I-frames contained in the 10-20 time interval: 25432@example 25433select=between(t\,10\,20)*eq(pict_type\,I) 25434@end example 25435 25436@item 25437Select frames with a minimum distance of 10 seconds: 25438@example 25439select='isnan(prev_selected_t)+gte(t-prev_selected_t\,10)' 25440@end example 25441 25442@item 25443Use aselect to select only audio frames with samples number > 100: 25444@example 25445aselect='gt(samples_n\,100)' 25446@end example 25447 25448@item 25449Create a mosaic of the first scenes: 25450@example 25451ffmpeg -i video.avi -vf select='gt(scene\,0.4)',scale=160:120,tile -frames:v 1 preview.png 25452@end example 25453 25454Comparing @var{scene} against a value between 0.3 and 0.5 is generally a sane 25455choice. 25456 25457@item 25458Send even and odd frames to separate outputs, and compose them: 25459@example 25460select=n=2:e='mod(n, 2)+1' [odd][even]; [odd] pad=h=2*ih [tmp]; [tmp][even] overlay=y=h 25461@end example 25462 25463@item 25464Select useful frames from an ffconcat file which is using inpoints and 25465outpoints but where the source files are not intra frame only. 25466@example 25467ffmpeg -copyts -vsync 0 -segment_time_metadata 1 -i input.ffconcat -vf select=concatdec_select -af aselect=concatdec_select output.avi 25468@end example 25469@end itemize 25470 25471@section sendcmd, asendcmd 25472 25473Send commands to filters in the filtergraph. 25474 25475These filters read commands to be sent to other filters in the 25476filtergraph. 25477 25478@code{sendcmd} must be inserted between two video filters, 25479@code{asendcmd} must be inserted between two audio filters, but apart 25480from that they act the same way. 25481 25482The specification of commands can be provided in the filter arguments 25483with the @var{commands} option, or in a file specified by the 25484@var{filename} option. 25485 25486These filters accept the following options: 25487@table @option 25488@item commands, c 25489Set the commands to be read and sent to the other filters. 25490@item filename, f 25491Set the filename of the commands to be read and sent to the other 25492filters. 25493@end table 25494 25495@subsection Commands syntax 25496 25497A commands description consists of a sequence of interval 25498specifications, comprising a list of commands to be executed when a 25499particular event related to that interval occurs. The occurring event 25500is typically the current frame time entering or leaving a given time 25501interval. 25502 25503An interval is specified by the following syntax: 25504@example 25505@var{START}[-@var{END}] @var{COMMANDS}; 25506@end example 25507 25508The time interval is specified by the @var{START} and @var{END} times. 25509@var{END} is optional and defaults to the maximum time. 25510 25511The current frame time is considered within the specified interval if 25512it is included in the interval [@var{START}, @var{END}), that is when 25513the time is greater or equal to @var{START} and is lesser than 25514@var{END}. 25515 25516@var{COMMANDS} consists of a sequence of one or more command 25517specifications, separated by ",", relating to that interval. The 25518syntax of a command specification is given by: 25519@example 25520[@var{FLAGS}] @var{TARGET} @var{COMMAND} @var{ARG} 25521@end example 25522 25523@var{FLAGS} is optional and specifies the type of events relating to 25524the time interval which enable sending the specified command, and must 25525be a non-null sequence of identifier flags separated by "+" or "|" and 25526enclosed between "[" and "]". 25527 25528The following flags are recognized: 25529@table @option 25530@item enter 25531The command is sent when the current frame timestamp enters the 25532specified interval. In other words, the command is sent when the 25533previous frame timestamp was not in the given interval, and the 25534current is. 25535 25536@item leave 25537The command is sent when the current frame timestamp leaves the 25538specified interval. In other words, the command is sent when the 25539previous frame timestamp was in the given interval, and the 25540current is not. 25541 25542@item expr 25543The command @var{ARG} is interpreted as expression and result of 25544expression is passed as @var{ARG}. 25545 25546The expression is evaluated through the eval API and can contain the following 25547constants: 25548 25549@table @option 25550@item POS 25551Original position in the file of the frame, or undefined if undefined 25552for the current frame. 25553 25554@item PTS 25555The presentation timestamp in input. 25556 25557@item N 25558The count of the input frame for video or audio, starting from 0. 25559 25560@item T 25561The time in seconds of the current frame. 25562 25563@item TS 25564The start time in seconds of the current command interval. 25565 25566@item TE 25567The end time in seconds of the current command interval. 25568 25569@item TI 25570The interpolated time of the current command interval, TI = (T - TS) / (TE - TS). 25571@end table 25572 25573@end table 25574 25575If @var{FLAGS} is not specified, a default value of @code{[enter]} is 25576assumed. 25577 25578@var{TARGET} specifies the target of the command, usually the name of 25579the filter class or a specific filter instance name. 25580 25581@var{COMMAND} specifies the name of the command for the target filter. 25582 25583@var{ARG} is optional and specifies the optional list of argument for 25584the given @var{COMMAND}. 25585 25586Between one interval specification and another, whitespaces, or 25587sequences of characters starting with @code{#} until the end of line, 25588are ignored and can be used to annotate comments. 25589 25590A simplified BNF description of the commands specification syntax 25591follows: 25592@example 25593@var{COMMAND_FLAG} ::= "enter" | "leave" 25594@var{COMMAND_FLAGS} ::= @var{COMMAND_FLAG} [(+|"|")@var{COMMAND_FLAG}] 25595@var{COMMAND} ::= ["[" @var{COMMAND_FLAGS} "]"] @var{TARGET} @var{COMMAND} [@var{ARG}] 25596@var{COMMANDS} ::= @var{COMMAND} [,@var{COMMANDS}] 25597@var{INTERVAL} ::= @var{START}[-@var{END}] @var{COMMANDS} 25598@var{INTERVALS} ::= @var{INTERVAL}[;@var{INTERVALS}] 25599@end example 25600 25601@subsection Examples 25602 25603@itemize 25604@item 25605Specify audio tempo change at second 4: 25606@example 25607asendcmd=c='4.0 atempo tempo 1.5',atempo 25608@end example 25609 25610@item 25611Target a specific filter instance: 25612@example 25613asendcmd=c='4.0 atempo@@my tempo 1.5',atempo@@my 25614@end example 25615 25616@item 25617Specify a list of drawtext and hue commands in a file. 25618@example 25619# show text in the interval 5-10 256205.0-10.0 [enter] drawtext reinit 'fontfile=FreeSerif.ttf:text=hello world', 25621 [leave] drawtext reinit 'fontfile=FreeSerif.ttf:text='; 25622 25623# desaturate the image in the interval 15-20 2562415.0-20.0 [enter] hue s 0, 25625 [enter] drawtext reinit 'fontfile=FreeSerif.ttf:text=nocolor', 25626 [leave] hue s 1, 25627 [leave] drawtext reinit 'fontfile=FreeSerif.ttf:text=color'; 25628 25629# apply an exponential saturation fade-out effect, starting from time 25 2563025 [enter] hue s exp(25-t) 25631@end example 25632 25633A filtergraph allowing to read and process the above command list 25634stored in a file @file{test.cmd}, can be specified with: 25635@example 25636sendcmd=f=test.cmd,drawtext=fontfile=FreeSerif.ttf:text='',hue 25637@end example 25638@end itemize 25639 25640@anchor{setpts} 25641@section setpts, asetpts 25642 25643Change the PTS (presentation timestamp) of the input frames. 25644 25645@code{setpts} works on video frames, @code{asetpts} on audio frames. 25646 25647This filter accepts the following options: 25648 25649@table @option 25650 25651@item expr 25652The expression which is evaluated for each frame to construct its timestamp. 25653 25654@end table 25655 25656The expression is evaluated through the eval API and can contain the following 25657constants: 25658 25659@table @option 25660@item FRAME_RATE, FR 25661frame rate, only defined for constant frame-rate video 25662 25663@item PTS 25664The presentation timestamp in input 25665 25666@item N 25667The count of the input frame for video or the number of consumed samples, 25668not including the current frame for audio, starting from 0. 25669 25670@item NB_CONSUMED_SAMPLES 25671The number of consumed samples, not including the current frame (only 25672audio) 25673 25674@item NB_SAMPLES, S 25675The number of samples in the current frame (only audio) 25676 25677@item SAMPLE_RATE, SR 25678The audio sample rate. 25679 25680@item STARTPTS 25681The PTS of the first frame. 25682 25683@item STARTT 25684the time in seconds of the first frame 25685 25686@item INTERLACED 25687State whether the current frame is interlaced. 25688 25689@item T 25690the time in seconds of the current frame 25691 25692@item POS 25693original position in the file of the frame, or undefined if undefined 25694for the current frame 25695 25696@item PREV_INPTS 25697The previous input PTS. 25698 25699@item PREV_INT 25700previous input time in seconds 25701 25702@item PREV_OUTPTS 25703The previous output PTS. 25704 25705@item PREV_OUTT 25706previous output time in seconds 25707 25708@item RTCTIME 25709The wallclock (RTC) time in microseconds. This is deprecated, use time(0) 25710instead. 25711 25712@item RTCSTART 25713The wallclock (RTC) time at the start of the movie in microseconds. 25714 25715@item TB 25716The timebase of the input timestamps. 25717 25718@end table 25719 25720@subsection Examples 25721 25722@itemize 25723@item 25724Start counting PTS from zero 25725@example 25726setpts=PTS-STARTPTS 25727@end example 25728 25729@item 25730Apply fast motion effect: 25731@example 25732setpts=0.5*PTS 25733@end example 25734 25735@item 25736Apply slow motion effect: 25737@example 25738setpts=2.0*PTS 25739@end example 25740 25741@item 25742Set fixed rate of 25 frames per second: 25743@example 25744setpts=N/(25*TB) 25745@end example 25746 25747@item 25748Set fixed rate 25 fps with some jitter: 25749@example 25750setpts='1/(25*TB) * (N + 0.05 * sin(N*2*PI/25))' 25751@end example 25752 25753@item 25754Apply an offset of 10 seconds to the input PTS: 25755@example 25756setpts=PTS+10/TB 25757@end example 25758 25759@item 25760Generate timestamps from a "live source" and rebase onto the current timebase: 25761@example 25762setpts='(RTCTIME - RTCSTART) / (TB * 1000000)' 25763@end example 25764 25765@item 25766Generate timestamps by counting samples: 25767@example 25768asetpts=N/SR/TB 25769@end example 25770 25771@end itemize 25772 25773@section setrange 25774 25775Force color range for the output video frame. 25776 25777The @code{setrange} filter marks the color range property for the 25778output frames. It does not change the input frame, but only sets the 25779corresponding property, which affects how the frame is treated by 25780following filters. 25781 25782The filter accepts the following options: 25783 25784@table @option 25785 25786@item range 25787Available values are: 25788 25789@table @samp 25790@item auto 25791Keep the same color range property. 25792 25793@item unspecified, unknown 25794Set the color range as unspecified. 25795 25796@item limited, tv, mpeg 25797Set the color range as limited. 25798 25799@item full, pc, jpeg 25800Set the color range as full. 25801@end table 25802@end table 25803 25804@section settb, asettb 25805 25806Set the timebase to use for the output frames timestamps. 25807It is mainly useful for testing timebase configuration. 25808 25809It accepts the following parameters: 25810 25811@table @option 25812 25813@item expr, tb 25814The expression which is evaluated into the output timebase. 25815 25816@end table 25817 25818The value for @option{tb} is an arithmetic expression representing a 25819rational. The expression can contain the constants "AVTB" (the default 25820timebase), "intb" (the input timebase) and "sr" (the sample rate, 25821audio only). Default value is "intb". 25822 25823@subsection Examples 25824 25825@itemize 25826@item 25827Set the timebase to 1/25: 25828@example 25829settb=expr=1/25 25830@end example 25831 25832@item 25833Set the timebase to 1/10: 25834@example 25835settb=expr=0.1 25836@end example 25837 25838@item 25839Set the timebase to 1001/1000: 25840@example 25841settb=1+0.001 25842@end example 25843 25844@item 25845Set the timebase to 2*intb: 25846@example 25847settb=2*intb 25848@end example 25849 25850@item 25851Set the default timebase value: 25852@example 25853settb=AVTB 25854@end example 25855@end itemize 25856 25857@section showcqt 25858Convert input audio to a video output representing frequency spectrum 25859logarithmically using Brown-Puckette constant Q transform algorithm with 25860direct frequency domain coefficient calculation (but the transform itself 25861is not really constant Q, instead the Q factor is actually variable/clamped), 25862with musical tone scale, from E0 to D#10. 25863 25864The filter accepts the following options: 25865 25866@table @option 25867@item size, s 25868Specify the video size for the output. It must be even. For the syntax of this option, 25869check the @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}. 25870Default value is @code{1920x1080}. 25871 25872@item fps, rate, r 25873Set the output frame rate. Default value is @code{25}. 25874 25875@item bar_h 25876Set the bargraph height. It must be even. Default value is @code{-1} which 25877computes the bargraph height automatically. 25878 25879@item axis_h 25880Set the axis height. It must be even. Default value is @code{-1} which computes 25881the axis height automatically. 25882 25883@item sono_h 25884Set the sonogram height. It must be even. Default value is @code{-1} which 25885computes the sonogram height automatically. 25886 25887@item fullhd 25888Set the fullhd resolution. This option is deprecated, use @var{size}, @var{s} 25889instead. Default value is @code{1}. 25890 25891@item sono_v, volume 25892Specify the sonogram volume expression. It can contain variables: 25893@table @option 25894@item bar_v 25895the @var{bar_v} evaluated expression 25896@item frequency, freq, f 25897the frequency where it is evaluated 25898@item timeclamp, tc 25899the value of @var{timeclamp} option 25900@end table 25901and functions: 25902@table @option 25903@item a_weighting(f) 25904A-weighting of equal loudness 25905@item b_weighting(f) 25906B-weighting of equal loudness 25907@item c_weighting(f) 25908C-weighting of equal loudness. 25909@end table 25910Default value is @code{16}. 25911 25912@item bar_v, volume2 25913Specify the bargraph volume expression. It can contain variables: 25914@table @option 25915@item sono_v 25916the @var{sono_v} evaluated expression 25917@item frequency, freq, f 25918the frequency where it is evaluated 25919@item timeclamp, tc 25920the value of @var{timeclamp} option 25921@end table 25922and functions: 25923@table @option 25924@item a_weighting(f) 25925A-weighting of equal loudness 25926@item b_weighting(f) 25927B-weighting of equal loudness 25928@item c_weighting(f) 25929C-weighting of equal loudness. 25930@end table 25931Default value is @code{sono_v}. 25932 25933@item sono_g, gamma 25934Specify the sonogram gamma. Lower gamma makes the spectrum more contrast, 25935higher gamma makes the spectrum having more range. Default value is @code{3}. 25936Acceptable range is @code{[1, 7]}. 25937 25938@item bar_g, gamma2 25939Specify the bargraph gamma. Default value is @code{1}. Acceptable range is 25940@code{[1, 7]}. 25941 25942@item bar_t 25943Specify the bargraph transparency level. Lower value makes the bargraph sharper. 25944Default value is @code{1}. Acceptable range is @code{[0, 1]}. 25945 25946@item timeclamp, tc 25947Specify the transform timeclamp. At low frequency, there is trade-off between 25948accuracy in time domain and frequency domain. If timeclamp is lower, 25949event in time domain is represented more accurately (such as fast bass drum), 25950otherwise event in frequency domain is represented more accurately 25951(such as bass guitar). Acceptable range is @code{[0.002, 1]}. Default value is @code{0.17}. 25952 25953@item attack 25954Set attack time in seconds. The default is @code{0} (disabled). Otherwise, it 25955limits future samples by applying asymmetric windowing in time domain, useful 25956when low latency is required. Accepted range is @code{[0, 1]}. 25957 25958@item basefreq 25959Specify the transform base frequency. Default value is @code{20.01523126408007475}, 25960which is frequency 50 cents below E0. Acceptable range is @code{[10, 100000]}. 25961 25962@item endfreq 25963Specify the transform end frequency. Default value is @code{20495.59681441799654}, 25964which is frequency 50 cents above D#10. Acceptable range is @code{[10, 100000]}. 25965 25966@item coeffclamp 25967This option is deprecated and ignored. 25968 25969@item tlength 25970Specify the transform length in time domain. Use this option to control accuracy 25971trade-off between time domain and frequency domain at every frequency sample. 25972It can contain variables: 25973@table @option 25974@item frequency, freq, f 25975the frequency where it is evaluated 25976@item timeclamp, tc 25977the value of @var{timeclamp} option. 25978@end table 25979Default value is @code{384*tc/(384+tc*f)}. 25980 25981@item count 25982Specify the transform count for every video frame. Default value is @code{6}. 25983Acceptable range is @code{[1, 30]}. 25984 25985@item fcount 25986Specify the transform count for every single pixel. Default value is @code{0}, 25987which makes it computed automatically. Acceptable range is @code{[0, 10]}. 25988 25989@item fontfile 25990Specify font file for use with freetype to draw the axis. If not specified, 25991use embedded font. Note that drawing with font file or embedded font is not 25992implemented with custom @var{basefreq} and @var{endfreq}, use @var{axisfile} 25993option instead. 25994 25995@item font 25996Specify fontconfig pattern. This has lower priority than @var{fontfile}. The 25997@code{:} in the pattern may be replaced by @code{|} to avoid unnecessary 25998escaping. 25999 26000@item fontcolor 26001Specify font color expression. This is arithmetic expression that should return 26002integer value 0xRRGGBB. It can contain variables: 26003@table @option 26004@item frequency, freq, f 26005the frequency where it is evaluated 26006@item timeclamp, tc 26007the value of @var{timeclamp} option 26008@end table 26009and functions: 26010@table @option 26011@item midi(f) 26012midi number of frequency f, some midi numbers: E0(16), C1(24), C2(36), A4(69) 26013@item r(x), g(x), b(x) 26014red, green, and blue value of intensity x. 26015@end table 26016Default value is @code{st(0, (midi(f)-59.5)/12); 26017st(1, if(between(ld(0),0,1), 0.5-0.5*cos(2*PI*ld(0)), 0)); 26018r(1-ld(1)) + b(ld(1))}. 26019 26020@item axisfile 26021Specify image file to draw the axis. This option override @var{fontfile} and 26022@var{fontcolor} option. 26023 26024@item axis, text 26025Enable/disable drawing text to the axis. If it is set to @code{0}, drawing to 26026the axis is disabled, ignoring @var{fontfile} and @var{axisfile} option. 26027Default value is @code{1}. 26028 26029@item csp 26030Set colorspace. The accepted values are: 26031@table @samp 26032@item unspecified 26033Unspecified (default) 26034 26035@item bt709 26036BT.709 26037 26038@item fcc 26039FCC 26040 26041@item bt470bg 26042BT.470BG or BT.601-6 625 26043 26044@item smpte170m 26045SMPTE-170M or BT.601-6 525 26046 26047@item smpte240m 26048SMPTE-240M 26049 26050@item bt2020ncl 26051BT.2020 with non-constant luminance 26052 26053@end table 26054 26055@item cscheme 26056Set spectrogram color scheme. This is list of floating point values with format 26057@code{left_r|left_g|left_b|right_r|right_g|right_b}. 26058The default is @code{1|0.5|0|0|0.5|1}. 26059 26060@end table 26061 26062@subsection Examples 26063 26064@itemize 26065@item 26066Playing audio while showing the spectrum: 26067@example 26068ffplay -f lavfi 'amovie=a.mp3, asplit [a][out1]; [a] showcqt [out0]' 26069@end example 26070 26071@item 26072Same as above, but with frame rate 30 fps: 26073@example 26074ffplay -f lavfi 'amovie=a.mp3, asplit [a][out1]; [a] showcqt=fps=30:count=5 [out0]' 26075@end example 26076 26077@item 26078Playing at 1280x720: 26079@example 26080ffplay -f lavfi 'amovie=a.mp3, asplit [a][out1]; [a] showcqt=s=1280x720:count=4 [out0]' 26081@end example 26082 26083@item 26084Disable sonogram display: 26085@example 26086sono_h=0 26087@end example 26088 26089@item 26090A1 and its harmonics: A1, A2, (near)E3, A3: 26091@example 26092ffplay -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), 26093 asplit[a][out1]; [a] showcqt [out0]' 26094@end example 26095 26096@item 26097Same as above, but with more accuracy in frequency domain: 26098@example 26099ffplay -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), 26100 asplit[a][out1]; [a] showcqt=timeclamp=0.5 [out0]' 26101@end example 26102 26103@item 26104Custom volume: 26105@example 26106bar_v=10:sono_v=bar_v*a_weighting(f) 26107@end example 26108 26109@item 26110Custom gamma, now spectrum is linear to the amplitude. 26111@example 26112bar_g=2:sono_g=2 26113@end example 26114 26115@item 26116Custom tlength equation: 26117@example 26118tc=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)))' 26119@end example 26120 26121@item 26122Custom fontcolor and fontfile, C-note is colored green, others are colored blue: 26123@example 26124fontcolor='if(mod(floor(midi(f)+0.5),12), 0x0000FF, g(1))':fontfile=myfont.ttf 26125@end example 26126 26127@item 26128Custom font using fontconfig: 26129@example 26130font='Courier New,Monospace,mono|bold' 26131@end example 26132 26133@item 26134Custom frequency range with custom axis using image file: 26135@example 26136axisfile=myaxis.png:basefreq=40:endfreq=10000 26137@end example 26138@end itemize 26139 26140@section showfreqs 26141 26142Convert input audio to video output representing the audio power spectrum. 26143Audio amplitude is on Y-axis while frequency is on X-axis. 26144 26145The filter accepts the following options: 26146 26147@table @option 26148@item size, s 26149Specify size of video. For the syntax of this option, check the 26150@ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}. 26151Default is @code{1024x512}. 26152 26153@item mode 26154Set display mode. 26155This set how each frequency bin will be represented. 26156 26157It accepts the following values: 26158@table @samp 26159@item line 26160@item bar 26161@item dot 26162@end table 26163Default is @code{bar}. 26164 26165@item ascale 26166Set amplitude scale. 26167 26168It accepts the following values: 26169@table @samp 26170@item lin 26171Linear scale. 26172 26173@item sqrt 26174Square root scale. 26175 26176@item cbrt 26177Cubic root scale. 26178 26179@item log 26180Logarithmic scale. 26181@end table 26182Default is @code{log}. 26183 26184@item fscale 26185Set frequency scale. 26186 26187It accepts the following values: 26188@table @samp 26189@item lin 26190Linear scale. 26191 26192@item log 26193Logarithmic scale. 26194 26195@item rlog 26196Reverse logarithmic scale. 26197@end table 26198Default is @code{lin}. 26199 26200@item win_size 26201Set window size. Allowed range is from 16 to 65536. 26202 26203Default is @code{2048} 26204 26205@item win_func 26206Set windowing function. 26207 26208It accepts the following values: 26209@table @samp 26210@item rect 26211@item bartlett 26212@item hanning 26213@item hamming 26214@item blackman 26215@item welch 26216@item flattop 26217@item bharris 26218@item bnuttall 26219@item bhann 26220@item sine 26221@item nuttall 26222@item lanczos 26223@item gauss 26224@item tukey 26225@item dolph 26226@item cauchy 26227@item parzen 26228@item poisson 26229@item bohman 26230@end table 26231Default is @code{hanning}. 26232 26233@item overlap 26234Set window overlap. In range @code{[0, 1]}. Default is @code{1}, 26235which means optimal overlap for selected window function will be picked. 26236 26237@item averaging 26238Set time averaging. Setting this to 0 will display current maximal peaks. 26239Default is @code{1}, which means time averaging is disabled. 26240 26241@item colors 26242Specify list of colors separated by space or by '|' which will be used to 26243draw channel frequencies. Unrecognized or missing colors will be replaced 26244by white color. 26245 26246@item cmode 26247Set channel display mode. 26248 26249It accepts the following values: 26250@table @samp 26251@item combined 26252@item separate 26253@end table 26254Default is @code{combined}. 26255 26256@item minamp 26257Set minimum amplitude used in @code{log} amplitude scaler. 26258 26259@item data 26260Set data display mode. 26261 26262It accepts the following values: 26263@table @samp 26264@item magnitude 26265@item phase 26266@item delay 26267@end table 26268Default is @code{magnitude}. 26269@end table 26270 26271@section showspatial 26272 26273Convert stereo input audio to a video output, representing the spatial relationship 26274between two channels. 26275 26276The filter accepts the following options: 26277 26278@table @option 26279@item size, s 26280Specify the video size for the output. For the syntax of this option, check the 26281@ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}. 26282Default value is @code{512x512}. 26283 26284@item win_size 26285Set window size. Allowed range is from @var{1024} to @var{65536}. Default size is @var{4096}. 26286 26287@item win_func 26288Set window function. 26289 26290It accepts the following values: 26291@table @samp 26292@item rect 26293@item bartlett 26294@item hann 26295@item hanning 26296@item hamming 26297@item blackman 26298@item welch 26299@item flattop 26300@item bharris 26301@item bnuttall 26302@item bhann 26303@item sine 26304@item nuttall 26305@item lanczos 26306@item gauss 26307@item tukey 26308@item dolph 26309@item cauchy 26310@item parzen 26311@item poisson 26312@item bohman 26313@end table 26314 26315Default value is @code{hann}. 26316 26317@item overlap 26318Set ratio of overlap window. Default value is @code{0.5}. 26319When value is @code{1} overlap is set to recommended size for specific 26320window function currently used. 26321@end table 26322 26323@anchor{showspectrum} 26324@section showspectrum 26325 26326Convert input audio to a video output, representing the audio frequency 26327spectrum. 26328 26329The filter accepts the following options: 26330 26331@table @option 26332@item size, s 26333Specify the video size for the output. For the syntax of this option, check the 26334@ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}. 26335Default value is @code{640x512}. 26336 26337@item slide 26338Specify how the spectrum should slide along the window. 26339 26340It accepts the following values: 26341@table @samp 26342@item replace 26343the samples start again on the left when they reach the right 26344@item scroll 26345the samples scroll from right to left 26346@item fullframe 26347frames are only produced when the samples reach the right 26348@item rscroll 26349the samples scroll from left to right 26350@end table 26351 26352Default value is @code{replace}. 26353 26354@item mode 26355Specify display mode. 26356 26357It accepts the following values: 26358@table @samp 26359@item combined 26360all channels are displayed in the same row 26361@item separate 26362all channels are displayed in separate rows 26363@end table 26364 26365Default value is @samp{combined}. 26366 26367@item color 26368Specify display color mode. 26369 26370It accepts the following values: 26371@table @samp 26372@item channel 26373each channel is displayed in a separate color 26374@item intensity 26375each channel is displayed using the same color scheme 26376@item rainbow 26377each channel is displayed using the rainbow color scheme 26378@item moreland 26379each channel is displayed using the moreland color scheme 26380@item nebulae 26381each channel is displayed using the nebulae color scheme 26382@item fire 26383each channel is displayed using the fire color scheme 26384@item fiery 26385each channel is displayed using the fiery color scheme 26386@item fruit 26387each channel is displayed using the fruit color scheme 26388@item cool 26389each channel is displayed using the cool color scheme 26390@item magma 26391each channel is displayed using the magma color scheme 26392@item green 26393each channel is displayed using the green color scheme 26394@item viridis 26395each channel is displayed using the viridis color scheme 26396@item plasma 26397each channel is displayed using the plasma color scheme 26398@item cividis 26399each channel is displayed using the cividis color scheme 26400@item terrain 26401each channel is displayed using the terrain color scheme 26402@end table 26403 26404Default value is @samp{channel}. 26405 26406@item scale 26407Specify scale used for calculating intensity color values. 26408 26409It accepts the following values: 26410@table @samp 26411@item lin 26412linear 26413@item sqrt 26414square root, default 26415@item cbrt 26416cubic root 26417@item log 26418logarithmic 26419@item 4thrt 264204th root 26421@item 5thrt 264225th root 26423@end table 26424 26425Default value is @samp{sqrt}. 26426 26427@item fscale 26428Specify frequency scale. 26429 26430It accepts the following values: 26431@table @samp 26432@item lin 26433linear 26434@item log 26435logarithmic 26436@end table 26437 26438Default value is @samp{lin}. 26439 26440@item saturation 26441Set saturation modifier for displayed colors. Negative values provide 26442alternative color scheme. @code{0} is no saturation at all. 26443Saturation must be in [-10.0, 10.0] range. 26444Default value is @code{1}. 26445 26446@item win_func 26447Set window function. 26448 26449It accepts the following values: 26450@table @samp 26451@item rect 26452@item bartlett 26453@item hann 26454@item hanning 26455@item hamming 26456@item blackman 26457@item welch 26458@item flattop 26459@item bharris 26460@item bnuttall 26461@item bhann 26462@item sine 26463@item nuttall 26464@item lanczos 26465@item gauss 26466@item tukey 26467@item dolph 26468@item cauchy 26469@item parzen 26470@item poisson 26471@item bohman 26472@end table 26473 26474Default value is @code{hann}. 26475 26476@item orientation 26477Set orientation of time vs frequency axis. Can be @code{vertical} or 26478@code{horizontal}. Default is @code{vertical}. 26479 26480@item overlap 26481Set ratio of overlap window. Default value is @code{0}. 26482When value is @code{1} overlap is set to recommended size for specific 26483window function currently used. 26484 26485@item gain 26486Set scale gain for calculating intensity color values. 26487Default value is @code{1}. 26488 26489@item data 26490Set which data to display. Can be @code{magnitude}, default or @code{phase}. 26491 26492@item rotation 26493Set color rotation, must be in [-1.0, 1.0] range. 26494Default value is @code{0}. 26495 26496@item start 26497Set start frequency from which to display spectrogram. Default is @code{0}. 26498 26499@item stop 26500Set stop frequency to which to display spectrogram. Default is @code{0}. 26501 26502@item fps 26503Set upper frame rate limit. Default is @code{auto}, unlimited. 26504 26505@item legend 26506Draw time and frequency axes and legends. Default is disabled. 26507@end table 26508 26509The usage is very similar to the showwaves filter; see the examples in that 26510section. 26511 26512@subsection Examples 26513 26514@itemize 26515@item 26516Large window with logarithmic color scaling: 26517@example 26518showspectrum=s=1280x480:scale=log 26519@end example 26520 26521@item 26522Complete example for a colored and sliding spectrum per channel using @command{ffplay}: 26523@example 26524ffplay -f lavfi 'amovie=input.mp3, asplit [a][out1]; 26525 [a] showspectrum=mode=separate:color=intensity:slide=1:scale=cbrt [out0]' 26526@end example 26527@end itemize 26528 26529@section showspectrumpic 26530 26531Convert input audio to a single video frame, representing the audio frequency 26532spectrum. 26533 26534The filter accepts the following options: 26535 26536@table @option 26537@item size, s 26538Specify the video size for the output. For the syntax of this option, check the 26539@ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}. 26540Default value is @code{4096x2048}. 26541 26542@item mode 26543Specify display mode. 26544 26545It accepts the following values: 26546@table @samp 26547@item combined 26548all channels are displayed in the same row 26549@item separate 26550all channels are displayed in separate rows 26551@end table 26552Default value is @samp{combined}. 26553 26554@item color 26555Specify display color mode. 26556 26557It accepts the following values: 26558@table @samp 26559@item channel 26560each channel is displayed in a separate color 26561@item intensity 26562each channel is displayed using the same color scheme 26563@item rainbow 26564each channel is displayed using the rainbow color scheme 26565@item moreland 26566each channel is displayed using the moreland color scheme 26567@item nebulae 26568each channel is displayed using the nebulae color scheme 26569@item fire 26570each channel is displayed using the fire color scheme 26571@item fiery 26572each channel is displayed using the fiery color scheme 26573@item fruit 26574each channel is displayed using the fruit color scheme 26575@item cool 26576each channel is displayed using the cool color scheme 26577@item magma 26578each channel is displayed using the magma color scheme 26579@item green 26580each channel is displayed using the green color scheme 26581@item viridis 26582each channel is displayed using the viridis color scheme 26583@item plasma 26584each channel is displayed using the plasma color scheme 26585@item cividis 26586each channel is displayed using the cividis color scheme 26587@item terrain 26588each channel is displayed using the terrain color scheme 26589@end table 26590Default value is @samp{intensity}. 26591 26592@item scale 26593Specify scale used for calculating intensity color values. 26594 26595It accepts the following values: 26596@table @samp 26597@item lin 26598linear 26599@item sqrt 26600square root, default 26601@item cbrt 26602cubic root 26603@item log 26604logarithmic 26605@item 4thrt 266064th root 26607@item 5thrt 266085th root 26609@end table 26610Default value is @samp{log}. 26611 26612@item fscale 26613Specify frequency scale. 26614 26615It accepts the following values: 26616@table @samp 26617@item lin 26618linear 26619@item log 26620logarithmic 26621@end table 26622 26623Default value is @samp{lin}. 26624 26625@item saturation 26626Set saturation modifier for displayed colors. Negative values provide 26627alternative color scheme. @code{0} is no saturation at all. 26628Saturation must be in [-10.0, 10.0] range. 26629Default value is @code{1}. 26630 26631@item win_func 26632Set window function. 26633 26634It accepts the following values: 26635@table @samp 26636@item rect 26637@item bartlett 26638@item hann 26639@item hanning 26640@item hamming 26641@item blackman 26642@item welch 26643@item flattop 26644@item bharris 26645@item bnuttall 26646@item bhann 26647@item sine 26648@item nuttall 26649@item lanczos 26650@item gauss 26651@item tukey 26652@item dolph 26653@item cauchy 26654@item parzen 26655@item poisson 26656@item bohman 26657@end table 26658Default value is @code{hann}. 26659 26660@item orientation 26661Set orientation of time vs frequency axis. Can be @code{vertical} or 26662@code{horizontal}. Default is @code{vertical}. 26663 26664@item gain 26665Set scale gain for calculating intensity color values. 26666Default value is @code{1}. 26667 26668@item legend 26669Draw time and frequency axes and legends. Default is enabled. 26670 26671@item rotation 26672Set color rotation, must be in [-1.0, 1.0] range. 26673Default value is @code{0}. 26674 26675@item start 26676Set start frequency from which to display spectrogram. Default is @code{0}. 26677 26678@item stop 26679Set stop frequency to which to display spectrogram. Default is @code{0}. 26680@end table 26681 26682@subsection Examples 26683 26684@itemize 26685@item 26686Extract an audio spectrogram of a whole audio track 26687in a 1024x1024 picture using @command{ffmpeg}: 26688@example 26689ffmpeg -i audio.flac -lavfi showspectrumpic=s=1024x1024 spectrogram.png 26690@end example 26691@end itemize 26692 26693@section showvolume 26694 26695Convert input audio volume to a video output. 26696 26697The filter accepts the following options: 26698 26699@table @option 26700@item rate, r 26701Set video rate. 26702 26703@item b 26704Set border width, allowed range is [0, 5]. Default is 1. 26705 26706@item w 26707Set channel width, allowed range is [80, 8192]. Default is 400. 26708 26709@item h 26710Set channel height, allowed range is [1, 900]. Default is 20. 26711 26712@item f 26713Set fade, allowed range is [0, 1]. Default is 0.95. 26714 26715@item c 26716Set volume color expression. 26717 26718The expression can use the following variables: 26719 26720@table @option 26721@item VOLUME 26722Current max volume of channel in dB. 26723 26724@item PEAK 26725Current peak. 26726 26727@item CHANNEL 26728Current channel number, starting from 0. 26729@end table 26730 26731@item t 26732If set, displays channel names. Default is enabled. 26733 26734@item v 26735If set, displays volume values. Default is enabled. 26736 26737@item o 26738Set orientation, can be horizontal: @code{h} or vertical: @code{v}, 26739default is @code{h}. 26740 26741@item s 26742Set step size, allowed range is [0, 5]. Default is 0, which means 26743step is disabled. 26744 26745@item p 26746Set background opacity, allowed range is [0, 1]. Default is 0. 26747 26748@item m 26749Set metering mode, can be peak: @code{p} or rms: @code{r}, 26750default is @code{p}. 26751 26752@item ds 26753Set display scale, can be linear: @code{lin} or log: @code{log}, 26754default is @code{lin}. 26755 26756@item dm 26757In second. 26758If set to > 0., display a line for the max level 26759in the previous seconds. 26760default is disabled: @code{0.} 26761 26762@item dmc 26763The color of the max line. Use when @code{dm} option is set to > 0. 26764default is: @code{orange} 26765@end table 26766 26767@section showwaves 26768 26769Convert input audio to a video output, representing the samples waves. 26770 26771The filter accepts the following options: 26772 26773@table @option 26774@item size, s 26775Specify the video size for the output. For the syntax of this option, check the 26776@ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}. 26777Default value is @code{600x240}. 26778 26779@item mode 26780Set display mode. 26781 26782Available values are: 26783@table @samp 26784@item point 26785Draw a point for each sample. 26786 26787@item line 26788Draw a vertical line for each sample. 26789 26790@item p2p 26791Draw a point for each sample and a line between them. 26792 26793@item cline 26794Draw a centered vertical line for each sample. 26795@end table 26796 26797Default value is @code{point}. 26798 26799@item n 26800Set the number of samples which are printed on the same column. A 26801larger value will decrease the frame rate. Must be a positive 26802integer. This option can be set only if the value for @var{rate} 26803is not explicitly specified. 26804 26805@item rate, r 26806Set the (approximate) output frame rate. This is done by setting the 26807option @var{n}. Default value is "25". 26808 26809@item split_channels 26810Set if channels should be drawn separately or overlap. Default value is 0. 26811 26812@item colors 26813Set colors separated by '|' which are going to be used for drawing of each channel. 26814 26815@item scale 26816Set amplitude scale. 26817 26818Available values are: 26819@table @samp 26820@item lin 26821Linear. 26822 26823@item log 26824Logarithmic. 26825 26826@item sqrt 26827Square root. 26828 26829@item cbrt 26830Cubic root. 26831@end table 26832 26833Default is linear. 26834 26835@item draw 26836Set the draw mode. This is mostly useful to set for high @var{n}. 26837 26838Available values are: 26839@table @samp 26840@item scale 26841Scale pixel values for each drawn sample. 26842 26843@item full 26844Draw every sample directly. 26845@end table 26846 26847Default value is @code{scale}. 26848@end table 26849 26850@subsection Examples 26851 26852@itemize 26853@item 26854Output the input file audio and the corresponding video representation 26855at the same time: 26856@example 26857amovie=a.mp3,asplit[out0],showwaves[out1] 26858@end example 26859 26860@item 26861Create a synthetic signal and show it with showwaves, forcing a 26862frame rate of 30 frames per second: 26863@example 26864aevalsrc=sin(1*2*PI*t)*sin(880*2*PI*t):cos(2*PI*200*t),asplit[out0],showwaves=r=30[out1] 26865@end example 26866@end itemize 26867 26868@section showwavespic 26869 26870Convert input audio to a single video frame, representing the samples waves. 26871 26872The filter accepts the following options: 26873 26874@table @option 26875@item size, s 26876Specify the video size for the output. For the syntax of this option, check the 26877@ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}. 26878Default value is @code{600x240}. 26879 26880@item split_channels 26881Set if channels should be drawn separately or overlap. Default value is 0. 26882 26883@item colors 26884Set colors separated by '|' which are going to be used for drawing of each channel. 26885 26886@item scale 26887Set amplitude scale. 26888 26889Available values are: 26890@table @samp 26891@item lin 26892Linear. 26893 26894@item log 26895Logarithmic. 26896 26897@item sqrt 26898Square root. 26899 26900@item cbrt 26901Cubic root. 26902@end table 26903 26904Default is linear. 26905 26906@item draw 26907Set the draw mode. 26908 26909Available values are: 26910@table @samp 26911@item scale 26912Scale pixel values for each drawn sample. 26913 26914@item full 26915Draw every sample directly. 26916@end table 26917 26918Default value is @code{scale}. 26919 26920@item filter 26921Set the filter mode. 26922 26923Available values are: 26924@table @samp 26925@item average 26926Use average samples values for each drawn sample. 26927 26928@item peak 26929Use peak samples values for each drawn sample. 26930@end table 26931 26932Default value is @code{average}. 26933@end table 26934 26935@subsection Examples 26936 26937@itemize 26938@item 26939Extract a channel split representation of the wave form of a whole audio track 26940in a 1024x800 picture using @command{ffmpeg}: 26941@example 26942ffmpeg -i audio.flac -lavfi showwavespic=split_channels=1:s=1024x800 waveform.png 26943@end example 26944@end itemize 26945 26946@section sidedata, asidedata 26947 26948Delete frame side data, or select frames based on it. 26949 26950This filter accepts the following options: 26951 26952@table @option 26953@item mode 26954Set mode of operation of the filter. 26955 26956Can be one of the following: 26957 26958@table @samp 26959@item select 26960Select every frame with side data of @code{type}. 26961 26962@item delete 26963Delete side data of @code{type}. If @code{type} is not set, delete all side 26964data in the frame. 26965 26966@end table 26967 26968@item type 26969Set side data type used with all modes. Must be set for @code{select} mode. For 26970the list of frame side data types, refer to the @code{AVFrameSideDataType} enum 26971in @file{libavutil/frame.h}. For example, to choose 26972@code{AV_FRAME_DATA_PANSCAN} side data, you must specify @code{PANSCAN}. 26973 26974@end table 26975 26976@section spectrumsynth 26977 26978Synthesize audio from 2 input video spectrums, first input stream represents 26979magnitude across time and second represents phase across time. 26980The filter will transform from frequency domain as displayed in videos back 26981to time domain as presented in audio output. 26982 26983This filter is primarily created for reversing processed @ref{showspectrum} 26984filter outputs, but can synthesize sound from other spectrograms too. 26985But in such case results are going to be poor if the phase data is not 26986available, because in such cases phase data need to be recreated, usually 26987it's just recreated from random noise. 26988For best results use gray only output (@code{channel} color mode in 26989@ref{showspectrum} filter) and @code{log} scale for magnitude video and 26990@code{lin} scale for phase video. To produce phase, for 2nd video, use 26991@code{data} option. Inputs videos should generally use @code{fullframe} 26992slide mode as that saves resources needed for decoding video. 26993 26994The filter accepts the following options: 26995 26996@table @option 26997@item sample_rate 26998Specify sample rate of output audio, the sample rate of audio from which 26999spectrum was generated may differ. 27000 27001@item channels 27002Set number of channels represented in input video spectrums. 27003 27004@item scale 27005Set scale which was used when generating magnitude input spectrum. 27006Can be @code{lin} or @code{log}. Default is @code{log}. 27007 27008@item slide 27009Set slide which was used when generating inputs spectrums. 27010Can be @code{replace}, @code{scroll}, @code{fullframe} or @code{rscroll}. 27011Default is @code{fullframe}. 27012 27013@item win_func 27014Set window function used for resynthesis. 27015 27016@item overlap 27017Set window overlap. In range @code{[0, 1]}. Default is @code{1}, 27018which means optimal overlap for selected window function will be picked. 27019 27020@item orientation 27021Set orientation of input videos. Can be @code{vertical} or @code{horizontal}. 27022Default is @code{vertical}. 27023@end table 27024 27025@subsection Examples 27026 27027@itemize 27028@item 27029First create magnitude and phase videos from audio, assuming audio is stereo with 44100 sample rate, 27030then resynthesize videos back to audio with spectrumsynth: 27031@example 27032ffmpeg -i input.flac -lavfi showspectrum=mode=separate:scale=log:overlap=0.875:color=channel:slide=fullframe:data=magnitude -an -c:v rawvideo magnitude.nut 27033ffmpeg -i input.flac -lavfi showspectrum=mode=separate:scale=lin:overlap=0.875:color=channel:slide=fullframe:data=phase -an -c:v rawvideo phase.nut 27034ffmpeg -i magnitude.nut -i phase.nut -lavfi spectrumsynth=channels=2:sample_rate=44100:win_func=hann:overlap=0.875:slide=fullframe output.flac 27035@end example 27036@end itemize 27037 27038@section split, asplit 27039 27040Split input into several identical outputs. 27041 27042@code{asplit} works with audio input, @code{split} with video. 27043 27044The filter accepts a single parameter which specifies the number of outputs. If 27045unspecified, it defaults to 2. 27046 27047@subsection Examples 27048 27049@itemize 27050@item 27051Create two separate outputs from the same input: 27052@example 27053[in] split [out0][out1] 27054@end example 27055 27056@item 27057To create 3 or more outputs, you need to specify the number of 27058outputs, like in: 27059@example 27060[in] asplit=3 [out0][out1][out2] 27061@end example 27062 27063@item 27064Create two separate outputs from the same input, one cropped and 27065one padded: 27066@example 27067[in] split [splitout1][splitout2]; 27068[splitout1] crop=100:100:0:0 [cropout]; 27069[splitout2] pad=200:200:100:100 [padout]; 27070@end example 27071 27072@item 27073Create 5 copies of the input audio with @command{ffmpeg}: 27074@example 27075ffmpeg -i INPUT -filter_complex asplit=5 OUTPUT 27076@end example 27077@end itemize 27078 27079@section zmq, azmq 27080 27081Receive commands sent through a libzmq client, and forward them to 27082filters in the filtergraph. 27083 27084@code{zmq} and @code{azmq} work as a pass-through filters. @code{zmq} 27085must be inserted between two video filters, @code{azmq} between two 27086audio filters. Both are capable to send messages to any filter type. 27087 27088To enable these filters you need to install the libzmq library and 27089headers and configure FFmpeg with @code{--enable-libzmq}. 27090 27091For more information about libzmq see: 27092@url{http://www.zeromq.org/} 27093 27094The @code{zmq} and @code{azmq} filters work as a libzmq server, which 27095receives messages sent through a network interface defined by the 27096@option{bind_address} (or the abbreviation "@option{b}") option. 27097Default value of this option is @file{tcp://localhost:5555}. You may 27098want to alter this value to your needs, but do not forget to escape any 27099':' signs (see @ref{filtergraph escaping}). 27100 27101The received message must be in the form: 27102@example 27103@var{TARGET} @var{COMMAND} [@var{ARG}] 27104@end example 27105 27106@var{TARGET} specifies the target of the command, usually the name of 27107the filter class or a specific filter instance name. The default 27108filter instance name uses the pattern @samp{Parsed_<filter_name>_<index>}, 27109but you can override this by using the @samp{filter_name@@id} syntax 27110(see @ref{Filtergraph syntax}). 27111 27112@var{COMMAND} specifies the name of the command for the target filter. 27113 27114@var{ARG} is optional and specifies the optional argument list for the 27115given @var{COMMAND}. 27116 27117Upon reception, the message is processed and the corresponding command 27118is injected into the filtergraph. Depending on the result, the filter 27119will send a reply to the client, adopting the format: 27120@example 27121@var{ERROR_CODE} @var{ERROR_REASON} 27122@var{MESSAGE} 27123@end example 27124 27125@var{MESSAGE} is optional. 27126 27127@subsection Examples 27128 27129Look at @file{tools/zmqsend} for an example of a zmq client which can 27130be used to send commands processed by these filters. 27131 27132Consider the following filtergraph generated by @command{ffplay}. 27133In this example the last overlay filter has an instance name. All other 27134filters will have default instance names. 27135 27136@example 27137ffplay -dumpgraph 1 -f lavfi " 27138color=s=100x100:c=red [l]; 27139color=s=100x100:c=blue [r]; 27140nullsrc=s=200x100, zmq [bg]; 27141[bg][l] overlay [bg+l]; 27142[bg+l][r] overlay@@my=x=100 " 27143@end example 27144 27145To change the color of the left side of the video, the following 27146command can be used: 27147@example 27148echo Parsed_color_0 c yellow | tools/zmqsend 27149@end example 27150 27151To change the right side: 27152@example 27153echo Parsed_color_1 c pink | tools/zmqsend 27154@end example 27155 27156To change the position of the right side: 27157@example 27158echo overlay@@my x 150 | tools/zmqsend 27159@end example 27160 27161 27162@c man end MULTIMEDIA FILTERS 27163 27164@chapter Multimedia Sources 27165@c man begin MULTIMEDIA SOURCES 27166 27167Below is a description of the currently available multimedia sources. 27168 27169@section amovie 27170 27171This is the same as @ref{movie} source, except it selects an audio 27172stream by default. 27173 27174@anchor{movie} 27175@section movie 27176 27177Read audio and/or video stream(s) from a movie container. 27178 27179It accepts the following parameters: 27180 27181@table @option 27182@item filename 27183The name of the resource to read (not necessarily a file; it can also be a 27184device or a stream accessed through some protocol). 27185 27186@item format_name, f 27187Specifies the format assumed for the movie to read, and can be either 27188the name of a container or an input device. If not specified, the 27189format is guessed from @var{movie_name} or by probing. 27190 27191@item seek_point, sp 27192Specifies the seek point in seconds. The frames will be output 27193starting from this seek point. The parameter is evaluated with 27194@code{av_strtod}, so the numerical value may be suffixed by an IS 27195postfix. The default value is "0". 27196 27197@item streams, s 27198Specifies the streams to read. Several streams can be specified, 27199separated by "+". The source will then have as many outputs, in the 27200same order. The syntax is explained in the @ref{Stream specifiers,,"Stream specifiers" 27201section in the ffmpeg manual,ffmpeg}. Two special names, "dv" and "da" specify 27202respectively the default (best suited) video and audio stream. Default 27203is "dv", or "da" if the filter is called as "amovie". 27204 27205@item stream_index, si 27206Specifies the index of the video stream to read. If the value is -1, 27207the most suitable video stream will be automatically selected. The default 27208value is "-1". Deprecated. If the filter is called "amovie", it will select 27209audio instead of video. 27210 27211@item loop 27212Specifies how many times to read the stream in sequence. 27213If the value is 0, the stream will be looped infinitely. 27214Default value is "1". 27215 27216Note that when the movie is looped the source timestamps are not 27217changed, so it will generate non monotonically increasing timestamps. 27218 27219@item discontinuity 27220Specifies the time difference between frames above which the point is 27221considered a timestamp discontinuity which is removed by adjusting the later 27222timestamps. 27223@end table 27224 27225It allows overlaying a second video on top of the main input of 27226a filtergraph, as shown in this graph: 27227@example 27228input -----------> deltapts0 --> overlay --> output 27229 ^ 27230 | 27231movie --> scale--> deltapts1 -------+ 27232@end example 27233@subsection Examples 27234 27235@itemize 27236@item 27237Skip 3.2 seconds from the start of the AVI file in.avi, and overlay it 27238on top of the input labelled "in": 27239@example 27240movie=in.avi:seek_point=3.2, scale=180:-1, setpts=PTS-STARTPTS [over]; 27241[in] setpts=PTS-STARTPTS [main]; 27242[main][over] overlay=16:16 [out] 27243@end example 27244 27245@item 27246Read from a video4linux2 device, and overlay it on top of the input 27247labelled "in": 27248@example 27249movie=/dev/video0:f=video4linux2, scale=180:-1, setpts=PTS-STARTPTS [over]; 27250[in] setpts=PTS-STARTPTS [main]; 27251[main][over] overlay=16:16 [out] 27252@end example 27253 27254@item 27255Read the first video stream and the audio stream with id 0x81 from 27256dvd.vob; the video is connected to the pad named "video" and the audio is 27257connected to the pad named "audio": 27258@example 27259movie=dvd.vob:s=v:0+#0x81 [video] [audio] 27260@end example 27261@end itemize 27262 27263@subsection Commands 27264 27265Both movie and amovie support the following commands: 27266@table @option 27267@item seek 27268Perform seek using "av_seek_frame". 27269The syntax is: seek @var{stream_index}|@var{timestamp}|@var{flags} 27270@itemize 27271@item 27272@var{stream_index}: If stream_index is -1, a default 27273stream is selected, and @var{timestamp} is automatically converted 27274from AV_TIME_BASE units to the stream specific time_base. 27275@item 27276@var{timestamp}: Timestamp in AVStream.time_base units 27277or, if no stream is specified, in AV_TIME_BASE units. 27278@item 27279@var{flags}: Flags which select direction and seeking mode. 27280@end itemize 27281 27282@item get_duration 27283Get movie duration in AV_TIME_BASE units. 27284 27285@end table 27286 27287@c man end MULTIMEDIA SOURCES 27288