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, can be @var{2nd}, @var{4th} or @var{8th}. 527Default is @var{4th}. 528@end table 529 530@section acrusher 531 532Reduce audio bit resolution. 533 534This filter is bit crusher with enhanced functionality. A bit crusher 535is used to audibly reduce number of bits an audio signal is sampled 536with. This doesn't change the bit depth at all, it just produces the 537effect. Material reduced in bit depth sounds more harsh and "digital". 538This filter is able to even round to continuous values instead of discrete 539bit depths. 540Additionally it has a D/C offset which results in different crushing of 541the lower and the upper half of the signal. 542An Anti-Aliasing setting is able to produce "softer" crushing sounds. 543 544Another feature of this filter is the logarithmic mode. 545This setting switches from linear distances between bits to logarithmic ones. 546The result is a much more "natural" sounding crusher which doesn't gate low 547signals for example. The human ear has a logarithmic perception, 548so this kind of crushing is much more pleasant. 549Logarithmic crushing is also able to get anti-aliased. 550 551The filter accepts the following options: 552 553@table @option 554@item level_in 555Set level in. 556 557@item level_out 558Set level out. 559 560@item bits 561Set bit reduction. 562 563@item mix 564Set mixing amount. 565 566@item mode 567Can be linear: @code{lin} or logarithmic: @code{log}. 568 569@item dc 570Set DC. 571 572@item aa 573Set anti-aliasing. 574 575@item samples 576Set sample reduction. 577 578@item lfo 579Enable LFO. By default disabled. 580 581@item lforange 582Set LFO range. 583 584@item lforate 585Set LFO rate. 586@end table 587 588@section acue 589 590Delay audio filtering until a given wallclock timestamp. See the @ref{cue} 591filter. 592 593@section adeclick 594Remove impulsive noise from input audio. 595 596Samples detected as impulsive noise are replaced by interpolated samples using 597autoregressive modelling. 598 599@table @option 600@item w 601Set window size, in milliseconds. Allowed range is from @code{10} to 602@code{100}. Default value is @code{55} milliseconds. 603This sets size of window which will be processed at once. 604 605@item o 606Set window overlap, in percentage of window size. Allowed range is from 607@code{50} to @code{95}. Default value is @code{75} percent. 608Setting this to a very high value increases impulsive noise removal but makes 609whole process much slower. 610 611@item a 612Set autoregression order, in percentage of window size. Allowed range is from 613@code{0} to @code{25}. Default value is @code{2} percent. This option also 614controls quality of interpolated samples using neighbour good samples. 615 616@item t 617Set threshold value. Allowed range is from @code{1} to @code{100}. 618Default value is @code{2}. 619This controls the strength of impulsive noise which is going to be removed. 620The lower value, the more samples will be detected as impulsive noise. 621 622@item b 623Set burst fusion, in percentage of window size. Allowed range is @code{0} to 624@code{10}. Default value is @code{2}. 625If any two samples detected as noise are spaced less than this value then any 626sample between those two samples will be also detected as noise. 627 628@item m 629Set overlap method. 630 631It accepts the following values: 632@table @option 633@item a 634Select overlap-add method. Even not interpolated samples are slightly 635changed with this method. 636 637@item s 638Select overlap-save method. Not interpolated samples remain unchanged. 639@end table 640 641Default value is @code{a}. 642@end table 643 644@section adeclip 645Remove clipped samples from input audio. 646 647Samples detected as clipped are replaced by interpolated samples using 648autoregressive modelling. 649 650@table @option 651@item w 652Set window size, in milliseconds. Allowed range is from @code{10} to @code{100}. 653Default value is @code{55} milliseconds. 654This sets size of window which will be processed at once. 655 656@item o 657Set window overlap, in percentage of window size. Allowed range is from @code{50} 658to @code{95}. Default value is @code{75} percent. 659 660@item a 661Set autoregression order, in percentage of window size. Allowed range is from 662@code{0} to @code{25}. Default value is @code{8} percent. This option also controls 663quality of interpolated samples using neighbour good samples. 664 665@item t 666Set threshold value. Allowed range is from @code{1} to @code{100}. 667Default value is @code{10}. Higher values make clip detection less aggressive. 668 669@item n 670Set size of histogram used to detect clips. Allowed range is from @code{100} to @code{9999}. 671Default value is @code{1000}. Higher values make clip detection less aggressive. 672 673@item m 674Set overlap method. 675 676It accepts the following values: 677@table @option 678@item a 679Select overlap-add method. Even not interpolated samples are slightly changed 680with this method. 681 682@item s 683Select overlap-save method. Not interpolated samples remain unchanged. 684@end table 685 686Default value is @code{a}. 687@end table 688 689@section adelay 690 691Delay one or more audio channels. 692 693Samples in delayed channel are filled with silence. 694 695The filter accepts the following option: 696 697@table @option 698@item delays 699Set list of delays in milliseconds for each channel separated by '|'. 700Unused delays will be silently ignored. If number of given delays is 701smaller than number of channels all remaining channels will not be delayed. 702If you want to delay exact number of samples, append 'S' to number. 703If you want instead to delay in seconds, append 's' to number. 704 705@item all 706Use last set delay for all remaining channels. By default is disabled. 707This option if enabled changes how option @code{delays} is interpreted. 708@end table 709 710@subsection Examples 711 712@itemize 713@item 714Delay first channel by 1.5 seconds, the third channel by 0.5 seconds and leave 715the second channel (and any other channels that may be present) unchanged. 716@example 717adelay=1500|0|500 718@end example 719 720@item 721Delay second channel by 500 samples, the third channel by 700 samples and leave 722the first channel (and any other channels that may be present) unchanged. 723@example 724adelay=0|500S|700S 725@end example 726 727@item 728Delay all channels by same number of samples: 729@example 730adelay=delays=64S:all=1 731@end example 732@end itemize 733 734@section aderivative, aintegral 735 736Compute derivative/integral of audio stream. 737 738Applying both filters one after another produces original audio. 739 740@section aecho 741 742Apply echoing to the input audio. 743 744Echoes are reflected sound and can occur naturally amongst mountains 745(and sometimes large buildings) when talking or shouting; digital echo 746effects emulate this behaviour and are often used to help fill out the 747sound of a single instrument or vocal. The time difference between the 748original signal and the reflection is the @code{delay}, and the 749loudness of the reflected signal is the @code{decay}. 750Multiple echoes can have different delays and decays. 751 752A description of the accepted parameters follows. 753 754@table @option 755@item in_gain 756Set input gain of reflected signal. Default is @code{0.6}. 757 758@item out_gain 759Set output gain of reflected signal. Default is @code{0.3}. 760 761@item delays 762Set list of time intervals in milliseconds between original signal and reflections 763separated by '|'. Allowed range for each @code{delay} is @code{(0 - 90000.0]}. 764Default is @code{1000}. 765 766@item decays 767Set list of loudness of reflected signals separated by '|'. 768Allowed range for each @code{decay} is @code{(0 - 1.0]}. 769Default is @code{0.5}. 770@end table 771 772@subsection Examples 773 774@itemize 775@item 776Make it sound as if there are twice as many instruments as are actually playing: 777@example 778aecho=0.8:0.88:60:0.4 779@end example 780 781@item 782If delay is very short, then it sounds like a (metallic) robot playing music: 783@example 784aecho=0.8:0.88:6:0.4 785@end example 786 787@item 788A longer delay will sound like an open air concert in the mountains: 789@example 790aecho=0.8:0.9:1000:0.3 791@end example 792 793@item 794Same as above but with one more mountain: 795@example 796aecho=0.8:0.9:1000|1800:0.3|0.25 797@end example 798@end itemize 799 800@section aemphasis 801Audio emphasis filter creates or restores material directly taken from LPs or 802emphased CDs with different filter curves. E.g. to store music on vinyl the 803signal has to be altered by a filter first to even out the disadvantages of 804this recording medium. 805Once the material is played back the inverse filter has to be applied to 806restore the distortion of the frequency response. 807 808The filter accepts the following options: 809 810@table @option 811@item level_in 812Set input gain. 813 814@item level_out 815Set output gain. 816 817@item mode 818Set filter mode. For restoring material use @code{reproduction} mode, otherwise 819use @code{production} mode. Default is @code{reproduction} mode. 820 821@item type 822Set filter type. Selects medium. Can be one of the following: 823 824@table @option 825@item col 826select Columbia. 827@item emi 828select EMI. 829@item bsi 830select BSI (78RPM). 831@item riaa 832select RIAA. 833@item cd 834select Compact Disc (CD). 835@item 50fm 836select 50µs (FM). 837@item 75fm 838select 75µs (FM). 839@item 50kf 840select 50µs (FM-KF). 841@item 75kf 842select 75µs (FM-KF). 843@end table 844@end table 845 846@section aeval 847 848Modify an audio signal according to the specified expressions. 849 850This filter accepts one or more expressions (one for each channel), 851which are evaluated and used to modify a corresponding audio signal. 852 853It accepts the following parameters: 854 855@table @option 856@item exprs 857Set the '|'-separated expressions list for each separate channel. If 858the number of input channels is greater than the number of 859expressions, the last specified expression is used for the remaining 860output channels. 861 862@item channel_layout, c 863Set output channel layout. If not specified, the channel layout is 864specified by the number of expressions. If set to @samp{same}, it will 865use by default the same input channel layout. 866@end table 867 868Each expression in @var{exprs} can contain the following constants and functions: 869 870@table @option 871@item ch 872channel number of the current expression 873 874@item n 875number of the evaluated sample, starting from 0 876 877@item s 878sample rate 879 880@item t 881time of the evaluated sample expressed in seconds 882 883@item nb_in_channels 884@item nb_out_channels 885input and output number of channels 886 887@item val(CH) 888the value of input channel with number @var{CH} 889@end table 890 891Note: this filter is slow. For faster processing you should use a 892dedicated filter. 893 894@subsection Examples 895 896@itemize 897@item 898Half volume: 899@example 900aeval=val(ch)/2:c=same 901@end example 902 903@item 904Invert phase of the second channel: 905@example 906aeval=val(0)|-val(1) 907@end example 908@end itemize 909 910@anchor{afade} 911@section afade 912 913Apply fade-in/out effect to input audio. 914 915A description of the accepted parameters follows. 916 917@table @option 918@item type, t 919Specify the effect type, can be either @code{in} for fade-in, or 920@code{out} for a fade-out effect. Default is @code{in}. 921 922@item start_sample, ss 923Specify the number of the start sample for starting to apply the fade 924effect. Default is 0. 925 926@item nb_samples, ns 927Specify the number of samples for which the fade effect has to last. At 928the end of the fade-in effect the output audio will have the same 929volume as the input audio, at the end of the fade-out transition 930the output audio will be silence. Default is 44100. 931 932@item start_time, st 933Specify the start time of the fade effect. Default is 0. 934The value must be specified as a time duration; see 935@ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils} 936for the accepted syntax. 937If set this option is used instead of @var{start_sample}. 938 939@item duration, d 940Specify the duration of the fade effect. See 941@ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils} 942for the accepted syntax. 943At the end of the fade-in effect the output audio will have the same 944volume as the input audio, at the end of the fade-out transition 945the output audio will be silence. 946By default the duration is determined by @var{nb_samples}. 947If set this option is used instead of @var{nb_samples}. 948 949@item curve 950Set curve for fade transition. 951 952It accepts the following values: 953@table @option 954@item tri 955select triangular, linear slope (default) 956@item qsin 957select quarter of sine wave 958@item hsin 959select half of sine wave 960@item esin 961select exponential sine wave 962@item log 963select logarithmic 964@item ipar 965select inverted parabola 966@item qua 967select quadratic 968@item cub 969select cubic 970@item squ 971select square root 972@item cbr 973select cubic root 974@item par 975select parabola 976@item exp 977select exponential 978@item iqsin 979select inverted quarter of sine wave 980@item ihsin 981select inverted half of sine wave 982@item dese 983select double-exponential seat 984@item desi 985select double-exponential sigmoid 986@item losi 987select logistic sigmoid 988@item nofade 989no fade applied 990@end table 991@end table 992 993@subsection Examples 994 995@itemize 996@item 997Fade in first 15 seconds of audio: 998@example 999afade=t=in:ss=0:d=15 1000@end example 1001 1002@item 1003Fade out last 25 seconds of a 900 seconds audio: 1004@example 1005afade=t=out:st=875:d=25 1006@end example 1007@end itemize 1008 1009@section afftdn 1010Denoise audio samples with FFT. 1011 1012A description of the accepted parameters follows. 1013 1014@table @option 1015@item nr 1016Set the noise reduction in dB, allowed range is 0.01 to 97. 1017Default value is 12 dB. 1018 1019@item nf 1020Set the noise floor in dB, allowed range is -80 to -20. 1021Default value is -50 dB. 1022 1023@item nt 1024Set the noise type. 1025 1026It accepts the following values: 1027@table @option 1028@item w 1029Select white noise. 1030 1031@item v 1032Select vinyl noise. 1033 1034@item s 1035Select shellac noise. 1036 1037@item c 1038Select custom noise, defined in @code{bn} option. 1039 1040Default value is white noise. 1041@end table 1042 1043@item bn 1044Set custom band noise for every one of 15 bands. 1045Bands are separated by ' ' or '|'. 1046 1047@item rf 1048Set the residual floor in dB, allowed range is -80 to -20. 1049Default value is -38 dB. 1050 1051@item tn 1052Enable noise tracking. By default is disabled. 1053With this enabled, noise floor is automatically adjusted. 1054 1055@item tr 1056Enable residual tracking. By default is disabled. 1057 1058@item om 1059Set the output mode. 1060 1061It accepts the following values: 1062@table @option 1063@item i 1064Pass input unchanged. 1065 1066@item o 1067Pass noise filtered out. 1068 1069@item n 1070Pass only noise. 1071 1072Default value is @var{o}. 1073@end table 1074@end table 1075 1076@subsection Commands 1077 1078This filter supports the following commands: 1079@table @option 1080@item sample_noise, sn 1081Start or stop measuring noise profile. 1082Syntax for the command is : "start" or "stop" string. 1083After measuring noise profile is stopped it will be 1084automatically applied in filtering. 1085 1086@item noise_reduction, nr 1087Change noise reduction. Argument is single float number. 1088Syntax for the command is : "@var{noise_reduction}" 1089 1090@item noise_floor, nf 1091Change noise floor. Argument is single float number. 1092Syntax for the command is : "@var{noise_floor}" 1093 1094@item output_mode, om 1095Change output mode operation. 1096Syntax for the command is : "i", "o" or "n" string. 1097@end table 1098 1099@section afftfilt 1100Apply arbitrary expressions to samples in frequency domain. 1101 1102@table @option 1103@item real 1104Set frequency domain real expression for each separate channel separated 1105by '|'. Default is "re". 1106If the number of input channels is greater than the number of 1107expressions, the last specified expression is used for the remaining 1108output channels. 1109 1110@item imag 1111Set frequency domain imaginary expression for each separate channel 1112separated by '|'. Default is "im". 1113 1114Each expression in @var{real} and @var{imag} can contain the following 1115constants and functions: 1116 1117@table @option 1118@item sr 1119sample rate 1120 1121@item b 1122current frequency bin number 1123 1124@item nb 1125number of available bins 1126 1127@item ch 1128channel number of the current expression 1129 1130@item chs 1131number of channels 1132 1133@item pts 1134current frame pts 1135 1136@item re 1137current real part of frequency bin of current channel 1138 1139@item im 1140current imaginary part of frequency bin of current channel 1141 1142@item real(b, ch) 1143Return the value of real part of frequency bin at location (@var{bin},@var{channel}) 1144 1145@item imag(b, ch) 1146Return the value of imaginary part of frequency bin at location (@var{bin},@var{channel}) 1147@end table 1148 1149@item win_size 1150Set window size. Allowed range is from 16 to 131072. 1151Default is @code{4096} 1152 1153@item win_func 1154Set window function. Default is @code{hann}. 1155 1156@item overlap 1157Set window overlap. If set to 1, the recommended overlap for selected 1158window function will be picked. Default is @code{0.75}. 1159@end table 1160 1161@subsection Examples 1162 1163@itemize 1164@item 1165Leave almost only low frequencies in audio: 1166@example 1167afftfilt="'real=re * (1-clip((b/nb)*b,0,1))':imag='im * (1-clip((b/nb)*b,0,1))'" 1168@end example 1169 1170@item 1171Apply robotize effect: 1172@example 1173afftfilt="real='hypot(re,im)*sin(0)':imag='hypot(re,im)*cos(0)':win_size=512:overlap=0.75" 1174@end example 1175 1176@item 1177Apply whisper effect: 1178@example 1179afftfilt="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" 1180@end example 1181@end itemize 1182 1183@anchor{afir} 1184@section afir 1185 1186Apply an arbitrary Finite Impulse Response filter. 1187 1188This filter is designed for applying long FIR filters, 1189up to 60 seconds long. 1190 1191It can be used as component for digital crossover filters, 1192room equalization, cross talk cancellation, wavefield synthesis, 1193auralization, ambiophonics, ambisonics and spatialization. 1194 1195This filter uses the streams higher than first one as FIR coefficients. 1196If the non-first stream holds a single channel, it will be used 1197for all input channels in the first stream, otherwise 1198the number of channels in the non-first stream must be same as 1199the number of channels in the first stream. 1200 1201It accepts the following parameters: 1202 1203@table @option 1204@item dry 1205Set dry gain. This sets input gain. 1206 1207@item wet 1208Set wet gain. This sets final output gain. 1209 1210@item length 1211Set Impulse Response filter length. Default is 1, which means whole IR is processed. 1212 1213@item gtype 1214Enable applying gain measured from power of IR. 1215 1216Set which approach to use for auto gain measurement. 1217 1218@table @option 1219@item none 1220Do not apply any gain. 1221 1222@item peak 1223select peak gain, very conservative approach. This is default value. 1224 1225@item dc 1226select DC gain, limited application. 1227 1228@item gn 1229select gain to noise approach, this is most popular one. 1230@end table 1231 1232@item irgain 1233Set gain to be applied to IR coefficients before filtering. 1234Allowed range is 0 to 1. This gain is applied after any gain applied with @var{gtype} option. 1235 1236@item irfmt 1237Set format of IR stream. Can be @code{mono} or @code{input}. 1238Default is @code{input}. 1239 1240@item maxir 1241Set max allowed Impulse Response filter duration in seconds. Default is 30 seconds. 1242Allowed range is 0.1 to 60 seconds. 1243 1244@item response 1245Show IR frequency response, magnitude(magenta), phase(green) and group delay(yellow) in additional video stream. 1246By default it is disabled. 1247 1248@item channel 1249Set for which IR channel to display frequency response. By default is first channel 1250displayed. This option is used only when @var{response} is enabled. 1251 1252@item size 1253Set video stream size. This option is used only when @var{response} is enabled. 1254 1255@item rate 1256Set video stream frame rate. This option is used only when @var{response} is enabled. 1257 1258@item minp 1259Set minimal partition size used for convolution. Default is @var{8192}. 1260Allowed range is from @var{1} to @var{32768}. 1261Lower values decreases latency at cost of higher CPU usage. 1262 1263@item maxp 1264Set maximal partition size used for convolution. Default is @var{8192}. 1265Allowed range is from @var{8} to @var{32768}. 1266Lower values may increase CPU usage. 1267 1268@item nbirs 1269Set number of input impulse responses streams which will be switchable at runtime. 1270Allowed range is from @var{1} to @var{32}. Default is @var{1}. 1271 1272@item ir 1273Set IR stream which will be used for convolution, starting from @var{0}, should always be 1274lower than supplied value by @code{nbirs} option. Default is @var{0}. 1275This option can be changed at runtime via @ref{commands}. 1276@end table 1277 1278@subsection Examples 1279 1280@itemize 1281@item 1282Apply reverb to stream using mono IR file as second input, complete command using ffmpeg: 1283@example 1284ffmpeg -i input.wav -i middle_tunnel_1way_mono.wav -lavfi afir output.wav 1285@end example 1286@end itemize 1287 1288@anchor{aformat} 1289@section aformat 1290 1291Set output format constraints for the input audio. The framework will 1292negotiate the most appropriate format to minimize conversions. 1293 1294It accepts the following parameters: 1295@table @option 1296 1297@item sample_fmts, f 1298A '|'-separated list of requested sample formats. 1299 1300@item sample_rates, r 1301A '|'-separated list of requested sample rates. 1302 1303@item channel_layouts, cl 1304A '|'-separated list of requested channel layouts. 1305 1306See @ref{channel layout syntax,,the Channel Layout section in the ffmpeg-utils(1) manual,ffmpeg-utils} 1307for the required syntax. 1308@end table 1309 1310If a parameter is omitted, all values are allowed. 1311 1312Force the output to either unsigned 8-bit or signed 16-bit stereo 1313@example 1314aformat=sample_fmts=u8|s16:channel_layouts=stereo 1315@end example 1316 1317@section agate 1318 1319A gate is mainly used to reduce lower parts of a signal. This kind of signal 1320processing reduces disturbing noise between useful signals. 1321 1322Gating is done by detecting the volume below a chosen level @var{threshold} 1323and dividing it by the factor set with @var{ratio}. The bottom of the noise 1324floor is set via @var{range}. Because an exact manipulation of the signal 1325would cause distortion of the waveform the reduction can be levelled over 1326time. This is done by setting @var{attack} and @var{release}. 1327 1328@var{attack} determines how long the signal has to fall below the threshold 1329before any reduction will occur and @var{release} sets the time the signal 1330has to rise above the threshold to reduce the reduction again. 1331Shorter signals than the chosen attack time will be left untouched. 1332 1333@table @option 1334@item level_in 1335Set input level before filtering. 1336Default is 1. Allowed range is from 0.015625 to 64. 1337 1338@item mode 1339Set the mode of operation. Can be @code{upward} or @code{downward}. 1340Default is @code{downward}. If set to @code{upward} mode, higher parts of signal 1341will be amplified, expanding dynamic range in upward direction. 1342Otherwise, in case of @code{downward} lower parts of signal will be reduced. 1343 1344@item range 1345Set the level of gain reduction when the signal is below the threshold. 1346Default is 0.06125. Allowed range is from 0 to 1. 1347Setting this to 0 disables reduction and then filter behaves like expander. 1348 1349@item threshold 1350If a signal rises above this level the gain reduction is released. 1351Default is 0.125. Allowed range is from 0 to 1. 1352 1353@item ratio 1354Set a ratio by which the signal is reduced. 1355Default is 2. Allowed range is from 1 to 9000. 1356 1357@item attack 1358Amount of milliseconds the signal has to rise above the threshold before gain 1359reduction stops. 1360Default is 20 milliseconds. Allowed range is from 0.01 to 9000. 1361 1362@item release 1363Amount of milliseconds the signal has to fall below the threshold before the 1364reduction is increased again. Default is 250 milliseconds. 1365Allowed range is from 0.01 to 9000. 1366 1367@item makeup 1368Set amount of amplification of signal after processing. 1369Default is 1. Allowed range is from 1 to 64. 1370 1371@item knee 1372Curve the sharp knee around the threshold to enter gain reduction more softly. 1373Default is 2.828427125. Allowed range is from 1 to 8. 1374 1375@item detection 1376Choose if exact signal should be taken for detection or an RMS like one. 1377Default is @code{rms}. Can be @code{peak} or @code{rms}. 1378 1379@item link 1380Choose if the average level between all channels or the louder channel affects 1381the reduction. 1382Default is @code{average}. Can be @code{average} or @code{maximum}. 1383@end table 1384 1385@section aiir 1386 1387Apply an arbitrary Infinite Impulse Response filter. 1388 1389It accepts the following parameters: 1390 1391@table @option 1392@item zeros, z 1393Set numerator/zeros coefficients. 1394 1395@item poles, p 1396Set denominator/poles coefficients. 1397 1398@item gains, k 1399Set channels gains. 1400 1401@item dry_gain 1402Set input gain. 1403 1404@item wet_gain 1405Set output gain. 1406 1407@item format, f 1408Set coefficients format. 1409 1410@table @samp 1411@item tf 1412digital transfer function 1413@item zp 1414Z-plane zeros/poles, cartesian (default) 1415@item pr 1416Z-plane zeros/poles, polar radians 1417@item pd 1418Z-plane zeros/poles, polar degrees 1419@item sp 1420S-plane zeros/poles 1421@end table 1422 1423@item process, r 1424Set kind of processing. 1425Can be @code{d} - direct or @code{s} - serial cascading. Default is @code{s}. 1426 1427@item precision, e 1428Set filtering precision. 1429 1430@table @samp 1431@item dbl 1432double-precision floating-point (default) 1433@item flt 1434single-precision floating-point 1435@item i32 143632-bit integers 1437@item i16 143816-bit integers 1439@end table 1440 1441@item normalize, n 1442Normalize filter coefficients, by default is enabled. 1443Enabling it will normalize magnitude response at DC to 0dB. 1444 1445@item mix 1446How much to use filtered signal in output. Default is 1. 1447Range is between 0 and 1. 1448 1449@item response 1450Show IR frequency response, magnitude(magenta), phase(green) and group delay(yellow) in additional video stream. 1451By default it is disabled. 1452 1453@item channel 1454Set for which IR channel to display frequency response. By default is first channel 1455displayed. This option is used only when @var{response} is enabled. 1456 1457@item size 1458Set video stream size. This option is used only when @var{response} is enabled. 1459@end table 1460 1461Coefficients in @code{tf} format are separated by spaces and are in ascending 1462order. 1463 1464Coefficients in @code{zp} format are separated by spaces and order of coefficients 1465doesn't matter. Coefficients in @code{zp} format are complex numbers with @var{i} 1466imaginary unit. 1467 1468Different coefficients and gains can be provided for every channel, in such case 1469use '|' to separate coefficients or gains. Last provided coefficients will be 1470used for all remaining channels. 1471 1472@subsection Examples 1473 1474@itemize 1475@item 1476Apply 2 pole elliptic notch at around 5000Hz for 48000 Hz sample rate: 1477@example 1478aiir=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 1479@end example 1480 1481@item 1482Same as above but in @code{zp} format: 1483@example 1484aiir=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 1485@end example 1486@end itemize 1487 1488@section alimiter 1489 1490The limiter prevents an input signal from rising over a desired threshold. 1491This limiter uses lookahead technology to prevent your signal from distorting. 1492It means that there is a small delay after the signal is processed. Keep in mind 1493that the delay it produces is the attack time you set. 1494 1495The filter accepts the following options: 1496 1497@table @option 1498@item level_in 1499Set input gain. Default is 1. 1500 1501@item level_out 1502Set output gain. Default is 1. 1503 1504@item limit 1505Don't let signals above this level pass the limiter. Default is 1. 1506 1507@item attack 1508The limiter will reach its attenuation level in this amount of time in 1509milliseconds. Default is 5 milliseconds. 1510 1511@item release 1512Come back from limiting to attenuation 1.0 in this amount of milliseconds. 1513Default is 50 milliseconds. 1514 1515@item asc 1516When gain reduction is always needed ASC takes care of releasing to an 1517average reduction level rather than reaching a reduction of 0 in the release 1518time. 1519 1520@item asc_level 1521Select how much the release time is affected by ASC, 0 means nearly no changes 1522in release time while 1 produces higher release times. 1523 1524@item level 1525Auto level output signal. Default is enabled. 1526This normalizes audio back to 0dB if enabled. 1527@end table 1528 1529Depending on picked setting it is recommended to upsample input 2x or 4x times 1530with @ref{aresample} before applying this filter. 1531 1532@section allpass 1533 1534Apply a two-pole all-pass filter with central frequency (in Hz) 1535@var{frequency}, and filter-width @var{width}. 1536An all-pass filter changes the audio's frequency to phase relationship 1537without changing its frequency to amplitude relationship. 1538 1539The filter accepts the following options: 1540 1541@table @option 1542@item frequency, f 1543Set frequency in Hz. 1544 1545@item width_type, t 1546Set method to specify band-width of filter. 1547@table @option 1548@item h 1549Hz 1550@item q 1551Q-Factor 1552@item o 1553octave 1554@item s 1555slope 1556@item k 1557kHz 1558@end table 1559 1560@item width, w 1561Specify the band-width of a filter in width_type units. 1562 1563@item mix, m 1564How much to use filtered signal in output. Default is 1. 1565Range is between 0 and 1. 1566 1567@item channels, c 1568Specify which channels to filter, by default all available are filtered. 1569 1570@item normalize, n 1571Normalize biquad coefficients, by default is disabled. 1572Enabling it will normalize magnitude response at DC to 0dB. 1573 1574@item order, o 1575Set the filter order, can be 1 or 2. Default is 2. 1576 1577@item transform, a 1578Set transform type of IIR filter. 1579@table @option 1580@item di 1581@item dii 1582@item tdii 1583@end table 1584@end table 1585 1586@subsection Commands 1587 1588This filter supports the following commands: 1589@table @option 1590@item frequency, f 1591Change allpass frequency. 1592Syntax for the command is : "@var{frequency}" 1593 1594@item width_type, t 1595Change allpass width_type. 1596Syntax for the command is : "@var{width_type}" 1597 1598@item width, w 1599Change allpass width. 1600Syntax for the command is : "@var{width}" 1601 1602@item mix, m 1603Change allpass mix. 1604Syntax for the command is : "@var{mix}" 1605@end table 1606 1607@section aloop 1608 1609Loop audio samples. 1610 1611The filter accepts the following options: 1612 1613@table @option 1614@item loop 1615Set the number of loops. Setting this value to -1 will result in infinite loops. 1616Default is 0. 1617 1618@item size 1619Set maximal number of samples. Default is 0. 1620 1621@item start 1622Set first sample of loop. Default is 0. 1623@end table 1624 1625@anchor{amerge} 1626@section amerge 1627 1628Merge two or more audio streams into a single multi-channel stream. 1629 1630The filter accepts the following options: 1631 1632@table @option 1633 1634@item inputs 1635Set the number of inputs. Default is 2. 1636 1637@end table 1638 1639If the channel layouts of the inputs are disjoint, and therefore compatible, 1640the channel layout of the output will be set accordingly and the channels 1641will be reordered as necessary. If the channel layouts of the inputs are not 1642disjoint, the output will have all the channels of the first input then all 1643the channels of the second input, in that order, and the channel layout of 1644the output will be the default value corresponding to the total number of 1645channels. 1646 1647For example, if the first input is in 2.1 (FL+FR+LF) and the second input 1648is FC+BL+BR, then the output will be in 5.1, with the channels in the 1649following order: a1, a2, b1, a3, b2, b3 (a1 is the first channel of the 1650first input, b1 is the first channel of the second input). 1651 1652On the other hand, if both input are in stereo, the output channels will be 1653in the default order: a1, a2, b1, b2, and the channel layout will be 1654arbitrarily set to 4.0, which may or may not be the expected value. 1655 1656All inputs must have the same sample rate, and format. 1657 1658If inputs do not have the same duration, the output will stop with the 1659shortest. 1660 1661@subsection Examples 1662 1663@itemize 1664@item 1665Merge two mono files into a stereo stream: 1666@example 1667amovie=left.wav [l] ; amovie=right.mp3 [r] ; [l] [r] amerge 1668@end example 1669 1670@item 1671Multiple merges assuming 1 video stream and 6 audio streams in @file{input.mkv}: 1672@example 1673ffmpeg -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 1674@end example 1675@end itemize 1676 1677@section amix 1678 1679Mixes multiple audio inputs into a single output. 1680 1681Note that this filter only supports float samples (the @var{amerge} 1682and @var{pan} audio filters support many formats). If the @var{amix} 1683input has integer samples then @ref{aresample} will be automatically 1684inserted to perform the conversion to float samples. 1685 1686For example 1687@example 1688ffmpeg -i INPUT1 -i INPUT2 -i INPUT3 -filter_complex amix=inputs=3:duration=first:dropout_transition=3 OUTPUT 1689@end example 1690will mix 3 input audio streams to a single output with the same duration as the 1691first input and a dropout transition time of 3 seconds. 1692 1693It accepts the following parameters: 1694@table @option 1695 1696@item inputs 1697The number of inputs. If unspecified, it defaults to 2. 1698 1699@item duration 1700How to determine the end-of-stream. 1701@table @option 1702 1703@item longest 1704The duration of the longest input. (default) 1705 1706@item shortest 1707The duration of the shortest input. 1708 1709@item first 1710The duration of the first input. 1711 1712@end table 1713 1714@item dropout_transition 1715The transition time, in seconds, for volume renormalization when an input 1716stream ends. The default value is 2 seconds. 1717 1718@item weights 1719Specify weight of each input audio stream as sequence. 1720Each weight is separated by space. By default all inputs have same weight. 1721@end table 1722 1723@subsection Commands 1724 1725This filter supports the following commands: 1726@table @option 1727@item weights 1728Syntax is same as option with same name. 1729@end table 1730 1731@section amultiply 1732 1733Multiply first audio stream with second audio stream and store result 1734in output audio stream. Multiplication is done by multiplying each 1735sample from first stream with sample at same position from second stream. 1736 1737With this element-wise multiplication one can create amplitude fades and 1738amplitude modulations. 1739 1740@section anequalizer 1741 1742High-order parametric multiband equalizer for each channel. 1743 1744It accepts the following parameters: 1745@table @option 1746@item params 1747 1748This option string is in format: 1749"c@var{chn} f=@var{cf} w=@var{w} g=@var{g} t=@var{f} | ..." 1750Each equalizer band is separated by '|'. 1751 1752@table @option 1753@item chn 1754Set channel number to which equalization will be applied. 1755If input doesn't have that channel the entry is ignored. 1756 1757@item f 1758Set central frequency for band. 1759If input doesn't have that frequency the entry is ignored. 1760 1761@item w 1762Set band width in hertz. 1763 1764@item g 1765Set band gain in dB. 1766 1767@item t 1768Set filter type for band, optional, can be: 1769 1770@table @samp 1771@item 0 1772Butterworth, this is default. 1773 1774@item 1 1775Chebyshev type 1. 1776 1777@item 2 1778Chebyshev type 2. 1779@end table 1780@end table 1781 1782@item curves 1783With this option activated frequency response of anequalizer is displayed 1784in video stream. 1785 1786@item size 1787Set video stream size. Only useful if curves option is activated. 1788 1789@item mgain 1790Set max gain that will be displayed. Only useful if curves option is activated. 1791Setting this to a reasonable value makes it possible to display gain which is derived from 1792neighbour bands which are too close to each other and thus produce higher gain 1793when both are activated. 1794 1795@item fscale 1796Set frequency scale used to draw frequency response in video output. 1797Can be linear or logarithmic. Default is logarithmic. 1798 1799@item colors 1800Set color for each channel curve which is going to be displayed in video stream. 1801This is list of color names separated by space or by '|'. 1802Unrecognised or missing colors will be replaced by white color. 1803@end table 1804 1805@subsection Examples 1806 1807@itemize 1808@item 1809Lower gain by 10 of central frequency 200Hz and width 100 Hz 1810for first 2 channels using Chebyshev type 1 filter: 1811@example 1812anequalizer=c0 f=200 w=100 g=-10 t=1|c1 f=200 w=100 g=-10 t=1 1813@end example 1814@end itemize 1815 1816@subsection Commands 1817 1818This filter supports the following commands: 1819@table @option 1820@item change 1821Alter existing filter parameters. 1822Syntax for the commands is : "@var{fN}|f=@var{freq}|w=@var{width}|g=@var{gain}" 1823 1824@var{fN} is existing filter number, starting from 0, if no such filter is available 1825error is returned. 1826@var{freq} set new frequency parameter. 1827@var{width} set new width parameter in herz. 1828@var{gain} set new gain parameter in dB. 1829 1830Full filter invocation with asendcmd may look like this: 1831asendcmd=c='4.0 anequalizer change 0|f=200|w=50|g=1',anequalizer=... 1832@end table 1833 1834@section anlmdn 1835 1836Reduce broadband noise in audio samples using Non-Local Means algorithm. 1837 1838Each sample is adjusted by looking for other samples with similar contexts. This 1839context similarity is defined by comparing their surrounding patches of size 1840@option{p}. Patches are searched in an area of @option{r} around the sample. 1841 1842The filter accepts the following options: 1843 1844@table @option 1845@item s 1846Set denoising strength. Allowed range is from 0.00001 to 10. Default value is 0.00001. 1847 1848@item p 1849Set patch radius duration. Allowed range is from 1 to 100 milliseconds. 1850Default value is 2 milliseconds. 1851 1852@item r 1853Set research radius duration. Allowed range is from 2 to 300 milliseconds. 1854Default value is 6 milliseconds. 1855 1856@item o 1857Set the output mode. 1858 1859It accepts the following values: 1860@table @option 1861@item i 1862Pass input unchanged. 1863 1864@item o 1865Pass noise filtered out. 1866 1867@item n 1868Pass only noise. 1869 1870Default value is @var{o}. 1871@end table 1872 1873@item m 1874Set smooth factor. Default value is @var{11}. Allowed range is from @var{1} to @var{15}. 1875@end table 1876 1877@subsection Commands 1878 1879This filter supports the following commands: 1880@table @option 1881@item s 1882Change denoise strength. Argument is single float number. 1883Syntax for the command is : "@var{s}" 1884 1885@item o 1886Change output mode. 1887Syntax for the command is : "i", "o" or "n" string. 1888@end table 1889 1890@section anlms 1891Apply Normalized Least-Mean-Squares algorithm to the first audio stream using the second audio stream. 1892 1893This adaptive filter is used to mimic a desired filter by finding the filter coefficients that 1894relate to producing the least mean square of the error signal (difference between the desired, 18952nd input audio stream and the actual signal, the 1st input audio stream). 1896 1897A description of the accepted options follows. 1898 1899@table @option 1900@item order 1901Set filter order. 1902 1903@item mu 1904Set filter mu. 1905 1906@item eps 1907Set the filter eps. 1908 1909@item leakage 1910Set the filter leakage. 1911 1912@item out_mode 1913It accepts the following values: 1914@table @option 1915@item i 1916Pass the 1st input. 1917 1918@item d 1919Pass the 2nd input. 1920 1921@item o 1922Pass filtered samples. 1923 1924@item n 1925Pass difference between desired and filtered samples. 1926 1927Default value is @var{o}. 1928@end table 1929@end table 1930 1931@subsection Examples 1932 1933@itemize 1934@item 1935One of many usages of this filter is noise reduction, input audio is filtered 1936with same samples that are delayed by fixed amount, one such example for stereo audio is: 1937@example 1938asplit[a][b],[a]adelay=32S|32S[a],[b][a]anlms=order=128:leakage=0.0005:mu=.5:out_mode=o 1939@end example 1940@end itemize 1941 1942@subsection Commands 1943 1944This filter supports the same commands as options, excluding option @code{order}. 1945 1946@section anull 1947 1948Pass the audio source unchanged to the output. 1949 1950@section apad 1951 1952Pad the end of an audio stream with silence. 1953 1954This can be used together with @command{ffmpeg} @option{-shortest} to 1955extend audio streams to the same length as the video stream. 1956 1957A description of the accepted options follows. 1958 1959@table @option 1960@item packet_size 1961Set silence packet size. Default value is 4096. 1962 1963@item pad_len 1964Set the number of samples of silence to add to the end. After the 1965value is reached, the stream is terminated. This option is mutually 1966exclusive with @option{whole_len}. 1967 1968@item whole_len 1969Set the minimum total number of samples in the output audio stream. If 1970the value is longer than the input audio length, silence is added to 1971the end, until the value is reached. This option is mutually exclusive 1972with @option{pad_len}. 1973 1974@item pad_dur 1975Specify the duration of samples of silence to add. See 1976@ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils} 1977for the accepted syntax. Used only if set to non-zero value. 1978 1979@item whole_dur 1980Specify the minimum total duration in the output audio stream. See 1981@ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils} 1982for the accepted syntax. Used only if set to non-zero value. If the value is longer than 1983the input audio length, silence is added to the end, until the value is reached. 1984This option is mutually exclusive with @option{pad_dur} 1985@end table 1986 1987If neither the @option{pad_len} nor the @option{whole_len} nor @option{pad_dur} 1988nor @option{whole_dur} option is set, the filter will add silence to the end of 1989the input stream indefinitely. 1990 1991@subsection Examples 1992 1993@itemize 1994@item 1995Add 1024 samples of silence to the end of the input: 1996@example 1997apad=pad_len=1024 1998@end example 1999 2000@item 2001Make sure the audio output will contain at least 10000 samples, pad 2002the input with silence if required: 2003@example 2004apad=whole_len=10000 2005@end example 2006 2007@item 2008Use @command{ffmpeg} to pad the audio input with silence, so that the 2009video stream will always result the shortest and will be converted 2010until the end in the output file when using the @option{shortest} 2011option: 2012@example 2013ffmpeg -i VIDEO -i AUDIO -filter_complex "[1:0]apad" -shortest OUTPUT 2014@end example 2015@end itemize 2016 2017@section aphaser 2018Add a phasing effect to the input audio. 2019 2020A phaser filter creates series of peaks and troughs in the frequency spectrum. 2021The position of the peaks and troughs are modulated so that they vary over time, creating a sweeping effect. 2022 2023A description of the accepted parameters follows. 2024 2025@table @option 2026@item in_gain 2027Set input gain. Default is 0.4. 2028 2029@item out_gain 2030Set output gain. Default is 0.74 2031 2032@item delay 2033Set delay in milliseconds. Default is 3.0. 2034 2035@item decay 2036Set decay. Default is 0.4. 2037 2038@item speed 2039Set modulation speed in Hz. Default is 0.5. 2040 2041@item type 2042Set modulation type. Default is triangular. 2043 2044It accepts the following values: 2045@table @samp 2046@item triangular, t 2047@item sinusoidal, s 2048@end table 2049@end table 2050 2051@section apulsator 2052 2053Audio pulsator is something between an autopanner and a tremolo. 2054But it can produce funny stereo effects as well. Pulsator changes the volume 2055of the left and right channel based on a LFO (low frequency oscillator) with 2056different waveforms and shifted phases. 2057This filter have the ability to define an offset between left and right 2058channel. An offset of 0 means that both LFO shapes match each other. 2059The left and right channel are altered equally - a conventional tremolo. 2060An offset of 50% means that the shape of the right channel is exactly shifted 2061in phase (or moved backwards about half of the frequency) - pulsator acts as 2062an autopanner. At 1 both curves match again. Every setting in between moves the 2063phase shift gapless between all stages and produces some "bypassing" sounds with 2064sine and triangle waveforms. The more you set the offset near 1 (starting from 2065the 0.5) the faster the signal passes from the left to the right speaker. 2066 2067The filter accepts the following options: 2068 2069@table @option 2070@item level_in 2071Set input gain. By default it is 1. Range is [0.015625 - 64]. 2072 2073@item level_out 2074Set output gain. By default it is 1. Range is [0.015625 - 64]. 2075 2076@item mode 2077Set waveform shape the LFO will use. Can be one of: sine, triangle, square, 2078sawup or sawdown. Default is sine. 2079 2080@item amount 2081Set modulation. Define how much of original signal is affected by the LFO. 2082 2083@item offset_l 2084Set left channel offset. Default is 0. Allowed range is [0 - 1]. 2085 2086@item offset_r 2087Set right channel offset. Default is 0.5. Allowed range is [0 - 1]. 2088 2089@item width 2090Set pulse width. Default is 1. Allowed range is [0 - 2]. 2091 2092@item timing 2093Set possible timing mode. Can be one of: bpm, ms or hz. Default is hz. 2094 2095@item bpm 2096Set bpm. Default is 120. Allowed range is [30 - 300]. Only used if timing 2097is set to bpm. 2098 2099@item ms 2100Set ms. Default is 500. Allowed range is [10 - 2000]. Only used if timing 2101is set to ms. 2102 2103@item hz 2104Set frequency in Hz. Default is 2. Allowed range is [0.01 - 100]. Only used 2105if timing is set to hz. 2106@end table 2107 2108@anchor{aresample} 2109@section aresample 2110 2111Resample the input audio to the specified parameters, using the 2112libswresample library. If none are specified then the filter will 2113automatically convert between its input and output. 2114 2115This filter is also able to stretch/squeeze the audio data to make it match 2116the timestamps or to inject silence / cut out audio to make it match the 2117timestamps, do a combination of both or do neither. 2118 2119The filter accepts the syntax 2120[@var{sample_rate}:]@var{resampler_options}, where @var{sample_rate} 2121expresses a sample rate and @var{resampler_options} is a list of 2122@var{key}=@var{value} pairs, separated by ":". See the 2123@ref{Resampler Options,,"Resampler Options" section in the 2124ffmpeg-resampler(1) manual,ffmpeg-resampler} 2125for the complete list of supported options. 2126 2127@subsection Examples 2128 2129@itemize 2130@item 2131Resample the input audio to 44100Hz: 2132@example 2133aresample=44100 2134@end example 2135 2136@item 2137Stretch/squeeze samples to the given timestamps, with a maximum of 1000 2138samples per second compensation: 2139@example 2140aresample=async=1000 2141@end example 2142@end itemize 2143 2144@section areverse 2145 2146Reverse an audio clip. 2147 2148Warning: This filter requires memory to buffer the entire clip, so trimming 2149is suggested. 2150 2151@subsection Examples 2152 2153@itemize 2154@item 2155Take the first 5 seconds of a clip, and reverse it. 2156@example 2157atrim=end=5,areverse 2158@end example 2159@end itemize 2160 2161@section arnndn 2162 2163Reduce noise from speech using Recurrent Neural Networks. 2164 2165This filter accepts the following options: 2166 2167@table @option 2168@item model, m 2169Set train model file to load. This option is always required. 2170@end table 2171 2172@section asetnsamples 2173 2174Set the number of samples per each output audio frame. 2175 2176The last output packet may contain a different number of samples, as 2177the filter will flush all the remaining samples when the input audio 2178signals its end. 2179 2180The filter accepts the following options: 2181 2182@table @option 2183 2184@item nb_out_samples, n 2185Set the number of frames per each output audio frame. The number is 2186intended as the number of samples @emph{per each channel}. 2187Default value is 1024. 2188 2189@item pad, p 2190If set to 1, the filter will pad the last audio frame with zeroes, so 2191that the last frame will contain the same number of samples as the 2192previous ones. Default value is 1. 2193@end table 2194 2195For example, to set the number of per-frame samples to 1234 and 2196disable padding for the last frame, use: 2197@example 2198asetnsamples=n=1234:p=0 2199@end example 2200 2201@section asetrate 2202 2203Set the sample rate without altering the PCM data. 2204This will result in a change of speed and pitch. 2205 2206The filter accepts the following options: 2207 2208@table @option 2209@item sample_rate, r 2210Set the output sample rate. Default is 44100 Hz. 2211@end table 2212 2213@section ashowinfo 2214 2215Show a line containing various information for each input audio frame. 2216The input audio is not modified. 2217 2218The shown line contains a sequence of key/value pairs of the form 2219@var{key}:@var{value}. 2220 2221The following values are shown in the output: 2222 2223@table @option 2224@item n 2225The (sequential) number of the input frame, starting from 0. 2226 2227@item pts 2228The presentation timestamp of the input frame, in time base units; the time base 2229depends on the filter input pad, and is usually 1/@var{sample_rate}. 2230 2231@item pts_time 2232The presentation timestamp of the input frame in seconds. 2233 2234@item pos 2235position of the frame in the input stream, -1 if this information in 2236unavailable and/or meaningless (for example in case of synthetic audio) 2237 2238@item fmt 2239The sample format. 2240 2241@item chlayout 2242The channel layout. 2243 2244@item rate 2245The sample rate for the audio frame. 2246 2247@item nb_samples 2248The number of samples (per channel) in the frame. 2249 2250@item checksum 2251The Adler-32 checksum (printed in hexadecimal) of the audio data. For planar 2252audio, the data is treated as if all the planes were concatenated. 2253 2254@item plane_checksums 2255A list of Adler-32 checksums for each data plane. 2256@end table 2257 2258@section asoftclip 2259Apply audio soft clipping. 2260 2261Soft clipping is a type of distortion effect where the amplitude of a signal is saturated 2262along a smooth curve, rather than the abrupt shape of hard-clipping. 2263 2264This filter accepts the following options: 2265 2266@table @option 2267@item type 2268Set type of soft-clipping. 2269 2270It accepts the following values: 2271@table @option 2272@item tanh 2273@item atan 2274@item cubic 2275@item exp 2276@item alg 2277@item quintic 2278@item sin 2279@end table 2280 2281@item param 2282Set additional parameter which controls sigmoid function. 2283@end table 2284 2285@subsection Commands 2286 2287This filter supports the all above options as @ref{commands}. 2288 2289@section asr 2290Automatic Speech Recognition 2291 2292This filter uses PocketSphinx for speech recognition. To enable 2293compilation of this filter, you need to configure FFmpeg with 2294@code{--enable-pocketsphinx}. 2295 2296It accepts the following options: 2297 2298@table @option 2299@item rate 2300Set sampling rate of input audio. Defaults is @code{16000}. 2301This need to match speech models, otherwise one will get poor results. 2302 2303@item hmm 2304Set dictionary containing acoustic model files. 2305 2306@item dict 2307Set pronunciation dictionary. 2308 2309@item lm 2310Set language model file. 2311 2312@item lmctl 2313Set language model set. 2314 2315@item lmname 2316Set which language model to use. 2317 2318@item logfn 2319Set output for log messages. 2320@end table 2321 2322The filter exports recognized speech as the frame metadata @code{lavfi.asr.text}. 2323 2324@anchor{astats} 2325@section astats 2326 2327Display time domain statistical information about the audio channels. 2328Statistics are calculated and displayed for each audio channel and, 2329where applicable, an overall figure is also given. 2330 2331It accepts the following option: 2332@table @option 2333@item length 2334Short window length in seconds, used for peak and trough RMS measurement. 2335Default is @code{0.05} (50 milliseconds). Allowed range is @code{[0.01 - 10]}. 2336 2337@item metadata 2338 2339Set metadata injection. All the metadata keys are prefixed with @code{lavfi.astats.X}, 2340where @code{X} is channel number starting from 1 or string @code{Overall}. Default is 2341disabled. 2342 2343Available keys for each channel are: 2344DC_offset 2345Min_level 2346Max_level 2347Min_difference 2348Max_difference 2349Mean_difference 2350RMS_difference 2351Peak_level 2352RMS_peak 2353RMS_trough 2354Crest_factor 2355Flat_factor 2356Peak_count 2357Noise_floor 2358Noise_floor_count 2359Bit_depth 2360Dynamic_range 2361Zero_crossings 2362Zero_crossings_rate 2363Number_of_NaNs 2364Number_of_Infs 2365Number_of_denormals 2366 2367and for Overall: 2368DC_offset 2369Min_level 2370Max_level 2371Min_difference 2372Max_difference 2373Mean_difference 2374RMS_difference 2375Peak_level 2376RMS_level 2377RMS_peak 2378RMS_trough 2379Flat_factor 2380Peak_count 2381Noise_floor 2382Noise_floor_count 2383Bit_depth 2384Number_of_samples 2385Number_of_NaNs 2386Number_of_Infs 2387Number_of_denormals 2388 2389For example full key look like this @code{lavfi.astats.1.DC_offset} or 2390this @code{lavfi.astats.Overall.Peak_count}. 2391 2392For description what each key means read below. 2393 2394@item reset 2395Set number of frame after which stats are going to be recalculated. 2396Default is disabled. 2397 2398@item measure_perchannel 2399Select the entries which need to be measured per channel. The metadata keys can 2400be used as flags, default is @option{all} which measures everything. 2401@option{none} disables all per channel measurement. 2402 2403@item measure_overall 2404Select the entries which need to be measured overall. The metadata keys can 2405be used as flags, default is @option{all} which measures everything. 2406@option{none} disables all overall measurement. 2407 2408@end table 2409 2410A description of each shown parameter follows: 2411 2412@table @option 2413@item DC offset 2414Mean amplitude displacement from zero. 2415 2416@item Min level 2417Minimal sample level. 2418 2419@item Max level 2420Maximal sample level. 2421 2422@item Min difference 2423Minimal difference between two consecutive samples. 2424 2425@item Max difference 2426Maximal difference between two consecutive samples. 2427 2428@item Mean difference 2429Mean difference between two consecutive samples. 2430The average of each difference between two consecutive samples. 2431 2432@item RMS difference 2433Root Mean Square difference between two consecutive samples. 2434 2435@item Peak level dB 2436@item RMS level dB 2437Standard peak and RMS level measured in dBFS. 2438 2439@item RMS peak dB 2440@item RMS trough dB 2441Peak and trough values for RMS level measured over a short window. 2442 2443@item Crest factor 2444Standard ratio of peak to RMS level (note: not in dB). 2445 2446@item Flat factor 2447Flatness (i.e. consecutive samples with the same value) of the signal at its peak levels 2448(i.e. either @var{Min level} or @var{Max level}). 2449 2450@item Peak count 2451Number of occasions (not the number of samples) that the signal attained either 2452@var{Min level} or @var{Max level}. 2453 2454@item Noise floor dB 2455Minimum local peak measured in dBFS over a short window. 2456 2457@item Noise floor count 2458Number of occasions (not the number of samples) that the signal attained 2459@var{Noise floor}. 2460 2461@item Bit depth 2462Overall bit depth of audio. Number of bits used for each sample. 2463 2464@item Dynamic range 2465Measured dynamic range of audio in dB. 2466 2467@item Zero crossings 2468Number of points where the waveform crosses the zero level axis. 2469 2470@item Zero crossings rate 2471Rate of Zero crossings and number of audio samples. 2472@end table 2473 2474@section asubboost 2475Boost subwoofer frequencies. 2476 2477The filter accepts the following options: 2478 2479@table @option 2480@item dry 2481Set dry gain, how much of original signal is kept. Allowed range is from 0 to 1. 2482Default value is 0.5. 2483 2484@item wet 2485Set wet gain, how much of filtered signal is kept. Allowed range is from 0 to 1. 2486Default value is 0.8. 2487 2488@item decay 2489Set delay line decay gain value. Allowed range is from 0 to 1. 2490Default value is 0.7. 2491 2492@item feedback 2493Set delay line feedback gain value. Allowed range is from 0 to 1. 2494Default value is 0.5. 2495 2496@item cutoff 2497Set cutoff frequency in herz. Allowed range is 50 to 900. 2498Default value is 100. 2499 2500@item slope 2501Set slope amount for cutoff frequency. Allowed range is 0.0001 to 1. 2502Default value is 0.5. 2503 2504@item delay 2505Set delay. Allowed range is from 1 to 100. 2506Default value is 20. 2507@end table 2508 2509@subsection Commands 2510 2511This filter supports the all above options as @ref{commands}. 2512 2513@section atempo 2514 2515Adjust audio tempo. 2516 2517The filter accepts exactly one parameter, the audio tempo. If not 2518specified then the filter will assume nominal 1.0 tempo. Tempo must 2519be in the [0.5, 100.0] range. 2520 2521Note that tempo greater than 2 will skip some samples rather than 2522blend them in. If for any reason this is a concern it is always 2523possible to daisy-chain several instances of atempo to achieve the 2524desired product tempo. 2525 2526@subsection Examples 2527 2528@itemize 2529@item 2530Slow down audio to 80% tempo: 2531@example 2532atempo=0.8 2533@end example 2534 2535@item 2536To speed up audio to 300% tempo: 2537@example 2538atempo=3 2539@end example 2540 2541@item 2542To speed up audio to 300% tempo by daisy-chaining two atempo instances: 2543@example 2544atempo=sqrt(3),atempo=sqrt(3) 2545@end example 2546@end itemize 2547 2548@subsection Commands 2549 2550This filter supports the following commands: 2551@table @option 2552@item tempo 2553Change filter tempo scale factor. 2554Syntax for the command is : "@var{tempo}" 2555@end table 2556 2557@section atrim 2558 2559Trim the input so that the output contains one continuous subpart of the input. 2560 2561It accepts the following parameters: 2562@table @option 2563@item start 2564Timestamp (in seconds) of the start of the section to keep. I.e. the audio 2565sample with the timestamp @var{start} will be the first sample in the output. 2566 2567@item end 2568Specify time of the first audio sample that will be dropped, i.e. the 2569audio sample immediately preceding the one with the timestamp @var{end} will be 2570the last sample in the output. 2571 2572@item start_pts 2573Same as @var{start}, except this option sets the start timestamp in samples 2574instead of seconds. 2575 2576@item end_pts 2577Same as @var{end}, except this option sets the end timestamp in samples instead 2578of seconds. 2579 2580@item duration 2581The maximum duration of the output in seconds. 2582 2583@item start_sample 2584The number of the first sample that should be output. 2585 2586@item end_sample 2587The number of the first sample that should be dropped. 2588@end table 2589 2590@option{start}, @option{end}, and @option{duration} are expressed as time 2591duration specifications; see 2592@ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}. 2593 2594Note that the first two sets of the start/end options and the @option{duration} 2595option look at the frame timestamp, while the _sample options simply count the 2596samples that pass through the filter. So start/end_pts and start/end_sample will 2597give different results when the timestamps are wrong, inexact or do not start at 2598zero. Also note that this filter does not modify the timestamps. If you wish 2599to have the output timestamps start at zero, insert the asetpts filter after the 2600atrim filter. 2601 2602If multiple start or end options are set, this filter tries to be greedy and 2603keep all samples that match at least one of the specified constraints. To keep 2604only the part that matches all the constraints at once, chain multiple atrim 2605filters. 2606 2607The defaults are such that all the input is kept. So it is possible to set e.g. 2608just the end values to keep everything before the specified time. 2609 2610Examples: 2611@itemize 2612@item 2613Drop everything except the second minute of input: 2614@example 2615ffmpeg -i INPUT -af atrim=60:120 2616@end example 2617 2618@item 2619Keep only the first 1000 samples: 2620@example 2621ffmpeg -i INPUT -af atrim=end_sample=1000 2622@end example 2623 2624@end itemize 2625 2626@section axcorrelate 2627Calculate normalized cross-correlation between two input audio streams. 2628 2629Resulted samples are always between -1 and 1 inclusive. 2630If result is 1 it means two input samples are highly correlated in that selected segment. 2631Result 0 means they are not correlated at all. 2632If result is -1 it means two input samples are out of phase, which means they cancel each 2633other. 2634 2635The filter accepts the following options: 2636 2637@table @option 2638@item size 2639Set size of segment over which cross-correlation is calculated. 2640Default is 256. Allowed range is from 2 to 131072. 2641 2642@item algo 2643Set algorithm for cross-correlation. Can be @code{slow} or @code{fast}. 2644Default is @code{slow}. Fast algorithm assumes mean values over any given segment 2645are always zero and thus need much less calculations to make. 2646This is generally not true, but is valid for typical audio streams. 2647@end table 2648 2649@subsection Examples 2650 2651@itemize 2652@item 2653Calculate correlation between channels in stereo audio stream: 2654@example 2655ffmpeg -i stereo.wav -af channelsplit,axcorrelate=size=1024:algo=fast correlation.wav 2656@end example 2657@end itemize 2658 2659@section bandpass 2660 2661Apply a two-pole Butterworth band-pass filter with central 2662frequency @var{frequency}, and (3dB-point) band-width width. 2663The @var{csg} option selects a constant skirt gain (peak gain = Q) 2664instead of the default: constant 0dB peak gain. 2665The filter roll off at 6dB per octave (20dB per decade). 2666 2667The filter accepts the following options: 2668 2669@table @option 2670@item frequency, f 2671Set the filter's central frequency. Default is @code{3000}. 2672 2673@item csg 2674Constant skirt gain if set to 1. Defaults to 0. 2675 2676@item width_type, t 2677Set method to specify band-width of filter. 2678@table @option 2679@item h 2680Hz 2681@item q 2682Q-Factor 2683@item o 2684octave 2685@item s 2686slope 2687@item k 2688kHz 2689@end table 2690 2691@item width, w 2692Specify the band-width of a filter in width_type units. 2693 2694@item mix, m 2695How much to use filtered signal in output. Default is 1. 2696Range is between 0 and 1. 2697 2698@item channels, c 2699Specify which channels to filter, by default all available are filtered. 2700 2701@item normalize, n 2702Normalize biquad coefficients, by default is disabled. 2703Enabling it will normalize magnitude response at DC to 0dB. 2704 2705@item transform, a 2706Set transform type of IIR filter. 2707@table @option 2708@item di 2709@item dii 2710@item tdii 2711@end table 2712@end table 2713 2714@subsection Commands 2715 2716This filter supports the following commands: 2717@table @option 2718@item frequency, f 2719Change bandpass frequency. 2720Syntax for the command is : "@var{frequency}" 2721 2722@item width_type, t 2723Change bandpass width_type. 2724Syntax for the command is : "@var{width_type}" 2725 2726@item width, w 2727Change bandpass width. 2728Syntax for the command is : "@var{width}" 2729 2730@item mix, m 2731Change bandpass mix. 2732Syntax for the command is : "@var{mix}" 2733@end table 2734 2735@section bandreject 2736 2737Apply a two-pole Butterworth band-reject filter with central 2738frequency @var{frequency}, and (3dB-point) band-width @var{width}. 2739The filter roll off at 6dB per octave (20dB per decade). 2740 2741The filter accepts the following options: 2742 2743@table @option 2744@item frequency, f 2745Set the filter's central frequency. Default is @code{3000}. 2746 2747@item width_type, t 2748Set method to specify band-width of filter. 2749@table @option 2750@item h 2751Hz 2752@item q 2753Q-Factor 2754@item o 2755octave 2756@item s 2757slope 2758@item k 2759kHz 2760@end table 2761 2762@item width, w 2763Specify the band-width of a filter in width_type units. 2764 2765@item mix, m 2766How much to use filtered signal in output. Default is 1. 2767Range is between 0 and 1. 2768 2769@item channels, c 2770Specify which channels to filter, by default all available are filtered. 2771 2772@item normalize, n 2773Normalize biquad coefficients, by default is disabled. 2774Enabling it will normalize magnitude response at DC to 0dB. 2775 2776@item transform, a 2777Set transform type of IIR filter. 2778@table @option 2779@item di 2780@item dii 2781@item tdii 2782@end table 2783@end table 2784 2785@subsection Commands 2786 2787This filter supports the following commands: 2788@table @option 2789@item frequency, f 2790Change bandreject frequency. 2791Syntax for the command is : "@var{frequency}" 2792 2793@item width_type, t 2794Change bandreject width_type. 2795Syntax for the command is : "@var{width_type}" 2796 2797@item width, w 2798Change bandreject width. 2799Syntax for the command is : "@var{width}" 2800 2801@item mix, m 2802Change bandreject mix. 2803Syntax for the command is : "@var{mix}" 2804@end table 2805 2806@section bass, lowshelf 2807 2808Boost or cut the bass (lower) frequencies of the audio using a two-pole 2809shelving filter with a response similar to that of a standard 2810hi-fi's tone-controls. This is also known as shelving equalisation (EQ). 2811 2812The filter accepts the following options: 2813 2814@table @option 2815@item gain, g 2816Give the gain at 0 Hz. Its useful range is about -20 2817(for a large cut) to +20 (for a large boost). 2818Beware of clipping when using a positive gain. 2819 2820@item frequency, f 2821Set the filter's central frequency and so can be used 2822to extend or reduce the frequency range to be boosted or cut. 2823The default value is @code{100} Hz. 2824 2825@item width_type, t 2826Set method to specify band-width of filter. 2827@table @option 2828@item h 2829Hz 2830@item q 2831Q-Factor 2832@item o 2833octave 2834@item s 2835slope 2836@item k 2837kHz 2838@end table 2839 2840@item width, w 2841Determine how steep is the filter's shelf transition. 2842 2843@item mix, m 2844How much to use filtered signal in output. Default is 1. 2845Range is between 0 and 1. 2846 2847@item channels, c 2848Specify which channels to filter, by default all available are filtered. 2849 2850@item normalize, n 2851Normalize biquad coefficients, by default is disabled. 2852Enabling it will normalize magnitude response at DC to 0dB. 2853 2854@item transform, a 2855Set transform type of IIR filter. 2856@table @option 2857@item di 2858@item dii 2859@item tdii 2860@end table 2861@end table 2862 2863@subsection Commands 2864 2865This filter supports the following commands: 2866@table @option 2867@item frequency, f 2868Change bass frequency. 2869Syntax for the command is : "@var{frequency}" 2870 2871@item width_type, t 2872Change bass width_type. 2873Syntax for the command is : "@var{width_type}" 2874 2875@item width, w 2876Change bass width. 2877Syntax for the command is : "@var{width}" 2878 2879@item gain, g 2880Change bass gain. 2881Syntax for the command is : "@var{gain}" 2882 2883@item mix, m 2884Change bass mix. 2885Syntax for the command is : "@var{mix}" 2886@end table 2887 2888@section biquad 2889 2890Apply a biquad IIR filter with the given coefficients. 2891Where @var{b0}, @var{b1}, @var{b2} and @var{a0}, @var{a1}, @var{a2} 2892are the numerator and denominator coefficients respectively. 2893and @var{channels}, @var{c} specify which channels to filter, by default all 2894available are filtered. 2895 2896@subsection Commands 2897 2898This filter supports the following commands: 2899@table @option 2900@item a0 2901@item a1 2902@item a2 2903@item b0 2904@item b1 2905@item b2 2906Change biquad parameter. 2907Syntax for the command is : "@var{value}" 2908 2909@item mix, m 2910How much to use filtered signal in output. Default is 1. 2911Range is between 0 and 1. 2912 2913@item channels, c 2914Specify which channels to filter, by default all available are filtered. 2915 2916@item normalize, n 2917Normalize biquad coefficients, by default is disabled. 2918Enabling it will normalize magnitude response at DC to 0dB. 2919 2920@item transform, a 2921Set transform type of IIR filter. 2922@table @option 2923@item di 2924@item dii 2925@item tdii 2926@end table 2927@end table 2928 2929@section bs2b 2930Bauer stereo to binaural transformation, which improves headphone listening of 2931stereo audio records. 2932 2933To enable compilation of this filter you need to configure FFmpeg with 2934@code{--enable-libbs2b}. 2935 2936It accepts the following parameters: 2937@table @option 2938 2939@item profile 2940Pre-defined crossfeed level. 2941@table @option 2942 2943@item default 2944Default level (fcut=700, feed=50). 2945 2946@item cmoy 2947Chu Moy circuit (fcut=700, feed=60). 2948 2949@item jmeier 2950Jan Meier circuit (fcut=650, feed=95). 2951 2952@end table 2953 2954@item fcut 2955Cut frequency (in Hz). 2956 2957@item feed 2958Feed level (in Hz). 2959 2960@end table 2961 2962@section channelmap 2963 2964Remap input channels to new locations. 2965 2966It accepts the following parameters: 2967@table @option 2968@item map 2969Map channels from input to output. The argument is a '|'-separated list of 2970mappings, each in the @code{@var{in_channel}-@var{out_channel}} or 2971@var{in_channel} form. @var{in_channel} can be either the name of the input 2972channel (e.g. FL for front left) or its index in the input channel layout. 2973@var{out_channel} is the name of the output channel or its index in the output 2974channel layout. If @var{out_channel} is not given then it is implicitly an 2975index, starting with zero and increasing by one for each mapping. 2976 2977@item channel_layout 2978The channel layout of the output stream. 2979@end table 2980 2981If no mapping is present, the filter will implicitly map input channels to 2982output channels, preserving indices. 2983 2984@subsection Examples 2985 2986@itemize 2987@item 2988For example, assuming a 5.1+downmix input MOV file, 2989@example 2990ffmpeg -i in.mov -filter 'channelmap=map=DL-FL|DR-FR' out.wav 2991@end example 2992will create an output WAV file tagged as stereo from the downmix channels of 2993the input. 2994 2995@item 2996To fix a 5.1 WAV improperly encoded in AAC's native channel order 2997@example 2998ffmpeg -i in.wav -filter 'channelmap=1|2|0|5|3|4:5.1' out.wav 2999@end example 3000@end itemize 3001 3002@section channelsplit 3003 3004Split each channel from an input audio stream into a separate output stream. 3005 3006It accepts the following parameters: 3007@table @option 3008@item channel_layout 3009The channel layout of the input stream. The default is "stereo". 3010@item channels 3011A channel layout describing the channels to be extracted as separate output streams 3012or "all" to extract each input channel as a separate stream. The default is "all". 3013 3014Choosing channels not present in channel layout in the input will result in an error. 3015@end table 3016 3017@subsection Examples 3018 3019@itemize 3020@item 3021For example, assuming a stereo input MP3 file, 3022@example 3023ffmpeg -i in.mp3 -filter_complex channelsplit out.mkv 3024@end example 3025will create an output Matroska file with two audio streams, one containing only 3026the left channel and the other the right channel. 3027 3028@item 3029Split a 5.1 WAV file into per-channel files: 3030@example 3031ffmpeg -i in.wav -filter_complex 3032'channelsplit=channel_layout=5.1[FL][FR][FC][LFE][SL][SR]' 3033-map '[FL]' front_left.wav -map '[FR]' front_right.wav -map '[FC]' 3034front_center.wav -map '[LFE]' lfe.wav -map '[SL]' side_left.wav -map '[SR]' 3035side_right.wav 3036@end example 3037 3038@item 3039Extract only LFE from a 5.1 WAV file: 3040@example 3041ffmpeg -i in.wav -filter_complex 'channelsplit=channel_layout=5.1:channels=LFE[LFE]' 3042-map '[LFE]' lfe.wav 3043@end example 3044@end itemize 3045 3046@section chorus 3047Add a chorus effect to the audio. 3048 3049Can make a single vocal sound like a chorus, but can also be applied to instrumentation. 3050 3051Chorus resembles an echo effect with a short delay, but whereas with echo the delay is 3052constant, with chorus, it is varied using using sinusoidal or triangular modulation. 3053The modulation depth defines the range the modulated delay is played before or after 3054the delay. Hence the delayed sound will sound slower or faster, that is the delayed 3055sound tuned around the original one, like in a chorus where some vocals are slightly 3056off key. 3057 3058It accepts the following parameters: 3059@table @option 3060@item in_gain 3061Set input gain. Default is 0.4. 3062 3063@item out_gain 3064Set output gain. Default is 0.4. 3065 3066@item delays 3067Set delays. A typical delay is around 40ms to 60ms. 3068 3069@item decays 3070Set decays. 3071 3072@item speeds 3073Set speeds. 3074 3075@item depths 3076Set depths. 3077@end table 3078 3079@subsection Examples 3080 3081@itemize 3082@item 3083A single delay: 3084@example 3085chorus=0.7:0.9:55:0.4:0.25:2 3086@end example 3087 3088@item 3089Two delays: 3090@example 3091chorus=0.6:0.9:50|60:0.4|0.32:0.25|0.4:2|1.3 3092@end example 3093 3094@item 3095Fuller sounding chorus with three delays: 3096@example 3097chorus=0.5:0.9:50|60|40:0.4|0.32|0.3:0.25|0.4|0.3:2|2.3|1.3 3098@end example 3099@end itemize 3100 3101@section compand 3102Compress or expand the audio's dynamic range. 3103 3104It accepts the following parameters: 3105 3106@table @option 3107 3108@item attacks 3109@item decays 3110A list of times in seconds for each channel over which the instantaneous level 3111of the input signal is averaged to determine its volume. @var{attacks} refers to 3112increase of volume and @var{decays} refers to decrease of volume. For most 3113situations, the attack time (response to the audio getting louder) should be 3114shorter than the decay time, because the human ear is more sensitive to sudden 3115loud audio than sudden soft audio. A typical value for attack is 0.3 seconds and 3116a typical value for decay is 0.8 seconds. 3117If specified number of attacks & decays is lower than number of channels, the last 3118set attack/decay will be used for all remaining channels. 3119 3120@item points 3121A list of points for the transfer function, specified in dB relative to the 3122maximum possible signal amplitude. Each key points list must be defined using 3123the following syntax: @code{x0/y0|x1/y1|x2/y2|....} or 3124@code{x0/y0 x1/y1 x2/y2 ....} 3125 3126The input values must be in strictly increasing order but the transfer function 3127does not have to be monotonically rising. The point @code{0/0} is assumed but 3128may be overridden (by @code{0/out-dBn}). Typical values for the transfer 3129function are @code{-70/-70|-60/-20|1/0}. 3130 3131@item soft-knee 3132Set the curve radius in dB for all joints. It defaults to 0.01. 3133 3134@item gain 3135Set the additional gain in dB to be applied at all points on the transfer 3136function. This allows for easy adjustment of the overall gain. 3137It defaults to 0. 3138 3139@item volume 3140Set an initial volume, in dB, to be assumed for each channel when filtering 3141starts. This permits the user to supply a nominal level initially, so that, for 3142example, a very large gain is not applied to initial signal levels before the 3143companding has begun to operate. A typical value for audio which is initially 3144quiet is -90 dB. It defaults to 0. 3145 3146@item delay 3147Set a delay, in seconds. The input audio is analyzed immediately, but audio is 3148delayed before being fed to the volume adjuster. Specifying a delay 3149approximately equal to the attack/decay times allows the filter to effectively 3150operate in predictive rather than reactive mode. It defaults to 0. 3151 3152@end table 3153 3154@subsection Examples 3155 3156@itemize 3157@item 3158Make music with both quiet and loud passages suitable for listening to in a 3159noisy environment: 3160@example 3161compand=.3|.3:1|1:-90/-60|-60/-40|-40/-30|-20/-20:6:0:-90:0.2 3162@end example 3163 3164Another example for audio with whisper and explosion parts: 3165@example 3166compand=0|0:1|1:-90/-900|-70/-70|-30/-9|0/-3:6:0:0:0 3167@end example 3168 3169@item 3170A noise gate for when the noise is at a lower level than the signal: 3171@example 3172compand=.1|.1:.2|.2:-900/-900|-50.1/-900|-50/-50:.01:0:-90:.1 3173@end example 3174 3175@item 3176Here is another noise gate, this time for when the noise is at a higher level 3177than the signal (making it, in some ways, similar to squelch): 3178@example 3179compand=.1|.1:.1|.1:-45.1/-45.1|-45/-900|0/-900:.01:45:-90:.1 3180@end example 3181 3182@item 31832:1 compression starting at -6dB: 3184@example 3185compand=points=-80/-80|-6/-6|0/-3.8|20/3.5 3186@end example 3187 3188@item 31892:1 compression starting at -9dB: 3190@example 3191compand=points=-80/-80|-9/-9|0/-5.3|20/2.9 3192@end example 3193 3194@item 31952:1 compression starting at -12dB: 3196@example 3197compand=points=-80/-80|-12/-12|0/-6.8|20/1.9 3198@end example 3199 3200@item 32012:1 compression starting at -18dB: 3202@example 3203compand=points=-80/-80|-18/-18|0/-9.8|20/0.7 3204@end example 3205 3206@item 32073:1 compression starting at -15dB: 3208@example 3209compand=points=-80/-80|-15/-15|0/-10.8|20/-5.2 3210@end example 3211 3212@item 3213Compressor/Gate: 3214@example 3215compand=points=-80/-105|-62/-80|-15.4/-15.4|0/-12|20/-7.6 3216@end example 3217 3218@item 3219Expander: 3220@example 3221compand=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 3222@end example 3223 3224@item 3225Hard limiter at -6dB: 3226@example 3227compand=attacks=0:points=-80/-80|-6/-6|20/-6 3228@end example 3229 3230@item 3231Hard limiter at -12dB: 3232@example 3233compand=attacks=0:points=-80/-80|-12/-12|20/-12 3234@end example 3235 3236@item 3237Hard noise gate at -35 dB: 3238@example 3239compand=attacks=0:points=-80/-115|-35.1/-80|-35/-35|20/20 3240@end example 3241 3242@item 3243Soft limiter: 3244@example 3245compand=attacks=0:points=-80/-80|-12.4/-12.4|-6/-8|0/-6.8|20/-2.8 3246@end example 3247@end itemize 3248 3249@section compensationdelay 3250 3251Compensation Delay Line is a metric based delay to compensate differing 3252positions of microphones or speakers. 3253 3254For example, you have recorded guitar with two microphones placed in 3255different locations. Because the front of sound wave has fixed speed in 3256normal conditions, the phasing of microphones can vary and depends on 3257their location and interposition. The best sound mix can be achieved when 3258these microphones are in phase (synchronized). Note that a distance of 3259~30 cm between microphones makes one microphone capture the signal in 3260antiphase to the other microphone. That makes the final mix sound moody. 3261This filter helps to solve phasing problems by adding different delays 3262to each microphone track and make them synchronized. 3263 3264The best result can be reached when you take one track as base and 3265synchronize other tracks one by one with it. 3266Remember that synchronization/delay tolerance depends on sample rate, too. 3267Higher sample rates will give more tolerance. 3268 3269The filter accepts the following parameters: 3270 3271@table @option 3272@item mm 3273Set millimeters distance. This is compensation distance for fine tuning. 3274Default is 0. 3275 3276@item cm 3277Set cm distance. This is compensation distance for tightening distance setup. 3278Default is 0. 3279 3280@item m 3281Set meters distance. This is compensation distance for hard distance setup. 3282Default is 0. 3283 3284@item dry 3285Set dry amount. Amount of unprocessed (dry) signal. 3286Default is 0. 3287 3288@item wet 3289Set wet amount. Amount of processed (wet) signal. 3290Default is 1. 3291 3292@item temp 3293Set temperature in degrees Celsius. This is the temperature of the environment. 3294Default is 20. 3295@end table 3296 3297@section crossfeed 3298Apply headphone crossfeed filter. 3299 3300Crossfeed is the process of blending the left and right channels of stereo 3301audio recording. 3302It is mainly used to reduce extreme stereo separation of low frequencies. 3303 3304The intent is to produce more speaker like sound to the listener. 3305 3306The filter accepts the following options: 3307 3308@table @option 3309@item strength 3310Set strength of crossfeed. Default is 0.2. Allowed range is from 0 to 1. 3311This sets gain of low shelf filter for side part of stereo image. 3312Default is -6dB. Max allowed is -30db when strength is set to 1. 3313 3314@item range 3315Set soundstage wideness. Default is 0.5. Allowed range is from 0 to 1. 3316This sets cut off frequency of low shelf filter. Default is cut off near 33171550 Hz. With range set to 1 cut off frequency is set to 2100 Hz. 3318 3319@item slope 3320Set curve slope of low shelf filter. Default is 0.5. 3321Allowed range is from 0.01 to 1. 3322 3323@item level_in 3324Set input gain. Default is 0.9. 3325 3326@item level_out 3327Set output gain. Default is 1. 3328@end table 3329 3330@subsection Commands 3331 3332This filter supports the all above options as @ref{commands}. 3333 3334@section crystalizer 3335Simple algorithm to expand audio dynamic range. 3336 3337The filter accepts the following options: 3338 3339@table @option 3340@item i 3341Sets the intensity of effect (default: 2.0). Must be in range between 0.0 3342(unchanged sound) to 10.0 (maximum effect). 3343 3344@item c 3345Enable clipping. By default is enabled. 3346@end table 3347 3348@subsection Commands 3349 3350This filter supports the all above options as @ref{commands}. 3351 3352@section dcshift 3353Apply a DC shift to the audio. 3354 3355This can be useful to remove a DC offset (caused perhaps by a hardware problem 3356in the recording chain) from the audio. The effect of a DC offset is reduced 3357headroom and hence volume. The @ref{astats} filter can be used to determine if 3358a signal has a DC offset. 3359 3360@table @option 3361@item shift 3362Set the DC shift, allowed range is [-1, 1]. It indicates the amount to shift 3363the audio. 3364 3365@item limitergain 3366Optional. It should have a value much less than 1 (e.g. 0.05 or 0.02) and is 3367used to prevent clipping. 3368@end table 3369 3370@section deesser 3371 3372Apply de-essing to the audio samples. 3373 3374@table @option 3375@item i 3376Set intensity for triggering de-essing. Allowed range is from 0 to 1. 3377Default is 0. 3378 3379@item m 3380Set amount of ducking on treble part of sound. Allowed range is from 0 to 1. 3381Default is 0.5. 3382 3383@item f 3384How much of original frequency content to keep when de-essing. Allowed range is from 0 to 1. 3385Default is 0.5. 3386 3387@item s 3388Set the output mode. 3389 3390It accepts the following values: 3391@table @option 3392@item i 3393Pass input unchanged. 3394 3395@item o 3396Pass ess filtered out. 3397 3398@item e 3399Pass only ess. 3400 3401Default value is @var{o}. 3402@end table 3403 3404@end table 3405 3406@section drmeter 3407Measure audio dynamic range. 3408 3409DR values of 14 and higher is found in very dynamic material. DR of 8 to 13 3410is found in transition material. And anything less that 8 have very poor dynamics 3411and is very compressed. 3412 3413The filter accepts the following options: 3414 3415@table @option 3416@item length 3417Set window length in seconds used to split audio into segments of equal length. 3418Default is 3 seconds. 3419@end table 3420 3421@section dynaudnorm 3422Dynamic Audio Normalizer. 3423 3424This filter applies a certain amount of gain to the input audio in order 3425to bring its peak magnitude to a target level (e.g. 0 dBFS). However, in 3426contrast to more "simple" normalization algorithms, the Dynamic Audio 3427Normalizer *dynamically* re-adjusts the gain factor to the input audio. 3428This allows for applying extra gain to the "quiet" sections of the audio 3429while avoiding distortions or clipping the "loud" sections. In other words: 3430The Dynamic Audio Normalizer will "even out" the volume of quiet and loud 3431sections, in the sense that the volume of each section is brought to the 3432same target level. Note, however, that the Dynamic Audio Normalizer achieves 3433this goal *without* applying "dynamic range compressing". It will retain 100% 3434of the dynamic range *within* each section of the audio file. 3435 3436@table @option 3437@item framelen, f 3438Set the frame length in milliseconds. In range from 10 to 8000 milliseconds. 3439Default is 500 milliseconds. 3440The Dynamic Audio Normalizer processes the input audio in small chunks, 3441referred to as frames. This is required, because a peak magnitude has no 3442meaning for just a single sample value. Instead, we need to determine the 3443peak magnitude for a contiguous sequence of sample values. While a "standard" 3444normalizer would simply use the peak magnitude of the complete file, the 3445Dynamic Audio Normalizer determines the peak magnitude individually for each 3446frame. The length of a frame is specified in milliseconds. By default, the 3447Dynamic Audio Normalizer uses a frame length of 500 milliseconds, which has 3448been found to give good results with most files. 3449Note that the exact frame length, in number of samples, will be determined 3450automatically, based on the sampling rate of the individual input audio file. 3451 3452@item gausssize, g 3453Set the Gaussian filter window size. In range from 3 to 301, must be odd 3454number. Default is 31. 3455Probably the most important parameter of the Dynamic Audio Normalizer is the 3456@code{window size} of the Gaussian smoothing filter. The filter's window size 3457is specified in frames, centered around the current frame. For the sake of 3458simplicity, this must be an odd number. Consequently, the default value of 31 3459takes into account the current frame, as well as the 15 preceding frames and 3460the 15 subsequent frames. Using a larger window results in a stronger 3461smoothing effect and thus in less gain variation, i.e. slower gain 3462adaptation. Conversely, using a smaller window results in a weaker smoothing 3463effect and thus in more gain variation, i.e. faster gain adaptation. 3464In other words, the more you increase this value, the more the Dynamic Audio 3465Normalizer will behave like a "traditional" normalization filter. On the 3466contrary, the more you decrease this value, the more the Dynamic Audio 3467Normalizer will behave like a dynamic range compressor. 3468 3469@item peak, p 3470Set the target peak value. This specifies the highest permissible magnitude 3471level for the normalized audio input. This filter will try to approach the 3472target peak magnitude as closely as possible, but at the same time it also 3473makes sure that the normalized signal will never exceed the peak magnitude. 3474A frame's maximum local gain factor is imposed directly by the target peak 3475magnitude. The default value is 0.95 and thus leaves a headroom of 5%*. 3476It is not recommended to go above this value. 3477 3478@item maxgain, m 3479Set the maximum gain factor. In range from 1.0 to 100.0. Default is 10.0. 3480The Dynamic Audio Normalizer determines the maximum possible (local) gain 3481factor for each input frame, i.e. the maximum gain factor that does not 3482result in clipping or distortion. The maximum gain factor is determined by 3483the frame's highest magnitude sample. However, the Dynamic Audio Normalizer 3484additionally bounds the frame's maximum gain factor by a predetermined 3485(global) maximum gain factor. This is done in order to avoid excessive gain 3486factors in "silent" or almost silent frames. By default, the maximum gain 3487factor is 10.0, For most inputs the default value should be sufficient and 3488it usually is not recommended to increase this value. Though, for input 3489with an extremely low overall volume level, it may be necessary to allow even 3490higher gain factors. Note, however, that the Dynamic Audio Normalizer does 3491not simply apply a "hard" threshold (i.e. cut off values above the threshold). 3492Instead, a "sigmoid" threshold function will be applied. This way, the 3493gain factors will smoothly approach the threshold value, but never exceed that 3494value. 3495 3496@item targetrms, r 3497Set the target RMS. In range from 0.0 to 1.0. Default is 0.0 - disabled. 3498By default, the Dynamic Audio Normalizer performs "peak" normalization. 3499This means that the maximum local gain factor for each frame is defined 3500(only) by the frame's highest magnitude sample. This way, the samples can 3501be amplified as much as possible without exceeding the maximum signal 3502level, i.e. without clipping. Optionally, however, the Dynamic Audio 3503Normalizer can also take into account the frame's root mean square, 3504abbreviated RMS. In electrical engineering, the RMS is commonly used to 3505determine the power of a time-varying signal. It is therefore considered 3506that the RMS is a better approximation of the "perceived loudness" than 3507just looking at the signal's peak magnitude. Consequently, by adjusting all 3508frames to a constant RMS value, a uniform "perceived loudness" can be 3509established. If a target RMS value has been specified, a frame's local gain 3510factor is defined as the factor that would result in exactly that RMS value. 3511Note, however, that the maximum local gain factor is still restricted by the 3512frame's highest magnitude sample, in order to prevent clipping. 3513 3514@item coupling, n 3515Enable channels coupling. By default is enabled. 3516By default, the Dynamic Audio Normalizer will amplify all channels by the same 3517amount. This means the same gain factor will be applied to all channels, i.e. 3518the maximum possible gain factor is determined by the "loudest" channel. 3519However, in some recordings, it may happen that the volume of the different 3520channels is uneven, e.g. one channel may be "quieter" than the other one(s). 3521In this case, this option can be used to disable the channel coupling. This way, 3522the gain factor will be determined independently for each channel, depending 3523only on the individual channel's highest magnitude sample. This allows for 3524harmonizing the volume of the different channels. 3525 3526@item correctdc, c 3527Enable DC bias correction. By default is disabled. 3528An audio signal (in the time domain) is a sequence of sample values. 3529In the Dynamic Audio Normalizer these sample values are represented in the 3530-1.0 to 1.0 range, regardless of the original input format. Normally, the 3531audio signal, or "waveform", should be centered around the zero point. 3532That means if we calculate the mean value of all samples in a file, or in a 3533single frame, then the result should be 0.0 or at least very close to that 3534value. If, however, there is a significant deviation of the mean value from 35350.0, in either positive or negative direction, this is referred to as a 3536DC bias or DC offset. Since a DC bias is clearly undesirable, the Dynamic 3537Audio Normalizer provides optional DC bias correction. 3538With DC bias correction enabled, the Dynamic Audio Normalizer will determine 3539the mean value, or "DC correction" offset, of each input frame and subtract 3540that value from all of the frame's sample values which ensures those samples 3541are centered around 0.0 again. Also, in order to avoid "gaps" at the frame 3542boundaries, the DC correction offset values will be interpolated smoothly 3543between neighbouring frames. 3544 3545@item altboundary, b 3546Enable alternative boundary mode. By default is disabled. 3547The Dynamic Audio Normalizer takes into account a certain neighbourhood 3548around each frame. This includes the preceding frames as well as the 3549subsequent frames. However, for the "boundary" frames, located at the very 3550beginning and at the very end of the audio file, not all neighbouring 3551frames are available. In particular, for the first few frames in the audio 3552file, the preceding frames are not known. And, similarly, for the last few 3553frames in the audio file, the subsequent frames are not known. Thus, the 3554question arises which gain factors should be assumed for the missing frames 3555in the "boundary" region. The Dynamic Audio Normalizer implements two modes 3556to deal with this situation. The default boundary mode assumes a gain factor 3557of exactly 1.0 for the missing frames, resulting in a smooth "fade in" and 3558"fade out" at the beginning and at the end of the input, respectively. 3559 3560@item compress, s 3561Set the compress factor. In range from 0.0 to 30.0. Default is 0.0. 3562By default, the Dynamic Audio Normalizer does not apply "traditional" 3563compression. This means that signal peaks will not be pruned and thus the 3564full dynamic range will be retained within each local neighbourhood. However, 3565in some cases it may be desirable to combine the Dynamic Audio Normalizer's 3566normalization algorithm with a more "traditional" compression. 3567For this purpose, the Dynamic Audio Normalizer provides an optional compression 3568(thresholding) function. If (and only if) the compression feature is enabled, 3569all input frames will be processed by a soft knee thresholding function prior 3570to the actual normalization process. Put simply, the thresholding function is 3571going to prune all samples whose magnitude exceeds a certain threshold value. 3572However, the Dynamic Audio Normalizer does not simply apply a fixed threshold 3573value. Instead, the threshold value will be adjusted for each individual 3574frame. 3575In general, smaller parameters result in stronger compression, and vice versa. 3576Values below 3.0 are not recommended, because audible distortion may appear. 3577 3578@item threshold, t 3579Set the target threshold value. This specifies the lowest permissible 3580magnitude level for the audio input which will be normalized. 3581If input frame volume is above this value frame will be normalized. 3582Otherwise frame may not be normalized at all. The default value is set 3583to 0, which means all input frames will be normalized. 3584This option is mostly useful if digital noise is not wanted to be amplified. 3585@end table 3586 3587@subsection Commands 3588 3589This filter supports the all above options as @ref{commands}. 3590 3591@section earwax 3592 3593Make audio easier to listen to on headphones. 3594 3595This filter adds `cues' to 44.1kHz stereo (i.e. audio CD format) audio 3596so that when listened to on headphones the stereo image is moved from 3597inside your head (standard for headphones) to outside and in front of 3598the listener (standard for speakers). 3599 3600Ported from SoX. 3601 3602@section equalizer 3603 3604Apply a two-pole peaking equalisation (EQ) filter. With this 3605filter, the signal-level at and around a selected frequency can 3606be increased or decreased, whilst (unlike bandpass and bandreject 3607filters) that at all other frequencies is unchanged. 3608 3609In order to produce complex equalisation curves, this filter can 3610be given several times, each with a different central frequency. 3611 3612The filter accepts the following options: 3613 3614@table @option 3615@item frequency, f 3616Set the filter's central frequency in Hz. 3617 3618@item width_type, t 3619Set method to specify band-width of filter. 3620@table @option 3621@item h 3622Hz 3623@item q 3624Q-Factor 3625@item o 3626octave 3627@item s 3628slope 3629@item k 3630kHz 3631@end table 3632 3633@item width, w 3634Specify the band-width of a filter in width_type units. 3635 3636@item gain, g 3637Set the required gain or attenuation in dB. 3638Beware of clipping when using a positive gain. 3639 3640@item mix, m 3641How much to use filtered signal in output. Default is 1. 3642Range is between 0 and 1. 3643 3644@item channels, c 3645Specify which channels to filter, by default all available are filtered. 3646 3647@item normalize, n 3648Normalize biquad coefficients, by default is disabled. 3649Enabling it will normalize magnitude response at DC to 0dB. 3650 3651@item transform, a 3652Set transform type of IIR filter. 3653@table @option 3654@item di 3655@item dii 3656@item tdii 3657@end table 3658@end table 3659 3660@subsection Examples 3661@itemize 3662@item 3663Attenuate 10 dB at 1000 Hz, with a bandwidth of 200 Hz: 3664@example 3665equalizer=f=1000:t=h:width=200:g=-10 3666@end example 3667 3668@item 3669Apply 2 dB gain at 1000 Hz with Q 1 and attenuate 5 dB at 100 Hz with Q 2: 3670@example 3671equalizer=f=1000:t=q:w=1:g=2,equalizer=f=100:t=q:w=2:g=-5 3672@end example 3673@end itemize 3674 3675@subsection Commands 3676 3677This filter supports the following commands: 3678@table @option 3679@item frequency, f 3680Change equalizer frequency. 3681Syntax for the command is : "@var{frequency}" 3682 3683@item width_type, t 3684Change equalizer width_type. 3685Syntax for the command is : "@var{width_type}" 3686 3687@item width, w 3688Change equalizer width. 3689Syntax for the command is : "@var{width}" 3690 3691@item gain, g 3692Change equalizer gain. 3693Syntax for the command is : "@var{gain}" 3694 3695@item mix, m 3696Change equalizer mix. 3697Syntax for the command is : "@var{mix}" 3698@end table 3699 3700@section extrastereo 3701 3702Linearly increases the difference between left and right channels which 3703adds some sort of "live" effect to playback. 3704 3705The filter accepts the following options: 3706 3707@table @option 3708@item m 3709Sets the difference coefficient (default: 2.5). 0.0 means mono sound 3710(average of both channels), with 1.0 sound will be unchanged, with 3711-1.0 left and right channels will be swapped. 3712 3713@item c 3714Enable clipping. By default is enabled. 3715@end table 3716 3717@subsection Commands 3718 3719This filter supports the all above options as @ref{commands}. 3720 3721@section firequalizer 3722Apply FIR Equalization using arbitrary frequency response. 3723 3724The filter accepts the following option: 3725 3726@table @option 3727@item gain 3728Set gain curve equation (in dB). The expression can contain variables: 3729@table @option 3730@item f 3731the evaluated frequency 3732@item sr 3733sample rate 3734@item ch 3735channel number, set to 0 when multichannels evaluation is disabled 3736@item chid 3737channel id, see libavutil/channel_layout.h, set to the first channel id when 3738multichannels evaluation is disabled 3739@item chs 3740number of channels 3741@item chlayout 3742channel_layout, see libavutil/channel_layout.h 3743 3744@end table 3745and functions: 3746@table @option 3747@item gain_interpolate(f) 3748interpolate gain on frequency f based on gain_entry 3749@item cubic_interpolate(f) 3750same as gain_interpolate, but smoother 3751@end table 3752This option is also available as command. Default is @code{gain_interpolate(f)}. 3753 3754@item gain_entry 3755Set gain entry for gain_interpolate function. The expression can 3756contain functions: 3757@table @option 3758@item entry(f, g) 3759store gain entry at frequency f with value g 3760@end table 3761This option is also available as command. 3762 3763@item delay 3764Set filter delay in seconds. Higher value means more accurate. 3765Default is @code{0.01}. 3766 3767@item accuracy 3768Set filter accuracy in Hz. Lower value means more accurate. 3769Default is @code{5}. 3770 3771@item wfunc 3772Set window function. Acceptable values are: 3773@table @option 3774@item rectangular 3775rectangular window, useful when gain curve is already smooth 3776@item hann 3777hann window (default) 3778@item hamming 3779hamming window 3780@item blackman 3781blackman window 3782@item nuttall3 37833-terms continuous 1st derivative nuttall window 3784@item mnuttall3 3785minimum 3-terms discontinuous nuttall window 3786@item nuttall 37874-terms continuous 1st derivative nuttall window 3788@item bnuttall 3789minimum 4-terms discontinuous nuttall (blackman-nuttall) window 3790@item bharris 3791blackman-harris window 3792@item tukey 3793tukey window 3794@end table 3795 3796@item fixed 3797If enabled, use fixed number of audio samples. This improves speed when 3798filtering with large delay. Default is disabled. 3799 3800@item multi 3801Enable multichannels evaluation on gain. Default is disabled. 3802 3803@item zero_phase 3804Enable zero phase mode by subtracting timestamp to compensate delay. 3805Default is disabled. 3806 3807@item scale 3808Set scale used by gain. Acceptable values are: 3809@table @option 3810@item linlin 3811linear frequency, linear gain 3812@item linlog 3813linear frequency, logarithmic (in dB) gain (default) 3814@item loglin 3815logarithmic (in octave scale where 20 Hz is 0) frequency, linear gain 3816@item loglog 3817logarithmic frequency, logarithmic gain 3818@end table 3819 3820@item dumpfile 3821Set file for dumping, suitable for gnuplot. 3822 3823@item dumpscale 3824Set scale for dumpfile. Acceptable values are same with scale option. 3825Default is linlog. 3826 3827@item fft2 3828Enable 2-channel convolution using complex FFT. This improves speed significantly. 3829Default is disabled. 3830 3831@item min_phase 3832Enable minimum phase impulse response. Default is disabled. 3833@end table 3834 3835@subsection Examples 3836@itemize 3837@item 3838lowpass at 1000 Hz: 3839@example 3840firequalizer=gain='if(lt(f,1000), 0, -INF)' 3841@end example 3842@item 3843lowpass at 1000 Hz with gain_entry: 3844@example 3845firequalizer=gain_entry='entry(1000,0); entry(1001, -INF)' 3846@end example 3847@item 3848custom equalization: 3849@example 3850firequalizer=gain_entry='entry(100,0); entry(400, -4); entry(1000, -6); entry(2000, 0)' 3851@end example 3852@item 3853higher delay with zero phase to compensate delay: 3854@example 3855firequalizer=delay=0.1:fixed=on:zero_phase=on 3856@end example 3857@item 3858lowpass on left channel, highpass on right channel: 3859@example 3860firequalizer=gain='if(eq(chid,1), gain_interpolate(f), if(eq(chid,2), gain_interpolate(1e6+f), 0))' 3861:gain_entry='entry(1000, 0); entry(1001,-INF); entry(1e6+1000,0)':multi=on 3862@end example 3863@end itemize 3864 3865@section flanger 3866Apply a flanging effect to the audio. 3867 3868The filter accepts the following options: 3869 3870@table @option 3871@item delay 3872Set base delay in milliseconds. Range from 0 to 30. Default value is 0. 3873 3874@item depth 3875Set added sweep delay in milliseconds. Range from 0 to 10. Default value is 2. 3876 3877@item regen 3878Set percentage regeneration (delayed signal feedback). Range from -95 to 95. 3879Default value is 0. 3880 3881@item width 3882Set percentage of delayed signal mixed with original. Range from 0 to 100. 3883Default value is 71. 3884 3885@item speed 3886Set sweeps per second (Hz). Range from 0.1 to 10. Default value is 0.5. 3887 3888@item shape 3889Set swept wave shape, can be @var{triangular} or @var{sinusoidal}. 3890Default value is @var{sinusoidal}. 3891 3892@item phase 3893Set swept wave percentage-shift for multi channel. Range from 0 to 100. 3894Default value is 25. 3895 3896@item interp 3897Set delay-line interpolation, @var{linear} or @var{quadratic}. 3898Default is @var{linear}. 3899@end table 3900 3901@section haas 3902Apply Haas effect to audio. 3903 3904Note that this makes most sense to apply on mono signals. 3905With this filter applied to mono signals it give some directionality and 3906stretches its stereo image. 3907 3908The filter accepts the following options: 3909 3910@table @option 3911@item level_in 3912Set input level. By default is @var{1}, or 0dB 3913 3914@item level_out 3915Set output level. By default is @var{1}, or 0dB. 3916 3917@item side_gain 3918Set gain applied to side part of signal. By default is @var{1}. 3919 3920@item middle_source 3921Set kind of middle source. Can be one of the following: 3922 3923@table @samp 3924@item left 3925Pick left channel. 3926 3927@item right 3928Pick right channel. 3929 3930@item mid 3931Pick middle part signal of stereo image. 3932 3933@item side 3934Pick side part signal of stereo image. 3935@end table 3936 3937@item middle_phase 3938Change middle phase. By default is disabled. 3939 3940@item left_delay 3941Set left channel delay. By default is @var{2.05} milliseconds. 3942 3943@item left_balance 3944Set left channel balance. By default is @var{-1}. 3945 3946@item left_gain 3947Set left channel gain. By default is @var{1}. 3948 3949@item left_phase 3950Change left phase. By default is disabled. 3951 3952@item right_delay 3953Set right channel delay. By defaults is @var{2.12} milliseconds. 3954 3955@item right_balance 3956Set right channel balance. By default is @var{1}. 3957 3958@item right_gain 3959Set right channel gain. By default is @var{1}. 3960 3961@item right_phase 3962Change right phase. By default is enabled. 3963@end table 3964 3965@section hdcd 3966 3967Decodes High Definition Compatible Digital (HDCD) data. A 16-bit PCM stream with 3968embedded HDCD codes is expanded into a 20-bit PCM stream. 3969 3970The filter supports the Peak Extend and Low-level Gain Adjustment features 3971of HDCD, and detects the Transient Filter flag. 3972 3973@example 3974ffmpeg -i HDCD16.flac -af hdcd OUT24.flac 3975@end example 3976 3977When using the filter with wav, note the default encoding for wav is 16-bit, 3978so the resulting 20-bit stream will be truncated back to 16-bit. Use something 3979like @command{-acodec pcm_s24le} after the filter to get 24-bit PCM output. 3980@example 3981ffmpeg -i HDCD16.wav -af hdcd OUT16.wav 3982ffmpeg -i HDCD16.wav -af hdcd -c:a pcm_s24le OUT24.wav 3983@end example 3984 3985The filter accepts the following options: 3986 3987@table @option 3988@item disable_autoconvert 3989Disable any automatic format conversion or resampling in the filter graph. 3990 3991@item process_stereo 3992Process the stereo channels together. If target_gain does not match between 3993channels, consider it invalid and use the last valid target_gain. 3994 3995@item cdt_ms 3996Set the code detect timer period in ms. 3997 3998@item force_pe 3999Always extend peaks above -3dBFS even if PE isn't signaled. 4000 4001@item analyze_mode 4002Replace audio with a solid tone and adjust the amplitude to signal some 4003specific aspect of the decoding process. The output file can be loaded in 4004an audio editor alongside the original to aid analysis. 4005 4006@code{analyze_mode=pe:force_pe=true} can be used to see all samples above the PE level. 4007 4008Modes are: 4009@table @samp 4010@item 0, off 4011Disabled 4012@item 1, lle 4013Gain adjustment level at each sample 4014@item 2, pe 4015Samples where peak extend occurs 4016@item 3, cdt 4017Samples where the code detect timer is active 4018@item 4, tgm 4019Samples where the target gain does not match between channels 4020@end table 4021@end table 4022 4023@section headphone 4024 4025Apply head-related transfer functions (HRTFs) to create virtual 4026loudspeakers around the user for binaural listening via headphones. 4027The HRIRs are provided via additional streams, for each channel 4028one stereo input stream is needed. 4029 4030The filter accepts the following options: 4031 4032@table @option 4033@item map 4034Set mapping of input streams for convolution. 4035The argument is a '|'-separated list of channel names in order as they 4036are given as additional stream inputs for filter. 4037This also specify number of input streams. Number of input streams 4038must be not less than number of channels in first stream plus one. 4039 4040@item gain 4041Set gain applied to audio. Value is in dB. Default is 0. 4042 4043@item type 4044Set processing type. Can be @var{time} or @var{freq}. @var{time} is 4045processing audio in time domain which is slow. 4046@var{freq} is processing audio in frequency domain which is fast. 4047Default is @var{freq}. 4048 4049@item lfe 4050Set custom gain for LFE channels. Value is in dB. Default is 0. 4051 4052@item size 4053Set size of frame in number of samples which will be processed at once. 4054Default value is @var{1024}. Allowed range is from 1024 to 96000. 4055 4056@item hrir 4057Set format of hrir stream. 4058Default value is @var{stereo}. Alternative value is @var{multich}. 4059If value is set to @var{stereo}, number of additional streams should 4060be greater or equal to number of input channels in first input stream. 4061Also each additional stream should have stereo number of channels. 4062If value is set to @var{multich}, number of additional streams should 4063be exactly one. Also number of input channels of additional stream 4064should be equal or greater than twice number of channels of first input 4065stream. 4066@end table 4067 4068@subsection Examples 4069 4070@itemize 4071@item 4072Full example using wav files as coefficients with amovie filters for 7.1 downmix, 4073each amovie filter use stereo file with IR coefficients as input. 4074The files give coefficients for each position of virtual loudspeaker: 4075@example 4076ffmpeg -i input.wav 4077-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" 4078output.wav 4079@end example 4080 4081@item 4082Full example using wav files as coefficients with amovie filters for 7.1 downmix, 4083but now in @var{multich} @var{hrir} format. 4084@example 4085ffmpeg -i input.wav -filter_complex "amovie=minp.wav[hrirs];[0:a][hrirs]headphone=map=FL|FR|FC|LFE|BL|BR|SL|SR:hrir=multich" 4086output.wav 4087@end example 4088@end itemize 4089 4090@section highpass 4091 4092Apply a high-pass filter with 3dB point frequency. 4093The filter can be either single-pole, or double-pole (the default). 4094The filter roll off at 6dB per pole per octave (20dB per pole per decade). 4095 4096The filter accepts the following options: 4097 4098@table @option 4099@item frequency, f 4100Set frequency in Hz. Default is 3000. 4101 4102@item poles, p 4103Set number of poles. Default is 2. 4104 4105@item width_type, t 4106Set method to specify band-width of filter. 4107@table @option 4108@item h 4109Hz 4110@item q 4111Q-Factor 4112@item o 4113octave 4114@item s 4115slope 4116@item k 4117kHz 4118@end table 4119 4120@item width, w 4121Specify the band-width of a filter in width_type units. 4122Applies only to double-pole filter. 4123The default is 0.707q and gives a Butterworth response. 4124 4125@item mix, m 4126How much to use filtered signal in output. Default is 1. 4127Range is between 0 and 1. 4128 4129@item channels, c 4130Specify which channels to filter, by default all available are filtered. 4131 4132@item normalize, n 4133Normalize biquad coefficients, by default is disabled. 4134Enabling it will normalize magnitude response at DC to 0dB. 4135 4136@item transform, a 4137Set transform type of IIR filter. 4138@table @option 4139@item di 4140@item dii 4141@item tdii 4142@end table 4143@end table 4144 4145@subsection Commands 4146 4147This filter supports the following commands: 4148@table @option 4149@item frequency, f 4150Change highpass frequency. 4151Syntax for the command is : "@var{frequency}" 4152 4153@item width_type, t 4154Change highpass width_type. 4155Syntax for the command is : "@var{width_type}" 4156 4157@item width, w 4158Change highpass width. 4159Syntax for the command is : "@var{width}" 4160 4161@item mix, m 4162Change highpass mix. 4163Syntax for the command is : "@var{mix}" 4164@end table 4165 4166@section join 4167 4168Join multiple input streams into one multi-channel stream. 4169 4170It accepts the following parameters: 4171@table @option 4172 4173@item inputs 4174The number of input streams. It defaults to 2. 4175 4176@item channel_layout 4177The desired output channel layout. It defaults to stereo. 4178 4179@item map 4180Map channels from inputs to output. The argument is a '|'-separated list of 4181mappings, each in the @code{@var{input_idx}.@var{in_channel}-@var{out_channel}} 4182form. @var{input_idx} is the 0-based index of the input stream. @var{in_channel} 4183can be either the name of the input channel (e.g. FL for front left) or its 4184index in the specified input stream. @var{out_channel} is the name of the output 4185channel. 4186@end table 4187 4188The filter will attempt to guess the mappings when they are not specified 4189explicitly. It does so by first trying to find an unused matching input channel 4190and if that fails it picks the first unused input channel. 4191 4192Join 3 inputs (with properly set channel layouts): 4193@example 4194ffmpeg -i INPUT1 -i INPUT2 -i INPUT3 -filter_complex join=inputs=3 OUTPUT 4195@end example 4196 4197Build a 5.1 output from 6 single-channel streams: 4198@example 4199ffmpeg -i fl -i fr -i fc -i sl -i sr -i lfe -filter_complex 4200'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' 4201out 4202@end example 4203 4204@section ladspa 4205 4206Load a LADSPA (Linux Audio Developer's Simple Plugin API) plugin. 4207 4208To enable compilation of this filter you need to configure FFmpeg with 4209@code{--enable-ladspa}. 4210 4211@table @option 4212@item file, f 4213Specifies the name of LADSPA plugin library to load. If the environment 4214variable @env{LADSPA_PATH} is defined, the LADSPA plugin is searched in 4215each one of the directories specified by the colon separated list in 4216@env{LADSPA_PATH}, otherwise in the standard LADSPA paths, which are in 4217this order: @file{HOME/.ladspa/lib/}, @file{/usr/local/lib/ladspa/}, 4218@file{/usr/lib/ladspa/}. 4219 4220@item plugin, p 4221Specifies the plugin within the library. Some libraries contain only 4222one plugin, but others contain many of them. If this is not set filter 4223will list all available plugins within the specified library. 4224 4225@item controls, c 4226Set the '|' separated list of controls which are zero or more floating point 4227values that determine the behavior of the loaded plugin (for example delay, 4228threshold or gain). 4229Controls need to be defined using the following syntax: 4230c0=@var{value0}|c1=@var{value1}|c2=@var{value2}|..., where 4231@var{valuei} is the value set on the @var{i}-th control. 4232Alternatively they can be also defined using the following syntax: 4233@var{value0}|@var{value1}|@var{value2}|..., where 4234@var{valuei} is the value set on the @var{i}-th control. 4235If @option{controls} is set to @code{help}, all available controls and 4236their valid ranges are printed. 4237 4238@item sample_rate, s 4239Specify the sample rate, default to 44100. Only used if plugin have 4240zero inputs. 4241 4242@item nb_samples, n 4243Set the number of samples per channel per each output frame, default 4244is 1024. Only used if plugin have zero inputs. 4245 4246@item duration, d 4247Set the minimum duration of the sourced audio. See 4248@ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils} 4249for the accepted syntax. 4250Note that the resulting duration may be greater than the specified duration, 4251as the generated audio is always cut at the end of a complete frame. 4252If not specified, or the expressed duration is negative, the audio is 4253supposed to be generated forever. 4254Only used if plugin have zero inputs. 4255 4256@item latency, l 4257Enable latency compensation, by default is disabled. 4258Only used if plugin have inputs. 4259@end table 4260 4261@subsection Examples 4262 4263@itemize 4264@item 4265List all available plugins within amp (LADSPA example plugin) library: 4266@example 4267ladspa=file=amp 4268@end example 4269 4270@item 4271List all available controls and their valid ranges for @code{vcf_notch} 4272plugin from @code{VCF} library: 4273@example 4274ladspa=f=vcf:p=vcf_notch:c=help 4275@end example 4276 4277@item 4278Simulate low quality audio equipment using @code{Computer Music Toolkit} (CMT) 4279plugin library: 4280@example 4281ladspa=file=cmt:plugin=lofi:controls=c0=22|c1=12|c2=12 4282@end example 4283 4284@item 4285Add reverberation to the audio using TAP-plugins 4286(Tom's Audio Processing plugins): 4287@example 4288ladspa=file=tap_reverb:tap_reverb 4289@end example 4290 4291@item 4292Generate white noise, with 0.2 amplitude: 4293@example 4294ladspa=file=cmt:noise_source_white:c=c0=.2 4295@end example 4296 4297@item 4298Generate 20 bpm clicks using plugin @code{C* Click - Metronome} from the 4299@code{C* Audio Plugin Suite} (CAPS) library: 4300@example 4301ladspa=file=caps:Click:c=c1=20' 4302@end example 4303 4304@item 4305Apply @code{C* Eq10X2 - Stereo 10-band equaliser} effect: 4306@example 4307ladspa=caps:Eq10X2:c=c0=-48|c9=-24|c3=12|c4=2 4308@end example 4309 4310@item 4311Increase volume by 20dB using fast lookahead limiter from Steve Harris 4312@code{SWH Plugins} collection: 4313@example 4314ladspa=fast_lookahead_limiter_1913:fastLookaheadLimiter:20|0|2 4315@end example 4316 4317@item 4318Attenuate low frequencies using Multiband EQ from Steve Harris 4319@code{SWH Plugins} collection: 4320@example 4321ladspa=mbeq_1197:mbeq:-24|-24|-24|0|0|0|0|0|0|0|0|0|0|0|0 4322@end example 4323 4324@item 4325Reduce stereo image using @code{Narrower} from the @code{C* Audio Plugin Suite} 4326(CAPS) library: 4327@example 4328ladspa=caps:Narrower 4329@end example 4330 4331@item 4332Another white noise, now using @code{C* Audio Plugin Suite} (CAPS) library: 4333@example 4334ladspa=caps:White:.2 4335@end example 4336 4337@item 4338Some fractal noise, using @code{C* Audio Plugin Suite} (CAPS) library: 4339@example 4340ladspa=caps:Fractal:c=c1=1 4341@end example 4342 4343@item 4344Dynamic volume normalization using @code{VLevel} plugin: 4345@example 4346ladspa=vlevel-ladspa:vlevel_mono 4347@end example 4348@end itemize 4349 4350@subsection Commands 4351 4352This filter supports the following commands: 4353@table @option 4354@item cN 4355Modify the @var{N}-th control value. 4356 4357If the specified value is not valid, it is ignored and prior one is kept. 4358@end table 4359 4360@section loudnorm 4361 4362EBU R128 loudness normalization. Includes both dynamic and linear normalization modes. 4363Support for both single pass (livestreams, files) and double pass (files) modes. 4364This algorithm can target IL, LRA, and maximum true peak. In dynamic mode, to accurately 4365detect true peaks, the audio stream will be upsampled to 192 kHz. 4366Use the @code{-ar} option or @code{aresample} filter to explicitly set an output sample rate. 4367 4368The filter accepts the following options: 4369 4370@table @option 4371@item I, i 4372Set integrated loudness target. 4373Range is -70.0 - -5.0. Default value is -24.0. 4374 4375@item LRA, lra 4376Set loudness range target. 4377Range is 1.0 - 20.0. Default value is 7.0. 4378 4379@item TP, tp 4380Set maximum true peak. 4381Range is -9.0 - +0.0. Default value is -2.0. 4382 4383@item measured_I, measured_i 4384Measured IL of input file. 4385Range is -99.0 - +0.0. 4386 4387@item measured_LRA, measured_lra 4388Measured LRA of input file. 4389Range is 0.0 - 99.0. 4390 4391@item measured_TP, measured_tp 4392Measured true peak of input file. 4393Range is -99.0 - +99.0. 4394 4395@item measured_thresh 4396Measured threshold of input file. 4397Range is -99.0 - +0.0. 4398 4399@item offset 4400Set offset gain. Gain is applied before the true-peak limiter. 4401Range is -99.0 - +99.0. Default is +0.0. 4402 4403@item linear 4404Normalize by linearly scaling the source audio. 4405@code{measured_I}, @code{measured_LRA}, @code{measured_TP}, 4406and @code{measured_thresh} must all be specified. Target LRA shouldn't 4407be lower than source LRA and the change in integrated loudness shouldn't 4408result in a true peak which exceeds the target TP. If any of these 4409conditions aren't met, normalization mode will revert to @var{dynamic}. 4410Options are @code{true} or @code{false}. Default is @code{true}. 4411 4412@item dual_mono 4413Treat mono input files as "dual-mono". If a mono file is intended for playback 4414on a stereo system, its EBU R128 measurement will be perceptually incorrect. 4415If set to @code{true}, this option will compensate for this effect. 4416Multi-channel input files are not affected by this option. 4417Options are true or false. Default is false. 4418 4419@item print_format 4420Set print format for stats. Options are summary, json, or none. 4421Default value is none. 4422@end table 4423 4424@section lowpass 4425 4426Apply a low-pass filter with 3dB point frequency. 4427The filter can be either single-pole or double-pole (the default). 4428The filter roll off at 6dB per pole per octave (20dB per pole per decade). 4429 4430The filter accepts the following options: 4431 4432@table @option 4433@item frequency, f 4434Set frequency in Hz. Default is 500. 4435 4436@item poles, p 4437Set number of poles. Default is 2. 4438 4439@item width_type, t 4440Set method to specify band-width of filter. 4441@table @option 4442@item h 4443Hz 4444@item q 4445Q-Factor 4446@item o 4447octave 4448@item s 4449slope 4450@item k 4451kHz 4452@end table 4453 4454@item width, w 4455Specify the band-width of a filter in width_type units. 4456Applies only to double-pole filter. 4457The default is 0.707q and gives a Butterworth response. 4458 4459@item mix, m 4460How much to use filtered signal in output. Default is 1. 4461Range is between 0 and 1. 4462 4463@item channels, c 4464Specify which channels to filter, by default all available are filtered. 4465 4466@item normalize, n 4467Normalize biquad coefficients, by default is disabled. 4468Enabling it will normalize magnitude response at DC to 0dB. 4469 4470@item transform, a 4471Set transform type of IIR filter. 4472@table @option 4473@item di 4474@item dii 4475@item tdii 4476@end table 4477@end table 4478 4479@subsection Examples 4480@itemize 4481@item 4482Lowpass only LFE channel, it LFE is not present it does nothing: 4483@example 4484lowpass=c=LFE 4485@end example 4486@end itemize 4487 4488@subsection Commands 4489 4490This filter supports the following commands: 4491@table @option 4492@item frequency, f 4493Change lowpass frequency. 4494Syntax for the command is : "@var{frequency}" 4495 4496@item width_type, t 4497Change lowpass width_type. 4498Syntax for the command is : "@var{width_type}" 4499 4500@item width, w 4501Change lowpass width. 4502Syntax for the command is : "@var{width}" 4503 4504@item mix, m 4505Change lowpass mix. 4506Syntax for the command is : "@var{mix}" 4507@end table 4508 4509@section lv2 4510 4511Load a LV2 (LADSPA Version 2) plugin. 4512 4513To enable compilation of this filter you need to configure FFmpeg with 4514@code{--enable-lv2}. 4515 4516@table @option 4517@item plugin, p 4518Specifies the plugin URI. You may need to escape ':'. 4519 4520@item controls, c 4521Set the '|' separated list of controls which are zero or more floating point 4522values that determine the behavior of the loaded plugin (for example delay, 4523threshold or gain). 4524If @option{controls} is set to @code{help}, all available controls and 4525their valid ranges are printed. 4526 4527@item sample_rate, s 4528Specify the sample rate, default to 44100. Only used if plugin have 4529zero inputs. 4530 4531@item nb_samples, n 4532Set the number of samples per channel per each output frame, default 4533is 1024. Only used if plugin have zero inputs. 4534 4535@item duration, d 4536Set the minimum duration of the sourced audio. See 4537@ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils} 4538for the accepted syntax. 4539Note that the resulting duration may be greater than the specified duration, 4540as the generated audio is always cut at the end of a complete frame. 4541If not specified, or the expressed duration is negative, the audio is 4542supposed to be generated forever. 4543Only used if plugin have zero inputs. 4544@end table 4545 4546@subsection Examples 4547 4548@itemize 4549@item 4550Apply bass enhancer plugin from Calf: 4551@example 4552lv2=p=http\\\\://calf.sourceforge.net/plugins/BassEnhancer:c=amount=2 4553@end example 4554 4555@item 4556Apply vinyl plugin from Calf: 4557@example 4558lv2=p=http\\\\://calf.sourceforge.net/plugins/Vinyl:c=drone=0.2|aging=0.5 4559@end example 4560 4561@item 4562Apply bit crusher plugin from ArtyFX: 4563@example 4564lv2=p=http\\\\://www.openavproductions.com/artyfx#bitta:c=crush=0.3 4565@end example 4566@end itemize 4567 4568@section mcompand 4569Multiband Compress or expand the audio's dynamic range. 4570 4571The input audio is divided into bands using 4th order Linkwitz-Riley IIRs. 4572This is akin to the crossover of a loudspeaker, and results in flat frequency 4573response when absent compander action. 4574 4575It accepts the following parameters: 4576 4577@table @option 4578@item args 4579This option syntax is: 4580attack,decay,[attack,decay..] soft-knee points crossover_frequency [delay [initial_volume [gain]]] | attack,decay ... 4581For explanation of each item refer to compand filter documentation. 4582@end table 4583 4584@anchor{pan} 4585@section pan 4586 4587Mix channels with specific gain levels. The filter accepts the output 4588channel layout followed by a set of channels definitions. 4589 4590This filter is also designed to efficiently remap the channels of an audio 4591stream. 4592 4593The filter accepts parameters of the form: 4594"@var{l}|@var{outdef}|@var{outdef}|..." 4595 4596@table @option 4597@item l 4598output channel layout or number of channels 4599 4600@item outdef 4601output channel specification, of the form: 4602"@var{out_name}=[@var{gain}*]@var{in_name}[(+-)[@var{gain}*]@var{in_name}...]" 4603 4604@item out_name 4605output channel to define, either a channel name (FL, FR, etc.) or a channel 4606number (c0, c1, etc.) 4607 4608@item gain 4609multiplicative coefficient for the channel, 1 leaving the volume unchanged 4610 4611@item in_name 4612input channel to use, see out_name for details; it is not possible to mix 4613named and numbered input channels 4614@end table 4615 4616If the `=' in a channel specification is replaced by `<', then the gains for 4617that specification will be renormalized so that the total is 1, thus 4618avoiding clipping noise. 4619 4620@subsection Mixing examples 4621 4622For example, if you want to down-mix from stereo to mono, but with a bigger 4623factor for the left channel: 4624@example 4625pan=1c|c0=0.9*c0+0.1*c1 4626@end example 4627 4628A customized down-mix to stereo that works automatically for 3-, 4-, 5- and 46297-channels surround: 4630@example 4631pan=stereo| FL < FL + 0.5*FC + 0.6*BL + 0.6*SL | FR < FR + 0.5*FC + 0.6*BR + 0.6*SR 4632@end example 4633 4634Note that @command{ffmpeg} integrates a default down-mix (and up-mix) system 4635that should be preferred (see "-ac" option) unless you have very specific 4636needs. 4637 4638@subsection Remapping examples 4639 4640The channel remapping will be effective if, and only if: 4641 4642@itemize 4643@item gain coefficients are zeroes or ones, 4644@item only one input per channel output, 4645@end itemize 4646 4647If all these conditions are satisfied, the filter will notify the user ("Pure 4648channel mapping detected"), and use an optimized and lossless method to do the 4649remapping. 4650 4651For example, if you have a 5.1 source and want a stereo audio stream by 4652dropping the extra channels: 4653@example 4654pan="stereo| c0=FL | c1=FR" 4655@end example 4656 4657Given the same source, you can also switch front left and front right channels 4658and keep the input channel layout: 4659@example 4660pan="5.1| c0=c1 | c1=c0 | c2=c2 | c3=c3 | c4=c4 | c5=c5" 4661@end example 4662 4663If the input is a stereo audio stream, you can mute the front left channel (and 4664still keep the stereo channel layout) with: 4665@example 4666pan="stereo|c1=c1" 4667@end example 4668 4669Still with a stereo audio stream input, you can copy the right channel in both 4670front left and right: 4671@example 4672pan="stereo| c0=FR | c1=FR" 4673@end example 4674 4675@section replaygain 4676 4677ReplayGain scanner filter. This filter takes an audio stream as an input and 4678outputs it unchanged. 4679At end of filtering it displays @code{track_gain} and @code{track_peak}. 4680 4681@section resample 4682 4683Convert the audio sample format, sample rate and channel layout. It is 4684not meant to be used directly. 4685 4686@section rubberband 4687Apply time-stretching and pitch-shifting with librubberband. 4688 4689To enable compilation of this filter, you need to configure FFmpeg with 4690@code{--enable-librubberband}. 4691 4692The filter accepts the following options: 4693 4694@table @option 4695@item tempo 4696Set tempo scale factor. 4697 4698@item pitch 4699Set pitch scale factor. 4700 4701@item transients 4702Set transients detector. 4703Possible values are: 4704@table @var 4705@item crisp 4706@item mixed 4707@item smooth 4708@end table 4709 4710@item detector 4711Set detector. 4712Possible values are: 4713@table @var 4714@item compound 4715@item percussive 4716@item soft 4717@end table 4718 4719@item phase 4720Set phase. 4721Possible values are: 4722@table @var 4723@item laminar 4724@item independent 4725@end table 4726 4727@item window 4728Set processing window size. 4729Possible values are: 4730@table @var 4731@item standard 4732@item short 4733@item long 4734@end table 4735 4736@item smoothing 4737Set smoothing. 4738Possible values are: 4739@table @var 4740@item off 4741@item on 4742@end table 4743 4744@item formant 4745Enable formant preservation when shift pitching. 4746Possible values are: 4747@table @var 4748@item shifted 4749@item preserved 4750@end table 4751 4752@item pitchq 4753Set pitch quality. 4754Possible values are: 4755@table @var 4756@item quality 4757@item speed 4758@item consistency 4759@end table 4760 4761@item channels 4762Set channels. 4763Possible values are: 4764@table @var 4765@item apart 4766@item together 4767@end table 4768@end table 4769 4770@subsection Commands 4771 4772This filter supports the following commands: 4773@table @option 4774@item tempo 4775Change filter tempo scale factor. 4776Syntax for the command is : "@var{tempo}" 4777 4778@item pitch 4779Change filter pitch scale factor. 4780Syntax for the command is : "@var{pitch}" 4781@end table 4782 4783@section sidechaincompress 4784 4785This filter acts like normal compressor but has the ability to compress 4786detected signal using second input signal. 4787It needs two input streams and returns one output stream. 4788First input stream will be processed depending on second stream signal. 4789The filtered signal then can be filtered with other filters in later stages of 4790processing. See @ref{pan} and @ref{amerge} filter. 4791 4792The filter accepts the following options: 4793 4794@table @option 4795@item level_in 4796Set input gain. Default is 1. Range is between 0.015625 and 64. 4797 4798@item mode 4799Set mode of compressor operation. Can be @code{upward} or @code{downward}. 4800Default is @code{downward}. 4801 4802@item threshold 4803If a signal of second stream raises above this level it will affect the gain 4804reduction of first stream. 4805By default is 0.125. Range is between 0.00097563 and 1. 4806 4807@item ratio 4808Set a ratio about which the signal is reduced. 1:2 means that if the level 4809raised 4dB above the threshold, it will be only 2dB above after the reduction. 4810Default is 2. Range is between 1 and 20. 4811 4812@item attack 4813Amount of milliseconds the signal has to rise above the threshold before gain 4814reduction starts. Default is 20. Range is between 0.01 and 2000. 4815 4816@item release 4817Amount of milliseconds the signal has to fall below the threshold before 4818reduction is decreased again. Default is 250. Range is between 0.01 and 9000. 4819 4820@item makeup 4821Set the amount by how much signal will be amplified after processing. 4822Default is 1. Range is from 1 to 64. 4823 4824@item knee 4825Curve the sharp knee around the threshold to enter gain reduction more softly. 4826Default is 2.82843. Range is between 1 and 8. 4827 4828@item link 4829Choose if the @code{average} level between all channels of side-chain stream 4830or the louder(@code{maximum}) channel of side-chain stream affects the 4831reduction. Default is @code{average}. 4832 4833@item detection 4834Should the exact signal be taken in case of @code{peak} or an RMS one in case 4835of @code{rms}. Default is @code{rms} which is mainly smoother. 4836 4837@item level_sc 4838Set sidechain gain. Default is 1. Range is between 0.015625 and 64. 4839 4840@item mix 4841How much to use compressed signal in output. Default is 1. 4842Range is between 0 and 1. 4843@end table 4844 4845@subsection Commands 4846 4847This filter supports the all above options as @ref{commands}. 4848 4849@subsection Examples 4850 4851@itemize 4852@item 4853Full ffmpeg example taking 2 audio inputs, 1st input to be compressed 4854depending on the signal of 2nd input and later compressed signal to be 4855merged with 2nd input: 4856@example 4857ffmpeg -i main.flac -i sidechain.flac -filter_complex "[1:a]asplit=2[sc][mix];[0:a][sc]sidechaincompress[compr];[compr][mix]amerge" 4858@end example 4859@end itemize 4860 4861@section sidechaingate 4862 4863A sidechain gate acts like a normal (wideband) gate but has the ability to 4864filter the detected signal before sending it to the gain reduction stage. 4865Normally a gate uses the full range signal to detect a level above the 4866threshold. 4867For example: If you cut all lower frequencies from your sidechain signal 4868the gate will decrease the volume of your track only if not enough highs 4869appear. With this technique you are able to reduce the resonation of a 4870natural drum or remove "rumbling" of muted strokes from a heavily distorted 4871guitar. 4872It needs two input streams and returns one output stream. 4873First input stream will be processed depending on second stream signal. 4874 4875The filter accepts the following options: 4876 4877@table @option 4878@item level_in 4879Set input level before filtering. 4880Default is 1. Allowed range is from 0.015625 to 64. 4881 4882@item mode 4883Set the mode of operation. Can be @code{upward} or @code{downward}. 4884Default is @code{downward}. If set to @code{upward} mode, higher parts of signal 4885will be amplified, expanding dynamic range in upward direction. 4886Otherwise, in case of @code{downward} lower parts of signal will be reduced. 4887 4888@item range 4889Set the level of gain reduction when the signal is below the threshold. 4890Default is 0.06125. Allowed range is from 0 to 1. 4891Setting this to 0 disables reduction and then filter behaves like expander. 4892 4893@item threshold 4894If a signal rises above this level the gain reduction is released. 4895Default is 0.125. Allowed range is from 0 to 1. 4896 4897@item ratio 4898Set a ratio about which the signal is reduced. 4899Default is 2. Allowed range is from 1 to 9000. 4900 4901@item attack 4902Amount of milliseconds the signal has to rise above the threshold before gain 4903reduction stops. 4904Default is 20 milliseconds. Allowed range is from 0.01 to 9000. 4905 4906@item release 4907Amount of milliseconds the signal has to fall below the threshold before the 4908reduction is increased again. Default is 250 milliseconds. 4909Allowed range is from 0.01 to 9000. 4910 4911@item makeup 4912Set amount of amplification of signal after processing. 4913Default is 1. Allowed range is from 1 to 64. 4914 4915@item knee 4916Curve the sharp knee around the threshold to enter gain reduction more softly. 4917Default is 2.828427125. Allowed range is from 1 to 8. 4918 4919@item detection 4920Choose if exact signal should be taken for detection or an RMS like one. 4921Default is rms. Can be peak or rms. 4922 4923@item link 4924Choose if the average level between all channels or the louder channel affects 4925the reduction. 4926Default is average. Can be average or maximum. 4927 4928@item level_sc 4929Set sidechain gain. Default is 1. Range is from 0.015625 to 64. 4930@end table 4931 4932@section silencedetect 4933 4934Detect silence in an audio stream. 4935 4936This filter logs a message when it detects that the input audio volume is less 4937or equal to a noise tolerance value for a duration greater or equal to the 4938minimum detected noise duration. 4939 4940The printed times and duration are expressed in seconds. The 4941@code{lavfi.silence_start} or @code{lavfi.silence_start.X} metadata key 4942is set on the first frame whose timestamp equals or exceeds the detection 4943duration and it contains the timestamp of the first frame of the silence. 4944 4945The @code{lavfi.silence_duration} or @code{lavfi.silence_duration.X} 4946and @code{lavfi.silence_end} or @code{lavfi.silence_end.X} metadata 4947keys are set on the first frame after the silence. If @option{mono} is 4948enabled, and each channel is evaluated separately, the @code{.X} 4949suffixed keys are used, and @code{X} corresponds to the channel number. 4950 4951The filter accepts the following options: 4952 4953@table @option 4954@item noise, n 4955Set noise tolerance. Can be specified in dB (in case "dB" is appended to the 4956specified value) or amplitude ratio. Default is -60dB, or 0.001. 4957 4958@item duration, d 4959Set silence duration until notification (default is 2 seconds). See 4960@ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils} 4961for the accepted syntax. 4962 4963@item mono, m 4964Process each channel separately, instead of combined. By default is disabled. 4965@end table 4966 4967@subsection Examples 4968 4969@itemize 4970@item 4971Detect 5 seconds of silence with -50dB noise tolerance: 4972@example 4973silencedetect=n=-50dB:d=5 4974@end example 4975 4976@item 4977Complete example with @command{ffmpeg} to detect silence with 0.0001 noise 4978tolerance in @file{silence.mp3}: 4979@example 4980ffmpeg -i silence.mp3 -af silencedetect=noise=0.0001 -f null - 4981@end example 4982@end itemize 4983 4984@section silenceremove 4985 4986Remove silence from the beginning, middle or end of the audio. 4987 4988The filter accepts the following options: 4989 4990@table @option 4991@item start_periods 4992This value is used to indicate if audio should be trimmed at beginning of 4993the audio. A value of zero indicates no silence should be trimmed from the 4994beginning. When specifying a non-zero value, it trims audio up until it 4995finds non-silence. Normally, when trimming silence from beginning of audio 4996the @var{start_periods} will be @code{1} but it can be increased to higher 4997values to trim all audio up to specific count of non-silence periods. 4998Default value is @code{0}. 4999 5000@item start_duration 5001Specify the amount of time that non-silence must be detected before it stops 5002trimming audio. By increasing the duration, bursts of noises can be treated 5003as silence and trimmed off. Default value is @code{0}. 5004 5005@item start_threshold 5006This indicates what sample value should be treated as silence. For digital 5007audio, a value of @code{0} may be fine but for audio recorded from analog, 5008you may wish to increase the value to account for background noise. 5009Can be specified in dB (in case "dB" is appended to the specified value) 5010or amplitude ratio. Default value is @code{0}. 5011 5012@item start_silence 5013Specify max duration of silence at beginning that will be kept after 5014trimming. Default is 0, which is equal to trimming all samples detected 5015as silence. 5016 5017@item start_mode 5018Specify mode of detection of silence end in start of multi-channel audio. 5019Can be @var{any} or @var{all}. Default is @var{any}. 5020With @var{any}, any sample that is detected as non-silence will cause 5021stopped trimming of silence. 5022With @var{all}, only if all channels are detected as non-silence will cause 5023stopped trimming of silence. 5024 5025@item stop_periods 5026Set the count for trimming silence from the end of audio. 5027To remove silence from the middle of a file, specify a @var{stop_periods} 5028that is negative. This value is then treated as a positive value and is 5029used to indicate the effect should restart processing as specified by 5030@var{start_periods}, making it suitable for removing periods of silence 5031in the middle of the audio. 5032Default value is @code{0}. 5033 5034@item stop_duration 5035Specify a duration of silence that must exist before audio is not copied any 5036more. By specifying a higher duration, silence that is wanted can be left in 5037the audio. 5038Default value is @code{0}. 5039 5040@item stop_threshold 5041This is the same as @option{start_threshold} but for trimming silence from 5042the end of audio. 5043Can be specified in dB (in case "dB" is appended to the specified value) 5044or amplitude ratio. Default value is @code{0}. 5045 5046@item stop_silence 5047Specify max duration of silence at end that will be kept after 5048trimming. Default is 0, which is equal to trimming all samples detected 5049as silence. 5050 5051@item stop_mode 5052Specify mode of detection of silence start in end of multi-channel audio. 5053Can be @var{any} or @var{all}. Default is @var{any}. 5054With @var{any}, any sample that is detected as non-silence will cause 5055stopped trimming of silence. 5056With @var{all}, only if all channels are detected as non-silence will cause 5057stopped trimming of silence. 5058 5059@item detection 5060Set how is silence detected. Can be @code{rms} or @code{peak}. Second is faster 5061and works better with digital silence which is exactly 0. 5062Default value is @code{rms}. 5063 5064@item window 5065Set duration in number of seconds used to calculate size of window in number 5066of samples for detecting silence. 5067Default value is @code{0.02}. Allowed range is from @code{0} to @code{10}. 5068@end table 5069 5070@subsection Examples 5071 5072@itemize 5073@item 5074The following example shows how this filter can be used to start a recording 5075that does not contain the delay at the start which usually occurs between 5076pressing the record button and the start of the performance: 5077@example 5078silenceremove=start_periods=1:start_duration=5:start_threshold=0.02 5079@end example 5080 5081@item 5082Trim all silence encountered from beginning to end where there is more than 1 5083second of silence in audio: 5084@example 5085silenceremove=stop_periods=-1:stop_duration=1:stop_threshold=-90dB 5086@end example 5087 5088@item 5089Trim all digital silence samples, using peak detection, from beginning to end 5090where there is more than 0 samples of digital silence in audio and digital 5091silence is detected in all channels at same positions in stream: 5092@example 5093silenceremove=window=0:detection=peak:stop_mode=all:start_mode=all:stop_periods=-1:stop_threshold=0 5094@end example 5095@end itemize 5096 5097@section sofalizer 5098 5099SOFAlizer uses head-related transfer functions (HRTFs) to create virtual 5100loudspeakers around the user for binaural listening via headphones (audio 5101formats up to 9 channels supported). 5102The HRTFs are stored in SOFA files (see @url{http://www.sofacoustics.org/} for a database). 5103SOFAlizer is developed at the Acoustics Research Institute (ARI) of the 5104Austrian Academy of Sciences. 5105 5106To enable compilation of this filter you need to configure FFmpeg with 5107@code{--enable-libmysofa}. 5108 5109The filter accepts the following options: 5110 5111@table @option 5112@item sofa 5113Set the SOFA file used for rendering. 5114 5115@item gain 5116Set gain applied to audio. Value is in dB. Default is 0. 5117 5118@item rotation 5119Set rotation of virtual loudspeakers in deg. Default is 0. 5120 5121@item elevation 5122Set elevation of virtual speakers in deg. Default is 0. 5123 5124@item radius 5125Set distance in meters between loudspeakers and the listener with near-field 5126HRTFs. Default is 1. 5127 5128@item type 5129Set processing type. Can be @var{time} or @var{freq}. @var{time} is 5130processing audio in time domain which is slow. 5131@var{freq} is processing audio in frequency domain which is fast. 5132Default is @var{freq}. 5133 5134@item speakers 5135Set custom positions of virtual loudspeakers. Syntax for this option is: 5136<CH> <AZIM> <ELEV>[|<CH> <AZIM> <ELEV>|...]. 5137Each virtual loudspeaker is described with short channel name following with 5138azimuth and elevation in degrees. 5139Each virtual loudspeaker description is separated by '|'. 5140For example to override front left and front right channel positions use: 5141'speakers=FL 45 15|FR 345 15'. 5142Descriptions with unrecognised channel names are ignored. 5143 5144@item lfegain 5145Set custom gain for LFE channels. Value is in dB. Default is 0. 5146 5147@item framesize 5148Set custom frame size in number of samples. Default is 1024. 5149Allowed range is from 1024 to 96000. Only used if option @samp{type} 5150is set to @var{freq}. 5151 5152@item normalize 5153Should all IRs be normalized upon importing SOFA file. 5154By default is enabled. 5155 5156@item interpolate 5157Should nearest IRs be interpolated with neighbor IRs if exact position 5158does not match. By default is disabled. 5159 5160@item minphase 5161Minphase all IRs upon loading of SOFA file. By default is disabled. 5162 5163@item anglestep 5164Set neighbor search angle step. Only used if option @var{interpolate} is enabled. 5165 5166@item radstep 5167Set neighbor search radius step. Only used if option @var{interpolate} is enabled. 5168@end table 5169 5170@subsection Examples 5171 5172@itemize 5173@item 5174Using ClubFritz6 sofa file: 5175@example 5176sofalizer=sofa=/path/to/ClubFritz6.sofa:type=freq:radius=1 5177@end example 5178 5179@item 5180Using ClubFritz12 sofa file and bigger radius with small rotation: 5181@example 5182sofalizer=sofa=/path/to/ClubFritz12.sofa:type=freq:radius=2:rotation=5 5183@end example 5184 5185@item 5186Similar as above but with custom speaker positions for front left, front right, back left and back right 5187and also with custom gain: 5188@example 5189"sofalizer=sofa=/path/to/ClubFritz6.sofa:type=freq:radius=2:speakers=FL 45|FR 315|BL 135|BR 225:gain=28" 5190@end example 5191@end itemize 5192 5193@section stereotools 5194 5195This filter has some handy utilities to manage stereo signals, for converting 5196M/S stereo recordings to L/R signal while having control over the parameters 5197or spreading the stereo image of master track. 5198 5199The filter accepts the following options: 5200 5201@table @option 5202@item level_in 5203Set input level before filtering for both channels. Defaults is 1. 5204Allowed range is from 0.015625 to 64. 5205 5206@item level_out 5207Set output level after filtering for both channels. Defaults is 1. 5208Allowed range is from 0.015625 to 64. 5209 5210@item balance_in 5211Set input balance between both channels. Default is 0. 5212Allowed range is from -1 to 1. 5213 5214@item balance_out 5215Set output balance between both channels. Default is 0. 5216Allowed range is from -1 to 1. 5217 5218@item softclip 5219Enable softclipping. Results in analog distortion instead of harsh digital 0dB 5220clipping. Disabled by default. 5221 5222@item mutel 5223Mute the left channel. Disabled by default. 5224 5225@item muter 5226Mute the right channel. Disabled by default. 5227 5228@item phasel 5229Change the phase of the left channel. Disabled by default. 5230 5231@item phaser 5232Change the phase of the right channel. Disabled by default. 5233 5234@item mode 5235Set stereo mode. Available values are: 5236 5237@table @samp 5238@item lr>lr 5239Left/Right to Left/Right, this is default. 5240 5241@item lr>ms 5242Left/Right to Mid/Side. 5243 5244@item ms>lr 5245Mid/Side to Left/Right. 5246 5247@item lr>ll 5248Left/Right to Left/Left. 5249 5250@item lr>rr 5251Left/Right to Right/Right. 5252 5253@item lr>l+r 5254Left/Right to Left + Right. 5255 5256@item lr>rl 5257Left/Right to Right/Left. 5258 5259@item ms>ll 5260Mid/Side to Left/Left. 5261 5262@item ms>rr 5263Mid/Side to Right/Right. 5264@end table 5265 5266@item slev 5267Set level of side signal. Default is 1. 5268Allowed range is from 0.015625 to 64. 5269 5270@item sbal 5271Set balance of side signal. Default is 0. 5272Allowed range is from -1 to 1. 5273 5274@item mlev 5275Set level of the middle signal. Default is 1. 5276Allowed range is from 0.015625 to 64. 5277 5278@item mpan 5279Set middle signal pan. Default is 0. Allowed range is from -1 to 1. 5280 5281@item base 5282Set stereo base between mono and inversed channels. Default is 0. 5283Allowed range is from -1 to 1. 5284 5285@item delay 5286Set delay in milliseconds how much to delay left from right channel and 5287vice versa. Default is 0. Allowed range is from -20 to 20. 5288 5289@item sclevel 5290Set S/C level. Default is 1. Allowed range is from 1 to 100. 5291 5292@item phase 5293Set the stereo phase in degrees. Default is 0. Allowed range is from 0 to 360. 5294 5295@item bmode_in, bmode_out 5296Set balance mode for balance_in/balance_out option. 5297 5298Can be one of the following: 5299 5300@table @samp 5301@item balance 5302Classic balance mode. Attenuate one channel at time. 5303Gain is raised up to 1. 5304 5305@item amplitude 5306Similar as classic mode above but gain is raised up to 2. 5307 5308@item power 5309Equal power distribution, from -6dB to +6dB range. 5310@end table 5311@end table 5312 5313@subsection Examples 5314 5315@itemize 5316@item 5317Apply karaoke like effect: 5318@example 5319stereotools=mlev=0.015625 5320@end example 5321 5322@item 5323Convert M/S signal to L/R: 5324@example 5325"stereotools=mode=ms>lr" 5326@end example 5327@end itemize 5328 5329@section stereowiden 5330 5331This filter enhance the stereo effect by suppressing signal common to both 5332channels and by delaying the signal of left into right and vice versa, 5333thereby widening the stereo effect. 5334 5335The filter accepts the following options: 5336 5337@table @option 5338@item delay 5339Time in milliseconds of the delay of left signal into right and vice versa. 5340Default is 20 milliseconds. 5341 5342@item feedback 5343Amount of gain in delayed signal into right and vice versa. Gives a delay 5344effect of left signal in right output and vice versa which gives widening 5345effect. Default is 0.3. 5346 5347@item crossfeed 5348Cross feed of left into right with inverted phase. This helps in suppressing 5349the mono. If the value is 1 it will cancel all the signal common to both 5350channels. Default is 0.3. 5351 5352@item drymix 5353Set level of input signal of original channel. Default is 0.8. 5354@end table 5355 5356@subsection Commands 5357 5358This filter supports the all above options except @code{delay} as @ref{commands}. 5359 5360@section superequalizer 5361Apply 18 band equalizer. 5362 5363The filter accepts the following options: 5364@table @option 5365@item 1b 5366Set 65Hz band gain. 5367@item 2b 5368Set 92Hz band gain. 5369@item 3b 5370Set 131Hz band gain. 5371@item 4b 5372Set 185Hz band gain. 5373@item 5b 5374Set 262Hz band gain. 5375@item 6b 5376Set 370Hz band gain. 5377@item 7b 5378Set 523Hz band gain. 5379@item 8b 5380Set 740Hz band gain. 5381@item 9b 5382Set 1047Hz band gain. 5383@item 10b 5384Set 1480Hz band gain. 5385@item 11b 5386Set 2093Hz band gain. 5387@item 12b 5388Set 2960Hz band gain. 5389@item 13b 5390Set 4186Hz band gain. 5391@item 14b 5392Set 5920Hz band gain. 5393@item 15b 5394Set 8372Hz band gain. 5395@item 16b 5396Set 11840Hz band gain. 5397@item 17b 5398Set 16744Hz band gain. 5399@item 18b 5400Set 20000Hz band gain. 5401@end table 5402 5403@section surround 5404Apply audio surround upmix filter. 5405 5406This filter allows to produce multichannel output from audio stream. 5407 5408The filter accepts the following options: 5409 5410@table @option 5411@item chl_out 5412Set output channel layout. By default, this is @var{5.1}. 5413 5414See @ref{channel layout syntax,,the Channel Layout section in the ffmpeg-utils(1) manual,ffmpeg-utils} 5415for the required syntax. 5416 5417@item chl_in 5418Set input channel layout. By default, this is @var{stereo}. 5419 5420See @ref{channel layout syntax,,the Channel Layout section in the ffmpeg-utils(1) manual,ffmpeg-utils} 5421for the required syntax. 5422 5423@item level_in 5424Set input volume level. By default, this is @var{1}. 5425 5426@item level_out 5427Set output volume level. By default, this is @var{1}. 5428 5429@item lfe 5430Enable LFE channel output if output channel layout has it. By default, this is enabled. 5431 5432@item lfe_low 5433Set LFE low cut off frequency. By default, this is @var{128} Hz. 5434 5435@item lfe_high 5436Set LFE high cut off frequency. By default, this is @var{256} Hz. 5437 5438@item lfe_mode 5439Set LFE mode, can be @var{add} or @var{sub}. Default is @var{add}. 5440In @var{add} mode, LFE channel is created from input audio and added to output. 5441In @var{sub} mode, LFE channel is created from input audio and added to output but 5442also all non-LFE output channels are subtracted with output LFE channel. 5443 5444@item angle 5445Set angle of stereo surround transform, Allowed range is from @var{0} to @var{360}. 5446Default is @var{90}. 5447 5448@item fc_in 5449Set front center input volume. By default, this is @var{1}. 5450 5451@item fc_out 5452Set front center output volume. By default, this is @var{1}. 5453 5454@item fl_in 5455Set front left input volume. By default, this is @var{1}. 5456 5457@item fl_out 5458Set front left output volume. By default, this is @var{1}. 5459 5460@item fr_in 5461Set front right input volume. By default, this is @var{1}. 5462 5463@item fr_out 5464Set front right output volume. By default, this is @var{1}. 5465 5466@item sl_in 5467Set side left input volume. By default, this is @var{1}. 5468 5469@item sl_out 5470Set side left output volume. By default, this is @var{1}. 5471 5472@item sr_in 5473Set side right input volume. By default, this is @var{1}. 5474 5475@item sr_out 5476Set side right output volume. By default, this is @var{1}. 5477 5478@item bl_in 5479Set back left input volume. By default, this is @var{1}. 5480 5481@item bl_out 5482Set back left output volume. By default, this is @var{1}. 5483 5484@item br_in 5485Set back right input volume. By default, this is @var{1}. 5486 5487@item br_out 5488Set back right output volume. By default, this is @var{1}. 5489 5490@item bc_in 5491Set back center input volume. By default, this is @var{1}. 5492 5493@item bc_out 5494Set back center output volume. By default, this is @var{1}. 5495 5496@item lfe_in 5497Set LFE input volume. By default, this is @var{1}. 5498 5499@item lfe_out 5500Set LFE output volume. By default, this is @var{1}. 5501 5502@item allx 5503Set spread usage of stereo image across X axis for all channels. 5504 5505@item ally 5506Set spread usage of stereo image across Y axis for all channels. 5507 5508@item fcx, flx, frx, blx, brx, slx, srx, bcx 5509Set spread usage of stereo image across X axis for each channel. 5510 5511@item fcy, fly, fry, bly, bry, sly, sry, bcy 5512Set spread usage of stereo image across Y axis for each channel. 5513 5514@item win_size 5515Set window size. Allowed range is from @var{1024} to @var{65536}. Default size is @var{4096}. 5516 5517@item win_func 5518Set window function. 5519 5520It accepts the following values: 5521@table @samp 5522@item rect 5523@item bartlett 5524@item hann, hanning 5525@item hamming 5526@item blackman 5527@item welch 5528@item flattop 5529@item bharris 5530@item bnuttall 5531@item bhann 5532@item sine 5533@item nuttall 5534@item lanczos 5535@item gauss 5536@item tukey 5537@item dolph 5538@item cauchy 5539@item parzen 5540@item poisson 5541@item bohman 5542@end table 5543Default is @code{hann}. 5544 5545@item overlap 5546Set window overlap. If set to 1, the recommended overlap for selected 5547window function will be picked. Default is @code{0.5}. 5548@end table 5549 5550@section treble, highshelf 5551 5552Boost or cut treble (upper) frequencies of the audio using a two-pole 5553shelving filter with a response similar to that of a standard 5554hi-fi's tone-controls. This is also known as shelving equalisation (EQ). 5555 5556The filter accepts the following options: 5557 5558@table @option 5559@item gain, g 5560Give the gain at whichever is the lower of ~22 kHz and the 5561Nyquist frequency. Its useful range is about -20 (for a large cut) 5562to +20 (for a large boost). Beware of clipping when using a positive gain. 5563 5564@item frequency, f 5565Set the filter's central frequency and so can be used 5566to extend or reduce the frequency range to be boosted or cut. 5567The default value is @code{3000} Hz. 5568 5569@item width_type, t 5570Set method to specify band-width of filter. 5571@table @option 5572@item h 5573Hz 5574@item q 5575Q-Factor 5576@item o 5577octave 5578@item s 5579slope 5580@item k 5581kHz 5582@end table 5583 5584@item width, w 5585Determine how steep is the filter's shelf transition. 5586 5587@item mix, m 5588How much to use filtered signal in output. Default is 1. 5589Range is between 0 and 1. 5590 5591@item channels, c 5592Specify which channels to filter, by default all available are filtered. 5593 5594@item normalize, n 5595Normalize biquad coefficients, by default is disabled. 5596Enabling it will normalize magnitude response at DC to 0dB. 5597 5598@item transform, a 5599Set transform type of IIR filter. 5600@table @option 5601@item di 5602@item dii 5603@item tdii 5604@end table 5605@end table 5606 5607@subsection Commands 5608 5609This filter supports the following commands: 5610@table @option 5611@item frequency, f 5612Change treble frequency. 5613Syntax for the command is : "@var{frequency}" 5614 5615@item width_type, t 5616Change treble width_type. 5617Syntax for the command is : "@var{width_type}" 5618 5619@item width, w 5620Change treble width. 5621Syntax for the command is : "@var{width}" 5622 5623@item gain, g 5624Change treble gain. 5625Syntax for the command is : "@var{gain}" 5626 5627@item mix, m 5628Change treble mix. 5629Syntax for the command is : "@var{mix}" 5630@end table 5631 5632@section tremolo 5633 5634Sinusoidal amplitude modulation. 5635 5636The filter accepts the following options: 5637 5638@table @option 5639@item f 5640Modulation frequency in Hertz. Modulation frequencies in the subharmonic range 5641(20 Hz or lower) will result in a tremolo effect. 5642This filter may also be used as a ring modulator by specifying 5643a modulation frequency higher than 20 Hz. 5644Range is 0.1 - 20000.0. Default value is 5.0 Hz. 5645 5646@item d 5647Depth of modulation as a percentage. Range is 0.0 - 1.0. 5648Default value is 0.5. 5649@end table 5650 5651@section vibrato 5652 5653Sinusoidal phase modulation. 5654 5655The filter accepts the following options: 5656 5657@table @option 5658@item f 5659Modulation frequency in Hertz. 5660Range is 0.1 - 20000.0. Default value is 5.0 Hz. 5661 5662@item d 5663Depth of modulation as a percentage. Range is 0.0 - 1.0. 5664Default value is 0.5. 5665@end table 5666 5667@section volume 5668 5669Adjust the input audio volume. 5670 5671It accepts the following parameters: 5672@table @option 5673 5674@item volume 5675Set audio volume expression. 5676 5677Output values are clipped to the maximum value. 5678 5679The output audio volume is given by the relation: 5680@example 5681@var{output_volume} = @var{volume} * @var{input_volume} 5682@end example 5683 5684The default value for @var{volume} is "1.0". 5685 5686@item precision 5687This parameter represents the mathematical precision. 5688 5689It determines which input sample formats will be allowed, which affects the 5690precision of the volume scaling. 5691 5692@table @option 5693@item fixed 56948-bit fixed-point; this limits input sample format to U8, S16, and S32. 5695@item float 569632-bit floating-point; this limits input sample format to FLT. (default) 5697@item double 569864-bit floating-point; this limits input sample format to DBL. 5699@end table 5700 5701@item replaygain 5702Choose the behaviour on encountering ReplayGain side data in input frames. 5703 5704@table @option 5705@item drop 5706Remove ReplayGain side data, ignoring its contents (the default). 5707 5708@item ignore 5709Ignore ReplayGain side data, but leave it in the frame. 5710 5711@item track 5712Prefer the track gain, if present. 5713 5714@item album 5715Prefer the album gain, if present. 5716@end table 5717 5718@item replaygain_preamp 5719Pre-amplification gain in dB to apply to the selected replaygain gain. 5720 5721Default value for @var{replaygain_preamp} is 0.0. 5722 5723@item replaygain_noclip 5724Prevent clipping by limiting the gain applied. 5725 5726Default value for @var{replaygain_noclip} is 1. 5727 5728@item eval 5729Set when the volume expression is evaluated. 5730 5731It accepts the following values: 5732@table @samp 5733@item once 5734only evaluate expression once during the filter initialization, or 5735when the @samp{volume} command is sent 5736 5737@item frame 5738evaluate expression for each incoming frame 5739@end table 5740 5741Default value is @samp{once}. 5742@end table 5743 5744The volume expression can contain the following parameters. 5745 5746@table @option 5747@item n 5748frame number (starting at zero) 5749@item nb_channels 5750number of channels 5751@item nb_consumed_samples 5752number of samples consumed by the filter 5753@item nb_samples 5754number of samples in the current frame 5755@item pos 5756original frame position in the file 5757@item pts 5758frame PTS 5759@item sample_rate 5760sample rate 5761@item startpts 5762PTS at start of stream 5763@item startt 5764time at start of stream 5765@item t 5766frame time 5767@item tb 5768timestamp timebase 5769@item volume 5770last set volume value 5771@end table 5772 5773Note that when @option{eval} is set to @samp{once} only the 5774@var{sample_rate} and @var{tb} variables are available, all other 5775variables will evaluate to NAN. 5776 5777@subsection Commands 5778 5779This filter supports the following commands: 5780@table @option 5781@item volume 5782Modify the volume expression. 5783The command accepts the same syntax of the corresponding option. 5784 5785If the specified expression is not valid, it is kept at its current 5786value. 5787@end table 5788 5789@subsection Examples 5790 5791@itemize 5792@item 5793Halve the input audio volume: 5794@example 5795volume=volume=0.5 5796volume=volume=1/2 5797volume=volume=-6.0206dB 5798@end example 5799 5800In all the above example the named key for @option{volume} can be 5801omitted, for example like in: 5802@example 5803volume=0.5 5804@end example 5805 5806@item 5807Increase input audio power by 6 decibels using fixed-point precision: 5808@example 5809volume=volume=6dB:precision=fixed 5810@end example 5811 5812@item 5813Fade volume after time 10 with an annihilation period of 5 seconds: 5814@example 5815volume='if(lt(t,10),1,max(1-(t-10)/5,0))':eval=frame 5816@end example 5817@end itemize 5818 5819@section volumedetect 5820 5821Detect the volume of the input video. 5822 5823The filter has no parameters. The input is not modified. Statistics about 5824the volume will be printed in the log when the input stream end is reached. 5825 5826In particular it will show the mean volume (root mean square), maximum 5827volume (on a per-sample basis), and the beginning of a histogram of the 5828registered volume values (from the maximum value to a cumulated 1/1000 of 5829the samples). 5830 5831All volumes are in decibels relative to the maximum PCM value. 5832 5833@subsection Examples 5834 5835Here is an excerpt of the output: 5836@example 5837[Parsed_volumedetect_0 @ 0xa23120] mean_volume: -27 dB 5838[Parsed_volumedetect_0 @ 0xa23120] max_volume: -4 dB 5839[Parsed_volumedetect_0 @ 0xa23120] histogram_4db: 6 5840[Parsed_volumedetect_0 @ 0xa23120] histogram_5db: 62 5841[Parsed_volumedetect_0 @ 0xa23120] histogram_6db: 286 5842[Parsed_volumedetect_0 @ 0xa23120] histogram_7db: 1042 5843[Parsed_volumedetect_0 @ 0xa23120] histogram_8db: 2551 5844[Parsed_volumedetect_0 @ 0xa23120] histogram_9db: 4609 5845[Parsed_volumedetect_0 @ 0xa23120] histogram_10db: 8409 5846@end example 5847 5848It means that: 5849@itemize 5850@item 5851The mean square energy is approximately -27 dB, or 10^-2.7. 5852@item 5853The largest sample is at -4 dB, or more precisely between -4 dB and -5 dB. 5854@item 5855There are 6 samples at -4 dB, 62 at -5 dB, 286 at -6 dB, etc. 5856@end itemize 5857 5858In other words, raising the volume by +4 dB does not cause any clipping, 5859raising it by +5 dB causes clipping for 6 samples, etc. 5860 5861@c man end AUDIO FILTERS 5862 5863@chapter Audio Sources 5864@c man begin AUDIO SOURCES 5865 5866Below is a description of the currently available audio sources. 5867 5868@section abuffer 5869 5870Buffer audio frames, and make them available to the filter chain. 5871 5872This source is mainly intended for a programmatic use, in particular 5873through the interface defined in @file{libavfilter/buffersrc.h}. 5874 5875It accepts the following parameters: 5876@table @option 5877 5878@item time_base 5879The timebase which will be used for timestamps of submitted frames. It must be 5880either a floating-point number or in @var{numerator}/@var{denominator} form. 5881 5882@item sample_rate 5883The sample rate of the incoming audio buffers. 5884 5885@item sample_fmt 5886The sample format of the incoming audio buffers. 5887Either a sample format name or its corresponding integer representation from 5888the enum AVSampleFormat in @file{libavutil/samplefmt.h} 5889 5890@item channel_layout 5891The channel layout of the incoming audio buffers. 5892Either a channel layout name from channel_layout_map in 5893@file{libavutil/channel_layout.c} or its corresponding integer representation 5894from the AV_CH_LAYOUT_* macros in @file{libavutil/channel_layout.h} 5895 5896@item channels 5897The number of channels of the incoming audio buffers. 5898If both @var{channels} and @var{channel_layout} are specified, then they 5899must be consistent. 5900 5901@end table 5902 5903@subsection Examples 5904 5905@example 5906abuffer=sample_rate=44100:sample_fmt=s16p:channel_layout=stereo 5907@end example 5908 5909will instruct the source to accept planar 16bit signed stereo at 44100Hz. 5910Since the sample format with name "s16p" corresponds to the number 59116 and the "stereo" channel layout corresponds to the value 0x3, this is 5912equivalent to: 5913@example 5914abuffer=sample_rate=44100:sample_fmt=6:channel_layout=0x3 5915@end example 5916 5917@section aevalsrc 5918 5919Generate an audio signal specified by an expression. 5920 5921This source accepts in input one or more expressions (one for each 5922channel), which are evaluated and used to generate a corresponding 5923audio signal. 5924 5925This source accepts the following options: 5926 5927@table @option 5928@item exprs 5929Set the '|'-separated expressions list for each separate channel. In case the 5930@option{channel_layout} option is not specified, the selected channel layout 5931depends on the number of provided expressions. Otherwise the last 5932specified expression is applied to the remaining output channels. 5933 5934@item channel_layout, c 5935Set the channel layout. The number of channels in the specified layout 5936must be equal to the number of specified expressions. 5937 5938@item duration, d 5939Set the minimum duration of the sourced audio. See 5940@ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils} 5941for the accepted syntax. 5942Note that the resulting duration may be greater than the specified 5943duration, as the generated audio is always cut at the end of a 5944complete frame. 5945 5946If not specified, or the expressed duration is negative, the audio is 5947supposed to be generated forever. 5948 5949@item nb_samples, n 5950Set the number of samples per channel per each output frame, 5951default to 1024. 5952 5953@item sample_rate, s 5954Specify the sample rate, default to 44100. 5955@end table 5956 5957Each expression in @var{exprs} can contain the following constants: 5958 5959@table @option 5960@item n 5961number of the evaluated sample, starting from 0 5962 5963@item t 5964time of the evaluated sample expressed in seconds, starting from 0 5965 5966@item s 5967sample rate 5968 5969@end table 5970 5971@subsection Examples 5972 5973@itemize 5974@item 5975Generate silence: 5976@example 5977aevalsrc=0 5978@end example 5979 5980@item 5981Generate a sin signal with frequency of 440 Hz, set sample rate to 59828000 Hz: 5983@example 5984aevalsrc="sin(440*2*PI*t):s=8000" 5985@end example 5986 5987@item 5988Generate a two channels signal, specify the channel layout (Front 5989Center + Back Center) explicitly: 5990@example 5991aevalsrc="sin(420*2*PI*t)|cos(430*2*PI*t):c=FC|BC" 5992@end example 5993 5994@item 5995Generate white noise: 5996@example 5997aevalsrc="-2+random(0)" 5998@end example 5999 6000@item 6001Generate an amplitude modulated signal: 6002@example 6003aevalsrc="sin(10*2*PI*t)*sin(880*2*PI*t)" 6004@end example 6005 6006@item 6007Generate 2.5 Hz binaural beats on a 360 Hz carrier: 6008@example 6009aevalsrc="0.1*sin(2*PI*(360-2.5/2)*t) | 0.1*sin(2*PI*(360+2.5/2)*t)" 6010@end example 6011 6012@end itemize 6013 6014@section afirsrc 6015 6016Generate a FIR coefficients using frequency sampling method. 6017 6018The resulting stream can be used with @ref{afir} filter for filtering the audio signal. 6019 6020The filter accepts the following options: 6021 6022@table @option 6023@item taps, t 6024Set number of filter coefficents in output audio stream. 6025Default value is 1025. 6026 6027@item frequency, f 6028Set frequency points from where magnitude and phase are set. 6029This must be in non decreasing order, and first element must be 0, while last element 6030must be 1. Elements are separated by white spaces. 6031 6032@item magnitude, m 6033Set magnitude value for every frequency point set by @option{frequency}. 6034Number of values must be same as number of frequency points. 6035Values are separated by white spaces. 6036 6037@item phase, p 6038Set phase value for every frequency point set by @option{frequency}. 6039Number of values must be same as number of frequency points. 6040Values are separated by white spaces. 6041 6042@item sample_rate, r 6043Set sample rate, default is 44100. 6044 6045@item nb_samples, n 6046Set number of samples per each frame. Default is 1024. 6047 6048@item win_func, w 6049Set window function. Default is blackman. 6050@end table 6051 6052@section anullsrc 6053 6054The null audio source, return unprocessed audio frames. It is mainly useful 6055as a template and to be employed in analysis / debugging tools, or as 6056the source for filters which ignore the input data (for example the sox 6057synth filter). 6058 6059This source accepts the following options: 6060 6061@table @option 6062 6063@item channel_layout, cl 6064 6065Specifies the channel layout, and can be either an integer or a string 6066representing a channel layout. The default value of @var{channel_layout} 6067is "stereo". 6068 6069Check the channel_layout_map definition in 6070@file{libavutil/channel_layout.c} for the mapping between strings and 6071channel layout values. 6072 6073@item sample_rate, r 6074Specifies the sample rate, and defaults to 44100. 6075 6076@item nb_samples, n 6077Set the number of samples per requested frames. 6078 6079@item duration, d 6080Set the duration of the sourced audio. See 6081@ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils} 6082for the accepted syntax. 6083 6084If not specified, or the expressed duration is negative, the audio is 6085supposed to be generated forever. 6086@end table 6087 6088@subsection Examples 6089 6090@itemize 6091@item 6092Set the sample rate to 48000 Hz and the channel layout to AV_CH_LAYOUT_MONO. 6093@example 6094anullsrc=r=48000:cl=4 6095@end example 6096 6097@item 6098Do the same operation with a more obvious syntax: 6099@example 6100anullsrc=r=48000:cl=mono 6101@end example 6102@end itemize 6103 6104All the parameters need to be explicitly defined. 6105 6106@section flite 6107 6108Synthesize a voice utterance using the libflite library. 6109 6110To enable compilation of this filter you need to configure FFmpeg with 6111@code{--enable-libflite}. 6112 6113Note that versions of the flite library prior to 2.0 are not thread-safe. 6114 6115The filter accepts the following options: 6116 6117@table @option 6118 6119@item list_voices 6120If set to 1, list the names of the available voices and exit 6121immediately. Default value is 0. 6122 6123@item nb_samples, n 6124Set the maximum number of samples per frame. Default value is 512. 6125 6126@item textfile 6127Set the filename containing the text to speak. 6128 6129@item text 6130Set the text to speak. 6131 6132@item voice, v 6133Set the voice to use for the speech synthesis. Default value is 6134@code{kal}. See also the @var{list_voices} option. 6135@end table 6136 6137@subsection Examples 6138 6139@itemize 6140@item 6141Read from file @file{speech.txt}, and synthesize the text using the 6142standard flite voice: 6143@example 6144flite=textfile=speech.txt 6145@end example 6146 6147@item 6148Read the specified text selecting the @code{slt} voice: 6149@example 6150flite=text='So fare thee well, poor devil of a Sub-Sub, whose commentator I am':voice=slt 6151@end example 6152 6153@item 6154Input text to ffmpeg: 6155@example 6156ffmpeg -f lavfi -i flite=text='So fare thee well, poor devil of a Sub-Sub, whose commentator I am':voice=slt 6157@end example 6158 6159@item 6160Make @file{ffplay} speak the specified text, using @code{flite} and 6161the @code{lavfi} device: 6162@example 6163ffplay -f lavfi flite=text='No more be grieved for which that thou hast done.' 6164@end example 6165@end itemize 6166 6167For more information about libflite, check: 6168@url{http://www.festvox.org/flite/} 6169 6170@section anoisesrc 6171 6172Generate a noise audio signal. 6173 6174The filter accepts the following options: 6175 6176@table @option 6177@item sample_rate, r 6178Specify the sample rate. Default value is 48000 Hz. 6179 6180@item amplitude, a 6181Specify the amplitude (0.0 - 1.0) of the generated audio stream. Default value 6182is 1.0. 6183 6184@item duration, d 6185Specify the duration of the generated audio stream. Not specifying this option 6186results in noise with an infinite length. 6187 6188@item color, colour, c 6189Specify the color of noise. Available noise colors are white, pink, brown, 6190blue, violet and velvet. Default color is white. 6191 6192@item seed, s 6193Specify a value used to seed the PRNG. 6194 6195@item nb_samples, n 6196Set the number of samples per each output frame, default is 1024. 6197@end table 6198 6199@subsection Examples 6200 6201@itemize 6202 6203@item 6204Generate 60 seconds of pink noise, with a 44.1 kHz sampling rate and an amplitude of 0.5: 6205@example 6206anoisesrc=d=60:c=pink:r=44100:a=0.5 6207@end example 6208@end itemize 6209 6210@section hilbert 6211 6212Generate odd-tap Hilbert transform FIR coefficients. 6213 6214The resulting stream can be used with @ref{afir} filter for phase-shifting 6215the signal by 90 degrees. 6216 6217This is used in many matrix coding schemes and for analytic signal generation. 6218The process is often written as a multiplication by i (or j), the imaginary unit. 6219 6220The filter accepts the following options: 6221 6222@table @option 6223 6224@item sample_rate, s 6225Set sample rate, default is 44100. 6226 6227@item taps, t 6228Set length of FIR filter, default is 22051. 6229 6230@item nb_samples, n 6231Set number of samples per each frame. 6232 6233@item win_func, w 6234Set window function to be used when generating FIR coefficients. 6235@end table 6236 6237@section sinc 6238 6239Generate a sinc kaiser-windowed low-pass, high-pass, band-pass, or band-reject FIR coefficients. 6240 6241The resulting stream can be used with @ref{afir} filter for filtering the audio signal. 6242 6243The filter accepts the following options: 6244 6245@table @option 6246@item sample_rate, r 6247Set sample rate, default is 44100. 6248 6249@item nb_samples, n 6250Set number of samples per each frame. Default is 1024. 6251 6252@item hp 6253Set high-pass frequency. Default is 0. 6254 6255@item lp 6256Set low-pass frequency. Default is 0. 6257If high-pass frequency is lower than low-pass frequency and low-pass frequency 6258is higher than 0 then filter will create band-pass filter coefficients, 6259otherwise band-reject filter coefficients. 6260 6261@item phase 6262Set filter phase response. Default is 50. Allowed range is from 0 to 100. 6263 6264@item beta 6265Set Kaiser window beta. 6266 6267@item att 6268Set stop-band attenuation. Default is 120dB, allowed range is from 40 to 180 dB. 6269 6270@item round 6271Enable rounding, by default is disabled. 6272 6273@item hptaps 6274Set number of taps for high-pass filter. 6275 6276@item lptaps 6277Set number of taps for low-pass filter. 6278@end table 6279 6280@section sine 6281 6282Generate an audio signal made of a sine wave with amplitude 1/8. 6283 6284The audio signal is bit-exact. 6285 6286The filter accepts the following options: 6287 6288@table @option 6289 6290@item frequency, f 6291Set the carrier frequency. Default is 440 Hz. 6292 6293@item beep_factor, b 6294Enable a periodic beep every second with frequency @var{beep_factor} times 6295the carrier frequency. Default is 0, meaning the beep is disabled. 6296 6297@item sample_rate, r 6298Specify the sample rate, default is 44100. 6299 6300@item duration, d 6301Specify the duration of the generated audio stream. 6302 6303@item samples_per_frame 6304Set the number of samples per output frame. 6305 6306The expression can contain the following constants: 6307 6308@table @option 6309@item n 6310The (sequential) number of the output audio frame, starting from 0. 6311 6312@item pts 6313The PTS (Presentation TimeStamp) of the output audio frame, 6314expressed in @var{TB} units. 6315 6316@item t 6317The PTS of the output audio frame, expressed in seconds. 6318 6319@item TB 6320The timebase of the output audio frames. 6321@end table 6322 6323Default is @code{1024}. 6324@end table 6325 6326@subsection Examples 6327 6328@itemize 6329 6330@item 6331Generate a simple 440 Hz sine wave: 6332@example 6333sine 6334@end example 6335 6336@item 6337Generate a 220 Hz sine wave with a 880 Hz beep each second, for 5 seconds: 6338@example 6339sine=220:4:d=5 6340sine=f=220:b=4:d=5 6341sine=frequency=220:beep_factor=4:duration=5 6342@end example 6343 6344@item 6345Generate a 1 kHz sine wave following @code{1602,1601,1602,1601,1602} NTSC 6346pattern: 6347@example 6348sine=1000:samples_per_frame='st(0,mod(n,5)); 1602-not(not(eq(ld(0),1)+eq(ld(0),3)))' 6349@end example 6350@end itemize 6351 6352@c man end AUDIO SOURCES 6353 6354@chapter Audio Sinks 6355@c man begin AUDIO SINKS 6356 6357Below is a description of the currently available audio sinks. 6358 6359@section abuffersink 6360 6361Buffer audio frames, and make them available to the end of filter chain. 6362 6363This sink is mainly intended for programmatic use, in particular 6364through the interface defined in @file{libavfilter/buffersink.h} 6365or the options system. 6366 6367It accepts a pointer to an AVABufferSinkContext structure, which 6368defines the incoming buffers' formats, to be passed as the opaque 6369parameter to @code{avfilter_init_filter} for initialization. 6370@section anullsink 6371 6372Null audio sink; do absolutely nothing with the input audio. It is 6373mainly useful as a template and for use in analysis / debugging 6374tools. 6375 6376@c man end AUDIO SINKS 6377 6378@chapter Video Filters 6379@c man begin VIDEO FILTERS 6380 6381When you configure your FFmpeg build, you can disable any of the 6382existing filters using @code{--disable-filters}. 6383The configure output will show the video filters included in your 6384build. 6385 6386Below is a description of the currently available video filters. 6387 6388@section addroi 6389 6390Mark a region of interest in a video frame. 6391 6392The frame data is passed through unchanged, but metadata is attached 6393to the frame indicating regions of interest which can affect the 6394behaviour of later encoding. Multiple regions can be marked by 6395applying the filter multiple times. 6396 6397@table @option 6398@item x 6399Region distance in pixels from the left edge of the frame. 6400@item y 6401Region distance in pixels from the top edge of the frame. 6402@item w 6403Region width in pixels. 6404@item h 6405Region height in pixels. 6406 6407The parameters @var{x}, @var{y}, @var{w} and @var{h} are expressions, 6408and may contain the following variables: 6409@table @option 6410@item iw 6411Width of the input frame. 6412@item ih 6413Height of the input frame. 6414@end table 6415 6416@item qoffset 6417Quantisation offset to apply within the region. 6418 6419This must be a real value in the range -1 to +1. A value of zero 6420indicates no quality change. A negative value asks for better quality 6421(less quantisation), while a positive value asks for worse quality 6422(greater quantisation). 6423 6424The range is calibrated so that the extreme values indicate the 6425largest possible offset - if the rest of the frame is encoded with the 6426worst possible quality, an offset of -1 indicates that this region 6427should be encoded with the best possible quality anyway. Intermediate 6428values are then interpolated in some codec-dependent way. 6429 6430For example, in 10-bit H.264 the quantisation parameter varies between 6431-12 and 51. A typical qoffset value of -1/10 therefore indicates that 6432this region should be encoded with a QP around one-tenth of the full 6433range better than the rest of the frame. So, if most of the frame 6434were to be encoded with a QP of around 30, this region would get a QP 6435of around 24 (an offset of approximately -1/10 * (51 - -12) = -6.3). 6436An extreme value of -1 would indicate that this region should be 6437encoded with the best possible quality regardless of the treatment of 6438the rest of the frame - that is, should be encoded at a QP of -12. 6439@item clear 6440If set to true, remove any existing regions of interest marked on the 6441frame before adding the new one. 6442@end table 6443 6444@subsection Examples 6445 6446@itemize 6447@item 6448Mark the centre quarter of the frame as interesting. 6449@example 6450addroi=iw/4:ih/4:iw/2:ih/2:-1/10 6451@end example 6452@item 6453Mark the 100-pixel-wide region on the left edge of the frame as very 6454uninteresting (to be encoded at much lower quality than the rest of 6455the frame). 6456@example 6457addroi=0:0:100:ih:+1/5 6458@end example 6459@end itemize 6460 6461@section alphaextract 6462 6463Extract the alpha component from the input as a grayscale video. This 6464is especially useful with the @var{alphamerge} filter. 6465 6466@section alphamerge 6467 6468Add or replace the alpha component of the primary input with the 6469grayscale value of a second input. This is intended for use with 6470@var{alphaextract} to allow the transmission or storage of frame 6471sequences that have alpha in a format that doesn't support an alpha 6472channel. 6473 6474For example, to reconstruct full frames from a normal YUV-encoded video 6475and a separate video created with @var{alphaextract}, you might use: 6476@example 6477movie=in_alpha.mkv [alpha]; [in][alpha] alphamerge [out] 6478@end example 6479 6480@section amplify 6481 6482Amplify differences between current pixel and pixels of adjacent frames in 6483same pixel location. 6484 6485This filter accepts the following options: 6486 6487@table @option 6488@item radius 6489Set frame radius. Default is 2. Allowed range is from 1 to 63. 6490For example radius of 3 will instruct filter to calculate average of 7 frames. 6491 6492@item factor 6493Set factor to amplify difference. Default is 2. Allowed range is from 0 to 65535. 6494 6495@item threshold 6496Set threshold for difference amplification. Any difference greater or equal to 6497this value will not alter source pixel. Default is 10. 6498Allowed range is from 0 to 65535. 6499 6500@item tolerance 6501Set tolerance for difference amplification. Any difference lower to 6502this value will not alter source pixel. Default is 0. 6503Allowed range is from 0 to 65535. 6504 6505@item low 6506Set lower limit for changing source pixel. Default is 65535. Allowed range is from 0 to 65535. 6507This option controls maximum possible value that will decrease source pixel value. 6508 6509@item high 6510Set high limit for changing source pixel. Default is 65535. Allowed range is from 0 to 65535. 6511This option controls maximum possible value that will increase source pixel value. 6512 6513@item planes 6514Set which planes to filter. Default is all. Allowed range is from 0 to 15. 6515@end table 6516 6517@subsection Commands 6518 6519This filter supports the following @ref{commands} that corresponds to option of same name: 6520@table @option 6521@item factor 6522@item threshold 6523@item tolerance 6524@item low 6525@item high 6526@item planes 6527@end table 6528 6529@section ass 6530 6531Same as the @ref{subtitles} filter, except that it doesn't require libavcodec 6532and libavformat to work. On the other hand, it is limited to ASS (Advanced 6533Substation Alpha) subtitles files. 6534 6535This filter accepts the following option in addition to the common options from 6536the @ref{subtitles} filter: 6537 6538@table @option 6539@item shaping 6540Set the shaping engine 6541 6542Available values are: 6543@table @samp 6544@item auto 6545The default libass shaping engine, which is the best available. 6546@item simple 6547Fast, font-agnostic shaper that can do only substitutions 6548@item complex 6549Slower shaper using OpenType for substitutions and positioning 6550@end table 6551 6552The default is @code{auto}. 6553@end table 6554 6555@section atadenoise 6556Apply an Adaptive Temporal Averaging Denoiser to the video input. 6557 6558The filter accepts the following options: 6559 6560@table @option 6561@item 0a 6562Set threshold A for 1st plane. Default is 0.02. 6563Valid range is 0 to 0.3. 6564 6565@item 0b 6566Set threshold B for 1st plane. Default is 0.04. 6567Valid range is 0 to 5. 6568 6569@item 1a 6570Set threshold A for 2nd plane. Default is 0.02. 6571Valid range is 0 to 0.3. 6572 6573@item 1b 6574Set threshold B for 2nd plane. Default is 0.04. 6575Valid range is 0 to 5. 6576 6577@item 2a 6578Set threshold A for 3rd plane. Default is 0.02. 6579Valid range is 0 to 0.3. 6580 6581@item 2b 6582Set threshold B for 3rd plane. Default is 0.04. 6583Valid range is 0 to 5. 6584 6585Threshold A is designed to react on abrupt changes in the input signal and 6586threshold B is designed to react on continuous changes in the input signal. 6587 6588@item s 6589Set number of frames filter will use for averaging. Default is 9. Must be odd 6590number in range [5, 129]. 6591 6592@item p 6593Set what planes of frame filter will use for averaging. Default is all. 6594 6595@item a 6596Set what variant of algorithm filter will use for averaging. Default is @code{p} parallel. 6597Alternatively can be set to @code{s} serial. 6598 6599Parallel can be faster then serial, while other way around is never true. 6600Parallel will abort early on first change being greater then thresholds, while serial 6601will continue processing other side of frames if they are equal or bellow thresholds. 6602@end table 6603 6604@subsection Commands 6605This filter supports same @ref{commands} as options except option @code{s}. 6606The command accepts the same syntax of the corresponding option. 6607 6608@section avgblur 6609 6610Apply average blur filter. 6611 6612The filter accepts the following options: 6613 6614@table @option 6615@item sizeX 6616Set horizontal radius size. 6617 6618@item planes 6619Set which planes to filter. By default all planes are filtered. 6620 6621@item sizeY 6622Set vertical radius size, if zero it will be same as @code{sizeX}. 6623Default is @code{0}. 6624@end table 6625 6626@subsection Commands 6627This filter supports same commands as options. 6628The command accepts the same syntax of the corresponding option. 6629 6630If the specified expression is not valid, it is kept at its current 6631value. 6632 6633@section bbox 6634 6635Compute the bounding box for the non-black pixels in the input frame 6636luminance plane. 6637 6638This filter computes the bounding box containing all the pixels with a 6639luminance value greater than the minimum allowed value. 6640The parameters describing the bounding box are printed on the filter 6641log. 6642 6643The filter accepts the following option: 6644 6645@table @option 6646@item min_val 6647Set the minimal luminance value. Default is @code{16}. 6648@end table 6649 6650@section bilateral 6651Apply bilateral filter, spatial smoothing while preserving edges. 6652 6653The filter accepts the following options: 6654@table @option 6655@item sigmaS 6656Set sigma of gaussian function to calculate spatial weight. 6657Allowed range is 0 to 512. Default is 0.1. 6658 6659@item sigmaR 6660Set sigma of gaussian function to calculate range weight. 6661Allowed range is 0 to 1. Default is 0.1. 6662 6663@item planes 6664Set planes to filter. Default is first only. 6665@end table 6666 6667@section bitplanenoise 6668 6669Show and measure bit plane noise. 6670 6671The filter accepts the following options: 6672 6673@table @option 6674@item bitplane 6675Set which plane to analyze. Default is @code{1}. 6676 6677@item filter 6678Filter out noisy pixels from @code{bitplane} set above. 6679Default is disabled. 6680@end table 6681 6682@section blackdetect 6683 6684Detect video intervals that are (almost) completely black. Can be 6685useful to detect chapter transitions, commercials, or invalid 6686recordings. 6687 6688The filter outputs its detection analysis to both the log as well as 6689frame metadata. If a black segment of at least the specified minimum 6690duration is found, a line with the start and end timestamps as well 6691as duration is printed to the log with level @code{info}. In addition, 6692a log line with level @code{debug} is printed per frame showing the 6693black amount detected for that frame. 6694 6695The filter also attaches metadata to the first frame of a black 6696segment with key @code{lavfi.black_start} and to the first frame 6697after the black segment ends with key @code{lavfi.black_end}. The 6698value is the frame's timestamp. This metadata is added regardless 6699of the minimum duration specified. 6700 6701The filter accepts the following options: 6702 6703@table @option 6704@item black_min_duration, d 6705Set the minimum detected black duration expressed in seconds. It must 6706be a non-negative floating point number. 6707 6708Default value is 2.0. 6709 6710@item picture_black_ratio_th, pic_th 6711Set the threshold for considering a picture "black". 6712Express the minimum value for the ratio: 6713@example 6714@var{nb_black_pixels} / @var{nb_pixels} 6715@end example 6716 6717for which a picture is considered black. 6718Default value is 0.98. 6719 6720@item pixel_black_th, pix_th 6721Set the threshold for considering a pixel "black". 6722 6723The threshold expresses the maximum pixel luminance value for which a 6724pixel is considered "black". The provided value is scaled according to 6725the following equation: 6726@example 6727@var{absolute_threshold} = @var{luminance_minimum_value} + @var{pixel_black_th} * @var{luminance_range_size} 6728@end example 6729 6730@var{luminance_range_size} and @var{luminance_minimum_value} depend on 6731the input video format, the range is [0-255] for YUV full-range 6732formats and [16-235] for YUV non full-range formats. 6733 6734Default value is 0.10. 6735@end table 6736 6737The following example sets the maximum pixel threshold to the minimum 6738value, and detects only black intervals of 2 or more seconds: 6739@example 6740blackdetect=d=2:pix_th=0.00 6741@end example 6742 6743@section blackframe 6744 6745Detect frames that are (almost) completely black. Can be useful to 6746detect chapter transitions or commercials. Output lines consist of 6747the frame number of the detected frame, the percentage of blackness, 6748the position in the file if known or -1 and the timestamp in seconds. 6749 6750In order to display the output lines, you need to set the loglevel at 6751least to the AV_LOG_INFO value. 6752 6753This filter exports frame metadata @code{lavfi.blackframe.pblack}. 6754The value represents the percentage of pixels in the picture that 6755are below the threshold value. 6756 6757It accepts the following parameters: 6758 6759@table @option 6760 6761@item amount 6762The percentage of the pixels that have to be below the threshold; it defaults to 6763@code{98}. 6764 6765@item threshold, thresh 6766The threshold below which a pixel value is considered black; it defaults to 6767@code{32}. 6768 6769@end table 6770 6771@anchor{blend} 6772@section blend 6773 6774Blend two video frames into each other. 6775 6776The @code{blend} filter takes two input streams and outputs one 6777stream, the first input is the "top" layer and second input is 6778"bottom" layer. By default, the output terminates when the longest input terminates. 6779 6780The @code{tblend} (time blend) filter takes two consecutive frames 6781from one single stream, and outputs the result obtained by blending 6782the new frame on top of the old frame. 6783 6784A description of the accepted options follows. 6785 6786@table @option 6787@item c0_mode 6788@item c1_mode 6789@item c2_mode 6790@item c3_mode 6791@item all_mode 6792Set blend mode for specific pixel component or all pixel components in case 6793of @var{all_mode}. Default value is @code{normal}. 6794 6795Available values for component modes are: 6796@table @samp 6797@item addition 6798@item grainmerge 6799@item and 6800@item average 6801@item burn 6802@item darken 6803@item difference 6804@item grainextract 6805@item divide 6806@item dodge 6807@item freeze 6808@item exclusion 6809@item extremity 6810@item glow 6811@item hardlight 6812@item hardmix 6813@item heat 6814@item lighten 6815@item linearlight 6816@item multiply 6817@item multiply128 6818@item negation 6819@item normal 6820@item or 6821@item overlay 6822@item phoenix 6823@item pinlight 6824@item reflect 6825@item screen 6826@item softlight 6827@item subtract 6828@item vividlight 6829@item xor 6830@end table 6831 6832@item c0_opacity 6833@item c1_opacity 6834@item c2_opacity 6835@item c3_opacity 6836@item all_opacity 6837Set blend opacity for specific pixel component or all pixel components in case 6838of @var{all_opacity}. Only used in combination with pixel component blend modes. 6839 6840@item c0_expr 6841@item c1_expr 6842@item c2_expr 6843@item c3_expr 6844@item all_expr 6845Set blend expression for specific pixel component or all pixel components in case 6846of @var{all_expr}. Note that related mode options will be ignored if those are set. 6847 6848The expressions can use the following variables: 6849 6850@table @option 6851@item N 6852The sequential number of the filtered frame, starting from @code{0}. 6853 6854@item X 6855@item Y 6856the coordinates of the current sample 6857 6858@item W 6859@item H 6860the width and height of currently filtered plane 6861 6862@item SW 6863@item SH 6864Width and height scale for the plane being filtered. It is the 6865ratio between the dimensions of the current plane to the luma plane, 6866e.g. for a @code{yuv420p} frame, the values are @code{1,1} for 6867the luma plane and @code{0.5,0.5} for the chroma planes. 6868 6869@item T 6870Time of the current frame, expressed in seconds. 6871 6872@item TOP, A 6873Value of pixel component at current location for first video frame (top layer). 6874 6875@item BOTTOM, B 6876Value of pixel component at current location for second video frame (bottom layer). 6877@end table 6878@end table 6879 6880The @code{blend} filter also supports the @ref{framesync} options. 6881 6882@subsection Examples 6883 6884@itemize 6885@item 6886Apply transition from bottom layer to top layer in first 10 seconds: 6887@example 6888blend=all_expr='A*(if(gte(T,10),1,T/10))+B*(1-(if(gte(T,10),1,T/10)))' 6889@end example 6890 6891@item 6892Apply linear horizontal transition from top layer to bottom layer: 6893@example 6894blend=all_expr='A*(X/W)+B*(1-X/W)' 6895@end example 6896 6897@item 6898Apply 1x1 checkerboard effect: 6899@example 6900blend=all_expr='if(eq(mod(X,2),mod(Y,2)),A,B)' 6901@end example 6902 6903@item 6904Apply uncover left effect: 6905@example 6906blend=all_expr='if(gte(N*SW+X,W),A,B)' 6907@end example 6908 6909@item 6910Apply uncover down effect: 6911@example 6912blend=all_expr='if(gte(Y-N*SH,0),A,B)' 6913@end example 6914 6915@item 6916Apply uncover up-left effect: 6917@example 6918blend=all_expr='if(gte(T*SH*40+Y,H)*gte((T*40*SW+X)*W/H,W),A,B)' 6919@end example 6920 6921@item 6922Split diagonally video and shows top and bottom layer on each side: 6923@example 6924blend=all_expr='if(gt(X,Y*(W/H)),A,B)' 6925@end example 6926 6927@item 6928Display differences between the current and the previous frame: 6929@example 6930tblend=all_mode=grainextract 6931@end example 6932@end itemize 6933 6934@section bm3d 6935 6936Denoise frames using Block-Matching 3D algorithm. 6937 6938The filter accepts the following options. 6939 6940@table @option 6941@item sigma 6942Set denoising strength. Default value is 1. 6943Allowed range is from 0 to 999.9. 6944The denoising algorithm is very sensitive to sigma, so adjust it 6945according to the source. 6946 6947@item block 6948Set local patch size. This sets dimensions in 2D. 6949 6950@item bstep 6951Set sliding step for processing blocks. Default value is 4. 6952Allowed range is from 1 to 64. 6953Smaller values allows processing more reference blocks and is slower. 6954 6955@item group 6956Set maximal number of similar blocks for 3rd dimension. Default value is 1. 6957When set to 1, no block matching is done. Larger values allows more blocks 6958in single group. 6959Allowed range is from 1 to 256. 6960 6961@item range 6962Set radius for search block matching. Default is 9. 6963Allowed range is from 1 to INT32_MAX. 6964 6965@item mstep 6966Set step between two search locations for block matching. Default is 1. 6967Allowed range is from 1 to 64. Smaller is slower. 6968 6969@item thmse 6970Set threshold of mean square error for block matching. Valid range is 0 to 6971INT32_MAX. 6972 6973@item hdthr 6974Set thresholding parameter for hard thresholding in 3D transformed domain. 6975Larger values results in stronger hard-thresholding filtering in frequency 6976domain. 6977 6978@item estim 6979Set filtering estimation mode. Can be @code{basic} or @code{final}. 6980Default is @code{basic}. 6981 6982@item ref 6983If enabled, filter will use 2nd stream for block matching. 6984Default is disabled for @code{basic} value of @var{estim} option, 6985and always enabled if value of @var{estim} is @code{final}. 6986 6987@item planes 6988Set planes to filter. Default is all available except alpha. 6989@end table 6990 6991@subsection Examples 6992 6993@itemize 6994@item 6995Basic filtering with bm3d: 6996@example 6997bm3d=sigma=3:block=4:bstep=2:group=1:estim=basic 6998@end example 6999 7000@item 7001Same as above, but filtering only luma: 7002@example 7003bm3d=sigma=3:block=4:bstep=2:group=1:estim=basic:planes=1 7004@end example 7005 7006@item 7007Same as above, but with both estimation modes: 7008@example 7009split[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 7010@end example 7011 7012@item 7013Same as above, but prefilter with @ref{nlmeans} filter instead: 7014@example 7015split[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 7016@end example 7017@end itemize 7018 7019@section boxblur 7020 7021Apply a boxblur algorithm to the input video. 7022 7023It accepts the following parameters: 7024 7025@table @option 7026 7027@item luma_radius, lr 7028@item luma_power, lp 7029@item chroma_radius, cr 7030@item chroma_power, cp 7031@item alpha_radius, ar 7032@item alpha_power, ap 7033 7034@end table 7035 7036A description of the accepted options follows. 7037 7038@table @option 7039@item luma_radius, lr 7040@item chroma_radius, cr 7041@item alpha_radius, ar 7042Set an expression for the box radius in pixels used for blurring the 7043corresponding input plane. 7044 7045The radius value must be a non-negative number, and must not be 7046greater than the value of the expression @code{min(w,h)/2} for the 7047luma and alpha planes, and of @code{min(cw,ch)/2} for the chroma 7048planes. 7049 7050Default value for @option{luma_radius} is "2". If not specified, 7051@option{chroma_radius} and @option{alpha_radius} default to the 7052corresponding value set for @option{luma_radius}. 7053 7054The expressions can contain the following constants: 7055@table @option 7056@item w 7057@item h 7058The input width and height in pixels. 7059 7060@item cw 7061@item ch 7062The input chroma image width and height in pixels. 7063 7064@item hsub 7065@item vsub 7066The horizontal and vertical chroma subsample values. For example, for the 7067pixel format "yuv422p", @var{hsub} is 2 and @var{vsub} is 1. 7068@end table 7069 7070@item luma_power, lp 7071@item chroma_power, cp 7072@item alpha_power, ap 7073Specify how many times the boxblur filter is applied to the 7074corresponding plane. 7075 7076Default value for @option{luma_power} is 2. If not specified, 7077@option{chroma_power} and @option{alpha_power} default to the 7078corresponding value set for @option{luma_power}. 7079 7080A value of 0 will disable the effect. 7081@end table 7082 7083@subsection Examples 7084 7085@itemize 7086@item 7087Apply a boxblur filter with the luma, chroma, and alpha radii 7088set to 2: 7089@example 7090boxblur=luma_radius=2:luma_power=1 7091boxblur=2:1 7092@end example 7093 7094@item 7095Set the luma radius to 2, and alpha and chroma radius to 0: 7096@example 7097boxblur=2:1:cr=0:ar=0 7098@end example 7099 7100@item 7101Set the luma and chroma radii to a fraction of the video dimension: 7102@example 7103boxblur=luma_radius=min(h\,w)/10:luma_power=1:chroma_radius=min(cw\,ch)/10:chroma_power=1 7104@end example 7105@end itemize 7106 7107@section bwdif 7108 7109Deinterlace the input video ("bwdif" stands for "Bob Weaver 7110Deinterlacing Filter"). 7111 7112Motion adaptive deinterlacing based on yadif with the use of w3fdif and cubic 7113interpolation algorithms. 7114It accepts the following parameters: 7115 7116@table @option 7117@item mode 7118The interlacing mode to adopt. It accepts one of the following values: 7119 7120@table @option 7121@item 0, send_frame 7122Output one frame for each frame. 7123@item 1, send_field 7124Output one frame for each field. 7125@end table 7126 7127The default value is @code{send_field}. 7128 7129@item parity 7130The picture field parity assumed for the input interlaced video. It accepts one 7131of the following values: 7132 7133@table @option 7134@item 0, tff 7135Assume the top field is first. 7136@item 1, bff 7137Assume the bottom field is first. 7138@item -1, auto 7139Enable automatic detection of field parity. 7140@end table 7141 7142The default value is @code{auto}. 7143If the interlacing is unknown or the decoder does not export this information, 7144top field first will be assumed. 7145 7146@item deint 7147Specify which frames to deinterlace. Accepts one of the following 7148values: 7149 7150@table @option 7151@item 0, all 7152Deinterlace all frames. 7153@item 1, interlaced 7154Only deinterlace frames marked as interlaced. 7155@end table 7156 7157The default value is @code{all}. 7158@end table 7159 7160@section cas 7161 7162Apply Contrast Adaptive Sharpen filter to video stream. 7163 7164The filter accepts the following options: 7165 7166@table @option 7167@item strength 7168Set the sharpening strength. Default value is 0. 7169 7170@item planes 7171Set planes to filter. Default value is to filter all 7172planes except alpha plane. 7173@end table 7174 7175@section chromahold 7176Remove all color information for all colors except for certain one. 7177 7178The filter accepts the following options: 7179 7180@table @option 7181@item color 7182The color which will not be replaced with neutral chroma. 7183 7184@item similarity 7185Similarity percentage with the above color. 71860.01 matches only the exact key color, while 1.0 matches everything. 7187 7188@item blend 7189Blend percentage. 71900.0 makes pixels either fully gray, or not gray at all. 7191Higher values result in more preserved color. 7192 7193@item yuv 7194Signals that the color passed is already in YUV instead of RGB. 7195 7196Literal colors like "green" or "red" don't make sense with this enabled anymore. 7197This can be used to pass exact YUV values as hexadecimal numbers. 7198@end table 7199 7200@subsection Commands 7201This filter supports same @ref{commands} as options. 7202The command accepts the same syntax of the corresponding option. 7203 7204If the specified expression is not valid, it is kept at its current 7205value. 7206 7207@section chromakey 7208YUV colorspace color/chroma keying. 7209 7210The filter accepts the following options: 7211 7212@table @option 7213@item color 7214The color which will be replaced with transparency. 7215 7216@item similarity 7217Similarity percentage with the key color. 7218 72190.01 matches only the exact key color, while 1.0 matches everything. 7220 7221@item blend 7222Blend percentage. 7223 72240.0 makes pixels either fully transparent, or not transparent at all. 7225 7226Higher values result in semi-transparent pixels, with a higher transparency 7227the more similar the pixels color is to the key color. 7228 7229@item yuv 7230Signals that the color passed is already in YUV instead of RGB. 7231 7232Literal colors like "green" or "red" don't make sense with this enabled anymore. 7233This can be used to pass exact YUV values as hexadecimal numbers. 7234@end table 7235 7236@subsection Commands 7237This filter supports same @ref{commands} as options. 7238The command accepts the same syntax of the corresponding option. 7239 7240If the specified expression is not valid, it is kept at its current 7241value. 7242 7243@subsection Examples 7244 7245@itemize 7246@item 7247Make every green pixel in the input image transparent: 7248@example 7249ffmpeg -i input.png -vf chromakey=green out.png 7250@end example 7251 7252@item 7253Overlay a greenscreen-video on top of a static black background. 7254@example 7255ffmpeg -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 7256@end example 7257@end itemize 7258 7259@section chromanr 7260Reduce chrominance noise. 7261 7262The filter accepts the following options: 7263 7264@table @option 7265@item thres 7266Set threshold for averaging chrominance values. 7267Sum of absolute difference of U and V pixel components or current 7268pixel and neighbour pixels lower than this threshold will be used in 7269averaging. Luma component is left unchanged and is copied to output. 7270Default value is 30. Allowed range is from 1 to 200. 7271 7272@item sizew 7273Set horizontal radius of rectangle used for averaging. 7274Allowed range is from 1 to 100. Default value is 5. 7275 7276@item sizeh 7277Set vertical radius of rectangle used for averaging. 7278Allowed range is from 1 to 100. Default value is 5. 7279 7280@item stepw 7281Set horizontal step when averaging. Default value is 1. 7282Allowed range is from 1 to 50. 7283Mostly useful to speed-up filtering. 7284 7285@item steph 7286Set vertical step when averaging. Default value is 1. 7287Allowed range is from 1 to 50. 7288Mostly useful to speed-up filtering. 7289@end table 7290 7291@subsection Commands 7292This filter supports same @ref{commands} as options. 7293The command accepts the same syntax of the corresponding option. 7294 7295@section chromashift 7296Shift chroma pixels horizontally and/or vertically. 7297 7298The filter accepts the following options: 7299@table @option 7300@item cbh 7301Set amount to shift chroma-blue horizontally. 7302@item cbv 7303Set amount to shift chroma-blue vertically. 7304@item crh 7305Set amount to shift chroma-red horizontally. 7306@item crv 7307Set amount to shift chroma-red vertically. 7308@item edge 7309Set edge mode, can be @var{smear}, default, or @var{warp}. 7310@end table 7311 7312@subsection Commands 7313 7314This filter supports the all above options as @ref{commands}. 7315 7316@section ciescope 7317 7318Display CIE color diagram with pixels overlaid onto it. 7319 7320The filter accepts the following options: 7321 7322@table @option 7323@item system 7324Set color system. 7325 7326@table @samp 7327@item ntsc, 470m 7328@item ebu, 470bg 7329@item smpte 7330@item 240m 7331@item apple 7332@item widergb 7333@item cie1931 7334@item rec709, hdtv 7335@item uhdtv, rec2020 7336@item dcip3 7337@end table 7338 7339@item cie 7340Set CIE system. 7341 7342@table @samp 7343@item xyy 7344@item ucs 7345@item luv 7346@end table 7347 7348@item gamuts 7349Set what gamuts to draw. 7350 7351See @code{system} option for available values. 7352 7353@item size, s 7354Set ciescope size, by default set to 512. 7355 7356@item intensity, i 7357Set intensity used to map input pixel values to CIE diagram. 7358 7359@item contrast 7360Set contrast used to draw tongue colors that are out of active color system gamut. 7361 7362@item corrgamma 7363Correct gamma displayed on scope, by default enabled. 7364 7365@item showwhite 7366Show white point on CIE diagram, by default disabled. 7367 7368@item gamma 7369Set input gamma. Used only with XYZ input color space. 7370@end table 7371 7372@section codecview 7373 7374Visualize information exported by some codecs. 7375 7376Some codecs can export information through frames using side-data or other 7377means. For example, some MPEG based codecs export motion vectors through the 7378@var{export_mvs} flag in the codec @option{flags2} option. 7379 7380The filter accepts the following option: 7381 7382@table @option 7383@item mv 7384Set motion vectors to visualize. 7385 7386Available flags for @var{mv} are: 7387 7388@table @samp 7389@item pf 7390forward predicted MVs of P-frames 7391@item bf 7392forward predicted MVs of B-frames 7393@item bb 7394backward predicted MVs of B-frames 7395@end table 7396 7397@item qp 7398Display quantization parameters using the chroma planes. 7399 7400@item mv_type, mvt 7401Set motion vectors type to visualize. Includes MVs from all frames unless specified by @var{frame_type} option. 7402 7403Available flags for @var{mv_type} are: 7404 7405@table @samp 7406@item fp 7407forward predicted MVs 7408@item bp 7409backward predicted MVs 7410@end table 7411 7412@item frame_type, ft 7413Set frame type to visualize motion vectors of. 7414 7415Available flags for @var{frame_type} are: 7416 7417@table @samp 7418@item if 7419intra-coded frames (I-frames) 7420@item pf 7421predicted frames (P-frames) 7422@item bf 7423bi-directionally predicted frames (B-frames) 7424@end table 7425@end table 7426 7427@subsection Examples 7428 7429@itemize 7430@item 7431Visualize forward predicted MVs of all frames using @command{ffplay}: 7432@example 7433ffplay -flags2 +export_mvs input.mp4 -vf codecview=mv_type=fp 7434@end example 7435 7436@item 7437Visualize multi-directionals MVs of P and B-Frames using @command{ffplay}: 7438@example 7439ffplay -flags2 +export_mvs input.mp4 -vf codecview=mv=pf+bf+bb 7440@end example 7441@end itemize 7442 7443@section colorbalance 7444Modify intensity of primary colors (red, green and blue) of input frames. 7445 7446The filter allows an input frame to be adjusted in the shadows, midtones or highlights 7447regions for the red-cyan, green-magenta or blue-yellow balance. 7448 7449A positive adjustment value shifts the balance towards the primary color, a negative 7450value towards the complementary color. 7451 7452The filter accepts the following options: 7453 7454@table @option 7455@item rs 7456@item gs 7457@item bs 7458Adjust red, green and blue shadows (darkest pixels). 7459 7460@item rm 7461@item gm 7462@item bm 7463Adjust red, green and blue midtones (medium pixels). 7464 7465@item rh 7466@item gh 7467@item bh 7468Adjust red, green and blue highlights (brightest pixels). 7469 7470Allowed ranges for options are @code{[-1.0, 1.0]}. Defaults are @code{0}. 7471 7472@item pl 7473Preserve lightness when changing color balance. Default is disabled. 7474@end table 7475 7476@subsection Examples 7477 7478@itemize 7479@item 7480Add red color cast to shadows: 7481@example 7482colorbalance=rs=.3 7483@end example 7484@end itemize 7485 7486@subsection Commands 7487 7488This filter supports the all above options as @ref{commands}. 7489 7490@section colorchannelmixer 7491 7492Adjust video input frames by re-mixing color channels. 7493 7494This filter modifies a color channel by adding the values associated to 7495the other channels of the same pixels. For example if the value to 7496modify is red, the output value will be: 7497@example 7498@var{red}=@var{red}*@var{rr} + @var{blue}*@var{rb} + @var{green}*@var{rg} + @var{alpha}*@var{ra} 7499@end example 7500 7501The filter accepts the following options: 7502 7503@table @option 7504@item rr 7505@item rg 7506@item rb 7507@item ra 7508Adjust contribution of input red, green, blue and alpha channels for output red channel. 7509Default is @code{1} for @var{rr}, and @code{0} for @var{rg}, @var{rb} and @var{ra}. 7510 7511@item gr 7512@item gg 7513@item gb 7514@item ga 7515Adjust contribution of input red, green, blue and alpha channels for output green channel. 7516Default is @code{1} for @var{gg}, and @code{0} for @var{gr}, @var{gb} and @var{ga}. 7517 7518@item br 7519@item bg 7520@item bb 7521@item ba 7522Adjust contribution of input red, green, blue and alpha channels for output blue channel. 7523Default is @code{1} for @var{bb}, and @code{0} for @var{br}, @var{bg} and @var{ba}. 7524 7525@item ar 7526@item ag 7527@item ab 7528@item aa 7529Adjust contribution of input red, green, blue and alpha channels for output alpha channel. 7530Default is @code{1} for @var{aa}, and @code{0} for @var{ar}, @var{ag} and @var{ab}. 7531 7532Allowed ranges for options are @code{[-2.0, 2.0]}. 7533@end table 7534 7535@subsection Examples 7536 7537@itemize 7538@item 7539Convert source to grayscale: 7540@example 7541colorchannelmixer=.3:.4:.3:0:.3:.4:.3:0:.3:.4:.3 7542@end example 7543@item 7544Simulate sepia tones: 7545@example 7546colorchannelmixer=.393:.769:.189:0:.349:.686:.168:0:.272:.534:.131 7547@end example 7548@end itemize 7549 7550@subsection Commands 7551 7552This filter supports the all above options as @ref{commands}. 7553 7554@section colorkey 7555RGB colorspace color keying. 7556 7557The filter accepts the following options: 7558 7559@table @option 7560@item color 7561The color which will be replaced with transparency. 7562 7563@item similarity 7564Similarity percentage with the key color. 7565 75660.01 matches only the exact key color, while 1.0 matches everything. 7567 7568@item blend 7569Blend percentage. 7570 75710.0 makes pixels either fully transparent, or not transparent at all. 7572 7573Higher values result in semi-transparent pixels, with a higher transparency 7574the more similar the pixels color is to the key color. 7575@end table 7576 7577@subsection Examples 7578 7579@itemize 7580@item 7581Make every green pixel in the input image transparent: 7582@example 7583ffmpeg -i input.png -vf colorkey=green out.png 7584@end example 7585 7586@item 7587Overlay a greenscreen-video on top of a static background image. 7588@example 7589ffmpeg -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 7590@end example 7591@end itemize 7592 7593@subsection Commands 7594This filter supports same @ref{commands} as options. 7595The command accepts the same syntax of the corresponding option. 7596 7597If the specified expression is not valid, it is kept at its current 7598value. 7599 7600@section colorhold 7601Remove all color information for all RGB colors except for certain one. 7602 7603The filter accepts the following options: 7604 7605@table @option 7606@item color 7607The color which will not be replaced with neutral gray. 7608 7609@item similarity 7610Similarity percentage with the above color. 76110.01 matches only the exact key color, while 1.0 matches everything. 7612 7613@item blend 7614Blend percentage. 0.0 makes pixels fully gray. 7615Higher values result in more preserved color. 7616@end table 7617 7618@subsection Commands 7619This filter supports same @ref{commands} as options. 7620The command accepts the same syntax of the corresponding option. 7621 7622If the specified expression is not valid, it is kept at its current 7623value. 7624 7625@section colorlevels 7626 7627Adjust video input frames using levels. 7628 7629The filter accepts the following options: 7630 7631@table @option 7632@item rimin 7633@item gimin 7634@item bimin 7635@item aimin 7636Adjust red, green, blue and alpha input black point. 7637Allowed ranges for options are @code{[-1.0, 1.0]}. Defaults are @code{0}. 7638 7639@item rimax 7640@item gimax 7641@item bimax 7642@item aimax 7643Adjust red, green, blue and alpha input white point. 7644Allowed ranges for options are @code{[-1.0, 1.0]}. Defaults are @code{1}. 7645 7646Input levels are used to lighten highlights (bright tones), darken shadows 7647(dark tones), change the balance of bright and dark tones. 7648 7649@item romin 7650@item gomin 7651@item bomin 7652@item aomin 7653Adjust red, green, blue and alpha output black point. 7654Allowed ranges for options are @code{[0, 1.0]}. Defaults are @code{0}. 7655 7656@item romax 7657@item gomax 7658@item bomax 7659@item aomax 7660Adjust red, green, blue and alpha output white point. 7661Allowed ranges for options are @code{[0, 1.0]}. Defaults are @code{1}. 7662 7663Output levels allows manual selection of a constrained output level range. 7664@end table 7665 7666@subsection Examples 7667 7668@itemize 7669@item 7670Make video output darker: 7671@example 7672colorlevels=rimin=0.058:gimin=0.058:bimin=0.058 7673@end example 7674 7675@item 7676Increase contrast: 7677@example 7678colorlevels=rimin=0.039:gimin=0.039:bimin=0.039:rimax=0.96:gimax=0.96:bimax=0.96 7679@end example 7680 7681@item 7682Make video output lighter: 7683@example 7684colorlevels=rimax=0.902:gimax=0.902:bimax=0.902 7685@end example 7686 7687@item 7688Increase brightness: 7689@example 7690colorlevels=romin=0.5:gomin=0.5:bomin=0.5 7691@end example 7692@end itemize 7693 7694@subsection Commands 7695 7696This filter supports the all above options as @ref{commands}. 7697 7698@section colormatrix 7699 7700Convert color matrix. 7701 7702The filter accepts the following options: 7703 7704@table @option 7705@item src 7706@item dst 7707Specify the source and destination color matrix. Both values must be 7708specified. 7709 7710The accepted values are: 7711@table @samp 7712@item bt709 7713BT.709 7714 7715@item fcc 7716FCC 7717 7718@item bt601 7719BT.601 7720 7721@item bt470 7722BT.470 7723 7724@item bt470bg 7725BT.470BG 7726 7727@item smpte170m 7728SMPTE-170M 7729 7730@item smpte240m 7731SMPTE-240M 7732 7733@item bt2020 7734BT.2020 7735@end table 7736@end table 7737 7738For example to convert from BT.601 to SMPTE-240M, use the command: 7739@example 7740colormatrix=bt601:smpte240m 7741@end example 7742 7743@section colorspace 7744 7745Convert colorspace, transfer characteristics or color primaries. 7746Input video needs to have an even size. 7747 7748The filter accepts the following options: 7749 7750@table @option 7751@anchor{all} 7752@item all 7753Specify all color properties at once. 7754 7755The accepted values are: 7756@table @samp 7757@item bt470m 7758BT.470M 7759 7760@item bt470bg 7761BT.470BG 7762 7763@item bt601-6-525 7764BT.601-6 525 7765 7766@item bt601-6-625 7767BT.601-6 625 7768 7769@item bt709 7770BT.709 7771 7772@item smpte170m 7773SMPTE-170M 7774 7775@item smpte240m 7776SMPTE-240M 7777 7778@item bt2020 7779BT.2020 7780 7781@end table 7782 7783@anchor{space} 7784@item space 7785Specify output colorspace. 7786 7787The accepted values are: 7788@table @samp 7789@item bt709 7790BT.709 7791 7792@item fcc 7793FCC 7794 7795@item bt470bg 7796BT.470BG or BT.601-6 625 7797 7798@item smpte170m 7799SMPTE-170M or BT.601-6 525 7800 7801@item smpte240m 7802SMPTE-240M 7803 7804@item ycgco 7805YCgCo 7806 7807@item bt2020ncl 7808BT.2020 with non-constant luminance 7809 7810@end table 7811 7812@anchor{trc} 7813@item trc 7814Specify output transfer characteristics. 7815 7816The accepted values are: 7817@table @samp 7818@item bt709 7819BT.709 7820 7821@item bt470m 7822BT.470M 7823 7824@item bt470bg 7825BT.470BG 7826 7827@item gamma22 7828Constant gamma of 2.2 7829 7830@item gamma28 7831Constant gamma of 2.8 7832 7833@item smpte170m 7834SMPTE-170M, BT.601-6 625 or BT.601-6 525 7835 7836@item smpte240m 7837SMPTE-240M 7838 7839@item srgb 7840SRGB 7841 7842@item iec61966-2-1 7843iec61966-2-1 7844 7845@item iec61966-2-4 7846iec61966-2-4 7847 7848@item xvycc 7849xvycc 7850 7851@item bt2020-10 7852BT.2020 for 10-bits content 7853 7854@item bt2020-12 7855BT.2020 for 12-bits content 7856 7857@end table 7858 7859@anchor{primaries} 7860@item primaries 7861Specify output color primaries. 7862 7863The accepted values are: 7864@table @samp 7865@item bt709 7866BT.709 7867 7868@item bt470m 7869BT.470M 7870 7871@item bt470bg 7872BT.470BG or BT.601-6 625 7873 7874@item smpte170m 7875SMPTE-170M or BT.601-6 525 7876 7877@item smpte240m 7878SMPTE-240M 7879 7880@item film 7881film 7882 7883@item smpte431 7884SMPTE-431 7885 7886@item smpte432 7887SMPTE-432 7888 7889@item bt2020 7890BT.2020 7891 7892@item jedec-p22 7893JEDEC P22 phosphors 7894 7895@end table 7896 7897@anchor{range} 7898@item range 7899Specify output color range. 7900 7901The accepted values are: 7902@table @samp 7903@item tv 7904TV (restricted) range 7905 7906@item mpeg 7907MPEG (restricted) range 7908 7909@item pc 7910PC (full) range 7911 7912@item jpeg 7913JPEG (full) range 7914 7915@end table 7916 7917@item format 7918Specify output color format. 7919 7920The accepted values are: 7921@table @samp 7922@item yuv420p 7923YUV 4:2:0 planar 8-bits 7924 7925@item yuv420p10 7926YUV 4:2:0 planar 10-bits 7927 7928@item yuv420p12 7929YUV 4:2:0 planar 12-bits 7930 7931@item yuv422p 7932YUV 4:2:2 planar 8-bits 7933 7934@item yuv422p10 7935YUV 4:2:2 planar 10-bits 7936 7937@item yuv422p12 7938YUV 4:2:2 planar 12-bits 7939 7940@item yuv444p 7941YUV 4:4:4 planar 8-bits 7942 7943@item yuv444p10 7944YUV 4:4:4 planar 10-bits 7945 7946@item yuv444p12 7947YUV 4:4:4 planar 12-bits 7948 7949@end table 7950 7951@item fast 7952Do a fast conversion, which skips gamma/primary correction. This will take 7953significantly less CPU, but will be mathematically incorrect. To get output 7954compatible with that produced by the colormatrix filter, use fast=1. 7955 7956@item dither 7957Specify dithering mode. 7958 7959The accepted values are: 7960@table @samp 7961@item none 7962No dithering 7963 7964@item fsb 7965Floyd-Steinberg dithering 7966@end table 7967 7968@item wpadapt 7969Whitepoint adaptation mode. 7970 7971The accepted values are: 7972@table @samp 7973@item bradford 7974Bradford whitepoint adaptation 7975 7976@item vonkries 7977von Kries whitepoint adaptation 7978 7979@item identity 7980identity whitepoint adaptation (i.e. no whitepoint adaptation) 7981@end table 7982 7983@item iall 7984Override all input properties at once. Same accepted values as @ref{all}. 7985 7986@item ispace 7987Override input colorspace. Same accepted values as @ref{space}. 7988 7989@item iprimaries 7990Override input color primaries. Same accepted values as @ref{primaries}. 7991 7992@item itrc 7993Override input transfer characteristics. Same accepted values as @ref{trc}. 7994 7995@item irange 7996Override input color range. Same accepted values as @ref{range}. 7997 7998@end table 7999 8000The filter converts the transfer characteristics, color space and color 8001primaries to the specified user values. The output value, if not specified, 8002is set to a default value based on the "all" property. If that property is 8003also not specified, the filter will log an error. The output color range and 8004format default to the same value as the input color range and format. The 8005input transfer characteristics, color space, color primaries and color range 8006should be set on the input data. If any of these are missing, the filter will 8007log an error and no conversion will take place. 8008 8009For example to convert the input to SMPTE-240M, use the command: 8010@example 8011colorspace=smpte240m 8012@end example 8013 8014@section convolution 8015 8016Apply convolution of 3x3, 5x5, 7x7 or horizontal/vertical up to 49 elements. 8017 8018The filter accepts the following options: 8019 8020@table @option 8021@item 0m 8022@item 1m 8023@item 2m 8024@item 3m 8025Set matrix for each plane. 8026Matrix is sequence of 9, 25 or 49 signed integers in @var{square} mode, 8027and from 1 to 49 odd number of signed integers in @var{row} mode. 8028 8029@item 0rdiv 8030@item 1rdiv 8031@item 2rdiv 8032@item 3rdiv 8033Set multiplier for calculated value for each plane. 8034If unset or 0, it will be sum of all matrix elements. 8035 8036@item 0bias 8037@item 1bias 8038@item 2bias 8039@item 3bias 8040Set bias for each plane. This value is added to the result of the multiplication. 8041Useful for making the overall image brighter or darker. Default is 0.0. 8042 8043@item 0mode 8044@item 1mode 8045@item 2mode 8046@item 3mode 8047Set matrix mode for each plane. Can be @var{square}, @var{row} or @var{column}. 8048Default is @var{square}. 8049@end table 8050 8051@subsection Examples 8052 8053@itemize 8054@item 8055Apply sharpen: 8056@example 8057convolution="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" 8058@end example 8059 8060@item 8061Apply blur: 8062@example 8063convolution="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" 8064@end example 8065 8066@item 8067Apply edge enhance: 8068@example 8069convolution="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" 8070@end example 8071 8072@item 8073Apply edge detect: 8074@example 8075convolution="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" 8076@end example 8077 8078@item 8079Apply laplacian edge detector which includes diagonals: 8080@example 8081convolution="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" 8082@end example 8083 8084@item 8085Apply emboss: 8086@example 8087convolution="-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" 8088@end example 8089@end itemize 8090 8091@section convolve 8092 8093Apply 2D convolution of video stream in frequency domain using second stream 8094as impulse. 8095 8096The filter accepts the following options: 8097 8098@table @option 8099@item planes 8100Set which planes to process. 8101 8102@item impulse 8103Set which impulse video frames will be processed, can be @var{first} 8104or @var{all}. Default is @var{all}. 8105@end table 8106 8107The @code{convolve} filter also supports the @ref{framesync} options. 8108 8109@section copy 8110 8111Copy the input video source unchanged to the output. This is mainly useful for 8112testing purposes. 8113 8114@anchor{coreimage} 8115@section coreimage 8116Video filtering on GPU using Apple's CoreImage API on OSX. 8117 8118Hardware acceleration is based on an OpenGL context. Usually, this means it is 8119processed by video hardware. However, software-based OpenGL implementations 8120exist which means there is no guarantee for hardware processing. It depends on 8121the respective OSX. 8122 8123There are many filters and image generators provided by Apple that come with a 8124large variety of options. The filter has to be referenced by its name along 8125with its options. 8126 8127The coreimage filter accepts the following options: 8128@table @option 8129@item list_filters 8130List all available filters and generators along with all their respective 8131options as well as possible minimum and maximum values along with the default 8132values. 8133@example 8134list_filters=true 8135@end example 8136 8137@item filter 8138Specify all filters by their respective name and options. 8139Use @var{list_filters} to determine all valid filter names and options. 8140Numerical options are specified by a float value and are automatically clamped 8141to their respective value range. Vector and color options have to be specified 8142by a list of space separated float values. Character escaping has to be done. 8143A special option name @code{default} is available to use default options for a 8144filter. 8145 8146It is required to specify either @code{default} or at least one of the filter options. 8147All omitted options are used with their default values. 8148The syntax of the filter string is as follows: 8149@example 8150filter=<NAME>@@<OPTION>=<VALUE>[@@<OPTION>=<VALUE>][@@...][#<NAME>@@<OPTION>=<VALUE>[@@<OPTION>=<VALUE>][@@...]][#...] 8151@end example 8152 8153@item output_rect 8154Specify a rectangle where the output of the filter chain is copied into the 8155input image. It is given by a list of space separated float values: 8156@example 8157output_rect=x\ y\ width\ height 8158@end example 8159If not given, the output rectangle equals the dimensions of the input image. 8160The output rectangle is automatically cropped at the borders of the input 8161image. Negative values are valid for each component. 8162@example 8163output_rect=25\ 25\ 100\ 100 8164@end example 8165@end table 8166 8167Several filters can be chained for successive processing without GPU-HOST 8168transfers allowing for fast processing of complex filter chains. 8169Currently, only filters with zero (generators) or exactly one (filters) input 8170image and one output image are supported. Also, transition filters are not yet 8171usable as intended. 8172 8173Some filters generate output images with additional padding depending on the 8174respective filter kernel. The padding is automatically removed to ensure the 8175filter output has the same size as the input image. 8176 8177For image generators, the size of the output image is determined by the 8178previous output image of the filter chain or the input image of the whole 8179filterchain, respectively. The generators do not use the pixel information of 8180this image to generate their output. However, the generated output is 8181blended onto this image, resulting in partial or complete coverage of the 8182output image. 8183 8184The @ref{coreimagesrc} video source can be used for generating input images 8185which are directly fed into the filter chain. By using it, providing input 8186images by another video source or an input video is not required. 8187 8188@subsection Examples 8189 8190@itemize 8191 8192@item 8193List all filters available: 8194@example 8195coreimage=list_filters=true 8196@end example 8197 8198@item 8199Use the CIBoxBlur filter with default options to blur an image: 8200@example 8201coreimage=filter=CIBoxBlur@@default 8202@end example 8203 8204@item 8205Use a filter chain with CISepiaTone at default values and CIVignetteEffect with 8206its center at 100x100 and a radius of 50 pixels: 8207@example 8208coreimage=filter=CIBoxBlur@@default#CIVignetteEffect@@inputCenter=100\ 100@@inputRadius=50 8209@end example 8210 8211@item 8212Use nullsrc and CIQRCodeGenerator to create a QR code for the FFmpeg homepage, 8213given as complete and escaped command-line for Apple's standard bash shell: 8214@example 8215ffmpeg -f lavfi -i nullsrc=s=100x100,coreimage=filter=CIQRCodeGenerator@@inputMessage=https\\\\\://FFmpeg.org/@@inputCorrectionLevel=H -frames:v 1 QRCode.png 8216@end example 8217@end itemize 8218 8219@section cover_rect 8220 8221Cover a rectangular object 8222 8223It accepts the following options: 8224 8225@table @option 8226@item cover 8227Filepath of the optional cover image, needs to be in yuv420. 8228 8229@item mode 8230Set covering mode. 8231 8232It accepts the following values: 8233@table @samp 8234@item cover 8235cover it by the supplied image 8236@item blur 8237cover it by interpolating the surrounding pixels 8238@end table 8239 8240Default value is @var{blur}. 8241@end table 8242 8243@subsection Examples 8244 8245@itemize 8246@item 8247Cover a rectangular object by the supplied image of a given video using @command{ffmpeg}: 8248@example 8249ffmpeg -i file.ts -vf find_rect=newref.pgm,cover_rect=cover.jpg:mode=cover new.mkv 8250@end example 8251@end itemize 8252 8253@section crop 8254 8255Crop the input video to given dimensions. 8256 8257It accepts the following parameters: 8258 8259@table @option 8260@item w, out_w 8261The width of the output video. It defaults to @code{iw}. 8262This expression is evaluated only once during the filter 8263configuration, or when the @samp{w} or @samp{out_w} command is sent. 8264 8265@item h, out_h 8266The height of the output video. It defaults to @code{ih}. 8267This expression is evaluated only once during the filter 8268configuration, or when the @samp{h} or @samp{out_h} command is sent. 8269 8270@item x 8271The horizontal position, in the input video, of the left edge of the output 8272video. It defaults to @code{(in_w-out_w)/2}. 8273This expression is evaluated per-frame. 8274 8275@item y 8276The vertical position, in the input video, of the top edge of the output video. 8277It defaults to @code{(in_h-out_h)/2}. 8278This expression is evaluated per-frame. 8279 8280@item keep_aspect 8281If set to 1 will force the output display aspect ratio 8282to be the same of the input, by changing the output sample aspect 8283ratio. It defaults to 0. 8284 8285@item exact 8286Enable exact cropping. If enabled, subsampled videos will be cropped at exact 8287width/height/x/y as specified and will not be rounded to nearest smaller value. 8288It defaults to 0. 8289@end table 8290 8291The @var{out_w}, @var{out_h}, @var{x}, @var{y} parameters are 8292expressions containing the following constants: 8293 8294@table @option 8295@item x 8296@item y 8297The computed values for @var{x} and @var{y}. They are evaluated for 8298each new frame. 8299 8300@item in_w 8301@item in_h 8302The input width and height. 8303 8304@item iw 8305@item ih 8306These are the same as @var{in_w} and @var{in_h}. 8307 8308@item out_w 8309@item out_h 8310The output (cropped) width and height. 8311 8312@item ow 8313@item oh 8314These are the same as @var{out_w} and @var{out_h}. 8315 8316@item a 8317same as @var{iw} / @var{ih} 8318 8319@item sar 8320input sample aspect ratio 8321 8322@item dar 8323input display aspect ratio, it is the same as (@var{iw} / @var{ih}) * @var{sar} 8324 8325@item hsub 8326@item vsub 8327horizontal and vertical chroma subsample values. For example for the 8328pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1. 8329 8330@item n 8331The number of the input frame, starting from 0. 8332 8333@item pos 8334the position in the file of the input frame, NAN if unknown 8335 8336@item t 8337The timestamp expressed in seconds. It's NAN if the input timestamp is unknown. 8338 8339@end table 8340 8341The expression for @var{out_w} may depend on the value of @var{out_h}, 8342and the expression for @var{out_h} may depend on @var{out_w}, but they 8343cannot depend on @var{x} and @var{y}, as @var{x} and @var{y} are 8344evaluated after @var{out_w} and @var{out_h}. 8345 8346The @var{x} and @var{y} parameters specify the expressions for the 8347position of the top-left corner of the output (non-cropped) area. They 8348are evaluated for each frame. If the evaluated value is not valid, it 8349is approximated to the nearest valid value. 8350 8351The expression for @var{x} may depend on @var{y}, and the expression 8352for @var{y} may depend on @var{x}. 8353 8354@subsection Examples 8355 8356@itemize 8357@item 8358Crop area with size 100x100 at position (12,34). 8359@example 8360crop=100:100:12:34 8361@end example 8362 8363Using named options, the example above becomes: 8364@example 8365crop=w=100:h=100:x=12:y=34 8366@end example 8367 8368@item 8369Crop the central input area with size 100x100: 8370@example 8371crop=100:100 8372@end example 8373 8374@item 8375Crop the central input area with size 2/3 of the input video: 8376@example 8377crop=2/3*in_w:2/3*in_h 8378@end example 8379 8380@item 8381Crop the input video central square: 8382@example 8383crop=out_w=in_h 8384crop=in_h 8385@end example 8386 8387@item 8388Delimit the rectangle with the top-left corner placed at position 8389100:100 and the right-bottom corner corresponding to the right-bottom 8390corner of the input image. 8391@example 8392crop=in_w-100:in_h-100:100:100 8393@end example 8394 8395@item 8396Crop 10 pixels from the left and right borders, and 20 pixels from 8397the top and bottom borders 8398@example 8399crop=in_w-2*10:in_h-2*20 8400@end example 8401 8402@item 8403Keep only the bottom right quarter of the input image: 8404@example 8405crop=in_w/2:in_h/2:in_w/2:in_h/2 8406@end example 8407 8408@item 8409Crop height for getting Greek harmony: 8410@example 8411crop=in_w:1/PHI*in_w 8412@end example 8413 8414@item 8415Apply trembling effect: 8416@example 8417crop=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) 8418@end example 8419 8420@item 8421Apply erratic camera effect depending on timestamp: 8422@example 8423crop=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)" 8424@end example 8425 8426@item 8427Set x depending on the value of y: 8428@example 8429crop=in_w/2:in_h/2:y:10+10*sin(n/10) 8430@end example 8431@end itemize 8432 8433@subsection Commands 8434 8435This filter supports the following commands: 8436@table @option 8437@item w, out_w 8438@item h, out_h 8439@item x 8440@item y 8441Set width/height of the output video and the horizontal/vertical position 8442in the input video. 8443The command accepts the same syntax of the corresponding option. 8444 8445If the specified expression is not valid, it is kept at its current 8446value. 8447@end table 8448 8449@section cropdetect 8450 8451Auto-detect the crop size. 8452 8453It calculates the necessary cropping parameters and prints the 8454recommended parameters via the logging system. The detected dimensions 8455correspond to the non-black area of the input video. 8456 8457It accepts the following parameters: 8458 8459@table @option 8460 8461@item limit 8462Set higher black value threshold, which can be optionally specified 8463from nothing (0) to everything (255 for 8-bit based formats). An intensity 8464value greater to the set value is considered non-black. It defaults to 24. 8465You can also specify a value between 0.0 and 1.0 which will be scaled depending 8466on the bitdepth of the pixel format. 8467 8468@item round 8469The value which the width/height should be divisible by. It defaults to 847016. The offset is automatically adjusted to center the video. Use 2 to 8471get only even dimensions (needed for 4:2:2 video). 16 is best when 8472encoding to most video codecs. 8473 8474@item reset_count, reset 8475Set the counter that determines after how many frames cropdetect will 8476reset the previously detected largest video area and start over to 8477detect the current optimal crop area. Default value is 0. 8478 8479This can be useful when channel logos distort the video area. 0 8480indicates 'never reset', and returns the largest area encountered during 8481playback. 8482@end table 8483 8484@anchor{cue} 8485@section cue 8486 8487Delay video filtering until a given wallclock timestamp. The filter first 8488passes on @option{preroll} amount of frames, then it buffers at most 8489@option{buffer} amount of frames and waits for the cue. After reaching the cue 8490it forwards the buffered frames and also any subsequent frames coming in its 8491input. 8492 8493The filter can be used synchronize the output of multiple ffmpeg processes for 8494realtime output devices like decklink. By putting the delay in the filtering 8495chain and pre-buffering frames the process can pass on data to output almost 8496immediately after the target wallclock timestamp is reached. 8497 8498Perfect frame accuracy cannot be guaranteed, but the result is good enough for 8499some use cases. 8500 8501@table @option 8502 8503@item cue 8504The cue timestamp expressed in a UNIX timestamp in microseconds. Default is 0. 8505 8506@item preroll 8507The duration of content to pass on as preroll expressed in seconds. Default is 0. 8508 8509@item buffer 8510The maximum duration of content to buffer before waiting for the cue expressed 8511in seconds. Default is 0. 8512 8513@end table 8514 8515@anchor{curves} 8516@section curves 8517 8518Apply color adjustments using curves. 8519 8520This filter is similar to the Adobe Photoshop and GIMP curves tools. Each 8521component (red, green and blue) has its values defined by @var{N} key points 8522tied from each other using a smooth curve. The x-axis represents the pixel 8523values from the input frame, and the y-axis the new pixel values to be set for 8524the output frame. 8525 8526By default, a component curve is defined by the two points @var{(0;0)} and 8527@var{(1;1)}. This creates a straight line where each original pixel value is 8528"adjusted" to its own value, which means no change to the image. 8529 8530The filter allows you to redefine these two points and add some more. A new 8531curve (using a natural cubic spline interpolation) will be define to pass 8532smoothly through all these new coordinates. The new defined points needs to be 8533strictly increasing over the x-axis, and their @var{x} and @var{y} values must 8534be in the @var{[0;1]} interval. If the computed curves happened to go outside 8535the vector spaces, the values will be clipped accordingly. 8536 8537The filter accepts the following options: 8538 8539@table @option 8540@item preset 8541Select one of the available color presets. This option can be used in addition 8542to the @option{r}, @option{g}, @option{b} parameters; in this case, the later 8543options takes priority on the preset values. 8544Available presets are: 8545@table @samp 8546@item none 8547@item color_negative 8548@item cross_process 8549@item darker 8550@item increase_contrast 8551@item lighter 8552@item linear_contrast 8553@item medium_contrast 8554@item negative 8555@item strong_contrast 8556@item vintage 8557@end table 8558Default is @code{none}. 8559@item master, m 8560Set the master key points. These points will define a second pass mapping. It 8561is sometimes called a "luminance" or "value" mapping. It can be used with 8562@option{r}, @option{g}, @option{b} or @option{all} since it acts like a 8563post-processing LUT. 8564@item red, r 8565Set the key points for the red component. 8566@item green, g 8567Set the key points for the green component. 8568@item blue, b 8569Set the key points for the blue component. 8570@item all 8571Set the key points for all components (not including master). 8572Can be used in addition to the other key points component 8573options. In this case, the unset component(s) will fallback on this 8574@option{all} setting. 8575@item psfile 8576Specify a Photoshop curves file (@code{.acv}) to import the settings from. 8577@item plot 8578Save Gnuplot script of the curves in specified file. 8579@end table 8580 8581To avoid some filtergraph syntax conflicts, each key points list need to be 8582defined using the following syntax: @code{x0/y0 x1/y1 x2/y2 ...}. 8583 8584@subsection Examples 8585 8586@itemize 8587@item 8588Increase slightly the middle level of blue: 8589@example 8590curves=blue='0/0 0.5/0.58 1/1' 8591@end example 8592 8593@item 8594Vintage effect: 8595@example 8596curves=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' 8597@end example 8598Here we obtain the following coordinates for each components: 8599@table @var 8600@item red 8601@code{(0;0.11) (0.42;0.51) (1;0.95)} 8602@item green 8603@code{(0;0) (0.50;0.48) (1;1)} 8604@item blue 8605@code{(0;0.22) (0.49;0.44) (1;0.80)} 8606@end table 8607 8608@item 8609The previous example can also be achieved with the associated built-in preset: 8610@example 8611curves=preset=vintage 8612@end example 8613 8614@item 8615Or simply: 8616@example 8617curves=vintage 8618@end example 8619 8620@item 8621Use a Photoshop preset and redefine the points of the green component: 8622@example 8623curves=psfile='MyCurvesPresets/purple.acv':green='0/0 0.45/0.53 1/1' 8624@end example 8625 8626@item 8627Check out the curves of the @code{cross_process} profile using @command{ffmpeg} 8628and @command{gnuplot}: 8629@example 8630ffmpeg -f lavfi -i color -vf curves=cross_process:plot=/tmp/curves.plt -frames:v 1 -f null - 8631gnuplot -p /tmp/curves.plt 8632@end example 8633@end itemize 8634 8635@section datascope 8636 8637Video data analysis filter. 8638 8639This filter shows hexadecimal pixel values of part of video. 8640 8641The filter accepts the following options: 8642 8643@table @option 8644@item size, s 8645Set output video size. 8646 8647@item x 8648Set x offset from where to pick pixels. 8649 8650@item y 8651Set y offset from where to pick pixels. 8652 8653@item mode 8654Set scope mode, can be one of the following: 8655@table @samp 8656@item mono 8657Draw hexadecimal pixel values with white color on black background. 8658 8659@item color 8660Draw hexadecimal pixel values with input video pixel color on black 8661background. 8662 8663@item color2 8664Draw hexadecimal pixel values on color background picked from input video, 8665the text color is picked in such way so its always visible. 8666@end table 8667 8668@item axis 8669Draw rows and columns numbers on left and top of video. 8670 8671@item opacity 8672Set background opacity. 8673 8674@item format 8675Set display number format. Can be @code{hex}, or @code{dec}. Default is @code{hex}. 8676@end table 8677 8678@section dblur 8679Apply Directional blur filter. 8680 8681The filter accepts the following options: 8682 8683@table @option 8684@item angle 8685Set angle of directional blur. Default is @code{45}. 8686 8687@item radius 8688Set radius of directional blur. Default is @code{5}. 8689 8690@item planes 8691Set which planes to filter. By default all planes are filtered. 8692@end table 8693 8694@subsection Commands 8695This filter supports same @ref{commands} as options. 8696The command accepts the same syntax of the corresponding option. 8697 8698If the specified expression is not valid, it is kept at its current 8699value. 8700 8701@section dctdnoiz 8702 8703Denoise frames using 2D DCT (frequency domain filtering). 8704 8705This filter is not designed for real time. 8706 8707The filter accepts the following options: 8708 8709@table @option 8710@item sigma, s 8711Set the noise sigma constant. 8712 8713This @var{sigma} defines a hard threshold of @code{3 * sigma}; every DCT 8714coefficient (absolute value) below this threshold with be dropped. 8715 8716If you need a more advanced filtering, see @option{expr}. 8717 8718Default is @code{0}. 8719 8720@item overlap 8721Set number overlapping pixels for each block. Since the filter can be slow, you 8722may want to reduce this value, at the cost of a less effective filter and the 8723risk of various artefacts. 8724 8725If the overlapping value doesn't permit processing the whole input width or 8726height, a warning will be displayed and according borders won't be denoised. 8727 8728Default value is @var{blocksize}-1, which is the best possible setting. 8729 8730@item expr, e 8731Set the coefficient factor expression. 8732 8733For each coefficient of a DCT block, this expression will be evaluated as a 8734multiplier value for the coefficient. 8735 8736If this is option is set, the @option{sigma} option will be ignored. 8737 8738The absolute value of the coefficient can be accessed through the @var{c} 8739variable. 8740 8741@item n 8742Set the @var{blocksize} using the number of bits. @code{1<<@var{n}} defines the 8743@var{blocksize}, which is the width and height of the processed blocks. 8744 8745The default value is @var{3} (8x8) and can be raised to @var{4} for a 8746@var{blocksize} of 16x16. Note that changing this setting has huge consequences 8747on the speed processing. Also, a larger block size does not necessarily means a 8748better de-noising. 8749@end table 8750 8751@subsection Examples 8752 8753Apply a denoise with a @option{sigma} of @code{4.5}: 8754@example 8755dctdnoiz=4.5 8756@end example 8757 8758The same operation can be achieved using the expression system: 8759@example 8760dctdnoiz=e='gte(c, 4.5*3)' 8761@end example 8762 8763Violent denoise using a block size of @code{16x16}: 8764@example 8765dctdnoiz=15:n=4 8766@end example 8767 8768@section deband 8769 8770Remove banding artifacts from input video. 8771It works by replacing banded pixels with average value of referenced pixels. 8772 8773The filter accepts the following options: 8774 8775@table @option 8776@item 1thr 8777@item 2thr 8778@item 3thr 8779@item 4thr 8780Set banding detection threshold for each plane. Default is 0.02. 8781Valid range is 0.00003 to 0.5. 8782If difference between current pixel and reference pixel is less than threshold, 8783it will be considered as banded. 8784 8785@item range, r 8786Banding detection range in pixels. Default is 16. If positive, random number 8787in range 0 to set value will be used. If negative, exact absolute value 8788will be used. 8789The range defines square of four pixels around current pixel. 8790 8791@item direction, d 8792Set direction in radians from which four pixel will be compared. If positive, 8793random direction from 0 to set direction will be picked. If negative, exact of 8794absolute value will be picked. For example direction 0, -PI or -2*PI radians 8795will pick only pixels on same row and -PI/2 will pick only pixels on same 8796column. 8797 8798@item blur, b 8799If enabled, current pixel is compared with average value of all four 8800surrounding pixels. The default is enabled. If disabled current pixel is 8801compared with all four surrounding pixels. The pixel is considered banded 8802if only all four differences with surrounding pixels are less than threshold. 8803 8804@item coupling, c 8805If enabled, current pixel is changed if and only if all pixel components are banded, 8806e.g. banding detection threshold is triggered for all color components. 8807The default is disabled. 8808@end table 8809 8810@section deblock 8811 8812Remove blocking artifacts from input video. 8813 8814The filter accepts the following options: 8815 8816@table @option 8817@item filter 8818Set filter type, can be @var{weak} or @var{strong}. Default is @var{strong}. 8819This controls what kind of deblocking is applied. 8820 8821@item block 8822Set size of block, allowed range is from 4 to 512. Default is @var{8}. 8823 8824@item alpha 8825@item beta 8826@item gamma 8827@item delta 8828Set blocking detection thresholds. Allowed range is 0 to 1. 8829Defaults are: @var{0.098} for @var{alpha} and @var{0.05} for the rest. 8830Using higher threshold gives more deblocking strength. 8831Setting @var{alpha} controls threshold detection at exact edge of block. 8832Remaining options controls threshold detection near the edge. Each one for 8833below/above or left/right. Setting any of those to @var{0} disables 8834deblocking. 8835 8836@item planes 8837Set planes to filter. Default is to filter all available planes. 8838@end table 8839 8840@subsection Examples 8841 8842@itemize 8843@item 8844Deblock using weak filter and block size of 4 pixels. 8845@example 8846deblock=filter=weak:block=4 8847@end example 8848 8849@item 8850Deblock using strong filter, block size of 4 pixels and custom thresholds for 8851deblocking more edges. 8852@example 8853deblock=filter=strong:block=4:alpha=0.12:beta=0.07:gamma=0.06:delta=0.05 8854@end example 8855 8856@item 8857Similar as above, but filter only first plane. 8858@example 8859deblock=filter=strong:block=4:alpha=0.12:beta=0.07:gamma=0.06:delta=0.05:planes=1 8860@end example 8861 8862@item 8863Similar as above, but filter only second and third plane. 8864@example 8865deblock=filter=strong:block=4:alpha=0.12:beta=0.07:gamma=0.06:delta=0.05:planes=6 8866@end example 8867@end itemize 8868 8869@anchor{decimate} 8870@section decimate 8871 8872Drop duplicated frames at regular intervals. 8873 8874The filter accepts the following options: 8875 8876@table @option 8877@item cycle 8878Set the number of frames from which one will be dropped. Setting this to 8879@var{N} means one frame in every batch of @var{N} frames will be dropped. 8880Default is @code{5}. 8881 8882@item dupthresh 8883Set the threshold for duplicate detection. If the difference metric for a frame 8884is less than or equal to this value, then it is declared as duplicate. Default 8885is @code{1.1} 8886 8887@item scthresh 8888Set scene change threshold. Default is @code{15}. 8889 8890@item blockx 8891@item blocky 8892Set the size of the x and y-axis blocks used during metric calculations. 8893Larger blocks give better noise suppression, but also give worse detection of 8894small movements. Must be a power of two. Default is @code{32}. 8895 8896@item ppsrc 8897Mark main input as a pre-processed input and activate clean source input 8898stream. This allows the input to be pre-processed with various filters to help 8899the metrics calculation while keeping the frame selection lossless. When set to 8900@code{1}, the first stream is for the pre-processed input, and the second 8901stream is the clean source from where the kept frames are chosen. Default is 8902@code{0}. 8903 8904@item chroma 8905Set whether or not chroma is considered in the metric calculations. Default is 8906@code{1}. 8907@end table 8908 8909@section deconvolve 8910 8911Apply 2D deconvolution of video stream in frequency domain using second stream 8912as impulse. 8913 8914The filter accepts the following options: 8915 8916@table @option 8917@item planes 8918Set which planes to process. 8919 8920@item impulse 8921Set which impulse video frames will be processed, can be @var{first} 8922or @var{all}. Default is @var{all}. 8923 8924@item noise 8925Set noise when doing divisions. Default is @var{0.0000001}. Useful when width 8926and height are not same and not power of 2 or if stream prior to convolving 8927had noise. 8928@end table 8929 8930The @code{deconvolve} filter also supports the @ref{framesync} options. 8931 8932@section dedot 8933 8934Reduce cross-luminance (dot-crawl) and cross-color (rainbows) from video. 8935 8936It accepts the following options: 8937 8938@table @option 8939@item m 8940Set mode of operation. Can be combination of @var{dotcrawl} for cross-luminance reduction and/or 8941@var{rainbows} for cross-color reduction. 8942 8943@item lt 8944Set spatial luma threshold. Lower values increases reduction of cross-luminance. 8945 8946@item tl 8947Set tolerance for temporal luma. Higher values increases reduction of cross-luminance. 8948 8949@item tc 8950Set tolerance for chroma temporal variation. Higher values increases reduction of cross-color. 8951 8952@item ct 8953Set temporal chroma threshold. Lower values increases reduction of cross-color. 8954@end table 8955 8956@section deflate 8957 8958Apply deflate effect to the video. 8959 8960This filter replaces the pixel by the local(3x3) average by taking into account 8961only values lower than the pixel. 8962 8963It accepts the following options: 8964 8965@table @option 8966@item threshold0 8967@item threshold1 8968@item threshold2 8969@item threshold3 8970Limit the maximum change for each plane, default is 65535. 8971If 0, plane will remain unchanged. 8972@end table 8973 8974@subsection Commands 8975 8976This filter supports the all above options as @ref{commands}. 8977 8978@section deflicker 8979 8980Remove temporal frame luminance variations. 8981 8982It accepts the following options: 8983 8984@table @option 8985@item size, s 8986Set moving-average filter size in frames. Default is 5. Allowed range is 2 - 129. 8987 8988@item mode, m 8989Set averaging mode to smooth temporal luminance variations. 8990 8991Available values are: 8992@table @samp 8993@item am 8994Arithmetic mean 8995 8996@item gm 8997Geometric mean 8998 8999@item hm 9000Harmonic mean 9001 9002@item qm 9003Quadratic mean 9004 9005@item cm 9006Cubic mean 9007 9008@item pm 9009Power mean 9010 9011@item median 9012Median 9013@end table 9014 9015@item bypass 9016Do not actually modify frame. Useful when one only wants metadata. 9017@end table 9018 9019@section dejudder 9020 9021Remove judder produced by partially interlaced telecined content. 9022 9023Judder can be introduced, for instance, by @ref{pullup} filter. If the original 9024source was partially telecined content then the output of @code{pullup,dejudder} 9025will have a variable frame rate. May change the recorded frame rate of the 9026container. Aside from that change, this filter will not affect constant frame 9027rate video. 9028 9029The option available in this filter is: 9030@table @option 9031 9032@item cycle 9033Specify the length of the window over which the judder repeats. 9034 9035Accepts any integer greater than 1. Useful values are: 9036@table @samp 9037 9038@item 4 9039If the original was telecined from 24 to 30 fps (Film to NTSC). 9040 9041@item 5 9042If the original was telecined from 25 to 30 fps (PAL to NTSC). 9043 9044@item 20 9045If a mixture of the two. 9046@end table 9047 9048The default is @samp{4}. 9049@end table 9050 9051@section delogo 9052 9053Suppress a TV station logo by a simple interpolation of the surrounding 9054pixels. Just set a rectangle covering the logo and watch it disappear 9055(and sometimes something even uglier appear - your mileage may vary). 9056 9057It accepts the following parameters: 9058@table @option 9059 9060@item x 9061@item y 9062Specify the top left corner coordinates of the logo. They must be 9063specified. 9064 9065@item w 9066@item h 9067Specify the width and height of the logo to clear. They must be 9068specified. 9069 9070@item band, t 9071Specify the thickness of the fuzzy edge of the rectangle (added to 9072@var{w} and @var{h}). The default value is 1. This option is 9073deprecated, setting higher values should no longer be necessary and 9074is not recommended. 9075 9076@item show 9077When set to 1, a green rectangle is drawn on the screen to simplify 9078finding the right @var{x}, @var{y}, @var{w}, and @var{h} parameters. 9079The default value is 0. 9080 9081The rectangle is drawn on the outermost pixels which will be (partly) 9082replaced with interpolated values. The values of the next pixels 9083immediately outside this rectangle in each direction will be used to 9084compute the interpolated pixel values inside the rectangle. 9085 9086@end table 9087 9088@subsection Examples 9089 9090@itemize 9091@item 9092Set a rectangle covering the area with top left corner coordinates 0,0 9093and size 100x77, and a band of size 10: 9094@example 9095delogo=x=0:y=0:w=100:h=77:band=10 9096@end example 9097 9098@end itemize 9099 9100@anchor{derain} 9101@section derain 9102 9103Remove the rain in the input image/video by applying the derain methods based on 9104convolutional neural networks. Supported models: 9105 9106@itemize 9107@item 9108Recurrent Squeeze-and-Excitation Context Aggregation Net (RESCAN). 9109See @url{http://openaccess.thecvf.com/content_ECCV_2018/papers/Xia_Li_Recurrent_Squeeze-and-Excitation_Context_ECCV_2018_paper.pdf}. 9110@end itemize 9111 9112Training as well as model generation scripts are provided in 9113the repository at @url{https://github.com/XueweiMeng/derain_filter.git}. 9114 9115Native model files (.model) can be generated from TensorFlow model 9116files (.pb) by using tools/python/convert.py 9117 9118The filter accepts the following options: 9119 9120@table @option 9121@item filter_type 9122Specify which filter to use. This option accepts the following values: 9123 9124@table @samp 9125@item derain 9126Derain filter. To conduct derain filter, you need to use a derain model. 9127 9128@item dehaze 9129Dehaze filter. To conduct dehaze filter, you need to use a dehaze model. 9130@end table 9131Default value is @samp{derain}. 9132 9133@item dnn_backend 9134Specify which DNN backend to use for model loading and execution. This option accepts 9135the following values: 9136 9137@table @samp 9138@item native 9139Native implementation of DNN loading and execution. 9140 9141@item tensorflow 9142TensorFlow backend. To enable this backend you 9143need to install the TensorFlow for C library (see 9144@url{https://www.tensorflow.org/install/install_c}) and configure FFmpeg with 9145@code{--enable-libtensorflow} 9146@end table 9147Default value is @samp{native}. 9148 9149@item model 9150Set path to model file specifying network architecture and its parameters. 9151Note that different backends use different file formats. TensorFlow and native 9152backend can load files for only its format. 9153@end table 9154 9155It can also be finished with @ref{dnn_processing} filter. 9156 9157@section deshake 9158 9159Attempt to fix small changes in horizontal and/or vertical shift. This 9160filter helps remove camera shake from hand-holding a camera, bumping a 9161tripod, moving on a vehicle, etc. 9162 9163The filter accepts the following options: 9164 9165@table @option 9166 9167@item x 9168@item y 9169@item w 9170@item h 9171Specify a rectangular area where to limit the search for motion 9172vectors. 9173If desired the search for motion vectors can be limited to a 9174rectangular area of the frame defined by its top left corner, width 9175and height. These parameters have the same meaning as the drawbox 9176filter which can be used to visualise the position of the bounding 9177box. 9178 9179This is useful when simultaneous movement of subjects within the frame 9180might be confused for camera motion by the motion vector search. 9181 9182If any or all of @var{x}, @var{y}, @var{w} and @var{h} are set to -1 9183then the full frame is used. This allows later options to be set 9184without specifying the bounding box for the motion vector search. 9185 9186Default - search the whole frame. 9187 9188@item rx 9189@item ry 9190Specify the maximum extent of movement in x and y directions in the 9191range 0-64 pixels. Default 16. 9192 9193@item edge 9194Specify how to generate pixels to fill blanks at the edge of the 9195frame. Available values are: 9196@table @samp 9197@item blank, 0 9198Fill zeroes at blank locations 9199@item original, 1 9200Original image at blank locations 9201@item clamp, 2 9202Extruded edge value at blank locations 9203@item mirror, 3 9204Mirrored edge at blank locations 9205@end table 9206Default value is @samp{mirror}. 9207 9208@item blocksize 9209Specify the blocksize to use for motion search. Range 4-128 pixels, 9210default 8. 9211 9212@item contrast 9213Specify the contrast threshold for blocks. Only blocks with more than 9214the specified contrast (difference between darkest and lightest 9215pixels) will be considered. Range 1-255, default 125. 9216 9217@item search 9218Specify the search strategy. Available values are: 9219@table @samp 9220@item exhaustive, 0 9221Set exhaustive search 9222@item less, 1 9223Set less exhaustive search. 9224@end table 9225Default value is @samp{exhaustive}. 9226 9227@item filename 9228If set then a detailed log of the motion search is written to the 9229specified file. 9230 9231@end table 9232 9233@section despill 9234 9235Remove unwanted contamination of foreground colors, caused by reflected color of 9236greenscreen or bluescreen. 9237 9238This filter accepts the following options: 9239 9240@table @option 9241@item type 9242Set what type of despill to use. 9243 9244@item mix 9245Set how spillmap will be generated. 9246 9247@item expand 9248Set how much to get rid of still remaining spill. 9249 9250@item red 9251Controls amount of red in spill area. 9252 9253@item green 9254Controls amount of green in spill area. 9255Should be -1 for greenscreen. 9256 9257@item blue 9258Controls amount of blue in spill area. 9259Should be -1 for bluescreen. 9260 9261@item brightness 9262Controls brightness of spill area, preserving colors. 9263 9264@item alpha 9265Modify alpha from generated spillmap. 9266@end table 9267 9268@section detelecine 9269 9270Apply an exact inverse of the telecine operation. It requires a predefined 9271pattern specified using the pattern option which must be the same as that passed 9272to the telecine filter. 9273 9274This filter accepts the following options: 9275 9276@table @option 9277@item first_field 9278@table @samp 9279@item top, t 9280top field first 9281@item bottom, b 9282bottom field first 9283The default value is @code{top}. 9284@end table 9285 9286@item pattern 9287A string of numbers representing the pulldown pattern you wish to apply. 9288The default value is @code{23}. 9289 9290@item start_frame 9291A number representing position of the first frame with respect to the telecine 9292pattern. This is to be used if the stream is cut. The default value is @code{0}. 9293@end table 9294 9295@section dilation 9296 9297Apply dilation effect to the video. 9298 9299This filter replaces the pixel by the local(3x3) maximum. 9300 9301It accepts the following options: 9302 9303@table @option 9304@item threshold0 9305@item threshold1 9306@item threshold2 9307@item threshold3 9308Limit the maximum change for each plane, default is 65535. 9309If 0, plane will remain unchanged. 9310 9311@item coordinates 9312Flag which specifies the pixel to refer to. Default is 255 i.e. all eight 9313pixels are used. 9314 9315Flags to local 3x3 coordinates maps like this: 9316 9317 1 2 3 9318 4 5 9319 6 7 8 9320@end table 9321 9322@subsection Commands 9323 9324This filter supports the all above options as @ref{commands}. 9325 9326@section displace 9327 9328Displace pixels as indicated by second and third input stream. 9329 9330It takes three input streams and outputs one stream, the first input is the 9331source, and second and third input are displacement maps. 9332 9333The second input specifies how much to displace pixels along the 9334x-axis, while the third input specifies how much to displace pixels 9335along the y-axis. 9336If one of displacement map streams terminates, last frame from that 9337displacement map will be used. 9338 9339Note that once generated, displacements maps can be reused over and over again. 9340 9341A description of the accepted options follows. 9342 9343@table @option 9344@item edge 9345Set displace behavior for pixels that are out of range. 9346 9347Available values are: 9348@table @samp 9349@item blank 9350Missing pixels are replaced by black pixels. 9351 9352@item smear 9353Adjacent pixels will spread out to replace missing pixels. 9354 9355@item wrap 9356Out of range pixels are wrapped so they point to pixels of other side. 9357 9358@item mirror 9359Out of range pixels will be replaced with mirrored pixels. 9360@end table 9361Default is @samp{smear}. 9362 9363@end table 9364 9365@subsection Examples 9366 9367@itemize 9368@item 9369Add ripple effect to rgb input of video size hd720: 9370@example 9371ffmpeg -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 9372@end example 9373 9374@item 9375Add wave effect to rgb input of video size hd720: 9376@example 9377ffmpeg -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 9378@end example 9379@end itemize 9380 9381@anchor{dnn_processing} 9382@section dnn_processing 9383 9384Do image processing with deep neural networks. It works together with another filter 9385which converts the pixel format of the Frame to what the dnn network requires. 9386 9387The filter accepts the following options: 9388 9389@table @option 9390@item dnn_backend 9391Specify which DNN backend to use for model loading and execution. This option accepts 9392the following values: 9393 9394@table @samp 9395@item native 9396Native implementation of DNN loading and execution. 9397 9398@item tensorflow 9399TensorFlow backend. To enable this backend you 9400need to install the TensorFlow for C library (see 9401@url{https://www.tensorflow.org/install/install_c}) and configure FFmpeg with 9402@code{--enable-libtensorflow} 9403 9404@item openvino 9405OpenVINO backend. To enable this backend you 9406need to build and install the OpenVINO for C library (see 9407@url{https://github.com/openvinotoolkit/openvino/blob/master/build-instruction.md}) and configure FFmpeg with 9408@code{--enable-libopenvino} (--extra-cflags=-I... --extra-ldflags=-L... might 9409be needed if the header files and libraries are not installed into system path) 9410 9411@end table 9412 9413Default value is @samp{native}. 9414 9415@item model 9416Set path to model file specifying network architecture and its parameters. 9417Note that different backends use different file formats. TensorFlow, OpenVINO and native 9418backend can load files for only its format. 9419 9420Native model file (.model) can be generated from TensorFlow model file (.pb) by using tools/python/convert.py 9421 9422@item input 9423Set the input name of the dnn network. 9424 9425@item output 9426Set the output name of the dnn network. 9427 9428@end table 9429 9430@subsection Examples 9431 9432@itemize 9433@item 9434Remove rain in rgb24 frame with can.pb (see @ref{derain} filter): 9435@example 9436./ffmpeg -i rain.jpg -vf format=rgb24,dnn_processing=dnn_backend=tensorflow:model=can.pb:input=x:output=y derain.jpg 9437@end example 9438 9439@item 9440Halve the pixel value of the frame with format gray32f: 9441@example 9442ffmpeg -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 9443@end example 9444 9445@item 9446Handle the Y channel with srcnn.pb (see @ref{sr} filter) for frame with yuv420p (planar YUV formats supported): 9447@example 9448./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 9449@end example 9450 9451@item 9452Handle the Y channel with espcn.pb (see @ref{sr} filter), which changes frame size, for format yuv420p (planar YUV formats supported): 9453@example 9454./ffmpeg -i 480p.jpg -vf format=yuv420p,dnn_processing=dnn_backend=tensorflow:model=espcn.pb:input=x:output=y -y tmp.espcn.jpg 9455@end example 9456 9457@end itemize 9458 9459@section drawbox 9460 9461Draw a colored box on the input image. 9462 9463It accepts the following parameters: 9464 9465@table @option 9466@item x 9467@item y 9468The expressions which specify the top left corner coordinates of the box. It defaults to 0. 9469 9470@item width, w 9471@item height, h 9472The expressions which specify the width and height of the box; if 0 they are interpreted as 9473the input width and height. It defaults to 0. 9474 9475@item color, c 9476Specify the color of the box to write. For the general syntax of this option, 9477check the @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}. If the special 9478value @code{invert} is used, the box edge color is the same as the 9479video with inverted luma. 9480 9481@item thickness, t 9482The expression which sets the thickness of the box edge. 9483A value of @code{fill} will create a filled box. Default value is @code{3}. 9484 9485See below for the list of accepted constants. 9486 9487@item replace 9488Applicable if the input has alpha. With value @code{1}, the pixels of the painted box 9489will overwrite the video's color and alpha pixels. 9490Default is @code{0}, which composites the box onto the input, leaving the video's alpha intact. 9491@end table 9492 9493The parameters for @var{x}, @var{y}, @var{w} and @var{h} and @var{t} are expressions containing the 9494following constants: 9495 9496@table @option 9497@item dar 9498The input display aspect ratio, it is the same as (@var{w} / @var{h}) * @var{sar}. 9499 9500@item hsub 9501@item vsub 9502horizontal and vertical chroma subsample values. For example for the 9503pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1. 9504 9505@item in_h, ih 9506@item in_w, iw 9507The input width and height. 9508 9509@item sar 9510The input sample aspect ratio. 9511 9512@item x 9513@item y 9514The x and y offset coordinates where the box is drawn. 9515 9516@item w 9517@item h 9518The width and height of the drawn box. 9519 9520@item t 9521The thickness of the drawn box. 9522 9523These constants allow the @var{x}, @var{y}, @var{w}, @var{h} and @var{t} expressions to refer to 9524each other, so you may for example specify @code{y=x/dar} or @code{h=w/dar}. 9525 9526@end table 9527 9528@subsection Examples 9529 9530@itemize 9531@item 9532Draw a black box around the edge of the input image: 9533@example 9534drawbox 9535@end example 9536 9537@item 9538Draw a box with color red and an opacity of 50%: 9539@example 9540drawbox=10:20:200:60:red@@0.5 9541@end example 9542 9543The previous example can be specified as: 9544@example 9545drawbox=x=10:y=20:w=200:h=60:color=red@@0.5 9546@end example 9547 9548@item 9549Fill the box with pink color: 9550@example 9551drawbox=x=10:y=10:w=100:h=100:color=pink@@0.5:t=fill 9552@end example 9553 9554@item 9555Draw a 2-pixel red 2.40:1 mask: 9556@example 9557drawbox=x=-t:y=0.5*(ih-iw/2.4)-t:w=iw+t*2:h=iw/2.4+t*2:t=2:c=red 9558@end example 9559@end itemize 9560 9561@subsection Commands 9562This filter supports same commands as options. 9563The command accepts the same syntax of the corresponding option. 9564 9565If the specified expression is not valid, it is kept at its current 9566value. 9567 9568@anchor{drawgraph} 9569@section drawgraph 9570Draw a graph using input video metadata. 9571 9572It accepts the following parameters: 9573 9574@table @option 9575@item m1 9576Set 1st frame metadata key from which metadata values will be used to draw a graph. 9577 9578@item fg1 9579Set 1st foreground color expression. 9580 9581@item m2 9582Set 2nd frame metadata key from which metadata values will be used to draw a graph. 9583 9584@item fg2 9585Set 2nd foreground color expression. 9586 9587@item m3 9588Set 3rd frame metadata key from which metadata values will be used to draw a graph. 9589 9590@item fg3 9591Set 3rd foreground color expression. 9592 9593@item m4 9594Set 4th frame metadata key from which metadata values will be used to draw a graph. 9595 9596@item fg4 9597Set 4th foreground color expression. 9598 9599@item min 9600Set minimal value of metadata value. 9601 9602@item max 9603Set maximal value of metadata value. 9604 9605@item bg 9606Set graph background color. Default is white. 9607 9608@item mode 9609Set graph mode. 9610 9611Available values for mode is: 9612@table @samp 9613@item bar 9614@item dot 9615@item line 9616@end table 9617 9618Default is @code{line}. 9619 9620@item slide 9621Set slide mode. 9622 9623Available values for slide is: 9624@table @samp 9625@item frame 9626Draw new frame when right border is reached. 9627 9628@item replace 9629Replace old columns with new ones. 9630 9631@item scroll 9632Scroll from right to left. 9633 9634@item rscroll 9635Scroll from left to right. 9636 9637@item picture 9638Draw single picture. 9639@end table 9640 9641Default is @code{frame}. 9642 9643@item size 9644Set size of graph video. For the syntax of this option, check the 9645@ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}. 9646The default value is @code{900x256}. 9647 9648@item rate, r 9649Set the output frame rate. Default value is @code{25}. 9650 9651The foreground color expressions can use the following variables: 9652@table @option 9653@item MIN 9654Minimal value of metadata value. 9655 9656@item MAX 9657Maximal value of metadata value. 9658 9659@item VAL 9660Current metadata key value. 9661@end table 9662 9663The color is defined as 0xAABBGGRR. 9664@end table 9665 9666Example using metadata from @ref{signalstats} filter: 9667@example 9668signalstats,drawgraph=lavfi.signalstats.YAVG:min=0:max=255 9669@end example 9670 9671Example using metadata from @ref{ebur128} filter: 9672@example 9673ebur128=metadata=1,adrawgraph=lavfi.r128.M:min=-120:max=5 9674@end example 9675 9676@section drawgrid 9677 9678Draw a grid on the input image. 9679 9680It accepts the following parameters: 9681 9682@table @option 9683@item x 9684@item y 9685The expressions which specify the coordinates of some point of grid intersection (meant to configure offset). Both default to 0. 9686 9687@item width, w 9688@item height, h 9689The expressions which specify the width and height of the grid cell, if 0 they are interpreted as the 9690input width and height, respectively, minus @code{thickness}, so image gets 9691framed. Default to 0. 9692 9693@item color, c 9694Specify the color of the grid. For the general syntax of this option, 9695check the @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}. If the special 9696value @code{invert} is used, the grid color is the same as the 9697video with inverted luma. 9698 9699@item thickness, t 9700The expression which sets the thickness of the grid line. Default value is @code{1}. 9701 9702See below for the list of accepted constants. 9703 9704@item replace 9705Applicable if the input has alpha. With @code{1} the pixels of the painted grid 9706will overwrite the video's color and alpha pixels. 9707Default is @code{0}, which composites the grid onto the input, leaving the video's alpha intact. 9708@end table 9709 9710The parameters for @var{x}, @var{y}, @var{w} and @var{h} and @var{t} are expressions containing the 9711following constants: 9712 9713@table @option 9714@item dar 9715The input display aspect ratio, it is the same as (@var{w} / @var{h}) * @var{sar}. 9716 9717@item hsub 9718@item vsub 9719horizontal and vertical chroma subsample values. For example for the 9720pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1. 9721 9722@item in_h, ih 9723@item in_w, iw 9724The input grid cell width and height. 9725 9726@item sar 9727The input sample aspect ratio. 9728 9729@item x 9730@item y 9731The x and y coordinates of some point of grid intersection (meant to configure offset). 9732 9733@item w 9734@item h 9735The width and height of the drawn cell. 9736 9737@item t 9738The thickness of the drawn cell. 9739 9740These constants allow the @var{x}, @var{y}, @var{w}, @var{h} and @var{t} expressions to refer to 9741each other, so you may for example specify @code{y=x/dar} or @code{h=w/dar}. 9742 9743@end table 9744 9745@subsection Examples 9746 9747@itemize 9748@item 9749Draw a grid with cell 100x100 pixels, thickness 2 pixels, with color red and an opacity of 50%: 9750@example 9751drawgrid=width=100:height=100:thickness=2:color=red@@0.5 9752@end example 9753 9754@item 9755Draw a white 3x3 grid with an opacity of 50%: 9756@example 9757drawgrid=w=iw/3:h=ih/3:t=2:c=white@@0.5 9758@end example 9759@end itemize 9760 9761@subsection Commands 9762This filter supports same commands as options. 9763The command accepts the same syntax of the corresponding option. 9764 9765If the specified expression is not valid, it is kept at its current 9766value. 9767 9768@anchor{drawtext} 9769@section drawtext 9770 9771Draw a text string or text from a specified file on top of a video, using the 9772libfreetype library. 9773 9774To enable compilation of this filter, you need to configure FFmpeg with 9775@code{--enable-libfreetype}. 9776To enable default font fallback and the @var{font} option you need to 9777configure FFmpeg with @code{--enable-libfontconfig}. 9778To enable the @var{text_shaping} option, you need to configure FFmpeg with 9779@code{--enable-libfribidi}. 9780 9781@subsection Syntax 9782 9783It accepts the following parameters: 9784 9785@table @option 9786 9787@item box 9788Used to draw a box around text using the background color. 9789The value must be either 1 (enable) or 0 (disable). 9790The default value of @var{box} is 0. 9791 9792@item boxborderw 9793Set the width of the border to be drawn around the box using @var{boxcolor}. 9794The default value of @var{boxborderw} is 0. 9795 9796@item boxcolor 9797The color to be used for drawing box around text. For the syntax of this 9798option, check the @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}. 9799 9800The default value of @var{boxcolor} is "white". 9801 9802@item line_spacing 9803Set the line spacing in pixels of the border to be drawn around the box using @var{box}. 9804The default value of @var{line_spacing} is 0. 9805 9806@item borderw 9807Set the width of the border to be drawn around the text using @var{bordercolor}. 9808The default value of @var{borderw} is 0. 9809 9810@item bordercolor 9811Set the color to be used for drawing border around text. For the syntax of this 9812option, check the @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}. 9813 9814The default value of @var{bordercolor} is "black". 9815 9816@item expansion 9817Select how the @var{text} is expanded. Can be either @code{none}, 9818@code{strftime} (deprecated) or 9819@code{normal} (default). See the @ref{drawtext_expansion, Text expansion} section 9820below for details. 9821 9822@item basetime 9823Set a start time for the count. Value is in microseconds. Only applied 9824in the deprecated strftime expansion mode. To emulate in normal expansion 9825mode use the @code{pts} function, supplying the start time (in seconds) 9826as the second argument. 9827 9828@item fix_bounds 9829If true, check and fix text coords to avoid clipping. 9830 9831@item fontcolor 9832The color to be used for drawing fonts. For the syntax of this option, check 9833the @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}. 9834 9835The default value of @var{fontcolor} is "black". 9836 9837@item fontcolor_expr 9838String which is expanded the same way as @var{text} to obtain dynamic 9839@var{fontcolor} value. By default this option has empty value and is not 9840processed. When this option is set, it overrides @var{fontcolor} option. 9841 9842@item font 9843The font family to be used for drawing text. By default Sans. 9844 9845@item fontfile 9846The font file to be used for drawing text. The path must be included. 9847This parameter is mandatory if the fontconfig support is disabled. 9848 9849@item alpha 9850Draw the text applying alpha blending. The value can 9851be a number between 0.0 and 1.0. 9852The expression accepts the same variables @var{x, y} as well. 9853The default value is 1. 9854Please see @var{fontcolor_expr}. 9855 9856@item fontsize 9857The font size to be used for drawing text. 9858The default value of @var{fontsize} is 16. 9859 9860@item text_shaping 9861If set to 1, attempt to shape the text (for example, reverse the order of 9862right-to-left text and join Arabic characters) before drawing it. 9863Otherwise, just draw the text exactly as given. 9864By default 1 (if supported). 9865 9866@item ft_load_flags 9867The flags to be used for loading the fonts. 9868 9869The flags map the corresponding flags supported by libfreetype, and are 9870a combination of the following values: 9871@table @var 9872@item default 9873@item no_scale 9874@item no_hinting 9875@item render 9876@item no_bitmap 9877@item vertical_layout 9878@item force_autohint 9879@item crop_bitmap 9880@item pedantic 9881@item ignore_global_advance_width 9882@item no_recurse 9883@item ignore_transform 9884@item monochrome 9885@item linear_design 9886@item no_autohint 9887@end table 9888 9889Default value is "default". 9890 9891For more information consult the documentation for the FT_LOAD_* 9892libfreetype flags. 9893 9894@item shadowcolor 9895The color to be used for drawing a shadow behind the drawn text. For the 9896syntax of this option, check the @ref{color syntax,,"Color" section in the 9897ffmpeg-utils manual,ffmpeg-utils}. 9898 9899The default value of @var{shadowcolor} is "black". 9900 9901@item shadowx 9902@item shadowy 9903The x and y offsets for the text shadow position with respect to the 9904position of the text. They can be either positive or negative 9905values. The default value for both is "0". 9906 9907@item start_number 9908The starting frame number for the n/frame_num variable. The default value 9909is "0". 9910 9911@item tabsize 9912The size in number of spaces to use for rendering the tab. 9913Default value is 4. 9914 9915@item timecode 9916Set the initial timecode representation in "hh:mm:ss[:;.]ff" 9917format. It can be used with or without text parameter. @var{timecode_rate} 9918option must be specified. 9919 9920@item timecode_rate, rate, r 9921Set the timecode frame rate (timecode only). Value will be rounded to nearest 9922integer. Minimum value is "1". 9923Drop-frame timecode is supported for frame rates 30 & 60. 9924 9925@item tc24hmax 9926If set to 1, the output of the timecode option will wrap around at 24 hours. 9927Default is 0 (disabled). 9928 9929@item text 9930The text string to be drawn. The text must be a sequence of UTF-8 9931encoded characters. 9932This parameter is mandatory if no file is specified with the parameter 9933@var{textfile}. 9934 9935@item textfile 9936A text file containing text to be drawn. The text must be a sequence 9937of UTF-8 encoded characters. 9938 9939This parameter is mandatory if no text string is specified with the 9940parameter @var{text}. 9941 9942If both @var{text} and @var{textfile} are specified, an error is thrown. 9943 9944@item reload 9945If set to 1, the @var{textfile} will be reloaded before each frame. 9946Be sure to update it atomically, or it may be read partially, or even fail. 9947 9948@item x 9949@item y 9950The expressions which specify the offsets where text will be drawn 9951within the video frame. They are relative to the top/left border of the 9952output image. 9953 9954The default value of @var{x} and @var{y} is "0". 9955 9956See below for the list of accepted constants and functions. 9957@end table 9958 9959The parameters for @var{x} and @var{y} are expressions containing the 9960following constants and functions: 9961 9962@table @option 9963@item dar 9964input display aspect ratio, it is the same as (@var{w} / @var{h}) * @var{sar} 9965 9966@item hsub 9967@item vsub 9968horizontal and vertical chroma subsample values. For example for the 9969pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1. 9970 9971@item line_h, lh 9972the height of each text line 9973 9974@item main_h, h, H 9975the input height 9976 9977@item main_w, w, W 9978the input width 9979 9980@item max_glyph_a, ascent 9981the maximum distance from the baseline to the highest/upper grid 9982coordinate used to place a glyph outline point, for all the rendered 9983glyphs. 9984It is a positive value, due to the grid's orientation with the Y axis 9985upwards. 9986 9987@item max_glyph_d, descent 9988the maximum distance from the baseline to the lowest grid coordinate 9989used to place a glyph outline point, for all the rendered glyphs. 9990This is a negative value, due to the grid's orientation, with the Y axis 9991upwards. 9992 9993@item max_glyph_h 9994maximum glyph height, that is the maximum height for all the glyphs 9995contained in the rendered text, it is equivalent to @var{ascent} - 9996@var{descent}. 9997 9998@item max_glyph_w 9999maximum glyph width, that is the maximum width for all the glyphs 10000contained in the rendered text 10001 10002@item n 10003the number of input frame, starting from 0 10004 10005@item rand(min, max) 10006return a random number included between @var{min} and @var{max} 10007 10008@item sar 10009The input sample aspect ratio. 10010 10011@item t 10012timestamp expressed in seconds, NAN if the input timestamp is unknown 10013 10014@item text_h, th 10015the height of the rendered text 10016 10017@item text_w, tw 10018the width of the rendered text 10019 10020@item x 10021@item y 10022the x and y offset coordinates where the text is drawn. 10023 10024These parameters allow the @var{x} and @var{y} expressions to refer 10025to each other, so you can for example specify @code{y=x/dar}. 10026 10027@item pict_type 10028A one character description of the current frame's picture type. 10029 10030@item pkt_pos 10031The current packet's position in the input file or stream 10032(in bytes, from the start of the input). A value of -1 indicates 10033this info is not available. 10034 10035@item pkt_duration 10036The current packet's duration, in seconds. 10037 10038@item pkt_size 10039The current packet's size (in bytes). 10040@end table 10041 10042@anchor{drawtext_expansion} 10043@subsection Text expansion 10044 10045If @option{expansion} is set to @code{strftime}, 10046the filter recognizes strftime() sequences in the provided text and 10047expands them accordingly. Check the documentation of strftime(). This 10048feature is deprecated. 10049 10050If @option{expansion} is set to @code{none}, the text is printed verbatim. 10051 10052If @option{expansion} is set to @code{normal} (which is the default), 10053the following expansion mechanism is used. 10054 10055The backslash character @samp{\}, followed by any character, always expands to 10056the second character. 10057 10058Sequences of the form @code{%@{...@}} are expanded. The text between the 10059braces is a function name, possibly followed by arguments separated by ':'. 10060If the arguments contain special characters or delimiters (':' or '@}'), 10061they should be escaped. 10062 10063Note that they probably must also be escaped as the value for the 10064@option{text} option in the filter argument string and as the filter 10065argument in the filtergraph description, and possibly also for the shell, 10066that makes up to four levels of escaping; using a text file avoids these 10067problems. 10068 10069The following functions are available: 10070 10071@table @command 10072 10073@item expr, e 10074The expression evaluation result. 10075 10076It must take one argument specifying the expression to be evaluated, 10077which accepts the same constants and functions as the @var{x} and 10078@var{y} values. Note that not all constants should be used, for 10079example the text size is not known when evaluating the expression, so 10080the constants @var{text_w} and @var{text_h} will have an undefined 10081value. 10082 10083@item expr_int_format, eif 10084Evaluate the expression's value and output as formatted integer. 10085 10086The first argument is the expression to be evaluated, just as for the @var{expr} function. 10087The second argument specifies the output format. Allowed values are @samp{x}, 10088@samp{X}, @samp{d} and @samp{u}. They are treated exactly as in the 10089@code{printf} function. 10090The third parameter is optional and sets the number of positions taken by the output. 10091It can be used to add padding with zeros from the left. 10092 10093@item gmtime 10094The time at which the filter is running, expressed in UTC. 10095It can accept an argument: a strftime() format string. 10096 10097@item localtime 10098The time at which the filter is running, expressed in the local time zone. 10099It can accept an argument: a strftime() format string. 10100 10101@item metadata 10102Frame metadata. Takes one or two arguments. 10103 10104The first argument is mandatory and specifies the metadata key. 10105 10106The second argument is optional and specifies a default value, used when the 10107metadata key is not found or empty. 10108 10109Available metadata can be identified by inspecting entries 10110starting with TAG included within each frame section 10111printed by running @code{ffprobe -show_frames}. 10112 10113String metadata generated in filters leading to 10114the drawtext filter are also available. 10115 10116@item n, frame_num 10117The frame number, starting from 0. 10118 10119@item pict_type 10120A one character description of the current picture type. 10121 10122@item pts 10123The timestamp of the current frame. 10124It can take up to three arguments. 10125 10126The first argument is the format of the timestamp; it defaults to @code{flt} 10127for seconds as a decimal number with microsecond accuracy; @code{hms} stands 10128for a formatted @var{[-]HH:MM:SS.mmm} timestamp with millisecond accuracy. 10129@code{gmtime} stands for the timestamp of the frame formatted as UTC time; 10130@code{localtime} stands for the timestamp of the frame formatted as 10131local time zone time. 10132 10133The second argument is an offset added to the timestamp. 10134 10135If the format is set to @code{hms}, a third argument @code{24HH} may be 10136supplied to present the hour part of the formatted timestamp in 24h format 10137(00-23). 10138 10139If the format is set to @code{localtime} or @code{gmtime}, 10140a third argument may be supplied: a strftime() format string. 10141By default, @var{YYYY-MM-DD HH:MM:SS} format will be used. 10142@end table 10143 10144@subsection Commands 10145 10146This filter supports altering parameters via commands: 10147@table @option 10148@item reinit 10149Alter existing filter parameters. 10150 10151Syntax for the argument is the same as for filter invocation, e.g. 10152 10153@example 10154fontsize=56:fontcolor=green:text='Hello World' 10155@end example 10156 10157Full filter invocation with sendcmd would look like this: 10158 10159@example 10160sendcmd=c='56.0 drawtext reinit fontsize=56\:fontcolor=green\:text=Hello\\ World' 10161@end example 10162@end table 10163 10164If the entire argument can't be parsed or applied as valid values then the filter will 10165continue with its existing parameters. 10166 10167@subsection Examples 10168 10169@itemize 10170@item 10171Draw "Test Text" with font FreeSerif, using the default values for the 10172optional parameters. 10173 10174@example 10175drawtext="fontfile=/usr/share/fonts/truetype/freefont/FreeSerif.ttf: text='Test Text'" 10176@end example 10177 10178@item 10179Draw 'Test Text' with font FreeSerif of size 24 at position x=100 10180and y=50 (counting from the top-left corner of the screen), text is 10181yellow with a red box around it. Both the text and the box have an 10182opacity of 20%. 10183 10184@example 10185drawtext="fontfile=/usr/share/fonts/truetype/freefont/FreeSerif.ttf: text='Test Text':\ 10186 x=100: y=50: fontsize=24: fontcolor=yellow@@0.2: box=1: boxcolor=red@@0.2" 10187@end example 10188 10189Note that the double quotes are not necessary if spaces are not used 10190within the parameter list. 10191 10192@item 10193Show the text at the center of the video frame: 10194@example 10195drawtext="fontsize=30:fontfile=FreeSerif.ttf:text='hello world':x=(w-text_w)/2:y=(h-text_h)/2" 10196@end example 10197 10198@item 10199Show the text at a random position, switching to a new position every 30 seconds: 10200@example 10201drawtext="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)" 10202@end example 10203 10204@item 10205Show a text line sliding from right to left in the last row of the video 10206frame. The file @file{LONG_LINE} is assumed to contain a single line 10207with no newlines. 10208@example 10209drawtext="fontsize=15:fontfile=FreeSerif.ttf:text=LONG_LINE:y=h-line_h:x=-50*t" 10210@end example 10211 10212@item 10213Show the content of file @file{CREDITS} off the bottom of the frame and scroll up. 10214@example 10215drawtext="fontsize=20:fontfile=FreeSerif.ttf:textfile=CREDITS:y=h-20*t" 10216@end example 10217 10218@item 10219Draw a single green letter "g", at the center of the input video. 10220The glyph baseline is placed at half screen height. 10221@example 10222drawtext="fontsize=60:fontfile=FreeSerif.ttf:fontcolor=green:text=g:x=(w-max_glyph_w)/2:y=h/2-ascent" 10223@end example 10224 10225@item 10226Show text for 1 second every 3 seconds: 10227@example 10228drawtext="fontfile=FreeSerif.ttf:fontcolor=white:x=100:y=x/dar:enable=lt(mod(t\,3)\,1):text='blink'" 10229@end example 10230 10231@item 10232Use fontconfig to set the font. Note that the colons need to be escaped. 10233@example 10234drawtext='fontfile=Linux Libertine O-40\:style=Semibold:text=FFmpeg' 10235@end example 10236 10237@item 10238Draw "Test Text" with font size dependent on height of the video. 10239@example 10240drawtext="text='Test Text': fontsize=h/30: x=(w-text_w)/2: y=(h-text_h*2)" 10241@end example 10242 10243@item 10244Print the date of a real-time encoding (see strftime(3)): 10245@example 10246drawtext='fontfile=FreeSans.ttf:text=%@{localtime\:%a %b %d %Y@}' 10247@end example 10248 10249@item 10250Show text fading in and out (appearing/disappearing): 10251@example 10252#!/bin/sh 10253DS=1.0 # display start 10254DE=10.0 # display end 10255FID=1.5 # fade in duration 10256FOD=5 # fade out duration 10257ffplay -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 @}" 10258@end example 10259 10260@item 10261Horizontally align multiple separate texts. Note that @option{max_glyph_a} 10262and the @option{fontsize} value are included in the @option{y} offset. 10263@example 10264drawtext=fontfile=FreeSans.ttf:text=DOG:fontsize=24:x=10:y=20+24-max_glyph_a, 10265drawtext=fontfile=FreeSans.ttf:text=cow:fontsize=24:x=80:y=20+24-max_glyph_a 10266@end example 10267 10268@item 10269Plot special @var{lavf.image2dec.source_basename} metadata onto each frame if 10270such metadata exists. Otherwise, plot the string "NA". Note that image2 demuxer 10271must have option @option{-export_path_metadata 1} for the special metadata fields 10272to be available for filters. 10273@example 10274drawtext="fontsize=20:fontcolor=white:fontfile=FreeSans.ttf:text='%@{metadata\:lavf.image2dec.source_basename\:NA@}':x=10:y=10" 10275@end example 10276 10277@end itemize 10278 10279For more information about libfreetype, check: 10280@url{http://www.freetype.org/}. 10281 10282For more information about fontconfig, check: 10283@url{http://freedesktop.org/software/fontconfig/fontconfig-user.html}. 10284 10285For more information about libfribidi, check: 10286@url{http://fribidi.org/}. 10287 10288@section edgedetect 10289 10290Detect and draw edges. The filter uses the Canny Edge Detection algorithm. 10291 10292The filter accepts the following options: 10293 10294@table @option 10295@item low 10296@item high 10297Set low and high threshold values used by the Canny thresholding 10298algorithm. 10299 10300The high threshold selects the "strong" edge pixels, which are then 10301connected through 8-connectivity with the "weak" edge pixels selected 10302by the low threshold. 10303 10304@var{low} and @var{high} threshold values must be chosen in the range 10305[0,1], and @var{low} should be lesser or equal to @var{high}. 10306 10307Default value for @var{low} is @code{20/255}, and default value for @var{high} 10308is @code{50/255}. 10309 10310@item mode 10311Define the drawing mode. 10312 10313@table @samp 10314@item wires 10315Draw white/gray wires on black background. 10316 10317@item colormix 10318Mix the colors to create a paint/cartoon effect. 10319 10320@item canny 10321Apply Canny edge detector on all selected planes. 10322@end table 10323Default value is @var{wires}. 10324 10325@item planes 10326Select planes for filtering. By default all available planes are filtered. 10327@end table 10328 10329@subsection Examples 10330 10331@itemize 10332@item 10333Standard edge detection with custom values for the hysteresis thresholding: 10334@example 10335edgedetect=low=0.1:high=0.4 10336@end example 10337 10338@item 10339Painting effect without thresholding: 10340@example 10341edgedetect=mode=colormix:high=0 10342@end example 10343@end itemize 10344 10345@section elbg 10346 10347Apply a posterize effect using the ELBG (Enhanced LBG) algorithm. 10348 10349For each input image, the filter will compute the optimal mapping from 10350the input to the output given the codebook length, that is the number 10351of distinct output colors. 10352 10353This filter accepts the following options. 10354 10355@table @option 10356@item codebook_length, l 10357Set codebook length. The value must be a positive integer, and 10358represents the number of distinct output colors. Default value is 256. 10359 10360@item nb_steps, n 10361Set the maximum number of iterations to apply for computing the optimal 10362mapping. The higher the value the better the result and the higher the 10363computation time. Default value is 1. 10364 10365@item seed, s 10366Set a random seed, must be an integer included between 0 and 10367UINT32_MAX. If not specified, or if explicitly set to -1, the filter 10368will try to use a good random seed on a best effort basis. 10369 10370@item pal8 10371Set pal8 output pixel format. This option does not work with codebook 10372length greater than 256. 10373@end table 10374 10375@section entropy 10376 10377Measure graylevel entropy in histogram of color channels of video frames. 10378 10379It accepts the following parameters: 10380 10381@table @option 10382@item mode 10383Can be either @var{normal} or @var{diff}. Default is @var{normal}. 10384 10385@var{diff} mode measures entropy of histogram delta values, absolute differences 10386between neighbour histogram values. 10387@end table 10388 10389@section eq 10390Set brightness, contrast, saturation and approximate gamma adjustment. 10391 10392The filter accepts the following options: 10393 10394@table @option 10395@item contrast 10396Set the contrast expression. The value must be a float value in range 10397@code{-1000.0} to @code{1000.0}. The default value is "1". 10398 10399@item brightness 10400Set the brightness expression. The value must be a float value in 10401range @code{-1.0} to @code{1.0}. The default value is "0". 10402 10403@item saturation 10404Set the saturation expression. The value must be a float in 10405range @code{0.0} to @code{3.0}. The default value is "1". 10406 10407@item gamma 10408Set the gamma expression. The value must be a float in range 10409@code{0.1} to @code{10.0}. The default value is "1". 10410 10411@item gamma_r 10412Set the gamma expression for red. The value must be a float in 10413range @code{0.1} to @code{10.0}. The default value is "1". 10414 10415@item gamma_g 10416Set the gamma expression for green. The value must be a float in range 10417@code{0.1} to @code{10.0}. The default value is "1". 10418 10419@item gamma_b 10420Set the gamma expression for blue. The value must be a float in range 10421@code{0.1} to @code{10.0}. The default value is "1". 10422 10423@item gamma_weight 10424Set the gamma weight expression. It can be used to reduce the effect 10425of a high gamma value on bright image areas, e.g. keep them from 10426getting overamplified and just plain white. The value must be a float 10427in range @code{0.0} to @code{1.0}. A value of @code{0.0} turns the 10428gamma correction all the way down while @code{1.0} leaves it at its 10429full strength. Default is "1". 10430 10431@item eval 10432Set when the expressions for brightness, contrast, saturation and 10433gamma expressions are evaluated. 10434 10435It accepts the following values: 10436@table @samp 10437@item init 10438only evaluate expressions once during the filter initialization or 10439when a command is processed 10440 10441@item frame 10442evaluate expressions for each incoming frame 10443@end table 10444 10445Default value is @samp{init}. 10446@end table 10447 10448The expressions accept the following parameters: 10449@table @option 10450@item n 10451frame count of the input frame starting from 0 10452 10453@item pos 10454byte position of the corresponding packet in the input file, NAN if 10455unspecified 10456 10457@item r 10458frame rate of the input video, NAN if the input frame rate is unknown 10459 10460@item t 10461timestamp expressed in seconds, NAN if the input timestamp is unknown 10462@end table 10463 10464@subsection Commands 10465The filter supports the following commands: 10466 10467@table @option 10468@item contrast 10469Set the contrast expression. 10470 10471@item brightness 10472Set the brightness expression. 10473 10474@item saturation 10475Set the saturation expression. 10476 10477@item gamma 10478Set the gamma expression. 10479 10480@item gamma_r 10481Set the gamma_r expression. 10482 10483@item gamma_g 10484Set gamma_g expression. 10485 10486@item gamma_b 10487Set gamma_b expression. 10488 10489@item gamma_weight 10490Set gamma_weight expression. 10491 10492The command accepts the same syntax of the corresponding option. 10493 10494If the specified expression is not valid, it is kept at its current 10495value. 10496 10497@end table 10498 10499@section erosion 10500 10501Apply erosion effect to the video. 10502 10503This filter replaces the pixel by the local(3x3) minimum. 10504 10505It accepts the following options: 10506 10507@table @option 10508@item threshold0 10509@item threshold1 10510@item threshold2 10511@item threshold3 10512Limit the maximum change for each plane, default is 65535. 10513If 0, plane will remain unchanged. 10514 10515@item coordinates 10516Flag which specifies the pixel to refer to. Default is 255 i.e. all eight 10517pixels are used. 10518 10519Flags to local 3x3 coordinates maps like this: 10520 10521 1 2 3 10522 4 5 10523 6 7 8 10524@end table 10525 10526@subsection Commands 10527 10528This filter supports the all above options as @ref{commands}. 10529 10530@section extractplanes 10531 10532Extract color channel components from input video stream into 10533separate grayscale video streams. 10534 10535The filter accepts the following option: 10536 10537@table @option 10538@item planes 10539Set plane(s) to extract. 10540 10541Available values for planes are: 10542@table @samp 10543@item y 10544@item u 10545@item v 10546@item a 10547@item r 10548@item g 10549@item b 10550@end table 10551 10552Choosing planes not available in the input will result in an error. 10553That means you cannot select @code{r}, @code{g}, @code{b} planes 10554with @code{y}, @code{u}, @code{v} planes at same time. 10555@end table 10556 10557@subsection Examples 10558 10559@itemize 10560@item 10561Extract luma, u and v color channel component from input video frame 10562into 3 grayscale outputs: 10563@example 10564ffmpeg -i video.avi -filter_complex 'extractplanes=y+u+v[y][u][v]' -map '[y]' y.avi -map '[u]' u.avi -map '[v]' v.avi 10565@end example 10566@end itemize 10567 10568@section fade 10569 10570Apply a fade-in/out effect to the input video. 10571 10572It accepts the following parameters: 10573 10574@table @option 10575@item type, t 10576The effect type can be either "in" for a fade-in, or "out" for a fade-out 10577effect. 10578Default is @code{in}. 10579 10580@item start_frame, s 10581Specify the number of the frame to start applying the fade 10582effect at. Default is 0. 10583 10584@item nb_frames, n 10585The number of frames that the fade effect lasts. At the end of the 10586fade-in effect, the output video will have the same intensity as the input video. 10587At the end of the fade-out transition, the output video will be filled with the 10588selected @option{color}. 10589Default is 25. 10590 10591@item alpha 10592If set to 1, fade only alpha channel, if one exists on the input. 10593Default value is 0. 10594 10595@item start_time, st 10596Specify the timestamp (in seconds) of the frame to start to apply the fade 10597effect. If both start_frame and start_time are specified, the fade will start at 10598whichever comes last. Default is 0. 10599 10600@item duration, d 10601The number of seconds for which the fade effect has to last. At the end of the 10602fade-in effect the output video will have the same intensity as the input video, 10603at the end of the fade-out transition the output video will be filled with the 10604selected @option{color}. 10605If both duration and nb_frames are specified, duration is used. Default is 0 10606(nb_frames is used by default). 10607 10608@item color, c 10609Specify the color of the fade. Default is "black". 10610@end table 10611 10612@subsection Examples 10613 10614@itemize 10615@item 10616Fade in the first 30 frames of video: 10617@example 10618fade=in:0:30 10619@end example 10620 10621The command above is equivalent to: 10622@example 10623fade=t=in:s=0:n=30 10624@end example 10625 10626@item 10627Fade out the last 45 frames of a 200-frame video: 10628@example 10629fade=out:155:45 10630fade=type=out:start_frame=155:nb_frames=45 10631@end example 10632 10633@item 10634Fade in the first 25 frames and fade out the last 25 frames of a 1000-frame video: 10635@example 10636fade=in:0:25, fade=out:975:25 10637@end example 10638 10639@item 10640Make the first 5 frames yellow, then fade in from frame 5-24: 10641@example 10642fade=in:5:20:color=yellow 10643@end example 10644 10645@item 10646Fade in alpha over first 25 frames of video: 10647@example 10648fade=in:0:25:alpha=1 10649@end example 10650 10651@item 10652Make the first 5.5 seconds black, then fade in for 0.5 seconds: 10653@example 10654fade=t=in:st=5.5:d=0.5 10655@end example 10656 10657@end itemize 10658 10659@section fftdnoiz 10660Denoise frames using 3D FFT (frequency domain filtering). 10661 10662The filter accepts the following options: 10663 10664@table @option 10665@item sigma 10666Set the noise sigma constant. This sets denoising strength. 10667Default value is 1. Allowed range is from 0 to 30. 10668Using very high sigma with low overlap may give blocking artifacts. 10669 10670@item amount 10671Set amount of denoising. By default all detected noise is reduced. 10672Default value is 1. Allowed range is from 0 to 1. 10673 10674@item block 10675Set size of block, Default is 4, can be 3, 4, 5 or 6. 10676Actual size of block in pixels is 2 to power of @var{block}, so by default 10677block size in pixels is 2^4 which is 16. 10678 10679@item overlap 10680Set block overlap. Default is 0.5. Allowed range is from 0.2 to 0.8. 10681 10682@item prev 10683Set number of previous frames to use for denoising. By default is set to 0. 10684 10685@item next 10686Set number of next frames to to use for denoising. By default is set to 0. 10687 10688@item planes 10689Set planes which will be filtered, by default are all available filtered 10690except alpha. 10691@end table 10692 10693@section fftfilt 10694Apply arbitrary expressions to samples in frequency domain 10695 10696@table @option 10697@item dc_Y 10698Adjust the dc value (gain) of the luma plane of the image. The filter 10699accepts an integer value in range @code{0} to @code{1000}. The default 10700value is set to @code{0}. 10701 10702@item dc_U 10703Adjust the dc value (gain) of the 1st chroma plane of the image. The 10704filter accepts an integer value in range @code{0} to @code{1000}. The 10705default value is set to @code{0}. 10706 10707@item dc_V 10708Adjust the dc value (gain) of the 2nd chroma plane of the image. The 10709filter accepts an integer value in range @code{0} to @code{1000}. The 10710default value is set to @code{0}. 10711 10712@item weight_Y 10713Set the frequency domain weight expression for the luma plane. 10714 10715@item weight_U 10716Set the frequency domain weight expression for the 1st chroma plane. 10717 10718@item weight_V 10719Set the frequency domain weight expression for the 2nd chroma plane. 10720 10721@item eval 10722Set when the expressions are evaluated. 10723 10724It accepts the following values: 10725@table @samp 10726@item init 10727Only evaluate expressions once during the filter initialization. 10728 10729@item frame 10730Evaluate expressions for each incoming frame. 10731@end table 10732 10733Default value is @samp{init}. 10734 10735The filter accepts the following variables: 10736@item X 10737@item Y 10738The coordinates of the current sample. 10739 10740@item W 10741@item H 10742The width and height of the image. 10743 10744@item N 10745The number of input frame, starting from 0. 10746@end table 10747 10748@subsection Examples 10749 10750@itemize 10751@item 10752High-pass: 10753@example 10754fftfilt=dc_Y=128:weight_Y='squish(1-(Y+X)/100)' 10755@end example 10756 10757@item 10758Low-pass: 10759@example 10760fftfilt=dc_Y=0:weight_Y='squish((Y+X)/100-1)' 10761@end example 10762 10763@item 10764Sharpen: 10765@example 10766fftfilt=dc_Y=0:weight_Y='1+squish(1-(Y+X)/100)' 10767@end example 10768 10769@item 10770Blur: 10771@example 10772fftfilt=dc_Y=0:weight_Y='exp(-4 * ((Y+X)/(W+H)))' 10773@end example 10774 10775@end itemize 10776 10777@section field 10778 10779Extract a single field from an interlaced image using stride 10780arithmetic to avoid wasting CPU time. The output frames are marked as 10781non-interlaced. 10782 10783The filter accepts the following options: 10784 10785@table @option 10786@item type 10787Specify whether to extract the top (if the value is @code{0} or 10788@code{top}) or the bottom field (if the value is @code{1} or 10789@code{bottom}). 10790@end table 10791 10792@section fieldhint 10793 10794Create new frames by copying the top and bottom fields from surrounding frames 10795supplied as numbers by the hint file. 10796 10797@table @option 10798@item hint 10799Set file containing hints: absolute/relative frame numbers. 10800 10801There must be one line for each frame in a clip. Each line must contain two 10802numbers separated by the comma, optionally followed by @code{-} or @code{+}. 10803Numbers supplied on each line of file can not be out of [N-1,N+1] where N 10804is current frame number for @code{absolute} mode or out of [-1, 1] range 10805for @code{relative} mode. First number tells from which frame to pick up top 10806field and second number tells from which frame to pick up bottom field. 10807 10808If optionally followed by @code{+} output frame will be marked as interlaced, 10809else if followed by @code{-} output frame will be marked as progressive, else 10810it will be marked same as input frame. 10811If optionally followed by @code{t} output frame will use only top field, or in 10812case of @code{b} it will use only bottom field. 10813If line starts with @code{#} or @code{;} that line is skipped. 10814 10815@item mode 10816Can be item @code{absolute} or @code{relative}. Default is @code{absolute}. 10817@end table 10818 10819Example of first several lines of @code{hint} file for @code{relative} mode: 10820@example 108210,0 - # first frame 108221,0 - # second frame, use third's frame top field and second's frame bottom field 108231,0 - # third frame, use fourth's frame top field and third's frame bottom field 108241,0 - 108250,0 - 108260,0 - 108271,0 - 108281,0 - 108291,0 - 108300,0 - 108310,0 - 108321,0 - 108331,0 - 108341,0 - 108350,0 - 10836@end example 10837 10838@section fieldmatch 10839 10840Field matching filter for inverse telecine. It is meant to reconstruct the 10841progressive frames from a telecined stream. The filter does not drop duplicated 10842frames, so to achieve a complete inverse telecine @code{fieldmatch} needs to be 10843followed by a decimation filter such as @ref{decimate} in the filtergraph. 10844 10845The separation of the field matching and the decimation is notably motivated by 10846the possibility of inserting a de-interlacing filter fallback between the two. 10847If the source has mixed telecined and real interlaced content, 10848@code{fieldmatch} will not be able to match fields for the interlaced parts. 10849But these remaining combed frames will be marked as interlaced, and thus can be 10850de-interlaced by a later filter such as @ref{yadif} before decimation. 10851 10852In addition to the various configuration options, @code{fieldmatch} can take an 10853optional second stream, activated through the @option{ppsrc} option. If 10854enabled, the frames reconstruction will be based on the fields and frames from 10855this second stream. This allows the first input to be pre-processed in order to 10856help the various algorithms of the filter, while keeping the output lossless 10857(assuming the fields are matched properly). Typically, a field-aware denoiser, 10858or brightness/contrast adjustments can help. 10859 10860Note that this filter uses the same algorithms as TIVTC/TFM (AviSynth project) 10861and VIVTC/VFM (VapourSynth project). The later is a light clone of TFM from 10862which @code{fieldmatch} is based on. While the semantic and usage are very 10863close, some behaviour and options names can differ. 10864 10865The @ref{decimate} filter currently only works for constant frame rate input. 10866If your input has mixed telecined (30fps) and progressive content with a lower 10867framerate like 24fps use the following filterchain to produce the necessary cfr 10868stream: @code{dejudder,fps=30000/1001,fieldmatch,decimate}. 10869 10870The filter accepts the following options: 10871 10872@table @option 10873@item order 10874Specify the assumed field order of the input stream. Available values are: 10875 10876@table @samp 10877@item auto 10878Auto detect parity (use FFmpeg's internal parity value). 10879@item bff 10880Assume bottom field first. 10881@item tff 10882Assume top field first. 10883@end table 10884 10885Note that it is sometimes recommended not to trust the parity announced by the 10886stream. 10887 10888Default value is @var{auto}. 10889 10890@item mode 10891Set the matching mode or strategy to use. @option{pc} mode is the safest in the 10892sense that it won't risk creating jerkiness due to duplicate frames when 10893possible, but if there are bad edits or blended fields it will end up 10894outputting combed frames when a good match might actually exist. On the other 10895hand, @option{pcn_ub} mode is the most risky in terms of creating jerkiness, 10896but will almost always find a good frame if there is one. The other values are 10897all somewhere in between @option{pc} and @option{pcn_ub} in terms of risking 10898jerkiness and creating duplicate frames versus finding good matches in sections 10899with bad edits, orphaned fields, blended fields, etc. 10900 10901More details about p/c/n/u/b are available in @ref{p/c/n/u/b meaning} section. 10902 10903Available values are: 10904 10905@table @samp 10906@item pc 109072-way matching (p/c) 10908@item pc_n 109092-way matching, and trying 3rd match if still combed (p/c + n) 10910@item pc_u 109112-way matching, and trying 3rd match (same order) if still combed (p/c + u) 10912@item pc_n_ub 109132-way matching, trying 3rd match if still combed, and trying 4th/5th matches if 10914still combed (p/c + n + u/b) 10915@item pcn 109163-way matching (p/c/n) 10917@item pcn_ub 109183-way matching, and trying 4th/5th matches if all 3 of the original matches are 10919detected as combed (p/c/n + u/b) 10920@end table 10921 10922The parenthesis at the end indicate the matches that would be used for that 10923mode assuming @option{order}=@var{tff} (and @option{field} on @var{auto} or 10924@var{top}). 10925 10926In terms of speed @option{pc} mode is by far the fastest and @option{pcn_ub} is 10927the slowest. 10928 10929Default value is @var{pc_n}. 10930 10931@item ppsrc 10932Mark the main input stream as a pre-processed input, and enable the secondary 10933input stream as the clean source to pick the fields from. See the filter 10934introduction for more details. It is similar to the @option{clip2} feature from 10935VFM/TFM. 10936 10937Default value is @code{0} (disabled). 10938 10939@item field 10940Set the field to match from. It is recommended to set this to the same value as 10941@option{order} unless you experience matching failures with that setting. In 10942certain circumstances changing the field that is used to match from can have a 10943large impact on matching performance. Available values are: 10944 10945@table @samp 10946@item auto 10947Automatic (same value as @option{order}). 10948@item bottom 10949Match from the bottom field. 10950@item top 10951Match from the top field. 10952@end table 10953 10954Default value is @var{auto}. 10955 10956@item mchroma 10957Set whether or not chroma is included during the match comparisons. In most 10958cases it is recommended to leave this enabled. You should set this to @code{0} 10959only if your clip has bad chroma problems such as heavy rainbowing or other 10960artifacts. Setting this to @code{0} could also be used to speed things up at 10961the cost of some accuracy. 10962 10963Default value is @code{1}. 10964 10965@item y0 10966@item y1 10967These define an exclusion band which excludes the lines between @option{y0} and 10968@option{y1} from being included in the field matching decision. An exclusion 10969band can be used to ignore subtitles, a logo, or other things that may 10970interfere with the matching. @option{y0} sets the starting scan line and 10971@option{y1} sets the ending line; all lines in between @option{y0} and 10972@option{y1} (including @option{y0} and @option{y1}) will be ignored. Setting 10973@option{y0} and @option{y1} to the same value will disable the feature. 10974@option{y0} and @option{y1} defaults to @code{0}. 10975 10976@item scthresh 10977Set the scene change detection threshold as a percentage of maximum change on 10978the luma plane. Good values are in the @code{[8.0, 14.0]} range. Scene change 10979detection is only relevant in case @option{combmatch}=@var{sc}. The range for 10980@option{scthresh} is @code{[0.0, 100.0]}. 10981 10982Default value is @code{12.0}. 10983 10984@item combmatch 10985When @option{combatch} is not @var{none}, @code{fieldmatch} will take into 10986account the combed scores of matches when deciding what match to use as the 10987final match. Available values are: 10988 10989@table @samp 10990@item none 10991No final matching based on combed scores. 10992@item sc 10993Combed scores are only used when a scene change is detected. 10994@item full 10995Use combed scores all the time. 10996@end table 10997 10998Default is @var{sc}. 10999 11000@item combdbg 11001Force @code{fieldmatch} to calculate the combed metrics for certain matches and 11002print them. This setting is known as @option{micout} in TFM/VFM vocabulary. 11003Available values are: 11004 11005@table @samp 11006@item none 11007No forced calculation. 11008@item pcn 11009Force p/c/n calculations. 11010@item pcnub 11011Force p/c/n/u/b calculations. 11012@end table 11013 11014Default value is @var{none}. 11015 11016@item cthresh 11017This is the area combing threshold used for combed frame detection. This 11018essentially controls how "strong" or "visible" combing must be to be detected. 11019Larger values mean combing must be more visible and smaller values mean combing 11020can be less visible or strong and still be detected. Valid settings are from 11021@code{-1} (every pixel will be detected as combed) to @code{255} (no pixel will 11022be detected as combed). This is basically a pixel difference value. A good 11023range is @code{[8, 12]}. 11024 11025Default value is @code{9}. 11026 11027@item chroma 11028Sets whether or not chroma is considered in the combed frame decision. Only 11029disable this if your source has chroma problems (rainbowing, etc.) that are 11030causing problems for the combed frame detection with chroma enabled. Actually, 11031using @option{chroma}=@var{0} is usually more reliable, except for the case 11032where there is chroma only combing in the source. 11033 11034Default value is @code{0}. 11035 11036@item blockx 11037@item blocky 11038Respectively set the x-axis and y-axis size of the window used during combed 11039frame detection. This has to do with the size of the area in which 11040@option{combpel} pixels are required to be detected as combed for a frame to be 11041declared combed. See the @option{combpel} parameter description for more info. 11042Possible values are any number that is a power of 2 starting at 4 and going up 11043to 512. 11044 11045Default value is @code{16}. 11046 11047@item combpel 11048The number of combed pixels inside any of the @option{blocky} by 11049@option{blockx} size blocks on the frame for the frame to be detected as 11050combed. While @option{cthresh} controls how "visible" the combing must be, this 11051setting controls "how much" combing there must be in any localized area (a 11052window defined by the @option{blockx} and @option{blocky} settings) on the 11053frame. Minimum value is @code{0} and maximum is @code{blocky x blockx} (at 11054which point no frames will ever be detected as combed). This setting is known 11055as @option{MI} in TFM/VFM vocabulary. 11056 11057Default value is @code{80}. 11058@end table 11059 11060@anchor{p/c/n/u/b meaning} 11061@subsection p/c/n/u/b meaning 11062 11063@subsubsection p/c/n 11064 11065We assume the following telecined stream: 11066 11067@example 11068Top fields: 1 2 2 3 4 11069Bottom fields: 1 2 3 4 4 11070@end example 11071 11072The numbers correspond to the progressive frame the fields relate to. Here, the 11073first two frames are progressive, the 3rd and 4th are combed, and so on. 11074 11075When @code{fieldmatch} is configured to run a matching from bottom 11076(@option{field}=@var{bottom}) this is how this input stream get transformed: 11077 11078@example 11079Input stream: 11080 T 1 2 2 3 4 11081 B 1 2 3 4 4 <-- matching reference 11082 11083Matches: c c n n c 11084 11085Output stream: 11086 T 1 2 3 4 4 11087 B 1 2 3 4 4 11088@end example 11089 11090As a result of the field matching, we can see that some frames get duplicated. 11091To perform a complete inverse telecine, you need to rely on a decimation filter 11092after this operation. See for instance the @ref{decimate} filter. 11093 11094The same operation now matching from top fields (@option{field}=@var{top}) 11095looks like this: 11096 11097@example 11098Input stream: 11099 T 1 2 2 3 4 <-- matching reference 11100 B 1 2 3 4 4 11101 11102Matches: c c p p c 11103 11104Output stream: 11105 T 1 2 2 3 4 11106 B 1 2 2 3 4 11107@end example 11108 11109In these examples, we can see what @var{p}, @var{c} and @var{n} mean; 11110basically, they refer to the frame and field of the opposite parity: 11111 11112@itemize 11113@item @var{p} matches the field of the opposite parity in the previous frame 11114@item @var{c} matches the field of the opposite parity in the current frame 11115@item @var{n} matches the field of the opposite parity in the next frame 11116@end itemize 11117 11118@subsubsection u/b 11119 11120The @var{u} and @var{b} matching are a bit special in the sense that they match 11121from the opposite parity flag. In the following examples, we assume that we are 11122currently matching the 2nd frame (Top:2, bottom:2). According to the match, a 11123'x' is placed above and below each matched fields. 11124 11125With bottom matching (@option{field}=@var{bottom}): 11126@example 11127Match: c p n b u 11128 11129 x x x x x 11130 Top 1 2 2 1 2 2 1 2 2 1 2 2 1 2 2 11131 Bottom 1 2 3 1 2 3 1 2 3 1 2 3 1 2 3 11132 x x x x x 11133 11134Output frames: 11135 2 1 2 2 2 11136 2 2 2 1 3 11137@end example 11138 11139With top matching (@option{field}=@var{top}): 11140@example 11141Match: c p n b u 11142 11143 x x x x x 11144 Top 1 2 2 1 2 2 1 2 2 1 2 2 1 2 2 11145 Bottom 1 2 3 1 2 3 1 2 3 1 2 3 1 2 3 11146 x x x x x 11147 11148Output frames: 11149 2 2 2 1 2 11150 2 1 3 2 2 11151@end example 11152 11153@subsection Examples 11154 11155Simple IVTC of a top field first telecined stream: 11156@example 11157fieldmatch=order=tff:combmatch=none, decimate 11158@end example 11159 11160Advanced IVTC, with fallback on @ref{yadif} for still combed frames: 11161@example 11162fieldmatch=order=tff:combmatch=full, yadif=deint=interlaced, decimate 11163@end example 11164 11165@section fieldorder 11166 11167Transform the field order of the input video. 11168 11169It accepts the following parameters: 11170 11171@table @option 11172 11173@item order 11174The output field order. Valid values are @var{tff} for top field first or @var{bff} 11175for bottom field first. 11176@end table 11177 11178The default value is @samp{tff}. 11179 11180The transformation is done by shifting the picture content up or down 11181by one line, and filling the remaining line with appropriate picture content. 11182This method is consistent with most broadcast field order converters. 11183 11184If the input video is not flagged as being interlaced, or it is already 11185flagged as being of the required output field order, then this filter does 11186not alter the incoming video. 11187 11188It is very useful when converting to or from PAL DV material, 11189which is bottom field first. 11190 11191For example: 11192@example 11193ffmpeg -i in.vob -vf "fieldorder=bff" out.dv 11194@end example 11195 11196@section fifo, afifo 11197 11198Buffer input images and send them when they are requested. 11199 11200It is mainly useful when auto-inserted by the libavfilter 11201framework. 11202 11203It does not take parameters. 11204 11205@section fillborders 11206 11207Fill borders of the input video, without changing video stream dimensions. 11208Sometimes video can have garbage at the four edges and you may not want to 11209crop video input to keep size multiple of some number. 11210 11211This filter accepts the following options: 11212 11213@table @option 11214@item left 11215Number of pixels to fill from left border. 11216 11217@item right 11218Number of pixels to fill from right border. 11219 11220@item top 11221Number of pixels to fill from top border. 11222 11223@item bottom 11224Number of pixels to fill from bottom border. 11225 11226@item mode 11227Set fill mode. 11228 11229It accepts the following values: 11230@table @samp 11231@item smear 11232fill pixels using outermost pixels 11233 11234@item mirror 11235fill pixels using mirroring 11236 11237@item fixed 11238fill pixels with constant value 11239@end table 11240 11241Default is @var{smear}. 11242 11243@item color 11244Set color for pixels in fixed mode. Default is @var{black}. 11245@end table 11246 11247@subsection Commands 11248This filter supports same @ref{commands} as options. 11249The command accepts the same syntax of the corresponding option. 11250 11251If the specified expression is not valid, it is kept at its current 11252value. 11253 11254@section find_rect 11255 11256Find a rectangular object 11257 11258It accepts the following options: 11259 11260@table @option 11261@item object 11262Filepath of the object image, needs to be in gray8. 11263 11264@item threshold 11265Detection threshold, default is 0.5. 11266 11267@item mipmaps 11268Number of mipmaps, default is 3. 11269 11270@item xmin, ymin, xmax, ymax 11271Specifies the rectangle in which to search. 11272@end table 11273 11274@subsection Examples 11275 11276@itemize 11277@item 11278Cover a rectangular object by the supplied image of a given video using @command{ffmpeg}: 11279@example 11280ffmpeg -i file.ts -vf find_rect=newref.pgm,cover_rect=cover.jpg:mode=cover new.mkv 11281@end example 11282@end itemize 11283 11284@section floodfill 11285 11286Flood area with values of same pixel components with another values. 11287 11288It accepts the following options: 11289@table @option 11290@item x 11291Set pixel x coordinate. 11292 11293@item y 11294Set pixel y coordinate. 11295 11296@item s0 11297Set source #0 component value. 11298 11299@item s1 11300Set source #1 component value. 11301 11302@item s2 11303Set source #2 component value. 11304 11305@item s3 11306Set source #3 component value. 11307 11308@item d0 11309Set destination #0 component value. 11310 11311@item d1 11312Set destination #1 component value. 11313 11314@item d2 11315Set destination #2 component value. 11316 11317@item d3 11318Set destination #3 component value. 11319@end table 11320 11321@anchor{format} 11322@section format 11323 11324Convert the input video to one of the specified pixel formats. 11325Libavfilter will try to pick one that is suitable as input to 11326the next filter. 11327 11328It accepts the following parameters: 11329@table @option 11330 11331@item pix_fmts 11332A '|'-separated list of pixel format names, such as 11333"pix_fmts=yuv420p|monow|rgb24". 11334 11335@end table 11336 11337@subsection Examples 11338 11339@itemize 11340@item 11341Convert the input video to the @var{yuv420p} format 11342@example 11343format=pix_fmts=yuv420p 11344@end example 11345 11346Convert the input video to any of the formats in the list 11347@example 11348format=pix_fmts=yuv420p|yuv444p|yuv410p 11349@end example 11350@end itemize 11351 11352@anchor{fps} 11353@section fps 11354 11355Convert the video to specified constant frame rate by duplicating or dropping 11356frames as necessary. 11357 11358It accepts the following parameters: 11359@table @option 11360 11361@item fps 11362The desired output frame rate. The default is @code{25}. 11363 11364@item start_time 11365Assume the first PTS should be the given value, in seconds. This allows for 11366padding/trimming at the start of stream. By default, no assumption is made 11367about the first frame's expected PTS, so no padding or trimming is done. 11368For example, this could be set to 0 to pad the beginning with duplicates of 11369the first frame if a video stream starts after the audio stream or to trim any 11370frames with a negative PTS. 11371 11372@item round 11373Timestamp (PTS) rounding method. 11374 11375Possible values are: 11376@table @option 11377@item zero 11378round towards 0 11379@item inf 11380round away from 0 11381@item down 11382round towards -infinity 11383@item up 11384round towards +infinity 11385@item near 11386round to nearest 11387@end table 11388The default is @code{near}. 11389 11390@item eof_action 11391Action performed when reading the last frame. 11392 11393Possible values are: 11394@table @option 11395@item round 11396Use same timestamp rounding method as used for other frames. 11397@item pass 11398Pass through last frame if input duration has not been reached yet. 11399@end table 11400The default is @code{round}. 11401 11402@end table 11403 11404Alternatively, the options can be specified as a flat string: 11405@var{fps}[:@var{start_time}[:@var{round}]]. 11406 11407See also the @ref{setpts} filter. 11408 11409@subsection Examples 11410 11411@itemize 11412@item 11413A typical usage in order to set the fps to 25: 11414@example 11415fps=fps=25 11416@end example 11417 11418@item 11419Sets the fps to 24, using abbreviation and rounding method to round to nearest: 11420@example 11421fps=fps=film:round=near 11422@end example 11423@end itemize 11424 11425@section framepack 11426 11427Pack two different video streams into a stereoscopic video, setting proper 11428metadata on supported codecs. The two views should have the same size and 11429framerate and processing will stop when the shorter video ends. Please note 11430that you may conveniently adjust view properties with the @ref{scale} and 11431@ref{fps} filters. 11432 11433It accepts the following parameters: 11434@table @option 11435 11436@item format 11437The desired packing format. Supported values are: 11438 11439@table @option 11440 11441@item sbs 11442The views are next to each other (default). 11443 11444@item tab 11445The views are on top of each other. 11446 11447@item lines 11448The views are packed by line. 11449 11450@item columns 11451The views are packed by column. 11452 11453@item frameseq 11454The views are temporally interleaved. 11455 11456@end table 11457 11458@end table 11459 11460Some examples: 11461 11462@example 11463# Convert left and right views into a frame-sequential video 11464ffmpeg -i LEFT -i RIGHT -filter_complex framepack=frameseq OUTPUT 11465 11466# Convert views into a side-by-side video with the same output resolution as the input 11467ffmpeg -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 11468@end example 11469 11470@section framerate 11471 11472Change the frame rate by interpolating new video output frames from the source 11473frames. 11474 11475This filter is not designed to function correctly with interlaced media. If 11476you wish to change the frame rate of interlaced media then you are required 11477to deinterlace before this filter and re-interlace after this filter. 11478 11479A description of the accepted options follows. 11480 11481@table @option 11482@item fps 11483Specify the output frames per second. This option can also be specified 11484as a value alone. The default is @code{50}. 11485 11486@item interp_start 11487Specify the start of a range where the output frame will be created as a 11488linear interpolation of two frames. The range is [@code{0}-@code{255}], 11489the default is @code{15}. 11490 11491@item interp_end 11492Specify the end of a range where the output frame will be created as a 11493linear interpolation of two frames. The range is [@code{0}-@code{255}], 11494the default is @code{240}. 11495 11496@item scene 11497Specify the level at which a scene change is detected as a value between 114980 and 100 to indicate a new scene; a low value reflects a low 11499probability for the current frame to introduce a new scene, while a higher 11500value means the current frame is more likely to be one. 11501The default is @code{8.2}. 11502 11503@item flags 11504Specify flags influencing the filter process. 11505 11506Available value for @var{flags} is: 11507 11508@table @option 11509@item scene_change_detect, scd 11510Enable scene change detection using the value of the option @var{scene}. 11511This flag is enabled by default. 11512@end table 11513@end table 11514 11515@section framestep 11516 11517Select one frame every N-th frame. 11518 11519This filter accepts the following option: 11520@table @option 11521@item step 11522Select frame after every @code{step} frames. 11523Allowed values are positive integers higher than 0. Default value is @code{1}. 11524@end table 11525 11526@section freezedetect 11527 11528Detect frozen video. 11529 11530This filter logs a message and sets frame metadata when it detects that the 11531input video has no significant change in content during a specified duration. 11532Video freeze detection calculates the mean average absolute difference of all 11533the components of video frames and compares it to a noise floor. 11534 11535The printed times and duration are expressed in seconds. The 11536@code{lavfi.freezedetect.freeze_start} metadata key is set on the first frame 11537whose timestamp equals or exceeds the detection duration and it contains the 11538timestamp of the first frame of the freeze. The 11539@code{lavfi.freezedetect.freeze_duration} and 11540@code{lavfi.freezedetect.freeze_end} metadata keys are set on the first frame 11541after the freeze. 11542 11543The filter accepts the following options: 11544 11545@table @option 11546@item noise, n 11547Set noise tolerance. Can be specified in dB (in case "dB" is appended to the 11548specified value) or as a difference ratio between 0 and 1. Default is -60dB, or 115490.001. 11550 11551@item duration, d 11552Set freeze duration until notification (default is 2 seconds). 11553@end table 11554 11555@section freezeframes 11556 11557Freeze video frames. 11558 11559This filter freezes video frames using frame from 2nd input. 11560 11561The filter accepts the following options: 11562 11563@table @option 11564@item first 11565Set number of first frame from which to start freeze. 11566 11567@item last 11568Set number of last frame from which to end freeze. 11569 11570@item replace 11571Set number of frame from 2nd input which will be used instead of replaced frames. 11572@end table 11573 11574@anchor{frei0r} 11575@section frei0r 11576 11577Apply a frei0r effect to the input video. 11578 11579To enable the compilation of this filter, you need to install the frei0r 11580header and configure FFmpeg with @code{--enable-frei0r}. 11581 11582It accepts the following parameters: 11583 11584@table @option 11585 11586@item filter_name 11587The name of the frei0r effect to load. If the environment variable 11588@env{FREI0R_PATH} is defined, the frei0r effect is searched for in each of the 11589directories specified by the colon-separated list in @env{FREI0R_PATH}. 11590Otherwise, the standard frei0r paths are searched, in this order: 11591@file{HOME/.frei0r-1/lib/}, @file{/usr/local/lib/frei0r-1/}, 11592@file{/usr/lib/frei0r-1/}. 11593 11594@item filter_params 11595A '|'-separated list of parameters to pass to the frei0r effect. 11596 11597@end table 11598 11599A frei0r effect parameter can be a boolean (its value is either 11600"y" or "n"), a double, a color (specified as 11601@var{R}/@var{G}/@var{B}, where @var{R}, @var{G}, and @var{B} are floating point 11602numbers between 0.0 and 1.0, inclusive) or a color description as specified in the 11603@ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}, 11604a position (specified as @var{X}/@var{Y}, where 11605@var{X} and @var{Y} are floating point numbers) and/or a string. 11606 11607The number and types of parameters depend on the loaded effect. If an 11608effect parameter is not specified, the default value is set. 11609 11610@subsection Examples 11611 11612@itemize 11613@item 11614Apply the distort0r effect, setting the first two double parameters: 11615@example 11616frei0r=filter_name=distort0r:filter_params=0.5|0.01 11617@end example 11618 11619@item 11620Apply the colordistance effect, taking a color as the first parameter: 11621@example 11622frei0r=colordistance:0.2/0.3/0.4 11623frei0r=colordistance:violet 11624frei0r=colordistance:0x112233 11625@end example 11626 11627@item 11628Apply the perspective effect, specifying the top left and top right image 11629positions: 11630@example 11631frei0r=perspective:0.2/0.2|0.8/0.2 11632@end example 11633@end itemize 11634 11635For more information, see 11636@url{http://frei0r.dyne.org} 11637 11638@section fspp 11639 11640Apply fast and simple postprocessing. It is a faster version of @ref{spp}. 11641 11642It splits (I)DCT into horizontal/vertical passes. Unlike the simple post- 11643processing filter, one of them is performed once per block, not per pixel. 11644This allows for much higher speed. 11645 11646The filter accepts the following options: 11647 11648@table @option 11649@item quality 11650Set quality. This option defines the number of levels for averaging. It accepts 11651an integer in the range 4-5. Default value is @code{4}. 11652 11653@item qp 11654Force a constant quantization parameter. It accepts an integer in range 0-63. 11655If not set, the filter will use the QP from the video stream (if available). 11656 11657@item strength 11658Set filter strength. It accepts an integer in range -15 to 32. Lower values mean 11659more details but also more artifacts, while higher values make the image smoother 11660but also blurrier. Default value is @code{0} − PSNR optimal. 11661 11662@item use_bframe_qp 11663Enable the use of the QP from the B-Frames if set to @code{1}. Using this 11664option may cause flicker since the B-Frames have often larger QP. Default is 11665@code{0} (not enabled). 11666 11667@end table 11668 11669@section gblur 11670 11671Apply Gaussian blur filter. 11672 11673The filter accepts the following options: 11674 11675@table @option 11676@item sigma 11677Set horizontal sigma, standard deviation of Gaussian blur. Default is @code{0.5}. 11678 11679@item steps 11680Set number of steps for Gaussian approximation. Default is @code{1}. 11681 11682@item planes 11683Set which planes to filter. By default all planes are filtered. 11684 11685@item sigmaV 11686Set vertical sigma, if negative it will be same as @code{sigma}. 11687Default is @code{-1}. 11688@end table 11689 11690@subsection Commands 11691This filter supports same commands as options. 11692The command accepts the same syntax of the corresponding option. 11693 11694If the specified expression is not valid, it is kept at its current 11695value. 11696 11697@section geq 11698 11699Apply generic equation to each pixel. 11700 11701The filter accepts the following options: 11702 11703@table @option 11704@item lum_expr, lum 11705Set the luminance expression. 11706@item cb_expr, cb 11707Set the chrominance blue expression. 11708@item cr_expr, cr 11709Set the chrominance red expression. 11710@item alpha_expr, a 11711Set the alpha expression. 11712@item red_expr, r 11713Set the red expression. 11714@item green_expr, g 11715Set the green expression. 11716@item blue_expr, b 11717Set the blue expression. 11718@end table 11719 11720The colorspace is selected according to the specified options. If one 11721of the @option{lum_expr}, @option{cb_expr}, or @option{cr_expr} 11722options is specified, the filter will automatically select a YCbCr 11723colorspace. If one of the @option{red_expr}, @option{green_expr}, or 11724@option{blue_expr} options is specified, it will select an RGB 11725colorspace. 11726 11727If one of the chrominance expression is not defined, it falls back on the other 11728one. If no alpha expression is specified it will evaluate to opaque value. 11729If none of chrominance expressions are specified, they will evaluate 11730to the luminance expression. 11731 11732The expressions can use the following variables and functions: 11733 11734@table @option 11735@item N 11736The sequential number of the filtered frame, starting from @code{0}. 11737 11738@item X 11739@item Y 11740The coordinates of the current sample. 11741 11742@item W 11743@item H 11744The width and height of the image. 11745 11746@item SW 11747@item SH 11748Width and height scale depending on the currently filtered plane. It is the 11749ratio between the corresponding luma plane number of pixels and the current 11750plane ones. E.g. for YUV4:2:0 the values are @code{1,1} for the luma plane, and 11751@code{0.5,0.5} for chroma planes. 11752 11753@item T 11754Time of the current frame, expressed in seconds. 11755 11756@item p(x, y) 11757Return the value of the pixel at location (@var{x},@var{y}) of the current 11758plane. 11759 11760@item lum(x, y) 11761Return the value of the pixel at location (@var{x},@var{y}) of the luminance 11762plane. 11763 11764@item cb(x, y) 11765Return the value of the pixel at location (@var{x},@var{y}) of the 11766blue-difference chroma plane. Return 0 if there is no such plane. 11767 11768@item cr(x, y) 11769Return the value of the pixel at location (@var{x},@var{y}) of the 11770red-difference chroma plane. Return 0 if there is no such plane. 11771 11772@item r(x, y) 11773@item g(x, y) 11774@item b(x, y) 11775Return the value of the pixel at location (@var{x},@var{y}) of the 11776red/green/blue component. Return 0 if there is no such component. 11777 11778@item alpha(x, y) 11779Return the value of the pixel at location (@var{x},@var{y}) of the alpha 11780plane. Return 0 if there is no such plane. 11781 11782@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) 11783Sum of sample values in the rectangle from (0,0) to (x,y), this allows obtaining 11784sums of samples within a rectangle. See the functions without the sum postfix. 11785 11786@item interpolation 11787Set one of interpolation methods: 11788@table @option 11789@item nearest, n 11790@item bilinear, b 11791@end table 11792Default is bilinear. 11793@end table 11794 11795For functions, if @var{x} and @var{y} are outside the area, the value will be 11796automatically clipped to the closer edge. 11797 11798Please note that this filter can use multiple threads in which case each slice 11799will have its own expression state. If you want to use only a single expression 11800state because your expressions depend on previous state then you should limit 11801the number of filter threads to 1. 11802 11803@subsection Examples 11804 11805@itemize 11806@item 11807Flip the image horizontally: 11808@example 11809geq=p(W-X\,Y) 11810@end example 11811 11812@item 11813Generate a bidimensional sine wave, with angle @code{PI/3} and a 11814wavelength of 100 pixels: 11815@example 11816geq=128 + 100*sin(2*(PI/100)*(cos(PI/3)*(X-50*T) + sin(PI/3)*Y)):128:128 11817@end example 11818 11819@item 11820Generate a fancy enigmatic moving light: 11821@example 11822nullsrc=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 11823@end example 11824 11825@item 11826Generate a quick emboss effect: 11827@example 11828format=gray,geq=lum_expr='(p(X,Y)+(256-p(X-4,Y-4)))/2' 11829@end example 11830 11831@item 11832Modify RGB components depending on pixel position: 11833@example 11834geq=r='X/W*r(X,Y)':g='(1-X/W)*g(X,Y)':b='(H-Y)/H*b(X,Y)' 11835@end example 11836 11837@item 11838Create a radial gradient that is the same size as the input (also see 11839the @ref{vignette} filter): 11840@example 11841geq=lum=255*gauss((X/W-0.5)*3)*gauss((Y/H-0.5)*3)/gauss(0)/gauss(0),format=gray 11842@end example 11843@end itemize 11844 11845@section gradfun 11846 11847Fix the banding artifacts that are sometimes introduced into nearly flat 11848regions by truncation to 8-bit color depth. 11849Interpolate the gradients that should go where the bands are, and 11850dither them. 11851 11852It is designed for playback only. Do not use it prior to 11853lossy compression, because compression tends to lose the dither and 11854bring back the bands. 11855 11856It accepts the following parameters: 11857 11858@table @option 11859 11860@item strength 11861The maximum amount by which the filter will change any one pixel. This is also 11862the threshold for detecting nearly flat regions. Acceptable values range from 11863.51 to 64; the default value is 1.2. Out-of-range values will be clipped to the 11864valid range. 11865 11866@item radius 11867The neighborhood to fit the gradient to. A larger radius makes for smoother 11868gradients, but also prevents the filter from modifying the pixels near detailed 11869regions. Acceptable values are 8-32; the default value is 16. Out-of-range 11870values will be clipped to the valid range. 11871 11872@end table 11873 11874Alternatively, the options can be specified as a flat string: 11875@var{strength}[:@var{radius}] 11876 11877@subsection Examples 11878 11879@itemize 11880@item 11881Apply the filter with a @code{3.5} strength and radius of @code{8}: 11882@example 11883gradfun=3.5:8 11884@end example 11885 11886@item 11887Specify radius, omitting the strength (which will fall-back to the default 11888value): 11889@example 11890gradfun=radius=8 11891@end example 11892 11893@end itemize 11894 11895@anchor{graphmonitor} 11896@section graphmonitor 11897Show various filtergraph stats. 11898 11899With this filter one can debug complete filtergraph. 11900Especially issues with links filling with queued frames. 11901 11902The filter accepts the following options: 11903 11904@table @option 11905@item size, s 11906Set video output size. Default is @var{hd720}. 11907 11908@item opacity, o 11909Set video opacity. Default is @var{0.9}. Allowed range is from @var{0} to @var{1}. 11910 11911@item mode, m 11912Set output mode, can be @var{fulll} or @var{compact}. 11913In @var{compact} mode only filters with some queued frames have displayed stats. 11914 11915@item flags, f 11916Set flags which enable which stats are shown in video. 11917 11918Available values for flags are: 11919@table @samp 11920@item queue 11921Display number of queued frames in each link. 11922 11923@item frame_count_in 11924Display number of frames taken from filter. 11925 11926@item frame_count_out 11927Display number of frames given out from filter. 11928 11929@item pts 11930Display current filtered frame pts. 11931 11932@item time 11933Display current filtered frame time. 11934 11935@item timebase 11936Display time base for filter link. 11937 11938@item format 11939Display used format for filter link. 11940 11941@item size 11942Display video size or number of audio channels in case of audio used by filter link. 11943 11944@item rate 11945Display video frame rate or sample rate in case of audio used by filter link. 11946 11947@item eof 11948Display link output status. 11949@end table 11950 11951@item rate, r 11952Set upper limit for video rate of output stream, Default value is @var{25}. 11953This guarantee that output video frame rate will not be higher than this value. 11954@end table 11955 11956@section greyedge 11957A color constancy variation filter which estimates scene illumination via grey edge algorithm 11958and corrects the scene colors accordingly. 11959 11960See: @url{https://staff.science.uva.nl/th.gevers/pub/GeversTIP07.pdf} 11961 11962The filter accepts the following options: 11963 11964@table @option 11965@item difford 11966The order of differentiation to be applied on the scene. Must be chosen in the range 11967[0,2] and default value is 1. 11968 11969@item minknorm 11970The Minkowski parameter to be used for calculating the Minkowski distance. Must 11971be chosen in the range [0,20] and default value is 1. Set to 0 for getting 11972max value instead of calculating Minkowski distance. 11973 11974@item sigma 11975The standard deviation of Gaussian blur to be applied on the scene. Must be 11976chosen in the range [0,1024.0] and default value = 1. floor( @var{sigma} * break_off_sigma(3) ) 11977can't be equal to 0 if @var{difford} is greater than 0. 11978@end table 11979 11980@subsection Examples 11981@itemize 11982 11983@item 11984Grey Edge: 11985@example 11986greyedge=difford=1:minknorm=5:sigma=2 11987@end example 11988 11989@item 11990Max Edge: 11991@example 11992greyedge=difford=1:minknorm=0:sigma=2 11993@end example 11994 11995@end itemize 11996 11997@anchor{haldclut} 11998@section haldclut 11999 12000Apply a Hald CLUT to a video stream. 12001 12002First input is the video stream to process, and second one is the Hald CLUT. 12003The Hald CLUT input can be a simple picture or a complete video stream. 12004 12005The filter accepts the following options: 12006 12007@table @option 12008@item shortest 12009Force termination when the shortest input terminates. Default is @code{0}. 12010@item repeatlast 12011Continue applying the last CLUT after the end of the stream. A value of 12012@code{0} disable the filter after the last frame of the CLUT is reached. 12013Default is @code{1}. 12014@end table 12015 12016@code{haldclut} also has the same interpolation options as @ref{lut3d} (both 12017filters share the same internals). 12018 12019This filter also supports the @ref{framesync} options. 12020 12021More information about the Hald CLUT can be found on Eskil Steenberg's website 12022(Hald CLUT author) at @url{http://www.quelsolaar.com/technology/clut.html}. 12023 12024@subsection Workflow examples 12025 12026@subsubsection Hald CLUT video stream 12027 12028Generate an identity Hald CLUT stream altered with various effects: 12029@example 12030ffmpeg -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 12031@end example 12032 12033Note: make sure you use a lossless codec. 12034 12035Then use it with @code{haldclut} to apply it on some random stream: 12036@example 12037ffmpeg -f lavfi -i mandelbrot -i clut.nut -filter_complex '[0][1] haldclut' -t 20 mandelclut.mkv 12038@end example 12039 12040The Hald CLUT will be applied to the 10 first seconds (duration of 12041@file{clut.nut}), then the latest picture of that CLUT stream will be applied 12042to the remaining frames of the @code{mandelbrot} stream. 12043 12044@subsubsection Hald CLUT with preview 12045 12046A Hald CLUT is supposed to be a squared image of @code{Level*Level*Level} by 12047@code{Level*Level*Level} pixels. For a given Hald CLUT, FFmpeg will select the 12048biggest possible square starting at the top left of the picture. The remaining 12049padding pixels (bottom or right) will be ignored. This area can be used to add 12050a preview of the Hald CLUT. 12051 12052Typically, the following generated Hald CLUT will be supported by the 12053@code{haldclut} filter: 12054 12055@example 12056ffmpeg -f lavfi -i @ref{haldclutsrc}=8 -vf " 12057 pad=iw+320 [padded_clut]; 12058 smptebars=s=320x256, split [a][b]; 12059 [padded_clut][a] overlay=W-320:h, curves=color_negative [main]; 12060 [main][b] overlay=W-320" -frames:v 1 clut.png 12061@end example 12062 12063It contains the original and a preview of the effect of the CLUT: SMPTE color 12064bars are displayed on the right-top, and below the same color bars processed by 12065the color changes. 12066 12067Then, the effect of this Hald CLUT can be visualized with: 12068@example 12069ffplay input.mkv -vf "movie=clut.png, [in] haldclut" 12070@end example 12071 12072@section hflip 12073 12074Flip the input video horizontally. 12075 12076For example, to horizontally flip the input video with @command{ffmpeg}: 12077@example 12078ffmpeg -i in.avi -vf "hflip" out.avi 12079@end example 12080 12081@section histeq 12082This filter applies a global color histogram equalization on a 12083per-frame basis. 12084 12085It can be used to correct video that has a compressed range of pixel 12086intensities. The filter redistributes the pixel intensities to 12087equalize their distribution across the intensity range. It may be 12088viewed as an "automatically adjusting contrast filter". This filter is 12089useful only for correcting degraded or poorly captured source 12090video. 12091 12092The filter accepts the following options: 12093 12094@table @option 12095@item strength 12096Determine the amount of equalization to be applied. As the strength 12097is reduced, the distribution of pixel intensities more-and-more 12098approaches that of the input frame. The value must be a float number 12099in the range [0,1] and defaults to 0.200. 12100 12101@item intensity 12102Set the maximum intensity that can generated and scale the output 12103values appropriately. The strength should be set as desired and then 12104the intensity can be limited if needed to avoid washing-out. The value 12105must be a float number in the range [0,1] and defaults to 0.210. 12106 12107@item antibanding 12108Set the antibanding level. If enabled the filter will randomly vary 12109the luminance of output pixels by a small amount to avoid banding of 12110the histogram. Possible values are @code{none}, @code{weak} or 12111@code{strong}. It defaults to @code{none}. 12112@end table 12113 12114@anchor{histogram} 12115@section histogram 12116 12117Compute and draw a color distribution histogram for the input video. 12118 12119The computed histogram is a representation of the color component 12120distribution in an image. 12121 12122Standard histogram displays the color components distribution in an image. 12123Displays color graph for each color component. Shows distribution of 12124the Y, U, V, A or R, G, B components, depending on input format, in the 12125current frame. Below each graph a color component scale meter is shown. 12126 12127The filter accepts the following options: 12128 12129@table @option 12130@item level_height 12131Set height of level. Default value is @code{200}. 12132Allowed range is [50, 2048]. 12133 12134@item scale_height 12135Set height of color scale. Default value is @code{12}. 12136Allowed range is [0, 40]. 12137 12138@item display_mode 12139Set display mode. 12140It accepts the following values: 12141@table @samp 12142@item stack 12143Per color component graphs are placed below each other. 12144 12145@item parade 12146Per color component graphs are placed side by side. 12147 12148@item overlay 12149Presents information identical to that in the @code{parade}, except 12150that the graphs representing color components are superimposed directly 12151over one another. 12152@end table 12153Default is @code{stack}. 12154 12155@item levels_mode 12156Set mode. Can be either @code{linear}, or @code{logarithmic}. 12157Default is @code{linear}. 12158 12159@item components 12160Set what color components to display. 12161Default is @code{7}. 12162 12163@item fgopacity 12164Set foreground opacity. Default is @code{0.7}. 12165 12166@item bgopacity 12167Set background opacity. Default is @code{0.5}. 12168@end table 12169 12170@subsection Examples 12171 12172@itemize 12173 12174@item 12175Calculate and draw histogram: 12176@example 12177ffplay -i input -vf histogram 12178@end example 12179 12180@end itemize 12181 12182@anchor{hqdn3d} 12183@section hqdn3d 12184 12185This is a high precision/quality 3d denoise filter. It aims to reduce 12186image noise, producing smooth images and making still images really 12187still. It should enhance compressibility. 12188 12189It accepts the following optional parameters: 12190 12191@table @option 12192@item luma_spatial 12193A non-negative floating point number which specifies spatial luma strength. 12194It defaults to 4.0. 12195 12196@item chroma_spatial 12197A non-negative floating point number which specifies spatial chroma strength. 12198It defaults to 3.0*@var{luma_spatial}/4.0. 12199 12200@item luma_tmp 12201A floating point number which specifies luma temporal strength. It defaults to 122026.0*@var{luma_spatial}/4.0. 12203 12204@item chroma_tmp 12205A floating point number which specifies chroma temporal strength. It defaults to 12206@var{luma_tmp}*@var{chroma_spatial}/@var{luma_spatial}. 12207@end table 12208 12209@subsection Commands 12210This filter supports same @ref{commands} as options. 12211The command accepts the same syntax of the corresponding option. 12212 12213If the specified expression is not valid, it is kept at its current 12214value. 12215 12216@anchor{hwdownload} 12217@section hwdownload 12218 12219Download hardware frames to system memory. 12220 12221The input must be in hardware frames, and the output a non-hardware format. 12222Not all formats will be supported on the output - it may be necessary to insert 12223an additional @option{format} filter immediately following in the graph to get 12224the output in a supported format. 12225 12226@section hwmap 12227 12228Map hardware frames to system memory or to another device. 12229 12230This filter has several different modes of operation; which one is used depends 12231on the input and output formats: 12232@itemize 12233@item 12234Hardware frame input, normal frame output 12235 12236Map the input frames to system memory and pass them to the output. If the 12237original hardware frame is later required (for example, after overlaying 12238something else on part of it), the @option{hwmap} filter can be used again 12239in the next mode to retrieve it. 12240@item 12241Normal frame input, hardware frame output 12242 12243If the input is actually a software-mapped hardware frame, then unmap it - 12244that is, return the original hardware frame. 12245 12246Otherwise, a device must be provided. Create new hardware surfaces on that 12247device for the output, then map them back to the software format at the input 12248and give those frames to the preceding filter. This will then act like the 12249@option{hwupload} filter, but may be able to avoid an additional copy when 12250the input is already in a compatible format. 12251@item 12252Hardware frame input and output 12253 12254A device must be supplied for the output, either directly or with the 12255@option{derive_device} option. The input and output devices must be of 12256different types and compatible - the exact meaning of this is 12257system-dependent, but typically it means that they must refer to the same 12258underlying hardware context (for example, refer to the same graphics card). 12259 12260If the input frames were originally created on the output device, then unmap 12261to retrieve the original frames. 12262 12263Otherwise, map the frames to the output device - create new hardware frames 12264on the output corresponding to the frames on the input. 12265@end itemize 12266 12267The following additional parameters are accepted: 12268 12269@table @option 12270@item mode 12271Set the frame mapping mode. Some combination of: 12272@table @var 12273@item read 12274The mapped frame should be readable. 12275@item write 12276The mapped frame should be writeable. 12277@item overwrite 12278The mapping will always overwrite the entire frame. 12279 12280This may improve performance in some cases, as the original contents of the 12281frame need not be loaded. 12282@item direct 12283The mapping must not involve any copying. 12284 12285Indirect mappings to copies of frames are created in some cases where either 12286direct mapping is not possible or it would have unexpected properties. 12287Setting this flag ensures that the mapping is direct and will fail if that is 12288not possible. 12289@end table 12290Defaults to @var{read+write} if not specified. 12291 12292@item derive_device @var{type} 12293Rather than using the device supplied at initialisation, instead derive a new 12294device of type @var{type} from the device the input frames exist on. 12295 12296@item reverse 12297In a hardware to hardware mapping, map in reverse - create frames in the sink 12298and map them back to the source. This may be necessary in some cases where 12299a mapping in one direction is required but only the opposite direction is 12300supported by the devices being used. 12301 12302This option is dangerous - it may break the preceding filter in undefined 12303ways if there are any additional constraints on that filter's output. 12304Do not use it without fully understanding the implications of its use. 12305@end table 12306 12307@anchor{hwupload} 12308@section hwupload 12309 12310Upload system memory frames to hardware surfaces. 12311 12312The device to upload to must be supplied when the filter is initialised. If 12313using ffmpeg, select the appropriate device with the @option{-filter_hw_device} 12314option or with the @option{derive_device} option. The input and output devices 12315must be of different types and compatible - the exact meaning of this is 12316system-dependent, but typically it means that they must refer to the same 12317underlying hardware context (for example, refer to the same graphics card). 12318 12319The following additional parameters are accepted: 12320 12321@table @option 12322@item derive_device @var{type} 12323Rather than using the device supplied at initialisation, instead derive a new 12324device of type @var{type} from the device the input frames exist on. 12325@end table 12326 12327@anchor{hwupload_cuda} 12328@section hwupload_cuda 12329 12330Upload system memory frames to a CUDA device. 12331 12332It accepts the following optional parameters: 12333 12334@table @option 12335@item device 12336The number of the CUDA device to use 12337@end table 12338 12339@section hqx 12340 12341Apply a high-quality magnification filter designed for pixel art. This filter 12342was originally created by Maxim Stepin. 12343 12344It accepts the following option: 12345 12346@table @option 12347@item n 12348Set the scaling dimension: @code{2} for @code{hq2x}, @code{3} for 12349@code{hq3x} and @code{4} for @code{hq4x}. 12350Default is @code{3}. 12351@end table 12352 12353@section hstack 12354Stack input videos horizontally. 12355 12356All streams must be of same pixel format and of same height. 12357 12358Note that this filter is faster than using @ref{overlay} and @ref{pad} filter 12359to create same output. 12360 12361The filter accepts the following option: 12362 12363@table @option 12364@item inputs 12365Set number of input streams. Default is 2. 12366 12367@item shortest 12368If set to 1, force the output to terminate when the shortest input 12369terminates. Default value is 0. 12370@end table 12371 12372@section hue 12373 12374Modify the hue and/or the saturation of the input. 12375 12376It accepts the following parameters: 12377 12378@table @option 12379@item h 12380Specify the hue angle as a number of degrees. It accepts an expression, 12381and defaults to "0". 12382 12383@item s 12384Specify the saturation in the [-10,10] range. It accepts an expression and 12385defaults to "1". 12386 12387@item H 12388Specify the hue angle as a number of radians. It accepts an 12389expression, and defaults to "0". 12390 12391@item b 12392Specify the brightness in the [-10,10] range. It accepts an expression and 12393defaults to "0". 12394@end table 12395 12396@option{h} and @option{H} are mutually exclusive, and can't be 12397specified at the same time. 12398 12399The @option{b}, @option{h}, @option{H} and @option{s} option values are 12400expressions containing the following constants: 12401 12402@table @option 12403@item n 12404frame count of the input frame starting from 0 12405 12406@item pts 12407presentation timestamp of the input frame expressed in time base units 12408 12409@item r 12410frame rate of the input video, NAN if the input frame rate is unknown 12411 12412@item t 12413timestamp expressed in seconds, NAN if the input timestamp is unknown 12414 12415@item tb 12416time base of the input video 12417@end table 12418 12419@subsection Examples 12420 12421@itemize 12422@item 12423Set the hue to 90 degrees and the saturation to 1.0: 12424@example 12425hue=h=90:s=1 12426@end example 12427 12428@item 12429Same command but expressing the hue in radians: 12430@example 12431hue=H=PI/2:s=1 12432@end example 12433 12434@item 12435Rotate hue and make the saturation swing between 0 12436and 2 over a period of 1 second: 12437@example 12438hue="H=2*PI*t: s=sin(2*PI*t)+1" 12439@end example 12440 12441@item 12442Apply a 3 seconds saturation fade-in effect starting at 0: 12443@example 12444hue="s=min(t/3\,1)" 12445@end example 12446 12447The general fade-in expression can be written as: 12448@example 12449hue="s=min(0\, max((t-START)/DURATION\, 1))" 12450@end example 12451 12452@item 12453Apply a 3 seconds saturation fade-out effect starting at 5 seconds: 12454@example 12455hue="s=max(0\, min(1\, (8-t)/3))" 12456@end example 12457 12458The general fade-out expression can be written as: 12459@example 12460hue="s=max(0\, min(1\, (START+DURATION-t)/DURATION))" 12461@end example 12462 12463@end itemize 12464 12465@subsection Commands 12466 12467This filter supports the following commands: 12468@table @option 12469@item b 12470@item s 12471@item h 12472@item H 12473Modify the hue and/or the saturation and/or brightness of the input video. 12474The command accepts the same syntax of the corresponding option. 12475 12476If the specified expression is not valid, it is kept at its current 12477value. 12478@end table 12479 12480@section hysteresis 12481 12482Grow first stream into second stream by connecting components. 12483This makes it possible to build more robust edge masks. 12484 12485This filter accepts the following options: 12486 12487@table @option 12488@item planes 12489Set which planes will be processed as bitmap, unprocessed planes will be 12490copied from first stream. 12491By default value 0xf, all planes will be processed. 12492 12493@item threshold 12494Set threshold which is used in filtering. If pixel component value is higher than 12495this value filter algorithm for connecting components is activated. 12496By default value is 0. 12497@end table 12498 12499The @code{hysteresis} filter also supports the @ref{framesync} options. 12500 12501@section idet 12502 12503Detect video interlacing type. 12504 12505This filter tries to detect if the input frames are interlaced, progressive, 12506top or bottom field first. It will also try to detect fields that are 12507repeated between adjacent frames (a sign of telecine). 12508 12509Single frame detection considers only immediately adjacent frames when classifying each frame. 12510Multiple frame detection incorporates the classification history of previous frames. 12511 12512The filter will log these metadata values: 12513 12514@table @option 12515@item single.current_frame 12516Detected type of current frame using single-frame detection. One of: 12517``tff'' (top field first), ``bff'' (bottom field first), 12518``progressive'', or ``undetermined'' 12519 12520@item single.tff 12521Cumulative number of frames detected as top field first using single-frame detection. 12522 12523@item multiple.tff 12524Cumulative number of frames detected as top field first using multiple-frame detection. 12525 12526@item single.bff 12527Cumulative number of frames detected as bottom field first using single-frame detection. 12528 12529@item multiple.current_frame 12530Detected type of current frame using multiple-frame detection. One of: 12531``tff'' (top field first), ``bff'' (bottom field first), 12532``progressive'', or ``undetermined'' 12533 12534@item multiple.bff 12535Cumulative number of frames detected as bottom field first using multiple-frame detection. 12536 12537@item single.progressive 12538Cumulative number of frames detected as progressive using single-frame detection. 12539 12540@item multiple.progressive 12541Cumulative number of frames detected as progressive using multiple-frame detection. 12542 12543@item single.undetermined 12544Cumulative number of frames that could not be classified using single-frame detection. 12545 12546@item multiple.undetermined 12547Cumulative number of frames that could not be classified using multiple-frame detection. 12548 12549@item repeated.current_frame 12550Which field in the current frame is repeated from the last. One of ``neither'', ``top'', or ``bottom''. 12551 12552@item repeated.neither 12553Cumulative number of frames with no repeated field. 12554 12555@item repeated.top 12556Cumulative number of frames with the top field repeated from the previous frame's top field. 12557 12558@item repeated.bottom 12559Cumulative number of frames with the bottom field repeated from the previous frame's bottom field. 12560@end table 12561 12562The filter accepts the following options: 12563 12564@table @option 12565@item intl_thres 12566Set interlacing threshold. 12567@item prog_thres 12568Set progressive threshold. 12569@item rep_thres 12570Threshold for repeated field detection. 12571@item half_life 12572Number of frames after which a given frame's contribution to the 12573statistics is halved (i.e., it contributes only 0.5 to its 12574classification). The default of 0 means that all frames seen are given 12575full weight of 1.0 forever. 12576@item analyze_interlaced_flag 12577When this is not 0 then idet will use the specified number of frames to determine 12578if the interlaced flag is accurate, it will not count undetermined frames. 12579If the flag is found to be accurate it will be used without any further 12580computations, if it is found to be inaccurate it will be cleared without any 12581further computations. This allows inserting the idet filter as a low computational 12582method to clean up the interlaced flag 12583@end table 12584 12585@section il 12586 12587Deinterleave or interleave fields. 12588 12589This filter allows one to process interlaced images fields without 12590deinterlacing them. Deinterleaving splits the input frame into 2 12591fields (so called half pictures). Odd lines are moved to the top 12592half of the output image, even lines to the bottom half. 12593You can process (filter) them independently and then re-interleave them. 12594 12595The filter accepts the following options: 12596 12597@table @option 12598@item luma_mode, l 12599@item chroma_mode, c 12600@item alpha_mode, a 12601Available values for @var{luma_mode}, @var{chroma_mode} and 12602@var{alpha_mode} are: 12603 12604@table @samp 12605@item none 12606Do nothing. 12607 12608@item deinterleave, d 12609Deinterleave fields, placing one above the other. 12610 12611@item interleave, i 12612Interleave fields. Reverse the effect of deinterleaving. 12613@end table 12614Default value is @code{none}. 12615 12616@item luma_swap, ls 12617@item chroma_swap, cs 12618@item alpha_swap, as 12619Swap luma/chroma/alpha fields. Exchange even & odd lines. Default value is @code{0}. 12620@end table 12621 12622@subsection Commands 12623 12624This filter supports the all above options as @ref{commands}. 12625 12626@section inflate 12627 12628Apply inflate effect to the video. 12629 12630This filter replaces the pixel by the local(3x3) average by taking into account 12631only values higher than the pixel. 12632 12633It accepts the following options: 12634 12635@table @option 12636@item threshold0 12637@item threshold1 12638@item threshold2 12639@item threshold3 12640Limit the maximum change for each plane, default is 65535. 12641If 0, plane will remain unchanged. 12642@end table 12643 12644@subsection Commands 12645 12646This filter supports the all above options as @ref{commands}. 12647 12648@section interlace 12649 12650Simple interlacing filter from progressive contents. This interleaves upper (or 12651lower) lines from odd frames with lower (or upper) lines from even frames, 12652halving the frame rate and preserving image height. 12653 12654@example 12655 Original Original New Frame 12656 Frame 'j' Frame 'j+1' (tff) 12657 ========== =========== ================== 12658 Line 0 --------------------> Frame 'j' Line 0 12659 Line 1 Line 1 ----> Frame 'j+1' Line 1 12660 Line 2 ---------------------> Frame 'j' Line 2 12661 Line 3 Line 3 ----> Frame 'j+1' Line 3 12662 ... ... ... 12663New Frame + 1 will be generated by Frame 'j+2' and Frame 'j+3' and so on 12664@end example 12665 12666It accepts the following optional parameters: 12667 12668@table @option 12669@item scan 12670This determines whether the interlaced frame is taken from the even 12671(tff - default) or odd (bff) lines of the progressive frame. 12672 12673@item lowpass 12674Vertical lowpass filter to avoid twitter interlacing and 12675reduce moire patterns. 12676 12677@table @samp 12678@item 0, off 12679Disable vertical lowpass filter 12680 12681@item 1, linear 12682Enable linear filter (default) 12683 12684@item 2, complex 12685Enable complex filter. This will slightly less reduce twitter and moire 12686but better retain detail and subjective sharpness impression. 12687 12688@end table 12689@end table 12690 12691@section kerndeint 12692 12693Deinterlace input video by applying Donald Graft's adaptive kernel 12694deinterling. Work on interlaced parts of a video to produce 12695progressive frames. 12696 12697The description of the accepted parameters follows. 12698 12699@table @option 12700@item thresh 12701Set the threshold which affects the filter's tolerance when 12702determining if a pixel line must be processed. It must be an integer 12703in the range [0,255] and defaults to 10. A value of 0 will result in 12704applying the process on every pixels. 12705 12706@item map 12707Paint pixels exceeding the threshold value to white if set to 1. 12708Default is 0. 12709 12710@item order 12711Set the fields order. Swap fields if set to 1, leave fields alone if 127120. Default is 0. 12713 12714@item sharp 12715Enable additional sharpening if set to 1. Default is 0. 12716 12717@item twoway 12718Enable twoway sharpening if set to 1. Default is 0. 12719@end table 12720 12721@subsection Examples 12722 12723@itemize 12724@item 12725Apply default values: 12726@example 12727kerndeint=thresh=10:map=0:order=0:sharp=0:twoway=0 12728@end example 12729 12730@item 12731Enable additional sharpening: 12732@example 12733kerndeint=sharp=1 12734@end example 12735 12736@item 12737Paint processed pixels in white: 12738@example 12739kerndeint=map=1 12740@end example 12741@end itemize 12742 12743@section lagfun 12744 12745Slowly update darker pixels. 12746 12747This filter makes short flashes of light appear longer. 12748This filter accepts the following options: 12749 12750@table @option 12751@item decay 12752Set factor for decaying. Default is .95. Allowed range is from 0 to 1. 12753 12754@item planes 12755Set which planes to filter. Default is all. Allowed range is from 0 to 15. 12756@end table 12757 12758@section lenscorrection 12759 12760Correct radial lens distortion 12761 12762This filter can be used to correct for radial distortion as can result from the use 12763of wide angle lenses, and thereby re-rectify the image. To find the right parameters 12764one can use tools available for example as part of opencv or simply trial-and-error. 12765To use opencv use the calibration sample (under samples/cpp) from the opencv sources 12766and extract the k1 and k2 coefficients from the resulting matrix. 12767 12768Note that effectively the same filter is available in the open-source tools Krita and 12769Digikam from the KDE project. 12770 12771In contrast to the @ref{vignette} filter, which can also be used to compensate lens errors, 12772this filter corrects the distortion of the image, whereas @ref{vignette} corrects the 12773brightness distribution, so you may want to use both filters together in certain 12774cases, though you will have to take care of ordering, i.e. whether vignetting should 12775be applied before or after lens correction. 12776 12777@subsection Options 12778 12779The filter accepts the following options: 12780 12781@table @option 12782@item cx 12783Relative x-coordinate of the focal point of the image, and thereby the center of the 12784distortion. This value has a range [0,1] and is expressed as fractions of the image 12785width. Default is 0.5. 12786@item cy 12787Relative y-coordinate of the focal point of the image, and thereby the center of the 12788distortion. This value has a range [0,1] and is expressed as fractions of the image 12789height. Default is 0.5. 12790@item k1 12791Coefficient of the quadratic correction term. This value has a range [-1,1]. 0 means 12792no correction. Default is 0. 12793@item k2 12794Coefficient of the double quadratic correction term. This value has a range [-1,1]. 127950 means no correction. Default is 0. 12796@end table 12797 12798The formula that generates the correction is: 12799 12800@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) 12801 12802where @var{r_0} is halve of the image diagonal and @var{r_src} and @var{r_tgt} are the 12803distances from the focal point in the source and target images, respectively. 12804 12805@section lensfun 12806 12807Apply lens correction via the lensfun library (@url{http://lensfun.sourceforge.net/}). 12808 12809The @code{lensfun} filter requires the camera make, camera model, and lens model 12810to apply the lens correction. The filter will load the lensfun database and 12811query it to find the corresponding camera and lens entries in the database. As 12812long as these entries can be found with the given options, the filter can 12813perform corrections on frames. Note that incomplete strings will result in the 12814filter choosing the best match with the given options, and the filter will 12815output the chosen camera and lens models (logged with level "info"). You must 12816provide the make, camera model, and lens model as they are required. 12817 12818The filter accepts the following options: 12819 12820@table @option 12821@item make 12822The make of the camera (for example, "Canon"). This option is required. 12823 12824@item model 12825The model of the camera (for example, "Canon EOS 100D"). This option is 12826required. 12827 12828@item lens_model 12829The model of the lens (for example, "Canon EF-S 18-55mm f/3.5-5.6 IS STM"). This 12830option is required. 12831 12832@item mode 12833The type of correction to apply. The following values are valid options: 12834 12835@table @samp 12836@item vignetting 12837Enables fixing lens vignetting. 12838 12839@item geometry 12840Enables fixing lens geometry. This is the default. 12841 12842@item subpixel 12843Enables fixing chromatic aberrations. 12844 12845@item vig_geo 12846Enables fixing lens vignetting and lens geometry. 12847 12848@item vig_subpixel 12849Enables fixing lens vignetting and chromatic aberrations. 12850 12851@item distortion 12852Enables fixing both lens geometry and chromatic aberrations. 12853 12854@item all 12855Enables all possible corrections. 12856 12857@end table 12858@item focal_length 12859The focal length of the image/video (zoom; expected constant for video). For 12860example, a 18--55mm lens has focal length range of [18--55], so a value in that 12861range should be chosen when using that lens. Default 18. 12862 12863@item aperture 12864The aperture of the image/video (expected constant for video). Note that 12865aperture is only used for vignetting correction. Default 3.5. 12866 12867@item focus_distance 12868The focus distance of the image/video (expected constant for video). Note that 12869focus distance is only used for vignetting and only slightly affects the 12870vignetting correction process. If unknown, leave it at the default value (which 12871is 1000). 12872 12873@item scale 12874The scale factor which is applied after transformation. After correction the 12875video is no longer necessarily rectangular. This parameter controls how much of 12876the resulting image is visible. The value 0 means that a value will be chosen 12877automatically such that there is little or no unmapped area in the output 12878image. 1.0 means that no additional scaling is done. Lower values may result 12879in more of the corrected image being visible, while higher values may avoid 12880unmapped areas in the output. 12881 12882@item target_geometry 12883The target geometry of the output image/video. The following values are valid 12884options: 12885 12886@table @samp 12887@item rectilinear (default) 12888@item fisheye 12889@item panoramic 12890@item equirectangular 12891@item fisheye_orthographic 12892@item fisheye_stereographic 12893@item fisheye_equisolid 12894@item fisheye_thoby 12895@end table 12896@item reverse 12897Apply the reverse of image correction (instead of correcting distortion, apply 12898it). 12899 12900@item interpolation 12901The type of interpolation used when correcting distortion. The following values 12902are valid options: 12903 12904@table @samp 12905@item nearest 12906@item linear (default) 12907@item lanczos 12908@end table 12909@end table 12910 12911@subsection Examples 12912 12913@itemize 12914@item 12915Apply lens correction with make "Canon", camera model "Canon EOS 100D", and lens 12916model "Canon EF-S 18-55mm f/3.5-5.6 IS STM" with focal length of "18" and 12917aperture of "8.0". 12918 12919@example 12920ffmpeg -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 12921@end example 12922 12923@item 12924Apply the same as before, but only for the first 5 seconds of video. 12925 12926@example 12927ffmpeg -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 12928@end example 12929 12930@end itemize 12931 12932@section libvmaf 12933 12934Obtain the VMAF (Video Multi-Method Assessment Fusion) 12935score between two input videos. 12936 12937The obtained VMAF score is printed through the logging system. 12938 12939It requires Netflix's vmaf library (libvmaf) as a pre-requisite. 12940After installing the library it can be enabled using: 12941@code{./configure --enable-libvmaf}. 12942If no model path is specified it uses the default model: @code{vmaf_v0.6.1.pkl}. 12943 12944The filter has following options: 12945 12946@table @option 12947@item model_path 12948Set the model path which is to be used for SVM. 12949Default value: @code{"/usr/local/share/model/vmaf_v0.6.1.pkl"} 12950 12951@item log_path 12952Set the file path to be used to store logs. 12953 12954@item log_fmt 12955Set the format of the log file (csv, json or xml). 12956 12957@item enable_transform 12958This option can enable/disable the @code{score_transform} applied to the final predicted VMAF score, 12959if you have specified score_transform option in the input parameter file passed to @code{run_vmaf_training.py} 12960Default value: @code{false} 12961 12962@item phone_model 12963Invokes the phone model which will generate VMAF scores higher than in the 12964regular model, which is more suitable for laptop, TV, etc. viewing conditions. 12965Default value: @code{false} 12966 12967@item psnr 12968Enables computing psnr along with vmaf. 12969Default value: @code{false} 12970 12971@item ssim 12972Enables computing ssim along with vmaf. 12973Default value: @code{false} 12974 12975@item ms_ssim 12976Enables computing ms_ssim along with vmaf. 12977Default value: @code{false} 12978 12979@item pool 12980Set the pool method to be used for computing vmaf. 12981Options are @code{min}, @code{harmonic_mean} or @code{mean} (default). 12982 12983@item n_threads 12984Set number of threads to be used when computing vmaf. 12985Default value: @code{0}, which makes use of all available logical processors. 12986 12987@item n_subsample 12988Set interval for frame subsampling used when computing vmaf. 12989Default value: @code{1} 12990 12991@item enable_conf_interval 12992Enables confidence interval. 12993Default value: @code{false} 12994@end table 12995 12996This filter also supports the @ref{framesync} options. 12997 12998@subsection Examples 12999@itemize 13000@item 13001On the below examples the input file @file{main.mpg} being processed is 13002compared with the reference file @file{ref.mpg}. 13003 13004@example 13005ffmpeg -i main.mpg -i ref.mpg -lavfi libvmaf -f null - 13006@end example 13007 13008@item 13009Example with options: 13010@example 13011ffmpeg -i main.mpg -i ref.mpg -lavfi libvmaf="psnr=1:log_fmt=json" -f null - 13012@end example 13013 13014@item 13015Example with options and different containers: 13016@example 13017ffmpeg -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 - 13018@end example 13019@end itemize 13020 13021@section limiter 13022 13023Limits the pixel components values to the specified range [min, max]. 13024 13025The filter accepts the following options: 13026 13027@table @option 13028@item min 13029Lower bound. Defaults to the lowest allowed value for the input. 13030 13031@item max 13032Upper bound. Defaults to the highest allowed value for the input. 13033 13034@item planes 13035Specify which planes will be processed. Defaults to all available. 13036@end table 13037 13038@section loop 13039 13040Loop video frames. 13041 13042The filter accepts the following options: 13043 13044@table @option 13045@item loop 13046Set the number of loops. Setting this value to -1 will result in infinite loops. 13047Default is 0. 13048 13049@item size 13050Set maximal size in number of frames. Default is 0. 13051 13052@item start 13053Set first frame of loop. Default is 0. 13054@end table 13055 13056@subsection Examples 13057 13058@itemize 13059@item 13060Loop single first frame infinitely: 13061@example 13062loop=loop=-1:size=1:start=0 13063@end example 13064 13065@item 13066Loop single first frame 10 times: 13067@example 13068loop=loop=10:size=1:start=0 13069@end example 13070 13071@item 13072Loop 10 first frames 5 times: 13073@example 13074loop=loop=5:size=10:start=0 13075@end example 13076@end itemize 13077 13078@section lut1d 13079 13080Apply a 1D LUT to an input video. 13081 13082The filter accepts the following options: 13083 13084@table @option 13085@item file 13086Set the 1D LUT file name. 13087 13088Currently supported formats: 13089@table @samp 13090@item cube 13091Iridas 13092@item csp 13093cineSpace 13094@end table 13095 13096@item interp 13097Select interpolation mode. 13098 13099Available values are: 13100 13101@table @samp 13102@item nearest 13103Use values from the nearest defined point. 13104@item linear 13105Interpolate values using the linear interpolation. 13106@item cosine 13107Interpolate values using the cosine interpolation. 13108@item cubic 13109Interpolate values using the cubic interpolation. 13110@item spline 13111Interpolate values using the spline interpolation. 13112@end table 13113@end table 13114 13115@anchor{lut3d} 13116@section lut3d 13117 13118Apply a 3D LUT to an input video. 13119 13120The filter accepts the following options: 13121 13122@table @option 13123@item file 13124Set the 3D LUT file name. 13125 13126Currently supported formats: 13127@table @samp 13128@item 3dl 13129AfterEffects 13130@item cube 13131Iridas 13132@item dat 13133DaVinci 13134@item m3d 13135Pandora 13136@item csp 13137cineSpace 13138@end table 13139@item interp 13140Select interpolation mode. 13141 13142Available values are: 13143 13144@table @samp 13145@item nearest 13146Use values from the nearest defined point. 13147@item trilinear 13148Interpolate values using the 8 points defining a cube. 13149@item tetrahedral 13150Interpolate values using a tetrahedron. 13151@end table 13152@end table 13153 13154@section lumakey 13155 13156Turn certain luma values into transparency. 13157 13158The filter accepts the following options: 13159 13160@table @option 13161@item threshold 13162Set the luma which will be used as base for transparency. 13163Default value is @code{0}. 13164 13165@item tolerance 13166Set the range of luma values to be keyed out. 13167Default value is @code{0.01}. 13168 13169@item softness 13170Set the range of softness. Default value is @code{0}. 13171Use this to control gradual transition from zero to full transparency. 13172@end table 13173 13174@subsection Commands 13175This filter supports same @ref{commands} as options. 13176The command accepts the same syntax of the corresponding option. 13177 13178If the specified expression is not valid, it is kept at its current 13179value. 13180 13181@section lut, lutrgb, lutyuv 13182 13183Compute a look-up table for binding each pixel component input value 13184to an output value, and apply it to the input video. 13185 13186@var{lutyuv} applies a lookup table to a YUV input video, @var{lutrgb} 13187to an RGB input video. 13188 13189These filters accept the following parameters: 13190@table @option 13191@item c0 13192set first pixel component expression 13193@item c1 13194set second pixel component expression 13195@item c2 13196set third pixel component expression 13197@item c3 13198set fourth pixel component expression, corresponds to the alpha component 13199 13200@item r 13201set red component expression 13202@item g 13203set green component expression 13204@item b 13205set blue component expression 13206@item a 13207alpha component expression 13208 13209@item y 13210set Y/luminance component expression 13211@item u 13212set U/Cb component expression 13213@item v 13214set V/Cr component expression 13215@end table 13216 13217Each of them specifies the expression to use for computing the lookup table for 13218the corresponding pixel component values. 13219 13220The exact component associated to each of the @var{c*} options depends on the 13221format in input. 13222 13223The @var{lut} filter requires either YUV or RGB pixel formats in input, 13224@var{lutrgb} requires RGB pixel formats in input, and @var{lutyuv} requires YUV. 13225 13226The expressions can contain the following constants and functions: 13227 13228@table @option 13229@item w 13230@item h 13231The input width and height. 13232 13233@item val 13234The input value for the pixel component. 13235 13236@item clipval 13237The input value, clipped to the @var{minval}-@var{maxval} range. 13238 13239@item maxval 13240The maximum value for the pixel component. 13241 13242@item minval 13243The minimum value for the pixel component. 13244 13245@item negval 13246The negated value for the pixel component value, clipped to the 13247@var{minval}-@var{maxval} range; it corresponds to the expression 13248"maxval-clipval+minval". 13249 13250@item clip(val) 13251The computed value in @var{val}, clipped to the 13252@var{minval}-@var{maxval} range. 13253 13254@item gammaval(gamma) 13255The computed gamma correction value of the pixel component value, 13256clipped to the @var{minval}-@var{maxval} range. It corresponds to the 13257expression 13258"pow((clipval-minval)/(maxval-minval)\,@var{gamma})*(maxval-minval)+minval" 13259 13260@end table 13261 13262All expressions default to "val". 13263 13264@subsection Examples 13265 13266@itemize 13267@item 13268Negate input video: 13269@example 13270lutrgb="r=maxval+minval-val:g=maxval+minval-val:b=maxval+minval-val" 13271lutyuv="y=maxval+minval-val:u=maxval+minval-val:v=maxval+minval-val" 13272@end example 13273 13274The above is the same as: 13275@example 13276lutrgb="r=negval:g=negval:b=negval" 13277lutyuv="y=negval:u=negval:v=negval" 13278@end example 13279 13280@item 13281Negate luminance: 13282@example 13283lutyuv=y=negval 13284@end example 13285 13286@item 13287Remove chroma components, turning the video into a graytone image: 13288@example 13289lutyuv="u=128:v=128" 13290@end example 13291 13292@item 13293Apply a luma burning effect: 13294@example 13295lutyuv="y=2*val" 13296@end example 13297 13298@item 13299Remove green and blue components: 13300@example 13301lutrgb="g=0:b=0" 13302@end example 13303 13304@item 13305Set a constant alpha channel value on input: 13306@example 13307format=rgba,lutrgb=a="maxval-minval/2" 13308@end example 13309 13310@item 13311Correct luminance gamma by a factor of 0.5: 13312@example 13313lutyuv=y=gammaval(0.5) 13314@end example 13315 13316@item 13317Discard least significant bits of luma: 13318@example 13319lutyuv=y='bitand(val, 128+64+32)' 13320@end example 13321 13322@item 13323Technicolor like effect: 13324@example 13325lutyuv=u='(val-maxval/2)*2+maxval/2':v='(val-maxval/2)*2+maxval/2' 13326@end example 13327@end itemize 13328 13329@section lut2, tlut2 13330 13331The @code{lut2} filter takes two input streams and outputs one 13332stream. 13333 13334The @code{tlut2} (time lut2) filter takes two consecutive frames 13335from one single stream. 13336 13337This filter accepts the following parameters: 13338@table @option 13339@item c0 13340set first pixel component expression 13341@item c1 13342set second pixel component expression 13343@item c2 13344set third pixel component expression 13345@item c3 13346set fourth pixel component expression, corresponds to the alpha component 13347 13348@item d 13349set output bit depth, only available for @code{lut2} filter. By default is 0, 13350which means bit depth is automatically picked from first input format. 13351@end table 13352 13353The @code{lut2} filter also supports the @ref{framesync} options. 13354 13355Each of them specifies the expression to use for computing the lookup table for 13356the corresponding pixel component values. 13357 13358The exact component associated to each of the @var{c*} options depends on the 13359format in inputs. 13360 13361The expressions can contain the following constants: 13362 13363@table @option 13364@item w 13365@item h 13366The input width and height. 13367 13368@item x 13369The first input value for the pixel component. 13370 13371@item y 13372The second input value for the pixel component. 13373 13374@item bdx 13375The first input video bit depth. 13376 13377@item bdy 13378The second input video bit depth. 13379@end table 13380 13381All expressions default to "x". 13382 13383@subsection Examples 13384 13385@itemize 13386@item 13387Highlight differences between two RGB video streams: 13388@example 13389lut2='ifnot(x-y,0,pow(2,bdx)-1):ifnot(x-y,0,pow(2,bdx)-1):ifnot(x-y,0,pow(2,bdx)-1)' 13390@end example 13391 13392@item 13393Highlight differences between two YUV video streams: 13394@example 13395lut2='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)' 13396@end example 13397 13398@item 13399Show max difference between two video streams: 13400@example 13401lut2='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)))' 13402@end example 13403@end itemize 13404 13405@section maskedclamp 13406 13407Clamp the first input stream with the second input and third input stream. 13408 13409Returns the value of first stream to be between second input 13410stream - @code{undershoot} and third input stream + @code{overshoot}. 13411 13412This filter accepts the following options: 13413@table @option 13414@item undershoot 13415Default value is @code{0}. 13416 13417@item overshoot 13418Default value is @code{0}. 13419 13420@item planes 13421Set which planes will be processed as bitmap, unprocessed planes will be 13422copied from first stream. 13423By default value 0xf, all planes will be processed. 13424@end table 13425 13426@section maskedmax 13427 13428Merge the second and third input stream into output stream using absolute differences 13429between second input stream and first input stream and absolute difference between 13430third input stream and first input stream. The picked value will be from second input 13431stream if second absolute difference is greater than first one or from third input stream 13432otherwise. 13433 13434This filter accepts the following options: 13435@table @option 13436@item planes 13437Set which planes will be processed as bitmap, unprocessed planes will be 13438copied from first stream. 13439By default value 0xf, all planes will be processed. 13440@end table 13441 13442@section maskedmerge 13443 13444Merge the first input stream with the second input stream using per pixel 13445weights in the third input stream. 13446 13447A value of 0 in the third stream pixel component means that pixel component 13448from first stream is returned unchanged, while maximum value (eg. 255 for 134498-bit videos) means that pixel component from second stream is returned 13450unchanged. Intermediate values define the amount of merging between both 13451input stream's pixel components. 13452 13453This filter accepts the following options: 13454@table @option 13455@item planes 13456Set which planes will be processed as bitmap, unprocessed planes will be 13457copied from first stream. 13458By default value 0xf, all planes will be processed. 13459@end table 13460 13461@section maskedmin 13462 13463Merge the second and third input stream into output stream using absolute differences 13464between second input stream and first input stream and absolute difference between 13465third input stream and first input stream. The picked value will be from second input 13466stream if second absolute difference is less than first one or from third input stream 13467otherwise. 13468 13469This filter accepts the following options: 13470@table @option 13471@item planes 13472Set which planes will be processed as bitmap, unprocessed planes will be 13473copied from first stream. 13474By default value 0xf, all planes will be processed. 13475@end table 13476 13477@section maskedthreshold 13478Pick pixels comparing absolute difference of two video streams with fixed 13479threshold. 13480 13481If absolute difference between pixel component of first and second video 13482stream is equal or lower than user supplied threshold than pixel component 13483from first video stream is picked, otherwise pixel component from second 13484video stream is picked. 13485 13486This filter accepts the following options: 13487@table @option 13488@item threshold 13489Set threshold used when picking pixels from absolute difference from two input 13490video streams. 13491 13492@item planes 13493Set which planes will be processed as bitmap, unprocessed planes will be 13494copied from second stream. 13495By default value 0xf, all planes will be processed. 13496@end table 13497 13498@section maskfun 13499Create mask from input video. 13500 13501For example it is useful to create motion masks after @code{tblend} filter. 13502 13503This filter accepts the following options: 13504 13505@table @option 13506@item low 13507Set low threshold. Any pixel component lower or exact than this value will be set to 0. 13508 13509@item high 13510Set high threshold. Any pixel component higher than this value will be set to max value 13511allowed for current pixel format. 13512 13513@item planes 13514Set planes to filter, by default all available planes are filtered. 13515 13516@item fill 13517Fill all frame pixels with this value. 13518 13519@item sum 13520Set max average pixel value for frame. If sum of all pixel components is higher that this 13521average, output frame will be completely filled with value set by @var{fill} option. 13522Typically useful for scene changes when used in combination with @code{tblend} filter. 13523@end table 13524 13525@section mcdeint 13526 13527Apply motion-compensation deinterlacing. 13528 13529It needs one field per frame as input and must thus be used together 13530with yadif=1/3 or equivalent. 13531 13532This filter accepts the following options: 13533@table @option 13534@item mode 13535Set the deinterlacing mode. 13536 13537It accepts one of the following values: 13538@table @samp 13539@item fast 13540@item medium 13541@item slow 13542use iterative motion estimation 13543@item extra_slow 13544like @samp{slow}, but use multiple reference frames. 13545@end table 13546Default value is @samp{fast}. 13547 13548@item parity 13549Set the picture field parity assumed for the input video. It must be 13550one of the following values: 13551 13552@table @samp 13553@item 0, tff 13554assume top field first 13555@item 1, bff 13556assume bottom field first 13557@end table 13558 13559Default value is @samp{bff}. 13560 13561@item qp 13562Set per-block quantization parameter (QP) used by the internal 13563encoder. 13564 13565Higher values should result in a smoother motion vector field but less 13566optimal individual vectors. Default value is 1. 13567@end table 13568 13569@section median 13570 13571Pick median pixel from certain rectangle defined by radius. 13572 13573This filter accepts the following options: 13574 13575@table @option 13576@item radius 13577Set horizontal radius size. Default value is @code{1}. 13578Allowed range is integer from 1 to 127. 13579 13580@item planes 13581Set which planes to process. Default is @code{15}, which is all available planes. 13582 13583@item radiusV 13584Set vertical radius size. Default value is @code{0}. 13585Allowed range is integer from 0 to 127. 13586If it is 0, value will be picked from horizontal @code{radius} option. 13587 13588@item percentile 13589Set median percentile. Default value is @code{0.5}. 13590Default value of @code{0.5} will pick always median values, while @code{0} will pick 13591minimum values, and @code{1} maximum values. 13592@end table 13593 13594@subsection Commands 13595This filter supports same @ref{commands} as options. 13596The command accepts the same syntax of the corresponding option. 13597 13598If the specified expression is not valid, it is kept at its current 13599value. 13600 13601@section mergeplanes 13602 13603Merge color channel components from several video streams. 13604 13605The filter accepts up to 4 input streams, and merge selected input 13606planes to the output video. 13607 13608This filter accepts the following options: 13609@table @option 13610@item mapping 13611Set input to output plane mapping. Default is @code{0}. 13612 13613The mappings is specified as a bitmap. It should be specified as a 13614hexadecimal number in the form 0xAa[Bb[Cc[Dd]]]. 'Aa' describes the 13615mapping for the first plane of the output stream. 'A' sets the number of 13616the input stream to use (from 0 to 3), and 'a' the plane number of the 13617corresponding input to use (from 0 to 3). The rest of the mappings is 13618similar, 'Bb' describes the mapping for the output stream second 13619plane, 'Cc' describes the mapping for the output stream third plane and 13620'Dd' describes the mapping for the output stream fourth plane. 13621 13622@item format 13623Set output pixel format. Default is @code{yuva444p}. 13624@end table 13625 13626@subsection Examples 13627 13628@itemize 13629@item 13630Merge three gray video streams of same width and height into single video stream: 13631@example 13632[a0][a1][a2]mergeplanes=0x001020:yuv444p 13633@end example 13634 13635@item 13636Merge 1st yuv444p stream and 2nd gray video stream into yuva444p video stream: 13637@example 13638[a0][a1]mergeplanes=0x00010210:yuva444p 13639@end example 13640 13641@item 13642Swap Y and A plane in yuva444p stream: 13643@example 13644format=yuva444p,mergeplanes=0x03010200:yuva444p 13645@end example 13646 13647@item 13648Swap U and V plane in yuv420p stream: 13649@example 13650format=yuv420p,mergeplanes=0x000201:yuv420p 13651@end example 13652 13653@item 13654Cast a rgb24 clip to yuv444p: 13655@example 13656format=rgb24,mergeplanes=0x000102:yuv444p 13657@end example 13658@end itemize 13659 13660@section mestimate 13661 13662Estimate and export motion vectors using block matching algorithms. 13663Motion vectors are stored in frame side data to be used by other filters. 13664 13665This filter accepts the following options: 13666@table @option 13667@item method 13668Specify the motion estimation method. Accepts one of the following values: 13669 13670@table @samp 13671@item esa 13672Exhaustive search algorithm. 13673@item tss 13674Three step search algorithm. 13675@item tdls 13676Two dimensional logarithmic search algorithm. 13677@item ntss 13678New three step search algorithm. 13679@item fss 13680Four step search algorithm. 13681@item ds 13682Diamond search algorithm. 13683@item hexbs 13684Hexagon-based search algorithm. 13685@item epzs 13686Enhanced predictive zonal search algorithm. 13687@item umh 13688Uneven multi-hexagon search algorithm. 13689@end table 13690Default value is @samp{esa}. 13691 13692@item mb_size 13693Macroblock size. Default @code{16}. 13694 13695@item search_param 13696Search parameter. Default @code{7}. 13697@end table 13698 13699@section midequalizer 13700 13701Apply Midway Image Equalization effect using two video streams. 13702 13703Midway Image Equalization adjusts a pair of images to have the same 13704histogram, while maintaining their dynamics as much as possible. It's 13705useful for e.g. matching exposures from a pair of stereo cameras. 13706 13707This filter has two inputs and one output, which must be of same pixel format, but 13708may be of different sizes. The output of filter is first input adjusted with 13709midway histogram of both inputs. 13710 13711This filter accepts the following option: 13712 13713@table @option 13714@item planes 13715Set which planes to process. Default is @code{15}, which is all available planes. 13716@end table 13717 13718@section minterpolate 13719 13720Convert the video to specified frame rate using motion interpolation. 13721 13722This filter accepts the following options: 13723@table @option 13724@item fps 13725Specify 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}. 13726 13727@item mi_mode 13728Motion interpolation mode. Following values are accepted: 13729@table @samp 13730@item dup 13731Duplicate previous or next frame for interpolating new ones. 13732@item blend 13733Blend source frames. Interpolated frame is mean of previous and next frames. 13734@item mci 13735Motion compensated interpolation. Following options are effective when this mode is selected: 13736 13737@table @samp 13738@item mc_mode 13739Motion compensation mode. Following values are accepted: 13740@table @samp 13741@item obmc 13742Overlapped block motion compensation. 13743@item aobmc 13744Adaptive overlapped block motion compensation. Window weighting coefficients are controlled adaptively according to the reliabilities of the neighboring motion vectors to reduce oversmoothing. 13745@end table 13746Default mode is @samp{obmc}. 13747 13748@item me_mode 13749Motion estimation mode. Following values are accepted: 13750@table @samp 13751@item bidir 13752Bidirectional motion estimation. Motion vectors are estimated for each source frame in both forward and backward directions. 13753@item bilat 13754Bilateral motion estimation. Motion vectors are estimated directly for interpolated frame. 13755@end table 13756Default mode is @samp{bilat}. 13757 13758@item me 13759The algorithm to be used for motion estimation. Following values are accepted: 13760@table @samp 13761@item esa 13762Exhaustive search algorithm. 13763@item tss 13764Three step search algorithm. 13765@item tdls 13766Two dimensional logarithmic search algorithm. 13767@item ntss 13768New three step search algorithm. 13769@item fss 13770Four step search algorithm. 13771@item ds 13772Diamond search algorithm. 13773@item hexbs 13774Hexagon-based search algorithm. 13775@item epzs 13776Enhanced predictive zonal search algorithm. 13777@item umh 13778Uneven multi-hexagon search algorithm. 13779@end table 13780Default algorithm is @samp{epzs}. 13781 13782@item mb_size 13783Macroblock size. Default @code{16}. 13784 13785@item search_param 13786Motion estimation search parameter. Default @code{32}. 13787 13788@item vsbmc 13789Enable 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). 13790@end table 13791@end table 13792 13793@item scd 13794Scene 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: 13795@table @samp 13796@item none 13797Disable scene change detection. 13798@item fdiff 13799Frame difference. Corresponding pixel values are compared and if it satisfies @var{scd_threshold} scene change is detected. 13800@end table 13801Default method is @samp{fdiff}. 13802 13803@item scd_threshold 13804Scene change detection threshold. Default is @code{10.}. 13805@end table 13806 13807@section mix 13808 13809Mix several video input streams into one video stream. 13810 13811A description of the accepted options follows. 13812 13813@table @option 13814@item nb_inputs 13815The number of inputs. If unspecified, it defaults to 2. 13816 13817@item weights 13818Specify weight of each input video stream as sequence. 13819Each weight is separated by space. If number of weights 13820is smaller than number of @var{frames} last specified 13821weight will be used for all remaining unset weights. 13822 13823@item scale 13824Specify scale, if it is set it will be multiplied with sum 13825of each weight multiplied with pixel values to give final destination 13826pixel value. By default @var{scale} is auto scaled to sum of weights. 13827 13828@item duration 13829Specify how end of stream is determined. 13830@table @samp 13831@item longest 13832The duration of the longest input. (default) 13833 13834@item shortest 13835The duration of the shortest input. 13836 13837@item first 13838The duration of the first input. 13839@end table 13840@end table 13841 13842@section mpdecimate 13843 13844Drop frames that do not differ greatly from the previous frame in 13845order to reduce frame rate. 13846 13847The main use of this filter is for very-low-bitrate encoding 13848(e.g. streaming over dialup modem), but it could in theory be used for 13849fixing movies that were inverse-telecined incorrectly. 13850 13851A description of the accepted options follows. 13852 13853@table @option 13854@item max 13855Set the maximum number of consecutive frames which can be dropped (if 13856positive), or the minimum interval between dropped frames (if 13857negative). If the value is 0, the frame is dropped disregarding the 13858number of previous sequentially dropped frames. 13859 13860Default value is 0. 13861 13862@item hi 13863@item lo 13864@item frac 13865Set the dropping threshold values. 13866 13867Values for @option{hi} and @option{lo} are for 8x8 pixel blocks and 13868represent actual pixel value differences, so a threshold of 64 13869corresponds to 1 unit of difference for each pixel, or the same spread 13870out differently over the block. 13871 13872A frame is a candidate for dropping if no 8x8 blocks differ by more 13873than a threshold of @option{hi}, and if no more than @option{frac} blocks (1 13874meaning the whole image) differ by more than a threshold of @option{lo}. 13875 13876Default value for @option{hi} is 64*12, default value for @option{lo} is 1387764*5, and default value for @option{frac} is 0.33. 13878@end table 13879 13880 13881@section negate 13882 13883Negate (invert) the input video. 13884 13885It accepts the following option: 13886 13887@table @option 13888 13889@item negate_alpha 13890With value 1, it negates the alpha component, if present. Default value is 0. 13891@end table 13892 13893@anchor{nlmeans} 13894@section nlmeans 13895 13896Denoise frames using Non-Local Means algorithm. 13897 13898Each pixel is adjusted by looking for other pixels with similar contexts. This 13899context similarity is defined by comparing their surrounding patches of size 13900@option{p}x@option{p}. Patches are searched in an area of @option{r}x@option{r} 13901around the pixel. 13902 13903Note that the research area defines centers for patches, which means some 13904patches will be made of pixels outside that research area. 13905 13906The filter accepts the following options. 13907 13908@table @option 13909@item s 13910Set denoising strength. Default is 1.0. Must be in range [1.0, 30.0]. 13911 13912@item p 13913Set patch size. Default is 7. Must be odd number in range [0, 99]. 13914 13915@item pc 13916Same as @option{p} but for chroma planes. 13917 13918The default value is @var{0} and means automatic. 13919 13920@item r 13921Set research size. Default is 15. Must be odd number in range [0, 99]. 13922 13923@item rc 13924Same as @option{r} but for chroma planes. 13925 13926The default value is @var{0} and means automatic. 13927@end table 13928 13929@section nnedi 13930 13931Deinterlace video using neural network edge directed interpolation. 13932 13933This filter accepts the following options: 13934 13935@table @option 13936@item weights 13937Mandatory option, without binary file filter can not work. 13938Currently file can be found here: 13939https://github.com/dubhater/vapoursynth-nnedi3/blob/master/src/nnedi3_weights.bin 13940 13941@item deint 13942Set which frames to deinterlace, by default it is @code{all}. 13943Can be @code{all} or @code{interlaced}. 13944 13945@item field 13946Set mode of operation. 13947 13948Can be one of the following: 13949 13950@table @samp 13951@item af 13952Use frame flags, both fields. 13953@item a 13954Use frame flags, single field. 13955@item t 13956Use top field only. 13957@item b 13958Use bottom field only. 13959@item tf 13960Use both fields, top first. 13961@item bf 13962Use both fields, bottom first. 13963@end table 13964 13965@item planes 13966Set which planes to process, by default filter process all frames. 13967 13968@item nsize 13969Set size of local neighborhood around each pixel, used by the predictor neural 13970network. 13971 13972Can be one of the following: 13973 13974@table @samp 13975@item s8x6 13976@item s16x6 13977@item s32x6 13978@item s48x6 13979@item s8x4 13980@item s16x4 13981@item s32x4 13982@end table 13983 13984@item nns 13985Set the number of neurons in predictor neural network. 13986Can be one of the following: 13987 13988@table @samp 13989@item n16 13990@item n32 13991@item n64 13992@item n128 13993@item n256 13994@end table 13995 13996@item qual 13997Controls the number of different neural network predictions that are blended 13998together to compute the final output value. Can be @code{fast}, default or 13999@code{slow}. 14000 14001@item etype 14002Set which set of weights to use in the predictor. 14003Can be one of the following: 14004 14005@table @samp 14006@item a 14007weights trained to minimize absolute error 14008@item s 14009weights trained to minimize squared error 14010@end table 14011 14012@item pscrn 14013Controls whether or not the prescreener neural network is used to decide 14014which pixels should be processed by the predictor neural network and which 14015can be handled by simple cubic interpolation. 14016The prescreener is trained to know whether cubic interpolation will be 14017sufficient for a pixel or whether it should be predicted by the predictor nn. 14018The computational complexity of the prescreener nn is much less than that of 14019the predictor nn. Since most pixels can be handled by cubic interpolation, 14020using the prescreener generally results in much faster processing. 14021The prescreener is pretty accurate, so the difference between using it and not 14022using it is almost always unnoticeable. 14023 14024Can be one of the following: 14025 14026@table @samp 14027@item none 14028@item original 14029@item new 14030@end table 14031 14032Default is @code{new}. 14033 14034@item fapprox 14035Set various debugging flags. 14036@end table 14037 14038@section noformat 14039 14040Force libavfilter not to use any of the specified pixel formats for the 14041input to the next filter. 14042 14043It accepts the following parameters: 14044@table @option 14045 14046@item pix_fmts 14047A '|'-separated list of pixel format names, such as 14048pix_fmts=yuv420p|monow|rgb24". 14049 14050@end table 14051 14052@subsection Examples 14053 14054@itemize 14055@item 14056Force libavfilter to use a format different from @var{yuv420p} for the 14057input to the vflip filter: 14058@example 14059noformat=pix_fmts=yuv420p,vflip 14060@end example 14061 14062@item 14063Convert the input video to any of the formats not contained in the list: 14064@example 14065noformat=yuv420p|yuv444p|yuv410p 14066@end example 14067@end itemize 14068 14069@section noise 14070 14071Add noise on video input frame. 14072 14073The filter accepts the following options: 14074 14075@table @option 14076@item all_seed 14077@item c0_seed 14078@item c1_seed 14079@item c2_seed 14080@item c3_seed 14081Set noise seed for specific pixel component or all pixel components in case 14082of @var{all_seed}. Default value is @code{123457}. 14083 14084@item all_strength, alls 14085@item c0_strength, c0s 14086@item c1_strength, c1s 14087@item c2_strength, c2s 14088@item c3_strength, c3s 14089Set noise strength for specific pixel component or all pixel components in case 14090@var{all_strength}. Default value is @code{0}. Allowed range is [0, 100]. 14091 14092@item all_flags, allf 14093@item c0_flags, c0f 14094@item c1_flags, c1f 14095@item c2_flags, c2f 14096@item c3_flags, c3f 14097Set pixel component flags or set flags for all components if @var{all_flags}. 14098Available values for component flags are: 14099@table @samp 14100@item a 14101averaged temporal noise (smoother) 14102@item p 14103mix random noise with a (semi)regular pattern 14104@item t 14105temporal noise (noise pattern changes between frames) 14106@item u 14107uniform noise (gaussian otherwise) 14108@end table 14109@end table 14110 14111@subsection Examples 14112 14113Add temporal and uniform noise to input video: 14114@example 14115noise=alls=20:allf=t+u 14116@end example 14117 14118@section normalize 14119 14120Normalize RGB video (aka histogram stretching, contrast stretching). 14121See: https://en.wikipedia.org/wiki/Normalization_(image_processing) 14122 14123For each channel of each frame, the filter computes the input range and maps 14124it linearly to the user-specified output range. The output range defaults 14125to the full dynamic range from pure black to pure white. 14126 14127Temporal smoothing can be used on the input range to reduce flickering (rapid 14128changes in brightness) caused when small dark or bright objects enter or leave 14129the scene. This is similar to the auto-exposure (automatic gain control) on a 14130video camera, and, like a video camera, it may cause a period of over- or 14131under-exposure of the video. 14132 14133The R,G,B channels can be normalized independently, which may cause some 14134color shifting, or linked together as a single channel, which prevents 14135color shifting. Linked normalization preserves hue. Independent normalization 14136does not, so it can be used to remove some color casts. Independent and linked 14137normalization can be combined in any ratio. 14138 14139The normalize filter accepts the following options: 14140 14141@table @option 14142@item blackpt 14143@item whitept 14144Colors which define the output range. The minimum input value is mapped to 14145the @var{blackpt}. The maximum input value is mapped to the @var{whitept}. 14146The defaults are black and white respectively. Specifying white for 14147@var{blackpt} and black for @var{whitept} will give color-inverted, 14148normalized video. Shades of grey can be used to reduce the dynamic range 14149(contrast). Specifying saturated colors here can create some interesting 14150effects. 14151 14152@item smoothing 14153The number of previous frames to use for temporal smoothing. The input range 14154of each channel is smoothed using a rolling average over the current frame 14155and the @var{smoothing} previous frames. The default is 0 (no temporal 14156smoothing). 14157 14158@item independence 14159Controls the ratio of independent (color shifting) channel normalization to 14160linked (color preserving) normalization. 0.0 is fully linked, 1.0 is fully 14161independent. Defaults to 1.0 (fully independent). 14162 14163@item strength 14164Overall strength of the filter. 1.0 is full strength. 0.0 is a rather 14165expensive no-op. Defaults to 1.0 (full strength). 14166 14167@end table 14168 14169@subsection Commands 14170This filter supports same @ref{commands} as options, excluding @var{smoothing} option. 14171The command accepts the same syntax of the corresponding option. 14172 14173If the specified expression is not valid, it is kept at its current 14174value. 14175 14176@subsection Examples 14177 14178Stretch video contrast to use the full dynamic range, with no temporal 14179smoothing; may flicker depending on the source content: 14180@example 14181normalize=blackpt=black:whitept=white:smoothing=0 14182@end example 14183 14184As above, but with 50 frames of temporal smoothing; flicker should be 14185reduced, depending on the source content: 14186@example 14187normalize=blackpt=black:whitept=white:smoothing=50 14188@end example 14189 14190As above, but with hue-preserving linked channel normalization: 14191@example 14192normalize=blackpt=black:whitept=white:smoothing=50:independence=0 14193@end example 14194 14195As above, but with half strength: 14196@example 14197normalize=blackpt=black:whitept=white:smoothing=50:independence=0:strength=0.5 14198@end example 14199 14200Map the darkest input color to red, the brightest input color to cyan: 14201@example 14202normalize=blackpt=red:whitept=cyan 14203@end example 14204 14205@section null 14206 14207Pass the video source unchanged to the output. 14208 14209@section ocr 14210Optical Character Recognition 14211 14212This filter uses Tesseract for optical character recognition. To enable 14213compilation of this filter, you need to configure FFmpeg with 14214@code{--enable-libtesseract}. 14215 14216It accepts the following options: 14217 14218@table @option 14219@item datapath 14220Set datapath to tesseract data. Default is to use whatever was 14221set at installation. 14222 14223@item language 14224Set language, default is "eng". 14225 14226@item whitelist 14227Set character whitelist. 14228 14229@item blacklist 14230Set character blacklist. 14231@end table 14232 14233The filter exports recognized text as the frame metadata @code{lavfi.ocr.text}. 14234The filter exports confidence of recognized words as the frame metadata @code{lavfi.ocr.confidence}. 14235 14236@section ocv 14237 14238Apply a video transform using libopencv. 14239 14240To enable this filter, install the libopencv library and headers and 14241configure FFmpeg with @code{--enable-libopencv}. 14242 14243It accepts the following parameters: 14244 14245@table @option 14246 14247@item filter_name 14248The name of the libopencv filter to apply. 14249 14250@item filter_params 14251The parameters to pass to the libopencv filter. If not specified, the default 14252values are assumed. 14253 14254@end table 14255 14256Refer to the official libopencv documentation for more precise 14257information: 14258@url{http://docs.opencv.org/master/modules/imgproc/doc/filtering.html} 14259 14260Several libopencv filters are supported; see the following subsections. 14261 14262@anchor{dilate} 14263@subsection dilate 14264 14265Dilate an image by using a specific structuring element. 14266It corresponds to the libopencv function @code{cvDilate}. 14267 14268It accepts the parameters: @var{struct_el}|@var{nb_iterations}. 14269 14270@var{struct_el} represents a structuring element, and has the syntax: 14271@var{cols}x@var{rows}+@var{anchor_x}x@var{anchor_y}/@var{shape} 14272 14273@var{cols} and @var{rows} represent the number of columns and rows of 14274the structuring element, @var{anchor_x} and @var{anchor_y} the anchor 14275point, and @var{shape} the shape for the structuring element. @var{shape} 14276must be "rect", "cross", "ellipse", or "custom". 14277 14278If the value for @var{shape} is "custom", it must be followed by a 14279string of the form "=@var{filename}". The file with name 14280@var{filename} is assumed to represent a binary image, with each 14281printable character corresponding to a bright pixel. When a custom 14282@var{shape} is used, @var{cols} and @var{rows} are ignored, the number 14283or columns and rows of the read file are assumed instead. 14284 14285The default value for @var{struct_el} is "3x3+0x0/rect". 14286 14287@var{nb_iterations} specifies the number of times the transform is 14288applied to the image, and defaults to 1. 14289 14290Some examples: 14291@example 14292# Use the default values 14293ocv=dilate 14294 14295# Dilate using a structuring element with a 5x5 cross, iterating two times 14296ocv=filter_name=dilate:filter_params=5x5+2x2/cross|2 14297 14298# Read the shape from the file diamond.shape, iterating two times. 14299# The file diamond.shape may contain a pattern of characters like this 14300# * 14301# *** 14302# ***** 14303# *** 14304# * 14305# The specified columns and rows are ignored 14306# but the anchor point coordinates are not 14307ocv=dilate:0x0+2x2/custom=diamond.shape|2 14308@end example 14309 14310@subsection erode 14311 14312Erode an image by using a specific structuring element. 14313It corresponds to the libopencv function @code{cvErode}. 14314 14315It accepts the parameters: @var{struct_el}:@var{nb_iterations}, 14316with the same syntax and semantics as the @ref{dilate} filter. 14317 14318@subsection smooth 14319 14320Smooth the input video. 14321 14322The filter takes the following parameters: 14323@var{type}|@var{param1}|@var{param2}|@var{param3}|@var{param4}. 14324 14325@var{type} is the type of smooth filter to apply, and must be one of 14326the following values: "blur", "blur_no_scale", "median", "gaussian", 14327or "bilateral". The default value is "gaussian". 14328 14329The meaning of @var{param1}, @var{param2}, @var{param3}, and @var{param4} 14330depends on the smooth type. @var{param1} and 14331@var{param2} accept integer positive values or 0. @var{param3} and 14332@var{param4} accept floating point values. 14333 14334The default value for @var{param1} is 3. The default value for the 14335other parameters is 0. 14336 14337These parameters correspond to the parameters assigned to the 14338libopencv function @code{cvSmooth}. 14339 14340@section oscilloscope 14341 143422D Video Oscilloscope. 14343 14344Useful to measure spatial impulse, step responses, chroma delays, etc. 14345 14346It accepts the following parameters: 14347 14348@table @option 14349@item x 14350Set scope center x position. 14351 14352@item y 14353Set scope center y position. 14354 14355@item s 14356Set scope size, relative to frame diagonal. 14357 14358@item t 14359Set scope tilt/rotation. 14360 14361@item o 14362Set trace opacity. 14363 14364@item tx 14365Set trace center x position. 14366 14367@item ty 14368Set trace center y position. 14369 14370@item tw 14371Set trace width, relative to width of frame. 14372 14373@item th 14374Set trace height, relative to height of frame. 14375 14376@item c 14377Set which components to trace. By default it traces first three components. 14378 14379@item g 14380Draw trace grid. By default is enabled. 14381 14382@item st 14383Draw some statistics. By default is enabled. 14384 14385@item sc 14386Draw scope. By default is enabled. 14387@end table 14388 14389@subsection Commands 14390This filter supports same @ref{commands} as options. 14391The command accepts the same syntax of the corresponding option. 14392 14393If the specified expression is not valid, it is kept at its current 14394value. 14395 14396@subsection Examples 14397 14398@itemize 14399@item 14400Inspect full first row of video frame. 14401@example 14402oscilloscope=x=0.5:y=0:s=1 14403@end example 14404 14405@item 14406Inspect full last row of video frame. 14407@example 14408oscilloscope=x=0.5:y=1:s=1 14409@end example 14410 14411@item 14412Inspect full 5th line of video frame of height 1080. 14413@example 14414oscilloscope=x=0.5:y=5/1080:s=1 14415@end example 14416 14417@item 14418Inspect full last column of video frame. 14419@example 14420oscilloscope=x=1:y=0.5:s=1:t=1 14421@end example 14422 14423@end itemize 14424 14425@anchor{overlay} 14426@section overlay 14427 14428Overlay one video on top of another. 14429 14430It takes two inputs and has one output. The first input is the "main" 14431video on which the second input is overlaid. 14432 14433It accepts the following parameters: 14434 14435A description of the accepted options follows. 14436 14437@table @option 14438@item x 14439@item y 14440Set the expression for the x and y coordinates of the overlaid video 14441on the main video. Default value is "0" for both expressions. In case 14442the expression is invalid, it is set to a huge value (meaning that the 14443overlay will not be displayed within the output visible area). 14444 14445@item eof_action 14446See @ref{framesync}. 14447 14448@item eval 14449Set when the expressions for @option{x}, and @option{y} are evaluated. 14450 14451It accepts the following values: 14452@table @samp 14453@item init 14454only evaluate expressions once during the filter initialization or 14455when a command is processed 14456 14457@item frame 14458evaluate expressions for each incoming frame 14459@end table 14460 14461Default value is @samp{frame}. 14462 14463@item shortest 14464See @ref{framesync}. 14465 14466@item format 14467Set the format for the output video. 14468 14469It accepts the following values: 14470@table @samp 14471@item yuv420 14472force YUV420 output 14473 14474@item yuv420p10 14475force YUV420p10 output 14476 14477@item yuv422 14478force YUV422 output 14479 14480@item yuv422p10 14481force YUV422p10 output 14482 14483@item yuv444 14484force YUV444 output 14485 14486@item rgb 14487force packed RGB output 14488 14489@item gbrp 14490force planar RGB output 14491 14492@item auto 14493automatically pick format 14494@end table 14495 14496Default value is @samp{yuv420}. 14497 14498@item repeatlast 14499See @ref{framesync}. 14500 14501@item alpha 14502Set format of alpha of the overlaid video, it can be @var{straight} or 14503@var{premultiplied}. Default is @var{straight}. 14504@end table 14505 14506The @option{x}, and @option{y} expressions can contain the following 14507parameters. 14508 14509@table @option 14510@item main_w, W 14511@item main_h, H 14512The main input width and height. 14513 14514@item overlay_w, w 14515@item overlay_h, h 14516The overlay input width and height. 14517 14518@item x 14519@item y 14520The computed values for @var{x} and @var{y}. They are evaluated for 14521each new frame. 14522 14523@item hsub 14524@item vsub 14525horizontal and vertical chroma subsample values of the output 14526format. For example for the pixel format "yuv422p" @var{hsub} is 2 and 14527@var{vsub} is 1. 14528 14529@item n 14530the number of input frame, starting from 0 14531 14532@item pos 14533the position in the file of the input frame, NAN if unknown 14534 14535@item t 14536The timestamp, expressed in seconds. It's NAN if the input timestamp is unknown. 14537 14538@end table 14539 14540This filter also supports the @ref{framesync} options. 14541 14542Note that the @var{n}, @var{pos}, @var{t} variables are available only 14543when evaluation is done @emph{per frame}, and will evaluate to NAN 14544when @option{eval} is set to @samp{init}. 14545 14546Be aware that frames are taken from each input video in timestamp 14547order, hence, if their initial timestamps differ, it is a good idea 14548to pass the two inputs through a @var{setpts=PTS-STARTPTS} filter to 14549have them begin in the same zero timestamp, as the example for 14550the @var{movie} filter does. 14551 14552You can chain together more overlays but you should test the 14553efficiency of such approach. 14554 14555@subsection Commands 14556 14557This filter supports the following commands: 14558@table @option 14559@item x 14560@item y 14561Modify the x and y of the overlay input. 14562The command accepts the same syntax of the corresponding option. 14563 14564If the specified expression is not valid, it is kept at its current 14565value. 14566@end table 14567 14568@subsection Examples 14569 14570@itemize 14571@item 14572Draw the overlay at 10 pixels from the bottom right corner of the main 14573video: 14574@example 14575overlay=main_w-overlay_w-10:main_h-overlay_h-10 14576@end example 14577 14578Using named options the example above becomes: 14579@example 14580overlay=x=main_w-overlay_w-10:y=main_h-overlay_h-10 14581@end example 14582 14583@item 14584Insert a transparent PNG logo in the bottom left corner of the input, 14585using the @command{ffmpeg} tool with the @code{-filter_complex} option: 14586@example 14587ffmpeg -i input -i logo -filter_complex 'overlay=10:main_h-overlay_h-10' output 14588@end example 14589 14590@item 14591Insert 2 different transparent PNG logos (second logo on bottom 14592right corner) using the @command{ffmpeg} tool: 14593@example 14594ffmpeg -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 14595@end example 14596 14597@item 14598Add a transparent color layer on top of the main video; @code{WxH} 14599must specify the size of the main input to the overlay filter: 14600@example 14601color=color=red@@.3:size=WxH [over]; [in][over] overlay [out] 14602@end example 14603 14604@item 14605Play an original video and a filtered version (here with the deshake 14606filter) side by side using the @command{ffplay} tool: 14607@example 14608ffplay input.avi -vf 'split[a][b]; [a]pad=iw*2:ih[src]; [b]deshake[filt]; [src][filt]overlay=w' 14609@end example 14610 14611The above command is the same as: 14612@example 14613ffplay input.avi -vf 'split[b], pad=iw*2[src], [b]deshake, [src]overlay=w' 14614@end example 14615 14616@item 14617Make a sliding overlay appearing from the left to the right top part of the 14618screen starting since time 2: 14619@example 14620overlay=x='if(gte(t,2), -w+(t-2)*20, NAN)':y=0 14621@end example 14622 14623@item 14624Compose output by putting two input videos side to side: 14625@example 14626ffmpeg -i left.avi -i right.avi -filter_complex " 14627nullsrc=size=200x100 [background]; 14628[0:v] setpts=PTS-STARTPTS, scale=100x100 [left]; 14629[1:v] setpts=PTS-STARTPTS, scale=100x100 [right]; 14630[background][left] overlay=shortest=1 [background+left]; 14631[background+left][right] overlay=shortest=1:x=100 [left+right] 14632" 14633@end example 14634 14635@item 14636Mask 10-20 seconds of a video by applying the delogo filter to a section 14637@example 14638ffmpeg -i test.avi -codec:v:0 wmv2 -ar 11025 -b:v 9000k 14639-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]' 14640masked.avi 14641@end example 14642 14643@item 14644Chain several overlays in cascade: 14645@example 14646nullsrc=s=200x200 [bg]; 14647testsrc=s=100x100, split=4 [in0][in1][in2][in3]; 14648[in0] lutrgb=r=0, [bg] overlay=0:0 [mid0]; 14649[in1] lutrgb=g=0, [mid0] overlay=100:0 [mid1]; 14650[in2] lutrgb=b=0, [mid1] overlay=0:100 [mid2]; 14651[in3] null, [mid2] overlay=100:100 [out0] 14652@end example 14653 14654@end itemize 14655 14656@anchor{overlay_cuda} 14657@section overlay_cuda 14658 14659Overlay one video on top of another. 14660 14661This is the CUDA cariant of the @ref{overlay} filter. 14662It only accepts CUDA frames. The underlying input pixel formats have to match. 14663 14664It takes two inputs and has one output. The first input is the "main" 14665video on which the second input is overlaid. 14666 14667It accepts the following parameters: 14668 14669@table @option 14670@item x 14671@item y 14672Set the x and y coordinates of the overlaid video on the main video. 14673Default value is "0" for both expressions. 14674 14675@item eof_action 14676See @ref{framesync}. 14677 14678@item shortest 14679See @ref{framesync}. 14680 14681@item repeatlast 14682See @ref{framesync}. 14683 14684@end table 14685 14686This filter also supports the @ref{framesync} options. 14687 14688@section owdenoise 14689 14690Apply Overcomplete Wavelet denoiser. 14691 14692The filter accepts the following options: 14693 14694@table @option 14695@item depth 14696Set depth. 14697 14698Larger depth values will denoise lower frequency components more, but 14699slow down filtering. 14700 14701Must be an int in the range 8-16, default is @code{8}. 14702 14703@item luma_strength, ls 14704Set luma strength. 14705 14706Must be a double value in the range 0-1000, default is @code{1.0}. 14707 14708@item chroma_strength, cs 14709Set chroma strength. 14710 14711Must be a double value in the range 0-1000, default is @code{1.0}. 14712@end table 14713 14714@anchor{pad} 14715@section pad 14716 14717Add paddings to the input image, and place the original input at the 14718provided @var{x}, @var{y} coordinates. 14719 14720It accepts the following parameters: 14721 14722@table @option 14723@item width, w 14724@item height, h 14725Specify an expression for the size of the output image with the 14726paddings added. If the value for @var{width} or @var{height} is 0, the 14727corresponding input size is used for the output. 14728 14729The @var{width} expression can reference the value set by the 14730@var{height} expression, and vice versa. 14731 14732The default value of @var{width} and @var{height} is 0. 14733 14734@item x 14735@item y 14736Specify the offsets to place the input image at within the padded area, 14737with respect to the top/left border of the output image. 14738 14739The @var{x} expression can reference the value set by the @var{y} 14740expression, and vice versa. 14741 14742The default value of @var{x} and @var{y} is 0. 14743 14744If @var{x} or @var{y} evaluate to a negative number, they'll be changed 14745so the input image is centered on the padded area. 14746 14747@item color 14748Specify the color of the padded area. For the syntax of this option, 14749check the @ref{color syntax,,"Color" section in the ffmpeg-utils 14750manual,ffmpeg-utils}. 14751 14752The default value of @var{color} is "black". 14753 14754@item eval 14755Specify when to evaluate @var{width}, @var{height}, @var{x} and @var{y} expression. 14756 14757It accepts the following values: 14758 14759@table @samp 14760@item init 14761Only evaluate expressions once during the filter initialization or when 14762a command is processed. 14763 14764@item frame 14765Evaluate expressions for each incoming frame. 14766 14767@end table 14768 14769Default value is @samp{init}. 14770 14771@item aspect 14772Pad to aspect instead to a resolution. 14773 14774@end table 14775 14776The value for the @var{width}, @var{height}, @var{x}, and @var{y} 14777options are expressions containing the following constants: 14778 14779@table @option 14780@item in_w 14781@item in_h 14782The input video width and height. 14783 14784@item iw 14785@item ih 14786These are the same as @var{in_w} and @var{in_h}. 14787 14788@item out_w 14789@item out_h 14790The output width and height (the size of the padded area), as 14791specified by the @var{width} and @var{height} expressions. 14792 14793@item ow 14794@item oh 14795These are the same as @var{out_w} and @var{out_h}. 14796 14797@item x 14798@item y 14799The x and y offsets as specified by the @var{x} and @var{y} 14800expressions, or NAN if not yet specified. 14801 14802@item a 14803same as @var{iw} / @var{ih} 14804 14805@item sar 14806input sample aspect ratio 14807 14808@item dar 14809input display aspect ratio, it is the same as (@var{iw} / @var{ih}) * @var{sar} 14810 14811@item hsub 14812@item vsub 14813The horizontal and vertical chroma subsample values. For example for the 14814pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1. 14815@end table 14816 14817@subsection Examples 14818 14819@itemize 14820@item 14821Add paddings with the color "violet" to the input video. The output video 14822size is 640x480, and the top-left corner of the input video is placed at 14823column 0, row 40 14824@example 14825pad=640:480:0:40:violet 14826@end example 14827 14828The example above is equivalent to the following command: 14829@example 14830pad=width=640:height=480:x=0:y=40:color=violet 14831@end example 14832 14833@item 14834Pad the input to get an output with dimensions increased by 3/2, 14835and put the input video at the center of the padded area: 14836@example 14837pad="3/2*iw:3/2*ih:(ow-iw)/2:(oh-ih)/2" 14838@end example 14839 14840@item 14841Pad the input to get a squared output with size equal to the maximum 14842value between the input width and height, and put the input video at 14843the center of the padded area: 14844@example 14845pad="max(iw\,ih):ow:(ow-iw)/2:(oh-ih)/2" 14846@end example 14847 14848@item 14849Pad the input to get a final w/h ratio of 16:9: 14850@example 14851pad="ih*16/9:ih:(ow-iw)/2:(oh-ih)/2" 14852@end example 14853 14854@item 14855In case of anamorphic video, in order to set the output display aspect 14856correctly, it is necessary to use @var{sar} in the expression, 14857according to the relation: 14858@example 14859(ih * X / ih) * sar = output_dar 14860X = output_dar / sar 14861@end example 14862 14863Thus the previous example needs to be modified to: 14864@example 14865pad="ih*16/9/sar:ih:(ow-iw)/2:(oh-ih)/2" 14866@end example 14867 14868@item 14869Double the output size and put the input video in the bottom-right 14870corner of the output padded area: 14871@example 14872pad="2*iw:2*ih:ow-iw:oh-ih" 14873@end example 14874@end itemize 14875 14876@anchor{palettegen} 14877@section palettegen 14878 14879Generate one palette for a whole video stream. 14880 14881It accepts the following options: 14882 14883@table @option 14884@item max_colors 14885Set the maximum number of colors to quantize in the palette. 14886Note: the palette will still contain 256 colors; the unused palette entries 14887will be black. 14888 14889@item reserve_transparent 14890Create a palette of 255 colors maximum and reserve the last one for 14891transparency. Reserving the transparency color is useful for GIF optimization. 14892If not set, the maximum of colors in the palette will be 256. You probably want 14893to disable this option for a standalone image. 14894Set by default. 14895 14896@item transparency_color 14897Set the color that will be used as background for transparency. 14898 14899@item stats_mode 14900Set statistics mode. 14901 14902It accepts the following values: 14903@table @samp 14904@item full 14905Compute full frame histograms. 14906@item diff 14907Compute histograms only for the part that differs from previous frame. This 14908might be relevant to give more importance to the moving part of your input if 14909the background is static. 14910@item single 14911Compute new histogram for each frame. 14912@end table 14913 14914Default value is @var{full}. 14915@end table 14916 14917The filter also exports the frame metadata @code{lavfi.color_quant_ratio} 14918(@code{nb_color_in / nb_color_out}) which you can use to evaluate the degree of 14919color quantization of the palette. This information is also visible at 14920@var{info} logging level. 14921 14922@subsection Examples 14923 14924@itemize 14925@item 14926Generate a representative palette of a given video using @command{ffmpeg}: 14927@example 14928ffmpeg -i input.mkv -vf palettegen palette.png 14929@end example 14930@end itemize 14931 14932@section paletteuse 14933 14934Use a palette to downsample an input video stream. 14935 14936The filter takes two inputs: one video stream and a palette. The palette must 14937be a 256 pixels image. 14938 14939It accepts the following options: 14940 14941@table @option 14942@item dither 14943Select dithering mode. Available algorithms are: 14944@table @samp 14945@item bayer 14946Ordered 8x8 bayer dithering (deterministic) 14947@item heckbert 14948Dithering as defined by Paul Heckbert in 1982 (simple error diffusion). 14949Note: this dithering is sometimes considered "wrong" and is included as a 14950reference. 14951@item floyd_steinberg 14952Floyd and Steingberg dithering (error diffusion) 14953@item sierra2 14954Frankie Sierra dithering v2 (error diffusion) 14955@item sierra2_4a 14956Frankie Sierra dithering v2 "Lite" (error diffusion) 14957@end table 14958 14959Default is @var{sierra2_4a}. 14960 14961@item bayer_scale 14962When @var{bayer} dithering is selected, this option defines the scale of the 14963pattern (how much the crosshatch pattern is visible). A low value means more 14964visible pattern for less banding, and higher value means less visible pattern 14965at the cost of more banding. 14966 14967The option must be an integer value in the range [0,5]. Default is @var{2}. 14968 14969@item diff_mode 14970If set, define the zone to process 14971 14972@table @samp 14973@item rectangle 14974Only the changing rectangle will be reprocessed. This is similar to GIF 14975cropping/offsetting compression mechanism. This option can be useful for speed 14976if only a part of the image is changing, and has use cases such as limiting the 14977scope of the error diffusal @option{dither} to the rectangle that bounds the 14978moving scene (it leads to more deterministic output if the scene doesn't change 14979much, and as a result less moving noise and better GIF compression). 14980@end table 14981 14982Default is @var{none}. 14983 14984@item new 14985Take new palette for each output frame. 14986 14987@item alpha_threshold 14988Sets the alpha threshold for transparency. Alpha values above this threshold 14989will be treated as completely opaque, and values below this threshold will be 14990treated as completely transparent. 14991 14992The option must be an integer value in the range [0,255]. Default is @var{128}. 14993@end table 14994 14995@subsection Examples 14996 14997@itemize 14998@item 14999Use a palette (generated for example with @ref{palettegen}) to encode a GIF 15000using @command{ffmpeg}: 15001@example 15002ffmpeg -i input.mkv -i palette.png -lavfi paletteuse output.gif 15003@end example 15004@end itemize 15005 15006@section perspective 15007 15008Correct perspective of video not recorded perpendicular to the screen. 15009 15010A description of the accepted parameters follows. 15011 15012@table @option 15013@item x0 15014@item y0 15015@item x1 15016@item y1 15017@item x2 15018@item y2 15019@item x3 15020@item y3 15021Set coordinates expression for top left, top right, bottom left and bottom right corners. 15022Default values are @code{0:0:W:0:0:H:W:H} with which perspective will remain unchanged. 15023If the @code{sense} option is set to @code{source}, then the specified points will be sent 15024to the corners of the destination. If the @code{sense} option is set to @code{destination}, 15025then the corners of the source will be sent to the specified coordinates. 15026 15027The expressions can use the following variables: 15028 15029@table @option 15030@item W 15031@item H 15032the width and height of video frame. 15033@item in 15034Input frame count. 15035@item on 15036Output frame count. 15037@end table 15038 15039@item interpolation 15040Set interpolation for perspective correction. 15041 15042It accepts the following values: 15043@table @samp 15044@item linear 15045@item cubic 15046@end table 15047 15048Default value is @samp{linear}. 15049 15050@item sense 15051Set interpretation of coordinate options. 15052 15053It accepts the following values: 15054@table @samp 15055@item 0, source 15056 15057Send point in the source specified by the given coordinates to 15058the corners of the destination. 15059 15060@item 1, destination 15061 15062Send the corners of the source to the point in the destination specified 15063by the given coordinates. 15064 15065Default value is @samp{source}. 15066@end table 15067 15068@item eval 15069Set when the expressions for coordinates @option{x0,y0,...x3,y3} are evaluated. 15070 15071It accepts the following values: 15072@table @samp 15073@item init 15074only evaluate expressions once during the filter initialization or 15075when a command is processed 15076 15077@item frame 15078evaluate expressions for each incoming frame 15079@end table 15080 15081Default value is @samp{init}. 15082@end table 15083 15084@section phase 15085 15086Delay interlaced video by one field time so that the field order changes. 15087 15088The intended use is to fix PAL movies that have been captured with the 15089opposite field order to the film-to-video transfer. 15090 15091A description of the accepted parameters follows. 15092 15093@table @option 15094@item mode 15095Set phase mode. 15096 15097It accepts the following values: 15098@table @samp 15099@item t 15100Capture field order top-first, transfer bottom-first. 15101Filter will delay the bottom field. 15102 15103@item b 15104Capture field order bottom-first, transfer top-first. 15105Filter will delay the top field. 15106 15107@item p 15108Capture and transfer with the same field order. This mode only exists 15109for the documentation of the other options to refer to, but if you 15110actually select it, the filter will faithfully do nothing. 15111 15112@item a 15113Capture field order determined automatically by field flags, transfer 15114opposite. 15115Filter selects among @samp{t} and @samp{b} modes on a frame by frame 15116basis using field flags. If no field information is available, 15117then this works just like @samp{u}. 15118 15119@item u 15120Capture unknown or varying, transfer opposite. 15121Filter selects among @samp{t} and @samp{b} on a frame by frame basis by 15122analyzing the images and selecting the alternative that produces best 15123match between the fields. 15124 15125@item T 15126Capture top-first, transfer unknown or varying. 15127Filter selects among @samp{t} and @samp{p} using image analysis. 15128 15129@item B 15130Capture bottom-first, transfer unknown or varying. 15131Filter selects among @samp{b} and @samp{p} using image analysis. 15132 15133@item A 15134Capture determined by field flags, transfer unknown or varying. 15135Filter selects among @samp{t}, @samp{b} and @samp{p} using field flags and 15136image analysis. If no field information is available, then this works just 15137like @samp{U}. This is the default mode. 15138 15139@item U 15140Both capture and transfer unknown or varying. 15141Filter selects among @samp{t}, @samp{b} and @samp{p} using image analysis only. 15142@end table 15143@end table 15144 15145@section photosensitivity 15146Reduce various flashes in video, so to help users with epilepsy. 15147 15148It accepts the following options: 15149@table @option 15150@item frames, f 15151Set how many frames to use when filtering. Default is 30. 15152 15153@item threshold, t 15154Set detection threshold factor. Default is 1. 15155Lower is stricter. 15156 15157@item skip 15158Set how many pixels to skip when sampling frames. Default is 1. 15159Allowed range is from 1 to 1024. 15160 15161@item bypass 15162Leave frames unchanged. Default is disabled. 15163@end table 15164 15165@section pixdesctest 15166 15167Pixel format descriptor test filter, mainly useful for internal 15168testing. The output video should be equal to the input video. 15169 15170For example: 15171@example 15172format=monow, pixdesctest 15173@end example 15174 15175can be used to test the monowhite pixel format descriptor definition. 15176 15177@section pixscope 15178 15179Display sample values of color channels. Mainly useful for checking color 15180and levels. Minimum supported resolution is 640x480. 15181 15182The filters accept the following options: 15183 15184@table @option 15185@item x 15186Set scope X position, relative offset on X axis. 15187 15188@item y 15189Set scope Y position, relative offset on Y axis. 15190 15191@item w 15192Set scope width. 15193 15194@item h 15195Set scope height. 15196 15197@item o 15198Set window opacity. This window also holds statistics about pixel area. 15199 15200@item wx 15201Set window X position, relative offset on X axis. 15202 15203@item wy 15204Set window Y position, relative offset on Y axis. 15205@end table 15206 15207@section pp 15208 15209Enable the specified chain of postprocessing subfilters using libpostproc. This 15210library should be automatically selected with a GPL build (@code{--enable-gpl}). 15211Subfilters must be separated by '/' and can be disabled by prepending a '-'. 15212Each subfilter and some options have a short and a long name that can be used 15213interchangeably, i.e. dr/dering are the same. 15214 15215The filters accept the following options: 15216 15217@table @option 15218@item subfilters 15219Set postprocessing subfilters string. 15220@end table 15221 15222All subfilters share common options to determine their scope: 15223 15224@table @option 15225@item a/autoq 15226Honor the quality commands for this subfilter. 15227 15228@item c/chrom 15229Do chrominance filtering, too (default). 15230 15231@item y/nochrom 15232Do luminance filtering only (no chrominance). 15233 15234@item n/noluma 15235Do chrominance filtering only (no luminance). 15236@end table 15237 15238These options can be appended after the subfilter name, separated by a '|'. 15239 15240Available subfilters are: 15241 15242@table @option 15243@item hb/hdeblock[|difference[|flatness]] 15244Horizontal deblocking filter 15245@table @option 15246@item difference 15247Difference factor where higher values mean more deblocking (default: @code{32}). 15248@item flatness 15249Flatness threshold where lower values mean more deblocking (default: @code{39}). 15250@end table 15251 15252@item vb/vdeblock[|difference[|flatness]] 15253Vertical deblocking filter 15254@table @option 15255@item difference 15256Difference factor where higher values mean more deblocking (default: @code{32}). 15257@item flatness 15258Flatness threshold where lower values mean more deblocking (default: @code{39}). 15259@end table 15260 15261@item ha/hadeblock[|difference[|flatness]] 15262Accurate horizontal deblocking filter 15263@table @option 15264@item difference 15265Difference factor where higher values mean more deblocking (default: @code{32}). 15266@item flatness 15267Flatness threshold where lower values mean more deblocking (default: @code{39}). 15268@end table 15269 15270@item va/vadeblock[|difference[|flatness]] 15271Accurate vertical deblocking filter 15272@table @option 15273@item difference 15274Difference factor where higher values mean more deblocking (default: @code{32}). 15275@item flatness 15276Flatness threshold where lower values mean more deblocking (default: @code{39}). 15277@end table 15278@end table 15279 15280The horizontal and vertical deblocking filters share the difference and 15281flatness values so you cannot set different horizontal and vertical 15282thresholds. 15283 15284@table @option 15285@item h1/x1hdeblock 15286Experimental horizontal deblocking filter 15287 15288@item v1/x1vdeblock 15289Experimental vertical deblocking filter 15290 15291@item dr/dering 15292Deringing filter 15293 15294@item tn/tmpnoise[|threshold1[|threshold2[|threshold3]]], temporal noise reducer 15295@table @option 15296@item threshold1 15297larger -> stronger filtering 15298@item threshold2 15299larger -> stronger filtering 15300@item threshold3 15301larger -> stronger filtering 15302@end table 15303 15304@item al/autolevels[:f/fullyrange], automatic brightness / contrast correction 15305@table @option 15306@item f/fullyrange 15307Stretch luminance to @code{0-255}. 15308@end table 15309 15310@item lb/linblenddeint 15311Linear blend deinterlacing filter that deinterlaces the given block by 15312filtering all lines with a @code{(1 2 1)} filter. 15313 15314@item li/linipoldeint 15315Linear interpolating deinterlacing filter that deinterlaces the given block by 15316linearly interpolating every second line. 15317 15318@item ci/cubicipoldeint 15319Cubic interpolating deinterlacing filter deinterlaces the given block by 15320cubically interpolating every second line. 15321 15322@item md/mediandeint 15323Median deinterlacing filter that deinterlaces the given block by applying a 15324median filter to every second line. 15325 15326@item fd/ffmpegdeint 15327FFmpeg deinterlacing filter that deinterlaces the given block by filtering every 15328second line with a @code{(-1 4 2 4 -1)} filter. 15329 15330@item l5/lowpass5 15331Vertically applied FIR lowpass deinterlacing filter that deinterlaces the given 15332block by filtering all lines with a @code{(-1 2 6 2 -1)} filter. 15333 15334@item fq/forceQuant[|quantizer] 15335Overrides the quantizer table from the input with the constant quantizer you 15336specify. 15337@table @option 15338@item quantizer 15339Quantizer to use 15340@end table 15341 15342@item de/default 15343Default pp filter combination (@code{hb|a,vb|a,dr|a}) 15344 15345@item fa/fast 15346Fast pp filter combination (@code{h1|a,v1|a,dr|a}) 15347 15348@item ac 15349High quality pp filter combination (@code{ha|a|128|7,va|a,dr|a}) 15350@end table 15351 15352@subsection Examples 15353 15354@itemize 15355@item 15356Apply horizontal and vertical deblocking, deringing and automatic 15357brightness/contrast: 15358@example 15359pp=hb/vb/dr/al 15360@end example 15361 15362@item 15363Apply default filters without brightness/contrast correction: 15364@example 15365pp=de/-al 15366@end example 15367 15368@item 15369Apply default filters and temporal denoiser: 15370@example 15371pp=default/tmpnoise|1|2|3 15372@end example 15373 15374@item 15375Apply deblocking on luminance only, and switch vertical deblocking on or off 15376automatically depending on available CPU time: 15377@example 15378pp=hb|y/vb|a 15379@end example 15380@end itemize 15381 15382@section pp7 15383Apply Postprocessing filter 7. It is variant of the @ref{spp} filter, 15384similar to spp = 6 with 7 point DCT, where only the center sample is 15385used after IDCT. 15386 15387The filter accepts the following options: 15388 15389@table @option 15390@item qp 15391Force a constant quantization parameter. It accepts an integer in range 153920 to 63. If not set, the filter will use the QP from the video stream 15393(if available). 15394 15395@item mode 15396Set thresholding mode. Available modes are: 15397 15398@table @samp 15399@item hard 15400Set hard thresholding. 15401@item soft 15402Set soft thresholding (better de-ringing effect, but likely blurrier). 15403@item medium 15404Set medium thresholding (good results, default). 15405@end table 15406@end table 15407 15408@section premultiply 15409Apply alpha premultiply effect to input video stream using first plane 15410of second stream as alpha. 15411 15412Both streams must have same dimensions and same pixel format. 15413 15414The filter accepts the following option: 15415 15416@table @option 15417@item planes 15418Set which planes will be processed, unprocessed planes will be copied. 15419By default value 0xf, all planes will be processed. 15420 15421@item inplace 15422Do not require 2nd input for processing, instead use alpha plane from input stream. 15423@end table 15424 15425@section prewitt 15426Apply prewitt operator to input video stream. 15427 15428The filter accepts the following option: 15429 15430@table @option 15431@item planes 15432Set which planes will be processed, unprocessed planes will be copied. 15433By default value 0xf, all planes will be processed. 15434 15435@item scale 15436Set value which will be multiplied with filtered result. 15437 15438@item delta 15439Set value which will be added to filtered result. 15440@end table 15441 15442@section pseudocolor 15443 15444Alter frame colors in video with pseudocolors. 15445 15446This filter accepts the following options: 15447 15448@table @option 15449@item c0 15450set pixel first component expression 15451 15452@item c1 15453set pixel second component expression 15454 15455@item c2 15456set pixel third component expression 15457 15458@item c3 15459set pixel fourth component expression, corresponds to the alpha component 15460 15461@item i 15462set component to use as base for altering colors 15463@end table 15464 15465Each of them specifies the expression to use for computing the lookup table for 15466the corresponding pixel component values. 15467 15468The expressions can contain the following constants and functions: 15469 15470@table @option 15471@item w 15472@item h 15473The input width and height. 15474 15475@item val 15476The input value for the pixel component. 15477 15478@item ymin, umin, vmin, amin 15479The minimum allowed component value. 15480 15481@item ymax, umax, vmax, amax 15482The maximum allowed component value. 15483@end table 15484 15485All expressions default to "val". 15486 15487@subsection Examples 15488 15489@itemize 15490@item 15491Change too high luma values to gradient: 15492@example 15493pseudocolor="'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'" 15494@end example 15495@end itemize 15496 15497@section psnr 15498 15499Obtain the average, maximum and minimum PSNR (Peak Signal to Noise 15500Ratio) between two input videos. 15501 15502This filter takes in input two input videos, the first input is 15503considered the "main" source and is passed unchanged to the 15504output. The second input is used as a "reference" video for computing 15505the PSNR. 15506 15507Both video inputs must have the same resolution and pixel format for 15508this filter to work correctly. Also it assumes that both inputs 15509have the same number of frames, which are compared one by one. 15510 15511The obtained average PSNR is printed through the logging system. 15512 15513The filter stores the accumulated MSE (mean squared error) of each 15514frame, and at the end of the processing it is averaged across all frames 15515equally, and the following formula is applied to obtain the PSNR: 15516 15517@example 15518PSNR = 10*log10(MAX^2/MSE) 15519@end example 15520 15521Where MAX is the average of the maximum values of each component of the 15522image. 15523 15524The description of the accepted parameters follows. 15525 15526@table @option 15527@item stats_file, f 15528If specified the filter will use the named file to save the PSNR of 15529each individual frame. When filename equals "-" the data is sent to 15530standard output. 15531 15532@item stats_version 15533Specifies which version of the stats file format to use. Details of 15534each format are written below. 15535Default value is 1. 15536 15537@item stats_add_max 15538Determines whether the max value is output to the stats log. 15539Default value is 0. 15540Requires stats_version >= 2. If this is set and stats_version < 2, 15541the filter will return an error. 15542@end table 15543 15544This filter also supports the @ref{framesync} options. 15545 15546The file printed if @var{stats_file} is selected, contains a sequence of 15547key/value pairs of the form @var{key}:@var{value} for each compared 15548couple of frames. 15549 15550If a @var{stats_version} greater than 1 is specified, a header line precedes 15551the list of per-frame-pair stats, with key value pairs following the frame 15552format with the following parameters: 15553 15554@table @option 15555@item psnr_log_version 15556The version of the log file format. Will match @var{stats_version}. 15557 15558@item fields 15559A comma separated list of the per-frame-pair parameters included in 15560the log. 15561@end table 15562 15563A description of each shown per-frame-pair parameter follows: 15564 15565@table @option 15566@item n 15567sequential number of the input frame, starting from 1 15568 15569@item mse_avg 15570Mean Square Error pixel-by-pixel average difference of the compared 15571frames, averaged over all the image components. 15572 15573@item mse_y, mse_u, mse_v, mse_r, mse_g, mse_b, mse_a 15574Mean Square Error pixel-by-pixel average difference of the compared 15575frames for the component specified by the suffix. 15576 15577@item psnr_y, psnr_u, psnr_v, psnr_r, psnr_g, psnr_b, psnr_a 15578Peak Signal to Noise ratio of the compared frames for the component 15579specified by the suffix. 15580 15581@item max_avg, max_y, max_u, max_v 15582Maximum allowed value for each channel, and average over all 15583channels. 15584@end table 15585 15586@subsection Examples 15587@itemize 15588@item 15589For example: 15590@example 15591movie=ref_movie.mpg, setpts=PTS-STARTPTS [main]; 15592[main][ref] psnr="stats_file=stats.log" [out] 15593@end example 15594 15595On this example the input file being processed is compared with the 15596reference file @file{ref_movie.mpg}. The PSNR of each individual frame 15597is stored in @file{stats.log}. 15598 15599@item 15600Another example with different containers: 15601@example 15602ffmpeg -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 - 15603@end example 15604@end itemize 15605 15606@anchor{pullup} 15607@section pullup 15608 15609Pulldown reversal (inverse telecine) filter, capable of handling mixed 15610hard-telecine, 24000/1001 fps progressive, and 30000/1001 fps progressive 15611content. 15612 15613The pullup filter is designed to take advantage of future context in making 15614its decisions. This filter is stateless in the sense that it does not lock 15615onto a pattern to follow, but it instead looks forward to the following 15616fields in order to identify matches and rebuild progressive frames. 15617 15618To produce content with an even framerate, insert the fps filter after 15619pullup, use @code{fps=24000/1001} if the input frame rate is 29.97fps, 15620@code{fps=24} for 30fps and the (rare) telecined 25fps input. 15621 15622The filter accepts the following options: 15623 15624@table @option 15625@item jl 15626@item jr 15627@item jt 15628@item jb 15629These options set the amount of "junk" to ignore at the left, right, top, and 15630bottom of the image, respectively. Left and right are in units of 8 pixels, 15631while top and bottom are in units of 2 lines. 15632The default is 8 pixels on each side. 15633 15634@item sb 15635Set the strict breaks. Setting this option to 1 will reduce the chances of 15636filter generating an occasional mismatched frame, but it may also cause an 15637excessive number of frames to be dropped during high motion sequences. 15638Conversely, setting it to -1 will make filter match fields more easily. 15639This may help processing of video where there is slight blurring between 15640the fields, but may also cause there to be interlaced frames in the output. 15641Default value is @code{0}. 15642 15643@item mp 15644Set the metric plane to use. It accepts the following values: 15645@table @samp 15646@item l 15647Use luma plane. 15648 15649@item u 15650Use chroma blue plane. 15651 15652@item v 15653Use chroma red plane. 15654@end table 15655 15656This option may be set to use chroma plane instead of the default luma plane 15657for doing filter's computations. This may improve accuracy on very clean 15658source material, but more likely will decrease accuracy, especially if there 15659is chroma noise (rainbow effect) or any grayscale video. 15660The main purpose of setting @option{mp} to a chroma plane is to reduce CPU 15661load and make pullup usable in realtime on slow machines. 15662@end table 15663 15664For best results (without duplicated frames in the output file) it is 15665necessary to change the output frame rate. For example, to inverse 15666telecine NTSC input: 15667@example 15668ffmpeg -i input -vf pullup -r 24000/1001 ... 15669@end example 15670 15671@section qp 15672 15673Change video quantization parameters (QP). 15674 15675The filter accepts the following option: 15676 15677@table @option 15678@item qp 15679Set expression for quantization parameter. 15680@end table 15681 15682The expression is evaluated through the eval API and can contain, among others, 15683the following constants: 15684 15685@table @var 15686@item known 156871 if index is not 129, 0 otherwise. 15688 15689@item qp 15690Sequential index starting from -129 to 128. 15691@end table 15692 15693@subsection Examples 15694 15695@itemize 15696@item 15697Some equation like: 15698@example 15699qp=2+2*sin(PI*qp) 15700@end example 15701@end itemize 15702 15703@section random 15704 15705Flush video frames from internal cache of frames into a random order. 15706No frame is discarded. 15707Inspired by @ref{frei0r} nervous filter. 15708 15709@table @option 15710@item frames 15711Set size in number of frames of internal cache, in range from @code{2} to 15712@code{512}. Default is @code{30}. 15713 15714@item seed 15715Set seed for random number generator, must be an integer included between 15716@code{0} and @code{UINT32_MAX}. If not specified, or if explicitly set to 15717less than @code{0}, the filter will try to use a good random seed on a 15718best effort basis. 15719@end table 15720 15721@section readeia608 15722 15723Read closed captioning (EIA-608) information from the top lines of a video frame. 15724 15725This filter adds frame metadata for @code{lavfi.readeia608.X.cc} and 15726@code{lavfi.readeia608.X.line}, where @code{X} is the number of the identified line 15727with EIA-608 data (starting from 0). A description of each metadata value follows: 15728 15729@table @option 15730@item lavfi.readeia608.X.cc 15731The two bytes stored as EIA-608 data (printed in hexadecimal). 15732 15733@item lavfi.readeia608.X.line 15734The number of the line on which the EIA-608 data was identified and read. 15735@end table 15736 15737This filter accepts the following options: 15738 15739@table @option 15740@item scan_min 15741Set the line to start scanning for EIA-608 data. Default is @code{0}. 15742 15743@item scan_max 15744Set the line to end scanning for EIA-608 data. Default is @code{29}. 15745 15746@item spw 15747Set the ratio of width reserved for sync code detection. 15748Default is @code{0.27}. Allowed range is @code{[0.1 - 0.7]}. 15749 15750@item chp 15751Enable checking the parity bit. In the event of a parity error, the filter will output 15752@code{0x00} for that character. Default is false. 15753 15754@item lp 15755Lowpass lines prior to further processing. Default is enabled. 15756@end table 15757 15758@subsection Examples 15759 15760@itemize 15761@item 15762Output a csv with presentation time and the first two lines of identified EIA-608 captioning data. 15763@example 15764ffprobe -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 15765@end example 15766@end itemize 15767 15768@section readvitc 15769 15770Read vertical interval timecode (VITC) information from the top lines of a 15771video frame. 15772 15773The filter adds frame metadata key @code{lavfi.readvitc.tc_str} with the 15774timecode value, if a valid timecode has been detected. Further metadata key 15775@code{lavfi.readvitc.found} is set to 0/1 depending on whether 15776timecode data has been found or not. 15777 15778This filter accepts the following options: 15779 15780@table @option 15781@item scan_max 15782Set the maximum number of lines to scan for VITC data. If the value is set to 15783@code{-1} the full video frame is scanned. Default is @code{45}. 15784 15785@item thr_b 15786Set the luma threshold for black. Accepts float numbers in the range [0.0,1.0], 15787default value is @code{0.2}. The value must be equal or less than @code{thr_w}. 15788 15789@item thr_w 15790Set the luma threshold for white. Accepts float numbers in the range [0.0,1.0], 15791default value is @code{0.6}. The value must be equal or greater than @code{thr_b}. 15792@end table 15793 15794@subsection Examples 15795 15796@itemize 15797@item 15798Detect and draw VITC data onto the video frame; if no valid VITC is detected, 15799draw @code{--:--:--:--} as a placeholder: 15800@example 15801ffmpeg -i input.avi -filter:v 'readvitc,drawtext=fontfile=FreeMono.ttf:text=%@{metadata\\:lavfi.readvitc.tc_str\\:--\\\\\\:--\\\\\\:--\\\\\\:--@}:x=(w-tw)/2:y=400-ascent' 15802@end example 15803@end itemize 15804 15805@section remap 15806 15807Remap pixels using 2nd: Xmap and 3rd: Ymap input video stream. 15808 15809Destination pixel at position (X, Y) will be picked from source (x, y) position 15810where x = Xmap(X, Y) and y = Ymap(X, Y). If mapping values are out of range, zero 15811value for pixel will be used for destination pixel. 15812 15813Xmap and Ymap input video streams must be of same dimensions. Output video stream 15814will have Xmap/Ymap video stream dimensions. 15815Xmap and Ymap input video streams are 16bit depth, single channel. 15816 15817@table @option 15818@item format 15819Specify pixel format of output from this filter. Can be @code{color} or @code{gray}. 15820Default is @code{color}. 15821 15822@item fill 15823Specify the color of the unmapped pixels. For the syntax of this option, 15824check the @ref{color syntax,,"Color" section in the ffmpeg-utils 15825manual,ffmpeg-utils}. Default color is @code{black}. 15826@end table 15827 15828@section removegrain 15829 15830The removegrain filter is a spatial denoiser for progressive video. 15831 15832@table @option 15833@item m0 15834Set mode for the first plane. 15835 15836@item m1 15837Set mode for the second plane. 15838 15839@item m2 15840Set mode for the third plane. 15841 15842@item m3 15843Set mode for the fourth plane. 15844@end table 15845 15846Range of mode is from 0 to 24. Description of each mode follows: 15847 15848@table @var 15849@item 0 15850Leave input plane unchanged. Default. 15851 15852@item 1 15853Clips the pixel with the minimum and maximum of the 8 neighbour pixels. 15854 15855@item 2 15856Clips the pixel with the second minimum and maximum of the 8 neighbour pixels. 15857 15858@item 3 15859Clips the pixel with the third minimum and maximum of the 8 neighbour pixels. 15860 15861@item 4 15862Clips the pixel with the fourth minimum and maximum of the 8 neighbour pixels. 15863This is equivalent to a median filter. 15864 15865@item 5 15866Line-sensitive clipping giving the minimal change. 15867 15868@item 6 15869Line-sensitive clipping, intermediate. 15870 15871@item 7 15872Line-sensitive clipping, intermediate. 15873 15874@item 8 15875Line-sensitive clipping, intermediate. 15876 15877@item 9 15878Line-sensitive clipping on a line where the neighbours pixels are the closest. 15879 15880@item 10 15881Replaces the target pixel with the closest neighbour. 15882 15883@item 11 15884[1 2 1] horizontal and vertical kernel blur. 15885 15886@item 12 15887Same as mode 11. 15888 15889@item 13 15890Bob mode, interpolates top field from the line where the neighbours 15891pixels are the closest. 15892 15893@item 14 15894Bob mode, interpolates bottom field from the line where the neighbours 15895pixels are the closest. 15896 15897@item 15 15898Bob mode, interpolates top field. Same as 13 but with a more complicated 15899interpolation formula. 15900 15901@item 16 15902Bob mode, interpolates bottom field. Same as 14 but with a more complicated 15903interpolation formula. 15904 15905@item 17 15906Clips the pixel with the minimum and maximum of respectively the maximum and 15907minimum of each pair of opposite neighbour pixels. 15908 15909@item 18 15910Line-sensitive clipping using opposite neighbours whose greatest distance from 15911the current pixel is minimal. 15912 15913@item 19 15914Replaces the pixel with the average of its 8 neighbours. 15915 15916@item 20 15917Averages the 9 pixels ([1 1 1] horizontal and vertical blur). 15918 15919@item 21 15920Clips pixels using the averages of opposite neighbour. 15921 15922@item 22 15923Same as mode 21 but simpler and faster. 15924 15925@item 23 15926Small edge and halo removal, but reputed useless. 15927 15928@item 24 15929Similar as 23. 15930@end table 15931 15932@section removelogo 15933 15934Suppress a TV station logo, using an image file to determine which 15935pixels comprise the logo. It works by filling in the pixels that 15936comprise the logo with neighboring pixels. 15937 15938The filter accepts the following options: 15939 15940@table @option 15941@item filename, f 15942Set the filter bitmap file, which can be any image format supported by 15943libavformat. The width and height of the image file must match those of the 15944video stream being processed. 15945@end table 15946 15947Pixels in the provided bitmap image with a value of zero are not 15948considered part of the logo, non-zero pixels are considered part of 15949the logo. If you use white (255) for the logo and black (0) for the 15950rest, you will be safe. For making the filter bitmap, it is 15951recommended to take a screen capture of a black frame with the logo 15952visible, and then using a threshold filter followed by the erode 15953filter once or twice. 15954 15955If needed, little splotches can be fixed manually. Remember that if 15956logo pixels are not covered, the filter quality will be much 15957reduced. Marking too many pixels as part of the logo does not hurt as 15958much, but it will increase the amount of blurring needed to cover over 15959the image and will destroy more information than necessary, and extra 15960pixels will slow things down on a large logo. 15961 15962@section repeatfields 15963 15964This filter uses the repeat_field flag from the Video ES headers and hard repeats 15965fields based on its value. 15966 15967@section reverse 15968 15969Reverse a video clip. 15970 15971Warning: This filter requires memory to buffer the entire clip, so trimming 15972is suggested. 15973 15974@subsection Examples 15975 15976@itemize 15977@item 15978Take the first 5 seconds of a clip, and reverse it. 15979@example 15980trim=end=5,reverse 15981@end example 15982@end itemize 15983 15984@section rgbashift 15985Shift R/G/B/A pixels horizontally and/or vertically. 15986 15987The filter accepts the following options: 15988@table @option 15989@item rh 15990Set amount to shift red horizontally. 15991@item rv 15992Set amount to shift red vertically. 15993@item gh 15994Set amount to shift green horizontally. 15995@item gv 15996Set amount to shift green vertically. 15997@item bh 15998Set amount to shift blue horizontally. 15999@item bv 16000Set amount to shift blue vertically. 16001@item ah 16002Set amount to shift alpha horizontally. 16003@item av 16004Set amount to shift alpha vertically. 16005@item edge 16006Set edge mode, can be @var{smear}, default, or @var{warp}. 16007@end table 16008 16009@subsection Commands 16010 16011This filter supports the all above options as @ref{commands}. 16012 16013@section roberts 16014Apply roberts cross operator to input video stream. 16015 16016The filter accepts the following option: 16017 16018@table @option 16019@item planes 16020Set which planes will be processed, unprocessed planes will be copied. 16021By default value 0xf, all planes will be processed. 16022 16023@item scale 16024Set value which will be multiplied with filtered result. 16025 16026@item delta 16027Set value which will be added to filtered result. 16028@end table 16029 16030@section rotate 16031 16032Rotate video by an arbitrary angle expressed in radians. 16033 16034The filter accepts the following options: 16035 16036A description of the optional parameters follows. 16037@table @option 16038@item angle, a 16039Set an expression for the angle by which to rotate the input video 16040clockwise, expressed as a number of radians. A negative value will 16041result in a counter-clockwise rotation. By default it is set to "0". 16042 16043This expression is evaluated for each frame. 16044 16045@item out_w, ow 16046Set the output width expression, default value is "iw". 16047This expression is evaluated just once during configuration. 16048 16049@item out_h, oh 16050Set the output height expression, default value is "ih". 16051This expression is evaluated just once during configuration. 16052 16053@item bilinear 16054Enable bilinear interpolation if set to 1, a value of 0 disables 16055it. Default value is 1. 16056 16057@item fillcolor, c 16058Set the color used to fill the output area not covered by the rotated 16059image. For the general syntax of this option, check the 16060@ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}. 16061If the special value "none" is selected then no 16062background is printed (useful for example if the background is never shown). 16063 16064Default value is "black". 16065@end table 16066 16067The expressions for the angle and the output size can contain the 16068following constants and functions: 16069 16070@table @option 16071@item n 16072sequential number of the input frame, starting from 0. It is always NAN 16073before the first frame is filtered. 16074 16075@item t 16076time in seconds of the input frame, it is set to 0 when the filter is 16077configured. It is always NAN before the first frame is filtered. 16078 16079@item hsub 16080@item vsub 16081horizontal and vertical chroma subsample values. For example for the 16082pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1. 16083 16084@item in_w, iw 16085@item in_h, ih 16086the input video width and height 16087 16088@item out_w, ow 16089@item out_h, oh 16090the output width and height, that is the size of the padded area as 16091specified by the @var{width} and @var{height} expressions 16092 16093@item rotw(a) 16094@item roth(a) 16095the minimal width/height required for completely containing the input 16096video rotated by @var{a} radians. 16097 16098These are only available when computing the @option{out_w} and 16099@option{out_h} expressions. 16100@end table 16101 16102@subsection Examples 16103 16104@itemize 16105@item 16106Rotate the input by PI/6 radians clockwise: 16107@example 16108rotate=PI/6 16109@end example 16110 16111@item 16112Rotate the input by PI/6 radians counter-clockwise: 16113@example 16114rotate=-PI/6 16115@end example 16116 16117@item 16118Rotate the input by 45 degrees clockwise: 16119@example 16120rotate=45*PI/180 16121@end example 16122 16123@item 16124Apply a constant rotation with period T, starting from an angle of PI/3: 16125@example 16126rotate=PI/3+2*PI*t/T 16127@end example 16128 16129@item 16130Make the input video rotation oscillating with a period of T 16131seconds and an amplitude of A radians: 16132@example 16133rotate=A*sin(2*PI/T*t) 16134@end example 16135 16136@item 16137Rotate the video, output size is chosen so that the whole rotating 16138input video is always completely contained in the output: 16139@example 16140rotate='2*PI*t:ow=hypot(iw,ih):oh=ow' 16141@end example 16142 16143@item 16144Rotate the video, reduce the output size so that no background is ever 16145shown: 16146@example 16147rotate=2*PI*t:ow='min(iw,ih)/sqrt(2)':oh=ow:c=none 16148@end example 16149@end itemize 16150 16151@subsection Commands 16152 16153The filter supports the following commands: 16154 16155@table @option 16156@item a, angle 16157Set the angle expression. 16158The command accepts the same syntax of the corresponding option. 16159 16160If the specified expression is not valid, it is kept at its current 16161value. 16162@end table 16163 16164@section sab 16165 16166Apply Shape Adaptive Blur. 16167 16168The filter accepts the following options: 16169 16170@table @option 16171@item luma_radius, lr 16172Set luma blur filter strength, must be a value in range 0.1-4.0, default 16173value is 1.0. A greater value will result in a more blurred image, and 16174in slower processing. 16175 16176@item luma_pre_filter_radius, lpfr 16177Set luma pre-filter radius, must be a value in the 0.1-2.0 range, default 16178value is 1.0. 16179 16180@item luma_strength, ls 16181Set luma maximum difference between pixels to still be considered, must 16182be a value in the 0.1-100.0 range, default value is 1.0. 16183 16184@item chroma_radius, cr 16185Set chroma blur filter strength, must be a value in range -0.9-4.0. A 16186greater value will result in a more blurred image, and in slower 16187processing. 16188 16189@item chroma_pre_filter_radius, cpfr 16190Set chroma pre-filter radius, must be a value in the -0.9-2.0 range. 16191 16192@item chroma_strength, cs 16193Set chroma maximum difference between pixels to still be considered, 16194must be a value in the -0.9-100.0 range. 16195@end table 16196 16197Each chroma option value, if not explicitly specified, is set to the 16198corresponding luma option value. 16199 16200@anchor{scale} 16201@section scale 16202 16203Scale (resize) the input video, using the libswscale library. 16204 16205The scale filter forces the output display aspect ratio to be the same 16206of the input, by changing the output sample aspect ratio. 16207 16208If the input image format is different from the format requested by 16209the next filter, the scale filter will convert the input to the 16210requested format. 16211 16212@subsection Options 16213The filter accepts the following options, or any of the options 16214supported by the libswscale scaler. 16215 16216See @ref{scaler_options,,the ffmpeg-scaler manual,ffmpeg-scaler} for 16217the complete list of scaler options. 16218 16219@table @option 16220@item width, w 16221@item height, h 16222Set the output video dimension expression. Default value is the input 16223dimension. 16224 16225If the @var{width} or @var{w} value is 0, the input width is used for 16226the output. If the @var{height} or @var{h} value is 0, the input height 16227is used for the output. 16228 16229If one and only one of the values is -n with n >= 1, the scale filter 16230will use a value that maintains the aspect ratio of the input image, 16231calculated from the other specified dimension. After that it will, 16232however, make sure that the calculated dimension is divisible by n and 16233adjust the value if necessary. 16234 16235If both values are -n with n >= 1, the behavior will be identical to 16236both values being set to 0 as previously detailed. 16237 16238See below for the list of accepted constants for use in the dimension 16239expression. 16240 16241@item eval 16242Specify when to evaluate @var{width} and @var{height} expression. It accepts the following values: 16243 16244@table @samp 16245@item init 16246Only evaluate expressions once during the filter initialization or when a command is processed. 16247 16248@item frame 16249Evaluate expressions for each incoming frame. 16250 16251@end table 16252 16253Default value is @samp{init}. 16254 16255 16256@item interl 16257Set the interlacing mode. It accepts the following values: 16258 16259@table @samp 16260@item 1 16261Force interlaced aware scaling. 16262 16263@item 0 16264Do not apply interlaced scaling. 16265 16266@item -1 16267Select interlaced aware scaling depending on whether the source frames 16268are flagged as interlaced or not. 16269@end table 16270 16271Default value is @samp{0}. 16272 16273@item flags 16274Set libswscale scaling flags. See 16275@ref{sws_flags,,the ffmpeg-scaler manual,ffmpeg-scaler} for the 16276complete list of values. If not explicitly specified the filter applies 16277the default flags. 16278 16279 16280@item param0, param1 16281Set libswscale input parameters for scaling algorithms that need them. See 16282@ref{sws_params,,the ffmpeg-scaler manual,ffmpeg-scaler} for the 16283complete documentation. If not explicitly specified the filter applies 16284empty parameters. 16285 16286 16287 16288@item size, s 16289Set the video size. For the syntax of this option, check the 16290@ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}. 16291 16292@item in_color_matrix 16293@item out_color_matrix 16294Set in/output YCbCr color space type. 16295 16296This allows the autodetected value to be overridden as well as allows forcing 16297a specific value used for the output and encoder. 16298 16299If not specified, the color space type depends on the pixel format. 16300 16301Possible values: 16302 16303@table @samp 16304@item auto 16305Choose automatically. 16306 16307@item bt709 16308Format conforming to International Telecommunication Union (ITU) 16309Recommendation BT.709. 16310 16311@item fcc 16312Set color space conforming to the United States Federal Communications 16313Commission (FCC) Code of Federal Regulations (CFR) Title 47 (2003) 73.682 (a). 16314 16315@item bt601 16316@item bt470 16317@item smpte170m 16318Set color space conforming to: 16319 16320@itemize 16321@item 16322ITU Radiocommunication Sector (ITU-R) Recommendation BT.601 16323 16324@item 16325ITU-R Rec. BT.470-6 (1998) Systems B, B1, and G 16326 16327@item 16328Society of Motion Picture and Television Engineers (SMPTE) ST 170:2004 16329 16330@end itemize 16331 16332@item smpte240m 16333Set color space conforming to SMPTE ST 240:1999. 16334 16335@item bt2020 16336Set color space conforming to ITU-R BT.2020 non-constant luminance system. 16337@end table 16338 16339@item in_range 16340@item out_range 16341Set in/output YCbCr sample range. 16342 16343This allows the autodetected value to be overridden as well as allows forcing 16344a specific value used for the output and encoder. If not specified, the 16345range depends on the pixel format. Possible values: 16346 16347@table @samp 16348@item auto/unknown 16349Choose automatically. 16350 16351@item jpeg/full/pc 16352Set full range (0-255 in case of 8-bit luma). 16353 16354@item mpeg/limited/tv 16355Set "MPEG" range (16-235 in case of 8-bit luma). 16356@end table 16357 16358@item force_original_aspect_ratio 16359Enable decreasing or increasing output video width or height if necessary to 16360keep the original aspect ratio. Possible values: 16361 16362@table @samp 16363@item disable 16364Scale the video as specified and disable this feature. 16365 16366@item decrease 16367The output video dimensions will automatically be decreased if needed. 16368 16369@item increase 16370The output video dimensions will automatically be increased if needed. 16371 16372@end table 16373 16374One useful instance of this option is that when you know a specific device's 16375maximum allowed resolution, you can use this to limit the output video to 16376that, while retaining the aspect ratio. For example, device A allows 163771280x720 playback, and your video is 1920x800. Using this option (set it to 16378decrease) and specifying 1280x720 to the command line makes the output 163791280x533. 16380 16381Please note that this is a different thing than specifying -1 for @option{w} 16382or @option{h}, you still need to specify the output resolution for this option 16383to work. 16384 16385@item force_divisible_by 16386Ensures that both the output dimensions, width and height, are divisible by the 16387given integer when used together with @option{force_original_aspect_ratio}. This 16388works similar to using @code{-n} in the @option{w} and @option{h} options. 16389 16390This option respects the value set for @option{force_original_aspect_ratio}, 16391increasing or decreasing the resolution accordingly. The video's aspect ratio 16392may be slightly modified. 16393 16394This option can be handy if you need to have a video fit within or exceed 16395a defined resolution using @option{force_original_aspect_ratio} but also have 16396encoder restrictions on width or height divisibility. 16397 16398@end table 16399 16400The values of the @option{w} and @option{h} options are expressions 16401containing the following constants: 16402 16403@table @var 16404@item in_w 16405@item in_h 16406The input width and height 16407 16408@item iw 16409@item ih 16410These are the same as @var{in_w} and @var{in_h}. 16411 16412@item out_w 16413@item out_h 16414The output (scaled) width and height 16415 16416@item ow 16417@item oh 16418These are the same as @var{out_w} and @var{out_h} 16419 16420@item a 16421The same as @var{iw} / @var{ih} 16422 16423@item sar 16424input sample aspect ratio 16425 16426@item dar 16427The input display aspect ratio. Calculated from @code{(iw / ih) * sar}. 16428 16429@item hsub 16430@item vsub 16431horizontal and vertical input chroma subsample values. For example for the 16432pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1. 16433 16434@item ohsub 16435@item ovsub 16436horizontal and vertical output chroma subsample values. For example for the 16437pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1. 16438 16439@item n 16440The (sequential) number of the input frame, starting from 0. 16441Only available with @code{eval=frame}. 16442 16443@item t 16444The presentation timestamp of the input frame, expressed as a number of 16445seconds. Only available with @code{eval=frame}. 16446 16447@item pos 16448The position (byte offset) of the frame in the input stream, or NaN if 16449this information is unavailable and/or meaningless (for example in case of synthetic video). 16450Only available with @code{eval=frame}. 16451@end table 16452 16453@subsection Examples 16454 16455@itemize 16456@item 16457Scale the input video to a size of 200x100 16458@example 16459scale=w=200:h=100 16460@end example 16461 16462This is equivalent to: 16463@example 16464scale=200:100 16465@end example 16466 16467or: 16468@example 16469scale=200x100 16470@end example 16471 16472@item 16473Specify a size abbreviation for the output size: 16474@example 16475scale=qcif 16476@end example 16477 16478which can also be written as: 16479@example 16480scale=size=qcif 16481@end example 16482 16483@item 16484Scale the input to 2x: 16485@example 16486scale=w=2*iw:h=2*ih 16487@end example 16488 16489@item 16490The above is the same as: 16491@example 16492scale=2*in_w:2*in_h 16493@end example 16494 16495@item 16496Scale the input to 2x with forced interlaced scaling: 16497@example 16498scale=2*iw:2*ih:interl=1 16499@end example 16500 16501@item 16502Scale the input to half size: 16503@example 16504scale=w=iw/2:h=ih/2 16505@end example 16506 16507@item 16508Increase the width, and set the height to the same size: 16509@example 16510scale=3/2*iw:ow 16511@end example 16512 16513@item 16514Seek Greek harmony: 16515@example 16516scale=iw:1/PHI*iw 16517scale=ih*PHI:ih 16518@end example 16519 16520@item 16521Increase the height, and set the width to 3/2 of the height: 16522@example 16523scale=w=3/2*oh:h=3/5*ih 16524@end example 16525 16526@item 16527Increase the size, making the size a multiple of the chroma 16528subsample values: 16529@example 16530scale="trunc(3/2*iw/hsub)*hsub:trunc(3/2*ih/vsub)*vsub" 16531@end example 16532 16533@item 16534Increase the width to a maximum of 500 pixels, 16535keeping the same aspect ratio as the input: 16536@example 16537scale=w='min(500\, iw*3/2):h=-1' 16538@end example 16539 16540@item 16541Make pixels square by combining scale and setsar: 16542@example 16543scale='trunc(ih*dar):ih',setsar=1/1 16544@end example 16545 16546@item 16547Make pixels square by combining scale and setsar, 16548making sure the resulting resolution is even (required by some codecs): 16549@example 16550scale='trunc(ih*dar/2)*2:trunc(ih/2)*2',setsar=1/1 16551@end example 16552@end itemize 16553 16554@subsection Commands 16555 16556This filter supports the following commands: 16557@table @option 16558@item width, w 16559@item height, h 16560Set the output video dimension expression. 16561The command accepts the same syntax of the corresponding option. 16562 16563If the specified expression is not valid, it is kept at its current 16564value. 16565@end table 16566 16567@section scale_npp 16568 16569Use the NVIDIA Performance Primitives (libnpp) to perform scaling and/or pixel 16570format conversion on CUDA video frames. Setting the output width and height 16571works in the same way as for the @var{scale} filter. 16572 16573The following additional options are accepted: 16574@table @option 16575@item format 16576The pixel format of the output CUDA frames. If set to the string "same" (the 16577default), the input format will be kept. Note that automatic format negotiation 16578and conversion is not yet supported for hardware frames 16579 16580@item interp_algo 16581The interpolation algorithm used for resizing. One of the following: 16582@table @option 16583@item nn 16584Nearest neighbour. 16585 16586@item linear 16587@item cubic 16588@item cubic2p_bspline 165892-parameter cubic (B=1, C=0) 16590 16591@item cubic2p_catmullrom 165922-parameter cubic (B=0, C=1/2) 16593 16594@item cubic2p_b05c03 165952-parameter cubic (B=1/2, C=3/10) 16596 16597@item super 16598Supersampling 16599 16600@item lanczos 16601@end table 16602 16603@item force_original_aspect_ratio 16604Enable decreasing or increasing output video width or height if necessary to 16605keep the original aspect ratio. Possible values: 16606 16607@table @samp 16608@item disable 16609Scale the video as specified and disable this feature. 16610 16611@item decrease 16612The output video dimensions will automatically be decreased if needed. 16613 16614@item increase 16615The output video dimensions will automatically be increased if needed. 16616 16617@end table 16618 16619One useful instance of this option is that when you know a specific device's 16620maximum allowed resolution, you can use this to limit the output video to 16621that, while retaining the aspect ratio. For example, device A allows 166221280x720 playback, and your video is 1920x800. Using this option (set it to 16623decrease) and specifying 1280x720 to the command line makes the output 166241280x533. 16625 16626Please note that this is a different thing than specifying -1 for @option{w} 16627or @option{h}, you still need to specify the output resolution for this option 16628to work. 16629 16630@item force_divisible_by 16631Ensures that both the output dimensions, width and height, are divisible by the 16632given integer when used together with @option{force_original_aspect_ratio}. This 16633works similar to using @code{-n} in the @option{w} and @option{h} options. 16634 16635This option respects the value set for @option{force_original_aspect_ratio}, 16636increasing or decreasing the resolution accordingly. The video's aspect ratio 16637may be slightly modified. 16638 16639This option can be handy if you need to have a video fit within or exceed 16640a defined resolution using @option{force_original_aspect_ratio} but also have 16641encoder restrictions on width or height divisibility. 16642 16643@end table 16644 16645@section scale2ref 16646 16647Scale (resize) the input video, based on a reference video. 16648 16649See the scale filter for available options, scale2ref supports the same but 16650uses the reference video instead of the main input as basis. scale2ref also 16651supports the following additional constants for the @option{w} and 16652@option{h} options: 16653 16654@table @var 16655@item main_w 16656@item main_h 16657The main input video's width and height 16658 16659@item main_a 16660The same as @var{main_w} / @var{main_h} 16661 16662@item main_sar 16663The main input video's sample aspect ratio 16664 16665@item main_dar, mdar 16666The main input video's display aspect ratio. Calculated from 16667@code{(main_w / main_h) * main_sar}. 16668 16669@item main_hsub 16670@item main_vsub 16671The main input video's horizontal and vertical chroma subsample values. 16672For example for the pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} 16673is 1. 16674 16675@item main_n 16676The (sequential) number of the main input frame, starting from 0. 16677Only available with @code{eval=frame}. 16678 16679@item main_t 16680The presentation timestamp of the main input frame, expressed as a number of 16681seconds. Only available with @code{eval=frame}. 16682 16683@item main_pos 16684The position (byte offset) of the frame in the main input stream, or NaN if 16685this information is unavailable and/or meaningless (for example in case of synthetic video). 16686Only available with @code{eval=frame}. 16687@end table 16688 16689@subsection Examples 16690 16691@itemize 16692@item 16693Scale a subtitle stream (b) to match the main video (a) in size before overlaying 16694@example 16695'scale2ref[b][a];[a][b]overlay' 16696@end example 16697 16698@item 16699Scale a logo to 1/10th the height of a video, while preserving its display aspect ratio. 16700@example 16701[logo-in][video-in]scale2ref=w=oh*mdar:h=ih/10[logo-out][video-out] 16702@end example 16703@end itemize 16704 16705@subsection Commands 16706 16707This filter supports the following commands: 16708@table @option 16709@item width, w 16710@item height, h 16711Set the output video dimension expression. 16712The command accepts the same syntax of the corresponding option. 16713 16714If the specified expression is not valid, it is kept at its current 16715value. 16716@end table 16717 16718@section scroll 16719Scroll input video horizontally and/or vertically by constant speed. 16720 16721The filter accepts the following options: 16722@table @option 16723@item horizontal, h 16724Set the horizontal scrolling speed. Default is 0. Allowed range is from -1 to 1. 16725Negative values changes scrolling direction. 16726 16727@item vertical, v 16728Set the vertical scrolling speed. Default is 0. Allowed range is from -1 to 1. 16729Negative values changes scrolling direction. 16730 16731@item hpos 16732Set the initial horizontal scrolling position. Default is 0. Allowed range is from 0 to 1. 16733 16734@item vpos 16735Set the initial vertical scrolling position. Default is 0. Allowed range is from 0 to 1. 16736@end table 16737 16738@subsection Commands 16739 16740This filter supports the following @ref{commands}: 16741@table @option 16742@item horizontal, h 16743Set the horizontal scrolling speed. 16744@item vertical, v 16745Set the vertical scrolling speed. 16746@end table 16747 16748@anchor{scdet} 16749@section scdet 16750 16751Detect video scene change. 16752 16753This filter sets frame metadata with mafd between frame, the scene score, and 16754forward the frame to the next filter, so they can use these metadata to detect 16755scene change or others. 16756 16757In addition, this filter logs a message and sets frame metadata when it detects 16758a scene change by @option{threshold}. 16759 16760@code{lavfi.scd.mafd} metadata keys are set with mafd for every frame. 16761 16762@code{lavfi.scd.score} metadata keys are set with scene change score for every frame 16763to detect scene change. 16764 16765@code{lavfi.scd.time} metadata keys are set with current filtered frame time which 16766detect scene change with @option{threshold}. 16767 16768The filter accepts the following options: 16769 16770@table @option 16771@item threshold, t 16772Set the scene change detection threshold as a percentage of maximum change. Good 16773values are in the @code{[8.0, 14.0]} range. The range for @option{threshold} is 16774@code{[0., 100.]}. 16775 16776Default value is @code{10.}. 16777 16778@item sc_pass, s 16779Set the flag to pass scene change frames to the next filter. Default value is @code{0} 16780You can enable it if you want to get snapshot of scene change frames only. 16781@end table 16782 16783@anchor{selectivecolor} 16784@section selectivecolor 16785 16786Adjust cyan, magenta, yellow and black (CMYK) to certain ranges of colors (such 16787as "reds", "yellows", "greens", "cyans", ...). The adjustment range is defined 16788by the "purity" of the color (that is, how saturated it already is). 16789 16790This filter is similar to the Adobe Photoshop Selective Color tool. 16791 16792The filter accepts the following options: 16793 16794@table @option 16795@item correction_method 16796Select color correction method. 16797 16798Available values are: 16799@table @samp 16800@item absolute 16801Specified adjustments are applied "as-is" (added/subtracted to original pixel 16802component value). 16803@item relative 16804Specified adjustments are relative to the original component value. 16805@end table 16806Default is @code{absolute}. 16807@item reds 16808Adjustments for red pixels (pixels where the red component is the maximum) 16809@item yellows 16810Adjustments for yellow pixels (pixels where the blue component is the minimum) 16811@item greens 16812Adjustments for green pixels (pixels where the green component is the maximum) 16813@item cyans 16814Adjustments for cyan pixels (pixels where the red component is the minimum) 16815@item blues 16816Adjustments for blue pixels (pixels where the blue component is the maximum) 16817@item magentas 16818Adjustments for magenta pixels (pixels where the green component is the minimum) 16819@item whites 16820Adjustments for white pixels (pixels where all components are greater than 128) 16821@item neutrals 16822Adjustments for all pixels except pure black and pure white 16823@item blacks 16824Adjustments for black pixels (pixels where all components are lesser than 128) 16825@item psfile 16826Specify a Photoshop selective color file (@code{.asv}) to import the settings from. 16827@end table 16828 16829All the adjustment settings (@option{reds}, @option{yellows}, ...) accept up to 168304 space separated floating point adjustment values in the [-1,1] range, 16831respectively to adjust the amount of cyan, magenta, yellow and black for the 16832pixels of its range. 16833 16834@subsection Examples 16835 16836@itemize 16837@item 16838Increase cyan by 50% and reduce yellow by 33% in every green areas, and 16839increase magenta by 27% in blue areas: 16840@example 16841selectivecolor=greens=.5 0 -.33 0:blues=0 .27 16842@end example 16843 16844@item 16845Use a Photoshop selective color preset: 16846@example 16847selectivecolor=psfile=MySelectiveColorPresets/Misty.asv 16848@end example 16849@end itemize 16850 16851@anchor{separatefields} 16852@section separatefields 16853 16854The @code{separatefields} takes a frame-based video input and splits 16855each frame into its components fields, producing a new half height clip 16856with twice the frame rate and twice the frame count. 16857 16858This filter use field-dominance information in frame to decide which 16859of each pair of fields to place first in the output. 16860If it gets it wrong use @ref{setfield} filter before @code{separatefields} filter. 16861 16862@section setdar, setsar 16863 16864The @code{setdar} filter sets the Display Aspect Ratio for the filter 16865output video. 16866 16867This is done by changing the specified Sample (aka Pixel) Aspect 16868Ratio, according to the following equation: 16869@example 16870@var{DAR} = @var{HORIZONTAL_RESOLUTION} / @var{VERTICAL_RESOLUTION} * @var{SAR} 16871@end example 16872 16873Keep in mind that the @code{setdar} filter does not modify the pixel 16874dimensions of the video frame. Also, the display aspect ratio set by 16875this filter may be changed by later filters in the filterchain, 16876e.g. in case of scaling or if another "setdar" or a "setsar" filter is 16877applied. 16878 16879The @code{setsar} filter sets the Sample (aka Pixel) Aspect Ratio for 16880the filter output video. 16881 16882Note that as a consequence of the application of this filter, the 16883output display aspect ratio will change according to the equation 16884above. 16885 16886Keep in mind that the sample aspect ratio set by the @code{setsar} 16887filter may be changed by later filters in the filterchain, e.g. if 16888another "setsar" or a "setdar" filter is applied. 16889 16890It accepts the following parameters: 16891 16892@table @option 16893@item r, ratio, dar (@code{setdar} only), sar (@code{setsar} only) 16894Set the aspect ratio used by the filter. 16895 16896The parameter can be a floating point number string, an expression, or 16897a string of the form @var{num}:@var{den}, where @var{num} and 16898@var{den} are the numerator and denominator of the aspect ratio. If 16899the parameter is not specified, it is assumed the value "0". 16900In case the form "@var{num}:@var{den}" is used, the @code{:} character 16901should be escaped. 16902 16903@item max 16904Set the maximum integer value to use for expressing numerator and 16905denominator when reducing the expressed aspect ratio to a rational. 16906Default value is @code{100}. 16907 16908@end table 16909 16910The parameter @var{sar} is an expression containing 16911the following constants: 16912 16913@table @option 16914@item E, PI, PHI 16915These are approximated values for the mathematical constants e 16916(Euler's number), pi (Greek pi), and phi (the golden ratio). 16917 16918@item w, h 16919The input width and height. 16920 16921@item a 16922These are the same as @var{w} / @var{h}. 16923 16924@item sar 16925The input sample aspect ratio. 16926 16927@item dar 16928The input display aspect ratio. It is the same as 16929(@var{w} / @var{h}) * @var{sar}. 16930 16931@item hsub, vsub 16932Horizontal and vertical chroma subsample values. For example, for the 16933pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1. 16934@end table 16935 16936@subsection Examples 16937 16938@itemize 16939 16940@item 16941To change the display aspect ratio to 16:9, specify one of the following: 16942@example 16943setdar=dar=1.77777 16944setdar=dar=16/9 16945@end example 16946 16947@item 16948To change the sample aspect ratio to 10:11, specify: 16949@example 16950setsar=sar=10/11 16951@end example 16952 16953@item 16954To set a display aspect ratio of 16:9, and specify a maximum integer value of 169551000 in the aspect ratio reduction, use the command: 16956@example 16957setdar=ratio=16/9:max=1000 16958@end example 16959 16960@end itemize 16961 16962@anchor{setfield} 16963@section setfield 16964 16965Force field for the output video frame. 16966 16967The @code{setfield} filter marks the interlace type field for the 16968output frames. It does not change the input frame, but only sets the 16969corresponding property, which affects how the frame is treated by 16970following filters (e.g. @code{fieldorder} or @code{yadif}). 16971 16972The filter accepts the following options: 16973 16974@table @option 16975 16976@item mode 16977Available values are: 16978 16979@table @samp 16980@item auto 16981Keep the same field property. 16982 16983@item bff 16984Mark the frame as bottom-field-first. 16985 16986@item tff 16987Mark the frame as top-field-first. 16988 16989@item prog 16990Mark the frame as progressive. 16991@end table 16992@end table 16993 16994@anchor{setparams} 16995@section setparams 16996 16997Force frame parameter for the output video frame. 16998 16999The @code{setparams} filter marks interlace and color range for the 17000output frames. It does not change the input frame, but only sets the 17001corresponding property, which affects how the frame is treated by 17002filters/encoders. 17003 17004@table @option 17005@item field_mode 17006Available values are: 17007 17008@table @samp 17009@item auto 17010Keep the same field property (default). 17011 17012@item bff 17013Mark the frame as bottom-field-first. 17014 17015@item tff 17016Mark the frame as top-field-first. 17017 17018@item prog 17019Mark the frame as progressive. 17020@end table 17021 17022@item range 17023Available values are: 17024 17025@table @samp 17026@item auto 17027Keep the same color range property (default). 17028 17029@item unspecified, unknown 17030Mark the frame as unspecified color range. 17031 17032@item limited, tv, mpeg 17033Mark the frame as limited range. 17034 17035@item full, pc, jpeg 17036Mark the frame as full range. 17037@end table 17038 17039@item color_primaries 17040Set the color primaries. 17041Available values are: 17042 17043@table @samp 17044@item auto 17045Keep the same color primaries property (default). 17046 17047@item bt709 17048@item unknown 17049@item bt470m 17050@item bt470bg 17051@item smpte170m 17052@item smpte240m 17053@item film 17054@item bt2020 17055@item smpte428 17056@item smpte431 17057@item smpte432 17058@item jedec-p22 17059@end table 17060 17061@item color_trc 17062Set the color transfer. 17063Available values are: 17064 17065@table @samp 17066@item auto 17067Keep the same color trc property (default). 17068 17069@item bt709 17070@item unknown 17071@item bt470m 17072@item bt470bg 17073@item smpte170m 17074@item smpte240m 17075@item linear 17076@item log100 17077@item log316 17078@item iec61966-2-4 17079@item bt1361e 17080@item iec61966-2-1 17081@item bt2020-10 17082@item bt2020-12 17083@item smpte2084 17084@item smpte428 17085@item arib-std-b67 17086@end table 17087 17088@item colorspace 17089Set the colorspace. 17090Available values are: 17091 17092@table @samp 17093@item auto 17094Keep the same colorspace property (default). 17095 17096@item gbr 17097@item bt709 17098@item unknown 17099@item fcc 17100@item bt470bg 17101@item smpte170m 17102@item smpte240m 17103@item ycgco 17104@item bt2020nc 17105@item bt2020c 17106@item smpte2085 17107@item chroma-derived-nc 17108@item chroma-derived-c 17109@item ictcp 17110@end table 17111@end table 17112 17113@section showinfo 17114 17115Show a line containing various information for each input video frame. 17116The input video is not modified. 17117 17118This filter supports the following options: 17119 17120@table @option 17121@item checksum 17122Calculate checksums of each plane. By default enabled. 17123@end table 17124 17125The shown line contains a sequence of key/value pairs of the form 17126@var{key}:@var{value}. 17127 17128The following values are shown in the output: 17129 17130@table @option 17131@item n 17132The (sequential) number of the input frame, starting from 0. 17133 17134@item pts 17135The Presentation TimeStamp of the input frame, expressed as a number of 17136time base units. The time base unit depends on the filter input pad. 17137 17138@item pts_time 17139The Presentation TimeStamp of the input frame, expressed as a number of 17140seconds. 17141 17142@item pos 17143The position of the frame in the input stream, or -1 if this information is 17144unavailable and/or meaningless (for example in case of synthetic video). 17145 17146@item fmt 17147The pixel format name. 17148 17149@item sar 17150The sample aspect ratio of the input frame, expressed in the form 17151@var{num}/@var{den}. 17152 17153@item s 17154The size of the input frame. For the syntax of this option, check the 17155@ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}. 17156 17157@item i 17158The type of interlaced mode ("P" for "progressive", "T" for top field first, "B" 17159for bottom field first). 17160 17161@item iskey 17162This is 1 if the frame is a key frame, 0 otherwise. 17163 17164@item type 17165The picture type of the input frame ("I" for an I-frame, "P" for a 17166P-frame, "B" for a B-frame, or "?" for an unknown type). 17167Also refer to the documentation of the @code{AVPictureType} enum and of 17168the @code{av_get_picture_type_char} function defined in 17169@file{libavutil/avutil.h}. 17170 17171@item checksum 17172The Adler-32 checksum (printed in hexadecimal) of all the planes of the input frame. 17173 17174@item plane_checksum 17175The Adler-32 checksum (printed in hexadecimal) of each plane of the input frame, 17176expressed in the form "[@var{c0} @var{c1} @var{c2} @var{c3}]". 17177 17178@item mean 17179The mean value of pixels in each plane of the input frame, expressed in the form 17180"[@var{mean0} @var{mean1} @var{mean2} @var{mean3}]". 17181 17182@item stdev 17183The standard deviation of pixel values in each plane of the input frame, expressed 17184in the form "[@var{stdev0} @var{stdev1} @var{stdev2} @var{stdev3}]". 17185 17186@end table 17187 17188@section showpalette 17189 17190Displays the 256 colors palette of each frame. This filter is only relevant for 17191@var{pal8} pixel format frames. 17192 17193It accepts the following option: 17194 17195@table @option 17196@item s 17197Set the size of the box used to represent one palette color entry. Default is 17198@code{30} (for a @code{30x30} pixel box). 17199@end table 17200 17201@section shuffleframes 17202 17203Reorder and/or duplicate and/or drop video frames. 17204 17205It accepts the following parameters: 17206 17207@table @option 17208@item mapping 17209Set the destination indexes of input frames. 17210This is space or '|' separated list of indexes that maps input frames to output 17211frames. Number of indexes also sets maximal value that each index may have. 17212'-1' index have special meaning and that is to drop frame. 17213@end table 17214 17215The first frame has the index 0. The default is to keep the input unchanged. 17216 17217@subsection Examples 17218 17219@itemize 17220@item 17221Swap second and third frame of every three frames of the input: 17222@example 17223ffmpeg -i INPUT -vf "shuffleframes=0 2 1" OUTPUT 17224@end example 17225 17226@item 17227Swap 10th and 1st frame of every ten frames of the input: 17228@example 17229ffmpeg -i INPUT -vf "shuffleframes=9 1 2 3 4 5 6 7 8 0" OUTPUT 17230@end example 17231@end itemize 17232 17233@section shuffleplanes 17234 17235Reorder and/or duplicate video planes. 17236 17237It accepts the following parameters: 17238 17239@table @option 17240 17241@item map0 17242The index of the input plane to be used as the first output plane. 17243 17244@item map1 17245The index of the input plane to be used as the second output plane. 17246 17247@item map2 17248The index of the input plane to be used as the third output plane. 17249 17250@item map3 17251The index of the input plane to be used as the fourth output plane. 17252 17253@end table 17254 17255The first plane has the index 0. The default is to keep the input unchanged. 17256 17257@subsection Examples 17258 17259@itemize 17260@item 17261Swap the second and third planes of the input: 17262@example 17263ffmpeg -i INPUT -vf shuffleplanes=0:2:1:3 OUTPUT 17264@end example 17265@end itemize 17266 17267@anchor{signalstats} 17268@section signalstats 17269Evaluate various visual metrics that assist in determining issues associated 17270with the digitization of analog video media. 17271 17272By default the filter will log these metadata values: 17273 17274@table @option 17275@item YMIN 17276Display the minimal Y value contained within the input frame. Expressed in 17277range of [0-255]. 17278 17279@item YLOW 17280Display the Y value at the 10% percentile within the input frame. Expressed in 17281range of [0-255]. 17282 17283@item YAVG 17284Display the average Y value within the input frame. Expressed in range of 17285[0-255]. 17286 17287@item YHIGH 17288Display the Y value at the 90% percentile within the input frame. Expressed in 17289range of [0-255]. 17290 17291@item YMAX 17292Display the maximum Y value contained within the input frame. Expressed in 17293range of [0-255]. 17294 17295@item UMIN 17296Display the minimal U value contained within the input frame. Expressed in 17297range of [0-255]. 17298 17299@item ULOW 17300Display the U value at the 10% percentile within the input frame. Expressed in 17301range of [0-255]. 17302 17303@item UAVG 17304Display the average U value within the input frame. Expressed in range of 17305[0-255]. 17306 17307@item UHIGH 17308Display the U value at the 90% percentile within the input frame. Expressed in 17309range of [0-255]. 17310 17311@item UMAX 17312Display the maximum U value contained within the input frame. Expressed in 17313range of [0-255]. 17314 17315@item VMIN 17316Display the minimal V value contained within the input frame. Expressed in 17317range of [0-255]. 17318 17319@item VLOW 17320Display the V value at the 10% percentile within the input frame. Expressed in 17321range of [0-255]. 17322 17323@item VAVG 17324Display the average V value within the input frame. Expressed in range of 17325[0-255]. 17326 17327@item VHIGH 17328Display the V value at the 90% percentile within the input frame. Expressed in 17329range of [0-255]. 17330 17331@item VMAX 17332Display the maximum V value contained within the input frame. Expressed in 17333range of [0-255]. 17334 17335@item SATMIN 17336Display the minimal saturation value contained within the input frame. 17337Expressed in range of [0-~181.02]. 17338 17339@item SATLOW 17340Display the saturation value at the 10% percentile within the input frame. 17341Expressed in range of [0-~181.02]. 17342 17343@item SATAVG 17344Display the average saturation value within the input frame. Expressed in range 17345of [0-~181.02]. 17346 17347@item SATHIGH 17348Display the saturation value at the 90% percentile within the input frame. 17349Expressed in range of [0-~181.02]. 17350 17351@item SATMAX 17352Display the maximum saturation value contained within the input frame. 17353Expressed in range of [0-~181.02]. 17354 17355@item HUEMED 17356Display the median value for hue within the input frame. Expressed in range of 17357[0-360]. 17358 17359@item HUEAVG 17360Display the average value for hue within the input frame. Expressed in range of 17361[0-360]. 17362 17363@item YDIF 17364Display the average of sample value difference between all values of the Y 17365plane in the current frame and corresponding values of the previous input frame. 17366Expressed in range of [0-255]. 17367 17368@item UDIF 17369Display the average of sample value difference between all values of the U 17370plane in the current frame and corresponding values of the previous input frame. 17371Expressed in range of [0-255]. 17372 17373@item VDIF 17374Display the average of sample value difference between all values of the V 17375plane in the current frame and corresponding values of the previous input frame. 17376Expressed in range of [0-255]. 17377 17378@item YBITDEPTH 17379Display bit depth of Y plane in current frame. 17380Expressed in range of [0-16]. 17381 17382@item UBITDEPTH 17383Display bit depth of U plane in current frame. 17384Expressed in range of [0-16]. 17385 17386@item VBITDEPTH 17387Display bit depth of V plane in current frame. 17388Expressed in range of [0-16]. 17389@end table 17390 17391The filter accepts the following options: 17392 17393@table @option 17394@item stat 17395@item out 17396 17397@option{stat} specify an additional form of image analysis. 17398@option{out} output video with the specified type of pixel highlighted. 17399 17400Both options accept the following values: 17401 17402@table @samp 17403@item tout 17404Identify @var{temporal outliers} pixels. A @var{temporal outlier} is a pixel 17405unlike the neighboring pixels of the same field. Examples of temporal outliers 17406include the results of video dropouts, head clogs, or tape tracking issues. 17407 17408@item vrep 17409Identify @var{vertical line repetition}. Vertical line repetition includes 17410similar rows of pixels within a frame. In born-digital video vertical line 17411repetition is common, but this pattern is uncommon in video digitized from an 17412analog source. When it occurs in video that results from the digitization of an 17413analog source it can indicate concealment from a dropout compensator. 17414 17415@item brng 17416Identify pixels that fall outside of legal broadcast range. 17417@end table 17418 17419@item color, c 17420Set the highlight color for the @option{out} option. The default color is 17421yellow. 17422@end table 17423 17424@subsection Examples 17425 17426@itemize 17427@item 17428Output data of various video metrics: 17429@example 17430ffprobe -f lavfi movie=example.mov,signalstats="stat=tout+vrep+brng" -show_frames 17431@end example 17432 17433@item 17434Output specific data about the minimum and maximum values of the Y plane per frame: 17435@example 17436ffprobe -f lavfi movie=example.mov,signalstats -show_entries frame_tags=lavfi.signalstats.YMAX,lavfi.signalstats.YMIN 17437@end example 17438 17439@item 17440Playback video while highlighting pixels that are outside of broadcast range in red. 17441@example 17442ffplay example.mov -vf signalstats="out=brng:color=red" 17443@end example 17444 17445@item 17446Playback video with signalstats metadata drawn over the frame. 17447@example 17448ffplay example.mov -vf signalstats=stat=brng+vrep+tout,drawtext=fontfile=FreeSerif.ttf:textfile=signalstat_drawtext.txt 17449@end example 17450 17451The contents of signalstat_drawtext.txt used in the command are: 17452@example 17453time %@{pts:hms@} 17454Y (%@{metadata:lavfi.signalstats.YMIN@}-%@{metadata:lavfi.signalstats.YMAX@}) 17455U (%@{metadata:lavfi.signalstats.UMIN@}-%@{metadata:lavfi.signalstats.UMAX@}) 17456V (%@{metadata:lavfi.signalstats.VMIN@}-%@{metadata:lavfi.signalstats.VMAX@}) 17457saturation maximum: %@{metadata:lavfi.signalstats.SATMAX@} 17458 17459@end example 17460@end itemize 17461 17462@anchor{signature} 17463@section signature 17464 17465Calculates the MPEG-7 Video Signature. The filter can handle more than one 17466input. In this case the matching between the inputs can be calculated additionally. 17467The filter always passes through the first input. The signature of each stream can 17468be written into a file. 17469 17470It accepts the following options: 17471 17472@table @option 17473@item detectmode 17474Enable or disable the matching process. 17475 17476Available values are: 17477 17478@table @samp 17479@item off 17480Disable the calculation of a matching (default). 17481@item full 17482Calculate the matching for the whole video and output whether the whole video 17483matches or only parts. 17484@item fast 17485Calculate only until a matching is found or the video ends. Should be faster in 17486some cases. 17487@end table 17488 17489@item nb_inputs 17490Set the number of inputs. The option value must be a non negative integer. 17491Default value is 1. 17492 17493@item filename 17494Set the path to which the output is written. If there is more than one input, 17495the path must be a prototype, i.e. must contain %d or %0nd (where n is a positive 17496integer), that will be replaced with the input number. If no filename is 17497specified, no output will be written. This is the default. 17498 17499@item format 17500Choose the output format. 17501 17502Available values are: 17503 17504@table @samp 17505@item binary 17506Use the specified binary representation (default). 17507@item xml 17508Use the specified xml representation. 17509@end table 17510 17511@item th_d 17512Set threshold to detect one word as similar. The option value must be an integer 17513greater than zero. The default value is 9000. 17514 17515@item th_dc 17516Set threshold to detect all words as similar. The option value must be an integer 17517greater than zero. The default value is 60000. 17518 17519@item th_xh 17520Set threshold to detect frames as similar. The option value must be an integer 17521greater than zero. The default value is 116. 17522 17523@item th_di 17524Set the minimum length of a sequence in frames to recognize it as matching 17525sequence. The option value must be a non negative integer value. 17526The default value is 0. 17527 17528@item th_it 17529Set the minimum relation, that matching frames to all frames must have. 17530The option value must be a double value between 0 and 1. The default value is 0.5. 17531@end table 17532 17533@subsection Examples 17534 17535@itemize 17536@item 17537To calculate the signature of an input video and store it in signature.bin: 17538@example 17539ffmpeg -i input.mkv -vf signature=filename=signature.bin -map 0:v -f null - 17540@end example 17541 17542@item 17543To detect whether two videos match and store the signatures in XML format in 17544signature0.xml and signature1.xml: 17545@example 17546ffmpeg -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 - 17547@end example 17548 17549@end itemize 17550 17551@anchor{smartblur} 17552@section smartblur 17553 17554Blur the input video without impacting the outlines. 17555 17556It accepts the following options: 17557 17558@table @option 17559@item luma_radius, lr 17560Set the luma radius. The option value must be a float number in 17561the range [0.1,5.0] that specifies the variance of the gaussian filter 17562used to blur the image (slower if larger). Default value is 1.0. 17563 17564@item luma_strength, ls 17565Set the luma strength. The option value must be a float number 17566in the range [-1.0,1.0] that configures the blurring. A value included 17567in [0.0,1.0] will blur the image whereas a value included in 17568[-1.0,0.0] will sharpen the image. Default value is 1.0. 17569 17570@item luma_threshold, lt 17571Set the luma threshold used as a coefficient to determine 17572whether a pixel should be blurred or not. The option value must be an 17573integer in the range [-30,30]. A value of 0 will filter all the image, 17574a value included in [0,30] will filter flat areas and a value included 17575in [-30,0] will filter edges. Default value is 0. 17576 17577@item chroma_radius, cr 17578Set the chroma radius. The option value must be a float number in 17579the range [0.1,5.0] that specifies the variance of the gaussian filter 17580used to blur the image (slower if larger). Default value is @option{luma_radius}. 17581 17582@item chroma_strength, cs 17583Set the chroma strength. The option value must be a float number 17584in the range [-1.0,1.0] that configures the blurring. A value included 17585in [0.0,1.0] will blur the image whereas a value included in 17586[-1.0,0.0] will sharpen the image. Default value is @option{luma_strength}. 17587 17588@item chroma_threshold, ct 17589Set the chroma threshold used as a coefficient to determine 17590whether a pixel should be blurred or not. The option value must be an 17591integer in the range [-30,30]. A value of 0 will filter all the image, 17592a value included in [0,30] will filter flat areas and a value included 17593in [-30,0] will filter edges. Default value is @option{luma_threshold}. 17594@end table 17595 17596If a chroma option is not explicitly set, the corresponding luma value 17597is set. 17598 17599@section sobel 17600Apply sobel operator to input video stream. 17601 17602The filter accepts the following option: 17603 17604@table @option 17605@item planes 17606Set which planes will be processed, unprocessed planes will be copied. 17607By default value 0xf, all planes will be processed. 17608 17609@item scale 17610Set value which will be multiplied with filtered result. 17611 17612@item delta 17613Set value which will be added to filtered result. 17614@end table 17615 17616@anchor{spp} 17617@section spp 17618 17619Apply a simple postprocessing filter that compresses and decompresses the image 17620at several (or - in the case of @option{quality} level @code{6} - all) shifts 17621and average the results. 17622 17623The filter accepts the following options: 17624 17625@table @option 17626@item quality 17627Set quality. This option defines the number of levels for averaging. It accepts 17628an integer in the range 0-6. If set to @code{0}, the filter will have no 17629effect. A value of @code{6} means the higher quality. For each increment of 17630that value the speed drops by a factor of approximately 2. Default value is 17631@code{3}. 17632 17633@item qp 17634Force a constant quantization parameter. If not set, the filter will use the QP 17635from the video stream (if available). 17636 17637@item mode 17638Set thresholding mode. Available modes are: 17639 17640@table @samp 17641@item hard 17642Set hard thresholding (default). 17643@item soft 17644Set soft thresholding (better de-ringing effect, but likely blurrier). 17645@end table 17646 17647@item use_bframe_qp 17648Enable the use of the QP from the B-Frames if set to @code{1}. Using this 17649option may cause flicker since the B-Frames have often larger QP. Default is 17650@code{0} (not enabled). 17651@end table 17652 17653@subsection Commands 17654 17655This filter supports the following commands: 17656@table @option 17657@item quality, level 17658Set quality level. The value @code{max} can be used to set the maximum level, 17659currently @code{6}. 17660@end table 17661 17662@anchor{sr} 17663@section sr 17664 17665Scale the input by applying one of the super-resolution methods based on 17666convolutional neural networks. Supported models: 17667 17668@itemize 17669@item 17670Super-Resolution Convolutional Neural Network model (SRCNN). 17671See @url{https://arxiv.org/abs/1501.00092}. 17672 17673@item 17674Efficient Sub-Pixel Convolutional Neural Network model (ESPCN). 17675See @url{https://arxiv.org/abs/1609.05158}. 17676@end itemize 17677 17678Training scripts as well as scripts for model file (.pb) saving can be found at 17679@url{https://github.com/XueweiMeng/sr/tree/sr_dnn_native}. Original repository 17680is at @url{https://github.com/HighVoltageRocknRoll/sr.git}. 17681 17682Native model files (.model) can be generated from TensorFlow model 17683files (.pb) by using tools/python/convert.py 17684 17685The filter accepts the following options: 17686 17687@table @option 17688@item dnn_backend 17689Specify which DNN backend to use for model loading and execution. This option accepts 17690the following values: 17691 17692@table @samp 17693@item native 17694Native implementation of DNN loading and execution. 17695 17696@item tensorflow 17697TensorFlow backend. To enable this backend you 17698need to install the TensorFlow for C library (see 17699@url{https://www.tensorflow.org/install/install_c}) and configure FFmpeg with 17700@code{--enable-libtensorflow} 17701@end table 17702 17703Default value is @samp{native}. 17704 17705@item model 17706Set path to model file specifying network architecture and its parameters. 17707Note that different backends use different file formats. TensorFlow backend 17708can load files for both formats, while native backend can load files for only 17709its format. 17710 17711@item scale_factor 17712Set scale factor for SRCNN model. Allowed values are @code{2}, @code{3} and @code{4}. 17713Default value is @code{2}. Scale factor is necessary for SRCNN model, because it accepts 17714input upscaled using bicubic upscaling with proper scale factor. 17715@end table 17716 17717This feature can also be finished with @ref{dnn_processing} filter. 17718 17719@section ssim 17720 17721Obtain the SSIM (Structural SImilarity Metric) between two input videos. 17722 17723This filter takes in input two input videos, the first input is 17724considered the "main" source and is passed unchanged to the 17725output. The second input is used as a "reference" video for computing 17726the SSIM. 17727 17728Both video inputs must have the same resolution and pixel format for 17729this filter to work correctly. Also it assumes that both inputs 17730have the same number of frames, which are compared one by one. 17731 17732The filter stores the calculated SSIM of each frame. 17733 17734The description of the accepted parameters follows. 17735 17736@table @option 17737@item stats_file, f 17738If specified the filter will use the named file to save the SSIM of 17739each individual frame. When filename equals "-" the data is sent to 17740standard output. 17741@end table 17742 17743The file printed if @var{stats_file} is selected, contains a sequence of 17744key/value pairs of the form @var{key}:@var{value} for each compared 17745couple of frames. 17746 17747A description of each shown parameter follows: 17748 17749@table @option 17750@item n 17751sequential number of the input frame, starting from 1 17752 17753@item Y, U, V, R, G, B 17754SSIM of the compared frames for the component specified by the suffix. 17755 17756@item All 17757SSIM of the compared frames for the whole frame. 17758 17759@item dB 17760Same as above but in dB representation. 17761@end table 17762 17763This filter also supports the @ref{framesync} options. 17764 17765@subsection Examples 17766@itemize 17767@item 17768For example: 17769@example 17770movie=ref_movie.mpg, setpts=PTS-STARTPTS [main]; 17771[main][ref] ssim="stats_file=stats.log" [out] 17772@end example 17773 17774On this example the input file being processed is compared with the 17775reference file @file{ref_movie.mpg}. The SSIM of each individual frame 17776is stored in @file{stats.log}. 17777 17778@item 17779Another example with both psnr and ssim at same time: 17780@example 17781ffmpeg -i main.mpg -i ref.mpg -lavfi "ssim;[0:v][1:v]psnr" -f null - 17782@end example 17783 17784@item 17785Another example with different containers: 17786@example 17787ffmpeg -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 - 17788@end example 17789@end itemize 17790 17791@section stereo3d 17792 17793Convert between different stereoscopic image formats. 17794 17795The filters accept the following options: 17796 17797@table @option 17798@item in 17799Set stereoscopic image format of input. 17800 17801Available values for input image formats are: 17802@table @samp 17803@item sbsl 17804side by side parallel (left eye left, right eye right) 17805 17806@item sbsr 17807side by side crosseye (right eye left, left eye right) 17808 17809@item sbs2l 17810side by side parallel with half width resolution 17811(left eye left, right eye right) 17812 17813@item sbs2r 17814side by side crosseye with half width resolution 17815(right eye left, left eye right) 17816 17817@item abl 17818@item tbl 17819above-below (left eye above, right eye below) 17820 17821@item abr 17822@item tbr 17823above-below (right eye above, left eye below) 17824 17825@item ab2l 17826@item tb2l 17827above-below with half height resolution 17828(left eye above, right eye below) 17829 17830@item ab2r 17831@item tb2r 17832above-below with half height resolution 17833(right eye above, left eye below) 17834 17835@item al 17836alternating frames (left eye first, right eye second) 17837 17838@item ar 17839alternating frames (right eye first, left eye second) 17840 17841@item irl 17842interleaved rows (left eye has top row, right eye starts on next row) 17843 17844@item irr 17845interleaved rows (right eye has top row, left eye starts on next row) 17846 17847@item icl 17848interleaved columns, left eye first 17849 17850@item icr 17851interleaved columns, right eye first 17852 17853Default value is @samp{sbsl}. 17854@end table 17855 17856@item out 17857Set stereoscopic image format of output. 17858 17859@table @samp 17860@item sbsl 17861side by side parallel (left eye left, right eye right) 17862 17863@item sbsr 17864side by side crosseye (right eye left, left eye right) 17865 17866@item sbs2l 17867side by side parallel with half width resolution 17868(left eye left, right eye right) 17869 17870@item sbs2r 17871side by side crosseye with half width resolution 17872(right eye left, left eye right) 17873 17874@item abl 17875@item tbl 17876above-below (left eye above, right eye below) 17877 17878@item abr 17879@item tbr 17880above-below (right eye above, left eye below) 17881 17882@item ab2l 17883@item tb2l 17884above-below with half height resolution 17885(left eye above, right eye below) 17886 17887@item ab2r 17888@item tb2r 17889above-below with half height resolution 17890(right eye above, left eye below) 17891 17892@item al 17893alternating frames (left eye first, right eye second) 17894 17895@item ar 17896alternating frames (right eye first, left eye second) 17897 17898@item irl 17899interleaved rows (left eye has top row, right eye starts on next row) 17900 17901@item irr 17902interleaved rows (right eye has top row, left eye starts on next row) 17903 17904@item arbg 17905anaglyph red/blue gray 17906(red filter on left eye, blue filter on right eye) 17907 17908@item argg 17909anaglyph red/green gray 17910(red filter on left eye, green filter on right eye) 17911 17912@item arcg 17913anaglyph red/cyan gray 17914(red filter on left eye, cyan filter on right eye) 17915 17916@item arch 17917anaglyph red/cyan half colored 17918(red filter on left eye, cyan filter on right eye) 17919 17920@item arcc 17921anaglyph red/cyan color 17922(red filter on left eye, cyan filter on right eye) 17923 17924@item arcd 17925anaglyph red/cyan color optimized with the least squares projection of dubois 17926(red filter on left eye, cyan filter on right eye) 17927 17928@item agmg 17929anaglyph green/magenta gray 17930(green filter on left eye, magenta filter on right eye) 17931 17932@item agmh 17933anaglyph green/magenta half colored 17934(green filter on left eye, magenta filter on right eye) 17935 17936@item agmc 17937anaglyph green/magenta colored 17938(green filter on left eye, magenta filter on right eye) 17939 17940@item agmd 17941anaglyph green/magenta color optimized with the least squares projection of dubois 17942(green filter on left eye, magenta filter on right eye) 17943 17944@item aybg 17945anaglyph yellow/blue gray 17946(yellow filter on left eye, blue filter on right eye) 17947 17948@item aybh 17949anaglyph yellow/blue half colored 17950(yellow filter on left eye, blue filter on right eye) 17951 17952@item aybc 17953anaglyph yellow/blue colored 17954(yellow filter on left eye, blue filter on right eye) 17955 17956@item aybd 17957anaglyph yellow/blue color optimized with the least squares projection of dubois 17958(yellow filter on left eye, blue filter on right eye) 17959 17960@item ml 17961mono output (left eye only) 17962 17963@item mr 17964mono output (right eye only) 17965 17966@item chl 17967checkerboard, left eye first 17968 17969@item chr 17970checkerboard, right eye first 17971 17972@item icl 17973interleaved columns, left eye first 17974 17975@item icr 17976interleaved columns, right eye first 17977 17978@item hdmi 17979HDMI frame pack 17980@end table 17981 17982Default value is @samp{arcd}. 17983@end table 17984 17985@subsection Examples 17986 17987@itemize 17988@item 17989Convert input video from side by side parallel to anaglyph yellow/blue dubois: 17990@example 17991stereo3d=sbsl:aybd 17992@end example 17993 17994@item 17995Convert input video from above below (left eye above, right eye below) to side by side crosseye. 17996@example 17997stereo3d=abl:sbsr 17998@end example 17999@end itemize 18000 18001@section streamselect, astreamselect 18002Select video or audio streams. 18003 18004The filter accepts the following options: 18005 18006@table @option 18007@item inputs 18008Set number of inputs. Default is 2. 18009 18010@item map 18011Set input indexes to remap to outputs. 18012@end table 18013 18014@subsection Commands 18015 18016The @code{streamselect} and @code{astreamselect} filter supports the following 18017commands: 18018 18019@table @option 18020@item map 18021Set input indexes to remap to outputs. 18022@end table 18023 18024@subsection Examples 18025 18026@itemize 18027@item 18028Select first 5 seconds 1st stream and rest of time 2nd stream: 18029@example 18030sendcmd='5.0 streamselect map 1',streamselect=inputs=2:map=0 18031@end example 18032 18033@item 18034Same as above, but for audio: 18035@example 18036asendcmd='5.0 astreamselect map 1',astreamselect=inputs=2:map=0 18037@end example 18038@end itemize 18039 18040@anchor{subtitles} 18041@section subtitles 18042 18043Draw subtitles on top of input video using the libass library. 18044 18045To enable compilation of this filter you need to configure FFmpeg with 18046@code{--enable-libass}. This filter also requires a build with libavcodec and 18047libavformat to convert the passed subtitles file to ASS (Advanced Substation 18048Alpha) subtitles format. 18049 18050The filter accepts the following options: 18051 18052@table @option 18053@item filename, f 18054Set the filename of the subtitle file to read. It must be specified. 18055 18056@item original_size 18057Specify the size of the original video, the video for which the ASS file 18058was composed. For the syntax of this option, check the 18059@ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}. 18060Due to a misdesign in ASS aspect ratio arithmetic, this is necessary to 18061correctly scale the fonts if the aspect ratio has been changed. 18062 18063@item fontsdir 18064Set a directory path containing fonts that can be used by the filter. 18065These fonts will be used in addition to whatever the font provider uses. 18066 18067@item alpha 18068Process alpha channel, by default alpha channel is untouched. 18069 18070@item charenc 18071Set subtitles input character encoding. @code{subtitles} filter only. Only 18072useful if not UTF-8. 18073 18074@item stream_index, si 18075Set subtitles stream index. @code{subtitles} filter only. 18076 18077@item force_style 18078Override default style or script info parameters of the subtitles. It accepts a 18079string containing ASS style format @code{KEY=VALUE} couples separated by ",". 18080@end table 18081 18082If the first key is not specified, it is assumed that the first value 18083specifies the @option{filename}. 18084 18085For example, to render the file @file{sub.srt} on top of the input 18086video, use the command: 18087@example 18088subtitles=sub.srt 18089@end example 18090 18091which is equivalent to: 18092@example 18093subtitles=filename=sub.srt 18094@end example 18095 18096To render the default subtitles stream from file @file{video.mkv}, use: 18097@example 18098subtitles=video.mkv 18099@end example 18100 18101To render the second subtitles stream from that file, use: 18102@example 18103subtitles=video.mkv:si=1 18104@end example 18105 18106To make the subtitles stream from @file{sub.srt} appear in 80% transparent blue 18107@code{DejaVu Serif}, use: 18108@example 18109subtitles=sub.srt:force_style='Fontname=DejaVu Serif,PrimaryColour=&HCCFF0000' 18110@end example 18111 18112@section super2xsai 18113 18114Scale the input by 2x and smooth using the Super2xSaI (Scale and 18115Interpolate) pixel art scaling algorithm. 18116 18117Useful for enlarging pixel art images without reducing sharpness. 18118 18119@section swaprect 18120 18121Swap two rectangular objects in video. 18122 18123This filter accepts the following options: 18124 18125@table @option 18126@item w 18127Set object width. 18128 18129@item h 18130Set object height. 18131 18132@item x1 18133Set 1st rect x coordinate. 18134 18135@item y1 18136Set 1st rect y coordinate. 18137 18138@item x2 18139Set 2nd rect x coordinate. 18140 18141@item y2 18142Set 2nd rect y coordinate. 18143 18144All expressions are evaluated once for each frame. 18145@end table 18146 18147The all options are expressions containing the following constants: 18148 18149@table @option 18150@item w 18151@item h 18152The input width and height. 18153 18154@item a 18155same as @var{w} / @var{h} 18156 18157@item sar 18158input sample aspect ratio 18159 18160@item dar 18161input display aspect ratio, it is the same as (@var{w} / @var{h}) * @var{sar} 18162 18163@item n 18164The number of the input frame, starting from 0. 18165 18166@item t 18167The timestamp expressed in seconds. It's NAN if the input timestamp is unknown. 18168 18169@item pos 18170the position in the file of the input frame, NAN if unknown 18171@end table 18172 18173@section swapuv 18174Swap U & V plane. 18175 18176@section tblend 18177Blend successive video frames. 18178 18179See @ref{blend} 18180 18181@section telecine 18182 18183Apply telecine process to the video. 18184 18185This filter accepts the following options: 18186 18187@table @option 18188@item first_field 18189@table @samp 18190@item top, t 18191top field first 18192@item bottom, b 18193bottom field first 18194The default value is @code{top}. 18195@end table 18196 18197@item pattern 18198A string of numbers representing the pulldown pattern you wish to apply. 18199The default value is @code{23}. 18200@end table 18201 18202@example 18203Some typical patterns: 18204 18205NTSC output (30i): 1820627.5p: 32222 1820724p: 23 (classic) 1820824p: 2332 (preferred) 1820920p: 33 1821018p: 334 1821116p: 3444 18212 18213PAL output (25i): 1821427.5p: 12222 1821524p: 222222222223 ("Euro pulldown") 1821616.67p: 33 1821716p: 33333334 18218@end example 18219 18220@section thistogram 18221 18222Compute and draw a color distribution histogram for the input video across time. 18223 18224Unlike @ref{histogram} video filter which only shows histogram of single input frame 18225at certain time, this filter shows also past histograms of number of frames defined 18226by @code{width} option. 18227 18228The computed histogram is a representation of the color component 18229distribution in an image. 18230 18231The filter accepts the following options: 18232 18233@table @option 18234@item width, w 18235Set width of single color component output. Default value is @code{0}. 18236Value of @code{0} means width will be picked from input video. 18237This also set number of passed histograms to keep. 18238Allowed range is [0, 8192]. 18239 18240@item display_mode, d 18241Set display mode. 18242It accepts the following values: 18243@table @samp 18244@item stack 18245Per color component graphs are placed below each other. 18246 18247@item parade 18248Per color component graphs are placed side by side. 18249 18250@item overlay 18251Presents information identical to that in the @code{parade}, except 18252that the graphs representing color components are superimposed directly 18253over one another. 18254@end table 18255Default is @code{stack}. 18256 18257@item levels_mode, m 18258Set mode. Can be either @code{linear}, or @code{logarithmic}. 18259Default is @code{linear}. 18260 18261@item components, c 18262Set what color components to display. 18263Default is @code{7}. 18264 18265@item bgopacity, b 18266Set background opacity. Default is @code{0.9}. 18267 18268@item envelope, e 18269Show envelope. Default is disabled. 18270 18271@item ecolor, ec 18272Set envelope color. Default is @code{gold}. 18273 18274@item slide 18275Set slide mode. 18276 18277Available values for slide is: 18278@table @samp 18279@item frame 18280Draw new frame when right border is reached. 18281 18282@item replace 18283Replace old columns with new ones. 18284 18285@item scroll 18286Scroll from right to left. 18287 18288@item rscroll 18289Scroll from left to right. 18290 18291@item picture 18292Draw single picture. 18293@end table 18294 18295Default is @code{replace}. 18296@end table 18297 18298@section threshold 18299 18300Apply threshold effect to video stream. 18301 18302This filter needs four video streams to perform thresholding. 18303First stream is stream we are filtering. 18304Second stream is holding threshold values, third stream is holding min values, 18305and last, fourth stream is holding max values. 18306 18307The filter accepts the following option: 18308 18309@table @option 18310@item planes 18311Set which planes will be processed, unprocessed planes will be copied. 18312By default value 0xf, all planes will be processed. 18313@end table 18314 18315For example if first stream pixel's component value is less then threshold value 18316of pixel component from 2nd threshold stream, third stream value will picked, 18317otherwise fourth stream pixel component value will be picked. 18318 18319Using color source filter one can perform various types of thresholding: 18320 18321@subsection Examples 18322 18323@itemize 18324@item 18325Binary threshold, using gray color as threshold: 18326@example 18327ffmpeg -i 320x240.avi -f lavfi -i color=gray -f lavfi -i color=black -f lavfi -i color=white -lavfi threshold output.avi 18328@end example 18329 18330@item 18331Inverted binary threshold, using gray color as threshold: 18332@example 18333ffmpeg -i 320x240.avi -f lavfi -i color=gray -f lavfi -i color=white -f lavfi -i color=black -lavfi threshold output.avi 18334@end example 18335 18336@item 18337Truncate binary threshold, using gray color as threshold: 18338@example 18339ffmpeg -i 320x240.avi -f lavfi -i color=gray -i 320x240.avi -f lavfi -i color=gray -lavfi threshold output.avi 18340@end example 18341 18342@item 18343Threshold to zero, using gray color as threshold: 18344@example 18345ffmpeg -i 320x240.avi -f lavfi -i color=gray -f lavfi -i color=white -i 320x240.avi -lavfi threshold output.avi 18346@end example 18347 18348@item 18349Inverted threshold to zero, using gray color as threshold: 18350@example 18351ffmpeg -i 320x240.avi -f lavfi -i color=gray -i 320x240.avi -f lavfi -i color=white -lavfi threshold output.avi 18352@end example 18353@end itemize 18354 18355@section thumbnail 18356Select the most representative frame in a given sequence of consecutive frames. 18357 18358The filter accepts the following options: 18359 18360@table @option 18361@item n 18362Set the frames batch size to analyze; in a set of @var{n} frames, the filter 18363will pick one of them, and then handle the next batch of @var{n} frames until 18364the end. Default is @code{100}. 18365@end table 18366 18367Since the filter keeps track of the whole frames sequence, a bigger @var{n} 18368value will result in a higher memory usage, so a high value is not recommended. 18369 18370@subsection Examples 18371 18372@itemize 18373@item 18374Extract one picture each 50 frames: 18375@example 18376thumbnail=50 18377@end example 18378 18379@item 18380Complete example of a thumbnail creation with @command{ffmpeg}: 18381@example 18382ffmpeg -i in.avi -vf thumbnail,scale=300:200 -frames:v 1 out.png 18383@end example 18384@end itemize 18385 18386@anchor{tile} 18387@section tile 18388 18389Tile several successive frames together. 18390 18391The @ref{untile} filter can do the reverse. 18392 18393The filter accepts the following options: 18394 18395@table @option 18396 18397@item layout 18398Set the grid size (i.e. the number of lines and columns). For the syntax of 18399this option, check the 18400@ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}. 18401 18402@item nb_frames 18403Set the maximum number of frames to render in the given area. It must be less 18404than or equal to @var{w}x@var{h}. The default value is @code{0}, meaning all 18405the area will be used. 18406 18407@item margin 18408Set the outer border margin in pixels. 18409 18410@item padding 18411Set the inner border thickness (i.e. the number of pixels between frames). For 18412more advanced padding options (such as having different values for the edges), 18413refer to the pad video filter. 18414 18415@item color 18416Specify the color of the unused area. For the syntax of this option, check the 18417@ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}. 18418The default value of @var{color} is "black". 18419 18420@item overlap 18421Set the number of frames to overlap when tiling several successive frames together. 18422The value must be between @code{0} and @var{nb_frames - 1}. 18423 18424@item init_padding 18425Set the number of frames to initially be empty before displaying first output frame. 18426This controls how soon will one get first output frame. 18427The value must be between @code{0} and @var{nb_frames - 1}. 18428@end table 18429 18430@subsection Examples 18431 18432@itemize 18433@item 18434Produce 8x8 PNG tiles of all keyframes (@option{-skip_frame nokey}) in a movie: 18435@example 18436ffmpeg -skip_frame nokey -i file.avi -vf 'scale=128:72,tile=8x8' -an -vsync 0 keyframes%03d.png 18437@end example 18438The @option{-vsync 0} is necessary to prevent @command{ffmpeg} from 18439duplicating each output frame to accommodate the originally detected frame 18440rate. 18441 18442@item 18443Display @code{5} pictures in an area of @code{3x2} frames, 18444with @code{7} pixels between them, and @code{2} pixels of initial margin, using 18445mixed flat and named options: 18446@example 18447tile=3x2:nb_frames=5:padding=7:margin=2 18448@end example 18449@end itemize 18450 18451@section tinterlace 18452 18453Perform various types of temporal field interlacing. 18454 18455Frames are counted starting from 1, so the first input frame is 18456considered odd. 18457 18458The filter accepts the following options: 18459 18460@table @option 18461 18462@item mode 18463Specify the mode of the interlacing. This option can also be specified 18464as a value alone. See below for a list of values for this option. 18465 18466Available values are: 18467 18468@table @samp 18469@item merge, 0 18470Move odd frames into the upper field, even into the lower field, 18471generating a double height frame at half frame rate. 18472@example 18473 ------> time 18474Input: 18475Frame 1 Frame 2 Frame 3 Frame 4 18476 1847711111 22222 33333 44444 1847811111 22222 33333 44444 1847911111 22222 33333 44444 1848011111 22222 33333 44444 18481 18482Output: 1848311111 33333 1848422222 44444 1848511111 33333 1848622222 44444 1848711111 33333 1848822222 44444 1848911111 33333 1849022222 44444 18491@end example 18492 18493@item drop_even, 1 18494Only output odd frames, even frames are dropped, generating a frame with 18495unchanged height at half frame rate. 18496 18497@example 18498 ------> time 18499Input: 18500Frame 1 Frame 2 Frame 3 Frame 4 18501 1850211111 22222 33333 44444 1850311111 22222 33333 44444 1850411111 22222 33333 44444 1850511111 22222 33333 44444 18506 18507Output: 1850811111 33333 1850911111 33333 1851011111 33333 1851111111 33333 18512@end example 18513 18514@item drop_odd, 2 18515Only output even frames, odd frames are dropped, generating a frame with 18516unchanged height at half frame rate. 18517 18518@example 18519 ------> time 18520Input: 18521Frame 1 Frame 2 Frame 3 Frame 4 18522 1852311111 22222 33333 44444 1852411111 22222 33333 44444 1852511111 22222 33333 44444 1852611111 22222 33333 44444 18527 18528Output: 18529 22222 44444 18530 22222 44444 18531 22222 44444 18532 22222 44444 18533@end example 18534 18535@item pad, 3 18536Expand each frame to full height, but pad alternate lines with black, 18537generating a frame with double height at the same input frame rate. 18538 18539@example 18540 ------> time 18541Input: 18542Frame 1 Frame 2 Frame 3 Frame 4 18543 1854411111 22222 33333 44444 1854511111 22222 33333 44444 1854611111 22222 33333 44444 1854711111 22222 33333 44444 18548 18549Output: 1855011111 ..... 33333 ..... 18551..... 22222 ..... 44444 1855211111 ..... 33333 ..... 18553..... 22222 ..... 44444 1855411111 ..... 33333 ..... 18555..... 22222 ..... 44444 1855611111 ..... 33333 ..... 18557..... 22222 ..... 44444 18558@end example 18559 18560 18561@item interleave_top, 4 18562Interleave the upper field from odd frames with the lower field from 18563even frames, generating a frame with unchanged height at half frame rate. 18564 18565@example 18566 ------> time 18567Input: 18568Frame 1 Frame 2 Frame 3 Frame 4 18569 1857011111<- 22222 33333<- 44444 1857111111 22222<- 33333 44444<- 1857211111<- 22222 33333<- 44444 1857311111 22222<- 33333 44444<- 18574 18575Output: 1857611111 33333 1857722222 44444 1857811111 33333 1857922222 44444 18580@end example 18581 18582 18583@item interleave_bottom, 5 18584Interleave the lower field from odd frames with the upper field from 18585even frames, generating a frame with unchanged height at half frame rate. 18586 18587@example 18588 ------> time 18589Input: 18590Frame 1 Frame 2 Frame 3 Frame 4 18591 1859211111 22222<- 33333 44444<- 1859311111<- 22222 33333<- 44444 1859411111 22222<- 33333 44444<- 1859511111<- 22222 33333<- 44444 18596 18597Output: 1859822222 44444 1859911111 33333 1860022222 44444 1860111111 33333 18602@end example 18603 18604 18605@item interlacex2, 6 18606Double frame rate with unchanged height. Frames are inserted each 18607containing the second temporal field from the previous input frame and 18608the first temporal field from the next input frame. This mode relies on 18609the top_field_first flag. Useful for interlaced video displays with no 18610field synchronisation. 18611 18612@example 18613 ------> time 18614Input: 18615Frame 1 Frame 2 Frame 3 Frame 4 18616 1861711111 22222 33333 44444 18618 11111 22222 33333 44444 1861911111 22222 33333 44444 18620 11111 22222 33333 44444 18621 18622Output: 1862311111 22222 22222 33333 33333 44444 44444 18624 11111 11111 22222 22222 33333 33333 44444 1862511111 22222 22222 33333 33333 44444 44444 18626 11111 11111 22222 22222 33333 33333 44444 18627@end example 18628 18629 18630@item mergex2, 7 18631Move odd frames into the upper field, even into the lower field, 18632generating a double height frame at same frame rate. 18633 18634@example 18635 ------> time 18636Input: 18637Frame 1 Frame 2 Frame 3 Frame 4 18638 1863911111 22222 33333 44444 1864011111 22222 33333 44444 1864111111 22222 33333 44444 1864211111 22222 33333 44444 18643 18644Output: 1864511111 33333 33333 55555 1864622222 22222 44444 44444 1864711111 33333 33333 55555 1864822222 22222 44444 44444 1864911111 33333 33333 55555 1865022222 22222 44444 44444 1865111111 33333 33333 55555 1865222222 22222 44444 44444 18653@end example 18654 18655@end table 18656 18657Numeric values are deprecated but are accepted for backward 18658compatibility reasons. 18659 18660Default mode is @code{merge}. 18661 18662@item flags 18663Specify flags influencing the filter process. 18664 18665Available value for @var{flags} is: 18666 18667@table @option 18668@item low_pass_filter, vlpf 18669Enable linear vertical low-pass filtering in the filter. 18670Vertical low-pass filtering is required when creating an interlaced 18671destination from a progressive source which contains high-frequency 18672vertical detail. Filtering will reduce interlace 'twitter' and Moire 18673patterning. 18674 18675@item complex_filter, cvlpf 18676Enable complex vertical low-pass filtering. 18677This will slightly less reduce interlace 'twitter' and Moire 18678patterning but better retain detail and subjective sharpness impression. 18679 18680@item bypass_il 18681Bypass already interlaced frames, only adjust the frame rate. 18682@end table 18683 18684Vertical low-pass filtering and bypassing already interlaced frames can only be 18685enabled for @option{mode} @var{interleave_top} and @var{interleave_bottom}. 18686 18687@end table 18688 18689@section tmedian 18690Pick median pixels from several successive input video frames. 18691 18692The filter accepts the following options: 18693 18694@table @option 18695@item radius 18696Set radius of median filter. 18697Default is 1. Allowed range is from 1 to 127. 18698 18699@item planes 18700Set which planes to filter. Default value is @code{15}, by which all planes are processed. 18701 18702@item percentile 18703Set median percentile. Default value is @code{0.5}. 18704Default value of @code{0.5} will pick always median values, while @code{0} will pick 18705minimum values, and @code{1} maximum values. 18706@end table 18707 18708@section tmix 18709 18710Mix successive video frames. 18711 18712A description of the accepted options follows. 18713 18714@table @option 18715@item frames 18716The number of successive frames to mix. If unspecified, it defaults to 3. 18717 18718@item weights 18719Specify weight of each input video frame. 18720Each weight is separated by space. If number of weights is smaller than 18721number of @var{frames} last specified weight will be used for all remaining 18722unset weights. 18723 18724@item scale 18725Specify scale, if it is set it will be multiplied with sum 18726of each weight multiplied with pixel values to give final destination 18727pixel value. By default @var{scale} is auto scaled to sum of weights. 18728@end table 18729 18730@subsection Examples 18731 18732@itemize 18733@item 18734Average 7 successive frames: 18735@example 18736tmix=frames=7:weights="1 1 1 1 1 1 1" 18737@end example 18738 18739@item 18740Apply simple temporal convolution: 18741@example 18742tmix=frames=3:weights="-1 3 -1" 18743@end example 18744 18745@item 18746Similar as above but only showing temporal differences: 18747@example 18748tmix=frames=3:weights="-1 2 -1":scale=1 18749@end example 18750@end itemize 18751 18752@anchor{tonemap} 18753@section tonemap 18754Tone map colors from different dynamic ranges. 18755 18756This filter expects data in single precision floating point, as it needs to 18757operate on (and can output) out-of-range values. Another filter, such as 18758@ref{zscale}, is needed to convert the resulting frame to a usable format. 18759 18760The tonemapping algorithms implemented only work on linear light, so input 18761data should be linearized beforehand (and possibly correctly tagged). 18762 18763@example 18764ffmpeg -i INPUT -vf zscale=transfer=linear,tonemap=clip,zscale=transfer=bt709,format=yuv420p OUTPUT 18765@end example 18766 18767@subsection Options 18768The filter accepts the following options. 18769 18770@table @option 18771@item tonemap 18772Set the tone map algorithm to use. 18773 18774Possible values are: 18775@table @var 18776@item none 18777Do not apply any tone map, only desaturate overbright pixels. 18778 18779@item clip 18780Hard-clip any out-of-range values. Use it for perfect color accuracy for 18781in-range values, while distorting out-of-range values. 18782 18783@item linear 18784Stretch the entire reference gamut to a linear multiple of the display. 18785 18786@item gamma 18787Fit a logarithmic transfer between the tone curves. 18788 18789@item reinhard 18790Preserve overall image brightness with a simple curve, using nonlinear 18791contrast, which results in flattening details and degrading color accuracy. 18792 18793@item hable 18794Preserve both dark and bright details better than @var{reinhard}, at the cost 18795of slightly darkening everything. Use it when detail preservation is more 18796important than color and brightness accuracy. 18797 18798@item mobius 18799Smoothly map out-of-range values, while retaining contrast and colors for 18800in-range material as much as possible. Use it when color accuracy is more 18801important than detail preservation. 18802@end table 18803 18804Default is none. 18805 18806@item param 18807Tune the tone mapping algorithm. 18808 18809This affects the following algorithms: 18810@table @var 18811@item none 18812Ignored. 18813 18814@item linear 18815Specifies the scale factor to use while stretching. 18816Default to 1.0. 18817 18818@item gamma 18819Specifies the exponent of the function. 18820Default to 1.8. 18821 18822@item clip 18823Specify an extra linear coefficient to multiply into the signal before clipping. 18824Default to 1.0. 18825 18826@item reinhard 18827Specify the local contrast coefficient at the display peak. 18828Default to 0.5, which means that in-gamut values will be about half as bright 18829as when clipping. 18830 18831@item hable 18832Ignored. 18833 18834@item mobius 18835Specify the transition point from linear to mobius transform. Every value 18836below this point is guaranteed to be mapped 1:1. The higher the value, the 18837more accurate the result will be, at the cost of losing bright details. 18838Default to 0.3, which due to the steep initial slope still preserves in-range 18839colors fairly accurately. 18840@end table 18841 18842@item desat 18843Apply desaturation for highlights that exceed this level of brightness. The 18844higher the parameter, the more color information will be preserved. This 18845setting helps prevent unnaturally blown-out colors for super-highlights, by 18846(smoothly) turning into white instead. This makes images feel more natural, 18847at the cost of reducing information about out-of-range colors. 18848 18849The default of 2.0 is somewhat conservative and will mostly just apply to 18850skies or directly sunlit surfaces. A setting of 0.0 disables this option. 18851 18852This option works only if the input frame has a supported color tag. 18853 18854@item peak 18855Override signal/nominal/reference peak with this value. Useful when the 18856embedded peak information in display metadata is not reliable or when tone 18857mapping from a lower range to a higher range. 18858@end table 18859 18860@section tpad 18861 18862Temporarily pad video frames. 18863 18864The filter accepts the following options: 18865 18866@table @option 18867@item start 18868Specify number of delay frames before input video stream. Default is 0. 18869 18870@item stop 18871Specify number of padding frames after input video stream. 18872Set to -1 to pad indefinitely. Default is 0. 18873 18874@item start_mode 18875Set kind of frames added to beginning of stream. 18876Can be either @var{add} or @var{clone}. 18877With @var{add} frames of solid-color are added. 18878With @var{clone} frames are clones of first frame. 18879Default is @var{add}. 18880 18881@item stop_mode 18882Set kind of frames added to end of stream. 18883Can be either @var{add} or @var{clone}. 18884With @var{add} frames of solid-color are added. 18885With @var{clone} frames are clones of last frame. 18886Default is @var{add}. 18887 18888@item start_duration, stop_duration 18889Specify the duration of the start/stop delay. See 18890@ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils} 18891for the accepted syntax. 18892These options override @var{start} and @var{stop}. Default is 0. 18893 18894@item color 18895Specify the color of the padded area. For the syntax of this option, 18896check the @ref{color syntax,,"Color" section in the ffmpeg-utils 18897manual,ffmpeg-utils}. 18898 18899The default value of @var{color} is "black". 18900@end table 18901 18902@anchor{transpose} 18903@section transpose 18904 18905Transpose rows with columns in the input video and optionally flip it. 18906 18907It accepts the following parameters: 18908 18909@table @option 18910 18911@item dir 18912Specify the transposition direction. 18913 18914Can assume the following values: 18915@table @samp 18916@item 0, 4, cclock_flip 18917Rotate by 90 degrees counterclockwise and vertically flip (default), that is: 18918@example 18919L.R L.l 18920. . -> . . 18921l.r R.r 18922@end example 18923 18924@item 1, 5, clock 18925Rotate by 90 degrees clockwise, that is: 18926@example 18927L.R l.L 18928. . -> . . 18929l.r r.R 18930@end example 18931 18932@item 2, 6, cclock 18933Rotate by 90 degrees counterclockwise, that is: 18934@example 18935L.R R.r 18936. . -> . . 18937l.r L.l 18938@end example 18939 18940@item 3, 7, clock_flip 18941Rotate by 90 degrees clockwise and vertically flip, that is: 18942@example 18943L.R r.R 18944. . -> . . 18945l.r l.L 18946@end example 18947@end table 18948 18949For values between 4-7, the transposition is only done if the input 18950video geometry is portrait and not landscape. These values are 18951deprecated, the @code{passthrough} option should be used instead. 18952 18953Numerical values are deprecated, and should be dropped in favor of 18954symbolic constants. 18955 18956@item passthrough 18957Do not apply the transposition if the input geometry matches the one 18958specified by the specified value. It accepts the following values: 18959@table @samp 18960@item none 18961Always apply transposition. 18962@item portrait 18963Preserve portrait geometry (when @var{height} >= @var{width}). 18964@item landscape 18965Preserve landscape geometry (when @var{width} >= @var{height}). 18966@end table 18967 18968Default value is @code{none}. 18969@end table 18970 18971For example to rotate by 90 degrees clockwise and preserve portrait 18972layout: 18973@example 18974transpose=dir=1:passthrough=portrait 18975@end example 18976 18977The command above can also be specified as: 18978@example 18979transpose=1:portrait 18980@end example 18981 18982@section transpose_npp 18983 18984Transpose rows with columns in the input video and optionally flip it. 18985For more in depth examples see the @ref{transpose} video filter, which shares mostly the same options. 18986 18987It accepts the following parameters: 18988 18989@table @option 18990 18991@item dir 18992Specify the transposition direction. 18993 18994Can assume the following values: 18995@table @samp 18996@item cclock_flip 18997Rotate by 90 degrees counterclockwise and vertically flip. (default) 18998 18999@item clock 19000Rotate by 90 degrees clockwise. 19001 19002@item cclock 19003Rotate by 90 degrees counterclockwise. 19004 19005@item clock_flip 19006Rotate by 90 degrees clockwise and vertically flip. 19007@end table 19008 19009@item passthrough 19010Do not apply the transposition if the input geometry matches the one 19011specified by the specified value. It accepts the following values: 19012@table @samp 19013@item none 19014Always apply transposition. (default) 19015@item portrait 19016Preserve portrait geometry (when @var{height} >= @var{width}). 19017@item landscape 19018Preserve landscape geometry (when @var{width} >= @var{height}). 19019@end table 19020 19021@end table 19022 19023@section trim 19024Trim the input so that the output contains one continuous subpart of the input. 19025 19026It accepts the following parameters: 19027@table @option 19028@item start 19029Specify the time of the start of the kept section, i.e. the frame with the 19030timestamp @var{start} will be the first frame in the output. 19031 19032@item end 19033Specify the time of the first frame that will be dropped, i.e. the frame 19034immediately preceding the one with the timestamp @var{end} will be the last 19035frame in the output. 19036 19037@item start_pts 19038This is the same as @var{start}, except this option sets the start timestamp 19039in timebase units instead of seconds. 19040 19041@item end_pts 19042This is the same as @var{end}, except this option sets the end timestamp 19043in timebase units instead of seconds. 19044 19045@item duration 19046The maximum duration of the output in seconds. 19047 19048@item start_frame 19049The number of the first frame that should be passed to the output. 19050 19051@item end_frame 19052The number of the first frame that should be dropped. 19053@end table 19054 19055@option{start}, @option{end}, and @option{duration} are expressed as time 19056duration specifications; see 19057@ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils} 19058for the accepted syntax. 19059 19060Note that the first two sets of the start/end options and the @option{duration} 19061option look at the frame timestamp, while the _frame variants simply count the 19062frames that pass through the filter. Also note that this filter does not modify 19063the timestamps. If you wish for the output timestamps to start at zero, insert a 19064setpts filter after the trim filter. 19065 19066If multiple start or end options are set, this filter tries to be greedy and 19067keep all the frames that match at least one of the specified constraints. To keep 19068only the part that matches all the constraints at once, chain multiple trim 19069filters. 19070 19071The defaults are such that all the input is kept. So it is possible to set e.g. 19072just the end values to keep everything before the specified time. 19073 19074Examples: 19075@itemize 19076@item 19077Drop everything except the second minute of input: 19078@example 19079ffmpeg -i INPUT -vf trim=60:120 19080@end example 19081 19082@item 19083Keep only the first second: 19084@example 19085ffmpeg -i INPUT -vf trim=duration=1 19086@end example 19087 19088@end itemize 19089 19090@section unpremultiply 19091Apply alpha unpremultiply effect to input video stream using first plane 19092of second stream as alpha. 19093 19094Both streams must have same dimensions and same pixel format. 19095 19096The filter accepts the following option: 19097 19098@table @option 19099@item planes 19100Set which planes will be processed, unprocessed planes will be copied. 19101By default value 0xf, all planes will be processed. 19102 19103If the format has 1 or 2 components, then luma is bit 0. 19104If the format has 3 or 4 components: 19105for RGB formats bit 0 is green, bit 1 is blue and bit 2 is red; 19106for YUV formats bit 0 is luma, bit 1 is chroma-U and bit 2 is chroma-V. 19107If present, the alpha channel is always the last bit. 19108 19109@item inplace 19110Do not require 2nd input for processing, instead use alpha plane from input stream. 19111@end table 19112 19113@anchor{unsharp} 19114@section unsharp 19115 19116Sharpen or blur the input video. 19117 19118It accepts the following parameters: 19119 19120@table @option 19121@item luma_msize_x, lx 19122Set the luma matrix horizontal size. It must be an odd integer between 191233 and 23. The default value is 5. 19124 19125@item luma_msize_y, ly 19126Set the luma matrix vertical size. It must be an odd integer between 3 19127and 23. The default value is 5. 19128 19129@item luma_amount, la 19130Set the luma effect strength. It must be a floating point number, reasonable 19131values lay between -1.5 and 1.5. 19132 19133Negative values will blur the input video, while positive values will 19134sharpen it, a value of zero will disable the effect. 19135 19136Default value is 1.0. 19137 19138@item chroma_msize_x, cx 19139Set the chroma matrix horizontal size. It must be an odd integer 19140between 3 and 23. The default value is 5. 19141 19142@item chroma_msize_y, cy 19143Set the chroma matrix vertical size. It must be an odd integer 19144between 3 and 23. The default value is 5. 19145 19146@item chroma_amount, ca 19147Set the chroma effect strength. It must be a floating point number, reasonable 19148values lay between -1.5 and 1.5. 19149 19150Negative values will blur the input video, while positive values will 19151sharpen it, a value of zero will disable the effect. 19152 19153Default value is 0.0. 19154 19155@end table 19156 19157All parameters are optional and default to the equivalent of the 19158string '5:5:1.0:5:5:0.0'. 19159 19160@subsection Examples 19161 19162@itemize 19163@item 19164Apply strong luma sharpen effect: 19165@example 19166unsharp=luma_msize_x=7:luma_msize_y=7:luma_amount=2.5 19167@end example 19168 19169@item 19170Apply a strong blur of both luma and chroma parameters: 19171@example 19172unsharp=7:7:-2:7:7:-2 19173@end example 19174@end itemize 19175 19176@anchor{untile} 19177@section untile 19178 19179Decompose a video made of tiled images into the individual images. 19180 19181The frame rate of the output video is the frame rate of the input video 19182multiplied by the number of tiles. 19183 19184This filter does the reverse of @ref{tile}. 19185 19186The filter accepts the following options: 19187 19188@table @option 19189 19190@item layout 19191Set the grid size (i.e. the number of lines and columns). For the syntax of 19192this option, check the 19193@ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}. 19194@end table 19195 19196@subsection Examples 19197 19198@itemize 19199@item 19200Produce a 1-second video from a still image file made of 25 frames stacked 19201vertically, like an analogic film reel: 19202@example 19203ffmpeg -r 1 -i image.jpg -vf untile=1x25 movie.mkv 19204@end example 19205@end itemize 19206 19207@section uspp 19208 19209Apply ultra slow/simple postprocessing filter that compresses and decompresses 19210the image at several (or - in the case of @option{quality} level @code{8} - all) 19211shifts and average the results. 19212 19213The way this differs from the behavior of spp is that uspp actually encodes & 19214decodes each case with libavcodec Snow, whereas spp uses a simplified intra only 8x8 19215DCT similar to MJPEG. 19216 19217The filter accepts the following options: 19218 19219@table @option 19220@item quality 19221Set quality. This option defines the number of levels for averaging. It accepts 19222an integer in the range 0-8. If set to @code{0}, the filter will have no 19223effect. A value of @code{8} means the higher quality. For each increment of 19224that value the speed drops by a factor of approximately 2. Default value is 19225@code{3}. 19226 19227@item qp 19228Force a constant quantization parameter. If not set, the filter will use the QP 19229from the video stream (if available). 19230@end table 19231 19232@section v360 19233 19234Convert 360 videos between various formats. 19235 19236The filter accepts the following options: 19237 19238@table @option 19239 19240@item input 19241@item output 19242Set format of the input/output video. 19243 19244Available formats: 19245 19246@table @samp 19247 19248@item e 19249@item equirect 19250Equirectangular projection. 19251 19252@item c3x2 19253@item c6x1 19254@item c1x6 19255Cubemap with 3x2/6x1/1x6 layout. 19256 19257Format specific options: 19258 19259@table @option 19260@item in_pad 19261@item out_pad 19262Set padding proportion for the input/output cubemap. Values in decimals. 19263 19264Example values: 19265@table @samp 19266@item 0 19267No padding. 19268@item 0.01 192691% 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) 19270@end table 19271 19272Default value is @b{@samp{0}}. 19273Maximum value is @b{@samp{0.1}}. 19274 19275@item fin_pad 19276@item fout_pad 19277Set fixed padding for the input/output cubemap. Values in pixels. 19278 19279Default value is @b{@samp{0}}. If greater than zero it overrides other padding options. 19280 19281@item in_forder 19282@item out_forder 19283Set order of faces for the input/output cubemap. Choose one direction for each position. 19284 19285Designation of directions: 19286@table @samp 19287@item r 19288right 19289@item l 19290left 19291@item u 19292up 19293@item d 19294down 19295@item f 19296forward 19297@item b 19298back 19299@end table 19300 19301Default value is @b{@samp{rludfb}}. 19302 19303@item in_frot 19304@item out_frot 19305Set rotation of faces for the input/output cubemap. Choose one angle for each position. 19306 19307Designation of angles: 19308@table @samp 19309@item 0 193100 degrees clockwise 19311@item 1 1931290 degrees clockwise 19313@item 2 19314180 degrees clockwise 19315@item 3 19316270 degrees clockwise 19317@end table 19318 19319Default value is @b{@samp{000000}}. 19320@end table 19321 19322@item eac 19323Equi-Angular Cubemap. 19324 19325@item flat 19326@item gnomonic 19327@item rectilinear 19328Regular video. 19329 19330Format specific options: 19331@table @option 19332@item h_fov 19333@item v_fov 19334@item d_fov 19335Set output horizontal/vertical/diagonal field of view. Values in degrees. 19336 19337If diagonal field of view is set it overrides horizontal and vertical field of view. 19338 19339@item ih_fov 19340@item iv_fov 19341@item id_fov 19342Set input horizontal/vertical/diagonal field of view. Values in degrees. 19343 19344If diagonal field of view is set it overrides horizontal and vertical field of view. 19345@end table 19346 19347@item dfisheye 19348Dual fisheye. 19349 19350Format specific options: 19351@table @option 19352@item h_fov 19353@item v_fov 19354@item d_fov 19355Set output horizontal/vertical/diagonal field of view. Values in degrees. 19356 19357If diagonal field of view is set it overrides horizontal and vertical field of view. 19358 19359@item ih_fov 19360@item iv_fov 19361@item id_fov 19362Set input horizontal/vertical/diagonal field of view. Values in degrees. 19363 19364If diagonal field of view is set it overrides horizontal and vertical field of view. 19365@end table 19366 19367@item barrel 19368@item fb 19369@item barrelsplit 19370Facebook's 360 formats. 19371 19372@item sg 19373Stereographic format. 19374 19375Format specific options: 19376@table @option 19377@item h_fov 19378@item v_fov 19379@item d_fov 19380Set output horizontal/vertical/diagonal field of view. Values in degrees. 19381 19382If diagonal field of view is set it overrides horizontal and vertical field of view. 19383 19384@item ih_fov 19385@item iv_fov 19386@item id_fov 19387Set input horizontal/vertical/diagonal field of view. Values in degrees. 19388 19389If diagonal field of view is set it overrides horizontal and vertical field of view. 19390@end table 19391 19392@item mercator 19393Mercator format. 19394 19395@item ball 19396Ball format, gives significant distortion toward the back. 19397 19398@item hammer 19399Hammer-Aitoff map projection format. 19400 19401@item sinusoidal 19402Sinusoidal map projection format. 19403 19404@item fisheye 19405Fisheye projection. 19406 19407Format specific options: 19408@table @option 19409@item h_fov 19410@item v_fov 19411@item d_fov 19412Set output horizontal/vertical/diagonal field of view. Values in degrees. 19413 19414If diagonal field of view is set it overrides horizontal and vertical field of view. 19415 19416@item ih_fov 19417@item iv_fov 19418@item id_fov 19419Set input horizontal/vertical/diagonal field of view. Values in degrees. 19420 19421If diagonal field of view is set it overrides horizontal and vertical field of view. 19422@end table 19423 19424@item pannini 19425Pannini projection. 19426 19427Format specific options: 19428@table @option 19429@item h_fov 19430Set output pannini parameter. 19431 19432@item ih_fov 19433Set input pannini parameter. 19434@end table 19435 19436@item cylindrical 19437Cylindrical projection. 19438 19439Format specific options: 19440@table @option 19441@item h_fov 19442@item v_fov 19443@item d_fov 19444Set output horizontal/vertical/diagonal field of view. Values in degrees. 19445 19446If diagonal field of view is set it overrides horizontal and vertical field of view. 19447 19448@item ih_fov 19449@item iv_fov 19450@item id_fov 19451Set input horizontal/vertical/diagonal field of view. Values in degrees. 19452 19453If diagonal field of view is set it overrides horizontal and vertical field of view. 19454@end table 19455 19456@item perspective 19457Perspective projection. @i{(output only)} 19458 19459Format specific options: 19460@table @option 19461@item v_fov 19462Set perspective parameter. 19463@end table 19464 19465@item tetrahedron 19466Tetrahedron projection. 19467 19468@item tsp 19469Truncated square pyramid projection. 19470 19471@item he 19472@item hequirect 19473Half equirectangular projection. 19474 19475@item equisolid 19476Equisolid format. 19477 19478Format specific options: 19479@table @option 19480@item h_fov 19481@item v_fov 19482@item d_fov 19483Set output horizontal/vertical/diagonal field of view. Values in degrees. 19484 19485If diagonal field of view is set it overrides horizontal and vertical field of view. 19486 19487@item ih_fov 19488@item iv_fov 19489@item id_fov 19490Set input horizontal/vertical/diagonal field of view. Values in degrees. 19491 19492If diagonal field of view is set it overrides horizontal and vertical field of view. 19493@end table 19494 19495@item og 19496Orthographic format. 19497 19498Format specific options: 19499@table @option 19500@item h_fov 19501@item v_fov 19502@item d_fov 19503Set output horizontal/vertical/diagonal field of view. Values in degrees. 19504 19505If diagonal field of view is set it overrides horizontal and vertical field of view. 19506 19507@item ih_fov 19508@item iv_fov 19509@item id_fov 19510Set input horizontal/vertical/diagonal field of view. Values in degrees. 19511 19512If diagonal field of view is set it overrides horizontal and vertical field of view. 19513@end table 19514 19515@item octahedron 19516Octahedron projection. 19517@end table 19518 19519@item interp 19520Set interpolation method.@* 19521@i{Note: more complex interpolation methods require much more memory to run.} 19522 19523Available methods: 19524 19525@table @samp 19526@item near 19527@item nearest 19528Nearest neighbour. 19529@item line 19530@item linear 19531Bilinear interpolation. 19532@item lagrange9 19533Lagrange9 interpolation. 19534@item cube 19535@item cubic 19536Bicubic interpolation. 19537@item lanc 19538@item lanczos 19539Lanczos interpolation. 19540@item sp16 19541@item spline16 19542Spline16 interpolation. 19543@item gauss 19544@item gaussian 19545Gaussian interpolation. 19546@end table 19547 19548Default value is @b{@samp{line}}. 19549 19550@item w 19551@item h 19552Set the output video resolution. 19553 19554Default resolution depends on formats. 19555 19556@item in_stereo 19557@item out_stereo 19558Set the input/output stereo format. 19559 19560@table @samp 19561@item 2d 195622D mono 19563@item sbs 19564Side by side 19565@item tb 19566Top bottom 19567@end table 19568 19569Default value is @b{@samp{2d}} for input and output format. 19570 19571@item yaw 19572@item pitch 19573@item roll 19574Set rotation for the output video. Values in degrees. 19575 19576@item rorder 19577Set rotation order for the output video. Choose one item for each position. 19578 19579@table @samp 19580@item y, Y 19581yaw 19582@item p, P 19583pitch 19584@item r, R 19585roll 19586@end table 19587 19588Default value is @b{@samp{ypr}}. 19589 19590@item h_flip 19591@item v_flip 19592@item d_flip 19593Flip the output video horizontally(swaps left-right)/vertically(swaps up-down)/in-depth(swaps back-forward). Boolean values. 19594 19595@item ih_flip 19596@item iv_flip 19597Set if input video is flipped horizontally/vertically. Boolean values. 19598 19599@item in_trans 19600Set if input video is transposed. Boolean value, by default disabled. 19601 19602@item out_trans 19603Set if output video needs to be transposed. Boolean value, by default disabled. 19604 19605@item alpha_mask 19606Build mask in alpha plane for all unmapped pixels by marking them fully transparent. Boolean value, by default disabled. 19607@end table 19608 19609@subsection Examples 19610 19611@itemize 19612@item 19613Convert equirectangular video to cubemap with 3x2 layout and 1% padding using bicubic interpolation: 19614@example 19615ffmpeg -i input.mkv -vf v360=e:c3x2:cubic:out_pad=0.01 output.mkv 19616@end example 19617@item 19618Extract back view of Equi-Angular Cubemap: 19619@example 19620ffmpeg -i input.mkv -vf v360=eac:flat:yaw=180 output.mkv 19621@end example 19622@item 19623Convert transposed and horizontally flipped Equi-Angular Cubemap in side-by-side stereo format to equirectangular top-bottom stereo format: 19624@example 19625v360=eac:equirect:in_stereo=sbs:in_trans=1:ih_flip=1:out_stereo=tb 19626@end example 19627@end itemize 19628 19629@subsection Commands 19630 19631This filter supports subset of above options as @ref{commands}. 19632 19633@section vaguedenoiser 19634 19635Apply a wavelet based denoiser. 19636 19637It transforms each frame from the video input into the wavelet domain, 19638using Cohen-Daubechies-Feauveau 9/7. Then it applies some filtering to 19639the obtained coefficients. It does an inverse wavelet transform after. 19640Due to wavelet properties, it should give a nice smoothed result, and 19641reduced noise, without blurring picture features. 19642 19643This filter accepts the following options: 19644 19645@table @option 19646@item threshold 19647The filtering strength. The higher, the more filtered the video will be. 19648Hard thresholding can use a higher threshold than soft thresholding 19649before the video looks overfiltered. Default value is 2. 19650 19651@item method 19652The filtering method the filter will use. 19653 19654It accepts the following values: 19655@table @samp 19656@item hard 19657All values under the threshold will be zeroed. 19658 19659@item soft 19660All values under the threshold will be zeroed. All values above will be 19661reduced by the threshold. 19662 19663@item garrote 19664Scales or nullifies coefficients - intermediary between (more) soft and 19665(less) hard thresholding. 19666@end table 19667 19668Default is garrote. 19669 19670@item nsteps 19671Number of times, the wavelet will decompose the picture. Picture can't 19672be decomposed beyond a particular point (typically, 8 for a 640x480 19673frame - as 2^9 = 512 > 480). Valid values are integers between 1 and 32. Default value is 6. 19674 19675@item percent 19676Partial of full denoising (limited coefficients shrinking), from 0 to 100. Default value is 85. 19677 19678@item planes 19679A list of the planes to process. By default all planes are processed. 19680 19681@item type 19682The threshold type the filter will use. 19683 19684It accepts the following values: 19685@table @samp 19686@item universal 19687Threshold used is same for all decompositions. 19688 19689@item bayes 19690Threshold used depends also on each decomposition coefficients. 19691@end table 19692 19693Default is universal. 19694@end table 19695 19696@section vectorscope 19697 19698Display 2 color component values in the two dimensional graph (which is called 19699a vectorscope). 19700 19701This filter accepts the following options: 19702 19703@table @option 19704@item mode, m 19705Set vectorscope mode. 19706 19707It accepts the following values: 19708@table @samp 19709@item gray 19710@item tint 19711Gray values are displayed on graph, higher brightness means more pixels have 19712same component color value on location in graph. This is the default mode. 19713 19714@item color 19715Gray values are displayed on graph. Surrounding pixels values which are not 19716present in video frame are drawn in gradient of 2 color components which are 19717set by option @code{x} and @code{y}. The 3rd color component is static. 19718 19719@item color2 19720Actual color components values present in video frame are displayed on graph. 19721 19722@item color3 19723Similar as color2 but higher frequency of same values @code{x} and @code{y} 19724on graph increases value of another color component, which is luminance by 19725default values of @code{x} and @code{y}. 19726 19727@item color4 19728Actual colors present in video frame are displayed on graph. If two different 19729colors map to same position on graph then color with higher value of component 19730not present in graph is picked. 19731 19732@item color5 19733Gray values are displayed on graph. Similar to @code{color} but with 3rd color 19734component picked from radial gradient. 19735@end table 19736 19737@item x 19738Set which color component will be represented on X-axis. Default is @code{1}. 19739 19740@item y 19741Set which color component will be represented on Y-axis. Default is @code{2}. 19742 19743@item intensity, i 19744Set intensity, used by modes: gray, color, color3 and color5 for increasing brightness 19745of color component which represents frequency of (X, Y) location in graph. 19746 19747@item envelope, e 19748@table @samp 19749@item none 19750No envelope, this is default. 19751 19752@item instant 19753Instant envelope, even darkest single pixel will be clearly highlighted. 19754 19755@item peak 19756Hold maximum and minimum values presented in graph over time. This way you 19757can still spot out of range values without constantly looking at vectorscope. 19758 19759@item peak+instant 19760Peak and instant envelope combined together. 19761@end table 19762 19763@item graticule, g 19764Set what kind of graticule to draw. 19765@table @samp 19766@item none 19767@item green 19768@item color 19769@item invert 19770@end table 19771 19772@item opacity, o 19773Set graticule opacity. 19774 19775@item flags, f 19776Set graticule flags. 19777 19778@table @samp 19779@item white 19780Draw graticule for white point. 19781 19782@item black 19783Draw graticule for black point. 19784 19785@item name 19786Draw color points short names. 19787@end table 19788 19789@item bgopacity, b 19790Set background opacity. 19791 19792@item lthreshold, l 19793Set low threshold for color component not represented on X or Y axis. 19794Values lower than this value will be ignored. Default is 0. 19795Note this value is multiplied with actual max possible value one pixel component 19796can have. So for 8-bit input and low threshold value of 0.1 actual threshold 19797is 0.1 * 255 = 25. 19798 19799@item hthreshold, h 19800Set high threshold for color component not represented on X or Y axis. 19801Values higher than this value will be ignored. Default is 1. 19802Note this value is multiplied with actual max possible value one pixel component 19803can have. So for 8-bit input and high threshold value of 0.9 actual threshold 19804is 0.9 * 255 = 230. 19805 19806@item colorspace, c 19807Set what kind of colorspace to use when drawing graticule. 19808@table @samp 19809@item auto 19810@item 601 19811@item 709 19812@end table 19813Default is auto. 19814 19815@item tint0, t0 19816@item tint1, t1 19817Set color tint for gray/tint vectorscope mode. By default both options are zero. 19818This means no tint, and output will remain gray. 19819@end table 19820 19821@anchor{vidstabdetect} 19822@section vidstabdetect 19823 19824Analyze video stabilization/deshaking. Perform pass 1 of 2, see 19825@ref{vidstabtransform} for pass 2. 19826 19827This filter generates a file with relative translation and rotation 19828transform information about subsequent frames, which is then used by 19829the @ref{vidstabtransform} filter. 19830 19831To enable compilation of this filter you need to configure FFmpeg with 19832@code{--enable-libvidstab}. 19833 19834This filter accepts the following options: 19835 19836@table @option 19837@item result 19838Set the path to the file used to write the transforms information. 19839Default value is @file{transforms.trf}. 19840 19841@item shakiness 19842Set how shaky the video is and how quick the camera is. It accepts an 19843integer in the range 1-10, a value of 1 means little shakiness, a 19844value of 10 means strong shakiness. Default value is 5. 19845 19846@item accuracy 19847Set the accuracy of the detection process. It must be a value in the 19848range 1-15. A value of 1 means low accuracy, a value of 15 means high 19849accuracy. Default value is 15. 19850 19851@item stepsize 19852Set stepsize of the search process. The region around minimum is 19853scanned with 1 pixel resolution. Default value is 6. 19854 19855@item mincontrast 19856Set minimum contrast. Below this value a local measurement field is 19857discarded. Must be a floating point value in the range 0-1. Default 19858value is 0.3. 19859 19860@item tripod 19861Set reference frame number for tripod mode. 19862 19863If enabled, the motion of the frames is compared to a reference frame 19864in the filtered stream, identified by the specified number. The idea 19865is to compensate all movements in a more-or-less static scene and keep 19866the camera view absolutely still. 19867 19868If set to 0, it is disabled. The frames are counted starting from 1. 19869 19870@item show 19871Show fields and transforms in the resulting frames. It accepts an 19872integer in the range 0-2. Default value is 0, which disables any 19873visualization. 19874@end table 19875 19876@subsection Examples 19877 19878@itemize 19879@item 19880Use default values: 19881@example 19882vidstabdetect 19883@end example 19884 19885@item 19886Analyze strongly shaky movie and put the results in file 19887@file{mytransforms.trf}: 19888@example 19889vidstabdetect=shakiness=10:accuracy=15:result="mytransforms.trf" 19890@end example 19891 19892@item 19893Visualize the result of internal transformations in the resulting 19894video: 19895@example 19896vidstabdetect=show=1 19897@end example 19898 19899@item 19900Analyze a video with medium shakiness using @command{ffmpeg}: 19901@example 19902ffmpeg -i input -vf vidstabdetect=shakiness=5:show=1 dummy.avi 19903@end example 19904@end itemize 19905 19906@anchor{vidstabtransform} 19907@section vidstabtransform 19908 19909Video stabilization/deshaking: pass 2 of 2, 19910see @ref{vidstabdetect} for pass 1. 19911 19912Read a file with transform information for each frame and 19913apply/compensate them. Together with the @ref{vidstabdetect} 19914filter this can be used to deshake videos. See also 19915@url{http://public.hronopik.de/vid.stab}. It is important to also use 19916the @ref{unsharp} filter, see below. 19917 19918To enable compilation of this filter you need to configure FFmpeg with 19919@code{--enable-libvidstab}. 19920 19921@subsection Options 19922 19923@table @option 19924@item input 19925Set path to the file used to read the transforms. Default value is 19926@file{transforms.trf}. 19927 19928@item smoothing 19929Set the number of frames (value*2 + 1) used for lowpass filtering the 19930camera movements. Default value is 10. 19931 19932For example a number of 10 means that 21 frames are used (10 in the 19933past and 10 in the future) to smoothen the motion in the video. A 19934larger value leads to a smoother video, but limits the acceleration of 19935the camera (pan/tilt movements). 0 is a special case where a static 19936camera is simulated. 19937 19938@item optalgo 19939Set the camera path optimization algorithm. 19940 19941Accepted values are: 19942@table @samp 19943@item gauss 19944gaussian kernel low-pass filter on camera motion (default) 19945@item avg 19946averaging on transformations 19947@end table 19948 19949@item maxshift 19950Set maximal number of pixels to translate frames. Default value is -1, 19951meaning no limit. 19952 19953@item maxangle 19954Set maximal angle in radians (degree*PI/180) to rotate frames. Default 19955value is -1, meaning no limit. 19956 19957@item crop 19958Specify how to deal with borders that may be visible due to movement 19959compensation. 19960 19961Available values are: 19962@table @samp 19963@item keep 19964keep image information from previous frame (default) 19965@item black 19966fill the border black 19967@end table 19968 19969@item invert 19970Invert transforms if set to 1. Default value is 0. 19971 19972@item relative 19973Consider transforms as relative to previous frame if set to 1, 19974absolute if set to 0. Default value is 0. 19975 19976@item zoom 19977Set percentage to zoom. A positive value will result in a zoom-in 19978effect, a negative value in a zoom-out effect. Default value is 0 (no 19979zoom). 19980 19981@item optzoom 19982Set optimal zooming to avoid borders. 19983 19984Accepted values are: 19985@table @samp 19986@item 0 19987disabled 19988@item 1 19989optimal static zoom value is determined (only very strong movements 19990will lead to visible borders) (default) 19991@item 2 19992optimal adaptive zoom value is determined (no borders will be 19993visible), see @option{zoomspeed} 19994@end table 19995 19996Note that the value given at zoom is added to the one calculated here. 19997 19998@item zoomspeed 19999Set percent to zoom maximally each frame (enabled when 20000@option{optzoom} is set to 2). Range is from 0 to 5, default value is 200010.25. 20002 20003@item interpol 20004Specify type of interpolation. 20005 20006Available values are: 20007@table @samp 20008@item no 20009no interpolation 20010@item linear 20011linear only horizontal 20012@item bilinear 20013linear in both directions (default) 20014@item bicubic 20015cubic in both directions (slow) 20016@end table 20017 20018@item tripod 20019Enable virtual tripod mode if set to 1, which is equivalent to 20020@code{relative=0:smoothing=0}. Default value is 0. 20021 20022Use also @code{tripod} option of @ref{vidstabdetect}. 20023 20024@item debug 20025Increase log verbosity if set to 1. Also the detected global motions 20026are written to the temporary file @file{global_motions.trf}. Default 20027value is 0. 20028@end table 20029 20030@subsection Examples 20031 20032@itemize 20033@item 20034Use @command{ffmpeg} for a typical stabilization with default values: 20035@example 20036ffmpeg -i inp.mpeg -vf vidstabtransform,unsharp=5:5:0.8:3:3:0.4 inp_stabilized.mpeg 20037@end example 20038 20039Note the use of the @ref{unsharp} filter which is always recommended. 20040 20041@item 20042Zoom in a bit more and load transform data from a given file: 20043@example 20044vidstabtransform=zoom=5:input="mytransforms.trf" 20045@end example 20046 20047@item 20048Smoothen the video even more: 20049@example 20050vidstabtransform=smoothing=30 20051@end example 20052@end itemize 20053 20054@section vflip 20055 20056Flip the input video vertically. 20057 20058For example, to vertically flip a video with @command{ffmpeg}: 20059@example 20060ffmpeg -i in.avi -vf "vflip" out.avi 20061@end example 20062 20063@section vfrdet 20064 20065Detect variable frame rate video. 20066 20067This filter tries to detect if the input is variable or constant frame rate. 20068 20069At end it will output number of frames detected as having variable delta pts, 20070and ones with constant delta pts. 20071If there was frames with variable delta, than it will also show min, max and 20072average delta encountered. 20073 20074@section vibrance 20075 20076Boost or alter saturation. 20077 20078The filter accepts the following options: 20079@table @option 20080@item intensity 20081Set strength of boost if positive value or strength of alter if negative value. 20082Default is 0. Allowed range is from -2 to 2. 20083 20084@item rbal 20085Set the red balance. Default is 1. Allowed range is from -10 to 10. 20086 20087@item gbal 20088Set the green balance. Default is 1. Allowed range is from -10 to 10. 20089 20090@item bbal 20091Set the blue balance. Default is 1. Allowed range is from -10 to 10. 20092 20093@item rlum 20094Set the red luma coefficient. 20095 20096@item glum 20097Set the green luma coefficient. 20098 20099@item blum 20100Set the blue luma coefficient. 20101 20102@item alternate 20103If @code{intensity} is negative and this is set to 1, colors will change, 20104otherwise colors will be less saturated, more towards gray. 20105@end table 20106 20107@subsection Commands 20108 20109This filter supports the all above options as @ref{commands}. 20110 20111@anchor{vignette} 20112@section vignette 20113 20114Make or reverse a natural vignetting effect. 20115 20116The filter accepts the following options: 20117 20118@table @option 20119@item angle, a 20120Set lens angle expression as a number of radians. 20121 20122The value is clipped in the @code{[0,PI/2]} range. 20123 20124Default value: @code{"PI/5"} 20125 20126@item x0 20127@item y0 20128Set center coordinates expressions. Respectively @code{"w/2"} and @code{"h/2"} 20129by default. 20130 20131@item mode 20132Set forward/backward mode. 20133 20134Available modes are: 20135@table @samp 20136@item forward 20137The larger the distance from the central point, the darker the image becomes. 20138 20139@item backward 20140The larger the distance from the central point, the brighter the image becomes. 20141This can be used to reverse a vignette effect, though there is no automatic 20142detection to extract the lens @option{angle} and other settings (yet). It can 20143also be used to create a burning effect. 20144@end table 20145 20146Default value is @samp{forward}. 20147 20148@item eval 20149Set evaluation mode for the expressions (@option{angle}, @option{x0}, @option{y0}). 20150 20151It accepts the following values: 20152@table @samp 20153@item init 20154Evaluate expressions only once during the filter initialization. 20155 20156@item frame 20157Evaluate expressions for each incoming frame. This is way slower than the 20158@samp{init} mode since it requires all the scalers to be re-computed, but it 20159allows advanced dynamic expressions. 20160@end table 20161 20162Default value is @samp{init}. 20163 20164@item dither 20165Set dithering to reduce the circular banding effects. Default is @code{1} 20166(enabled). 20167 20168@item aspect 20169Set vignette aspect. This setting allows one to adjust the shape of the vignette. 20170Setting this value to the SAR of the input will make a rectangular vignetting 20171following the dimensions of the video. 20172 20173Default is @code{1/1}. 20174@end table 20175 20176@subsection Expressions 20177 20178The @option{alpha}, @option{x0} and @option{y0} expressions can contain the 20179following parameters. 20180 20181@table @option 20182@item w 20183@item h 20184input width and height 20185 20186@item n 20187the number of input frame, starting from 0 20188 20189@item pts 20190the PTS (Presentation TimeStamp) time of the filtered video frame, expressed in 20191@var{TB} units, NAN if undefined 20192 20193@item r 20194frame rate of the input video, NAN if the input frame rate is unknown 20195 20196@item t 20197the PTS (Presentation TimeStamp) of the filtered video frame, 20198expressed in seconds, NAN if undefined 20199 20200@item tb 20201time base of the input video 20202@end table 20203 20204 20205@subsection Examples 20206 20207@itemize 20208@item 20209Apply simple strong vignetting effect: 20210@example 20211vignette=PI/4 20212@end example 20213 20214@item 20215Make a flickering vignetting: 20216@example 20217vignette='PI/4+random(1)*PI/50':eval=frame 20218@end example 20219 20220@end itemize 20221 20222@section vmafmotion 20223 20224Obtain the average VMAF motion score of a video. 20225It is one of the component metrics of VMAF. 20226 20227The obtained average motion score is printed through the logging system. 20228 20229The filter accepts the following options: 20230 20231@table @option 20232@item stats_file 20233If specified, the filter will use the named file to save the motion score of 20234each frame with respect to the previous frame. 20235When filename equals "-" the data is sent to standard output. 20236@end table 20237 20238Example: 20239@example 20240ffmpeg -i ref.mpg -vf vmafmotion -f null - 20241@end example 20242 20243@section vstack 20244Stack input videos vertically. 20245 20246All streams must be of same pixel format and of same width. 20247 20248Note that this filter is faster than using @ref{overlay} and @ref{pad} filter 20249to create same output. 20250 20251The filter accepts the following options: 20252 20253@table @option 20254@item inputs 20255Set number of input streams. Default is 2. 20256 20257@item shortest 20258If set to 1, force the output to terminate when the shortest input 20259terminates. Default value is 0. 20260@end table 20261 20262@section w3fdif 20263 20264Deinterlace the input video ("w3fdif" stands for "Weston 3 Field 20265Deinterlacing Filter"). 20266 20267Based on the process described by Martin Weston for BBC R&D, and 20268implemented based on the de-interlace algorithm written by Jim 20269Easterbrook for BBC R&D, the Weston 3 field deinterlacing filter 20270uses filter coefficients calculated by BBC R&D. 20271 20272This filter uses field-dominance information in frame to decide which 20273of each pair of fields to place first in the output. 20274If it gets it wrong use @ref{setfield} filter before @code{w3fdif} filter. 20275 20276There are two sets of filter coefficients, so called "simple" 20277and "complex". Which set of filter coefficients is used can 20278be set by passing an optional parameter: 20279 20280@table @option 20281@item filter 20282Set the interlacing filter coefficients. Accepts one of the following values: 20283 20284@table @samp 20285@item simple 20286Simple filter coefficient set. 20287@item complex 20288More-complex filter coefficient set. 20289@end table 20290Default value is @samp{complex}. 20291 20292@item deint 20293Specify which frames to deinterlace. Accepts one of the following values: 20294 20295@table @samp 20296@item all 20297Deinterlace all frames, 20298@item interlaced 20299Only deinterlace frames marked as interlaced. 20300@end table 20301 20302Default value is @samp{all}. 20303@end table 20304 20305@section waveform 20306Video waveform monitor. 20307 20308The waveform monitor plots color component intensity. By default luminance 20309only. Each column of the waveform corresponds to a column of pixels in the 20310source video. 20311 20312It accepts the following options: 20313 20314@table @option 20315@item mode, m 20316Can be either @code{row}, or @code{column}. Default is @code{column}. 20317In row mode, the graph on the left side represents color component value 0 and 20318the right side represents value = 255. In column mode, the top side represents 20319color component value = 0 and bottom side represents value = 255. 20320 20321@item intensity, i 20322Set intensity. Smaller values are useful to find out how many values of the same 20323luminance are distributed across input rows/columns. 20324Default value is @code{0.04}. Allowed range is [0, 1]. 20325 20326@item mirror, r 20327Set mirroring mode. @code{0} means unmirrored, @code{1} means mirrored. 20328In mirrored mode, higher values will be represented on the left 20329side for @code{row} mode and at the top for @code{column} mode. Default is 20330@code{1} (mirrored). 20331 20332@item display, d 20333Set display mode. 20334It accepts the following values: 20335@table @samp 20336@item overlay 20337Presents information identical to that in the @code{parade}, except 20338that the graphs representing color components are superimposed directly 20339over one another. 20340 20341This display mode makes it easier to spot relative differences or similarities 20342in overlapping areas of the color components that are supposed to be identical, 20343such as neutral whites, grays, or blacks. 20344 20345@item stack 20346Display separate graph for the color components side by side in 20347@code{row} mode or one below the other in @code{column} mode. 20348 20349@item parade 20350Display separate graph for the color components side by side in 20351@code{column} mode or one below the other in @code{row} mode. 20352 20353Using this display mode makes it easy to spot color casts in the highlights 20354and shadows of an image, by comparing the contours of the top and the bottom 20355graphs of each waveform. Since whites, grays, and blacks are characterized 20356by exactly equal amounts of red, green, and blue, neutral areas of the picture 20357should display three waveforms of roughly equal width/height. If not, the 20358correction is easy to perform by making level adjustments the three waveforms. 20359@end table 20360Default is @code{stack}. 20361 20362@item components, c 20363Set which color components to display. Default is 1, which means only luminance 20364or red color component if input is in RGB colorspace. If is set for example to 203657 it will display all 3 (if) available color components. 20366 20367@item envelope, e 20368@table @samp 20369@item none 20370No envelope, this is default. 20371 20372@item instant 20373Instant envelope, minimum and maximum values presented in graph will be easily 20374visible even with small @code{step} value. 20375 20376@item peak 20377Hold minimum and maximum values presented in graph across time. This way you 20378can still spot out of range values without constantly looking at waveforms. 20379 20380@item peak+instant 20381Peak and instant envelope combined together. 20382@end table 20383 20384@item filter, f 20385@table @samp 20386@item lowpass 20387No filtering, this is default. 20388 20389@item flat 20390Luma and chroma combined together. 20391 20392@item aflat 20393Similar as above, but shows difference between blue and red chroma. 20394 20395@item xflat 20396Similar as above, but use different colors. 20397 20398@item yflat 20399Similar as above, but again with different colors. 20400 20401@item chroma 20402Displays only chroma. 20403 20404@item color 20405Displays actual color value on waveform. 20406 20407@item acolor 20408Similar as above, but with luma showing frequency of chroma values. 20409@end table 20410 20411@item graticule, g 20412Set which graticule to display. 20413 20414@table @samp 20415@item none 20416Do not display graticule. 20417 20418@item green 20419Display green graticule showing legal broadcast ranges. 20420 20421@item orange 20422Display orange graticule showing legal broadcast ranges. 20423 20424@item invert 20425Display invert graticule showing legal broadcast ranges. 20426@end table 20427 20428@item opacity, o 20429Set graticule opacity. 20430 20431@item flags, fl 20432Set graticule flags. 20433 20434@table @samp 20435@item numbers 20436Draw numbers above lines. By default enabled. 20437 20438@item dots 20439Draw dots instead of lines. 20440@end table 20441 20442@item scale, s 20443Set scale used for displaying graticule. 20444 20445@table @samp 20446@item digital 20447@item millivolts 20448@item ire 20449@end table 20450Default is digital. 20451 20452@item bgopacity, b 20453Set background opacity. 20454 20455@item tint0, t0 20456@item tint1, t1 20457Set tint for output. 20458Only used with lowpass filter and when display is not overlay and input 20459pixel formats are not RGB. 20460@end table 20461 20462@section weave, doubleweave 20463 20464The @code{weave} takes a field-based video input and join 20465each two sequential fields into single frame, producing a new double 20466height clip with half the frame rate and half the frame count. 20467 20468The @code{doubleweave} works same as @code{weave} but without 20469halving frame rate and frame count. 20470 20471It accepts the following option: 20472 20473@table @option 20474@item first_field 20475Set first field. Available values are: 20476 20477@table @samp 20478@item top, t 20479Set the frame as top-field-first. 20480 20481@item bottom, b 20482Set the frame as bottom-field-first. 20483@end table 20484@end table 20485 20486@subsection Examples 20487 20488@itemize 20489@item 20490Interlace video using @ref{select} and @ref{separatefields} filter: 20491@example 20492separatefields,select=eq(mod(n,4),0)+eq(mod(n,4),3),weave 20493@end example 20494@end itemize 20495 20496@section xbr 20497Apply the xBR high-quality magnification filter which is designed for pixel 20498art. It follows a set of edge-detection rules, see 20499@url{https://forums.libretro.com/t/xbr-algorithm-tutorial/123}. 20500 20501It accepts the following option: 20502 20503@table @option 20504@item n 20505Set the scaling dimension: @code{2} for @code{2xBR}, @code{3} for 20506@code{3xBR} and @code{4} for @code{4xBR}. 20507Default is @code{3}. 20508@end table 20509 20510@section xfade 20511 20512Apply cross fade from one input video stream to another input video stream. 20513The cross fade is applied for specified duration. 20514 20515The filter accepts the following options: 20516 20517@table @option 20518@item transition 20519Set one of available transition effects: 20520 20521@table @samp 20522@item custom 20523@item fade 20524@item wipeleft 20525@item wiperight 20526@item wipeup 20527@item wipedown 20528@item slideleft 20529@item slideright 20530@item slideup 20531@item slidedown 20532@item circlecrop 20533@item rectcrop 20534@item distance 20535@item fadeblack 20536@item fadewhite 20537@item radial 20538@item smoothleft 20539@item smoothright 20540@item smoothup 20541@item smoothdown 20542@item circleopen 20543@item circleclose 20544@item vertopen 20545@item vertclose 20546@item horzopen 20547@item horzclose 20548@item dissolve 20549@item pixelize 20550@item diagtl 20551@item diagtr 20552@item diagbl 20553@item diagbr 20554@item hlslice 20555@item hrslice 20556@item vuslice 20557@item vdslice 20558@item hblur 20559@item fadegrays 20560@item wipetl 20561@item wipetr 20562@item wipebl 20563@item wipebr 20564@end table 20565Default transition effect is fade. 20566 20567@item duration 20568Set cross fade duration in seconds. 20569Default duration is 1 second. 20570 20571@item offset 20572Set cross fade start relative to first input stream in seconds. 20573Default offset is 0. 20574 20575@item expr 20576Set expression for custom transition effect. 20577 20578The expressions can use the following variables and functions: 20579 20580@table @option 20581@item X 20582@item Y 20583The coordinates of the current sample. 20584 20585@item W 20586@item H 20587The width and height of the image. 20588 20589@item P 20590Progress of transition effect. 20591 20592@item PLANE 20593Currently processed plane. 20594 20595@item A 20596Return value of first input at current location and plane. 20597 20598@item B 20599Return value of second input at current location and plane. 20600 20601@item a0(x, y) 20602@item a1(x, y) 20603@item a2(x, y) 20604@item a3(x, y) 20605Return the value of the pixel at location (@var{x},@var{y}) of the 20606first/second/third/fourth component of first input. 20607 20608@item b0(x, y) 20609@item b1(x, y) 20610@item b2(x, y) 20611@item b3(x, y) 20612Return the value of the pixel at location (@var{x},@var{y}) of the 20613first/second/third/fourth component of second input. 20614@end table 20615@end table 20616 20617@subsection Examples 20618 20619@itemize 20620@item 20621Cross fade from one input video to another input video, with fade transition and duration of transition 20622of 2 seconds starting at offset of 5 seconds: 20623@example 20624ffmpeg -i first.mp4 -i second.mp4 -filter_complex xfade=transition=fade:duration=2:offset=5 output.mp4 20625@end example 20626@end itemize 20627 20628@section xmedian 20629Pick median pixels from several input videos. 20630 20631The filter accepts the following options: 20632 20633@table @option 20634@item inputs 20635Set number of inputs. 20636Default is 3. Allowed range is from 3 to 255. 20637If number of inputs is even number, than result will be mean value between two median values. 20638 20639@item planes 20640Set which planes to filter. Default value is @code{15}, by which all planes are processed. 20641 20642@item percentile 20643Set median percentile. Default value is @code{0.5}. 20644Default value of @code{0.5} will pick always median values, while @code{0} will pick 20645minimum values, and @code{1} maximum values. 20646@end table 20647 20648@section xstack 20649Stack video inputs into custom layout. 20650 20651All streams must be of same pixel format. 20652 20653The filter accepts the following options: 20654 20655@table @option 20656@item inputs 20657Set number of input streams. Default is 2. 20658 20659@item layout 20660Specify layout of inputs. 20661This option requires the desired layout configuration to be explicitly set by the user. 20662This sets position of each video input in output. Each input 20663is separated by '|'. 20664The first number represents the column, and the second number represents the row. 20665Numbers start at 0 and are separated by '_'. Optionally one can use wX and hX, 20666where X is video input from which to take width or height. 20667Multiple values can be used when separated by '+'. In such 20668case values are summed together. 20669 20670Note that if inputs are of different sizes gaps may appear, as not all of 20671the output video frame will be filled. Similarly, videos can overlap each 20672other if their position doesn't leave enough space for the full frame of 20673adjoining videos. 20674 20675For 2 inputs, a default layout of @code{0_0|w0_0} is set. In all other cases, 20676a layout must be set by the user. 20677 20678@item shortest 20679If set to 1, force the output to terminate when the shortest input 20680terminates. Default value is 0. 20681 20682@item fill 20683If set to valid color, all unused pixels will be filled with that color. 20684By default fill is set to none, so it is disabled. 20685@end table 20686 20687@subsection Examples 20688 20689@itemize 20690@item 20691Display 4 inputs into 2x2 grid. 20692 20693Layout: 20694@example 20695input1(0, 0) | input3(w0, 0) 20696input2(0, h0) | input4(w0, h0) 20697@end example 20698 20699@example 20700xstack=inputs=4:layout=0_0|0_h0|w0_0|w0_h0 20701@end example 20702 20703Note that if inputs are of different sizes, gaps or overlaps may occur. 20704 20705@item 20706Display 4 inputs into 1x4 grid. 20707 20708Layout: 20709@example 20710input1(0, 0) 20711input2(0, h0) 20712input3(0, h0+h1) 20713input4(0, h0+h1+h2) 20714@end example 20715 20716@example 20717xstack=inputs=4:layout=0_0|0_h0|0_h0+h1|0_h0+h1+h2 20718@end example 20719 20720Note that if inputs are of different widths, unused space will appear. 20721 20722@item 20723Display 9 inputs into 3x3 grid. 20724 20725Layout: 20726@example 20727input1(0, 0) | input4(w0, 0) | input7(w0+w3, 0) 20728input2(0, h0) | input5(w0, h0) | input8(w0+w3, h0) 20729input3(0, h0+h1) | input6(w0, h0+h1) | input9(w0+w3, h0+h1) 20730@end example 20731 20732@example 20733xstack=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 20734@end example 20735 20736Note that if inputs are of different sizes, gaps or overlaps may occur. 20737 20738@item 20739Display 16 inputs into 4x4 grid. 20740 20741Layout: 20742@example 20743input1(0, 0) | input5(w0, 0) | input9 (w0+w4, 0) | input13(w0+w4+w8, 0) 20744input2(0, h0) | input6(w0, h0) | input10(w0+w4, h0) | input14(w0+w4+w8, h0) 20745input3(0, h0+h1) | input7(w0, h0+h1) | input11(w0+w4, h0+h1) | input15(w0+w4+w8, h0+h1) 20746input4(0, h0+h1+h2)| input8(w0, h0+h1+h2)| input12(w0+w4, h0+h1+h2)| input16(w0+w4+w8, h0+h1+h2) 20747@end example 20748 20749@example 20750xstack=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| 20751w0+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 20752@end example 20753 20754Note that if inputs are of different sizes, gaps or overlaps may occur. 20755 20756@end itemize 20757 20758@anchor{yadif} 20759@section yadif 20760 20761Deinterlace the input video ("yadif" means "yet another deinterlacing 20762filter"). 20763 20764It accepts the following parameters: 20765 20766 20767@table @option 20768 20769@item mode 20770The interlacing mode to adopt. It accepts one of the following values: 20771 20772@table @option 20773@item 0, send_frame 20774Output one frame for each frame. 20775@item 1, send_field 20776Output one frame for each field. 20777@item 2, send_frame_nospatial 20778Like @code{send_frame}, but it skips the spatial interlacing check. 20779@item 3, send_field_nospatial 20780Like @code{send_field}, but it skips the spatial interlacing check. 20781@end table 20782 20783The default value is @code{send_frame}. 20784 20785@item parity 20786The picture field parity assumed for the input interlaced video. It accepts one 20787of the following values: 20788 20789@table @option 20790@item 0, tff 20791Assume the top field is first. 20792@item 1, bff 20793Assume the bottom field is first. 20794@item -1, auto 20795Enable automatic detection of field parity. 20796@end table 20797 20798The default value is @code{auto}. 20799If the interlacing is unknown or the decoder does not export this information, 20800top field first will be assumed. 20801 20802@item deint 20803Specify which frames to deinterlace. Accepts one of the following 20804values: 20805 20806@table @option 20807@item 0, all 20808Deinterlace all frames. 20809@item 1, interlaced 20810Only deinterlace frames marked as interlaced. 20811@end table 20812 20813The default value is @code{all}. 20814@end table 20815 20816@section yadif_cuda 20817 20818Deinterlace the input video using the @ref{yadif} algorithm, but implemented 20819in CUDA so that it can work as part of a GPU accelerated pipeline with nvdec 20820and/or nvenc. 20821 20822It accepts the following parameters: 20823 20824 20825@table @option 20826 20827@item mode 20828The interlacing mode to adopt. It accepts one of the following values: 20829 20830@table @option 20831@item 0, send_frame 20832Output one frame for each frame. 20833@item 1, send_field 20834Output one frame for each field. 20835@item 2, send_frame_nospatial 20836Like @code{send_frame}, but it skips the spatial interlacing check. 20837@item 3, send_field_nospatial 20838Like @code{send_field}, but it skips the spatial interlacing check. 20839@end table 20840 20841The default value is @code{send_frame}. 20842 20843@item parity 20844The picture field parity assumed for the input interlaced video. It accepts one 20845of the following values: 20846 20847@table @option 20848@item 0, tff 20849Assume the top field is first. 20850@item 1, bff 20851Assume the bottom field is first. 20852@item -1, auto 20853Enable automatic detection of field parity. 20854@end table 20855 20856The default value is @code{auto}. 20857If the interlacing is unknown or the decoder does not export this information, 20858top field first will be assumed. 20859 20860@item deint 20861Specify which frames to deinterlace. Accepts one of the following 20862values: 20863 20864@table @option 20865@item 0, all 20866Deinterlace all frames. 20867@item 1, interlaced 20868Only deinterlace frames marked as interlaced. 20869@end table 20870 20871The default value is @code{all}. 20872@end table 20873 20874@section yaepblur 20875 20876Apply blur filter while preserving edges ("yaepblur" means "yet another edge preserving blur filter"). 20877The algorithm is described in 20878"J. S. Lee, Digital image enhancement and noise filtering by use of local statistics, IEEE Trans. Pattern Anal. Mach. Intell. PAMI-2, 1980." 20879 20880It accepts the following parameters: 20881 20882@table @option 20883@item radius, r 20884Set the window radius. Default value is 3. 20885 20886@item planes, p 20887Set which planes to filter. Default is only the first plane. 20888 20889@item sigma, s 20890Set blur strength. Default value is 128. 20891@end table 20892 20893@subsection Commands 20894This filter supports same @ref{commands} as options. 20895 20896@section zoompan 20897 20898Apply Zoom & Pan effect. 20899 20900This filter accepts the following options: 20901 20902@table @option 20903@item zoom, z 20904Set the zoom expression. Range is 1-10. Default is 1. 20905 20906@item x 20907@item y 20908Set the x and y expression. Default is 0. 20909 20910@item d 20911Set the duration expression in number of frames. 20912This sets for how many number of frames effect will last for 20913single input image. 20914 20915@item s 20916Set the output image size, default is 'hd720'. 20917 20918@item fps 20919Set the output frame rate, default is '25'. 20920@end table 20921 20922Each expression can contain the following constants: 20923 20924@table @option 20925@item in_w, iw 20926Input width. 20927 20928@item in_h, ih 20929Input height. 20930 20931@item out_w, ow 20932Output width. 20933 20934@item out_h, oh 20935Output height. 20936 20937@item in 20938Input frame count. 20939 20940@item on 20941Output frame count. 20942 20943@item in_time, it 20944The input timestamp expressed in seconds. It's NAN if the input timestamp is unknown. 20945 20946@item out_time, time, ot 20947The output timestamp expressed in seconds. 20948 20949@item x 20950@item y 20951Last calculated 'x' and 'y' position from 'x' and 'y' expression 20952for current input frame. 20953 20954@item px 20955@item py 20956'x' and 'y' of last output frame of previous input frame or 0 when there was 20957not yet such frame (first input frame). 20958 20959@item zoom 20960Last calculated zoom from 'z' expression for current input frame. 20961 20962@item pzoom 20963Last calculated zoom of last output frame of previous input frame. 20964 20965@item duration 20966Number of output frames for current input frame. Calculated from 'd' expression 20967for each input frame. 20968 20969@item pduration 20970number of output frames created for previous input frame 20971 20972@item a 20973Rational number: input width / input height 20974 20975@item sar 20976sample aspect ratio 20977 20978@item dar 20979display aspect ratio 20980 20981@end table 20982 20983@subsection Examples 20984 20985@itemize 20986@item 20987Zoom in up to 1.5x and pan at same time to some spot near center of picture: 20988@example 20989zoompan=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 20990@end example 20991 20992@item 20993Zoom in up to 1.5x and pan always at center of picture: 20994@example 20995zoompan=z='min(zoom+0.0015,1.5)':d=700:x='iw/2-(iw/zoom/2)':y='ih/2-(ih/zoom/2)' 20996@end example 20997 20998@item 20999Same as above but without pausing: 21000@example 21001zoompan=z='min(max(zoom,pzoom)+0.0015,1.5)':d=1:x='iw/2-(iw/zoom/2)':y='ih/2-(ih/zoom/2)' 21002@end example 21003 21004@item 21005Zoom in 2x into center of picture only for the first second of the input video: 21006@example 21007zoompan=z='if(between(in_time,0,1),2,1)':d=1:x='iw/2-(iw/zoom/2)':y='ih/2-(ih/zoom/2)' 21008@end example 21009 21010@end itemize 21011 21012@anchor{zscale} 21013@section zscale 21014Scale (resize) the input video, using the z.lib library: 21015@url{https://github.com/sekrit-twc/zimg}. To enable compilation of this 21016filter, you need to configure FFmpeg with @code{--enable-libzimg}. 21017 21018The zscale filter forces the output display aspect ratio to be the same 21019as the input, by changing the output sample aspect ratio. 21020 21021If the input image format is different from the format requested by 21022the next filter, the zscale filter will convert the input to the 21023requested format. 21024 21025@subsection Options 21026The filter accepts the following options. 21027 21028@table @option 21029@item width, w 21030@item height, h 21031Set the output video dimension expression. Default value is the input 21032dimension. 21033 21034If the @var{width} or @var{w} value is 0, the input width is used for 21035the output. If the @var{height} or @var{h} value is 0, the input height 21036is used for the output. 21037 21038If one and only one of the values is -n with n >= 1, the zscale filter 21039will use a value that maintains the aspect ratio of the input image, 21040calculated from the other specified dimension. After that it will, 21041however, make sure that the calculated dimension is divisible by n and 21042adjust the value if necessary. 21043 21044If both values are -n with n >= 1, the behavior will be identical to 21045both values being set to 0 as previously detailed. 21046 21047See below for the list of accepted constants for use in the dimension 21048expression. 21049 21050@item size, s 21051Set the video size. For the syntax of this option, check the 21052@ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}. 21053 21054@item dither, d 21055Set the dither type. 21056 21057Possible values are: 21058@table @var 21059@item none 21060@item ordered 21061@item random 21062@item error_diffusion 21063@end table 21064 21065Default is none. 21066 21067@item filter, f 21068Set the resize filter type. 21069 21070Possible values are: 21071@table @var 21072@item point 21073@item bilinear 21074@item bicubic 21075@item spline16 21076@item spline36 21077@item lanczos 21078@end table 21079 21080Default is bilinear. 21081 21082@item range, r 21083Set the color range. 21084 21085Possible values are: 21086@table @var 21087@item input 21088@item limited 21089@item full 21090@end table 21091 21092Default is same as input. 21093 21094@item primaries, p 21095Set the color primaries. 21096 21097Possible values are: 21098@table @var 21099@item input 21100@item 709 21101@item unspecified 21102@item 170m 21103@item 240m 21104@item 2020 21105@end table 21106 21107Default is same as input. 21108 21109@item transfer, t 21110Set the transfer characteristics. 21111 21112Possible values are: 21113@table @var 21114@item input 21115@item 709 21116@item unspecified 21117@item 601 21118@item linear 21119@item 2020_10 21120@item 2020_12 21121@item smpte2084 21122@item iec61966-2-1 21123@item arib-std-b67 21124@end table 21125 21126Default is same as input. 21127 21128@item matrix, m 21129Set the colorspace matrix. 21130 21131Possible value are: 21132@table @var 21133@item input 21134@item 709 21135@item unspecified 21136@item 470bg 21137@item 170m 21138@item 2020_ncl 21139@item 2020_cl 21140@end table 21141 21142Default is same as input. 21143 21144@item rangein, rin 21145Set the input color range. 21146 21147Possible values are: 21148@table @var 21149@item input 21150@item limited 21151@item full 21152@end table 21153 21154Default is same as input. 21155 21156@item primariesin, pin 21157Set the input color primaries. 21158 21159Possible values are: 21160@table @var 21161@item input 21162@item 709 21163@item unspecified 21164@item 170m 21165@item 240m 21166@item 2020 21167@end table 21168 21169Default is same as input. 21170 21171@item transferin, tin 21172Set the input transfer characteristics. 21173 21174Possible values are: 21175@table @var 21176@item input 21177@item 709 21178@item unspecified 21179@item 601 21180@item linear 21181@item 2020_10 21182@item 2020_12 21183@end table 21184 21185Default is same as input. 21186 21187@item matrixin, min 21188Set the input colorspace matrix. 21189 21190Possible value are: 21191@table @var 21192@item input 21193@item 709 21194@item unspecified 21195@item 470bg 21196@item 170m 21197@item 2020_ncl 21198@item 2020_cl 21199@end table 21200 21201@item chromal, c 21202Set the output chroma location. 21203 21204Possible values are: 21205@table @var 21206@item input 21207@item left 21208@item center 21209@item topleft 21210@item top 21211@item bottomleft 21212@item bottom 21213@end table 21214 21215@item chromalin, cin 21216Set the input chroma location. 21217 21218Possible values are: 21219@table @var 21220@item input 21221@item left 21222@item center 21223@item topleft 21224@item top 21225@item bottomleft 21226@item bottom 21227@end table 21228 21229@item npl 21230Set the nominal peak luminance. 21231@end table 21232 21233The values of the @option{w} and @option{h} options are expressions 21234containing the following constants: 21235 21236@table @var 21237@item in_w 21238@item in_h 21239The input width and height 21240 21241@item iw 21242@item ih 21243These are the same as @var{in_w} and @var{in_h}. 21244 21245@item out_w 21246@item out_h 21247The output (scaled) width and height 21248 21249@item ow 21250@item oh 21251These are the same as @var{out_w} and @var{out_h} 21252 21253@item a 21254The same as @var{iw} / @var{ih} 21255 21256@item sar 21257input sample aspect ratio 21258 21259@item dar 21260The input display aspect ratio. Calculated from @code{(iw / ih) * sar}. 21261 21262@item hsub 21263@item vsub 21264horizontal and vertical input chroma subsample values. For example for the 21265pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1. 21266 21267@item ohsub 21268@item ovsub 21269horizontal and vertical output chroma subsample values. For example for the 21270pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1. 21271@end table 21272 21273@subsection Commands 21274 21275This filter supports the following commands: 21276@table @option 21277@item width, w 21278@item height, h 21279Set the output video dimension expression. 21280The command accepts the same syntax of the corresponding option. 21281 21282If the specified expression is not valid, it is kept at its current 21283value. 21284@end table 21285 21286@c man end VIDEO FILTERS 21287 21288@chapter OpenCL Video Filters 21289@c man begin OPENCL VIDEO FILTERS 21290 21291Below is a description of the currently available OpenCL video filters. 21292 21293To enable compilation of these filters you need to configure FFmpeg with 21294@code{--enable-opencl}. 21295 21296Running OpenCL filters requires you to initialize a hardware device and to pass that device to all filters in any filter graph. 21297@table @option 21298 21299@item -init_hw_device opencl[=@var{name}][:@var{device}[,@var{key=value}...]] 21300Initialise a new hardware device of type @var{opencl} called @var{name}, using the 21301given device parameters. 21302 21303@item -filter_hw_device @var{name} 21304Pass the hardware device called @var{name} to all filters in any filter graph. 21305 21306@end table 21307 21308For more detailed information see @url{https://www.ffmpeg.org/ffmpeg.html#Advanced-Video-options} 21309 21310@itemize 21311@item 21312Example of choosing the first device on the second platform and running avgblur_opencl filter with default parameters on it. 21313@example 21314-init_hw_device opencl=gpu:1.0 -filter_hw_device gpu -i INPUT -vf "hwupload, avgblur_opencl, hwdownload" OUTPUT 21315@end example 21316@end itemize 21317 21318Since 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. 21319 21320@section avgblur_opencl 21321 21322Apply average blur filter. 21323 21324The filter accepts the following options: 21325 21326@table @option 21327@item sizeX 21328Set horizontal radius size. 21329Range is @code{[1, 1024]} and default value is @code{1}. 21330 21331@item planes 21332Set which planes to filter. Default value is @code{0xf}, by which all planes are processed. 21333 21334@item sizeY 21335Set vertical radius size. Range is @code{[1, 1024]} and default value is @code{0}. If zero, @code{sizeX} value will be used. 21336@end table 21337 21338@subsection Example 21339 21340@itemize 21341@item 21342Apply 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. 21343@example 21344-i INPUT -vf "hwupload, avgblur_opencl=3, hwdownload" OUTPUT 21345@end example 21346@end itemize 21347 21348@section boxblur_opencl 21349 21350Apply a boxblur algorithm to the input video. 21351 21352It accepts the following parameters: 21353 21354@table @option 21355 21356@item luma_radius, lr 21357@item luma_power, lp 21358@item chroma_radius, cr 21359@item chroma_power, cp 21360@item alpha_radius, ar 21361@item alpha_power, ap 21362 21363@end table 21364 21365A description of the accepted options follows. 21366 21367@table @option 21368@item luma_radius, lr 21369@item chroma_radius, cr 21370@item alpha_radius, ar 21371Set an expression for the box radius in pixels used for blurring the 21372corresponding input plane. 21373 21374The radius value must be a non-negative number, and must not be 21375greater than the value of the expression @code{min(w,h)/2} for the 21376luma and alpha planes, and of @code{min(cw,ch)/2} for the chroma 21377planes. 21378 21379Default value for @option{luma_radius} is "2". If not specified, 21380@option{chroma_radius} and @option{alpha_radius} default to the 21381corresponding value set for @option{luma_radius}. 21382 21383The expressions can contain the following constants: 21384@table @option 21385@item w 21386@item h 21387The input width and height in pixels. 21388 21389@item cw 21390@item ch 21391The input chroma image width and height in pixels. 21392 21393@item hsub 21394@item vsub 21395The horizontal and vertical chroma subsample values. For example, for the 21396pixel format "yuv422p", @var{hsub} is 2 and @var{vsub} is 1. 21397@end table 21398 21399@item luma_power, lp 21400@item chroma_power, cp 21401@item alpha_power, ap 21402Specify how many times the boxblur filter is applied to the 21403corresponding plane. 21404 21405Default value for @option{luma_power} is 2. If not specified, 21406@option{chroma_power} and @option{alpha_power} default to the 21407corresponding value set for @option{luma_power}. 21408 21409A value of 0 will disable the effect. 21410@end table 21411 21412@subsection Examples 21413 21414Apply 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. 21415 21416@itemize 21417@item 21418Apply a boxblur filter with the luma, chroma, and alpha radius 21419set 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. 21420@example 21421-i INPUT -vf "hwupload, boxblur_opencl=luma_radius=2:luma_power=3, hwdownload" OUTPUT 21422-i INPUT -vf "hwupload, boxblur_opencl=2:3, hwdownload" OUTPUT 21423@end example 21424 21425@item 21426Apply 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. 21427 21428For the luma plane, a 2x2 box radius will be run once. 21429 21430For the chroma plane, a 4x4 box radius will be run 5 times. 21431 21432For the alpha plane, a 3x3 box radius will be run 7 times. 21433@example 21434-i INPUT -vf "hwupload, boxblur_opencl=2:1:4:5:3:7, hwdownload" OUTPUT 21435@end example 21436@end itemize 21437 21438@section colorkey_opencl 21439RGB colorspace color keying. 21440 21441The filter accepts the following options: 21442 21443@table @option 21444@item color 21445The color which will be replaced with transparency. 21446 21447@item similarity 21448Similarity percentage with the key color. 21449 214500.01 matches only the exact key color, while 1.0 matches everything. 21451 21452@item blend 21453Blend percentage. 21454 214550.0 makes pixels either fully transparent, or not transparent at all. 21456 21457Higher values result in semi-transparent pixels, with a higher transparency 21458the more similar the pixels color is to the key color. 21459@end table 21460 21461@subsection Examples 21462 21463@itemize 21464@item 21465Make every semi-green pixel in the input transparent with some slight blending: 21466@example 21467-i INPUT -vf "hwupload, colorkey_opencl=green:0.3:0.1, hwdownload" OUTPUT 21468@end example 21469@end itemize 21470 21471@section convolution_opencl 21472 21473Apply convolution of 3x3, 5x5, 7x7 matrix. 21474 21475The filter accepts the following options: 21476 21477@table @option 21478@item 0m 21479@item 1m 21480@item 2m 21481@item 3m 21482Set matrix for each plane. 21483Matrix is sequence of 9, 25 or 49 signed numbers. 21484Default value for each plane is @code{0 0 0 0 1 0 0 0 0}. 21485 21486@item 0rdiv 21487@item 1rdiv 21488@item 2rdiv 21489@item 3rdiv 21490Set multiplier for calculated value for each plane. 21491If unset or 0, it will be sum of all matrix elements. 21492The option value must be a float number greater or equal to @code{0.0}. Default value is @code{1.0}. 21493 21494@item 0bias 21495@item 1bias 21496@item 2bias 21497@item 3bias 21498Set bias for each plane. This value is added to the result of the multiplication. 21499Useful for making the overall image brighter or darker. 21500The option value must be a float number greater or equal to @code{0.0}. Default value is @code{0.0}. 21501 21502@end table 21503 21504@subsection Examples 21505 21506@itemize 21507@item 21508Apply sharpen: 21509@example 21510-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 21511@end example 21512 21513@item 21514Apply blur: 21515@example 21516-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 21517@end example 21518 21519@item 21520Apply edge enhance: 21521@example 21522-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 21523@end example 21524 21525@item 21526Apply edge detect: 21527@example 21528-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 21529@end example 21530 21531@item 21532Apply laplacian edge detector which includes diagonals: 21533@example 21534-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 21535@end example 21536 21537@item 21538Apply emboss: 21539@example 21540-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 21541@end example 21542@end itemize 21543 21544@section erosion_opencl 21545 21546Apply erosion effect to the video. 21547 21548This filter replaces the pixel by the local(3x3) minimum. 21549 21550It accepts the following options: 21551 21552@table @option 21553@item threshold0 21554@item threshold1 21555@item threshold2 21556@item threshold3 21557Limit the maximum change for each plane. Range is @code{[0, 65535]} and default value is @code{65535}. 21558If @code{0}, plane will remain unchanged. 21559 21560@item coordinates 21561Flag which specifies the pixel to refer to. 21562Range is @code{[0, 255]} and default value is @code{255}, i.e. all eight pixels are used. 21563 21564Flags to local 3x3 coordinates region centered on @code{x}: 21565 21566 1 2 3 21567 21568 4 x 5 21569 21570 6 7 8 21571@end table 21572 21573@subsection Example 21574 21575@itemize 21576@item 21577Apply 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. 21578@example 21579-i INPUT -vf "hwupload, erosion_opencl=30:40:50:coordinates=231, hwdownload" OUTPUT 21580@end example 21581@end itemize 21582 21583@section deshake_opencl 21584Feature-point based video stabilization filter. 21585 21586The filter accepts the following options: 21587 21588@table @option 21589@item tripod 21590Simulates a tripod by preventing any camera movement whatsoever from the original frame. Defaults to @code{0}. 21591 21592@item debug 21593Whether or not additional debug info should be displayed, both in the processed output and in the console. 21594 21595Note that in order to see console debug output you will also need to pass @code{-v verbose} to ffmpeg. 21596 21597Viewing point matches in the output video is only supported for RGB input. 21598 21599Defaults to @code{0}. 21600 21601@item adaptive_crop 21602Whether or not to do a tiny bit of cropping at the borders to cut down on the amount of mirrored pixels. 21603 21604Defaults to @code{1}. 21605 21606@item refine_features 21607Whether or not feature points should be refined at a sub-pixel level. 21608 21609This can be turned off for a slight performance gain at the cost of precision. 21610 21611Defaults to @code{1}. 21612 21613@item smooth_strength 21614The strength of the smoothing applied to the camera path from @code{0.0} to @code{1.0}. 21615 21616@code{1.0} is the maximum smoothing strength while values less than that result in less smoothing. 21617 21618@code{0.0} causes the filter to adaptively choose a smoothing strength on a per-frame basis. 21619 21620Defaults to @code{0.0}. 21621 21622@item smooth_window_multiplier 21623Controls the size of the smoothing window (the number of frames buffered to determine motion information from). 21624 21625The size of the smoothing window is determined by multiplying the framerate of the video by this number. 21626 21627Acceptable values range from @code{0.1} to @code{10.0}. 21628 21629Larger values increase the amount of motion data available for determining how to smooth the camera path, 21630potentially improving smoothness, but also increase latency and memory usage. 21631 21632Defaults to @code{2.0}. 21633 21634@end table 21635 21636@subsection Examples 21637 21638@itemize 21639@item 21640Stabilize a video with a fixed, medium smoothing strength: 21641@example 21642-i INPUT -vf "hwupload, deshake_opencl=smooth_strength=0.5, hwdownload" OUTPUT 21643@end example 21644 21645@item 21646Stabilize a video with debugging (both in console and in rendered video): 21647@example 21648-i INPUT -filter_complex "[0:v]format=rgba, hwupload, deshake_opencl=debug=1, hwdownload, format=rgba, format=yuv420p" -v verbose OUTPUT 21649@end example 21650@end itemize 21651 21652@section dilation_opencl 21653 21654Apply dilation effect to the video. 21655 21656This filter replaces the pixel by the local(3x3) maximum. 21657 21658It accepts the following options: 21659 21660@table @option 21661@item threshold0 21662@item threshold1 21663@item threshold2 21664@item threshold3 21665Limit the maximum change for each plane. Range is @code{[0, 65535]} and default value is @code{65535}. 21666If @code{0}, plane will remain unchanged. 21667 21668@item coordinates 21669Flag which specifies the pixel to refer to. 21670Range is @code{[0, 255]} and default value is @code{255}, i.e. all eight pixels are used. 21671 21672Flags to local 3x3 coordinates region centered on @code{x}: 21673 21674 1 2 3 21675 21676 4 x 5 21677 21678 6 7 8 21679@end table 21680 21681@subsection Example 21682 21683@itemize 21684@item 21685Apply 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. 21686@example 21687-i INPUT -vf "hwupload, dilation_opencl=30:40:50:coordinates=231, hwdownload" OUTPUT 21688@end example 21689@end itemize 21690 21691@section nlmeans_opencl 21692 21693Non-local Means denoise filter through OpenCL, this filter accepts same options as @ref{nlmeans}. 21694 21695@section overlay_opencl 21696 21697Overlay one video on top of another. 21698 21699It takes two inputs and has one output. The first input is the "main" video on which the second input is overlaid. 21700This filter requires same memory layout for all the inputs. So, format conversion may be needed. 21701 21702The filter accepts the following options: 21703 21704@table @option 21705 21706@item x 21707Set the x coordinate of the overlaid video on the main video. 21708Default value is @code{0}. 21709 21710@item y 21711Set the y coordinate of the overlaid video on the main video. 21712Default value is @code{0}. 21713 21714@end table 21715 21716@subsection Examples 21717 21718@itemize 21719@item 21720Overlay an image LOGO at the top-left corner of the INPUT video. Both inputs are yuv420p format. 21721@example 21722-i INPUT -i LOGO -filter_complex "[0:v]hwupload[a], [1:v]format=yuv420p, hwupload[b], [a][b]overlay_opencl, hwdownload" OUTPUT 21723@end example 21724@item 21725The inputs have same memory layout for color channels , the overlay has additional alpha plane, like INPUT is yuv420p, and the LOGO is yuva420p. 21726@example 21727-i INPUT -i LOGO -filter_complex "[0:v]hwupload[a], [1:v]format=yuva420p, hwupload[b], [a][b]overlay_opencl, hwdownload" OUTPUT 21728@end example 21729 21730@end itemize 21731 21732@section pad_opencl 21733 21734Add paddings to the input image, and place the original input at the 21735provided @var{x}, @var{y} coordinates. 21736 21737It accepts the following options: 21738 21739@table @option 21740@item width, w 21741@item height, h 21742Specify an expression for the size of the output image with the 21743paddings added. If the value for @var{width} or @var{height} is 0, the 21744corresponding input size is used for the output. 21745 21746The @var{width} expression can reference the value set by the 21747@var{height} expression, and vice versa. 21748 21749The default value of @var{width} and @var{height} is 0. 21750 21751@item x 21752@item y 21753Specify the offsets to place the input image at within the padded area, 21754with respect to the top/left border of the output image. 21755 21756The @var{x} expression can reference the value set by the @var{y} 21757expression, and vice versa. 21758 21759The default value of @var{x} and @var{y} is 0. 21760 21761If @var{x} or @var{y} evaluate to a negative number, they'll be changed 21762so the input image is centered on the padded area. 21763 21764@item color 21765Specify the color of the padded area. For the syntax of this option, 21766check the @ref{color syntax,,"Color" section in the ffmpeg-utils 21767manual,ffmpeg-utils}. 21768 21769@item aspect 21770Pad to an aspect instead to a resolution. 21771@end table 21772 21773The value for the @var{width}, @var{height}, @var{x}, and @var{y} 21774options are expressions containing the following constants: 21775 21776@table @option 21777@item in_w 21778@item in_h 21779The input video width and height. 21780 21781@item iw 21782@item ih 21783These are the same as @var{in_w} and @var{in_h}. 21784 21785@item out_w 21786@item out_h 21787The output width and height (the size of the padded area), as 21788specified by the @var{width} and @var{height} expressions. 21789 21790@item ow 21791@item oh 21792These are the same as @var{out_w} and @var{out_h}. 21793 21794@item x 21795@item y 21796The x and y offsets as specified by the @var{x} and @var{y} 21797expressions, or NAN if not yet specified. 21798 21799@item a 21800same as @var{iw} / @var{ih} 21801 21802@item sar 21803input sample aspect ratio 21804 21805@item dar 21806input display aspect ratio, it is the same as (@var{iw} / @var{ih}) * @var{sar} 21807@end table 21808 21809@section prewitt_opencl 21810 21811Apply the Prewitt operator (@url{https://en.wikipedia.org/wiki/Prewitt_operator}) to input video stream. 21812 21813The filter accepts the following option: 21814 21815@table @option 21816@item planes 21817Set which planes to filter. Default value is @code{0xf}, by which all planes are processed. 21818 21819@item scale 21820Set value which will be multiplied with filtered result. 21821Range is @code{[0.0, 65535]} and default value is @code{1.0}. 21822 21823@item delta 21824Set value which will be added to filtered result. 21825Range is @code{[-65535, 65535]} and default value is @code{0.0}. 21826@end table 21827 21828@subsection Example 21829 21830@itemize 21831@item 21832Apply the Prewitt operator with scale set to 2 and delta set to 10. 21833@example 21834-i INPUT -vf "hwupload, prewitt_opencl=scale=2:delta=10, hwdownload" OUTPUT 21835@end example 21836@end itemize 21837 21838@anchor{program_opencl} 21839@section program_opencl 21840 21841Filter video using an OpenCL program. 21842 21843@table @option 21844 21845@item source 21846OpenCL program source file. 21847 21848@item kernel 21849Kernel name in program. 21850 21851@item inputs 21852Number of inputs to the filter. Defaults to 1. 21853 21854@item size, s 21855Size of output frames. Defaults to the same as the first input. 21856 21857@end table 21858 21859The @code{program_opencl} filter also supports the @ref{framesync} options. 21860 21861The program source file must contain a kernel function with the given name, 21862which will be run once for each plane of the output. Each run on a plane 21863gets enqueued as a separate 2D global NDRange with one work-item for each 21864pixel to be generated. The global ID offset for each work-item is therefore 21865the coordinates of a pixel in the destination image. 21866 21867The kernel function needs to take the following arguments: 21868@itemize 21869@item 21870Destination image, @var{__write_only image2d_t}. 21871 21872This image will become the output; the kernel should write all of it. 21873@item 21874Frame index, @var{unsigned int}. 21875 21876This is a counter starting from zero and increasing by one for each frame. 21877@item 21878Source images, @var{__read_only image2d_t}. 21879 21880These are the most recent images on each input. The kernel may read from 21881them to generate the output, but they can't be written to. 21882@end itemize 21883 21884Example programs: 21885 21886@itemize 21887@item 21888Copy the input to the output (output must be the same size as the input). 21889@verbatim 21890__kernel void copy(__write_only image2d_t destination, 21891 unsigned int index, 21892 __read_only image2d_t source) 21893{ 21894 const sampler_t sampler = CLK_NORMALIZED_COORDS_FALSE; 21895 21896 int2 location = (int2)(get_global_id(0), get_global_id(1)); 21897 21898 float4 value = read_imagef(source, sampler, location); 21899 21900 write_imagef(destination, location, value); 21901} 21902@end verbatim 21903 21904@item 21905Apply a simple transformation, rotating the input by an amount increasing 21906with the index counter. Pixel values are linearly interpolated by the 21907sampler, and the output need not have the same dimensions as the input. 21908@verbatim 21909__kernel void rotate_image(__write_only image2d_t dst, 21910 unsigned int index, 21911 __read_only image2d_t src) 21912{ 21913 const sampler_t sampler = (CLK_NORMALIZED_COORDS_FALSE | 21914 CLK_FILTER_LINEAR); 21915 21916 float angle = (float)index / 100.0f; 21917 21918 float2 dst_dim = convert_float2(get_image_dim(dst)); 21919 float2 src_dim = convert_float2(get_image_dim(src)); 21920 21921 float2 dst_cen = dst_dim / 2.0f; 21922 float2 src_cen = src_dim / 2.0f; 21923 21924 int2 dst_loc = (int2)(get_global_id(0), get_global_id(1)); 21925 21926 float2 dst_pos = convert_float2(dst_loc) - dst_cen; 21927 float2 src_pos = { 21928 cos(angle) * dst_pos.x - sin(angle) * dst_pos.y, 21929 sin(angle) * dst_pos.x + cos(angle) * dst_pos.y 21930 }; 21931 src_pos = src_pos * src_dim / dst_dim; 21932 21933 float2 src_loc = src_pos + src_cen; 21934 21935 if (src_loc.x < 0.0f || src_loc.y < 0.0f || 21936 src_loc.x > src_dim.x || src_loc.y > src_dim.y) 21937 write_imagef(dst, dst_loc, 0.5f); 21938 else 21939 write_imagef(dst, dst_loc, read_imagef(src, sampler, src_loc)); 21940} 21941@end verbatim 21942 21943@item 21944Blend two inputs together, with the amount of each input used varying 21945with the index counter. 21946@verbatim 21947__kernel void blend_images(__write_only image2d_t dst, 21948 unsigned int index, 21949 __read_only image2d_t src1, 21950 __read_only image2d_t src2) 21951{ 21952 const sampler_t sampler = (CLK_NORMALIZED_COORDS_FALSE | 21953 CLK_FILTER_LINEAR); 21954 21955 float blend = (cos((float)index / 50.0f) + 1.0f) / 2.0f; 21956 21957 int2 dst_loc = (int2)(get_global_id(0), get_global_id(1)); 21958 int2 src1_loc = dst_loc * get_image_dim(src1) / get_image_dim(dst); 21959 int2 src2_loc = dst_loc * get_image_dim(src2) / get_image_dim(dst); 21960 21961 float4 val1 = read_imagef(src1, sampler, src1_loc); 21962 float4 val2 = read_imagef(src2, sampler, src2_loc); 21963 21964 write_imagef(dst, dst_loc, val1 * blend + val2 * (1.0f - blend)); 21965} 21966@end verbatim 21967 21968@end itemize 21969 21970@section roberts_opencl 21971Apply the Roberts cross operator (@url{https://en.wikipedia.org/wiki/Roberts_cross}) to input video stream. 21972 21973The filter accepts the following option: 21974 21975@table @option 21976@item planes 21977Set which planes to filter. Default value is @code{0xf}, by which all planes are processed. 21978 21979@item scale 21980Set value which will be multiplied with filtered result. 21981Range is @code{[0.0, 65535]} and default value is @code{1.0}. 21982 21983@item delta 21984Set value which will be added to filtered result. 21985Range is @code{[-65535, 65535]} and default value is @code{0.0}. 21986@end table 21987 21988@subsection Example 21989 21990@itemize 21991@item 21992Apply the Roberts cross operator with scale set to 2 and delta set to 10 21993@example 21994-i INPUT -vf "hwupload, roberts_opencl=scale=2:delta=10, hwdownload" OUTPUT 21995@end example 21996@end itemize 21997 21998@section sobel_opencl 21999 22000Apply the Sobel operator (@url{https://en.wikipedia.org/wiki/Sobel_operator}) to input video stream. 22001 22002The filter accepts the following option: 22003 22004@table @option 22005@item planes 22006Set which planes to filter. Default value is @code{0xf}, by which all planes are processed. 22007 22008@item scale 22009Set value which will be multiplied with filtered result. 22010Range is @code{[0.0, 65535]} and default value is @code{1.0}. 22011 22012@item delta 22013Set value which will be added to filtered result. 22014Range is @code{[-65535, 65535]} and default value is @code{0.0}. 22015@end table 22016 22017@subsection Example 22018 22019@itemize 22020@item 22021Apply sobel operator with scale set to 2 and delta set to 10 22022@example 22023-i INPUT -vf "hwupload, sobel_opencl=scale=2:delta=10, hwdownload" OUTPUT 22024@end example 22025@end itemize 22026 22027@section tonemap_opencl 22028 22029Perform HDR(PQ/HLG) to SDR conversion with tone-mapping. 22030 22031It accepts the following parameters: 22032 22033@table @option 22034@item tonemap 22035Specify the tone-mapping operator to be used. Same as tonemap option in @ref{tonemap}. 22036 22037@item param 22038Tune the tone mapping algorithm. same as param option in @ref{tonemap}. 22039 22040@item desat 22041Apply desaturation for highlights that exceed this level of brightness. The 22042higher the parameter, the more color information will be preserved. This 22043setting helps prevent unnaturally blown-out colors for super-highlights, by 22044(smoothly) turning into white instead. This makes images feel more natural, 22045at the cost of reducing information about out-of-range colors. 22046 22047The default value is 0.5, and the algorithm here is a little different from 22048the cpu version tonemap currently. A setting of 0.0 disables this option. 22049 22050@item threshold 22051The tonemapping algorithm parameters is fine-tuned per each scene. And a threshold 22052is used to detect whether the scene has changed or not. If the distance between 22053the current frame average brightness and the current running average exceeds 22054a threshold value, we would re-calculate scene average and peak brightness. 22055The default value is 0.2. 22056 22057@item format 22058Specify the output pixel format. 22059 22060Currently supported formats are: 22061@table @var 22062@item p010 22063@item nv12 22064@end table 22065 22066@item range, r 22067Set the output color range. 22068 22069Possible values are: 22070@table @var 22071@item tv/mpeg 22072@item pc/jpeg 22073@end table 22074 22075Default is same as input. 22076 22077@item primaries, p 22078Set the output color primaries. 22079 22080Possible values are: 22081@table @var 22082@item bt709 22083@item bt2020 22084@end table 22085 22086Default is same as input. 22087 22088@item transfer, t 22089Set the output transfer characteristics. 22090 22091Possible values are: 22092@table @var 22093@item bt709 22094@item bt2020 22095@end table 22096 22097Default is bt709. 22098 22099@item matrix, m 22100Set the output colorspace matrix. 22101 22102Possible value are: 22103@table @var 22104@item bt709 22105@item bt2020 22106@end table 22107 22108Default is same as input. 22109 22110@end table 22111 22112@subsection Example 22113 22114@itemize 22115@item 22116Convert HDR(PQ/HLG) video to bt2020-transfer-characteristic p010 format using linear operator. 22117@example 22118-i INPUT -vf "format=p010,hwupload,tonemap_opencl=t=bt2020:tonemap=linear:format=p010,hwdownload,format=p010" OUTPUT 22119@end example 22120@end itemize 22121 22122@section unsharp_opencl 22123 22124Sharpen or blur the input video. 22125 22126It accepts the following parameters: 22127 22128@table @option 22129@item luma_msize_x, lx 22130Set the luma matrix horizontal size. 22131Range is @code{[1, 23]} and default value is @code{5}. 22132 22133@item luma_msize_y, ly 22134Set the luma matrix vertical size. 22135Range is @code{[1, 23]} and default value is @code{5}. 22136 22137@item luma_amount, la 22138Set the luma effect strength. 22139Range is @code{[-10, 10]} and default value is @code{1.0}. 22140 22141Negative values will blur the input video, while positive values will 22142sharpen it, a value of zero will disable the effect. 22143 22144@item chroma_msize_x, cx 22145Set the chroma matrix horizontal size. 22146Range is @code{[1, 23]} and default value is @code{5}. 22147 22148@item chroma_msize_y, cy 22149Set the chroma matrix vertical size. 22150Range is @code{[1, 23]} and default value is @code{5}. 22151 22152@item chroma_amount, ca 22153Set the chroma effect strength. 22154Range is @code{[-10, 10]} and default value is @code{0.0}. 22155 22156Negative values will blur the input video, while positive values will 22157sharpen it, a value of zero will disable the effect. 22158 22159@end table 22160 22161All parameters are optional and default to the equivalent of the 22162string '5:5:1.0:5:5:0.0'. 22163 22164@subsection Examples 22165 22166@itemize 22167@item 22168Apply strong luma sharpen effect: 22169@example 22170-i INPUT -vf "hwupload, unsharp_opencl=luma_msize_x=7:luma_msize_y=7:luma_amount=2.5, hwdownload" OUTPUT 22171@end example 22172 22173@item 22174Apply a strong blur of both luma and chroma parameters: 22175@example 22176-i INPUT -vf "hwupload, unsharp_opencl=7:7:-2:7:7:-2, hwdownload" OUTPUT 22177@end example 22178@end itemize 22179 22180@section xfade_opencl 22181 22182Cross fade two videos with custom transition effect by using OpenCL. 22183 22184It accepts the following options: 22185 22186@table @option 22187@item transition 22188Set one of possible transition effects. 22189 22190@table @option 22191@item custom 22192Select custom transition effect, the actual transition description 22193will be picked from source and kernel options. 22194 22195@item fade 22196@item wipeleft 22197@item wiperight 22198@item wipeup 22199@item wipedown 22200@item slideleft 22201@item slideright 22202@item slideup 22203@item slidedown 22204 22205Default transition is fade. 22206@end table 22207 22208@item source 22209OpenCL program source file for custom transition. 22210 22211@item kernel 22212Set name of kernel to use for custom transition from program source file. 22213 22214@item duration 22215Set duration of video transition. 22216 22217@item offset 22218Set time of start of transition relative to first video. 22219@end table 22220 22221The program source file must contain a kernel function with the given name, 22222which will be run once for each plane of the output. Each run on a plane 22223gets enqueued as a separate 2D global NDRange with one work-item for each 22224pixel to be generated. The global ID offset for each work-item is therefore 22225the coordinates of a pixel in the destination image. 22226 22227The kernel function needs to take the following arguments: 22228@itemize 22229@item 22230Destination image, @var{__write_only image2d_t}. 22231 22232This image will become the output; the kernel should write all of it. 22233 22234@item 22235First Source image, @var{__read_only image2d_t}. 22236Second Source image, @var{__read_only image2d_t}. 22237 22238These are the most recent images on each input. The kernel may read from 22239them to generate the output, but they can't be written to. 22240 22241@item 22242Transition progress, @var{float}. This value is always between 0 and 1 inclusive. 22243@end itemize 22244 22245Example programs: 22246 22247@itemize 22248@item 22249Apply dots curtain transition effect: 22250@verbatim 22251__kernel void blend_images(__write_only image2d_t dst, 22252 __read_only image2d_t src1, 22253 __read_only image2d_t src2, 22254 float progress) 22255{ 22256 const sampler_t sampler = (CLK_NORMALIZED_COORDS_FALSE | 22257 CLK_FILTER_LINEAR); 22258 int2 p = (int2)(get_global_id(0), get_global_id(1)); 22259 float2 rp = (float2)(get_global_id(0), get_global_id(1)); 22260 float2 dim = (float2)(get_image_dim(src1).x, get_image_dim(src1).y); 22261 rp = rp / dim; 22262 22263 float2 dots = (float2)(20.0, 20.0); 22264 float2 center = (float2)(0,0); 22265 float2 unused; 22266 22267 float4 val1 = read_imagef(src1, sampler, p); 22268 float4 val2 = read_imagef(src2, sampler, p); 22269 bool next = distance(fract(rp * dots, &unused), (float2)(0.5, 0.5)) < (progress / distance(rp, center)); 22270 22271 write_imagef(dst, p, next ? val1 : val2); 22272} 22273@end verbatim 22274 22275@end itemize 22276 22277@c man end OPENCL VIDEO FILTERS 22278 22279@chapter VAAPI Video Filters 22280@c man begin VAAPI VIDEO FILTERS 22281 22282VAAPI Video filters are usually used with VAAPI decoder and VAAPI encoder. Below is a description of VAAPI video filters. 22283 22284To enable compilation of these filters you need to configure FFmpeg with 22285@code{--enable-vaapi}. 22286 22287To use vaapi filters, you need to setup the vaapi device correctly. For more information, please read @url{https://trac.ffmpeg.org/wiki/Hardware/VAAPI} 22288 22289@section tonemap_vaapi 22290 22291Perform HDR(High Dynamic Range) to SDR(Standard Dynamic Range) conversion with tone-mapping. 22292It maps the dynamic range of HDR10 content to the SDR content. 22293It currently only accepts HDR10 as input. 22294 22295It accepts the following parameters: 22296 22297@table @option 22298@item format 22299Specify the output pixel format. 22300 22301Currently supported formats are: 22302@table @var 22303@item p010 22304@item nv12 22305@end table 22306 22307Default is nv12. 22308 22309@item primaries, p 22310Set the output color primaries. 22311 22312Default is same as input. 22313 22314@item transfer, t 22315Set the output transfer characteristics. 22316 22317Default is bt709. 22318 22319@item matrix, m 22320Set the output colorspace matrix. 22321 22322Default is same as input. 22323 22324@end table 22325 22326@subsection Example 22327 22328@itemize 22329@item 22330Convert HDR(HDR10) video to bt2020-transfer-characteristic p010 format 22331@example 22332tonemap_vaapi=format=p010:t=bt2020-10 22333@end example 22334@end itemize 22335 22336@c man end VAAPI VIDEO FILTERS 22337 22338@chapter Video Sources 22339@c man begin VIDEO SOURCES 22340 22341Below is a description of the currently available video sources. 22342 22343@section buffer 22344 22345Buffer video frames, and make them available to the filter chain. 22346 22347This source is mainly intended for a programmatic use, in particular 22348through the interface defined in @file{libavfilter/buffersrc.h}. 22349 22350It accepts the following parameters: 22351 22352@table @option 22353 22354@item video_size 22355Specify the size (width and height) of the buffered video frames. For the 22356syntax of this option, check the 22357@ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}. 22358 22359@item width 22360The input video width. 22361 22362@item height 22363The input video height. 22364 22365@item pix_fmt 22366A string representing the pixel format of the buffered video frames. 22367It may be a number corresponding to a pixel format, or a pixel format 22368name. 22369 22370@item time_base 22371Specify the timebase assumed by the timestamps of the buffered frames. 22372 22373@item frame_rate 22374Specify the frame rate expected for the video stream. 22375 22376@item pixel_aspect, sar 22377The sample (pixel) aspect ratio of the input video. 22378 22379@item sws_param 22380This option is deprecated and ignored. Prepend @code{sws_flags=@var{flags};} 22381to the filtergraph description to specify swscale flags for automatically 22382inserted scalers. See @ref{Filtergraph syntax}. 22383 22384@item hw_frames_ctx 22385When using a hardware pixel format, this should be a reference to an 22386AVHWFramesContext describing input frames. 22387@end table 22388 22389For example: 22390@example 22391buffer=width=320:height=240:pix_fmt=yuv410p:time_base=1/24:sar=1 22392@end example 22393 22394will instruct the source to accept video frames with size 320x240 and 22395with format "yuv410p", assuming 1/24 as the timestamps timebase and 22396square pixels (1:1 sample aspect ratio). 22397Since the pixel format with name "yuv410p" corresponds to the number 6 22398(check the enum AVPixelFormat definition in @file{libavutil/pixfmt.h}), 22399this example corresponds to: 22400@example 22401buffer=size=320x240:pixfmt=6:time_base=1/24:pixel_aspect=1/1 22402@end example 22403 22404Alternatively, the options can be specified as a flat string, but this 22405syntax is deprecated: 22406 22407@var{width}:@var{height}:@var{pix_fmt}:@var{time_base.num}:@var{time_base.den}:@var{pixel_aspect.num}:@var{pixel_aspect.den} 22408 22409@section cellauto 22410 22411Create a pattern generated by an elementary cellular automaton. 22412 22413The initial state of the cellular automaton can be defined through the 22414@option{filename} and @option{pattern} options. If such options are 22415not specified an initial state is created randomly. 22416 22417At each new frame a new row in the video is filled with the result of 22418the cellular automaton next generation. The behavior when the whole 22419frame is filled is defined by the @option{scroll} option. 22420 22421This source accepts the following options: 22422 22423@table @option 22424@item filename, f 22425Read the initial cellular automaton state, i.e. the starting row, from 22426the specified file. 22427In the file, each non-whitespace character is considered an alive 22428cell, a newline will terminate the row, and further characters in the 22429file will be ignored. 22430 22431@item pattern, p 22432Read the initial cellular automaton state, i.e. the starting row, from 22433the specified string. 22434 22435Each non-whitespace character in the string is considered an alive 22436cell, a newline will terminate the row, and further characters in the 22437string will be ignored. 22438 22439@item rate, r 22440Set the video rate, that is the number of frames generated per second. 22441Default is 25. 22442 22443@item random_fill_ratio, ratio 22444Set the random fill ratio for the initial cellular automaton row. It 22445is a floating point number value ranging from 0 to 1, defaults to 224461/PHI. 22447 22448This option is ignored when a file or a pattern is specified. 22449 22450@item random_seed, seed 22451Set the seed for filling randomly the initial row, must be an integer 22452included between 0 and UINT32_MAX. If not specified, or if explicitly 22453set to -1, the filter will try to use a good random seed on a best 22454effort basis. 22455 22456@item rule 22457Set the cellular automaton rule, it is a number ranging from 0 to 255. 22458Default value is 110. 22459 22460@item size, s 22461Set the size of the output video. For the syntax of this option, check the 22462@ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}. 22463 22464If @option{filename} or @option{pattern} is specified, the size is set 22465by default to the width of the specified initial state row, and the 22466height is set to @var{width} * PHI. 22467 22468If @option{size} is set, it must contain the width of the specified 22469pattern string, and the specified pattern will be centered in the 22470larger row. 22471 22472If a filename or a pattern string is not specified, the size value 22473defaults to "320x518" (used for a randomly generated initial state). 22474 22475@item scroll 22476If set to 1, scroll the output upward when all the rows in the output 22477have been already filled. If set to 0, the new generated row will be 22478written over the top row just after the bottom row is filled. 22479Defaults to 1. 22480 22481@item start_full, full 22482If set to 1, completely fill the output with generated rows before 22483outputting the first frame. 22484This is the default behavior, for disabling set the value to 0. 22485 22486@item stitch 22487If set to 1, stitch the left and right row edges together. 22488This is the default behavior, for disabling set the value to 0. 22489@end table 22490 22491@subsection Examples 22492 22493@itemize 22494@item 22495Read the initial state from @file{pattern}, and specify an output of 22496size 200x400. 22497@example 22498cellauto=f=pattern:s=200x400 22499@end example 22500 22501@item 22502Generate a random initial row with a width of 200 cells, with a fill 22503ratio of 2/3: 22504@example 22505cellauto=ratio=2/3:s=200x200 22506@end example 22507 22508@item 22509Create a pattern generated by rule 18 starting by a single alive cell 22510centered on an initial row with width 100: 22511@example 22512cellauto=p=@@:s=100x400:full=0:rule=18 22513@end example 22514 22515@item 22516Specify a more elaborated initial pattern: 22517@example 22518cellauto=p='@@@@ @@ @@@@':s=100x400:full=0:rule=18 22519@end example 22520 22521@end itemize 22522 22523@anchor{coreimagesrc} 22524@section coreimagesrc 22525Video source generated on GPU using Apple's CoreImage API on OSX. 22526 22527This video source is a specialized version of the @ref{coreimage} video filter. 22528Use a core image generator at the beginning of the applied filterchain to 22529generate the content. 22530 22531The coreimagesrc video source accepts the following options: 22532@table @option 22533@item list_generators 22534List all available generators along with all their respective options as well as 22535possible minimum and maximum values along with the default values. 22536@example 22537list_generators=true 22538@end example 22539 22540@item size, s 22541Specify the size of the sourced video. For the syntax of this option, check the 22542@ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}. 22543The default value is @code{320x240}. 22544 22545@item rate, r 22546Specify the frame rate of the sourced video, as the number of frames 22547generated per second. It has to be a string in the format 22548@var{frame_rate_num}/@var{frame_rate_den}, an integer number, a floating point 22549number or a valid video frame rate abbreviation. The default value is 22550"25". 22551 22552@item sar 22553Set the sample aspect ratio of the sourced video. 22554 22555@item duration, d 22556Set the duration of the sourced video. See 22557@ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils} 22558for the accepted syntax. 22559 22560If not specified, or the expressed duration is negative, the video is 22561supposed to be generated forever. 22562@end table 22563 22564Additionally, all options of the @ref{coreimage} video filter are accepted. 22565A complete filterchain can be used for further processing of the 22566generated input without CPU-HOST transfer. See @ref{coreimage} documentation 22567and examples for details. 22568 22569@subsection Examples 22570 22571@itemize 22572 22573@item 22574Use CIQRCodeGenerator to create a QR code for the FFmpeg homepage, 22575given as complete and escaped command-line for Apple's standard bash shell: 22576@example 22577ffmpeg -f lavfi -i coreimagesrc=s=100x100:filter=CIQRCodeGenerator@@inputMessage=https\\\\\://FFmpeg.org/@@inputCorrectionLevel=H -frames:v 1 QRCode.png 22578@end example 22579This example is equivalent to the QRCode example of @ref{coreimage} without the 22580need for a nullsrc video source. 22581@end itemize 22582 22583 22584@section gradients 22585Generate several gradients. 22586 22587@table @option 22588@item size, s 22589Set frame size. For the syntax of this option, check the @ref{video size syntax,,"Video 22590size" section in the ffmpeg-utils manual,ffmpeg-utils}. Default value is "640x480". 22591 22592@item rate, r 22593Set frame rate, expressed as number of frames per second. Default 22594value is "25". 22595 22596@item c0, c1, c2, c3, c4, c5, c6, c7 22597Set 8 colors. Default values for colors is to pick random one. 22598 22599@item x0, y0, y0, y1 22600Set gradient line source and destination points. If negative or out of range, random ones 22601are picked. 22602 22603@item nb_colors, n 22604Set number of colors to use at once. Allowed range is from 2 to 8. Default value is 2. 22605 22606@item seed 22607Set seed for picking gradient line points. 22608 22609@item duration, d 22610Set the duration of the sourced video. See 22611@ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils} 22612for the accepted syntax. 22613 22614If not specified, or the expressed duration is negative, the video is 22615supposed to be generated forever. 22616 22617@item speed 22618Set speed of gradients rotation. 22619@end table 22620 22621 22622@section mandelbrot 22623 22624Generate a Mandelbrot set fractal, and progressively zoom towards the 22625point specified with @var{start_x} and @var{start_y}. 22626 22627This source accepts the following options: 22628 22629@table @option 22630 22631@item end_pts 22632Set the terminal pts value. Default value is 400. 22633 22634@item end_scale 22635Set the terminal scale value. 22636Must be a floating point value. Default value is 0.3. 22637 22638@item inner 22639Set the inner coloring mode, that is the algorithm used to draw the 22640Mandelbrot fractal internal region. 22641 22642It shall assume one of the following values: 22643@table @option 22644@item black 22645Set black mode. 22646@item convergence 22647Show time until convergence. 22648@item mincol 22649Set color based on point closest to the origin of the iterations. 22650@item period 22651Set period mode. 22652@end table 22653 22654Default value is @var{mincol}. 22655 22656@item bailout 22657Set the bailout value. Default value is 10.0. 22658 22659@item maxiter 22660Set the maximum of iterations performed by the rendering 22661algorithm. Default value is 7189. 22662 22663@item outer 22664Set outer coloring mode. 22665It shall assume one of following values: 22666@table @option 22667@item iteration_count 22668Set iteration count mode. 22669@item normalized_iteration_count 22670set normalized iteration count mode. 22671@end table 22672Default value is @var{normalized_iteration_count}. 22673 22674@item rate, r 22675Set frame rate, expressed as number of frames per second. Default 22676value is "25". 22677 22678@item size, s 22679Set frame size. For the syntax of this option, check the @ref{video size syntax,,"Video 22680size" section in the ffmpeg-utils manual,ffmpeg-utils}. Default value is "640x480". 22681 22682@item start_scale 22683Set the initial scale value. Default value is 3.0. 22684 22685@item start_x 22686Set the initial x position. Must be a floating point value between 22687-100 and 100. Default value is -0.743643887037158704752191506114774. 22688 22689@item start_y 22690Set the initial y position. Must be a floating point value between 22691-100 and 100. Default value is -0.131825904205311970493132056385139. 22692@end table 22693 22694@section mptestsrc 22695 22696Generate various test patterns, as generated by the MPlayer test filter. 22697 22698The size of the generated video is fixed, and is 256x256. 22699This source is useful in particular for testing encoding features. 22700 22701This source accepts the following options: 22702 22703@table @option 22704 22705@item rate, r 22706Specify the frame rate of the sourced video, as the number of frames 22707generated per second. It has to be a string in the format 22708@var{frame_rate_num}/@var{frame_rate_den}, an integer number, a floating point 22709number or a valid video frame rate abbreviation. The default value is 22710"25". 22711 22712@item duration, d 22713Set the duration of the sourced video. See 22714@ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils} 22715for the accepted syntax. 22716 22717If not specified, or the expressed duration is negative, the video is 22718supposed to be generated forever. 22719 22720@item test, t 22721 22722Set the number or the name of the test to perform. Supported tests are: 22723@table @option 22724@item dc_luma 22725@item dc_chroma 22726@item freq_luma 22727@item freq_chroma 22728@item amp_luma 22729@item amp_chroma 22730@item cbp 22731@item mv 22732@item ring1 22733@item ring2 22734@item all 22735 22736@item max_frames, m 22737Set the maximum number of frames generated for each test, default value is 30. 22738 22739@end table 22740 22741Default value is "all", which will cycle through the list of all tests. 22742@end table 22743 22744Some examples: 22745@example 22746mptestsrc=t=dc_luma 22747@end example 22748 22749will generate a "dc_luma" test pattern. 22750 22751@section frei0r_src 22752 22753Provide a frei0r source. 22754 22755To enable compilation of this filter you need to install the frei0r 22756header and configure FFmpeg with @code{--enable-frei0r}. 22757 22758This source accepts the following parameters: 22759 22760@table @option 22761 22762@item size 22763The size of the video to generate. For the syntax of this option, check the 22764@ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}. 22765 22766@item framerate 22767The framerate of the generated video. It may be a string of the form 22768@var{num}/@var{den} or a frame rate abbreviation. 22769 22770@item filter_name 22771The name to the frei0r source to load. For more information regarding frei0r and 22772how to set the parameters, read the @ref{frei0r} section in the video filters 22773documentation. 22774 22775@item filter_params 22776A '|'-separated list of parameters to pass to the frei0r source. 22777 22778@end table 22779 22780For example, to generate a frei0r partik0l source with size 200x200 22781and frame rate 10 which is overlaid on the overlay filter main input: 22782@example 22783frei0r_src=size=200x200:framerate=10:filter_name=partik0l:filter_params=1234 [overlay]; [in][overlay] overlay 22784@end example 22785 22786@section life 22787 22788Generate a life pattern. 22789 22790This source is based on a generalization of John Conway's life game. 22791 22792The sourced input represents a life grid, each pixel represents a cell 22793which can be in one of two possible states, alive or dead. Every cell 22794interacts with its eight neighbours, which are the cells that are 22795horizontally, vertically, or diagonally adjacent. 22796 22797At each interaction the grid evolves according to the adopted rule, 22798which specifies the number of neighbor alive cells which will make a 22799cell stay alive or born. The @option{rule} option allows one to specify 22800the rule to adopt. 22801 22802This source accepts the following options: 22803 22804@table @option 22805@item filename, f 22806Set the file from which to read the initial grid state. In the file, 22807each non-whitespace character is considered an alive cell, and newline 22808is used to delimit the end of each row. 22809 22810If this option is not specified, the initial grid is generated 22811randomly. 22812 22813@item rate, r 22814Set the video rate, that is the number of frames generated per second. 22815Default is 25. 22816 22817@item random_fill_ratio, ratio 22818Set the random fill ratio for the initial random grid. It is a 22819floating point number value ranging from 0 to 1, defaults to 1/PHI. 22820It is ignored when a file is specified. 22821 22822@item random_seed, seed 22823Set the seed for filling the initial random grid, must be an integer 22824included between 0 and UINT32_MAX. If not specified, or if explicitly 22825set to -1, the filter will try to use a good random seed on a best 22826effort basis. 22827 22828@item rule 22829Set the life rule. 22830 22831A rule can be specified with a code of the kind "S@var{NS}/B@var{NB}", 22832where @var{NS} and @var{NB} are sequences of numbers in the range 0-8, 22833@var{NS} specifies the number of alive neighbor cells which make a 22834live cell stay alive, and @var{NB} the number of alive neighbor cells 22835which make a dead cell to become alive (i.e. to "born"). 22836"s" and "b" can be used in place of "S" and "B", respectively. 22837 22838Alternatively a rule can be specified by an 18-bits integer. The 9 22839high order bits are used to encode the next cell state if it is alive 22840for each number of neighbor alive cells, the low order bits specify 22841the rule for "borning" new cells. Higher order bits encode for an 22842higher number of neighbor cells. 22843For example the number 6153 = @code{(12<<9)+9} specifies a stay alive 22844rule of 12 and a born rule of 9, which corresponds to "S23/B03". 22845 22846Default value is "S23/B3", which is the original Conway's game of life 22847rule, and will keep a cell alive if it has 2 or 3 neighbor alive 22848cells, and will born a new cell if there are three alive cells around 22849a dead cell. 22850 22851@item size, s 22852Set the size of the output video. For the syntax of this option, check the 22853@ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}. 22854 22855If @option{filename} is specified, the size is set by default to the 22856same size of the input file. If @option{size} is set, it must contain 22857the size specified in the input file, and the initial grid defined in 22858that file is centered in the larger resulting area. 22859 22860If a filename is not specified, the size value defaults to "320x240" 22861(used for a randomly generated initial grid). 22862 22863@item stitch 22864If set to 1, stitch the left and right grid edges together, and the 22865top and bottom edges also. Defaults to 1. 22866 22867@item mold 22868Set cell mold speed. If set, a dead cell will go from @option{death_color} to 22869@option{mold_color} with a step of @option{mold}. @option{mold} can have a 22870value from 0 to 255. 22871 22872@item life_color 22873Set the color of living (or new born) cells. 22874 22875@item death_color 22876Set the color of dead cells. If @option{mold} is set, this is the first color 22877used to represent a dead cell. 22878 22879@item mold_color 22880Set mold color, for definitely dead and moldy cells. 22881 22882For the syntax of these 3 color options, check the @ref{color syntax,,"Color" section in the 22883ffmpeg-utils manual,ffmpeg-utils}. 22884@end table 22885 22886@subsection Examples 22887 22888@itemize 22889@item 22890Read a grid from @file{pattern}, and center it on a grid of size 22891300x300 pixels: 22892@example 22893life=f=pattern:s=300x300 22894@end example 22895 22896@item 22897Generate a random grid of size 200x200, with a fill ratio of 2/3: 22898@example 22899life=ratio=2/3:s=200x200 22900@end example 22901 22902@item 22903Specify a custom rule for evolving a randomly generated grid: 22904@example 22905life=rule=S14/B34 22906@end example 22907 22908@item 22909Full example with slow death effect (mold) using @command{ffplay}: 22910@example 22911ffplay -f lavfi life=s=300x200:mold=10:r=60:ratio=0.1:death_color=#C83232:life_color=#00ff00,scale=1200:800:flags=16 22912@end example 22913@end itemize 22914 22915@anchor{allrgb} 22916@anchor{allyuv} 22917@anchor{color} 22918@anchor{haldclutsrc} 22919@anchor{nullsrc} 22920@anchor{pal75bars} 22921@anchor{pal100bars} 22922@anchor{rgbtestsrc} 22923@anchor{smptebars} 22924@anchor{smptehdbars} 22925@anchor{testsrc} 22926@anchor{testsrc2} 22927@anchor{yuvtestsrc} 22928@section allrgb, allyuv, color, haldclutsrc, nullsrc, pal75bars, pal100bars, rgbtestsrc, smptebars, smptehdbars, testsrc, testsrc2, yuvtestsrc 22929 22930The @code{allrgb} source returns frames of size 4096x4096 of all rgb colors. 22931 22932The @code{allyuv} source returns frames of size 4096x4096 of all yuv colors. 22933 22934The @code{color} source provides an uniformly colored input. 22935 22936The @code{haldclutsrc} source provides an identity Hald CLUT. See also 22937@ref{haldclut} filter. 22938 22939The @code{nullsrc} source returns unprocessed video frames. It is 22940mainly useful to be employed in analysis / debugging tools, or as the 22941source for filters which ignore the input data. 22942 22943The @code{pal75bars} source generates a color bars pattern, based on 22944EBU PAL recommendations with 75% color levels. 22945 22946The @code{pal100bars} source generates a color bars pattern, based on 22947EBU PAL recommendations with 100% color levels. 22948 22949The @code{rgbtestsrc} source generates an RGB test pattern useful for 22950detecting RGB vs BGR issues. You should see a red, green and blue 22951stripe from top to bottom. 22952 22953The @code{smptebars} source generates a color bars pattern, based on 22954the SMPTE Engineering Guideline EG 1-1990. 22955 22956The @code{smptehdbars} source generates a color bars pattern, based on 22957the SMPTE RP 219-2002. 22958 22959The @code{testsrc} source generates a test video pattern, showing a 22960color pattern, a scrolling gradient and a timestamp. This is mainly 22961intended for testing purposes. 22962 22963The @code{testsrc2} source is similar to testsrc, but supports more 22964pixel formats instead of just @code{rgb24}. This allows using it as an 22965input for other tests without requiring a format conversion. 22966 22967The @code{yuvtestsrc} source generates an YUV test pattern. You should 22968see a y, cb and cr stripe from top to bottom. 22969 22970The sources accept the following parameters: 22971 22972@table @option 22973 22974@item level 22975Specify the level of the Hald CLUT, only available in the @code{haldclutsrc} 22976source. A level of @code{N} generates a picture of @code{N*N*N} by @code{N*N*N} 22977pixels to be used as identity matrix for 3D lookup tables. Each component is 22978coded on a @code{1/(N*N)} scale. 22979 22980@item color, c 22981Specify the color of the source, only available in the @code{color} 22982source. For the syntax of this option, check the 22983@ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}. 22984 22985@item size, s 22986Specify the size of the sourced video. For the syntax of this option, check the 22987@ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}. 22988The default value is @code{320x240}. 22989 22990This option is not available with the @code{allrgb}, @code{allyuv}, and 22991@code{haldclutsrc} filters. 22992 22993@item rate, r 22994Specify the frame rate of the sourced video, as the number of frames 22995generated per second. It has to be a string in the format 22996@var{frame_rate_num}/@var{frame_rate_den}, an integer number, a floating point 22997number or a valid video frame rate abbreviation. The default value is 22998"25". 22999 23000@item duration, d 23001Set the duration of the sourced video. See 23002@ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils} 23003for the accepted syntax. 23004 23005If not specified, or the expressed duration is negative, the video is 23006supposed to be generated forever. 23007 23008Since the frame rate is used as time base, all frames including the last one 23009will have their full duration. If the specified duration is not a multiple 23010of the frame duration, it will be rounded up. 23011 23012@item sar 23013Set the sample aspect ratio of the sourced video. 23014 23015@item alpha 23016Specify the alpha (opacity) of the background, only available in the 23017@code{testsrc2} source. The value must be between 0 (fully transparent) and 23018255 (fully opaque, the default). 23019 23020@item decimals, n 23021Set the number of decimals to show in the timestamp, only available in the 23022@code{testsrc} source. 23023 23024The displayed timestamp value will correspond to the original 23025timestamp value multiplied by the power of 10 of the specified 23026value. Default value is 0. 23027@end table 23028 23029@subsection Examples 23030 23031@itemize 23032@item 23033Generate a video with a duration of 5.3 seconds, with size 23034176x144 and a frame rate of 10 frames per second: 23035@example 23036testsrc=duration=5.3:size=qcif:rate=10 23037@end example 23038 23039@item 23040The following graph description will generate a red source 23041with an opacity of 0.2, with size "qcif" and a frame rate of 10 23042frames per second: 23043@example 23044color=c=red@@0.2:s=qcif:r=10 23045@end example 23046 23047@item 23048If the input content is to be ignored, @code{nullsrc} can be used. The 23049following command generates noise in the luminance plane by employing 23050the @code{geq} filter: 23051@example 23052nullsrc=s=256x256, geq=random(1)*255:128:128 23053@end example 23054@end itemize 23055 23056@subsection Commands 23057 23058The @code{color} source supports the following commands: 23059 23060@table @option 23061@item c, color 23062Set the color of the created image. Accepts the same syntax of the 23063corresponding @option{color} option. 23064@end table 23065 23066@section openclsrc 23067 23068Generate video using an OpenCL program. 23069 23070@table @option 23071 23072@item source 23073OpenCL program source file. 23074 23075@item kernel 23076Kernel name in program. 23077 23078@item size, s 23079Size of frames to generate. This must be set. 23080 23081@item format 23082Pixel format to use for the generated frames. This must be set. 23083 23084@item rate, r 23085Number of frames generated every second. Default value is '25'. 23086 23087@end table 23088 23089For details of how the program loading works, see the @ref{program_opencl} 23090filter. 23091 23092Example programs: 23093 23094@itemize 23095@item 23096Generate a colour ramp by setting pixel values from the position of the pixel 23097in the output image. (Note that this will work with all pixel formats, but 23098the generated output will not be the same.) 23099@verbatim 23100__kernel void ramp(__write_only image2d_t dst, 23101 unsigned int index) 23102{ 23103 int2 loc = (int2)(get_global_id(0), get_global_id(1)); 23104 23105 float4 val; 23106 val.xy = val.zw = convert_float2(loc) / convert_float2(get_image_dim(dst)); 23107 23108 write_imagef(dst, loc, val); 23109} 23110@end verbatim 23111 23112@item 23113Generate a Sierpinski carpet pattern, panning by a single pixel each frame. 23114@verbatim 23115__kernel void sierpinski_carpet(__write_only image2d_t dst, 23116 unsigned int index) 23117{ 23118 int2 loc = (int2)(get_global_id(0), get_global_id(1)); 23119 23120 float4 value = 0.0f; 23121 int x = loc.x + index; 23122 int y = loc.y + index; 23123 while (x > 0 || y > 0) { 23124 if (x % 3 == 1 && y % 3 == 1) { 23125 value = 1.0f; 23126 break; 23127 } 23128 x /= 3; 23129 y /= 3; 23130 } 23131 23132 write_imagef(dst, loc, value); 23133} 23134@end verbatim 23135 23136@end itemize 23137 23138@section sierpinski 23139 23140Generate a Sierpinski carpet/triangle fractal, and randomly pan around. 23141 23142This source accepts the following options: 23143 23144@table @option 23145@item size, s 23146Set frame size. For the syntax of this option, check the @ref{video size syntax,,"Video 23147size" section in the ffmpeg-utils manual,ffmpeg-utils}. Default value is "640x480". 23148 23149@item rate, r 23150Set frame rate, expressed as number of frames per second. Default 23151value is "25". 23152 23153@item seed 23154Set seed which is used for random panning. 23155 23156@item jump 23157Set max jump for single pan destination. Allowed range is from 1 to 10000. 23158 23159@item type 23160Set fractal type, can be default @code{carpet} or @code{triangle}. 23161@end table 23162 23163@c man end VIDEO SOURCES 23164 23165@chapter Video Sinks 23166@c man begin VIDEO SINKS 23167 23168Below is a description of the currently available video sinks. 23169 23170@section buffersink 23171 23172Buffer video frames, and make them available to the end of the filter 23173graph. 23174 23175This sink is mainly intended for programmatic use, in particular 23176through the interface defined in @file{libavfilter/buffersink.h} 23177or the options system. 23178 23179It accepts a pointer to an AVBufferSinkContext structure, which 23180defines the incoming buffers' formats, to be passed as the opaque 23181parameter to @code{avfilter_init_filter} for initialization. 23182 23183@section nullsink 23184 23185Null video sink: do absolutely nothing with the input video. It is 23186mainly useful as a template and for use in analysis / debugging 23187tools. 23188 23189@c man end VIDEO SINKS 23190 23191@chapter Multimedia Filters 23192@c man begin MULTIMEDIA FILTERS 23193 23194Below is a description of the currently available multimedia filters. 23195 23196@section abitscope 23197 23198Convert input audio to a video output, displaying the audio bit scope. 23199 23200The filter accepts the following options: 23201 23202@table @option 23203@item rate, r 23204Set frame rate, expressed as number of frames per second. Default 23205value is "25". 23206 23207@item size, s 23208Specify the video size for the output. For the syntax of this option, check the 23209@ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}. 23210Default value is @code{1024x256}. 23211 23212@item colors 23213Specify list of colors separated by space or by '|' which will be used to 23214draw channels. Unrecognized or missing colors will be replaced 23215by white color. 23216@end table 23217 23218@section adrawgraph 23219Draw a graph using input audio metadata. 23220 23221See @ref{drawgraph} 23222 23223@section agraphmonitor 23224 23225See @ref{graphmonitor}. 23226 23227@section ahistogram 23228 23229Convert input audio to a video output, displaying the volume histogram. 23230 23231The filter accepts the following options: 23232 23233@table @option 23234@item dmode 23235Specify how histogram is calculated. 23236 23237It accepts the following values: 23238@table @samp 23239@item single 23240Use single histogram for all channels. 23241@item separate 23242Use separate histogram for each channel. 23243@end table 23244Default is @code{single}. 23245 23246@item rate, r 23247Set frame rate, expressed as number of frames per second. Default 23248value is "25". 23249 23250@item size, s 23251Specify the video size for the output. For the syntax of this option, check the 23252@ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}. 23253Default value is @code{hd720}. 23254 23255@item scale 23256Set display scale. 23257 23258It accepts the following values: 23259@table @samp 23260@item log 23261logarithmic 23262@item sqrt 23263square root 23264@item cbrt 23265cubic root 23266@item lin 23267linear 23268@item rlog 23269reverse logarithmic 23270@end table 23271Default is @code{log}. 23272 23273@item ascale 23274Set amplitude scale. 23275 23276It accepts the following values: 23277@table @samp 23278@item log 23279logarithmic 23280@item lin 23281linear 23282@end table 23283Default is @code{log}. 23284 23285@item acount 23286Set how much frames to accumulate in histogram. 23287Default is 1. Setting this to -1 accumulates all frames. 23288 23289@item rheight 23290Set histogram ratio of window height. 23291 23292@item slide 23293Set sonogram sliding. 23294 23295It accepts the following values: 23296@table @samp 23297@item replace 23298replace old rows with new ones. 23299@item scroll 23300scroll from top to bottom. 23301@end table 23302Default is @code{replace}. 23303@end table 23304 23305@section aphasemeter 23306 23307Measures phase of input audio, which is exported as metadata @code{lavfi.aphasemeter.phase}, 23308representing mean phase of current audio frame. A video output can also be produced and is 23309enabled by default. The audio is passed through as first output. 23310 23311Audio will be rematrixed to stereo if it has a different channel layout. Phase value is in 23312range @code{[-1, 1]} where @code{-1} means left and right channels are completely out of phase 23313and @code{1} means channels are in phase. 23314 23315The filter accepts the following options, all related to its video output: 23316 23317@table @option 23318@item rate, r 23319Set the output frame rate. Default value is @code{25}. 23320 23321@item size, s 23322Set the video size for the output. For the syntax of this option, check the 23323@ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}. 23324Default value is @code{800x400}. 23325 23326@item rc 23327@item gc 23328@item bc 23329Specify the red, green, blue contrast. Default values are @code{2}, 23330@code{7} and @code{1}. 23331Allowed range is @code{[0, 255]}. 23332 23333@item mpc 23334Set color which will be used for drawing median phase. If color is 23335@code{none} which is default, no median phase value will be drawn. 23336 23337@item video 23338Enable video output. Default is enabled. 23339@end table 23340 23341@section avectorscope 23342 23343Convert input audio to a video output, representing the audio vector 23344scope. 23345 23346The filter is used to measure the difference between channels of stereo 23347audio stream. A monaural signal, consisting of identical left and right 23348signal, results in straight vertical line. Any stereo separation is visible 23349as a deviation from this line, creating a Lissajous figure. 23350If the straight (or deviation from it) but horizontal line appears this 23351indicates that the left and right channels are out of phase. 23352 23353The filter accepts the following options: 23354 23355@table @option 23356@item mode, m 23357Set the vectorscope mode. 23358 23359Available values are: 23360@table @samp 23361@item lissajous 23362Lissajous rotated by 45 degrees. 23363 23364@item lissajous_xy 23365Same as above but not rotated. 23366 23367@item polar 23368Shape resembling half of circle. 23369@end table 23370 23371Default value is @samp{lissajous}. 23372 23373@item size, s 23374Set the video size for the output. For the syntax of this option, check the 23375@ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}. 23376Default value is @code{400x400}. 23377 23378@item rate, r 23379Set the output frame rate. Default value is @code{25}. 23380 23381@item rc 23382@item gc 23383@item bc 23384@item ac 23385Specify the red, green, blue and alpha contrast. Default values are @code{40}, 23386@code{160}, @code{80} and @code{255}. 23387Allowed range is @code{[0, 255]}. 23388 23389@item rf 23390@item gf 23391@item bf 23392@item af 23393Specify the red, green, blue and alpha fade. Default values are @code{15}, 23394@code{10}, @code{5} and @code{5}. 23395Allowed range is @code{[0, 255]}. 23396 23397@item zoom 23398Set the zoom factor. Default value is @code{1}. Allowed range is @code{[0, 10]}. 23399Values lower than @var{1} will auto adjust zoom factor to maximal possible value. 23400 23401@item draw 23402Set the vectorscope drawing mode. 23403 23404Available values are: 23405@table @samp 23406@item dot 23407Draw dot for each sample. 23408 23409@item line 23410Draw line between previous and current sample. 23411@end table 23412 23413Default value is @samp{dot}. 23414 23415@item scale 23416Specify amplitude scale of audio samples. 23417 23418Available values are: 23419@table @samp 23420@item lin 23421Linear. 23422 23423@item sqrt 23424Square root. 23425 23426@item cbrt 23427Cubic root. 23428 23429@item log 23430Logarithmic. 23431@end table 23432 23433@item swap 23434Swap left channel axis with right channel axis. 23435 23436@item mirror 23437Mirror axis. 23438 23439@table @samp 23440@item none 23441No mirror. 23442 23443@item x 23444Mirror only x axis. 23445 23446@item y 23447Mirror only y axis. 23448 23449@item xy 23450Mirror both axis. 23451@end table 23452 23453@end table 23454 23455@subsection Examples 23456 23457@itemize 23458@item 23459Complete example using @command{ffplay}: 23460@example 23461ffplay -f lavfi 'amovie=input.mp3, asplit [a][out1]; 23462 [a] avectorscope=zoom=1.3:rc=2:gc=200:bc=10:rf=1:gf=8:bf=7 [out0]' 23463@end example 23464@end itemize 23465 23466@section bench, abench 23467 23468Benchmark part of a filtergraph. 23469 23470The filter accepts the following options: 23471 23472@table @option 23473@item action 23474Start or stop a timer. 23475 23476Available values are: 23477@table @samp 23478@item start 23479Get the current time, set it as frame metadata (using the key 23480@code{lavfi.bench.start_time}), and forward the frame to the next filter. 23481 23482@item stop 23483Get the current time and fetch the @code{lavfi.bench.start_time} metadata from 23484the input frame metadata to get the time difference. Time difference, average, 23485maximum and minimum time (respectively @code{t}, @code{avg}, @code{max} and 23486@code{min}) are then printed. The timestamps are expressed in seconds. 23487@end table 23488@end table 23489 23490@subsection Examples 23491 23492@itemize 23493@item 23494Benchmark @ref{selectivecolor} filter: 23495@example 23496bench=start,selectivecolor=reds=-.2 .12 -.49,bench=stop 23497@end example 23498@end itemize 23499 23500@section concat 23501 23502Concatenate audio and video streams, joining them together one after the 23503other. 23504 23505The filter works on segments of synchronized video and audio streams. All 23506segments must have the same number of streams of each type, and that will 23507also be the number of streams at output. 23508 23509The filter accepts the following options: 23510 23511@table @option 23512 23513@item n 23514Set the number of segments. Default is 2. 23515 23516@item v 23517Set the number of output video streams, that is also the number of video 23518streams in each segment. Default is 1. 23519 23520@item a 23521Set the number of output audio streams, that is also the number of audio 23522streams in each segment. Default is 0. 23523 23524@item unsafe 23525Activate unsafe mode: do not fail if segments have a different format. 23526 23527@end table 23528 23529The filter has @var{v}+@var{a} outputs: first @var{v} video outputs, then 23530@var{a} audio outputs. 23531 23532There are @var{n}x(@var{v}+@var{a}) inputs: first the inputs for the first 23533segment, in the same order as the outputs, then the inputs for the second 23534segment, etc. 23535 23536Related streams do not always have exactly the same duration, for various 23537reasons including codec frame size or sloppy authoring. For that reason, 23538related synchronized streams (e.g. a video and its audio track) should be 23539concatenated at once. The concat filter will use the duration of the longest 23540stream in each segment (except the last one), and if necessary pad shorter 23541audio streams with silence. 23542 23543For this filter to work correctly, all segments must start at timestamp 0. 23544 23545All corresponding streams must have the same parameters in all segments; the 23546filtering system will automatically select a common pixel format for video 23547streams, and a common sample format, sample rate and channel layout for 23548audio streams, but other settings, such as resolution, must be converted 23549explicitly by the user. 23550 23551Different frame rates are acceptable but will result in variable frame rate 23552at output; be sure to configure the output file to handle it. 23553 23554@subsection Examples 23555 23556@itemize 23557@item 23558Concatenate an opening, an episode and an ending, all in bilingual version 23559(video in stream 0, audio in streams 1 and 2): 23560@example 23561ffmpeg -i opening.mkv -i episode.mkv -i ending.mkv -filter_complex \ 23562 '[0:0] [0:1] [0:2] [1:0] [1:1] [1:2] [2:0] [2:1] [2:2] 23563 concat=n=3:v=1:a=2 [v] [a1] [a2]' \ 23564 -map '[v]' -map '[a1]' -map '[a2]' output.mkv 23565@end example 23566 23567@item 23568Concatenate two parts, handling audio and video separately, using the 23569(a)movie sources, and adjusting the resolution: 23570@example 23571movie=part1.mp4, scale=512:288 [v1] ; amovie=part1.mp4 [a1] ; 23572movie=part2.mp4, scale=512:288 [v2] ; amovie=part2.mp4 [a2] ; 23573[v1] [v2] concat [outv] ; [a1] [a2] concat=v=0:a=1 [outa] 23574@end example 23575Note that a desync will happen at the stitch if the audio and video streams 23576do not have exactly the same duration in the first file. 23577 23578@end itemize 23579 23580@subsection Commands 23581 23582This filter supports the following commands: 23583@table @option 23584@item next 23585Close the current segment and step to the next one 23586@end table 23587 23588@anchor{ebur128} 23589@section ebur128 23590 23591EBU R128 scanner filter. This filter takes an audio stream and analyzes its loudness 23592level. By default, it logs a message at a frequency of 10Hz with the 23593Momentary loudness (identified by @code{M}), Short-term loudness (@code{S}), 23594Integrated loudness (@code{I}) and Loudness Range (@code{LRA}). 23595 23596The filter can only analyze streams which have a sampling rate of 48000 Hz and whose 23597sample format is double-precision floating point. The input stream will be converted to 23598this specification, if needed. Users may need to insert aformat and/or aresample filters 23599after this filter to obtain the original parameters. 23600 23601The filter also has a video output (see the @var{video} option) with a real 23602time graph to observe the loudness evolution. The graphic contains the logged 23603message mentioned above, so it is not printed anymore when this option is set, 23604unless the verbose logging is set. The main graphing area contains the 23605short-term loudness (3 seconds of analysis), and the gauge on the right is for 23606the momentary loudness (400 milliseconds), but can optionally be configured 23607to instead display short-term loudness (see @var{gauge}). 23608 23609The green area marks a +/- 1LU target range around the target loudness 23610(-23LUFS by default, unless modified through @var{target}). 23611 23612More information about the Loudness Recommendation EBU R128 on 23613@url{http://tech.ebu.ch/loudness}. 23614 23615The filter accepts the following options: 23616 23617@table @option 23618 23619@item video 23620Activate the video output. The audio stream is passed unchanged whether this 23621option is set or no. The video stream will be the first output stream if 23622activated. Default is @code{0}. 23623 23624@item size 23625Set the video size. This option is for video only. For the syntax of this 23626option, check the 23627@ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}. 23628Default and minimum resolution is @code{640x480}. 23629 23630@item meter 23631Set the EBU scale meter. Default is @code{9}. Common values are @code{9} and 23632@code{18}, respectively for EBU scale meter +9 and EBU scale meter +18. Any 23633other integer value between this range is allowed. 23634 23635@item metadata 23636Set metadata injection. If set to @code{1}, the audio input will be segmented 23637into 100ms output frames, each of them containing various loudness information 23638in metadata. All the metadata keys are prefixed with @code{lavfi.r128.}. 23639 23640Default is @code{0}. 23641 23642@item framelog 23643Force the frame logging level. 23644 23645Available values are: 23646@table @samp 23647@item info 23648information logging level 23649@item verbose 23650verbose logging level 23651@end table 23652 23653By default, the logging level is set to @var{info}. If the @option{video} or 23654the @option{metadata} options are set, it switches to @var{verbose}. 23655 23656@item peak 23657Set peak mode(s). 23658 23659Available modes can be cumulated (the option is a @code{flag} type). Possible 23660values are: 23661@table @samp 23662@item none 23663Disable any peak mode (default). 23664@item sample 23665Enable sample-peak mode. 23666 23667Simple peak mode looking for the higher sample value. It logs a message 23668for sample-peak (identified by @code{SPK}). 23669@item true 23670Enable true-peak mode. 23671 23672If enabled, the peak lookup is done on an over-sampled version of the input 23673stream for better peak accuracy. It logs a message for true-peak. 23674(identified by @code{TPK}) and true-peak per frame (identified by @code{FTPK}). 23675This mode requires a build with @code{libswresample}. 23676@end table 23677 23678@item dualmono 23679Treat mono input files as "dual mono". If a mono file is intended for playback 23680on a stereo system, its EBU R128 measurement will be perceptually incorrect. 23681If set to @code{true}, this option will compensate for this effect. 23682Multi-channel input files are not affected by this option. 23683 23684@item panlaw 23685Set a specific pan law to be used for the measurement of dual mono files. 23686This parameter is optional, and has a default value of -3.01dB. 23687 23688@item target 23689Set a specific target level (in LUFS) used as relative zero in the visualization. 23690This parameter is optional and has a default value of -23LUFS as specified 23691by EBU R128. However, material published online may prefer a level of -16LUFS 23692(e.g. for use with podcasts or video platforms). 23693 23694@item gauge 23695Set the value displayed by the gauge. Valid values are @code{momentary} and s 23696@code{shortterm}. By default the momentary value will be used, but in certain 23697scenarios it may be more useful to observe the short term value instead (e.g. 23698live mixing). 23699 23700@item scale 23701Sets the display scale for the loudness. Valid parameters are @code{absolute} 23702(in LUFS) or @code{relative} (LU) relative to the target. This only affects the 23703video output, not the summary or continuous log output. 23704@end table 23705 23706@subsection Examples 23707 23708@itemize 23709@item 23710Real-time graph using @command{ffplay}, with a EBU scale meter +18: 23711@example 23712ffplay -f lavfi -i "amovie=input.mp3,ebur128=video=1:meter=18 [out0][out1]" 23713@end example 23714 23715@item 23716Run an analysis with @command{ffmpeg}: 23717@example 23718ffmpeg -nostats -i input.mp3 -filter_complex ebur128 -f null - 23719@end example 23720@end itemize 23721 23722@section interleave, ainterleave 23723 23724Temporally interleave frames from several inputs. 23725 23726@code{interleave} works with video inputs, @code{ainterleave} with audio. 23727 23728These filters read frames from several inputs and send the oldest 23729queued frame to the output. 23730 23731Input streams must have well defined, monotonically increasing frame 23732timestamp values. 23733 23734In order to submit one frame to output, these filters need to enqueue 23735at least one frame for each input, so they cannot work in case one 23736input is not yet terminated and will not receive incoming frames. 23737 23738For example consider the case when one input is a @code{select} filter 23739which always drops input frames. The @code{interleave} filter will keep 23740reading from that input, but it will never be able to send new frames 23741to output until the input sends an end-of-stream signal. 23742 23743Also, depending on inputs synchronization, the filters will drop 23744frames in case one input receives more frames than the other ones, and 23745the queue is already filled. 23746 23747These filters accept the following options: 23748 23749@table @option 23750@item nb_inputs, n 23751Set the number of different inputs, it is 2 by default. 23752 23753@item duration 23754How to determine the end-of-stream. 23755 23756@table @option 23757@item longest 23758The duration of the longest input. (default) 23759 23760@item shortest 23761The duration of the shortest input. 23762 23763@item first 23764The duration of the first input. 23765@end table 23766 23767@end table 23768 23769@subsection Examples 23770 23771@itemize 23772@item 23773Interleave frames belonging to different streams using @command{ffmpeg}: 23774@example 23775ffmpeg -i bambi.avi -i pr0n.mkv -filter_complex "[0:v][1:v] interleave" out.avi 23776@end example 23777 23778@item 23779Add flickering blur effect: 23780@example 23781select='if(gt(random(0), 0.2), 1, 2)':n=2 [tmp], boxblur=2:2, [tmp] interleave 23782@end example 23783@end itemize 23784 23785@section metadata, ametadata 23786 23787Manipulate frame metadata. 23788 23789This filter accepts the following options: 23790 23791@table @option 23792@item mode 23793Set mode of operation of the filter. 23794 23795Can be one of the following: 23796 23797@table @samp 23798@item select 23799If both @code{value} and @code{key} is set, select frames 23800which have such metadata. If only @code{key} is set, select 23801every frame that has such key in metadata. 23802 23803@item add 23804Add new metadata @code{key} and @code{value}. If key is already available 23805do nothing. 23806 23807@item modify 23808Modify value of already present key. 23809 23810@item delete 23811If @code{value} is set, delete only keys that have such value. 23812Otherwise, delete key. If @code{key} is not set, delete all metadata values in 23813the frame. 23814 23815@item print 23816Print key and its value if metadata was found. If @code{key} is not set print all 23817metadata values available in frame. 23818@end table 23819 23820@item key 23821Set key used with all modes. Must be set for all modes except @code{print} and @code{delete}. 23822 23823@item value 23824Set metadata value which will be used. This option is mandatory for 23825@code{modify} and @code{add} mode. 23826 23827@item function 23828Which function to use when comparing metadata value and @code{value}. 23829 23830Can be one of following: 23831 23832@table @samp 23833@item same_str 23834Values are interpreted as strings, returns true if metadata value is same as @code{value}. 23835 23836@item starts_with 23837Values are interpreted as strings, returns true if metadata value starts with 23838the @code{value} option string. 23839 23840@item less 23841Values are interpreted as floats, returns true if metadata value is less than @code{value}. 23842 23843@item equal 23844Values are interpreted as floats, returns true if @code{value} is equal with metadata value. 23845 23846@item greater 23847Values are interpreted as floats, returns true if metadata value is greater than @code{value}. 23848 23849@item expr 23850Values are interpreted as floats, returns true if expression from option @code{expr} 23851evaluates to true. 23852 23853@item ends_with 23854Values are interpreted as strings, returns true if metadata value ends with 23855the @code{value} option string. 23856@end table 23857 23858@item expr 23859Set expression which is used when @code{function} is set to @code{expr}. 23860The expression is evaluated through the eval API and can contain the following 23861constants: 23862 23863@table @option 23864@item VALUE1 23865Float representation of @code{value} from metadata key. 23866 23867@item VALUE2 23868Float representation of @code{value} as supplied by user in @code{value} option. 23869@end table 23870 23871@item file 23872If specified in @code{print} mode, output is written to the named file. Instead of 23873plain filename any writable url can be specified. Filename ``-'' is a shorthand 23874for standard output. If @code{file} option is not set, output is written to the log 23875with AV_LOG_INFO loglevel. 23876 23877@item direct 23878Reduces buffering in print mode when output is written to a URL set using @var{file}. 23879 23880@end table 23881 23882@subsection Examples 23883 23884@itemize 23885@item 23886Print all metadata values for frames with key @code{lavfi.signalstats.YDIF} with values 23887between 0 and 1. 23888@example 23889signalstats,metadata=print:key=lavfi.signalstats.YDIF:value=0:function=expr:expr='between(VALUE1,0,1)' 23890@end example 23891@item 23892Print silencedetect output to file @file{metadata.txt}. 23893@example 23894silencedetect,ametadata=mode=print:file=metadata.txt 23895@end example 23896@item 23897Direct all metadata to a pipe with file descriptor 4. 23898@example 23899metadata=mode=print:file='pipe\:4' 23900@end example 23901@end itemize 23902 23903@section perms, aperms 23904 23905Set read/write permissions for the output frames. 23906 23907These filters are mainly aimed at developers to test direct path in the 23908following filter in the filtergraph. 23909 23910The filters accept the following options: 23911 23912@table @option 23913@item mode 23914Select the permissions mode. 23915 23916It accepts the following values: 23917@table @samp 23918@item none 23919Do nothing. This is the default. 23920@item ro 23921Set all the output frames read-only. 23922@item rw 23923Set all the output frames directly writable. 23924@item toggle 23925Make the frame read-only if writable, and writable if read-only. 23926@item random 23927Set each output frame read-only or writable randomly. 23928@end table 23929 23930@item seed 23931Set the seed for the @var{random} mode, must be an integer included between 23932@code{0} and @code{UINT32_MAX}. If not specified, or if explicitly set to 23933@code{-1}, the filter will try to use a good random seed on a best effort 23934basis. 23935@end table 23936 23937Note: in case of auto-inserted filter between the permission filter and the 23938following one, the permission might not be received as expected in that 23939following filter. Inserting a @ref{format} or @ref{aformat} filter before the 23940perms/aperms filter can avoid this problem. 23941 23942@section realtime, arealtime 23943 23944Slow down filtering to match real time approximately. 23945 23946These filters will pause the filtering for a variable amount of time to 23947match the output rate with the input timestamps. 23948They are similar to the @option{re} option to @code{ffmpeg}. 23949 23950They accept the following options: 23951 23952@table @option 23953@item limit 23954Time limit for the pauses. Any pause longer than that will be considered 23955a timestamp discontinuity and reset the timer. Default is 2 seconds. 23956@item speed 23957Speed factor for processing. The value must be a float larger than zero. 23958Values larger than 1.0 will result in faster than realtime processing, 23959smaller will slow processing down. The @var{limit} is automatically adapted 23960accordingly. Default is 1.0. 23961 23962A processing speed faster than what is possible without these filters cannot 23963be achieved. 23964@end table 23965 23966@anchor{select} 23967@section select, aselect 23968 23969Select frames to pass in output. 23970 23971This filter accepts the following options: 23972 23973@table @option 23974 23975@item expr, e 23976Set expression, which is evaluated for each input frame. 23977 23978If the expression is evaluated to zero, the frame is discarded. 23979 23980If the evaluation result is negative or NaN, the frame is sent to the 23981first output; otherwise it is sent to the output with index 23982@code{ceil(val)-1}, assuming that the input index starts from 0. 23983 23984For example a value of @code{1.2} corresponds to the output with index 23985@code{ceil(1.2)-1 = 2-1 = 1}, that is the second output. 23986 23987@item outputs, n 23988Set the number of outputs. The output to which to send the selected 23989frame is based on the result of the evaluation. Default value is 1. 23990@end table 23991 23992The expression can contain the following constants: 23993 23994@table @option 23995@item n 23996The (sequential) number of the filtered frame, starting from 0. 23997 23998@item selected_n 23999The (sequential) number of the selected frame, starting from 0. 24000 24001@item prev_selected_n 24002The sequential number of the last selected frame. It's NAN if undefined. 24003 24004@item TB 24005The timebase of the input timestamps. 24006 24007@item pts 24008The PTS (Presentation TimeStamp) of the filtered video frame, 24009expressed in @var{TB} units. It's NAN if undefined. 24010 24011@item t 24012The PTS of the filtered video frame, 24013expressed in seconds. It's NAN if undefined. 24014 24015@item prev_pts 24016The PTS of the previously filtered video frame. It's NAN if undefined. 24017 24018@item prev_selected_pts 24019The PTS of the last previously filtered video frame. It's NAN if undefined. 24020 24021@item prev_selected_t 24022The PTS of the last previously selected video frame, expressed in seconds. It's NAN if undefined. 24023 24024@item start_pts 24025The PTS of the first video frame in the video. It's NAN if undefined. 24026 24027@item start_t 24028The time of the first video frame in the video. It's NAN if undefined. 24029 24030@item pict_type @emph{(video only)} 24031The type of the filtered frame. It can assume one of the following 24032values: 24033@table @option 24034@item I 24035@item P 24036@item B 24037@item S 24038@item SI 24039@item SP 24040@item BI 24041@end table 24042 24043@item interlace_type @emph{(video only)} 24044The frame interlace type. It can assume one of the following values: 24045@table @option 24046@item PROGRESSIVE 24047The frame is progressive (not interlaced). 24048@item TOPFIRST 24049The frame is top-field-first. 24050@item BOTTOMFIRST 24051The frame is bottom-field-first. 24052@end table 24053 24054@item consumed_sample_n @emph{(audio only)} 24055the number of selected samples before the current frame 24056 24057@item samples_n @emph{(audio only)} 24058the number of samples in the current frame 24059 24060@item sample_rate @emph{(audio only)} 24061the input sample rate 24062 24063@item key 24064This is 1 if the filtered frame is a key-frame, 0 otherwise. 24065 24066@item pos 24067the position in the file of the filtered frame, -1 if the information 24068is not available (e.g. for synthetic video) 24069 24070@item scene @emph{(video only)} 24071value between 0 and 1 to indicate a new scene; a low value reflects a low 24072probability for the current frame to introduce a new scene, while a higher 24073value means the current frame is more likely to be one (see the example below) 24074 24075@item concatdec_select 24076The concat demuxer can select only part of a concat input file by setting an 24077inpoint and an outpoint, but the output packets may not be entirely contained 24078in the selected interval. By using this variable, it is possible to skip frames 24079generated by the concat demuxer which are not exactly contained in the selected 24080interval. 24081 24082This works by comparing the frame pts against the @var{lavf.concat.start_time} 24083and the @var{lavf.concat.duration} packet metadata values which are also 24084present in the decoded frames. 24085 24086The @var{concatdec_select} variable is -1 if the frame pts is at least 24087start_time and either the duration metadata is missing or the frame pts is less 24088than start_time + duration, 0 otherwise, and NaN if the start_time metadata is 24089missing. 24090 24091That basically means that an input frame is selected if its pts is within the 24092interval set by the concat demuxer. 24093 24094@end table 24095 24096The default value of the select expression is "1". 24097 24098@subsection Examples 24099 24100@itemize 24101@item 24102Select all frames in input: 24103@example 24104select 24105@end example 24106 24107The example above is the same as: 24108@example 24109select=1 24110@end example 24111 24112@item 24113Skip all frames: 24114@example 24115select=0 24116@end example 24117 24118@item 24119Select only I-frames: 24120@example 24121select='eq(pict_type\,I)' 24122@end example 24123 24124@item 24125Select one frame every 100: 24126@example 24127select='not(mod(n\,100))' 24128@end example 24129 24130@item 24131Select only frames contained in the 10-20 time interval: 24132@example 24133select=between(t\,10\,20) 24134@end example 24135 24136@item 24137Select only I-frames contained in the 10-20 time interval: 24138@example 24139select=between(t\,10\,20)*eq(pict_type\,I) 24140@end example 24141 24142@item 24143Select frames with a minimum distance of 10 seconds: 24144@example 24145select='isnan(prev_selected_t)+gte(t-prev_selected_t\,10)' 24146@end example 24147 24148@item 24149Use aselect to select only audio frames with samples number > 100: 24150@example 24151aselect='gt(samples_n\,100)' 24152@end example 24153 24154@item 24155Create a mosaic of the first scenes: 24156@example 24157ffmpeg -i video.avi -vf select='gt(scene\,0.4)',scale=160:120,tile -frames:v 1 preview.png 24158@end example 24159 24160Comparing @var{scene} against a value between 0.3 and 0.5 is generally a sane 24161choice. 24162 24163@item 24164Send even and odd frames to separate outputs, and compose them: 24165@example 24166select=n=2:e='mod(n, 2)+1' [odd][even]; [odd] pad=h=2*ih [tmp]; [tmp][even] overlay=y=h 24167@end example 24168 24169@item 24170Select useful frames from an ffconcat file which is using inpoints and 24171outpoints but where the source files are not intra frame only. 24172@example 24173ffmpeg -copyts -vsync 0 -segment_time_metadata 1 -i input.ffconcat -vf select=concatdec_select -af aselect=concatdec_select output.avi 24174@end example 24175@end itemize 24176 24177@section sendcmd, asendcmd 24178 24179Send commands to filters in the filtergraph. 24180 24181These filters read commands to be sent to other filters in the 24182filtergraph. 24183 24184@code{sendcmd} must be inserted between two video filters, 24185@code{asendcmd} must be inserted between two audio filters, but apart 24186from that they act the same way. 24187 24188The specification of commands can be provided in the filter arguments 24189with the @var{commands} option, or in a file specified by the 24190@var{filename} option. 24191 24192These filters accept the following options: 24193@table @option 24194@item commands, c 24195Set the commands to be read and sent to the other filters. 24196@item filename, f 24197Set the filename of the commands to be read and sent to the other 24198filters. 24199@end table 24200 24201@subsection Commands syntax 24202 24203A commands description consists of a sequence of interval 24204specifications, comprising a list of commands to be executed when a 24205particular event related to that interval occurs. The occurring event 24206is typically the current frame time entering or leaving a given time 24207interval. 24208 24209An interval is specified by the following syntax: 24210@example 24211@var{START}[-@var{END}] @var{COMMANDS}; 24212@end example 24213 24214The time interval is specified by the @var{START} and @var{END} times. 24215@var{END} is optional and defaults to the maximum time. 24216 24217The current frame time is considered within the specified interval if 24218it is included in the interval [@var{START}, @var{END}), that is when 24219the time is greater or equal to @var{START} and is lesser than 24220@var{END}. 24221 24222@var{COMMANDS} consists of a sequence of one or more command 24223specifications, separated by ",", relating to that interval. The 24224syntax of a command specification is given by: 24225@example 24226[@var{FLAGS}] @var{TARGET} @var{COMMAND} @var{ARG} 24227@end example 24228 24229@var{FLAGS} is optional and specifies the type of events relating to 24230the time interval which enable sending the specified command, and must 24231be a non-null sequence of identifier flags separated by "+" or "|" and 24232enclosed between "[" and "]". 24233 24234The following flags are recognized: 24235@table @option 24236@item enter 24237The command is sent when the current frame timestamp enters the 24238specified interval. In other words, the command is sent when the 24239previous frame timestamp was not in the given interval, and the 24240current is. 24241 24242@item leave 24243The command is sent when the current frame timestamp leaves the 24244specified interval. In other words, the command is sent when the 24245previous frame timestamp was in the given interval, and the 24246current is not. 24247 24248@item expr 24249The command @var{ARG} is interpreted as expression and result of 24250expression is passed as @var{ARG}. 24251 24252The expression is evaluated through the eval API and can contain the following 24253constants: 24254 24255@table @option 24256@item POS 24257Original position in the file of the frame, or undefined if undefined 24258for the current frame. 24259 24260@item PTS 24261The presentation timestamp in input. 24262 24263@item N 24264The count of the input frame for video or audio, starting from 0. 24265 24266@item T 24267The time in seconds of the current frame. 24268 24269@item TS 24270The start time in seconds of the current command interval. 24271 24272@item TE 24273The end time in seconds of the current command interval. 24274 24275@item TI 24276The interpolated time of the current command interval, TI = (T - TS) / (TE - TS). 24277@end table 24278 24279@end table 24280 24281If @var{FLAGS} is not specified, a default value of @code{[enter]} is 24282assumed. 24283 24284@var{TARGET} specifies the target of the command, usually the name of 24285the filter class or a specific filter instance name. 24286 24287@var{COMMAND} specifies the name of the command for the target filter. 24288 24289@var{ARG} is optional and specifies the optional list of argument for 24290the given @var{COMMAND}. 24291 24292Between one interval specification and another, whitespaces, or 24293sequences of characters starting with @code{#} until the end of line, 24294are ignored and can be used to annotate comments. 24295 24296A simplified BNF description of the commands specification syntax 24297follows: 24298@example 24299@var{COMMAND_FLAG} ::= "enter" | "leave" 24300@var{COMMAND_FLAGS} ::= @var{COMMAND_FLAG} [(+|"|")@var{COMMAND_FLAG}] 24301@var{COMMAND} ::= ["[" @var{COMMAND_FLAGS} "]"] @var{TARGET} @var{COMMAND} [@var{ARG}] 24302@var{COMMANDS} ::= @var{COMMAND} [,@var{COMMANDS}] 24303@var{INTERVAL} ::= @var{START}[-@var{END}] @var{COMMANDS} 24304@var{INTERVALS} ::= @var{INTERVAL}[;@var{INTERVALS}] 24305@end example 24306 24307@subsection Examples 24308 24309@itemize 24310@item 24311Specify audio tempo change at second 4: 24312@example 24313asendcmd=c='4.0 atempo tempo 1.5',atempo 24314@end example 24315 24316@item 24317Target a specific filter instance: 24318@example 24319asendcmd=c='4.0 atempo@@my tempo 1.5',atempo@@my 24320@end example 24321 24322@item 24323Specify a list of drawtext and hue commands in a file. 24324@example 24325# show text in the interval 5-10 243265.0-10.0 [enter] drawtext reinit 'fontfile=FreeSerif.ttf:text=hello world', 24327 [leave] drawtext reinit 'fontfile=FreeSerif.ttf:text='; 24328 24329# desaturate the image in the interval 15-20 2433015.0-20.0 [enter] hue s 0, 24331 [enter] drawtext reinit 'fontfile=FreeSerif.ttf:text=nocolor', 24332 [leave] hue s 1, 24333 [leave] drawtext reinit 'fontfile=FreeSerif.ttf:text=color'; 24334 24335# apply an exponential saturation fade-out effect, starting from time 25 2433625 [enter] hue s exp(25-t) 24337@end example 24338 24339A filtergraph allowing to read and process the above command list 24340stored in a file @file{test.cmd}, can be specified with: 24341@example 24342sendcmd=f=test.cmd,drawtext=fontfile=FreeSerif.ttf:text='',hue 24343@end example 24344@end itemize 24345 24346@anchor{setpts} 24347@section setpts, asetpts 24348 24349Change the PTS (presentation timestamp) of the input frames. 24350 24351@code{setpts} works on video frames, @code{asetpts} on audio frames. 24352 24353This filter accepts the following options: 24354 24355@table @option 24356 24357@item expr 24358The expression which is evaluated for each frame to construct its timestamp. 24359 24360@end table 24361 24362The expression is evaluated through the eval API and can contain the following 24363constants: 24364 24365@table @option 24366@item FRAME_RATE, FR 24367frame rate, only defined for constant frame-rate video 24368 24369@item PTS 24370The presentation timestamp in input 24371 24372@item N 24373The count of the input frame for video or the number of consumed samples, 24374not including the current frame for audio, starting from 0. 24375 24376@item NB_CONSUMED_SAMPLES 24377The number of consumed samples, not including the current frame (only 24378audio) 24379 24380@item NB_SAMPLES, S 24381The number of samples in the current frame (only audio) 24382 24383@item SAMPLE_RATE, SR 24384The audio sample rate. 24385 24386@item STARTPTS 24387The PTS of the first frame. 24388 24389@item STARTT 24390the time in seconds of the first frame 24391 24392@item INTERLACED 24393State whether the current frame is interlaced. 24394 24395@item T 24396the time in seconds of the current frame 24397 24398@item POS 24399original position in the file of the frame, or undefined if undefined 24400for the current frame 24401 24402@item PREV_INPTS 24403The previous input PTS. 24404 24405@item PREV_INT 24406previous input time in seconds 24407 24408@item PREV_OUTPTS 24409The previous output PTS. 24410 24411@item PREV_OUTT 24412previous output time in seconds 24413 24414@item RTCTIME 24415The wallclock (RTC) time in microseconds. This is deprecated, use time(0) 24416instead. 24417 24418@item RTCSTART 24419The wallclock (RTC) time at the start of the movie in microseconds. 24420 24421@item TB 24422The timebase of the input timestamps. 24423 24424@end table 24425 24426@subsection Examples 24427 24428@itemize 24429@item 24430Start counting PTS from zero 24431@example 24432setpts=PTS-STARTPTS 24433@end example 24434 24435@item 24436Apply fast motion effect: 24437@example 24438setpts=0.5*PTS 24439@end example 24440 24441@item 24442Apply slow motion effect: 24443@example 24444setpts=2.0*PTS 24445@end example 24446 24447@item 24448Set fixed rate of 25 frames per second: 24449@example 24450setpts=N/(25*TB) 24451@end example 24452 24453@item 24454Set fixed rate 25 fps with some jitter: 24455@example 24456setpts='1/(25*TB) * (N + 0.05 * sin(N*2*PI/25))' 24457@end example 24458 24459@item 24460Apply an offset of 10 seconds to the input PTS: 24461@example 24462setpts=PTS+10/TB 24463@end example 24464 24465@item 24466Generate timestamps from a "live source" and rebase onto the current timebase: 24467@example 24468setpts='(RTCTIME - RTCSTART) / (TB * 1000000)' 24469@end example 24470 24471@item 24472Generate timestamps by counting samples: 24473@example 24474asetpts=N/SR/TB 24475@end example 24476 24477@end itemize 24478 24479@section setrange 24480 24481Force color range for the output video frame. 24482 24483The @code{setrange} filter marks the color range property for the 24484output frames. It does not change the input frame, but only sets the 24485corresponding property, which affects how the frame is treated by 24486following filters. 24487 24488The filter accepts the following options: 24489 24490@table @option 24491 24492@item range 24493Available values are: 24494 24495@table @samp 24496@item auto 24497Keep the same color range property. 24498 24499@item unspecified, unknown 24500Set the color range as unspecified. 24501 24502@item limited, tv, mpeg 24503Set the color range as limited. 24504 24505@item full, pc, jpeg 24506Set the color range as full. 24507@end table 24508@end table 24509 24510@section settb, asettb 24511 24512Set the timebase to use for the output frames timestamps. 24513It is mainly useful for testing timebase configuration. 24514 24515It accepts the following parameters: 24516 24517@table @option 24518 24519@item expr, tb 24520The expression which is evaluated into the output timebase. 24521 24522@end table 24523 24524The value for @option{tb} is an arithmetic expression representing a 24525rational. The expression can contain the constants "AVTB" (the default 24526timebase), "intb" (the input timebase) and "sr" (the sample rate, 24527audio only). Default value is "intb". 24528 24529@subsection Examples 24530 24531@itemize 24532@item 24533Set the timebase to 1/25: 24534@example 24535settb=expr=1/25 24536@end example 24537 24538@item 24539Set the timebase to 1/10: 24540@example 24541settb=expr=0.1 24542@end example 24543 24544@item 24545Set the timebase to 1001/1000: 24546@example 24547settb=1+0.001 24548@end example 24549 24550@item 24551Set the timebase to 2*intb: 24552@example 24553settb=2*intb 24554@end example 24555 24556@item 24557Set the default timebase value: 24558@example 24559settb=AVTB 24560@end example 24561@end itemize 24562 24563@section showcqt 24564Convert input audio to a video output representing frequency spectrum 24565logarithmically using Brown-Puckette constant Q transform algorithm with 24566direct frequency domain coefficient calculation (but the transform itself 24567is not really constant Q, instead the Q factor is actually variable/clamped), 24568with musical tone scale, from E0 to D#10. 24569 24570The filter accepts the following options: 24571 24572@table @option 24573@item size, s 24574Specify the video size for the output. It must be even. For the syntax of this option, 24575check the @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}. 24576Default value is @code{1920x1080}. 24577 24578@item fps, rate, r 24579Set the output frame rate. Default value is @code{25}. 24580 24581@item bar_h 24582Set the bargraph height. It must be even. Default value is @code{-1} which 24583computes the bargraph height automatically. 24584 24585@item axis_h 24586Set the axis height. It must be even. Default value is @code{-1} which computes 24587the axis height automatically. 24588 24589@item sono_h 24590Set the sonogram height. It must be even. Default value is @code{-1} which 24591computes the sonogram height automatically. 24592 24593@item fullhd 24594Set the fullhd resolution. This option is deprecated, use @var{size}, @var{s} 24595instead. Default value is @code{1}. 24596 24597@item sono_v, volume 24598Specify the sonogram volume expression. It can contain variables: 24599@table @option 24600@item bar_v 24601the @var{bar_v} evaluated expression 24602@item frequency, freq, f 24603the frequency where it is evaluated 24604@item timeclamp, tc 24605the value of @var{timeclamp} option 24606@end table 24607and functions: 24608@table @option 24609@item a_weighting(f) 24610A-weighting of equal loudness 24611@item b_weighting(f) 24612B-weighting of equal loudness 24613@item c_weighting(f) 24614C-weighting of equal loudness. 24615@end table 24616Default value is @code{16}. 24617 24618@item bar_v, volume2 24619Specify the bargraph volume expression. It can contain variables: 24620@table @option 24621@item sono_v 24622the @var{sono_v} evaluated expression 24623@item frequency, freq, f 24624the frequency where it is evaluated 24625@item timeclamp, tc 24626the value of @var{timeclamp} option 24627@end table 24628and functions: 24629@table @option 24630@item a_weighting(f) 24631A-weighting of equal loudness 24632@item b_weighting(f) 24633B-weighting of equal loudness 24634@item c_weighting(f) 24635C-weighting of equal loudness. 24636@end table 24637Default value is @code{sono_v}. 24638 24639@item sono_g, gamma 24640Specify the sonogram gamma. Lower gamma makes the spectrum more contrast, 24641higher gamma makes the spectrum having more range. Default value is @code{3}. 24642Acceptable range is @code{[1, 7]}. 24643 24644@item bar_g, gamma2 24645Specify the bargraph gamma. Default value is @code{1}. Acceptable range is 24646@code{[1, 7]}. 24647 24648@item bar_t 24649Specify the bargraph transparency level. Lower value makes the bargraph sharper. 24650Default value is @code{1}. Acceptable range is @code{[0, 1]}. 24651 24652@item timeclamp, tc 24653Specify the transform timeclamp. At low frequency, there is trade-off between 24654accuracy in time domain and frequency domain. If timeclamp is lower, 24655event in time domain is represented more accurately (such as fast bass drum), 24656otherwise event in frequency domain is represented more accurately 24657(such as bass guitar). Acceptable range is @code{[0.002, 1]}. Default value is @code{0.17}. 24658 24659@item attack 24660Set attack time in seconds. The default is @code{0} (disabled). Otherwise, it 24661limits future samples by applying asymmetric windowing in time domain, useful 24662when low latency is required. Accepted range is @code{[0, 1]}. 24663 24664@item basefreq 24665Specify the transform base frequency. Default value is @code{20.01523126408007475}, 24666which is frequency 50 cents below E0. Acceptable range is @code{[10, 100000]}. 24667 24668@item endfreq 24669Specify the transform end frequency. Default value is @code{20495.59681441799654}, 24670which is frequency 50 cents above D#10. Acceptable range is @code{[10, 100000]}. 24671 24672@item coeffclamp 24673This option is deprecated and ignored. 24674 24675@item tlength 24676Specify the transform length in time domain. Use this option to control accuracy 24677trade-off between time domain and frequency domain at every frequency sample. 24678It can contain variables: 24679@table @option 24680@item frequency, freq, f 24681the frequency where it is evaluated 24682@item timeclamp, tc 24683the value of @var{timeclamp} option. 24684@end table 24685Default value is @code{384*tc/(384+tc*f)}. 24686 24687@item count 24688Specify the transform count for every video frame. Default value is @code{6}. 24689Acceptable range is @code{[1, 30]}. 24690 24691@item fcount 24692Specify the transform count for every single pixel. Default value is @code{0}, 24693which makes it computed automatically. Acceptable range is @code{[0, 10]}. 24694 24695@item fontfile 24696Specify font file for use with freetype to draw the axis. If not specified, 24697use embedded font. Note that drawing with font file or embedded font is not 24698implemented with custom @var{basefreq} and @var{endfreq}, use @var{axisfile} 24699option instead. 24700 24701@item font 24702Specify fontconfig pattern. This has lower priority than @var{fontfile}. The 24703@code{:} in the pattern may be replaced by @code{|} to avoid unnecessary 24704escaping. 24705 24706@item fontcolor 24707Specify font color expression. This is arithmetic expression that should return 24708integer value 0xRRGGBB. It can contain variables: 24709@table @option 24710@item frequency, freq, f 24711the frequency where it is evaluated 24712@item timeclamp, tc 24713the value of @var{timeclamp} option 24714@end table 24715and functions: 24716@table @option 24717@item midi(f) 24718midi number of frequency f, some midi numbers: E0(16), C1(24), C2(36), A4(69) 24719@item r(x), g(x), b(x) 24720red, green, and blue value of intensity x. 24721@end table 24722Default value is @code{st(0, (midi(f)-59.5)/12); 24723st(1, if(between(ld(0),0,1), 0.5-0.5*cos(2*PI*ld(0)), 0)); 24724r(1-ld(1)) + b(ld(1))}. 24725 24726@item axisfile 24727Specify image file to draw the axis. This option override @var{fontfile} and 24728@var{fontcolor} option. 24729 24730@item axis, text 24731Enable/disable drawing text to the axis. If it is set to @code{0}, drawing to 24732the axis is disabled, ignoring @var{fontfile} and @var{axisfile} option. 24733Default value is @code{1}. 24734 24735@item csp 24736Set colorspace. The accepted values are: 24737@table @samp 24738@item unspecified 24739Unspecified (default) 24740 24741@item bt709 24742BT.709 24743 24744@item fcc 24745FCC 24746 24747@item bt470bg 24748BT.470BG or BT.601-6 625 24749 24750@item smpte170m 24751SMPTE-170M or BT.601-6 525 24752 24753@item smpte240m 24754SMPTE-240M 24755 24756@item bt2020ncl 24757BT.2020 with non-constant luminance 24758 24759@end table 24760 24761@item cscheme 24762Set spectrogram color scheme. This is list of floating point values with format 24763@code{left_r|left_g|left_b|right_r|right_g|right_b}. 24764The default is @code{1|0.5|0|0|0.5|1}. 24765 24766@end table 24767 24768@subsection Examples 24769 24770@itemize 24771@item 24772Playing audio while showing the spectrum: 24773@example 24774ffplay -f lavfi 'amovie=a.mp3, asplit [a][out1]; [a] showcqt [out0]' 24775@end example 24776 24777@item 24778Same as above, but with frame rate 30 fps: 24779@example 24780ffplay -f lavfi 'amovie=a.mp3, asplit [a][out1]; [a] showcqt=fps=30:count=5 [out0]' 24781@end example 24782 24783@item 24784Playing at 1280x720: 24785@example 24786ffplay -f lavfi 'amovie=a.mp3, asplit [a][out1]; [a] showcqt=s=1280x720:count=4 [out0]' 24787@end example 24788 24789@item 24790Disable sonogram display: 24791@example 24792sono_h=0 24793@end example 24794 24795@item 24796A1 and its harmonics: A1, A2, (near)E3, A3: 24797@example 24798ffplay -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), 24799 asplit[a][out1]; [a] showcqt [out0]' 24800@end example 24801 24802@item 24803Same as above, but with more accuracy in frequency domain: 24804@example 24805ffplay -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), 24806 asplit[a][out1]; [a] showcqt=timeclamp=0.5 [out0]' 24807@end example 24808 24809@item 24810Custom volume: 24811@example 24812bar_v=10:sono_v=bar_v*a_weighting(f) 24813@end example 24814 24815@item 24816Custom gamma, now spectrum is linear to the amplitude. 24817@example 24818bar_g=2:sono_g=2 24819@end example 24820 24821@item 24822Custom tlength equation: 24823@example 24824tc=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)))' 24825@end example 24826 24827@item 24828Custom fontcolor and fontfile, C-note is colored green, others are colored blue: 24829@example 24830fontcolor='if(mod(floor(midi(f)+0.5),12), 0x0000FF, g(1))':fontfile=myfont.ttf 24831@end example 24832 24833@item 24834Custom font using fontconfig: 24835@example 24836font='Courier New,Monospace,mono|bold' 24837@end example 24838 24839@item 24840Custom frequency range with custom axis using image file: 24841@example 24842axisfile=myaxis.png:basefreq=40:endfreq=10000 24843@end example 24844@end itemize 24845 24846@section showfreqs 24847 24848Convert input audio to video output representing the audio power spectrum. 24849Audio amplitude is on Y-axis while frequency is on X-axis. 24850 24851The filter accepts the following options: 24852 24853@table @option 24854@item size, s 24855Specify size of video. For the syntax of this option, check the 24856@ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}. 24857Default is @code{1024x512}. 24858 24859@item mode 24860Set display mode. 24861This set how each frequency bin will be represented. 24862 24863It accepts the following values: 24864@table @samp 24865@item line 24866@item bar 24867@item dot 24868@end table 24869Default is @code{bar}. 24870 24871@item ascale 24872Set amplitude scale. 24873 24874It accepts the following values: 24875@table @samp 24876@item lin 24877Linear scale. 24878 24879@item sqrt 24880Square root scale. 24881 24882@item cbrt 24883Cubic root scale. 24884 24885@item log 24886Logarithmic scale. 24887@end table 24888Default is @code{log}. 24889 24890@item fscale 24891Set frequency scale. 24892 24893It accepts the following values: 24894@table @samp 24895@item lin 24896Linear scale. 24897 24898@item log 24899Logarithmic scale. 24900 24901@item rlog 24902Reverse logarithmic scale. 24903@end table 24904Default is @code{lin}. 24905 24906@item win_size 24907Set window size. Allowed range is from 16 to 65536. 24908 24909Default is @code{2048} 24910 24911@item win_func 24912Set windowing function. 24913 24914It accepts the following values: 24915@table @samp 24916@item rect 24917@item bartlett 24918@item hanning 24919@item hamming 24920@item blackman 24921@item welch 24922@item flattop 24923@item bharris 24924@item bnuttall 24925@item bhann 24926@item sine 24927@item nuttall 24928@item lanczos 24929@item gauss 24930@item tukey 24931@item dolph 24932@item cauchy 24933@item parzen 24934@item poisson 24935@item bohman 24936@end table 24937Default is @code{hanning}. 24938 24939@item overlap 24940Set window overlap. In range @code{[0, 1]}. Default is @code{1}, 24941which means optimal overlap for selected window function will be picked. 24942 24943@item averaging 24944Set time averaging. Setting this to 0 will display current maximal peaks. 24945Default is @code{1}, which means time averaging is disabled. 24946 24947@item colors 24948Specify list of colors separated by space or by '|' which will be used to 24949draw channel frequencies. Unrecognized or missing colors will be replaced 24950by white color. 24951 24952@item cmode 24953Set channel display mode. 24954 24955It accepts the following values: 24956@table @samp 24957@item combined 24958@item separate 24959@end table 24960Default is @code{combined}. 24961 24962@item minamp 24963Set minimum amplitude used in @code{log} amplitude scaler. 24964 24965@end table 24966 24967@section showspatial 24968 24969Convert stereo input audio to a video output, representing the spatial relationship 24970between two channels. 24971 24972The filter accepts the following options: 24973 24974@table @option 24975@item size, s 24976Specify the video size for the output. For the syntax of this option, check the 24977@ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}. 24978Default value is @code{512x512}. 24979 24980@item win_size 24981Set window size. Allowed range is from @var{1024} to @var{65536}. Default size is @var{4096}. 24982 24983@item win_func 24984Set window function. 24985 24986It accepts the following values: 24987@table @samp 24988@item rect 24989@item bartlett 24990@item hann 24991@item hanning 24992@item hamming 24993@item blackman 24994@item welch 24995@item flattop 24996@item bharris 24997@item bnuttall 24998@item bhann 24999@item sine 25000@item nuttall 25001@item lanczos 25002@item gauss 25003@item tukey 25004@item dolph 25005@item cauchy 25006@item parzen 25007@item poisson 25008@item bohman 25009@end table 25010 25011Default value is @code{hann}. 25012 25013@item overlap 25014Set ratio of overlap window. Default value is @code{0.5}. 25015When value is @code{1} overlap is set to recommended size for specific 25016window function currently used. 25017@end table 25018 25019@anchor{showspectrum} 25020@section showspectrum 25021 25022Convert input audio to a video output, representing the audio frequency 25023spectrum. 25024 25025The filter accepts the following options: 25026 25027@table @option 25028@item size, s 25029Specify the video size for the output. For the syntax of this option, check the 25030@ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}. 25031Default value is @code{640x512}. 25032 25033@item slide 25034Specify how the spectrum should slide along the window. 25035 25036It accepts the following values: 25037@table @samp 25038@item replace 25039the samples start again on the left when they reach the right 25040@item scroll 25041the samples scroll from right to left 25042@item fullframe 25043frames are only produced when the samples reach the right 25044@item rscroll 25045the samples scroll from left to right 25046@end table 25047 25048Default value is @code{replace}. 25049 25050@item mode 25051Specify display mode. 25052 25053It accepts the following values: 25054@table @samp 25055@item combined 25056all channels are displayed in the same row 25057@item separate 25058all channels are displayed in separate rows 25059@end table 25060 25061Default value is @samp{combined}. 25062 25063@item color 25064Specify display color mode. 25065 25066It accepts the following values: 25067@table @samp 25068@item channel 25069each channel is displayed in a separate color 25070@item intensity 25071each channel is displayed using the same color scheme 25072@item rainbow 25073each channel is displayed using the rainbow color scheme 25074@item moreland 25075each channel is displayed using the moreland color scheme 25076@item nebulae 25077each channel is displayed using the nebulae color scheme 25078@item fire 25079each channel is displayed using the fire color scheme 25080@item fiery 25081each channel is displayed using the fiery color scheme 25082@item fruit 25083each channel is displayed using the fruit color scheme 25084@item cool 25085each channel is displayed using the cool color scheme 25086@item magma 25087each channel is displayed using the magma color scheme 25088@item green 25089each channel is displayed using the green color scheme 25090@item viridis 25091each channel is displayed using the viridis color scheme 25092@item plasma 25093each channel is displayed using the plasma color scheme 25094@item cividis 25095each channel is displayed using the cividis color scheme 25096@item terrain 25097each channel is displayed using the terrain color scheme 25098@end table 25099 25100Default value is @samp{channel}. 25101 25102@item scale 25103Specify scale used for calculating intensity color values. 25104 25105It accepts the following values: 25106@table @samp 25107@item lin 25108linear 25109@item sqrt 25110square root, default 25111@item cbrt 25112cubic root 25113@item log 25114logarithmic 25115@item 4thrt 251164th root 25117@item 5thrt 251185th root 25119@end table 25120 25121Default value is @samp{sqrt}. 25122 25123@item fscale 25124Specify frequency scale. 25125 25126It accepts the following values: 25127@table @samp 25128@item lin 25129linear 25130@item log 25131logarithmic 25132@end table 25133 25134Default value is @samp{lin}. 25135 25136@item saturation 25137Set saturation modifier for displayed colors. Negative values provide 25138alternative color scheme. @code{0} is no saturation at all. 25139Saturation must be in [-10.0, 10.0] range. 25140Default value is @code{1}. 25141 25142@item win_func 25143Set window function. 25144 25145It accepts the following values: 25146@table @samp 25147@item rect 25148@item bartlett 25149@item hann 25150@item hanning 25151@item hamming 25152@item blackman 25153@item welch 25154@item flattop 25155@item bharris 25156@item bnuttall 25157@item bhann 25158@item sine 25159@item nuttall 25160@item lanczos 25161@item gauss 25162@item tukey 25163@item dolph 25164@item cauchy 25165@item parzen 25166@item poisson 25167@item bohman 25168@end table 25169 25170Default value is @code{hann}. 25171 25172@item orientation 25173Set orientation of time vs frequency axis. Can be @code{vertical} or 25174@code{horizontal}. Default is @code{vertical}. 25175 25176@item overlap 25177Set ratio of overlap window. Default value is @code{0}. 25178When value is @code{1} overlap is set to recommended size for specific 25179window function currently used. 25180 25181@item gain 25182Set scale gain for calculating intensity color values. 25183Default value is @code{1}. 25184 25185@item data 25186Set which data to display. Can be @code{magnitude}, default or @code{phase}. 25187 25188@item rotation 25189Set color rotation, must be in [-1.0, 1.0] range. 25190Default value is @code{0}. 25191 25192@item start 25193Set start frequency from which to display spectrogram. Default is @code{0}. 25194 25195@item stop 25196Set stop frequency to which to display spectrogram. Default is @code{0}. 25197 25198@item fps 25199Set upper frame rate limit. Default is @code{auto}, unlimited. 25200 25201@item legend 25202Draw time and frequency axes and legends. Default is disabled. 25203@end table 25204 25205The usage is very similar to the showwaves filter; see the examples in that 25206section. 25207 25208@subsection Examples 25209 25210@itemize 25211@item 25212Large window with logarithmic color scaling: 25213@example 25214showspectrum=s=1280x480:scale=log 25215@end example 25216 25217@item 25218Complete example for a colored and sliding spectrum per channel using @command{ffplay}: 25219@example 25220ffplay -f lavfi 'amovie=input.mp3, asplit [a][out1]; 25221 [a] showspectrum=mode=separate:color=intensity:slide=1:scale=cbrt [out0]' 25222@end example 25223@end itemize 25224 25225@section showspectrumpic 25226 25227Convert input audio to a single video frame, representing the audio frequency 25228spectrum. 25229 25230The filter accepts the following options: 25231 25232@table @option 25233@item size, s 25234Specify the video size for the output. For the syntax of this option, check the 25235@ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}. 25236Default value is @code{4096x2048}. 25237 25238@item mode 25239Specify display mode. 25240 25241It accepts the following values: 25242@table @samp 25243@item combined 25244all channels are displayed in the same row 25245@item separate 25246all channels are displayed in separate rows 25247@end table 25248Default value is @samp{combined}. 25249 25250@item color 25251Specify display color mode. 25252 25253It accepts the following values: 25254@table @samp 25255@item channel 25256each channel is displayed in a separate color 25257@item intensity 25258each channel is displayed using the same color scheme 25259@item rainbow 25260each channel is displayed using the rainbow color scheme 25261@item moreland 25262each channel is displayed using the moreland color scheme 25263@item nebulae 25264each channel is displayed using the nebulae color scheme 25265@item fire 25266each channel is displayed using the fire color scheme 25267@item fiery 25268each channel is displayed using the fiery color scheme 25269@item fruit 25270each channel is displayed using the fruit color scheme 25271@item cool 25272each channel is displayed using the cool color scheme 25273@item magma 25274each channel is displayed using the magma color scheme 25275@item green 25276each channel is displayed using the green color scheme 25277@item viridis 25278each channel is displayed using the viridis color scheme 25279@item plasma 25280each channel is displayed using the plasma color scheme 25281@item cividis 25282each channel is displayed using the cividis color scheme 25283@item terrain 25284each channel is displayed using the terrain color scheme 25285@end table 25286Default value is @samp{intensity}. 25287 25288@item scale 25289Specify scale used for calculating intensity color values. 25290 25291It accepts the following values: 25292@table @samp 25293@item lin 25294linear 25295@item sqrt 25296square root, default 25297@item cbrt 25298cubic root 25299@item log 25300logarithmic 25301@item 4thrt 253024th root 25303@item 5thrt 253045th root 25305@end table 25306Default value is @samp{log}. 25307 25308@item fscale 25309Specify frequency scale. 25310 25311It accepts the following values: 25312@table @samp 25313@item lin 25314linear 25315@item log 25316logarithmic 25317@end table 25318 25319Default value is @samp{lin}. 25320 25321@item saturation 25322Set saturation modifier for displayed colors. Negative values provide 25323alternative color scheme. @code{0} is no saturation at all. 25324Saturation must be in [-10.0, 10.0] range. 25325Default value is @code{1}. 25326 25327@item win_func 25328Set window function. 25329 25330It accepts the following values: 25331@table @samp 25332@item rect 25333@item bartlett 25334@item hann 25335@item hanning 25336@item hamming 25337@item blackman 25338@item welch 25339@item flattop 25340@item bharris 25341@item bnuttall 25342@item bhann 25343@item sine 25344@item nuttall 25345@item lanczos 25346@item gauss 25347@item tukey 25348@item dolph 25349@item cauchy 25350@item parzen 25351@item poisson 25352@item bohman 25353@end table 25354Default value is @code{hann}. 25355 25356@item orientation 25357Set orientation of time vs frequency axis. Can be @code{vertical} or 25358@code{horizontal}. Default is @code{vertical}. 25359 25360@item gain 25361Set scale gain for calculating intensity color values. 25362Default value is @code{1}. 25363 25364@item legend 25365Draw time and frequency axes and legends. Default is enabled. 25366 25367@item rotation 25368Set color rotation, must be in [-1.0, 1.0] range. 25369Default value is @code{0}. 25370 25371@item start 25372Set start frequency from which to display spectrogram. Default is @code{0}. 25373 25374@item stop 25375Set stop frequency to which to display spectrogram. Default is @code{0}. 25376@end table 25377 25378@subsection Examples 25379 25380@itemize 25381@item 25382Extract an audio spectrogram of a whole audio track 25383in a 1024x1024 picture using @command{ffmpeg}: 25384@example 25385ffmpeg -i audio.flac -lavfi showspectrumpic=s=1024x1024 spectrogram.png 25386@end example 25387@end itemize 25388 25389@section showvolume 25390 25391Convert input audio volume to a video output. 25392 25393The filter accepts the following options: 25394 25395@table @option 25396@item rate, r 25397Set video rate. 25398 25399@item b 25400Set border width, allowed range is [0, 5]. Default is 1. 25401 25402@item w 25403Set channel width, allowed range is [80, 8192]. Default is 400. 25404 25405@item h 25406Set channel height, allowed range is [1, 900]. Default is 20. 25407 25408@item f 25409Set fade, allowed range is [0, 1]. Default is 0.95. 25410 25411@item c 25412Set volume color expression. 25413 25414The expression can use the following variables: 25415 25416@table @option 25417@item VOLUME 25418Current max volume of channel in dB. 25419 25420@item PEAK 25421Current peak. 25422 25423@item CHANNEL 25424Current channel number, starting from 0. 25425@end table 25426 25427@item t 25428If set, displays channel names. Default is enabled. 25429 25430@item v 25431If set, displays volume values. Default is enabled. 25432 25433@item o 25434Set orientation, can be horizontal: @code{h} or vertical: @code{v}, 25435default is @code{h}. 25436 25437@item s 25438Set step size, allowed range is [0, 5]. Default is 0, which means 25439step is disabled. 25440 25441@item p 25442Set background opacity, allowed range is [0, 1]. Default is 0. 25443 25444@item m 25445Set metering mode, can be peak: @code{p} or rms: @code{r}, 25446default is @code{p}. 25447 25448@item ds 25449Set display scale, can be linear: @code{lin} or log: @code{log}, 25450default is @code{lin}. 25451 25452@item dm 25453In second. 25454If set to > 0., display a line for the max level 25455in the previous seconds. 25456default is disabled: @code{0.} 25457 25458@item dmc 25459The color of the max line. Use when @code{dm} option is set to > 0. 25460default is: @code{orange} 25461@end table 25462 25463@section showwaves 25464 25465Convert input audio to a video output, representing the samples waves. 25466 25467The filter accepts the following options: 25468 25469@table @option 25470@item size, s 25471Specify the video size for the output. For the syntax of this option, check the 25472@ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}. 25473Default value is @code{600x240}. 25474 25475@item mode 25476Set display mode. 25477 25478Available values are: 25479@table @samp 25480@item point 25481Draw a point for each sample. 25482 25483@item line 25484Draw a vertical line for each sample. 25485 25486@item p2p 25487Draw a point for each sample and a line between them. 25488 25489@item cline 25490Draw a centered vertical line for each sample. 25491@end table 25492 25493Default value is @code{point}. 25494 25495@item n 25496Set the number of samples which are printed on the same column. A 25497larger value will decrease the frame rate. Must be a positive 25498integer. This option can be set only if the value for @var{rate} 25499is not explicitly specified. 25500 25501@item rate, r 25502Set the (approximate) output frame rate. This is done by setting the 25503option @var{n}. Default value is "25". 25504 25505@item split_channels 25506Set if channels should be drawn separately or overlap. Default value is 0. 25507 25508@item colors 25509Set colors separated by '|' which are going to be used for drawing of each channel. 25510 25511@item scale 25512Set amplitude scale. 25513 25514Available values are: 25515@table @samp 25516@item lin 25517Linear. 25518 25519@item log 25520Logarithmic. 25521 25522@item sqrt 25523Square root. 25524 25525@item cbrt 25526Cubic root. 25527@end table 25528 25529Default is linear. 25530 25531@item draw 25532Set the draw mode. This is mostly useful to set for high @var{n}. 25533 25534Available values are: 25535@table @samp 25536@item scale 25537Scale pixel values for each drawn sample. 25538 25539@item full 25540Draw every sample directly. 25541@end table 25542 25543Default value is @code{scale}. 25544@end table 25545 25546@subsection Examples 25547 25548@itemize 25549@item 25550Output the input file audio and the corresponding video representation 25551at the same time: 25552@example 25553amovie=a.mp3,asplit[out0],showwaves[out1] 25554@end example 25555 25556@item 25557Create a synthetic signal and show it with showwaves, forcing a 25558frame rate of 30 frames per second: 25559@example 25560aevalsrc=sin(1*2*PI*t)*sin(880*2*PI*t):cos(2*PI*200*t),asplit[out0],showwaves=r=30[out1] 25561@end example 25562@end itemize 25563 25564@section showwavespic 25565 25566Convert input audio to a single video frame, representing the samples waves. 25567 25568The filter accepts the following options: 25569 25570@table @option 25571@item size, s 25572Specify the video size for the output. For the syntax of this option, check the 25573@ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}. 25574Default value is @code{600x240}. 25575 25576@item split_channels 25577Set if channels should be drawn separately or overlap. Default value is 0. 25578 25579@item colors 25580Set colors separated by '|' which are going to be used for drawing of each channel. 25581 25582@item scale 25583Set amplitude scale. 25584 25585Available values are: 25586@table @samp 25587@item lin 25588Linear. 25589 25590@item log 25591Logarithmic. 25592 25593@item sqrt 25594Square root. 25595 25596@item cbrt 25597Cubic root. 25598@end table 25599 25600Default is linear. 25601 25602@item draw 25603Set the draw mode. 25604 25605Available values are: 25606@table @samp 25607@item scale 25608Scale pixel values for each drawn sample. 25609 25610@item full 25611Draw every sample directly. 25612@end table 25613 25614Default value is @code{scale}. 25615 25616@item filter 25617Set the filter mode. 25618 25619Available values are: 25620@table @samp 25621@item average 25622Use average samples values for each drawn sample. 25623 25624@item peak 25625Use peak samples values for each drawn sample. 25626@end table 25627 25628Default value is @code{average}. 25629@end table 25630 25631@subsection Examples 25632 25633@itemize 25634@item 25635Extract a channel split representation of the wave form of a whole audio track 25636in a 1024x800 picture using @command{ffmpeg}: 25637@example 25638ffmpeg -i audio.flac -lavfi showwavespic=split_channels=1:s=1024x800 waveform.png 25639@end example 25640@end itemize 25641 25642@section sidedata, asidedata 25643 25644Delete frame side data, or select frames based on it. 25645 25646This filter accepts the following options: 25647 25648@table @option 25649@item mode 25650Set mode of operation of the filter. 25651 25652Can be one of the following: 25653 25654@table @samp 25655@item select 25656Select every frame with side data of @code{type}. 25657 25658@item delete 25659Delete side data of @code{type}. If @code{type} is not set, delete all side 25660data in the frame. 25661 25662@end table 25663 25664@item type 25665Set side data type used with all modes. Must be set for @code{select} mode. For 25666the list of frame side data types, refer to the @code{AVFrameSideDataType} enum 25667in @file{libavutil/frame.h}. For example, to choose 25668@code{AV_FRAME_DATA_PANSCAN} side data, you must specify @code{PANSCAN}. 25669 25670@end table 25671 25672@section spectrumsynth 25673 25674Synthesize audio from 2 input video spectrums, first input stream represents 25675magnitude across time and second represents phase across time. 25676The filter will transform from frequency domain as displayed in videos back 25677to time domain as presented in audio output. 25678 25679This filter is primarily created for reversing processed @ref{showspectrum} 25680filter outputs, but can synthesize sound from other spectrograms too. 25681But in such case results are going to be poor if the phase data is not 25682available, because in such cases phase data need to be recreated, usually 25683it's just recreated from random noise. 25684For best results use gray only output (@code{channel} color mode in 25685@ref{showspectrum} filter) and @code{log} scale for magnitude video and 25686@code{lin} scale for phase video. To produce phase, for 2nd video, use 25687@code{data} option. Inputs videos should generally use @code{fullframe} 25688slide mode as that saves resources needed for decoding video. 25689 25690The filter accepts the following options: 25691 25692@table @option 25693@item sample_rate 25694Specify sample rate of output audio, the sample rate of audio from which 25695spectrum was generated may differ. 25696 25697@item channels 25698Set number of channels represented in input video spectrums. 25699 25700@item scale 25701Set scale which was used when generating magnitude input spectrum. 25702Can be @code{lin} or @code{log}. Default is @code{log}. 25703 25704@item slide 25705Set slide which was used when generating inputs spectrums. 25706Can be @code{replace}, @code{scroll}, @code{fullframe} or @code{rscroll}. 25707Default is @code{fullframe}. 25708 25709@item win_func 25710Set window function used for resynthesis. 25711 25712@item overlap 25713Set window overlap. In range @code{[0, 1]}. Default is @code{1}, 25714which means optimal overlap for selected window function will be picked. 25715 25716@item orientation 25717Set orientation of input videos. Can be @code{vertical} or @code{horizontal}. 25718Default is @code{vertical}. 25719@end table 25720 25721@subsection Examples 25722 25723@itemize 25724@item 25725First create magnitude and phase videos from audio, assuming audio is stereo with 44100 sample rate, 25726then resynthesize videos back to audio with spectrumsynth: 25727@example 25728ffmpeg -i input.flac -lavfi showspectrum=mode=separate:scale=log:overlap=0.875:color=channel:slide=fullframe:data=magnitude -an -c:v rawvideo magnitude.nut 25729ffmpeg -i input.flac -lavfi showspectrum=mode=separate:scale=lin:overlap=0.875:color=channel:slide=fullframe:data=phase -an -c:v rawvideo phase.nut 25730ffmpeg -i magnitude.nut -i phase.nut -lavfi spectrumsynth=channels=2:sample_rate=44100:win_func=hann:overlap=0.875:slide=fullframe output.flac 25731@end example 25732@end itemize 25733 25734@section split, asplit 25735 25736Split input into several identical outputs. 25737 25738@code{asplit} works with audio input, @code{split} with video. 25739 25740The filter accepts a single parameter which specifies the number of outputs. If 25741unspecified, it defaults to 2. 25742 25743@subsection Examples 25744 25745@itemize 25746@item 25747Create two separate outputs from the same input: 25748@example 25749[in] split [out0][out1] 25750@end example 25751 25752@item 25753To create 3 or more outputs, you need to specify the number of 25754outputs, like in: 25755@example 25756[in] asplit=3 [out0][out1][out2] 25757@end example 25758 25759@item 25760Create two separate outputs from the same input, one cropped and 25761one padded: 25762@example 25763[in] split [splitout1][splitout2]; 25764[splitout1] crop=100:100:0:0 [cropout]; 25765[splitout2] pad=200:200:100:100 [padout]; 25766@end example 25767 25768@item 25769Create 5 copies of the input audio with @command{ffmpeg}: 25770@example 25771ffmpeg -i INPUT -filter_complex asplit=5 OUTPUT 25772@end example 25773@end itemize 25774 25775@section zmq, azmq 25776 25777Receive commands sent through a libzmq client, and forward them to 25778filters in the filtergraph. 25779 25780@code{zmq} and @code{azmq} work as a pass-through filters. @code{zmq} 25781must be inserted between two video filters, @code{azmq} between two 25782audio filters. Both are capable to send messages to any filter type. 25783 25784To enable these filters you need to install the libzmq library and 25785headers and configure FFmpeg with @code{--enable-libzmq}. 25786 25787For more information about libzmq see: 25788@url{http://www.zeromq.org/} 25789 25790The @code{zmq} and @code{azmq} filters work as a libzmq server, which 25791receives messages sent through a network interface defined by the 25792@option{bind_address} (or the abbreviation "@option{b}") option. 25793Default value of this option is @file{tcp://localhost:5555}. You may 25794want to alter this value to your needs, but do not forget to escape any 25795':' signs (see @ref{filtergraph escaping}). 25796 25797The received message must be in the form: 25798@example 25799@var{TARGET} @var{COMMAND} [@var{ARG}] 25800@end example 25801 25802@var{TARGET} specifies the target of the command, usually the name of 25803the filter class or a specific filter instance name. The default 25804filter instance name uses the pattern @samp{Parsed_<filter_name>_<index>}, 25805but you can override this by using the @samp{filter_name@@id} syntax 25806(see @ref{Filtergraph syntax}). 25807 25808@var{COMMAND} specifies the name of the command for the target filter. 25809 25810@var{ARG} is optional and specifies the optional argument list for the 25811given @var{COMMAND}. 25812 25813Upon reception, the message is processed and the corresponding command 25814is injected into the filtergraph. Depending on the result, the filter 25815will send a reply to the client, adopting the format: 25816@example 25817@var{ERROR_CODE} @var{ERROR_REASON} 25818@var{MESSAGE} 25819@end example 25820 25821@var{MESSAGE} is optional. 25822 25823@subsection Examples 25824 25825Look at @file{tools/zmqsend} for an example of a zmq client which can 25826be used to send commands processed by these filters. 25827 25828Consider the following filtergraph generated by @command{ffplay}. 25829In this example the last overlay filter has an instance name. All other 25830filters will have default instance names. 25831 25832@example 25833ffplay -dumpgraph 1 -f lavfi " 25834color=s=100x100:c=red [l]; 25835color=s=100x100:c=blue [r]; 25836nullsrc=s=200x100, zmq [bg]; 25837[bg][l] overlay [bg+l]; 25838[bg+l][r] overlay@@my=x=100 " 25839@end example 25840 25841To change the color of the left side of the video, the following 25842command can be used: 25843@example 25844echo Parsed_color_0 c yellow | tools/zmqsend 25845@end example 25846 25847To change the right side: 25848@example 25849echo Parsed_color_1 c pink | tools/zmqsend 25850@end example 25851 25852To change the position of the right side: 25853@example 25854echo overlay@@my x 150 | tools/zmqsend 25855@end example 25856 25857 25858@c man end MULTIMEDIA FILTERS 25859 25860@chapter Multimedia Sources 25861@c man begin MULTIMEDIA SOURCES 25862 25863Below is a description of the currently available multimedia sources. 25864 25865@section amovie 25866 25867This is the same as @ref{movie} source, except it selects an audio 25868stream by default. 25869 25870@anchor{movie} 25871@section movie 25872 25873Read audio and/or video stream(s) from a movie container. 25874 25875It accepts the following parameters: 25876 25877@table @option 25878@item filename 25879The name of the resource to read (not necessarily a file; it can also be a 25880device or a stream accessed through some protocol). 25881 25882@item format_name, f 25883Specifies the format assumed for the movie to read, and can be either 25884the name of a container or an input device. If not specified, the 25885format is guessed from @var{movie_name} or by probing. 25886 25887@item seek_point, sp 25888Specifies the seek point in seconds. The frames will be output 25889starting from this seek point. The parameter is evaluated with 25890@code{av_strtod}, so the numerical value may be suffixed by an IS 25891postfix. The default value is "0". 25892 25893@item streams, s 25894Specifies the streams to read. Several streams can be specified, 25895separated by "+". The source will then have as many outputs, in the 25896same order. The syntax is explained in the @ref{Stream specifiers,,"Stream specifiers" 25897section in the ffmpeg manual,ffmpeg}. Two special names, "dv" and "da" specify 25898respectively the default (best suited) video and audio stream. Default 25899is "dv", or "da" if the filter is called as "amovie". 25900 25901@item stream_index, si 25902Specifies the index of the video stream to read. If the value is -1, 25903the most suitable video stream will be automatically selected. The default 25904value is "-1". Deprecated. If the filter is called "amovie", it will select 25905audio instead of video. 25906 25907@item loop 25908Specifies how many times to read the stream in sequence. 25909If the value is 0, the stream will be looped infinitely. 25910Default value is "1". 25911 25912Note that when the movie is looped the source timestamps are not 25913changed, so it will generate non monotonically increasing timestamps. 25914 25915@item discontinuity 25916Specifies the time difference between frames above which the point is 25917considered a timestamp discontinuity which is removed by adjusting the later 25918timestamps. 25919@end table 25920 25921It allows overlaying a second video on top of the main input of 25922a filtergraph, as shown in this graph: 25923@example 25924input -----------> deltapts0 --> overlay --> output 25925 ^ 25926 | 25927movie --> scale--> deltapts1 -------+ 25928@end example 25929@subsection Examples 25930 25931@itemize 25932@item 25933Skip 3.2 seconds from the start of the AVI file in.avi, and overlay it 25934on top of the input labelled "in": 25935@example 25936movie=in.avi:seek_point=3.2, scale=180:-1, setpts=PTS-STARTPTS [over]; 25937[in] setpts=PTS-STARTPTS [main]; 25938[main][over] overlay=16:16 [out] 25939@end example 25940 25941@item 25942Read from a video4linux2 device, and overlay it on top of the input 25943labelled "in": 25944@example 25945movie=/dev/video0:f=video4linux2, scale=180:-1, setpts=PTS-STARTPTS [over]; 25946[in] setpts=PTS-STARTPTS [main]; 25947[main][over] overlay=16:16 [out] 25948@end example 25949 25950@item 25951Read the first video stream and the audio stream with id 0x81 from 25952dvd.vob; the video is connected to the pad named "video" and the audio is 25953connected to the pad named "audio": 25954@example 25955movie=dvd.vob:s=v:0+#0x81 [video] [audio] 25956@end example 25957@end itemize 25958 25959@subsection Commands 25960 25961Both movie and amovie support the following commands: 25962@table @option 25963@item seek 25964Perform seek using "av_seek_frame". 25965The syntax is: seek @var{stream_index}|@var{timestamp}|@var{flags} 25966@itemize 25967@item 25968@var{stream_index}: If stream_index is -1, a default 25969stream is selected, and @var{timestamp} is automatically converted 25970from AV_TIME_BASE units to the stream specific time_base. 25971@item 25972@var{timestamp}: Timestamp in AVStream.time_base units 25973or, if no stream is specified, in AV_TIME_BASE units. 25974@item 25975@var{flags}: Flags which select direction and seeking mode. 25976@end itemize 25977 25978@item get_duration 25979Get movie duration in AV_TIME_BASE units. 25980 25981@end table 25982 25983@c man end MULTIMEDIA SOURCES 25984