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