| 1 | @chapter Filtering Introduction |
| 2 | @c man begin FILTERING INTRODUCTION |
| 3 | |
| 4 | Filtering in FFmpeg is enabled through the libavfilter library. |
| 5 | |
| 6 | In libavfilter, a filter can have multiple inputs and multiple |
| 7 | outputs. |
| 8 | To illustrate the sorts of things that are possible, we consider the |
| 9 | following filtergraph. |
| 10 | |
| 11 | @example |
| 12 | [main] |
| 13 | input --> split ---------------------> overlay --> output |
| 14 | | ^ |
| 15 | |[tmp] [flip]| |
| 16 | +-----> crop --> vflip -------+ |
| 17 | @end example |
| 18 | |
| 19 | This filtergraph splits the input stream in two streams, then sends one |
| 20 | stream through the crop filter and the vflip filter, before merging it |
| 21 | back with the other stream by overlaying it on top. You can use the |
| 22 | following command to achieve this: |
| 23 | |
| 24 | @example |
| 25 | ffmpeg -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 | |
| 28 | The result will be that the top half of the video is mirrored |
| 29 | onto the bottom half of the output video. |
| 30 | |
| 31 | Filters in the same linear chain are separated by commas, and distinct |
| 32 | linear 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 |
| 35 | chains join are labelled by names enclosed in square brackets. In the |
| 36 | example, the split filter generates two outputs that are associated to |
| 37 | the labels @var{[main]} and @var{[tmp]}. |
| 38 | |
| 39 | The stream sent to the second output of @var{split}, labelled as |
| 40 | @var{[tmp]}, is processed through the @var{crop} filter, which crops |
| 41 | away 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 |
| 43 | split filter (which was labelled as @var{[main]}), and overlay on its |
| 44 | lower half the output generated by the @var{crop,vflip} filterchain. |
| 45 | |
| 46 | Some filters take in input a list of parameters: they are specified |
| 47 | after the filter name and an equal sign, and are separated from each other |
| 48 | by a colon. |
| 49 | |
| 50 | There exist so-called @var{source filters} that do not have an |
| 51 | audio/video input, and @var{sink filters} that will not have audio/video |
| 52 | output. |
| 53 | |
| 54 | @c man end FILTERING INTRODUCTION |
| 55 | |
| 56 | @chapter graph2dot |
| 57 | @c man begin GRAPH2DOT |
| 58 | |
| 59 | The @file{graph2dot} program included in the FFmpeg @file{tools} |
| 60 | directory can be used to parse a filtergraph description and issue a |
| 61 | corresponding textual representation in the dot language. |
| 62 | |
| 63 | Invoke the command: |
| 64 | @example |
| 65 | graph2dot -h |
| 66 | @end example |
| 67 | |
| 68 | to see how to use @file{graph2dot}. |
| 69 | |
| 70 | You can then pass the dot description to the @file{dot} program (from |
| 71 | the graphviz suite of programs) and obtain a graphical representation |
| 72 | of the filtergraph. |
| 73 | |
| 74 | For example the sequence of commands: |
| 75 | @example |
| 76 | echo @var{GRAPH_DESCRIPTION} | \ |
| 77 | tools/graph2dot -o graph.tmp && \ |
| 78 | dot -Tpng graph.tmp -o graph.png && \ |
| 79 | display graph.png |
| 80 | @end example |
| 81 | |
| 82 | can be used to create and display an image representing the graph |
| 83 | described by the @var{GRAPH_DESCRIPTION} string. Note that this string must be |
| 84 | a complete self-contained graph, with its inputs and outputs explicitly defined. |
| 85 | For example if your command line is of the form: |
| 86 | @example |
| 87 | ffmpeg -i infile -vf scale=640:360 outfile |
| 88 | @end example |
| 89 | your @var{GRAPH_DESCRIPTION} string will need to be of the form: |
| 90 | @example |
| 91 | nullsrc,scale=640:360,nullsink |
| 92 | @end example |
| 93 | you may also need to set the @var{nullsrc} parameters and add a @var{format} |
| 94 | filter 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 | |
| 101 | A filtergraph is a directed graph of connected filters. It can contain |
| 102 | cycles, and there can be multiple links between a pair of |
| 103 | filters. Each link has one input pad on one side connecting it to one |
| 104 | filter from which it takes its input, and one output pad on the other |
| 105 | side connecting it to one filter accepting its output. |
| 106 | |
| 107 | Each filter in a filtergraph is an instance of a filter class |
| 108 | registered in the application, which defines the features and the |
| 109 | number of input and output pads of the filter. |
| 110 | |
| 111 | A filter with no input pads is called a "source", and a filter with no |
| 112 | output pads is called a "sink". |
| 113 | |
| 114 | @anchor{Filtergraph syntax} |
| 115 | @section Filtergraph syntax |
| 116 | |
| 117 | A filtergraph has a textual representation, which is |
| 118 | recognized by the @option{-filter}/@option{-vf} and @option{-filter_complex} |
| 119 | options 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 | |
| 123 | A filterchain consists of a sequence of connected filters, each one |
| 124 | connected to the previous one in the sequence. A filterchain is |
| 125 | represented by a list of ","-separated filter descriptions. |
| 126 | |
| 127 | A filtergraph consists of a sequence of filterchains. A sequence of |
| 128 | filterchains is represented by a list of ";"-separated filterchain |
| 129 | descriptions. |
| 130 | |
| 131 | A 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 |
| 135 | described filter is an instance of, and has to be the name of one of |
| 136 | the filter classes registered in the program. |
| 137 | The 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 |
| 141 | initialize the filter instance. It may have one of two forms: |
| 142 | @itemize |
| 143 | |
| 144 | @item |
| 145 | A ':'-separated list of @var{key=value} pairs. |
| 146 | |
| 147 | @item |
| 148 | A ':'-separated list of @var{value}. In this case, the keys are assumed to be |
| 149 | the option names in the order they are declared. E.g. the @code{fade} filter |
| 150 | declares 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 |
| 156 | A ':'-separated list of mixed direct @var{value} and long @var{key=value} |
| 157 | pairs. The direct @var{value} must precede the @var{key=value} pairs, and |
| 158 | follow 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 | |
| 163 | If the option value itself is a list of items (e.g. the @code{format} filter |
| 164 | takes a list of pixel formats), the items in the list are usually separated by |
| 165 | '|'. |
| 166 | |
| 167 | The list of arguments can be quoted using the character "'" as initial |
| 168 | and ending mark, and the character '\' for escaping the characters |
| 169 | within the quoted text; otherwise the argument string is considered |
| 170 | terminated when the next special character (belonging to the set |
| 171 | "[]=;,") is encountered. |
| 172 | |
| 173 | The name and arguments of the filter are optionally preceded and |
| 174 | followed by a list of link labels. |
| 175 | A link label allows one to name a link and associate it to a filter output |
| 176 | or input pad. The preceding labels @var{in_link_1} |
| 177 | ... @var{in_link_N}, are associated to the filter input pads, |
| 178 | the following labels @var{out_link_1} ... @var{out_link_M}, are |
| 179 | associated to the output pads. |
| 180 | |
| 181 | When two link labels with the same name are found in the |
| 182 | filtergraph, a link between the corresponding input and output pad is |
| 183 | created. |
| 184 | |
| 185 | If an output pad is not labelled, it is linked by default to the first |
| 186 | unlabelled input pad of the next filter in the filterchain. |
| 187 | For example in the filterchain |
| 188 | @example |
| 189 | nullsrc, split[L1], [L2]overlay, nullsink |
| 190 | @end example |
| 191 | the split filter instance has two output pads, and the overlay filter |
| 192 | instance 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 |
| 194 | output pad of split is linked to the second input pad of overlay, |
| 195 | which are both unlabelled. |
| 196 | |
| 197 | In a complete filterchain all the unlabelled filter input and output |
| 198 | pads must be connected. A filtergraph is considered valid if all the |
| 199 | filter input and output pads of all the filterchains are connected. |
| 200 | |
| 201 | Libavfilter will automatically insert @ref{scale} filters where format |
| 202 | conversion is required. It is possible to specify swscale flags |
| 203 | for those automatically inserted scalers by prepending |
| 204 | @code{sws_flags=@var{flags};} |
| 205 | to the filtergraph description. |
| 206 | |
| 207 | Here 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 | |
| 220 | Filtergraph description composition entails several levels of |
| 221 | escaping. See @ref{quoting_and_escaping,,the "Quoting and escaping" |
| 222 | section in the ffmpeg-utils(1) manual,ffmpeg-utils} for more |
| 223 | information about the employed escaping procedure. |
| 224 | |
| 225 | A first level escaping affects the content of each filter option |
| 226 | value, which may contain the special character @code{:} used to |
| 227 | separate values, or one of the escaping characters @code{\'}. |
| 228 | |
| 229 | A second level escaping affects the whole filter description, which |
| 230 | may contain the escaping characters @code{\'} or the special |
| 231 | characters @code{[],;} used by the filtergraph description. |
| 232 | |
| 233 | Finally, when you specify a filtergraph on a shell commandline, you |
| 234 | need to perform a third level escaping for the shell special |
| 235 | characters contained within it. |
| 236 | |
| 237 | For example, consider the following string to be embedded in |
| 238 | the @ref{drawtext} filter description @option{text} value: |
| 239 | @example |
| 240 | this is a 'string': may contain one, or more, special characters |
| 241 | @end example |
| 242 | |
| 243 | This string contains the @code{'} special escaping character, and the |
| 244 | @code{:} special character, so it needs to be escaped in this way: |
| 245 | @example |
| 246 | text=this is a \'string\'\: may contain one, or more, special characters |
| 247 | @end example |
| 248 | |
| 249 | A second level of escaping is required when embedding the filter |
| 250 | description in a filtergraph description, in order to escape all the |
| 251 | filtergraph special characters. Thus the example above becomes: |
| 252 | @example |
| 253 | drawtext=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, |
| 256 | also @code{,} needs to be escaped). |
| 257 | |
| 258 | Finally an additional level of escaping is needed when writing the |
| 259 | filtergraph description in a shell command, which depends on the |
| 260 | escaping rules of the adopted shell. For example, assuming that |
| 261 | @code{\} is special and needs to be escaped with another @code{\}, the |
| 262 | previous 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 | |
| 269 | Some filters support a generic @option{enable} option. For the filters |
| 270 | supporting timeline editing, this option can be set to an expression which is |
| 271 | evaluated before sending a frame to the filter. If the evaluation is non-zero, |
| 272 | the filter will be enabled, otherwise the frame will be sent unchanged to the |
| 273 | next filter in the filtergraph. |
| 274 | |
| 275 | The expression accepts the following values: |
| 276 | @table @samp |
| 277 | @item t |
| 278 | timestamp expressed in seconds, NAN if the input timestamp is unknown |
| 279 | |
| 280 | @item n |
| 281 | sequential number of the input frame, starting from 0 |
| 282 | |
| 283 | @item pos |
| 284 | the position in the file of the input frame, NAN if unknown |
| 285 | |
| 286 | @item w |
| 287 | @item h |
| 288 | width and height of the input frame if video |
| 289 | @end table |
| 290 | |
| 291 | Additionally, these filters support an @option{enable} command that can be used |
| 292 | to re-define the expression. |
| 293 | |
| 294 | Like any other filtering option, the @option{enable} option follows the same |
| 295 | rules. |
| 296 | |
| 297 | For example, to enable a blur filter (@ref{smartblur}) from 10 seconds to 3 |
| 298 | minutes, and a @ref{curves} filter starting at 3 seconds: |
| 299 | @example |
| 300 | smartblur = enable='between(t,10,3*60)', |
| 301 | curves = enable='gte(t,3)' : preset=cross_process |
| 302 | @end example |
| 303 | |
| 304 | @c man end FILTERGRAPH DESCRIPTION |
| 305 | |
| 306 | @chapter Audio Filters |
| 307 | @c man begin AUDIO FILTERS |
| 308 | |
| 309 | When you configure your FFmpeg build, you can disable any of the |
| 310 | existing filters using @code{--disable-filters}. |
| 311 | The configure output will show the audio filters included in your |
| 312 | build. |
| 313 | |
| 314 | Below is a description of the currently available audio filters. |
| 315 | |
| 316 | @section adelay |
| 317 | |
| 318 | Delay one or more audio channels. |
| 319 | |
| 320 | Samples in delayed channel are filled with silence. |
| 321 | |
| 322 | The filter accepts the following option: |
| 323 | |
| 324 | @table @option |
| 325 | @item delays |
| 326 | Set list of delays in milliseconds for each channel separated by '|'. |
| 327 | At least one delay greater than 0 should be provided. |
| 328 | Unused delays will be silently ignored. If number of given delays is |
| 329 | smaller than number of channels all remaining channels will not be delayed. |
| 330 | @end table |
| 331 | |
| 332 | @subsection Examples |
| 333 | |
| 334 | @itemize |
| 335 | @item |
| 336 | Delay first channel by 1.5 seconds, the third channel by 0.5 seconds and leave |
| 337 | the second channel (and any other channels that may be present) unchanged. |
| 338 | @example |
| 339 | adelay=1500|0|500 |
| 340 | @end example |
| 341 | @end itemize |
| 342 | |
| 343 | @section aecho |
| 344 | |
| 345 | Apply echoing to the input audio. |
| 346 | |
| 347 | Echoes are reflected sound and can occur naturally amongst mountains |
| 348 | (and sometimes large buildings) when talking or shouting; digital echo |
| 349 | effects emulate this behaviour and are often used to help fill out the |
| 350 | sound of a single instrument or vocal. The time difference between the |
| 351 | original signal and the reflection is the @code{delay}, and the |
| 352 | loudness of the reflected signal is the @code{decay}. |
| 353 | Multiple echoes can have different delays and decays. |
| 354 | |
| 355 | A description of the accepted parameters follows. |
| 356 | |
| 357 | @table @option |
| 358 | @item in_gain |
| 359 | Set input gain of reflected signal. Default is @code{0.6}. |
| 360 | |
| 361 | @item out_gain |
| 362 | Set output gain of reflected signal. Default is @code{0.3}. |
| 363 | |
| 364 | @item delays |
| 365 | Set list of time intervals in milliseconds between original signal and reflections |
| 366 | separated by '|'. Allowed range for each @code{delay} is @code{(0 - 90000.0]}. |
| 367 | Default is @code{1000}. |
| 368 | |
| 369 | @item decays |
| 370 | Set list of loudnesses of reflected signals separated by '|'. |
| 371 | Allowed range for each @code{decay} is @code{(0 - 1.0]}. |
| 372 | Default is @code{0.5}. |
| 373 | @end table |
| 374 | |
| 375 | @subsection Examples |
| 376 | |
| 377 | @itemize |
| 378 | @item |
| 379 | Make it sound as if there are twice as many instruments as are actually playing: |
| 380 | @example |
| 381 | aecho=0.8:0.88:60:0.4 |
| 382 | @end example |
| 383 | |
| 384 | @item |
| 385 | If delay is very short, then it sound like a (metallic) robot playing music: |
| 386 | @example |
| 387 | aecho=0.8:0.88:6:0.4 |
| 388 | @end example |
| 389 | |
| 390 | @item |
| 391 | A longer delay will sound like an open air concert in the mountains: |
| 392 | @example |
| 393 | aecho=0.8:0.9:1000:0.3 |
| 394 | @end example |
| 395 | |
| 396 | @item |
| 397 | Same as above but with one more mountain: |
| 398 | @example |
| 399 | aecho=0.8:0.9:1000|1800:0.3|0.25 |
| 400 | @end example |
| 401 | @end itemize |
| 402 | |
| 403 | @section aeval |
| 404 | |
| 405 | Modify an audio signal according to the specified expressions. |
| 406 | |
| 407 | This filter accepts one or more expressions (one for each channel), |
| 408 | which are evaluated and used to modify a corresponding audio signal. |
| 409 | |
| 410 | It accepts the following parameters: |
| 411 | |
| 412 | @table @option |
| 413 | @item exprs |
| 414 | Set the '|'-separated expressions list for each separate channel. If |
| 415 | the number of input channels is greater than the number of |
| 416 | expressions, the last specified expression is used for the remaining |
| 417 | output channels. |
| 418 | |
| 419 | @item channel_layout, c |
| 420 | Set output channel layout. If not specified, the channel layout is |
| 421 | specified by the number of expressions. If set to @samp{same}, it will |
| 422 | use by default the same input channel layout. |
| 423 | @end table |
| 424 | |
| 425 | Each expression in @var{exprs} can contain the following constants and functions: |
| 426 | |
| 427 | @table @option |
| 428 | @item ch |
| 429 | channel number of the current expression |
| 430 | |
| 431 | @item n |
| 432 | number of the evaluated sample, starting from 0 |
| 433 | |
| 434 | @item s |
| 435 | sample rate |
| 436 | |
| 437 | @item t |
| 438 | time of the evaluated sample expressed in seconds |
| 439 | |
| 440 | @item nb_in_channels |
| 441 | @item nb_out_channels |
| 442 | input and output number of channels |
| 443 | |
| 444 | @item val(CH) |
| 445 | the value of input channel with number @var{CH} |
| 446 | @end table |
| 447 | |
| 448 | Note: this filter is slow. For faster processing you should use a |
| 449 | dedicated filter. |
| 450 | |
| 451 | @subsection Examples |
| 452 | |
| 453 | @itemize |
| 454 | @item |
| 455 | Half volume: |
| 456 | @example |
| 457 | aeval=val(ch)/2:c=same |
| 458 | @end example |
| 459 | |
| 460 | @item |
| 461 | Invert phase of the second channel: |
| 462 | @example |
| 463 | aeval=val(0)|-val(1) |
| 464 | @end example |
| 465 | @end itemize |
| 466 | |
| 467 | @section afade |
| 468 | |
| 469 | Apply fade-in/out effect to input audio. |
| 470 | |
| 471 | A description of the accepted parameters follows. |
| 472 | |
| 473 | @table @option |
| 474 | @item type, t |
| 475 | Specify the effect type, can be either @code{in} for fade-in, or |
| 476 | @code{out} for a fade-out effect. Default is @code{in}. |
| 477 | |
| 478 | @item start_sample, ss |
| 479 | Specify the number of the start sample for starting to apply the fade |
| 480 | effect. Default is 0. |
| 481 | |
| 482 | @item nb_samples, ns |
| 483 | Specify the number of samples for which the fade effect has to last. At |
| 484 | the end of the fade-in effect the output audio will have the same |
| 485 | volume as the input audio, at the end of the fade-out transition |
| 486 | the output audio will be silence. Default is 44100. |
| 487 | |
| 488 | @item start_time, st |
| 489 | Specify the start time of the fade effect. Default is 0. |
| 490 | The value must be specified as a time duration; see |
| 491 | @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils} |
| 492 | for the accepted syntax. |
| 493 | If set this option is used instead of @var{start_sample}. |
| 494 | |
| 495 | @item duration, d |
| 496 | Specify the duration of the fade effect. See |
| 497 | @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils} |
| 498 | for the accepted syntax. |
| 499 | At the end of the fade-in effect the output audio will have the same |
| 500 | volume as the input audio, at the end of the fade-out transition |
| 501 | the output audio will be silence. |
| 502 | By default the duration is determined by @var{nb_samples}. |
| 503 | If set this option is used instead of @var{nb_samples}. |
| 504 | |
| 505 | @item curve |
| 506 | Set curve for fade transition. |
| 507 | |
| 508 | It accepts the following values: |
| 509 | @table @option |
| 510 | @item tri |
| 511 | select triangular, linear slope (default) |
| 512 | @item qsin |
| 513 | select quarter of sine wave |
| 514 | @item hsin |
| 515 | select half of sine wave |
| 516 | @item esin |
| 517 | select exponential sine wave |
| 518 | @item log |
| 519 | select logarithmic |
| 520 | @item par |
| 521 | select inverted parabola |
| 522 | @item qua |
| 523 | select quadratic |
| 524 | @item cub |
| 525 | select cubic |
| 526 | @item squ |
| 527 | select square root |
| 528 | @item cbr |
| 529 | select cubic root |
| 530 | @end table |
| 531 | @end table |
| 532 | |
| 533 | @subsection Examples |
| 534 | |
| 535 | @itemize |
| 536 | @item |
| 537 | Fade in first 15 seconds of audio: |
| 538 | @example |
| 539 | afade=t=in:ss=0:d=15 |
| 540 | @end example |
| 541 | |
| 542 | @item |
| 543 | Fade out last 25 seconds of a 900 seconds audio: |
| 544 | @example |
| 545 | afade=t=out:st=875:d=25 |
| 546 | @end example |
| 547 | @end itemize |
| 548 | |
| 549 | @anchor{aformat} |
| 550 | @section aformat |
| 551 | |
| 552 | Set output format constraints for the input audio. The framework will |
| 553 | negotiate the most appropriate format to minimize conversions. |
| 554 | |
| 555 | It accepts the following parameters: |
| 556 | @table @option |
| 557 | |
| 558 | @item sample_fmts |
| 559 | A '|'-separated list of requested sample formats. |
| 560 | |
| 561 | @item sample_rates |
| 562 | A '|'-separated list of requested sample rates. |
| 563 | |
| 564 | @item channel_layouts |
| 565 | A '|'-separated list of requested channel layouts. |
| 566 | |
| 567 | See @ref{channel layout syntax,,the Channel Layout section in the ffmpeg-utils(1) manual,ffmpeg-utils} |
| 568 | for the required syntax. |
| 569 | @end table |
| 570 | |
| 571 | If a parameter is omitted, all values are allowed. |
| 572 | |
| 573 | Force the output to either unsigned 8-bit or signed 16-bit stereo |
| 574 | @example |
| 575 | aformat=sample_fmts=u8|s16:channel_layouts=stereo |
| 576 | @end example |
| 577 | |
| 578 | @section allpass |
| 579 | |
| 580 | Apply a two-pole all-pass filter with central frequency (in Hz) |
| 581 | @var{frequency}, and filter-width @var{width}. |
| 582 | An all-pass filter changes the audio's frequency to phase relationship |
| 583 | without changing its frequency to amplitude relationship. |
| 584 | |
| 585 | The filter accepts the following options: |
| 586 | |
| 587 | @table @option |
| 588 | @item frequency, f |
| 589 | Set frequency in Hz. |
| 590 | |
| 591 | @item width_type |
| 592 | Set method to specify band-width of filter. |
| 593 | @table @option |
| 594 | @item h |
| 595 | Hz |
| 596 | @item q |
| 597 | Q-Factor |
| 598 | @item o |
| 599 | octave |
| 600 | @item s |
| 601 | slope |
| 602 | @end table |
| 603 | |
| 604 | @item width, w |
| 605 | Specify the band-width of a filter in width_type units. |
| 606 | @end table |
| 607 | |
| 608 | @section amerge |
| 609 | |
| 610 | Merge two or more audio streams into a single multi-channel stream. |
| 611 | |
| 612 | The filter accepts the following options: |
| 613 | |
| 614 | @table @option |
| 615 | |
| 616 | @item inputs |
| 617 | Set the number of inputs. Default is 2. |
| 618 | |
| 619 | @end table |
| 620 | |
| 621 | If the channel layouts of the inputs are disjoint, and therefore compatible, |
| 622 | the channel layout of the output will be set accordingly and the channels |
| 623 | will be reordered as necessary. If the channel layouts of the inputs are not |
| 624 | disjoint, the output will have all the channels of the first input then all |
| 625 | the channels of the second input, in that order, and the channel layout of |
| 626 | the output will be the default value corresponding to the total number of |
| 627 | channels. |
| 628 | |
| 629 | For example, if the first input is in 2.1 (FL+FR+LF) and the second input |
| 630 | is FC+BL+BR, then the output will be in 5.1, with the channels in the |
| 631 | following order: a1, a2, b1, a3, b2, b3 (a1 is the first channel of the |
| 632 | first input, b1 is the first channel of the second input). |
| 633 | |
| 634 | On the other hand, if both input are in stereo, the output channels will be |
| 635 | in the default order: a1, a2, b1, b2, and the channel layout will be |
| 636 | arbitrarily set to 4.0, which may or may not be the expected value. |
| 637 | |
| 638 | All inputs must have the same sample rate, and format. |
| 639 | |
| 640 | If inputs do not have the same duration, the output will stop with the |
| 641 | shortest. |
| 642 | |
| 643 | @subsection Examples |
| 644 | |
| 645 | @itemize |
| 646 | @item |
| 647 | Merge two mono files into a stereo stream: |
| 648 | @example |
| 649 | amovie=left.wav [l] ; amovie=right.mp3 [r] ; [l] [r] amerge |
| 650 | @end example |
| 651 | |
| 652 | @item |
| 653 | Multiple merges assuming 1 video stream and 6 audio streams in @file{input.mkv}: |
| 654 | @example |
| 655 | ffmpeg -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 |
| 656 | @end example |
| 657 | @end itemize |
| 658 | |
| 659 | @section amix |
| 660 | |
| 661 | Mixes multiple audio inputs into a single output. |
| 662 | |
| 663 | Note that this filter only supports float samples (the @var{amerge} |
| 664 | and @var{pan} audio filters support many formats). If the @var{amix} |
| 665 | input has integer samples then @ref{aresample} will be automatically |
| 666 | inserted to perform the conversion to float samples. |
| 667 | |
| 668 | For example |
| 669 | @example |
| 670 | ffmpeg -i INPUT1 -i INPUT2 -i INPUT3 -filter_complex amix=inputs=3:duration=first:dropout_transition=3 OUTPUT |
| 671 | @end example |
| 672 | will mix 3 input audio streams to a single output with the same duration as the |
| 673 | first input and a dropout transition time of 3 seconds. |
| 674 | |
| 675 | It accepts the following parameters: |
| 676 | @table @option |
| 677 | |
| 678 | @item inputs |
| 679 | The number of inputs. If unspecified, it defaults to 2. |
| 680 | |
| 681 | @item duration |
| 682 | How to determine the end-of-stream. |
| 683 | @table @option |
| 684 | |
| 685 | @item longest |
| 686 | The duration of the longest input. (default) |
| 687 | |
| 688 | @item shortest |
| 689 | The duration of the shortest input. |
| 690 | |
| 691 | @item first |
| 692 | The duration of the first input. |
| 693 | |
| 694 | @end table |
| 695 | |
| 696 | @item dropout_transition |
| 697 | The transition time, in seconds, for volume renormalization when an input |
| 698 | stream ends. The default value is 2 seconds. |
| 699 | |
| 700 | @end table |
| 701 | |
| 702 | @section anull |
| 703 | |
| 704 | Pass the audio source unchanged to the output. |
| 705 | |
| 706 | @section apad |
| 707 | |
| 708 | Pad the end of an audio stream with silence. |
| 709 | |
| 710 | This can be used together with @command{ffmpeg} @option{-shortest} to |
| 711 | extend audio streams to the same length as the video stream. |
| 712 | |
| 713 | A description of the accepted options follows. |
| 714 | |
| 715 | @table @option |
| 716 | @item packet_size |
| 717 | Set silence packet size. Default value is 4096. |
| 718 | |
| 719 | @item pad_len |
| 720 | Set the number of samples of silence to add to the end. After the |
| 721 | value is reached, the stream is terminated. This option is mutually |
| 722 | exclusive with @option{whole_len}. |
| 723 | |
| 724 | @item whole_len |
| 725 | Set the minimum total number of samples in the output audio stream. If |
| 726 | the value is longer than the input audio length, silence is added to |
| 727 | the end, until the value is reached. This option is mutually exclusive |
| 728 | with @option{pad_len}. |
| 729 | @end table |
| 730 | |
| 731 | If neither the @option{pad_len} nor the @option{whole_len} option is |
| 732 | set, the filter will add silence to the end of the input stream |
| 733 | indefinitely. |
| 734 | |
| 735 | @subsection Examples |
| 736 | |
| 737 | @itemize |
| 738 | @item |
| 739 | Add 1024 samples of silence to the end of the input: |
| 740 | @example |
| 741 | apad=pad_len=1024 |
| 742 | @end example |
| 743 | |
| 744 | @item |
| 745 | Make sure the audio output will contain at least 10000 samples, pad |
| 746 | the input with silence if required: |
| 747 | @example |
| 748 | apad=whole_len=10000 |
| 749 | @end example |
| 750 | |
| 751 | @item |
| 752 | Use @command{ffmpeg} to pad the audio input with silence, so that the |
| 753 | video stream will always result the shortest and will be converted |
| 754 | until the end in the output file when using the @option{shortest} |
| 755 | option: |
| 756 | @example |
| 757 | ffmpeg -i VIDEO -i AUDIO -filter_complex "[1:0]apad" -shortest OUTPUT |
| 758 | @end example |
| 759 | @end itemize |
| 760 | |
| 761 | @section aphaser |
| 762 | Add a phasing effect to the input audio. |
| 763 | |
| 764 | A phaser filter creates series of peaks and troughs in the frequency spectrum. |
| 765 | The position of the peaks and troughs are modulated so that they vary over time, creating a sweeping effect. |
| 766 | |
| 767 | A description of the accepted parameters follows. |
| 768 | |
| 769 | @table @option |
| 770 | @item in_gain |
| 771 | Set input gain. Default is 0.4. |
| 772 | |
| 773 | @item out_gain |
| 774 | Set output gain. Default is 0.74 |
| 775 | |
| 776 | @item delay |
| 777 | Set delay in milliseconds. Default is 3.0. |
| 778 | |
| 779 | @item decay |
| 780 | Set decay. Default is 0.4. |
| 781 | |
| 782 | @item speed |
| 783 | Set modulation speed in Hz. Default is 0.5. |
| 784 | |
| 785 | @item type |
| 786 | Set modulation type. Default is triangular. |
| 787 | |
| 788 | It accepts the following values: |
| 789 | @table @samp |
| 790 | @item triangular, t |
| 791 | @item sinusoidal, s |
| 792 | @end table |
| 793 | @end table |
| 794 | |
| 795 | @anchor{aresample} |
| 796 | @section aresample |
| 797 | |
| 798 | Resample the input audio to the specified parameters, using the |
| 799 | libswresample library. If none are specified then the filter will |
| 800 | automatically convert between its input and output. |
| 801 | |
| 802 | This filter is also able to stretch/squeeze the audio data to make it match |
| 803 | the timestamps or to inject silence / cut out audio to make it match the |
| 804 | timestamps, do a combination of both or do neither. |
| 805 | |
| 806 | The filter accepts the syntax |
| 807 | [@var{sample_rate}:]@var{resampler_options}, where @var{sample_rate} |
| 808 | expresses a sample rate and @var{resampler_options} is a list of |
| 809 | @var{key}=@var{value} pairs, separated by ":". See the |
| 810 | ffmpeg-resampler manual for the complete list of supported options. |
| 811 | |
| 812 | @subsection Examples |
| 813 | |
| 814 | @itemize |
| 815 | @item |
| 816 | Resample the input audio to 44100Hz: |
| 817 | @example |
| 818 | aresample=44100 |
| 819 | @end example |
| 820 | |
| 821 | @item |
| 822 | Stretch/squeeze samples to the given timestamps, with a maximum of 1000 |
| 823 | samples per second compensation: |
| 824 | @example |
| 825 | aresample=async=1000 |
| 826 | @end example |
| 827 | @end itemize |
| 828 | |
| 829 | @section asetnsamples |
| 830 | |
| 831 | Set the number of samples per each output audio frame. |
| 832 | |
| 833 | The last output packet may contain a different number of samples, as |
| 834 | the filter will flush all the remaining samples when the input audio |
| 835 | signal its end. |
| 836 | |
| 837 | The filter accepts the following options: |
| 838 | |
| 839 | @table @option |
| 840 | |
| 841 | @item nb_out_samples, n |
| 842 | Set the number of frames per each output audio frame. The number is |
| 843 | intended as the number of samples @emph{per each channel}. |
| 844 | Default value is 1024. |
| 845 | |
| 846 | @item pad, p |
| 847 | If set to 1, the filter will pad the last audio frame with zeroes, so |
| 848 | that the last frame will contain the same number of samples as the |
| 849 | previous ones. Default value is 1. |
| 850 | @end table |
| 851 | |
| 852 | For example, to set the number of per-frame samples to 1234 and |
| 853 | disable padding for the last frame, use: |
| 854 | @example |
| 855 | asetnsamples=n=1234:p=0 |
| 856 | @end example |
| 857 | |
| 858 | @section asetrate |
| 859 | |
| 860 | Set the sample rate without altering the PCM data. |
| 861 | This will result in a change of speed and pitch. |
| 862 | |
| 863 | The filter accepts the following options: |
| 864 | |
| 865 | @table @option |
| 866 | @item sample_rate, r |
| 867 | Set the output sample rate. Default is 44100 Hz. |
| 868 | @end table |
| 869 | |
| 870 | @section ashowinfo |
| 871 | |
| 872 | Show a line containing various information for each input audio frame. |
| 873 | The input audio is not modified. |
| 874 | |
| 875 | The shown line contains a sequence of key/value pairs of the form |
| 876 | @var{key}:@var{value}. |
| 877 | |
| 878 | The following values are shown in the output: |
| 879 | |
| 880 | @table @option |
| 881 | @item n |
| 882 | The (sequential) number of the input frame, starting from 0. |
| 883 | |
| 884 | @item pts |
| 885 | The presentation timestamp of the input frame, in time base units; the time base |
| 886 | depends on the filter input pad, and is usually 1/@var{sample_rate}. |
| 887 | |
| 888 | @item pts_time |
| 889 | The presentation timestamp of the input frame in seconds. |
| 890 | |
| 891 | @item pos |
| 892 | position of the frame in the input stream, -1 if this information in |
| 893 | unavailable and/or meaningless (for example in case of synthetic audio) |
| 894 | |
| 895 | @item fmt |
| 896 | The sample format. |
| 897 | |
| 898 | @item chlayout |
| 899 | The channel layout. |
| 900 | |
| 901 | @item rate |
| 902 | The sample rate for the audio frame. |
| 903 | |
| 904 | @item nb_samples |
| 905 | The number of samples (per channel) in the frame. |
| 906 | |
| 907 | @item checksum |
| 908 | The Adler-32 checksum (printed in hexadecimal) of the audio data. For planar |
| 909 | audio, the data is treated as if all the planes were concatenated. |
| 910 | |
| 911 | @item plane_checksums |
| 912 | A list of Adler-32 checksums for each data plane. |
| 913 | @end table |
| 914 | |
| 915 | @section astats |
| 916 | |
| 917 | Display time domain statistical information about the audio channels. |
| 918 | Statistics are calculated and displayed for each audio channel and, |
| 919 | where applicable, an overall figure is also given. |
| 920 | |
| 921 | It accepts the following option: |
| 922 | @table @option |
| 923 | @item length |
| 924 | Short window length in seconds, used for peak and trough RMS measurement. |
| 925 | Default is @code{0.05} (50 miliseconds). Allowed range is @code{[0.1 - 10]}. |
| 926 | @end table |
| 927 | |
| 928 | A description of each shown parameter follows: |
| 929 | |
| 930 | @table @option |
| 931 | @item DC offset |
| 932 | Mean amplitude displacement from zero. |
| 933 | |
| 934 | @item Min level |
| 935 | Minimal sample level. |
| 936 | |
| 937 | @item Max level |
| 938 | Maximal sample level. |
| 939 | |
| 940 | @item Peak level dB |
| 941 | @item RMS level dB |
| 942 | Standard peak and RMS level measured in dBFS. |
| 943 | |
| 944 | @item RMS peak dB |
| 945 | @item RMS trough dB |
| 946 | Peak and trough values for RMS level measured over a short window. |
| 947 | |
| 948 | @item Crest factor |
| 949 | Standard ratio of peak to RMS level (note: not in dB). |
| 950 | |
| 951 | @item Flat factor |
| 952 | Flatness (i.e. consecutive samples with the same value) of the signal at its peak levels |
| 953 | (i.e. either @var{Min level} or @var{Max level}). |
| 954 | |
| 955 | @item Peak count |
| 956 | Number of occasions (not the number of samples) that the signal attained either |
| 957 | @var{Min level} or @var{Max level}. |
| 958 | @end table |
| 959 | |
| 960 | @section astreamsync |
| 961 | |
| 962 | Forward two audio streams and control the order the buffers are forwarded. |
| 963 | |
| 964 | The filter accepts the following options: |
| 965 | |
| 966 | @table @option |
| 967 | @item expr, e |
| 968 | Set the expression deciding which stream should be |
| 969 | forwarded next: if the result is negative, the first stream is forwarded; if |
| 970 | the result is positive or zero, the second stream is forwarded. It can use |
| 971 | the following variables: |
| 972 | |
| 973 | @table @var |
| 974 | @item b1 b2 |
| 975 | number of buffers forwarded so far on each stream |
| 976 | @item s1 s2 |
| 977 | number of samples forwarded so far on each stream |
| 978 | @item t1 t2 |
| 979 | current timestamp of each stream |
| 980 | @end table |
| 981 | |
| 982 | The default value is @code{t1-t2}, which means to always forward the stream |
| 983 | that has a smaller timestamp. |
| 984 | @end table |
| 985 | |
| 986 | @subsection Examples |
| 987 | |
| 988 | Stress-test @code{amerge} by randomly sending buffers on the wrong |
| 989 | input, while avoiding too much of a desynchronization: |
| 990 | @example |
| 991 | amovie=file.ogg [a] ; amovie=file.mp3 [b] ; |
| 992 | [a] [b] astreamsync=(2*random(1))-1+tanh(5*(t1-t2)) [a2] [b2] ; |
| 993 | [a2] [b2] amerge |
| 994 | @end example |
| 995 | |
| 996 | @section asyncts |
| 997 | |
| 998 | Synchronize audio data with timestamps by squeezing/stretching it and/or |
| 999 | dropping samples/adding silence when needed. |
| 1000 | |
| 1001 | This filter is not built by default, please use @ref{aresample} to do squeezing/stretching. |
| 1002 | |
| 1003 | It accepts the following parameters: |
| 1004 | @table @option |
| 1005 | |
| 1006 | @item compensate |
| 1007 | Enable stretching/squeezing the data to make it match the timestamps. Disabled |
| 1008 | by default. When disabled, time gaps are covered with silence. |
| 1009 | |
| 1010 | @item min_delta |
| 1011 | The minimum difference between timestamps and audio data (in seconds) to trigger |
| 1012 | adding/dropping samples. The default value is 0.1. If you get an imperfect |
| 1013 | sync with this filter, try setting this parameter to 0. |
| 1014 | |
| 1015 | @item max_comp |
| 1016 | The maximum compensation in samples per second. Only relevant with compensate=1. |
| 1017 | The default value is 500. |
| 1018 | |
| 1019 | @item first_pts |
| 1020 | Assume that the first PTS should be this value. The time base is 1 / sample |
| 1021 | rate. This allows for padding/trimming at the start of the stream. By default, |
| 1022 | no assumption is made about the first frame's expected PTS, so no padding or |
| 1023 | trimming is done. For example, this could be set to 0 to pad the beginning with |
| 1024 | silence if an audio stream starts after the video stream or to trim any samples |
| 1025 | with a negative PTS due to encoder delay. |
| 1026 | |
| 1027 | @end table |
| 1028 | |
| 1029 | @section atempo |
| 1030 | |
| 1031 | Adjust audio tempo. |
| 1032 | |
| 1033 | The filter accepts exactly one parameter, the audio tempo. If not |
| 1034 | specified then the filter will assume nominal 1.0 tempo. Tempo must |
| 1035 | be in the [0.5, 2.0] range. |
| 1036 | |
| 1037 | @subsection Examples |
| 1038 | |
| 1039 | @itemize |
| 1040 | @item |
| 1041 | Slow down audio to 80% tempo: |
| 1042 | @example |
| 1043 | atempo=0.8 |
| 1044 | @end example |
| 1045 | |
| 1046 | @item |
| 1047 | To speed up audio to 125% tempo: |
| 1048 | @example |
| 1049 | atempo=1.25 |
| 1050 | @end example |
| 1051 | @end itemize |
| 1052 | |
| 1053 | @section atrim |
| 1054 | |
| 1055 | Trim the input so that the output contains one continuous subpart of the input. |
| 1056 | |
| 1057 | It accepts the following parameters: |
| 1058 | @table @option |
| 1059 | @item start |
| 1060 | Timestamp (in seconds) of the start of the section to keep. I.e. the audio |
| 1061 | sample with the timestamp @var{start} will be the first sample in the output. |
| 1062 | |
| 1063 | @item end |
| 1064 | Specify time of the first audio sample that will be dropped, i.e. the |
| 1065 | audio sample immediately preceding the one with the timestamp @var{end} will be |
| 1066 | the last sample in the output. |
| 1067 | |
| 1068 | @item start_pts |
| 1069 | Same as @var{start}, except this option sets the start timestamp in samples |
| 1070 | instead of seconds. |
| 1071 | |
| 1072 | @item end_pts |
| 1073 | Same as @var{end}, except this option sets the end timestamp in samples instead |
| 1074 | of seconds. |
| 1075 | |
| 1076 | @item duration |
| 1077 | The maximum duration of the output in seconds. |
| 1078 | |
| 1079 | @item start_sample |
| 1080 | The number of the first sample that should be output. |
| 1081 | |
| 1082 | @item end_sample |
| 1083 | The number of the first sample that should be dropped. |
| 1084 | @end table |
| 1085 | |
| 1086 | @option{start}, @option{end}, and @option{duration} are expressed as time |
| 1087 | duration specifications; see |
| 1088 | @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}. |
| 1089 | |
| 1090 | Note that the first two sets of the start/end options and the @option{duration} |
| 1091 | option look at the frame timestamp, while the _sample options simply count the |
| 1092 | samples that pass through the filter. So start/end_pts and start/end_sample will |
| 1093 | give different results when the timestamps are wrong, inexact or do not start at |
| 1094 | zero. Also note that this filter does not modify the timestamps. If you wish |
| 1095 | to have the output timestamps start at zero, insert the asetpts filter after the |
| 1096 | atrim filter. |
| 1097 | |
| 1098 | If multiple start or end options are set, this filter tries to be greedy and |
| 1099 | keep all samples that match at least one of the specified constraints. To keep |
| 1100 | only the part that matches all the constraints at once, chain multiple atrim |
| 1101 | filters. |
| 1102 | |
| 1103 | The defaults are such that all the input is kept. So it is possible to set e.g. |
| 1104 | just the end values to keep everything before the specified time. |
| 1105 | |
| 1106 | Examples: |
| 1107 | @itemize |
| 1108 | @item |
| 1109 | Drop everything except the second minute of input: |
| 1110 | @example |
| 1111 | ffmpeg -i INPUT -af atrim=60:120 |
| 1112 | @end example |
| 1113 | |
| 1114 | @item |
| 1115 | Keep only the first 1000 samples: |
| 1116 | @example |
| 1117 | ffmpeg -i INPUT -af atrim=end_sample=1000 |
| 1118 | @end example |
| 1119 | |
| 1120 | @end itemize |
| 1121 | |
| 1122 | @section bandpass |
| 1123 | |
| 1124 | Apply a two-pole Butterworth band-pass filter with central |
| 1125 | frequency @var{frequency}, and (3dB-point) band-width width. |
| 1126 | The @var{csg} option selects a constant skirt gain (peak gain = Q) |
| 1127 | instead of the default: constant 0dB peak gain. |
| 1128 | The filter roll off at 6dB per octave (20dB per decade). |
| 1129 | |
| 1130 | The filter accepts the following options: |
| 1131 | |
| 1132 | @table @option |
| 1133 | @item frequency, f |
| 1134 | Set the filter's central frequency. Default is @code{3000}. |
| 1135 | |
| 1136 | @item csg |
| 1137 | Constant skirt gain if set to 1. Defaults to 0. |
| 1138 | |
| 1139 | @item width_type |
| 1140 | Set method to specify band-width of filter. |
| 1141 | @table @option |
| 1142 | @item h |
| 1143 | Hz |
| 1144 | @item q |
| 1145 | Q-Factor |
| 1146 | @item o |
| 1147 | octave |
| 1148 | @item s |
| 1149 | slope |
| 1150 | @end table |
| 1151 | |
| 1152 | @item width, w |
| 1153 | Specify the band-width of a filter in width_type units. |
| 1154 | @end table |
| 1155 | |
| 1156 | @section bandreject |
| 1157 | |
| 1158 | Apply a two-pole Butterworth band-reject filter with central |
| 1159 | frequency @var{frequency}, and (3dB-point) band-width @var{width}. |
| 1160 | The filter roll off at 6dB per octave (20dB per decade). |
| 1161 | |
| 1162 | The filter accepts the following options: |
| 1163 | |
| 1164 | @table @option |
| 1165 | @item frequency, f |
| 1166 | Set the filter's central frequency. Default is @code{3000}. |
| 1167 | |
| 1168 | @item width_type |
| 1169 | Set method to specify band-width of filter. |
| 1170 | @table @option |
| 1171 | @item h |
| 1172 | Hz |
| 1173 | @item q |
| 1174 | Q-Factor |
| 1175 | @item o |
| 1176 | octave |
| 1177 | @item s |
| 1178 | slope |
| 1179 | @end table |
| 1180 | |
| 1181 | @item width, w |
| 1182 | Specify the band-width of a filter in width_type units. |
| 1183 | @end table |
| 1184 | |
| 1185 | @section bass |
| 1186 | |
| 1187 | Boost or cut the bass (lower) frequencies of the audio using a two-pole |
| 1188 | shelving filter with a response similar to that of a standard |
| 1189 | hi-fi's tone-controls. This is also known as shelving equalisation (EQ). |
| 1190 | |
| 1191 | The filter accepts the following options: |
| 1192 | |
| 1193 | @table @option |
| 1194 | @item gain, g |
| 1195 | Give the gain at 0 Hz. Its useful range is about -20 |
| 1196 | (for a large cut) to +20 (for a large boost). |
| 1197 | Beware of clipping when using a positive gain. |
| 1198 | |
| 1199 | @item frequency, f |
| 1200 | Set the filter's central frequency and so can be used |
| 1201 | to extend or reduce the frequency range to be boosted or cut. |
| 1202 | The default value is @code{100} Hz. |
| 1203 | |
| 1204 | @item width_type |
| 1205 | Set method to specify band-width of filter. |
| 1206 | @table @option |
| 1207 | @item h |
| 1208 | Hz |
| 1209 | @item q |
| 1210 | Q-Factor |
| 1211 | @item o |
| 1212 | octave |
| 1213 | @item s |
| 1214 | slope |
| 1215 | @end table |
| 1216 | |
| 1217 | @item width, w |
| 1218 | Determine how steep is the filter's shelf transition. |
| 1219 | @end table |
| 1220 | |
| 1221 | @section biquad |
| 1222 | |
| 1223 | Apply a biquad IIR filter with the given coefficients. |
| 1224 | Where @var{b0}, @var{b1}, @var{b2} and @var{a0}, @var{a1}, @var{a2} |
| 1225 | are the numerator and denominator coefficients respectively. |
| 1226 | |
| 1227 | @section bs2b |
| 1228 | Bauer stereo to binaural transformation, which improves headphone listening of |
| 1229 | stereo audio records. |
| 1230 | |
| 1231 | It accepts the following parameters: |
| 1232 | @table @option |
| 1233 | |
| 1234 | @item profile |
| 1235 | Pre-defined crossfeed level. |
| 1236 | @table @option |
| 1237 | |
| 1238 | @item default |
| 1239 | Default level (fcut=700, feed=50). |
| 1240 | |
| 1241 | @item cmoy |
| 1242 | Chu Moy circuit (fcut=700, feed=60). |
| 1243 | |
| 1244 | @item jmeier |
| 1245 | Jan Meier circuit (fcut=650, feed=95). |
| 1246 | |
| 1247 | @end table |
| 1248 | |
| 1249 | @item fcut |
| 1250 | Cut frequency (in Hz). |
| 1251 | |
| 1252 | @item feed |
| 1253 | Feed level (in Hz). |
| 1254 | |
| 1255 | @end table |
| 1256 | |
| 1257 | @section channelmap |
| 1258 | |
| 1259 | Remap input channels to new locations. |
| 1260 | |
| 1261 | It accepts the following parameters: |
| 1262 | @table @option |
| 1263 | @item channel_layout |
| 1264 | The channel layout of the output stream. |
| 1265 | |
| 1266 | @item map |
| 1267 | Map channels from input to output. The argument is a '|'-separated list of |
| 1268 | mappings, each in the @code{@var{in_channel}-@var{out_channel}} or |
| 1269 | @var{in_channel} form. @var{in_channel} can be either the name of the input |
| 1270 | channel (e.g. FL for front left) or its index in the input channel layout. |
| 1271 | @var{out_channel} is the name of the output channel or its index in the output |
| 1272 | channel layout. If @var{out_channel} is not given then it is implicitly an |
| 1273 | index, starting with zero and increasing by one for each mapping. |
| 1274 | @end table |
| 1275 | |
| 1276 | If no mapping is present, the filter will implicitly map input channels to |
| 1277 | output channels, preserving indices. |
| 1278 | |
| 1279 | For example, assuming a 5.1+downmix input MOV file, |
| 1280 | @example |
| 1281 | ffmpeg -i in.mov -filter 'channelmap=map=DL-FL|DR-FR' out.wav |
| 1282 | @end example |
| 1283 | will create an output WAV file tagged as stereo from the downmix channels of |
| 1284 | the input. |
| 1285 | |
| 1286 | To fix a 5.1 WAV improperly encoded in AAC's native channel order |
| 1287 | @example |
| 1288 | ffmpeg -i in.wav -filter 'channelmap=1|2|0|5|3|4:channel_layout=5.1' out.wav |
| 1289 | @end example |
| 1290 | |
| 1291 | @section channelsplit |
| 1292 | |
| 1293 | Split each channel from an input audio stream into a separate output stream. |
| 1294 | |
| 1295 | It accepts the following parameters: |
| 1296 | @table @option |
| 1297 | @item channel_layout |
| 1298 | The channel layout of the input stream. The default is "stereo". |
| 1299 | @end table |
| 1300 | |
| 1301 | For example, assuming a stereo input MP3 file, |
| 1302 | @example |
| 1303 | ffmpeg -i in.mp3 -filter_complex channelsplit out.mkv |
| 1304 | @end example |
| 1305 | will create an output Matroska file with two audio streams, one containing only |
| 1306 | the left channel and the other the right channel. |
| 1307 | |
| 1308 | Split a 5.1 WAV file into per-channel files: |
| 1309 | @example |
| 1310 | ffmpeg -i in.wav -filter_complex |
| 1311 | 'channelsplit=channel_layout=5.1[FL][FR][FC][LFE][SL][SR]' |
| 1312 | -map '[FL]' front_left.wav -map '[FR]' front_right.wav -map '[FC]' |
| 1313 | front_center.wav -map '[LFE]' lfe.wav -map '[SL]' side_left.wav -map '[SR]' |
| 1314 | side_right.wav |
| 1315 | @end example |
| 1316 | |
| 1317 | @section compand |
| 1318 | Compress or expand the audio's dynamic range. |
| 1319 | |
| 1320 | It accepts the following parameters: |
| 1321 | |
| 1322 | @table @option |
| 1323 | |
| 1324 | @item attacks |
| 1325 | @item decays |
| 1326 | A list of times in seconds for each channel over which the instantaneous level |
| 1327 | of the input signal is averaged to determine its volume. @var{attacks} refers to |
| 1328 | increase of volume and @var{decays} refers to decrease of volume. For most |
| 1329 | situations, the attack time (response to the audio getting louder) should be |
| 1330 | shorter than the decay time, because the human ear is more sensitive to sudden |
| 1331 | loud audio than sudden soft audio. A typical value for attack is 0.3 seconds and |
| 1332 | a typical value for decay is 0.8 seconds. |
| 1333 | |
| 1334 | @item points |
| 1335 | A list of points for the transfer function, specified in dB relative to the |
| 1336 | maximum possible signal amplitude. Each key points list must be defined using |
| 1337 | the following syntax: @code{x0/y0|x1/y1|x2/y2|....} or |
| 1338 | @code{x0/y0 x1/y1 x2/y2 ....} |
| 1339 | |
| 1340 | The input values must be in strictly increasing order but the transfer function |
| 1341 | does not have to be monotonically rising. The point @code{0/0} is assumed but |
| 1342 | may be overridden (by @code{0/out-dBn}). Typical values for the transfer |
| 1343 | function are @code{-70/-70|-60/-20}. |
| 1344 | |
| 1345 | @item soft-knee |
| 1346 | Set the curve radius in dB for all joints. It defaults to 0.01. |
| 1347 | |
| 1348 | @item gain |
| 1349 | Set the additional gain in dB to be applied at all points on the transfer |
| 1350 | function. This allows for easy adjustment of the overall gain. |
| 1351 | It defaults to 0. |
| 1352 | |
| 1353 | @item volume |
| 1354 | Set an initial volume, in dB, to be assumed for each channel when filtering |
| 1355 | starts. This permits the user to supply a nominal level initially, so that, for |
| 1356 | example, a very large gain is not applied to initial signal levels before the |
| 1357 | companding has begun to operate. A typical value for audio which is initially |
| 1358 | quiet is -90 dB. It defaults to 0. |
| 1359 | |
| 1360 | @item delay |
| 1361 | Set a delay, in seconds. The input audio is analyzed immediately, but audio is |
| 1362 | delayed before being fed to the volume adjuster. Specifying a delay |
| 1363 | approximately equal to the attack/decay times allows the filter to effectively |
| 1364 | operate in predictive rather than reactive mode. It defaults to 0. |
| 1365 | |
| 1366 | @end table |
| 1367 | |
| 1368 | @subsection Examples |
| 1369 | |
| 1370 | @itemize |
| 1371 | @item |
| 1372 | Make music with both quiet and loud passages suitable for listening to in a |
| 1373 | noisy environment: |
| 1374 | @example |
| 1375 | compand=.3|.3:1|1:-90/-60|-60/-40|-40/-30|-20/-20:6:0:-90:0.2 |
| 1376 | @end example |
| 1377 | |
| 1378 | @item |
| 1379 | A noise gate for when the noise is at a lower level than the signal: |
| 1380 | @example |
| 1381 | compand=.1|.1:.2|.2:-900/-900|-50.1/-900|-50/-50:.01:0:-90:.1 |
| 1382 | @end example |
| 1383 | |
| 1384 | @item |
| 1385 | Here is another noise gate, this time for when the noise is at a higher level |
| 1386 | than the signal (making it, in some ways, similar to squelch): |
| 1387 | @example |
| 1388 | compand=.1|.1:.1|.1:-45.1/-45.1|-45/-900|0/-900:.01:45:-90:.1 |
| 1389 | @end example |
| 1390 | @end itemize |
| 1391 | |
| 1392 | @section earwax |
| 1393 | |
| 1394 | Make audio easier to listen to on headphones. |
| 1395 | |
| 1396 | This filter adds `cues' to 44.1kHz stereo (i.e. audio CD format) audio |
| 1397 | so that when listened to on headphones the stereo image is moved from |
| 1398 | inside your head (standard for headphones) to outside and in front of |
| 1399 | the listener (standard for speakers). |
| 1400 | |
| 1401 | Ported from SoX. |
| 1402 | |
| 1403 | @section equalizer |
| 1404 | |
| 1405 | Apply a two-pole peaking equalisation (EQ) filter. With this |
| 1406 | filter, the signal-level at and around a selected frequency can |
| 1407 | be increased or decreased, whilst (unlike bandpass and bandreject |
| 1408 | filters) that at all other frequencies is unchanged. |
| 1409 | |
| 1410 | In order to produce complex equalisation curves, this filter can |
| 1411 | be given several times, each with a different central frequency. |
| 1412 | |
| 1413 | The filter accepts the following options: |
| 1414 | |
| 1415 | @table @option |
| 1416 | @item frequency, f |
| 1417 | Set the filter's central frequency in Hz. |
| 1418 | |
| 1419 | @item width_type |
| 1420 | Set method to specify band-width of filter. |
| 1421 | @table @option |
| 1422 | @item h |
| 1423 | Hz |
| 1424 | @item q |
| 1425 | Q-Factor |
| 1426 | @item o |
| 1427 | octave |
| 1428 | @item s |
| 1429 | slope |
| 1430 | @end table |
| 1431 | |
| 1432 | @item width, w |
| 1433 | Specify the band-width of a filter in width_type units. |
| 1434 | |
| 1435 | @item gain, g |
| 1436 | Set the required gain or attenuation in dB. |
| 1437 | Beware of clipping when using a positive gain. |
| 1438 | @end table |
| 1439 | |
| 1440 | @subsection Examples |
| 1441 | @itemize |
| 1442 | @item |
| 1443 | Attenuate 10 dB at 1000 Hz, with a bandwidth of 200 Hz: |
| 1444 | @example |
| 1445 | equalizer=f=1000:width_type=h:width=200:g=-10 |
| 1446 | @end example |
| 1447 | |
| 1448 | @item |
| 1449 | Apply 2 dB gain at 1000 Hz with Q 1 and attenuate 5 dB at 100 Hz with Q 2: |
| 1450 | @example |
| 1451 | equalizer=f=1000:width_type=q:width=1:g=2,equalizer=f=100:width_type=q:width=2:g=-5 |
| 1452 | @end example |
| 1453 | @end itemize |
| 1454 | |
| 1455 | @section flanger |
| 1456 | Apply a flanging effect to the audio. |
| 1457 | |
| 1458 | The filter accepts the following options: |
| 1459 | |
| 1460 | @table @option |
| 1461 | @item delay |
| 1462 | Set base delay in milliseconds. Range from 0 to 30. Default value is 0. |
| 1463 | |
| 1464 | @item depth |
| 1465 | Set added swep delay in milliseconds. Range from 0 to 10. Default value is 2. |
| 1466 | |
| 1467 | @item regen |
| 1468 | Set percentage regeneneration (delayed signal feedback). Range from -95 to 95. |
| 1469 | Default value is 0. |
| 1470 | |
| 1471 | @item width |
| 1472 | Set percentage of delayed signal mixed with original. Range from 0 to 100. |
| 1473 | Default valu is 71. |
| 1474 | |
| 1475 | @item speed |
| 1476 | Set sweeps per second (Hz). Range from 0.1 to 10. Default value is 0.5. |
| 1477 | |
| 1478 | @item shape |
| 1479 | Set swept wave shape, can be @var{triangular} or @var{sinusoidal}. |
| 1480 | Default value is @var{sinusoidal}. |
| 1481 | |
| 1482 | @item phase |
| 1483 | Set swept wave percentage-shift for multi channel. Range from 0 to 100. |
| 1484 | Default value is 25. |
| 1485 | |
| 1486 | @item interp |
| 1487 | Set delay-line interpolation, @var{linear} or @var{quadratic}. |
| 1488 | Default is @var{linear}. |
| 1489 | @end table |
| 1490 | |
| 1491 | @section highpass |
| 1492 | |
| 1493 | Apply a high-pass filter with 3dB point frequency. |
| 1494 | The filter can be either single-pole, or double-pole (the default). |
| 1495 | The filter roll off at 6dB per pole per octave (20dB per pole per decade). |
| 1496 | |
| 1497 | The filter accepts the following options: |
| 1498 | |
| 1499 | @table @option |
| 1500 | @item frequency, f |
| 1501 | Set frequency in Hz. Default is 3000. |
| 1502 | |
| 1503 | @item poles, p |
| 1504 | Set number of poles. Default is 2. |
| 1505 | |
| 1506 | @item width_type |
| 1507 | Set method to specify band-width of filter. |
| 1508 | @table @option |
| 1509 | @item h |
| 1510 | Hz |
| 1511 | @item q |
| 1512 | Q-Factor |
| 1513 | @item o |
| 1514 | octave |
| 1515 | @item s |
| 1516 | slope |
| 1517 | @end table |
| 1518 | |
| 1519 | @item width, w |
| 1520 | Specify the band-width of a filter in width_type units. |
| 1521 | Applies only to double-pole filter. |
| 1522 | The default is 0.707q and gives a Butterworth response. |
| 1523 | @end table |
| 1524 | |
| 1525 | @section join |
| 1526 | |
| 1527 | Join multiple input streams into one multi-channel stream. |
| 1528 | |
| 1529 | It accepts the following parameters: |
| 1530 | @table @option |
| 1531 | |
| 1532 | @item inputs |
| 1533 | The number of input streams. It defaults to 2. |
| 1534 | |
| 1535 | @item channel_layout |
| 1536 | The desired output channel layout. It defaults to stereo. |
| 1537 | |
| 1538 | @item map |
| 1539 | Map channels from inputs to output. The argument is a '|'-separated list of |
| 1540 | mappings, each in the @code{@var{input_idx}.@var{in_channel}-@var{out_channel}} |
| 1541 | form. @var{input_idx} is the 0-based index of the input stream. @var{in_channel} |
| 1542 | can be either the name of the input channel (e.g. FL for front left) or its |
| 1543 | index in the specified input stream. @var{out_channel} is the name of the output |
| 1544 | channel. |
| 1545 | @end table |
| 1546 | |
| 1547 | The filter will attempt to guess the mappings when they are not specified |
| 1548 | explicitly. It does so by first trying to find an unused matching input channel |
| 1549 | and if that fails it picks the first unused input channel. |
| 1550 | |
| 1551 | Join 3 inputs (with properly set channel layouts): |
| 1552 | @example |
| 1553 | ffmpeg -i INPUT1 -i INPUT2 -i INPUT3 -filter_complex join=inputs=3 OUTPUT |
| 1554 | @end example |
| 1555 | |
| 1556 | Build a 5.1 output from 6 single-channel streams: |
| 1557 | @example |
| 1558 | ffmpeg -i fl -i fr -i fc -i sl -i sr -i lfe -filter_complex |
| 1559 | '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' |
| 1560 | out |
| 1561 | @end example |
| 1562 | |
| 1563 | @section ladspa |
| 1564 | |
| 1565 | Load a LADSPA (Linux Audio Developer's Simple Plugin API) plugin. |
| 1566 | |
| 1567 | To enable compilation of this filter you need to configure FFmpeg with |
| 1568 | @code{--enable-ladspa}. |
| 1569 | |
| 1570 | @table @option |
| 1571 | @item file, f |
| 1572 | Specifies the name of LADSPA plugin library to load. If the environment |
| 1573 | variable @env{LADSPA_PATH} is defined, the LADSPA plugin is searched in |
| 1574 | each one of the directories specified by the colon separated list in |
| 1575 | @env{LADSPA_PATH}, otherwise in the standard LADSPA paths, which are in |
| 1576 | this order: @file{HOME/.ladspa/lib/}, @file{/usr/local/lib/ladspa/}, |
| 1577 | @file{/usr/lib/ladspa/}. |
| 1578 | |
| 1579 | @item plugin, p |
| 1580 | Specifies the plugin within the library. Some libraries contain only |
| 1581 | one plugin, but others contain many of them. If this is not set filter |
| 1582 | will list all available plugins within the specified library. |
| 1583 | |
| 1584 | @item controls, c |
| 1585 | Set the '|' separated list of controls which are zero or more floating point |
| 1586 | values that determine the behavior of the loaded plugin (for example delay, |
| 1587 | threshold or gain). |
| 1588 | Controls need to be defined using the following syntax: |
| 1589 | c0=@var{value0}|c1=@var{value1}|c2=@var{value2}|..., where |
| 1590 | @var{valuei} is the value set on the @var{i}-th control. |
| 1591 | If @option{controls} is set to @code{help}, all available controls and |
| 1592 | their valid ranges are printed. |
| 1593 | |
| 1594 | @item sample_rate, s |
| 1595 | Specify the sample rate, default to 44100. Only used if plugin have |
| 1596 | zero inputs. |
| 1597 | |
| 1598 | @item nb_samples, n |
| 1599 | Set the number of samples per channel per each output frame, default |
| 1600 | is 1024. Only used if plugin have zero inputs. |
| 1601 | |
| 1602 | @item duration, d |
| 1603 | Set the minimum duration of the sourced audio. See |
| 1604 | @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils} |
| 1605 | for the accepted syntax. |
| 1606 | Note that the resulting duration may be greater than the specified duration, |
| 1607 | as the generated audio is always cut at the end of a complete frame. |
| 1608 | If not specified, or the expressed duration is negative, the audio is |
| 1609 | supposed to be generated forever. |
| 1610 | Only used if plugin have zero inputs. |
| 1611 | |
| 1612 | @end table |
| 1613 | |
| 1614 | @subsection Examples |
| 1615 | |
| 1616 | @itemize |
| 1617 | @item |
| 1618 | List all available plugins within amp (LADSPA example plugin) library: |
| 1619 | @example |
| 1620 | ladspa=file=amp |
| 1621 | @end example |
| 1622 | |
| 1623 | @item |
| 1624 | List all available controls and their valid ranges for @code{vcf_notch} |
| 1625 | plugin from @code{VCF} library: |
| 1626 | @example |
| 1627 | ladspa=f=vcf:p=vcf_notch:c=help |
| 1628 | @end example |
| 1629 | |
| 1630 | @item |
| 1631 | Simulate low quality audio equipment using @code{Computer Music Toolkit} (CMT) |
| 1632 | plugin library: |
| 1633 | @example |
| 1634 | ladspa=file=cmt:plugin=lofi:controls=c0=22|c1=12|c2=12 |
| 1635 | @end example |
| 1636 | |
| 1637 | @item |
| 1638 | Add reverberation to the audio using TAP-plugins |
| 1639 | (Tom's Audio Processing plugins): |
| 1640 | @example |
| 1641 | ladspa=file=tap_reverb:tap_reverb |
| 1642 | @end example |
| 1643 | |
| 1644 | @item |
| 1645 | Generate white noise, with 0.2 amplitude: |
| 1646 | @example |
| 1647 | ladspa=file=cmt:noise_source_white:c=c0=.2 |
| 1648 | @end example |
| 1649 | |
| 1650 | @item |
| 1651 | Generate 20 bpm clicks using plugin @code{C* Click - Metronome} from the |
| 1652 | @code{C* Audio Plugin Suite} (CAPS) library: |
| 1653 | @example |
| 1654 | ladspa=file=caps:Click:c=c1=20' |
| 1655 | @end example |
| 1656 | |
| 1657 | @item |
| 1658 | Apply @code{C* Eq10X2 - Stereo 10-band equaliser} effect: |
| 1659 | @example |
| 1660 | ladspa=caps:Eq10X2:c=c0=-48|c9=-24|c3=12|c4=2 |
| 1661 | @end example |
| 1662 | @end itemize |
| 1663 | |
| 1664 | @subsection Commands |
| 1665 | |
| 1666 | This filter supports the following commands: |
| 1667 | @table @option |
| 1668 | @item cN |
| 1669 | Modify the @var{N}-th control value. |
| 1670 | |
| 1671 | If the specified value is not valid, it is ignored and prior one is kept. |
| 1672 | @end table |
| 1673 | |
| 1674 | @section lowpass |
| 1675 | |
| 1676 | Apply a low-pass filter with 3dB point frequency. |
| 1677 | The filter can be either single-pole or double-pole (the default). |
| 1678 | The filter roll off at 6dB per pole per octave (20dB per pole per decade). |
| 1679 | |
| 1680 | The filter accepts the following options: |
| 1681 | |
| 1682 | @table @option |
| 1683 | @item frequency, f |
| 1684 | Set frequency in Hz. Default is 500. |
| 1685 | |
| 1686 | @item poles, p |
| 1687 | Set number of poles. Default is 2. |
| 1688 | |
| 1689 | @item width_type |
| 1690 | Set method to specify band-width of filter. |
| 1691 | @table @option |
| 1692 | @item h |
| 1693 | Hz |
| 1694 | @item q |
| 1695 | Q-Factor |
| 1696 | @item o |
| 1697 | octave |
| 1698 | @item s |
| 1699 | slope |
| 1700 | @end table |
| 1701 | |
| 1702 | @item width, w |
| 1703 | Specify the band-width of a filter in width_type units. |
| 1704 | Applies only to double-pole filter. |
| 1705 | The default is 0.707q and gives a Butterworth response. |
| 1706 | @end table |
| 1707 | |
| 1708 | @section pan |
| 1709 | |
| 1710 | Mix channels with specific gain levels. The filter accepts the output |
| 1711 | channel layout followed by a set of channels definitions. |
| 1712 | |
| 1713 | This filter is also designed to efficiently remap the channels of an audio |
| 1714 | stream. |
| 1715 | |
| 1716 | The filter accepts parameters of the form: |
| 1717 | "@var{l}|@var{outdef}|@var{outdef}|..." |
| 1718 | |
| 1719 | @table @option |
| 1720 | @item l |
| 1721 | output channel layout or number of channels |
| 1722 | |
| 1723 | @item outdef |
| 1724 | output channel specification, of the form: |
| 1725 | "@var{out_name}=[@var{gain}*]@var{in_name}[+[@var{gain}*]@var{in_name}...]" |
| 1726 | |
| 1727 | @item out_name |
| 1728 | output channel to define, either a channel name (FL, FR, etc.) or a channel |
| 1729 | number (c0, c1, etc.) |
| 1730 | |
| 1731 | @item gain |
| 1732 | multiplicative coefficient for the channel, 1 leaving the volume unchanged |
| 1733 | |
| 1734 | @item in_name |
| 1735 | input channel to use, see out_name for details; it is not possible to mix |
| 1736 | named and numbered input channels |
| 1737 | @end table |
| 1738 | |
| 1739 | If the `=' in a channel specification is replaced by `<', then the gains for |
| 1740 | that specification will be renormalized so that the total is 1, thus |
| 1741 | avoiding clipping noise. |
| 1742 | |
| 1743 | @subsection Mixing examples |
| 1744 | |
| 1745 | For example, if you want to down-mix from stereo to mono, but with a bigger |
| 1746 | factor for the left channel: |
| 1747 | @example |
| 1748 | pan=1c|c0=0.9*c0+0.1*c1 |
| 1749 | @end example |
| 1750 | |
| 1751 | A customized down-mix to stereo that works automatically for 3-, 4-, 5- and |
| 1752 | 7-channels surround: |
| 1753 | @example |
| 1754 | pan=stereo| FL < FL + 0.5*FC + 0.6*BL + 0.6*SL | FR < FR + 0.5*FC + 0.6*BR + 0.6*SR |
| 1755 | @end example |
| 1756 | |
| 1757 | Note that @command{ffmpeg} integrates a default down-mix (and up-mix) system |
| 1758 | that should be preferred (see "-ac" option) unless you have very specific |
| 1759 | needs. |
| 1760 | |
| 1761 | @subsection Remapping examples |
| 1762 | |
| 1763 | The channel remapping will be effective if, and only if: |
| 1764 | |
| 1765 | @itemize |
| 1766 | @item gain coefficients are zeroes or ones, |
| 1767 | @item only one input per channel output, |
| 1768 | @end itemize |
| 1769 | |
| 1770 | If all these conditions are satisfied, the filter will notify the user ("Pure |
| 1771 | channel mapping detected"), and use an optimized and lossless method to do the |
| 1772 | remapping. |
| 1773 | |
| 1774 | For example, if you have a 5.1 source and want a stereo audio stream by |
| 1775 | dropping the extra channels: |
| 1776 | @example |
| 1777 | pan="stereo| c0=FL | c1=FR" |
| 1778 | @end example |
| 1779 | |
| 1780 | Given the same source, you can also switch front left and front right channels |
| 1781 | and keep the input channel layout: |
| 1782 | @example |
| 1783 | pan="5.1| c0=c1 | c1=c0 | c2=c2 | c3=c3 | c4=c4 | c5=c5" |
| 1784 | @end example |
| 1785 | |
| 1786 | If the input is a stereo audio stream, you can mute the front left channel (and |
| 1787 | still keep the stereo channel layout) with: |
| 1788 | @example |
| 1789 | pan="stereo|c1=c1" |
| 1790 | @end example |
| 1791 | |
| 1792 | Still with a stereo audio stream input, you can copy the right channel in both |
| 1793 | front left and right: |
| 1794 | @example |
| 1795 | pan="stereo| c0=FR | c1=FR" |
| 1796 | @end example |
| 1797 | |
| 1798 | @section replaygain |
| 1799 | |
| 1800 | ReplayGain scanner filter. This filter takes an audio stream as an input and |
| 1801 | outputs it unchanged. |
| 1802 | At end of filtering it displays @code{track_gain} and @code{track_peak}. |
| 1803 | |
| 1804 | @section resample |
| 1805 | |
| 1806 | Convert the audio sample format, sample rate and channel layout. It is |
| 1807 | not meant to be used directly. |
| 1808 | |
| 1809 | @section silencedetect |
| 1810 | |
| 1811 | Detect silence in an audio stream. |
| 1812 | |
| 1813 | This filter logs a message when it detects that the input audio volume is less |
| 1814 | or equal to a noise tolerance value for a duration greater or equal to the |
| 1815 | minimum detected noise duration. |
| 1816 | |
| 1817 | The printed times and duration are expressed in seconds. |
| 1818 | |
| 1819 | The filter accepts the following options: |
| 1820 | |
| 1821 | @table @option |
| 1822 | @item duration, d |
| 1823 | Set silence duration until notification (default is 2 seconds). |
| 1824 | |
| 1825 | @item noise, n |
| 1826 | Set noise tolerance. Can be specified in dB (in case "dB" is appended to the |
| 1827 | specified value) or amplitude ratio. Default is -60dB, or 0.001. |
| 1828 | @end table |
| 1829 | |
| 1830 | @subsection Examples |
| 1831 | |
| 1832 | @itemize |
| 1833 | @item |
| 1834 | Detect 5 seconds of silence with -50dB noise tolerance: |
| 1835 | @example |
| 1836 | silencedetect=n=-50dB:d=5 |
| 1837 | @end example |
| 1838 | |
| 1839 | @item |
| 1840 | Complete example with @command{ffmpeg} to detect silence with 0.0001 noise |
| 1841 | tolerance in @file{silence.mp3}: |
| 1842 | @example |
| 1843 | ffmpeg -i silence.mp3 -af silencedetect=noise=0.0001 -f null - |
| 1844 | @end example |
| 1845 | @end itemize |
| 1846 | |
| 1847 | @section silenceremove |
| 1848 | |
| 1849 | Remove silence from the beginning, middle or end of the audio. |
| 1850 | |
| 1851 | The filter accepts the following options: |
| 1852 | |
| 1853 | @table @option |
| 1854 | @item start_periods |
| 1855 | This value is used to indicate if audio should be trimmed at beginning of |
| 1856 | the audio. A value of zero indicates no silence should be trimmed from the |
| 1857 | beginning. When specifying a non-zero value, it trims audio up until it |
| 1858 | finds non-silence. Normally, when trimming silence from beginning of audio |
| 1859 | the @var{start_periods} will be @code{1} but it can be increased to higher |
| 1860 | values to trim all audio up to specific count of non-silence periods. |
| 1861 | Default value is @code{0}. |
| 1862 | |
| 1863 | @item start_duration |
| 1864 | Specify the amount of time that non-silence must be detected before it stops |
| 1865 | trimming audio. By increasing the duration, bursts of noises can be treated |
| 1866 | as silence and trimmed off. Default value is @code{0}. |
| 1867 | |
| 1868 | @item start_threshold |
| 1869 | This indicates what sample value should be treated as silence. For digital |
| 1870 | audio, a value of @code{0} may be fine but for audio recorded from analog, |
| 1871 | you may wish to increase the value to account for background noise. |
| 1872 | Can be specified in dB (in case "dB" is appended to the specified value) |
| 1873 | or amplitude ratio. Default value is @code{0}. |
| 1874 | |
| 1875 | @item stop_periods |
| 1876 | Set the count for trimming silence from the end of audio. |
| 1877 | To remove silence from the middle of a file, specify a @var{stop_periods} |
| 1878 | that is negative. This value is then threated as a positive value and is |
| 1879 | used to indicate the effect should restart processing as specified by |
| 1880 | @var{start_periods}, making it suitable for removing periods of silence |
| 1881 | in the middle of the audio. |
| 1882 | Default value is @code{0}. |
| 1883 | |
| 1884 | @item stop_duration |
| 1885 | Specify a duration of silence that must exist before audio is not copied any |
| 1886 | more. By specifying a higher duration, silence that is wanted can be left in |
| 1887 | the audio. |
| 1888 | Default value is @code{0}. |
| 1889 | |
| 1890 | @item stop_threshold |
| 1891 | This is the same as @option{start_threshold} but for trimming silence from |
| 1892 | the end of audio. |
| 1893 | Can be specified in dB (in case "dB" is appended to the specified value) |
| 1894 | or amplitude ratio. Default value is @code{0}. |
| 1895 | |
| 1896 | @item leave_silence |
| 1897 | This indicate that @var{stop_duration} length of audio should be left intact |
| 1898 | at the beginning of each period of silence. |
| 1899 | For example, if you want to remove long pauses between words but do not want |
| 1900 | to remove the pauses completely. Default value is @code{0}. |
| 1901 | |
| 1902 | @end table |
| 1903 | |
| 1904 | @subsection Examples |
| 1905 | |
| 1906 | @itemize |
| 1907 | @item |
| 1908 | The following example shows how this filter can be used to start a recording |
| 1909 | that does not contain the delay at the start which usually occurs between |
| 1910 | pressing the record button and the start of the performance: |
| 1911 | @example |
| 1912 | silenceremove=1:5:0.02 |
| 1913 | @end example |
| 1914 | @end itemize |
| 1915 | |
| 1916 | @section treble |
| 1917 | |
| 1918 | Boost or cut treble (upper) frequencies of the audio using a two-pole |
| 1919 | shelving filter with a response similar to that of a standard |
| 1920 | hi-fi's tone-controls. This is also known as shelving equalisation (EQ). |
| 1921 | |
| 1922 | The filter accepts the following options: |
| 1923 | |
| 1924 | @table @option |
| 1925 | @item gain, g |
| 1926 | Give the gain at whichever is the lower of ~22 kHz and the |
| 1927 | Nyquist frequency. Its useful range is about -20 (for a large cut) |
| 1928 | to +20 (for a large boost). Beware of clipping when using a positive gain. |
| 1929 | |
| 1930 | @item frequency, f |
| 1931 | Set the filter's central frequency and so can be used |
| 1932 | to extend or reduce the frequency range to be boosted or cut. |
| 1933 | The default value is @code{3000} Hz. |
| 1934 | |
| 1935 | @item width_type |
| 1936 | Set method to specify band-width of filter. |
| 1937 | @table @option |
| 1938 | @item h |
| 1939 | Hz |
| 1940 | @item q |
| 1941 | Q-Factor |
| 1942 | @item o |
| 1943 | octave |
| 1944 | @item s |
| 1945 | slope |
| 1946 | @end table |
| 1947 | |
| 1948 | @item width, w |
| 1949 | Determine how steep is the filter's shelf transition. |
| 1950 | @end table |
| 1951 | |
| 1952 | @section volume |
| 1953 | |
| 1954 | Adjust the input audio volume. |
| 1955 | |
| 1956 | It accepts the following parameters: |
| 1957 | @table @option |
| 1958 | |
| 1959 | @item volume |
| 1960 | Set audio volume expression. |
| 1961 | |
| 1962 | Output values are clipped to the maximum value. |
| 1963 | |
| 1964 | The output audio volume is given by the relation: |
| 1965 | @example |
| 1966 | @var{output_volume} = @var{volume} * @var{input_volume} |
| 1967 | @end example |
| 1968 | |
| 1969 | The default value for @var{volume} is "1.0". |
| 1970 | |
| 1971 | @item precision |
| 1972 | This parameter represents the mathematical precision. |
| 1973 | |
| 1974 | It determines which input sample formats will be allowed, which affects the |
| 1975 | precision of the volume scaling. |
| 1976 | |
| 1977 | @table @option |
| 1978 | @item fixed |
| 1979 | 8-bit fixed-point; this limits input sample format to U8, S16, and S32. |
| 1980 | @item float |
| 1981 | 32-bit floating-point; this limits input sample format to FLT. (default) |
| 1982 | @item double |
| 1983 | 64-bit floating-point; this limits input sample format to DBL. |
| 1984 | @end table |
| 1985 | |
| 1986 | @item replaygain |
| 1987 | Choose the behaviour on encountering ReplayGain side data in input frames. |
| 1988 | |
| 1989 | @table @option |
| 1990 | @item drop |
| 1991 | Remove ReplayGain side data, ignoring its contents (the default). |
| 1992 | |
| 1993 | @item ignore |
| 1994 | Ignore ReplayGain side data, but leave it in the frame. |
| 1995 | |
| 1996 | @item track |
| 1997 | Prefer the track gain, if present. |
| 1998 | |
| 1999 | @item album |
| 2000 | Prefer the album gain, if present. |
| 2001 | @end table |
| 2002 | |
| 2003 | @item replaygain_preamp |
| 2004 | Pre-amplification gain in dB to apply to the selected replaygain gain. |
| 2005 | |
| 2006 | Default value for @var{replaygain_preamp} is 0.0. |
| 2007 | |
| 2008 | @item eval |
| 2009 | Set when the volume expression is evaluated. |
| 2010 | |
| 2011 | It accepts the following values: |
| 2012 | @table @samp |
| 2013 | @item once |
| 2014 | only evaluate expression once during the filter initialization, or |
| 2015 | when the @samp{volume} command is sent |
| 2016 | |
| 2017 | @item frame |
| 2018 | evaluate expression for each incoming frame |
| 2019 | @end table |
| 2020 | |
| 2021 | Default value is @samp{once}. |
| 2022 | @end table |
| 2023 | |
| 2024 | The volume expression can contain the following parameters. |
| 2025 | |
| 2026 | @table @option |
| 2027 | @item n |
| 2028 | frame number (starting at zero) |
| 2029 | @item nb_channels |
| 2030 | number of channels |
| 2031 | @item nb_consumed_samples |
| 2032 | number of samples consumed by the filter |
| 2033 | @item nb_samples |
| 2034 | number of samples in the current frame |
| 2035 | @item pos |
| 2036 | original frame position in the file |
| 2037 | @item pts |
| 2038 | frame PTS |
| 2039 | @item sample_rate |
| 2040 | sample rate |
| 2041 | @item startpts |
| 2042 | PTS at start of stream |
| 2043 | @item startt |
| 2044 | time at start of stream |
| 2045 | @item t |
| 2046 | frame time |
| 2047 | @item tb |
| 2048 | timestamp timebase |
| 2049 | @item volume |
| 2050 | last set volume value |
| 2051 | @end table |
| 2052 | |
| 2053 | Note that when @option{eval} is set to @samp{once} only the |
| 2054 | @var{sample_rate} and @var{tb} variables are available, all other |
| 2055 | variables will evaluate to NAN. |
| 2056 | |
| 2057 | @subsection Commands |
| 2058 | |
| 2059 | This filter supports the following commands: |
| 2060 | @table @option |
| 2061 | @item volume |
| 2062 | Modify the volume expression. |
| 2063 | The command accepts the same syntax of the corresponding option. |
| 2064 | |
| 2065 | If the specified expression is not valid, it is kept at its current |
| 2066 | value. |
| 2067 | @item replaygain_noclip |
| 2068 | Prevent clipping by limiting the gain applied. |
| 2069 | |
| 2070 | Default value for @var{replaygain_noclip} is 1. |
| 2071 | |
| 2072 | @end table |
| 2073 | |
| 2074 | @subsection Examples |
| 2075 | |
| 2076 | @itemize |
| 2077 | @item |
| 2078 | Halve the input audio volume: |
| 2079 | @example |
| 2080 | volume=volume=0.5 |
| 2081 | volume=volume=1/2 |
| 2082 | volume=volume=-6.0206dB |
| 2083 | @end example |
| 2084 | |
| 2085 | In all the above example the named key for @option{volume} can be |
| 2086 | omitted, for example like in: |
| 2087 | @example |
| 2088 | volume=0.5 |
| 2089 | @end example |
| 2090 | |
| 2091 | @item |
| 2092 | Increase input audio power by 6 decibels using fixed-point precision: |
| 2093 | @example |
| 2094 | volume=volume=6dB:precision=fixed |
| 2095 | @end example |
| 2096 | |
| 2097 | @item |
| 2098 | Fade volume after time 10 with an annihilation period of 5 seconds: |
| 2099 | @example |
| 2100 | volume='if(lt(t,10),1,max(1-(t-10)/5,0))':eval=frame |
| 2101 | @end example |
| 2102 | @end itemize |
| 2103 | |
| 2104 | @section volumedetect |
| 2105 | |
| 2106 | Detect the volume of the input video. |
| 2107 | |
| 2108 | The filter has no parameters. The input is not modified. Statistics about |
| 2109 | the volume will be printed in the log when the input stream end is reached. |
| 2110 | |
| 2111 | In particular it will show the mean volume (root mean square), maximum |
| 2112 | volume (on a per-sample basis), and the beginning of a histogram of the |
| 2113 | registered volume values (from the maximum value to a cumulated 1/1000 of |
| 2114 | the samples). |
| 2115 | |
| 2116 | All volumes are in decibels relative to the maximum PCM value. |
| 2117 | |
| 2118 | @subsection Examples |
| 2119 | |
| 2120 | Here is an excerpt of the output: |
| 2121 | @example |
| 2122 | [Parsed_volumedetect_0 @ 0xa23120] mean_volume: -27 dB |
| 2123 | [Parsed_volumedetect_0 @ 0xa23120] max_volume: -4 dB |
| 2124 | [Parsed_volumedetect_0 @ 0xa23120] histogram_4db: 6 |
| 2125 | [Parsed_volumedetect_0 @ 0xa23120] histogram_5db: 62 |
| 2126 | [Parsed_volumedetect_0 @ 0xa23120] histogram_6db: 286 |
| 2127 | [Parsed_volumedetect_0 @ 0xa23120] histogram_7db: 1042 |
| 2128 | [Parsed_volumedetect_0 @ 0xa23120] histogram_8db: 2551 |
| 2129 | [Parsed_volumedetect_0 @ 0xa23120] histogram_9db: 4609 |
| 2130 | [Parsed_volumedetect_0 @ 0xa23120] histogram_10db: 8409 |
| 2131 | @end example |
| 2132 | |
| 2133 | It means that: |
| 2134 | @itemize |
| 2135 | @item |
| 2136 | The mean square energy is approximately -27 dB, or 10^-2.7. |
| 2137 | @item |
| 2138 | The largest sample is at -4 dB, or more precisely between -4 dB and -5 dB. |
| 2139 | @item |
| 2140 | There are 6 samples at -4 dB, 62 at -5 dB, 286 at -6 dB, etc. |
| 2141 | @end itemize |
| 2142 | |
| 2143 | In other words, raising the volume by +4 dB does not cause any clipping, |
| 2144 | raising it by +5 dB causes clipping for 6 samples, etc. |
| 2145 | |
| 2146 | @c man end AUDIO FILTERS |
| 2147 | |
| 2148 | @chapter Audio Sources |
| 2149 | @c man begin AUDIO SOURCES |
| 2150 | |
| 2151 | Below is a description of the currently available audio sources. |
| 2152 | |
| 2153 | @section abuffer |
| 2154 | |
| 2155 | Buffer audio frames, and make them available to the filter chain. |
| 2156 | |
| 2157 | This source is mainly intended for a programmatic use, in particular |
| 2158 | through the interface defined in @file{libavfilter/asrc_abuffer.h}. |
| 2159 | |
| 2160 | It accepts the following parameters: |
| 2161 | @table @option |
| 2162 | |
| 2163 | @item time_base |
| 2164 | The timebase which will be used for timestamps of submitted frames. It must be |
| 2165 | either a floating-point number or in @var{numerator}/@var{denominator} form. |
| 2166 | |
| 2167 | @item sample_rate |
| 2168 | The sample rate of the incoming audio buffers. |
| 2169 | |
| 2170 | @item sample_fmt |
| 2171 | The sample format of the incoming audio buffers. |
| 2172 | Either a sample format name or its corresponging integer representation from |
| 2173 | the enum AVSampleFormat in @file{libavutil/samplefmt.h} |
| 2174 | |
| 2175 | @item channel_layout |
| 2176 | The channel layout of the incoming audio buffers. |
| 2177 | Either a channel layout name from channel_layout_map in |
| 2178 | @file{libavutil/channel_layout.c} or its corresponding integer representation |
| 2179 | from the AV_CH_LAYOUT_* macros in @file{libavutil/channel_layout.h} |
| 2180 | |
| 2181 | @item channels |
| 2182 | The number of channels of the incoming audio buffers. |
| 2183 | If both @var{channels} and @var{channel_layout} are specified, then they |
| 2184 | must be consistent. |
| 2185 | |
| 2186 | @end table |
| 2187 | |
| 2188 | @subsection Examples |
| 2189 | |
| 2190 | @example |
| 2191 | abuffer=sample_rate=44100:sample_fmt=s16p:channel_layout=stereo |
| 2192 | @end example |
| 2193 | |
| 2194 | will instruct the source to accept planar 16bit signed stereo at 44100Hz. |
| 2195 | Since the sample format with name "s16p" corresponds to the number |
| 2196 | 6 and the "stereo" channel layout corresponds to the value 0x3, this is |
| 2197 | equivalent to: |
| 2198 | @example |
| 2199 | abuffer=sample_rate=44100:sample_fmt=6:channel_layout=0x3 |
| 2200 | @end example |
| 2201 | |
| 2202 | @section aevalsrc |
| 2203 | |
| 2204 | Generate an audio signal specified by an expression. |
| 2205 | |
| 2206 | This source accepts in input one or more expressions (one for each |
| 2207 | channel), which are evaluated and used to generate a corresponding |
| 2208 | audio signal. |
| 2209 | |
| 2210 | This source accepts the following options: |
| 2211 | |
| 2212 | @table @option |
| 2213 | @item exprs |
| 2214 | Set the '|'-separated expressions list for each separate channel. In case the |
| 2215 | @option{channel_layout} option is not specified, the selected channel layout |
| 2216 | depends on the number of provided expressions. Otherwise the last |
| 2217 | specified expression is applied to the remaining output channels. |
| 2218 | |
| 2219 | @item channel_layout, c |
| 2220 | Set the channel layout. The number of channels in the specified layout |
| 2221 | must be equal to the number of specified expressions. |
| 2222 | |
| 2223 | @item duration, d |
| 2224 | Set the minimum duration of the sourced audio. See |
| 2225 | @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils} |
| 2226 | for the accepted syntax. |
| 2227 | Note that the resulting duration may be greater than the specified |
| 2228 | duration, as the generated audio is always cut at the end of a |
| 2229 | complete frame. |
| 2230 | |
| 2231 | If not specified, or the expressed duration is negative, the audio is |
| 2232 | supposed to be generated forever. |
| 2233 | |
| 2234 | @item nb_samples, n |
| 2235 | Set the number of samples per channel per each output frame, |
| 2236 | default to 1024. |
| 2237 | |
| 2238 | @item sample_rate, s |
| 2239 | Specify the sample rate, default to 44100. |
| 2240 | @end table |
| 2241 | |
| 2242 | Each expression in @var{exprs} can contain the following constants: |
| 2243 | |
| 2244 | @table @option |
| 2245 | @item n |
| 2246 | number of the evaluated sample, starting from 0 |
| 2247 | |
| 2248 | @item t |
| 2249 | time of the evaluated sample expressed in seconds, starting from 0 |
| 2250 | |
| 2251 | @item s |
| 2252 | sample rate |
| 2253 | |
| 2254 | @end table |
| 2255 | |
| 2256 | @subsection Examples |
| 2257 | |
| 2258 | @itemize |
| 2259 | @item |
| 2260 | Generate silence: |
| 2261 | @example |
| 2262 | aevalsrc=0 |
| 2263 | @end example |
| 2264 | |
| 2265 | @item |
| 2266 | Generate a sin signal with frequency of 440 Hz, set sample rate to |
| 2267 | 8000 Hz: |
| 2268 | @example |
| 2269 | aevalsrc="sin(440*2*PI*t):s=8000" |
| 2270 | @end example |
| 2271 | |
| 2272 | @item |
| 2273 | Generate a two channels signal, specify the channel layout (Front |
| 2274 | Center + Back Center) explicitly: |
| 2275 | @example |
| 2276 | aevalsrc="sin(420*2*PI*t)|cos(430*2*PI*t):c=FC|BC" |
| 2277 | @end example |
| 2278 | |
| 2279 | @item |
| 2280 | Generate white noise: |
| 2281 | @example |
| 2282 | aevalsrc="-2+random(0)" |
| 2283 | @end example |
| 2284 | |
| 2285 | @item |
| 2286 | Generate an amplitude modulated signal: |
| 2287 | @example |
| 2288 | aevalsrc="sin(10*2*PI*t)*sin(880*2*PI*t)" |
| 2289 | @end example |
| 2290 | |
| 2291 | @item |
| 2292 | Generate 2.5 Hz binaural beats on a 360 Hz carrier: |
| 2293 | @example |
| 2294 | aevalsrc="0.1*sin(2*PI*(360-2.5/2)*t) | 0.1*sin(2*PI*(360+2.5/2)*t)" |
| 2295 | @end example |
| 2296 | |
| 2297 | @end itemize |
| 2298 | |
| 2299 | @section anullsrc |
| 2300 | |
| 2301 | The null audio source, return unprocessed audio frames. It is mainly useful |
| 2302 | as a template and to be employed in analysis / debugging tools, or as |
| 2303 | the source for filters which ignore the input data (for example the sox |
| 2304 | synth filter). |
| 2305 | |
| 2306 | This source accepts the following options: |
| 2307 | |
| 2308 | @table @option |
| 2309 | |
| 2310 | @item channel_layout, cl |
| 2311 | |
| 2312 | Specifies the channel layout, and can be either an integer or a string |
| 2313 | representing a channel layout. The default value of @var{channel_layout} |
| 2314 | is "stereo". |
| 2315 | |
| 2316 | Check the channel_layout_map definition in |
| 2317 | @file{libavutil/channel_layout.c} for the mapping between strings and |
| 2318 | channel layout values. |
| 2319 | |
| 2320 | @item sample_rate, r |
| 2321 | Specifies the sample rate, and defaults to 44100. |
| 2322 | |
| 2323 | @item nb_samples, n |
| 2324 | Set the number of samples per requested frames. |
| 2325 | |
| 2326 | @end table |
| 2327 | |
| 2328 | @subsection Examples |
| 2329 | |
| 2330 | @itemize |
| 2331 | @item |
| 2332 | Set the sample rate to 48000 Hz and the channel layout to AV_CH_LAYOUT_MONO. |
| 2333 | @example |
| 2334 | anullsrc=r=48000:cl=4 |
| 2335 | @end example |
| 2336 | |
| 2337 | @item |
| 2338 | Do the same operation with a more obvious syntax: |
| 2339 | @example |
| 2340 | anullsrc=r=48000:cl=mono |
| 2341 | @end example |
| 2342 | @end itemize |
| 2343 | |
| 2344 | All the parameters need to be explicitly defined. |
| 2345 | |
| 2346 | @section flite |
| 2347 | |
| 2348 | Synthesize a voice utterance using the libflite library. |
| 2349 | |
| 2350 | To enable compilation of this filter you need to configure FFmpeg with |
| 2351 | @code{--enable-libflite}. |
| 2352 | |
| 2353 | Note that the flite library is not thread-safe. |
| 2354 | |
| 2355 | The filter accepts the following options: |
| 2356 | |
| 2357 | @table @option |
| 2358 | |
| 2359 | @item list_voices |
| 2360 | If set to 1, list the names of the available voices and exit |
| 2361 | immediately. Default value is 0. |
| 2362 | |
| 2363 | @item nb_samples, n |
| 2364 | Set the maximum number of samples per frame. Default value is 512. |
| 2365 | |
| 2366 | @item textfile |
| 2367 | Set the filename containing the text to speak. |
| 2368 | |
| 2369 | @item text |
| 2370 | Set the text to speak. |
| 2371 | |
| 2372 | @item voice, v |
| 2373 | Set the voice to use for the speech synthesis. Default value is |
| 2374 | @code{kal}. See also the @var{list_voices} option. |
| 2375 | @end table |
| 2376 | |
| 2377 | @subsection Examples |
| 2378 | |
| 2379 | @itemize |
| 2380 | @item |
| 2381 | Read from file @file{speech.txt}, and synthetize the text using the |
| 2382 | standard flite voice: |
| 2383 | @example |
| 2384 | flite=textfile=speech.txt |
| 2385 | @end example |
| 2386 | |
| 2387 | @item |
| 2388 | Read the specified text selecting the @code{slt} voice: |
| 2389 | @example |
| 2390 | flite=text='So fare thee well, poor devil of a Sub-Sub, whose commentator I am':voice=slt |
| 2391 | @end example |
| 2392 | |
| 2393 | @item |
| 2394 | Input text to ffmpeg: |
| 2395 | @example |
| 2396 | ffmpeg -f lavfi -i flite=text='So fare thee well, poor devil of a Sub-Sub, whose commentator I am':voice=slt |
| 2397 | @end example |
| 2398 | |
| 2399 | @item |
| 2400 | Make @file{ffplay} speak the specified text, using @code{flite} and |
| 2401 | the @code{lavfi} device: |
| 2402 | @example |
| 2403 | ffplay -f lavfi flite=text='No more be grieved for which that thou hast done.' |
| 2404 | @end example |
| 2405 | @end itemize |
| 2406 | |
| 2407 | For more information about libflite, check: |
| 2408 | @url{http://www.speech.cs.cmu.edu/flite/} |
| 2409 | |
| 2410 | @section sine |
| 2411 | |
| 2412 | Generate an audio signal made of a sine wave with amplitude 1/8. |
| 2413 | |
| 2414 | The audio signal is bit-exact. |
| 2415 | |
| 2416 | The filter accepts the following options: |
| 2417 | |
| 2418 | @table @option |
| 2419 | |
| 2420 | @item frequency, f |
| 2421 | Set the carrier frequency. Default is 440 Hz. |
| 2422 | |
| 2423 | @item beep_factor, b |
| 2424 | Enable a periodic beep every second with frequency @var{beep_factor} times |
| 2425 | the carrier frequency. Default is 0, meaning the beep is disabled. |
| 2426 | |
| 2427 | @item sample_rate, r |
| 2428 | Specify the sample rate, default is 44100. |
| 2429 | |
| 2430 | @item duration, d |
| 2431 | Specify the duration of the generated audio stream. |
| 2432 | |
| 2433 | @item samples_per_frame |
| 2434 | Set the number of samples per output frame, default is 1024. |
| 2435 | @end table |
| 2436 | |
| 2437 | @subsection Examples |
| 2438 | |
| 2439 | @itemize |
| 2440 | |
| 2441 | @item |
| 2442 | Generate a simple 440 Hz sine wave: |
| 2443 | @example |
| 2444 | sine |
| 2445 | @end example |
| 2446 | |
| 2447 | @item |
| 2448 | Generate a 220 Hz sine wave with a 880 Hz beep each second, for 5 seconds: |
| 2449 | @example |
| 2450 | sine=220:4:d=5 |
| 2451 | sine=f=220:b=4:d=5 |
| 2452 | sine=frequency=220:beep_factor=4:duration=5 |
| 2453 | @end example |
| 2454 | |
| 2455 | @end itemize |
| 2456 | |
| 2457 | @c man end AUDIO SOURCES |
| 2458 | |
| 2459 | @chapter Audio Sinks |
| 2460 | @c man begin AUDIO SINKS |
| 2461 | |
| 2462 | Below is a description of the currently available audio sinks. |
| 2463 | |
| 2464 | @section abuffersink |
| 2465 | |
| 2466 | Buffer audio frames, and make them available to the end of filter chain. |
| 2467 | |
| 2468 | This sink is mainly intended for programmatic use, in particular |
| 2469 | through the interface defined in @file{libavfilter/buffersink.h} |
| 2470 | or the options system. |
| 2471 | |
| 2472 | It accepts a pointer to an AVABufferSinkContext structure, which |
| 2473 | defines the incoming buffers' formats, to be passed as the opaque |
| 2474 | parameter to @code{avfilter_init_filter} for initialization. |
| 2475 | @section anullsink |
| 2476 | |
| 2477 | Null audio sink; do absolutely nothing with the input audio. It is |
| 2478 | mainly useful as a template and for use in analysis / debugging |
| 2479 | tools. |
| 2480 | |
| 2481 | @c man end AUDIO SINKS |
| 2482 | |
| 2483 | @chapter Video Filters |
| 2484 | @c man begin VIDEO FILTERS |
| 2485 | |
| 2486 | When you configure your FFmpeg build, you can disable any of the |
| 2487 | existing filters using @code{--disable-filters}. |
| 2488 | The configure output will show the video filters included in your |
| 2489 | build. |
| 2490 | |
| 2491 | Below is a description of the currently available video filters. |
| 2492 | |
| 2493 | @section alphaextract |
| 2494 | |
| 2495 | Extract the alpha component from the input as a grayscale video. This |
| 2496 | is especially useful with the @var{alphamerge} filter. |
| 2497 | |
| 2498 | @section alphamerge |
| 2499 | |
| 2500 | Add or replace the alpha component of the primary input with the |
| 2501 | grayscale value of a second input. This is intended for use with |
| 2502 | @var{alphaextract} to allow the transmission or storage of frame |
| 2503 | sequences that have alpha in a format that doesn't support an alpha |
| 2504 | channel. |
| 2505 | |
| 2506 | For example, to reconstruct full frames from a normal YUV-encoded video |
| 2507 | and a separate video created with @var{alphaextract}, you might use: |
| 2508 | @example |
| 2509 | movie=in_alpha.mkv [alpha]; [in][alpha] alphamerge [out] |
| 2510 | @end example |
| 2511 | |
| 2512 | Since this filter is designed for reconstruction, it operates on frame |
| 2513 | sequences without considering timestamps, and terminates when either |
| 2514 | input reaches end of stream. This will cause problems if your encoding |
| 2515 | pipeline drops frames. If you're trying to apply an image as an |
| 2516 | overlay to a video stream, consider the @var{overlay} filter instead. |
| 2517 | |
| 2518 | @section ass |
| 2519 | |
| 2520 | Same as the @ref{subtitles} filter, except that it doesn't require libavcodec |
| 2521 | and libavformat to work. On the other hand, it is limited to ASS (Advanced |
| 2522 | Substation Alpha) subtitles files. |
| 2523 | |
| 2524 | This filter accepts the following option in addition to the common options from |
| 2525 | the @ref{subtitles} filter: |
| 2526 | |
| 2527 | @table @option |
| 2528 | @item shaping |
| 2529 | Set the shaping engine |
| 2530 | |
| 2531 | Available values are: |
| 2532 | @table @samp |
| 2533 | @item auto |
| 2534 | The default libass shaping engine, which is the best available. |
| 2535 | @item simple |
| 2536 | Fast, font-agnostic shaper that can do only substitutions |
| 2537 | @item complex |
| 2538 | Slower shaper using OpenType for substitutions and positioning |
| 2539 | @end table |
| 2540 | |
| 2541 | The default is @code{auto}. |
| 2542 | @end table |
| 2543 | |
| 2544 | @section bbox |
| 2545 | |
| 2546 | Compute the bounding box for the non-black pixels in the input frame |
| 2547 | luminance plane. |
| 2548 | |
| 2549 | This filter computes the bounding box containing all the pixels with a |
| 2550 | luminance value greater than the minimum allowed value. |
| 2551 | The parameters describing the bounding box are printed on the filter |
| 2552 | log. |
| 2553 | |
| 2554 | The filter accepts the following option: |
| 2555 | |
| 2556 | @table @option |
| 2557 | @item min_val |
| 2558 | Set the minimal luminance value. Default is @code{16}. |
| 2559 | @end table |
| 2560 | |
| 2561 | @section blackdetect |
| 2562 | |
| 2563 | Detect video intervals that are (almost) completely black. Can be |
| 2564 | useful to detect chapter transitions, commercials, or invalid |
| 2565 | recordings. Output lines contains the time for the start, end and |
| 2566 | duration of the detected black interval expressed in seconds. |
| 2567 | |
| 2568 | In order to display the output lines, you need to set the loglevel at |
| 2569 | least to the AV_LOG_INFO value. |
| 2570 | |
| 2571 | The filter accepts the following options: |
| 2572 | |
| 2573 | @table @option |
| 2574 | @item black_min_duration, d |
| 2575 | Set the minimum detected black duration expressed in seconds. It must |
| 2576 | be a non-negative floating point number. |
| 2577 | |
| 2578 | Default value is 2.0. |
| 2579 | |
| 2580 | @item picture_black_ratio_th, pic_th |
| 2581 | Set the threshold for considering a picture "black". |
| 2582 | Express the minimum value for the ratio: |
| 2583 | @example |
| 2584 | @var{nb_black_pixels} / @var{nb_pixels} |
| 2585 | @end example |
| 2586 | |
| 2587 | for which a picture is considered black. |
| 2588 | Default value is 0.98. |
| 2589 | |
| 2590 | @item pixel_black_th, pix_th |
| 2591 | Set the threshold for considering a pixel "black". |
| 2592 | |
| 2593 | The threshold expresses the maximum pixel luminance value for which a |
| 2594 | pixel is considered "black". The provided value is scaled according to |
| 2595 | the following equation: |
| 2596 | @example |
| 2597 | @var{absolute_threshold} = @var{luminance_minimum_value} + @var{pixel_black_th} * @var{luminance_range_size} |
| 2598 | @end example |
| 2599 | |
| 2600 | @var{luminance_range_size} and @var{luminance_minimum_value} depend on |
| 2601 | the input video format, the range is [0-255] for YUV full-range |
| 2602 | formats and [16-235] for YUV non full-range formats. |
| 2603 | |
| 2604 | Default value is 0.10. |
| 2605 | @end table |
| 2606 | |
| 2607 | The following example sets the maximum pixel threshold to the minimum |
| 2608 | value, and detects only black intervals of 2 or more seconds: |
| 2609 | @example |
| 2610 | blackdetect=d=2:pix_th=0.00 |
| 2611 | @end example |
| 2612 | |
| 2613 | @section blackframe |
| 2614 | |
| 2615 | Detect frames that are (almost) completely black. Can be useful to |
| 2616 | detect chapter transitions or commercials. Output lines consist of |
| 2617 | the frame number of the detected frame, the percentage of blackness, |
| 2618 | the position in the file if known or -1 and the timestamp in seconds. |
| 2619 | |
| 2620 | In order to display the output lines, you need to set the loglevel at |
| 2621 | least to the AV_LOG_INFO value. |
| 2622 | |
| 2623 | It accepts the following parameters: |
| 2624 | |
| 2625 | @table @option |
| 2626 | |
| 2627 | @item amount |
| 2628 | The percentage of the pixels that have to be below the threshold; it defaults to |
| 2629 | @code{98}. |
| 2630 | |
| 2631 | @item threshold, thresh |
| 2632 | The threshold below which a pixel value is considered black; it defaults to |
| 2633 | @code{32}. |
| 2634 | |
| 2635 | @end table |
| 2636 | |
| 2637 | @section blend |
| 2638 | |
| 2639 | Blend two video frames into each other. |
| 2640 | |
| 2641 | It takes two input streams and outputs one stream, the first input is the |
| 2642 | "top" layer and second input is "bottom" layer. |
| 2643 | Output terminates when shortest input terminates. |
| 2644 | |
| 2645 | A description of the accepted options follows. |
| 2646 | |
| 2647 | @table @option |
| 2648 | @item c0_mode |
| 2649 | @item c1_mode |
| 2650 | @item c2_mode |
| 2651 | @item c3_mode |
| 2652 | @item all_mode |
| 2653 | Set blend mode for specific pixel component or all pixel components in case |
| 2654 | of @var{all_mode}. Default value is @code{normal}. |
| 2655 | |
| 2656 | Available values for component modes are: |
| 2657 | @table @samp |
| 2658 | @item addition |
| 2659 | @item and |
| 2660 | @item average |
| 2661 | @item burn |
| 2662 | @item darken |
| 2663 | @item difference |
| 2664 | @item divide |
| 2665 | @item dodge |
| 2666 | @item exclusion |
| 2667 | @item hardlight |
| 2668 | @item lighten |
| 2669 | @item multiply |
| 2670 | @item negation |
| 2671 | @item normal |
| 2672 | @item or |
| 2673 | @item overlay |
| 2674 | @item phoenix |
| 2675 | @item pinlight |
| 2676 | @item reflect |
| 2677 | @item screen |
| 2678 | @item softlight |
| 2679 | @item subtract |
| 2680 | @item vividlight |
| 2681 | @item xor |
| 2682 | @end table |
| 2683 | |
| 2684 | @item c0_opacity |
| 2685 | @item c1_opacity |
| 2686 | @item c2_opacity |
| 2687 | @item c3_opacity |
| 2688 | @item all_opacity |
| 2689 | Set blend opacity for specific pixel component or all pixel components in case |
| 2690 | of @var{all_opacity}. Only used in combination with pixel component blend modes. |
| 2691 | |
| 2692 | @item c0_expr |
| 2693 | @item c1_expr |
| 2694 | @item c2_expr |
| 2695 | @item c3_expr |
| 2696 | @item all_expr |
| 2697 | Set blend expression for specific pixel component or all pixel components in case |
| 2698 | of @var{all_expr}. Note that related mode options will be ignored if those are set. |
| 2699 | |
| 2700 | The expressions can use the following variables: |
| 2701 | |
| 2702 | @table @option |
| 2703 | @item N |
| 2704 | The sequential number of the filtered frame, starting from @code{0}. |
| 2705 | |
| 2706 | @item X |
| 2707 | @item Y |
| 2708 | the coordinates of the current sample |
| 2709 | |
| 2710 | @item W |
| 2711 | @item H |
| 2712 | the width and height of currently filtered plane |
| 2713 | |
| 2714 | @item SW |
| 2715 | @item SH |
| 2716 | Width and height scale depending on the currently filtered plane. It is the |
| 2717 | ratio between the corresponding luma plane number of pixels and the current |
| 2718 | plane ones. E.g. for YUV4:2:0 the values are @code{1,1} for the luma plane, and |
| 2719 | @code{0.5,0.5} for chroma planes. |
| 2720 | |
| 2721 | @item T |
| 2722 | Time of the current frame, expressed in seconds. |
| 2723 | |
| 2724 | @item TOP, A |
| 2725 | Value of pixel component at current location for first video frame (top layer). |
| 2726 | |
| 2727 | @item BOTTOM, B |
| 2728 | Value of pixel component at current location for second video frame (bottom layer). |
| 2729 | @end table |
| 2730 | |
| 2731 | @item shortest |
| 2732 | Force termination when the shortest input terminates. Default is @code{0}. |
| 2733 | @item repeatlast |
| 2734 | Continue applying the last bottom frame after the end of the stream. A value of |
| 2735 | @code{0} disable the filter after the last frame of the bottom layer is reached. |
| 2736 | Default is @code{1}. |
| 2737 | @end table |
| 2738 | |
| 2739 | @subsection Examples |
| 2740 | |
| 2741 | @itemize |
| 2742 | @item |
| 2743 | Apply transition from bottom layer to top layer in first 10 seconds: |
| 2744 | @example |
| 2745 | blend=all_expr='A*(if(gte(T,10),1,T/10))+B*(1-(if(gte(T,10),1,T/10)))' |
| 2746 | @end example |
| 2747 | |
| 2748 | @item |
| 2749 | Apply 1x1 checkerboard effect: |
| 2750 | @example |
| 2751 | blend=all_expr='if(eq(mod(X,2),mod(Y,2)),A,B)' |
| 2752 | @end example |
| 2753 | |
| 2754 | @item |
| 2755 | Apply uncover left effect: |
| 2756 | @example |
| 2757 | blend=all_expr='if(gte(N*SW+X,W),A,B)' |
| 2758 | @end example |
| 2759 | |
| 2760 | @item |
| 2761 | Apply uncover down effect: |
| 2762 | @example |
| 2763 | blend=all_expr='if(gte(Y-N*SH,0),A,B)' |
| 2764 | @end example |
| 2765 | |
| 2766 | @item |
| 2767 | Apply uncover up-left effect: |
| 2768 | @example |
| 2769 | blend=all_expr='if(gte(T*SH*40+Y,H)*gte((T*40*SW+X)*W/H,W),A,B)' |
| 2770 | @end example |
| 2771 | @end itemize |
| 2772 | |
| 2773 | @section boxblur |
| 2774 | |
| 2775 | Apply a boxblur algorithm to the input video. |
| 2776 | |
| 2777 | It accepts the following parameters: |
| 2778 | |
| 2779 | @table @option |
| 2780 | |
| 2781 | @item luma_radius, lr |
| 2782 | @item luma_power, lp |
| 2783 | @item chroma_radius, cr |
| 2784 | @item chroma_power, cp |
| 2785 | @item alpha_radius, ar |
| 2786 | @item alpha_power, ap |
| 2787 | |
| 2788 | @end table |
| 2789 | |
| 2790 | A description of the accepted options follows. |
| 2791 | |
| 2792 | @table @option |
| 2793 | @item luma_radius, lr |
| 2794 | @item chroma_radius, cr |
| 2795 | @item alpha_radius, ar |
| 2796 | Set an expression for the box radius in pixels used for blurring the |
| 2797 | corresponding input plane. |
| 2798 | |
| 2799 | The radius value must be a non-negative number, and must not be |
| 2800 | greater than the value of the expression @code{min(w,h)/2} for the |
| 2801 | luma and alpha planes, and of @code{min(cw,ch)/2} for the chroma |
| 2802 | planes. |
| 2803 | |
| 2804 | Default value for @option{luma_radius} is "2". If not specified, |
| 2805 | @option{chroma_radius} and @option{alpha_radius} default to the |
| 2806 | corresponding value set for @option{luma_radius}. |
| 2807 | |
| 2808 | The expressions can contain the following constants: |
| 2809 | @table @option |
| 2810 | @item w |
| 2811 | @item h |
| 2812 | The input width and height in pixels. |
| 2813 | |
| 2814 | @item cw |
| 2815 | @item ch |
| 2816 | The input chroma image width and height in pixels. |
| 2817 | |
| 2818 | @item hsub |
| 2819 | @item vsub |
| 2820 | The horizontal and vertical chroma subsample values. For example, for the |
| 2821 | pixel format "yuv422p", @var{hsub} is 2 and @var{vsub} is 1. |
| 2822 | @end table |
| 2823 | |
| 2824 | @item luma_power, lp |
| 2825 | @item chroma_power, cp |
| 2826 | @item alpha_power, ap |
| 2827 | Specify how many times the boxblur filter is applied to the |
| 2828 | corresponding plane. |
| 2829 | |
| 2830 | Default value for @option{luma_power} is 2. If not specified, |
| 2831 | @option{chroma_power} and @option{alpha_power} default to the |
| 2832 | corresponding value set for @option{luma_power}. |
| 2833 | |
| 2834 | A value of 0 will disable the effect. |
| 2835 | @end table |
| 2836 | |
| 2837 | @subsection Examples |
| 2838 | |
| 2839 | @itemize |
| 2840 | @item |
| 2841 | Apply a boxblur filter with the luma, chroma, and alpha radii |
| 2842 | set to 2: |
| 2843 | @example |
| 2844 | boxblur=luma_radius=2:luma_power=1 |
| 2845 | boxblur=2:1 |
| 2846 | @end example |
| 2847 | |
| 2848 | @item |
| 2849 | Set the luma radius to 2, and alpha and chroma radius to 0: |
| 2850 | @example |
| 2851 | boxblur=2:1:cr=0:ar=0 |
| 2852 | @end example |
| 2853 | |
| 2854 | @item |
| 2855 | Set the luma and chroma radii to a fraction of the video dimension: |
| 2856 | @example |
| 2857 | boxblur=luma_radius=min(h\,w)/10:luma_power=1:chroma_radius=min(cw\,ch)/10:chroma_power=1 |
| 2858 | @end example |
| 2859 | @end itemize |
| 2860 | |
| 2861 | @section codecview |
| 2862 | |
| 2863 | Visualize information exported by some codecs. |
| 2864 | |
| 2865 | Some codecs can export information through frames using side-data or other |
| 2866 | means. For example, some MPEG based codecs export motion vectors through the |
| 2867 | @var{export_mvs} flag in the codec @option{flags2} option. |
| 2868 | |
| 2869 | The filter accepts the following option: |
| 2870 | |
| 2871 | @table @option |
| 2872 | @item mv |
| 2873 | Set motion vectors to visualize. |
| 2874 | |
| 2875 | Available flags for @var{mv} are: |
| 2876 | |
| 2877 | @table @samp |
| 2878 | @item pf |
| 2879 | forward predicted MVs of P-frames |
| 2880 | @item bf |
| 2881 | forward predicted MVs of B-frames |
| 2882 | @item bb |
| 2883 | backward predicted MVs of B-frames |
| 2884 | @end table |
| 2885 | @end table |
| 2886 | |
| 2887 | @subsection Examples |
| 2888 | |
| 2889 | @itemize |
| 2890 | @item |
| 2891 | Visualizes multi-directionals MVs from P and B-Frames using @command{ffplay}: |
| 2892 | @example |
| 2893 | ffplay -flags2 +export_mvs input.mpg -vf codecview=mv=pf+bf+bb |
| 2894 | @end example |
| 2895 | @end itemize |
| 2896 | |
| 2897 | @section colorbalance |
| 2898 | Modify intensity of primary colors (red, green and blue) of input frames. |
| 2899 | |
| 2900 | The filter allows an input frame to be adjusted in the shadows, midtones or highlights |
| 2901 | regions for the red-cyan, green-magenta or blue-yellow balance. |
| 2902 | |
| 2903 | A positive adjustment value shifts the balance towards the primary color, a negative |
| 2904 | value towards the complementary color. |
| 2905 | |
| 2906 | The filter accepts the following options: |
| 2907 | |
| 2908 | @table @option |
| 2909 | @item rs |
| 2910 | @item gs |
| 2911 | @item bs |
| 2912 | Adjust red, green and blue shadows (darkest pixels). |
| 2913 | |
| 2914 | @item rm |
| 2915 | @item gm |
| 2916 | @item bm |
| 2917 | Adjust red, green and blue midtones (medium pixels). |
| 2918 | |
| 2919 | @item rh |
| 2920 | @item gh |
| 2921 | @item bh |
| 2922 | Adjust red, green and blue highlights (brightest pixels). |
| 2923 | |
| 2924 | Allowed ranges for options are @code{[-1.0, 1.0]}. Defaults are @code{0}. |
| 2925 | @end table |
| 2926 | |
| 2927 | @subsection Examples |
| 2928 | |
| 2929 | @itemize |
| 2930 | @item |
| 2931 | Add red color cast to shadows: |
| 2932 | @example |
| 2933 | colorbalance=rs=.3 |
| 2934 | @end example |
| 2935 | @end itemize |
| 2936 | |
| 2937 | @section colorchannelmixer |
| 2938 | |
| 2939 | Adjust video input frames by re-mixing color channels. |
| 2940 | |
| 2941 | This filter modifies a color channel by adding the values associated to |
| 2942 | the other channels of the same pixels. For example if the value to |
| 2943 | modify is red, the output value will be: |
| 2944 | @example |
| 2945 | @var{red}=@var{red}*@var{rr} + @var{blue}*@var{rb} + @var{green}*@var{rg} + @var{alpha}*@var{ra} |
| 2946 | @end example |
| 2947 | |
| 2948 | The filter accepts the following options: |
| 2949 | |
| 2950 | @table @option |
| 2951 | @item rr |
| 2952 | @item rg |
| 2953 | @item rb |
| 2954 | @item ra |
| 2955 | Adjust contribution of input red, green, blue and alpha channels for output red channel. |
| 2956 | Default is @code{1} for @var{rr}, and @code{0} for @var{rg}, @var{rb} and @var{ra}. |
| 2957 | |
| 2958 | @item gr |
| 2959 | @item gg |
| 2960 | @item gb |
| 2961 | @item ga |
| 2962 | Adjust contribution of input red, green, blue and alpha channels for output green channel. |
| 2963 | Default is @code{1} for @var{gg}, and @code{0} for @var{gr}, @var{gb} and @var{ga}. |
| 2964 | |
| 2965 | @item br |
| 2966 | @item bg |
| 2967 | @item bb |
| 2968 | @item ba |
| 2969 | Adjust contribution of input red, green, blue and alpha channels for output blue channel. |
| 2970 | Default is @code{1} for @var{bb}, and @code{0} for @var{br}, @var{bg} and @var{ba}. |
| 2971 | |
| 2972 | @item ar |
| 2973 | @item ag |
| 2974 | @item ab |
| 2975 | @item aa |
| 2976 | Adjust contribution of input red, green, blue and alpha channels for output alpha channel. |
| 2977 | Default is @code{1} for @var{aa}, and @code{0} for @var{ar}, @var{ag} and @var{ab}. |
| 2978 | |
| 2979 | Allowed ranges for options are @code{[-2.0, 2.0]}. |
| 2980 | @end table |
| 2981 | |
| 2982 | @subsection Examples |
| 2983 | |
| 2984 | @itemize |
| 2985 | @item |
| 2986 | Convert source to grayscale: |
| 2987 | @example |
| 2988 | colorchannelmixer=.3:.4:.3:0:.3:.4:.3:0:.3:.4:.3 |
| 2989 | @end example |
| 2990 | @item |
| 2991 | Simulate sepia tones: |
| 2992 | @example |
| 2993 | colorchannelmixer=.393:.769:.189:0:.349:.686:.168:0:.272:.534:.131 |
| 2994 | @end example |
| 2995 | @end itemize |
| 2996 | |
| 2997 | @section colormatrix |
| 2998 | |
| 2999 | Convert color matrix. |
| 3000 | |
| 3001 | The filter accepts the following options: |
| 3002 | |
| 3003 | @table @option |
| 3004 | @item src |
| 3005 | @item dst |
| 3006 | Specify the source and destination color matrix. Both values must be |
| 3007 | specified. |
| 3008 | |
| 3009 | The accepted values are: |
| 3010 | @table @samp |
| 3011 | @item bt709 |
| 3012 | BT.709 |
| 3013 | |
| 3014 | @item bt601 |
| 3015 | BT.601 |
| 3016 | |
| 3017 | @item smpte240m |
| 3018 | SMPTE-240M |
| 3019 | |
| 3020 | @item fcc |
| 3021 | FCC |
| 3022 | @end table |
| 3023 | @end table |
| 3024 | |
| 3025 | For example to convert from BT.601 to SMPTE-240M, use the command: |
| 3026 | @example |
| 3027 | colormatrix=bt601:smpte240m |
| 3028 | @end example |
| 3029 | |
| 3030 | @section copy |
| 3031 | |
| 3032 | Copy the input source unchanged to the output. This is mainly useful for |
| 3033 | testing purposes. |
| 3034 | |
| 3035 | @section crop |
| 3036 | |
| 3037 | Crop the input video to given dimensions. |
| 3038 | |
| 3039 | It accepts the following parameters: |
| 3040 | |
| 3041 | @table @option |
| 3042 | @item w, out_w |
| 3043 | The width of the output video. It defaults to @code{iw}. |
| 3044 | This expression is evaluated only once during the filter |
| 3045 | configuration. |
| 3046 | |
| 3047 | @item h, out_h |
| 3048 | The height of the output video. It defaults to @code{ih}. |
| 3049 | This expression is evaluated only once during the filter |
| 3050 | configuration. |
| 3051 | |
| 3052 | @item x |
| 3053 | The horizontal position, in the input video, of the left edge of the output |
| 3054 | video. It defaults to @code{(in_w-out_w)/2}. |
| 3055 | This expression is evaluated per-frame. |
| 3056 | |
| 3057 | @item y |
| 3058 | The vertical position, in the input video, of the top edge of the output video. |
| 3059 | It defaults to @code{(in_h-out_h)/2}. |
| 3060 | This expression is evaluated per-frame. |
| 3061 | |
| 3062 | @item keep_aspect |
| 3063 | If set to 1 will force the output display aspect ratio |
| 3064 | to be the same of the input, by changing the output sample aspect |
| 3065 | ratio. It defaults to 0. |
| 3066 | @end table |
| 3067 | |
| 3068 | The @var{out_w}, @var{out_h}, @var{x}, @var{y} parameters are |
| 3069 | expressions containing the following constants: |
| 3070 | |
| 3071 | @table @option |
| 3072 | @item x |
| 3073 | @item y |
| 3074 | The computed values for @var{x} and @var{y}. They are evaluated for |
| 3075 | each new frame. |
| 3076 | |
| 3077 | @item in_w |
| 3078 | @item in_h |
| 3079 | The input width and height. |
| 3080 | |
| 3081 | @item iw |
| 3082 | @item ih |
| 3083 | These are the same as @var{in_w} and @var{in_h}. |
| 3084 | |
| 3085 | @item out_w |
| 3086 | @item out_h |
| 3087 | The output (cropped) width and height. |
| 3088 | |
| 3089 | @item ow |
| 3090 | @item oh |
| 3091 | These are the same as @var{out_w} and @var{out_h}. |
| 3092 | |
| 3093 | @item a |
| 3094 | same as @var{iw} / @var{ih} |
| 3095 | |
| 3096 | @item sar |
| 3097 | input sample aspect ratio |
| 3098 | |
| 3099 | @item dar |
| 3100 | input display aspect ratio, it is the same as (@var{iw} / @var{ih}) * @var{sar} |
| 3101 | |
| 3102 | @item hsub |
| 3103 | @item vsub |
| 3104 | horizontal and vertical chroma subsample values. For example for the |
| 3105 | pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1. |
| 3106 | |
| 3107 | @item n |
| 3108 | The number of the input frame, starting from 0. |
| 3109 | |
| 3110 | @item pos |
| 3111 | the position in the file of the input frame, NAN if unknown |
| 3112 | |
| 3113 | @item t |
| 3114 | The timestamp expressed in seconds. It's NAN if the input timestamp is unknown. |
| 3115 | |
| 3116 | @end table |
| 3117 | |
| 3118 | The expression for @var{out_w} may depend on the value of @var{out_h}, |
| 3119 | and the expression for @var{out_h} may depend on @var{out_w}, but they |
| 3120 | cannot depend on @var{x} and @var{y}, as @var{x} and @var{y} are |
| 3121 | evaluated after @var{out_w} and @var{out_h}. |
| 3122 | |
| 3123 | The @var{x} and @var{y} parameters specify the expressions for the |
| 3124 | position of the top-left corner of the output (non-cropped) area. They |
| 3125 | are evaluated for each frame. If the evaluated value is not valid, it |
| 3126 | is approximated to the nearest valid value. |
| 3127 | |
| 3128 | The expression for @var{x} may depend on @var{y}, and the expression |
| 3129 | for @var{y} may depend on @var{x}. |
| 3130 | |
| 3131 | @subsection Examples |
| 3132 | |
| 3133 | @itemize |
| 3134 | @item |
| 3135 | Crop area with size 100x100 at position (12,34). |
| 3136 | @example |
| 3137 | crop=100:100:12:34 |
| 3138 | @end example |
| 3139 | |
| 3140 | Using named options, the example above becomes: |
| 3141 | @example |
| 3142 | crop=w=100:h=100:x=12:y=34 |
| 3143 | @end example |
| 3144 | |
| 3145 | @item |
| 3146 | Crop the central input area with size 100x100: |
| 3147 | @example |
| 3148 | crop=100:100 |
| 3149 | @end example |
| 3150 | |
| 3151 | @item |
| 3152 | Crop the central input area with size 2/3 of the input video: |
| 3153 | @example |
| 3154 | crop=2/3*in_w:2/3*in_h |
| 3155 | @end example |
| 3156 | |
| 3157 | @item |
| 3158 | Crop the input video central square: |
| 3159 | @example |
| 3160 | crop=out_w=in_h |
| 3161 | crop=in_h |
| 3162 | @end example |
| 3163 | |
| 3164 | @item |
| 3165 | Delimit the rectangle with the top-left corner placed at position |
| 3166 | 100:100 and the right-bottom corner corresponding to the right-bottom |
| 3167 | corner of the input image. |
| 3168 | @example |
| 3169 | crop=in_w-100:in_h-100:100:100 |
| 3170 | @end example |
| 3171 | |
| 3172 | @item |
| 3173 | Crop 10 pixels from the left and right borders, and 20 pixels from |
| 3174 | the top and bottom borders |
| 3175 | @example |
| 3176 | crop=in_w-2*10:in_h-2*20 |
| 3177 | @end example |
| 3178 | |
| 3179 | @item |
| 3180 | Keep only the bottom right quarter of the input image: |
| 3181 | @example |
| 3182 | crop=in_w/2:in_h/2:in_w/2:in_h/2 |
| 3183 | @end example |
| 3184 | |
| 3185 | @item |
| 3186 | Crop height for getting Greek harmony: |
| 3187 | @example |
| 3188 | crop=in_w:1/PHI*in_w |
| 3189 | @end example |
| 3190 | |
| 3191 | @item |
| 3192 | Appply trembling effect: |
| 3193 | @example |
| 3194 | crop=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) |
| 3195 | @end example |
| 3196 | |
| 3197 | @item |
| 3198 | Apply erratic camera effect depending on timestamp: |
| 3199 | @example |
| 3200 | crop=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)" |
| 3201 | @end example |
| 3202 | |
| 3203 | @item |
| 3204 | Set x depending on the value of y: |
| 3205 | @example |
| 3206 | crop=in_w/2:in_h/2:y:10+10*sin(n/10) |
| 3207 | @end example |
| 3208 | @end itemize |
| 3209 | |
| 3210 | @section cropdetect |
| 3211 | |
| 3212 | Auto-detect the crop size. |
| 3213 | |
| 3214 | It calculates the necessary cropping parameters and prints the |
| 3215 | recommended parameters via the logging system. The detected dimensions |
| 3216 | correspond to the non-black area of the input video. |
| 3217 | |
| 3218 | It accepts the following parameters: |
| 3219 | |
| 3220 | @table @option |
| 3221 | |
| 3222 | @item limit |
| 3223 | Set higher black value threshold, which can be optionally specified |
| 3224 | from nothing (0) to everything (255). An intensity value greater |
| 3225 | to the set value is considered non-black. It defaults to 24. |
| 3226 | |
| 3227 | @item round |
| 3228 | The value which the width/height should be divisible by. It defaults to |
| 3229 | 16. The offset is automatically adjusted to center the video. Use 2 to |
| 3230 | get only even dimensions (needed for 4:2:2 video). 16 is best when |
| 3231 | encoding to most video codecs. |
| 3232 | |
| 3233 | @item reset_count, reset |
| 3234 | Set the counter that determines after how many frames cropdetect will |
| 3235 | reset the previously detected largest video area and start over to |
| 3236 | detect the current optimal crop area. Default value is 0. |
| 3237 | |
| 3238 | This can be useful when channel logos distort the video area. 0 |
| 3239 | indicates 'never reset', and returns the largest area encountered during |
| 3240 | playback. |
| 3241 | @end table |
| 3242 | |
| 3243 | @anchor{curves} |
| 3244 | @section curves |
| 3245 | |
| 3246 | Apply color adjustments using curves. |
| 3247 | |
| 3248 | This filter is similar to the Adobe Photoshop and GIMP curves tools. Each |
| 3249 | component (red, green and blue) has its values defined by @var{N} key points |
| 3250 | tied from each other using a smooth curve. The x-axis represents the pixel |
| 3251 | values from the input frame, and the y-axis the new pixel values to be set for |
| 3252 | the output frame. |
| 3253 | |
| 3254 | By default, a component curve is defined by the two points @var{(0;0)} and |
| 3255 | @var{(1;1)}. This creates a straight line where each original pixel value is |
| 3256 | "adjusted" to its own value, which means no change to the image. |
| 3257 | |
| 3258 | The filter allows you to redefine these two points and add some more. A new |
| 3259 | curve (using a natural cubic spline interpolation) will be define to pass |
| 3260 | smoothly through all these new coordinates. The new defined points needs to be |
| 3261 | strictly increasing over the x-axis, and their @var{x} and @var{y} values must |
| 3262 | be in the @var{[0;1]} interval. If the computed curves happened to go outside |
| 3263 | the vector spaces, the values will be clipped accordingly. |
| 3264 | |
| 3265 | If there is no key point defined in @code{x=0}, the filter will automatically |
| 3266 | insert a @var{(0;0)} point. In the same way, if there is no key point defined |
| 3267 | in @code{x=1}, the filter will automatically insert a @var{(1;1)} point. |
| 3268 | |
| 3269 | The filter accepts the following options: |
| 3270 | |
| 3271 | @table @option |
| 3272 | @item preset |
| 3273 | Select one of the available color presets. This option can be used in addition |
| 3274 | to the @option{r}, @option{g}, @option{b} parameters; in this case, the later |
| 3275 | options takes priority on the preset values. |
| 3276 | Available presets are: |
| 3277 | @table @samp |
| 3278 | @item none |
| 3279 | @item color_negative |
| 3280 | @item cross_process |
| 3281 | @item darker |
| 3282 | @item increase_contrast |
| 3283 | @item lighter |
| 3284 | @item linear_contrast |
| 3285 | @item medium_contrast |
| 3286 | @item negative |
| 3287 | @item strong_contrast |
| 3288 | @item vintage |
| 3289 | @end table |
| 3290 | Default is @code{none}. |
| 3291 | @item master, m |
| 3292 | Set the master key points. These points will define a second pass mapping. It |
| 3293 | is sometimes called a "luminance" or "value" mapping. It can be used with |
| 3294 | @option{r}, @option{g}, @option{b} or @option{all} since it acts like a |
| 3295 | post-processing LUT. |
| 3296 | @item red, r |
| 3297 | Set the key points for the red component. |
| 3298 | @item green, g |
| 3299 | Set the key points for the green component. |
| 3300 | @item blue, b |
| 3301 | Set the key points for the blue component. |
| 3302 | @item all |
| 3303 | Set the key points for all components (not including master). |
| 3304 | Can be used in addition to the other key points component |
| 3305 | options. In this case, the unset component(s) will fallback on this |
| 3306 | @option{all} setting. |
| 3307 | @item psfile |
| 3308 | Specify a Photoshop curves file (@code{.asv}) to import the settings from. |
| 3309 | @end table |
| 3310 | |
| 3311 | To avoid some filtergraph syntax conflicts, each key points list need to be |
| 3312 | defined using the following syntax: @code{x0/y0 x1/y1 x2/y2 ...}. |
| 3313 | |
| 3314 | @subsection Examples |
| 3315 | |
| 3316 | @itemize |
| 3317 | @item |
| 3318 | Increase slightly the middle level of blue: |
| 3319 | @example |
| 3320 | curves=blue='0.5/0.58' |
| 3321 | @end example |
| 3322 | |
| 3323 | @item |
| 3324 | Vintage effect: |
| 3325 | @example |
| 3326 | curves=r='0/0.11 .42/.51 1/0.95':g='0.50/0.48':b='0/0.22 .49/.44 1/0.8' |
| 3327 | @end example |
| 3328 | Here we obtain the following coordinates for each components: |
| 3329 | @table @var |
| 3330 | @item red |
| 3331 | @code{(0;0.11) (0.42;0.51) (1;0.95)} |
| 3332 | @item green |
| 3333 | @code{(0;0) (0.50;0.48) (1;1)} |
| 3334 | @item blue |
| 3335 | @code{(0;0.22) (0.49;0.44) (1;0.80)} |
| 3336 | @end table |
| 3337 | |
| 3338 | @item |
| 3339 | The previous example can also be achieved with the associated built-in preset: |
| 3340 | @example |
| 3341 | curves=preset=vintage |
| 3342 | @end example |
| 3343 | |
| 3344 | @item |
| 3345 | Or simply: |
| 3346 | @example |
| 3347 | curves=vintage |
| 3348 | @end example |
| 3349 | |
| 3350 | @item |
| 3351 | Use a Photoshop preset and redefine the points of the green component: |
| 3352 | @example |
| 3353 | curves=psfile='MyCurvesPresets/purple.asv':green='0.45/0.53' |
| 3354 | @end example |
| 3355 | @end itemize |
| 3356 | |
| 3357 | @section dctdnoiz |
| 3358 | |
| 3359 | Denoise frames using 2D DCT (frequency domain filtering). |
| 3360 | |
| 3361 | This filter is not designed for real time. |
| 3362 | |
| 3363 | The filter accepts the following options: |
| 3364 | |
| 3365 | @table @option |
| 3366 | @item sigma, s |
| 3367 | Set the noise sigma constant. |
| 3368 | |
| 3369 | This @var{sigma} defines a hard threshold of @code{3 * sigma}; every DCT |
| 3370 | coefficient (absolute value) below this threshold with be dropped. |
| 3371 | |
| 3372 | If you need a more advanced filtering, see @option{expr}. |
| 3373 | |
| 3374 | Default is @code{0}. |
| 3375 | |
| 3376 | @item overlap |
| 3377 | Set number overlapping pixels for each block. Since the filter can be slow, you |
| 3378 | may want to reduce this value, at the cost of a less effective filter and the |
| 3379 | risk of various artefacts. |
| 3380 | |
| 3381 | If the overlapping value doesn't allow to process the whole input width or |
| 3382 | height, a warning will be displayed and according borders won't be denoised. |
| 3383 | |
| 3384 | Default value is @var{blocksize}-1, which is the best possible setting. |
| 3385 | |
| 3386 | @item expr, e |
| 3387 | Set the coefficient factor expression. |
| 3388 | |
| 3389 | For each coefficient of a DCT block, this expression will be evaluated as a |
| 3390 | multiplier value for the coefficient. |
| 3391 | |
| 3392 | If this is option is set, the @option{sigma} option will be ignored. |
| 3393 | |
| 3394 | The absolute value of the coefficient can be accessed through the @var{c} |
| 3395 | variable. |
| 3396 | |
| 3397 | @item n |
| 3398 | Set the @var{blocksize} using the number of bits. @code{1<<@var{n}} defines the |
| 3399 | @var{blocksize}, which is the width and height of the processed blocks. |
| 3400 | |
| 3401 | The default value is @var{3} (8x8) and can be raised to @var{4} for a |
| 3402 | @var{blocksize} of 16x16. Note that changing this setting has huge consequences |
| 3403 | on the speed processing. Also, a larger block size does not necessarily means a |
| 3404 | better de-noising. |
| 3405 | @end table |
| 3406 | |
| 3407 | @subsection Examples |
| 3408 | |
| 3409 | Apply a denoise with a @option{sigma} of @code{4.5}: |
| 3410 | @example |
| 3411 | dctdnoiz=4.5 |
| 3412 | @end example |
| 3413 | |
| 3414 | The same operation can be achieved using the expression system: |
| 3415 | @example |
| 3416 | dctdnoiz=e='gte(c, 4.5*3)' |
| 3417 | @end example |
| 3418 | |
| 3419 | Violent denoise using a block size of @code{16x16}: |
| 3420 | @example |
| 3421 | dctdnoiz=15:n=4 |
| 3422 | @end example |
| 3423 | |
| 3424 | @anchor{decimate} |
| 3425 | @section decimate |
| 3426 | |
| 3427 | Drop duplicated frames at regular intervals. |
| 3428 | |
| 3429 | The filter accepts the following options: |
| 3430 | |
| 3431 | @table @option |
| 3432 | @item cycle |
| 3433 | Set the number of frames from which one will be dropped. Setting this to |
| 3434 | @var{N} means one frame in every batch of @var{N} frames will be dropped. |
| 3435 | Default is @code{5}. |
| 3436 | |
| 3437 | @item dupthresh |
| 3438 | Set the threshold for duplicate detection. If the difference metric for a frame |
| 3439 | is less than or equal to this value, then it is declared as duplicate. Default |
| 3440 | is @code{1.1} |
| 3441 | |
| 3442 | @item scthresh |
| 3443 | Set scene change threshold. Default is @code{15}. |
| 3444 | |
| 3445 | @item blockx |
| 3446 | @item blocky |
| 3447 | Set the size of the x and y-axis blocks used during metric calculations. |
| 3448 | Larger blocks give better noise suppression, but also give worse detection of |
| 3449 | small movements. Must be a power of two. Default is @code{32}. |
| 3450 | |
| 3451 | @item ppsrc |
| 3452 | Mark main input as a pre-processed input and activate clean source input |
| 3453 | stream. This allows the input to be pre-processed with various filters to help |
| 3454 | the metrics calculation while keeping the frame selection lossless. When set to |
| 3455 | @code{1}, the first stream is for the pre-processed input, and the second |
| 3456 | stream is the clean source from where the kept frames are chosen. Default is |
| 3457 | @code{0}. |
| 3458 | |
| 3459 | @item chroma |
| 3460 | Set whether or not chroma is considered in the metric calculations. Default is |
| 3461 | @code{1}. |
| 3462 | @end table |
| 3463 | |
| 3464 | @section dejudder |
| 3465 | |
| 3466 | Remove judder produced by partially interlaced telecined content. |
| 3467 | |
| 3468 | Judder can be introduced, for instance, by @ref{pullup} filter. If the original |
| 3469 | source was partially telecined content then the output of @code{pullup,dejudder} |
| 3470 | will have a variable frame rate. May change the recorded frame rate of the |
| 3471 | container. Aside from that change, this filter will not affect constant frame |
| 3472 | rate video. |
| 3473 | |
| 3474 | The option available in this filter is: |
| 3475 | @table @option |
| 3476 | |
| 3477 | @item cycle |
| 3478 | Specify the length of the window over which the judder repeats. |
| 3479 | |
| 3480 | Accepts any integer greater than 1. Useful values are: |
| 3481 | @table @samp |
| 3482 | |
| 3483 | @item 4 |
| 3484 | If the original was telecined from 24 to 30 fps (Film to NTSC). |
| 3485 | |
| 3486 | @item 5 |
| 3487 | If the original was telecined from 25 to 30 fps (PAL to NTSC). |
| 3488 | |
| 3489 | @item 20 |
| 3490 | If a mixture of the two. |
| 3491 | @end table |
| 3492 | |
| 3493 | The default is @samp{4}. |
| 3494 | @end table |
| 3495 | |
| 3496 | @section delogo |
| 3497 | |
| 3498 | Suppress a TV station logo by a simple interpolation of the surrounding |
| 3499 | pixels. Just set a rectangle covering the logo and watch it disappear |
| 3500 | (and sometimes something even uglier appear - your mileage may vary). |
| 3501 | |
| 3502 | It accepts the following parameters: |
| 3503 | @table @option |
| 3504 | |
| 3505 | @item x |
| 3506 | @item y |
| 3507 | Specify the top left corner coordinates of the logo. They must be |
| 3508 | specified. |
| 3509 | |
| 3510 | @item w |
| 3511 | @item h |
| 3512 | Specify the width and height of the logo to clear. They must be |
| 3513 | specified. |
| 3514 | |
| 3515 | @item band, t |
| 3516 | Specify the thickness of the fuzzy edge of the rectangle (added to |
| 3517 | @var{w} and @var{h}). The default value is 4. |
| 3518 | |
| 3519 | @item show |
| 3520 | When set to 1, a green rectangle is drawn on the screen to simplify |
| 3521 | finding the right @var{x}, @var{y}, @var{w}, and @var{h} parameters. |
| 3522 | The default value is 0. |
| 3523 | |
| 3524 | The rectangle is drawn on the outermost pixels which will be (partly) |
| 3525 | replaced with interpolated values. The values of the next pixels |
| 3526 | immediately outside this rectangle in each direction will be used to |
| 3527 | compute the interpolated pixel values inside the rectangle. |
| 3528 | |
| 3529 | @end table |
| 3530 | |
| 3531 | @subsection Examples |
| 3532 | |
| 3533 | @itemize |
| 3534 | @item |
| 3535 | Set a rectangle covering the area with top left corner coordinates 0,0 |
| 3536 | and size 100x77, and a band of size 10: |
| 3537 | @example |
| 3538 | delogo=x=0:y=0:w=100:h=77:band=10 |
| 3539 | @end example |
| 3540 | |
| 3541 | @end itemize |
| 3542 | |
| 3543 | @section deshake |
| 3544 | |
| 3545 | Attempt to fix small changes in horizontal and/or vertical shift. This |
| 3546 | filter helps remove camera shake from hand-holding a camera, bumping a |
| 3547 | tripod, moving on a vehicle, etc. |
| 3548 | |
| 3549 | The filter accepts the following options: |
| 3550 | |
| 3551 | @table @option |
| 3552 | |
| 3553 | @item x |
| 3554 | @item y |
| 3555 | @item w |
| 3556 | @item h |
| 3557 | Specify a rectangular area where to limit the search for motion |
| 3558 | vectors. |
| 3559 | If desired the search for motion vectors can be limited to a |
| 3560 | rectangular area of the frame defined by its top left corner, width |
| 3561 | and height. These parameters have the same meaning as the drawbox |
| 3562 | filter which can be used to visualise the position of the bounding |
| 3563 | box. |
| 3564 | |
| 3565 | This is useful when simultaneous movement of subjects within the frame |
| 3566 | might be confused for camera motion by the motion vector search. |
| 3567 | |
| 3568 | If any or all of @var{x}, @var{y}, @var{w} and @var{h} are set to -1 |
| 3569 | then the full frame is used. This allows later options to be set |
| 3570 | without specifying the bounding box for the motion vector search. |
| 3571 | |
| 3572 | Default - search the whole frame. |
| 3573 | |
| 3574 | @item rx |
| 3575 | @item ry |
| 3576 | Specify the maximum extent of movement in x and y directions in the |
| 3577 | range 0-64 pixels. Default 16. |
| 3578 | |
| 3579 | @item edge |
| 3580 | Specify how to generate pixels to fill blanks at the edge of the |
| 3581 | frame. Available values are: |
| 3582 | @table @samp |
| 3583 | @item blank, 0 |
| 3584 | Fill zeroes at blank locations |
| 3585 | @item original, 1 |
| 3586 | Original image at blank locations |
| 3587 | @item clamp, 2 |
| 3588 | Extruded edge value at blank locations |
| 3589 | @item mirror, 3 |
| 3590 | Mirrored edge at blank locations |
| 3591 | @end table |
| 3592 | Default value is @samp{mirror}. |
| 3593 | |
| 3594 | @item blocksize |
| 3595 | Specify the blocksize to use for motion search. Range 4-128 pixels, |
| 3596 | default 8. |
| 3597 | |
| 3598 | @item contrast |
| 3599 | Specify the contrast threshold for blocks. Only blocks with more than |
| 3600 | the specified contrast (difference between darkest and lightest |
| 3601 | pixels) will be considered. Range 1-255, default 125. |
| 3602 | |
| 3603 | @item search |
| 3604 | Specify the search strategy. Available values are: |
| 3605 | @table @samp |
| 3606 | @item exhaustive, 0 |
| 3607 | Set exhaustive search |
| 3608 | @item less, 1 |
| 3609 | Set less exhaustive search. |
| 3610 | @end table |
| 3611 | Default value is @samp{exhaustive}. |
| 3612 | |
| 3613 | @item filename |
| 3614 | If set then a detailed log of the motion search is written to the |
| 3615 | specified file. |
| 3616 | |
| 3617 | @item opencl |
| 3618 | If set to 1, specify using OpenCL capabilities, only available if |
| 3619 | FFmpeg was configured with @code{--enable-opencl}. Default value is 0. |
| 3620 | |
| 3621 | @end table |
| 3622 | |
| 3623 | @section drawbox |
| 3624 | |
| 3625 | Draw a colored box on the input image. |
| 3626 | |
| 3627 | It accepts the following parameters: |
| 3628 | |
| 3629 | @table @option |
| 3630 | @item x |
| 3631 | @item y |
| 3632 | The expressions which specify the top left corner coordinates of the box. It defaults to 0. |
| 3633 | |
| 3634 | @item width, w |
| 3635 | @item height, h |
| 3636 | The expressions which specify the width and height of the box; if 0 they are interpreted as |
| 3637 | the input width and height. It defaults to 0. |
| 3638 | |
| 3639 | @item color, c |
| 3640 | Specify the color of the box to write. For the general syntax of this option, |
| 3641 | check the "Color" section in the ffmpeg-utils manual. If the special |
| 3642 | value @code{invert} is used, the box edge color is the same as the |
| 3643 | video with inverted luma. |
| 3644 | |
| 3645 | @item thickness, t |
| 3646 | The expression which sets the thickness of the box edge. Default value is @code{3}. |
| 3647 | |
| 3648 | See below for the list of accepted constants. |
| 3649 | @end table |
| 3650 | |
| 3651 | The parameters for @var{x}, @var{y}, @var{w} and @var{h} and @var{t} are expressions containing the |
| 3652 | following constants: |
| 3653 | |
| 3654 | @table @option |
| 3655 | @item dar |
| 3656 | The input display aspect ratio, it is the same as (@var{w} / @var{h}) * @var{sar}. |
| 3657 | |
| 3658 | @item hsub |
| 3659 | @item vsub |
| 3660 | horizontal and vertical chroma subsample values. For example for the |
| 3661 | pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1. |
| 3662 | |
| 3663 | @item in_h, ih |
| 3664 | @item in_w, iw |
| 3665 | The input width and height. |
| 3666 | |
| 3667 | @item sar |
| 3668 | The input sample aspect ratio. |
| 3669 | |
| 3670 | @item x |
| 3671 | @item y |
| 3672 | The x and y offset coordinates where the box is drawn. |
| 3673 | |
| 3674 | @item w |
| 3675 | @item h |
| 3676 | The width and height of the drawn box. |
| 3677 | |
| 3678 | @item t |
| 3679 | The thickness of the drawn box. |
| 3680 | |
| 3681 | These constants allow the @var{x}, @var{y}, @var{w}, @var{h} and @var{t} expressions to refer to |
| 3682 | each other, so you may for example specify @code{y=x/dar} or @code{h=w/dar}. |
| 3683 | |
| 3684 | @end table |
| 3685 | |
| 3686 | @subsection Examples |
| 3687 | |
| 3688 | @itemize |
| 3689 | @item |
| 3690 | Draw a black box around the edge of the input image: |
| 3691 | @example |
| 3692 | drawbox |
| 3693 | @end example |
| 3694 | |
| 3695 | @item |
| 3696 | Draw a box with color red and an opacity of 50%: |
| 3697 | @example |
| 3698 | drawbox=10:20:200:60:red@@0.5 |
| 3699 | @end example |
| 3700 | |
| 3701 | The previous example can be specified as: |
| 3702 | @example |
| 3703 | drawbox=x=10:y=20:w=200:h=60:color=red@@0.5 |
| 3704 | @end example |
| 3705 | |
| 3706 | @item |
| 3707 | Fill the box with pink color: |
| 3708 | @example |
| 3709 | drawbox=x=10:y=10:w=100:h=100:color=pink@@0.5:t=max |
| 3710 | @end example |
| 3711 | |
| 3712 | @item |
| 3713 | Draw a 2-pixel red 2.40:1 mask: |
| 3714 | @example |
| 3715 | drawbox=x=-t:y=0.5*(ih-iw/2.4)-t:w=iw+t*2:h=iw/2.4+t*2:t=2:c=red |
| 3716 | @end example |
| 3717 | @end itemize |
| 3718 | |
| 3719 | @section drawgrid |
| 3720 | |
| 3721 | Draw a grid on the input image. |
| 3722 | |
| 3723 | It accepts the following parameters: |
| 3724 | |
| 3725 | @table @option |
| 3726 | @item x |
| 3727 | @item y |
| 3728 | The expressions which specify the coordinates of some point of grid intersection (meant to configure offset). Both default to 0. |
| 3729 | |
| 3730 | @item width, w |
| 3731 | @item height, h |
| 3732 | The expressions which specify the width and height of the grid cell, if 0 they are interpreted as the |
| 3733 | input width and height, respectively, minus @code{thickness}, so image gets |
| 3734 | framed. Default to 0. |
| 3735 | |
| 3736 | @item color, c |
| 3737 | Specify the color of the grid. For the general syntax of this option, |
| 3738 | check the "Color" section in the ffmpeg-utils manual. If the special |
| 3739 | value @code{invert} is used, the grid color is the same as the |
| 3740 | video with inverted luma. |
| 3741 | |
| 3742 | @item thickness, t |
| 3743 | The expression which sets the thickness of the grid line. Default value is @code{1}. |
| 3744 | |
| 3745 | See below for the list of accepted constants. |
| 3746 | @end table |
| 3747 | |
| 3748 | The parameters for @var{x}, @var{y}, @var{w} and @var{h} and @var{t} are expressions containing the |
| 3749 | following constants: |
| 3750 | |
| 3751 | @table @option |
| 3752 | @item dar |
| 3753 | The input display aspect ratio, it is the same as (@var{w} / @var{h}) * @var{sar}. |
| 3754 | |
| 3755 | @item hsub |
| 3756 | @item vsub |
| 3757 | horizontal and vertical chroma subsample values. For example for the |
| 3758 | pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1. |
| 3759 | |
| 3760 | @item in_h, ih |
| 3761 | @item in_w, iw |
| 3762 | The input grid cell width and height. |
| 3763 | |
| 3764 | @item sar |
| 3765 | The input sample aspect ratio. |
| 3766 | |
| 3767 | @item x |
| 3768 | @item y |
| 3769 | The x and y coordinates of some point of grid intersection (meant to configure offset). |
| 3770 | |
| 3771 | @item w |
| 3772 | @item h |
| 3773 | The width and height of the drawn cell. |
| 3774 | |
| 3775 | @item t |
| 3776 | The thickness of the drawn cell. |
| 3777 | |
| 3778 | These constants allow the @var{x}, @var{y}, @var{w}, @var{h} and @var{t} expressions to refer to |
| 3779 | each other, so you may for example specify @code{y=x/dar} or @code{h=w/dar}. |
| 3780 | |
| 3781 | @end table |
| 3782 | |
| 3783 | @subsection Examples |
| 3784 | |
| 3785 | @itemize |
| 3786 | @item |
| 3787 | Draw a grid with cell 100x100 pixels, thickness 2 pixels, with color red and an opacity of 50%: |
| 3788 | @example |
| 3789 | drawgrid=width=100:height=100:thickness=2:color=red@@0.5 |
| 3790 | @end example |
| 3791 | |
| 3792 | @item |
| 3793 | Draw a white 3x3 grid with an opacity of 50%: |
| 3794 | @example |
| 3795 | drawgrid=w=iw/3:h=ih/3:t=2:c=white@@0.5 |
| 3796 | @end example |
| 3797 | @end itemize |
| 3798 | |
| 3799 | @anchor{drawtext} |
| 3800 | @section drawtext |
| 3801 | |
| 3802 | Draw a text string or text from a specified file on top of a video, using the |
| 3803 | libfreetype library. |
| 3804 | |
| 3805 | To enable compilation of this filter, you need to configure FFmpeg with |
| 3806 | @code{--enable-libfreetype}. |
| 3807 | To enable default font fallback and the @var{font} option you need to |
| 3808 | configure FFmpeg with @code{--enable-libfontconfig}. |
| 3809 | To enable the @var{text_shaping} option, you need to configure FFmpeg with |
| 3810 | @code{--enable-libfribidi}. |
| 3811 | |
| 3812 | @subsection Syntax |
| 3813 | |
| 3814 | It accepts the following parameters: |
| 3815 | |
| 3816 | @table @option |
| 3817 | |
| 3818 | @item box |
| 3819 | Used to draw a box around text using the background color. |
| 3820 | The value must be either 1 (enable) or 0 (disable). |
| 3821 | The default value of @var{box} is 0. |
| 3822 | |
| 3823 | @item boxcolor |
| 3824 | The color to be used for drawing box around text. For the syntax of this |
| 3825 | option, check the "Color" section in the ffmpeg-utils manual. |
| 3826 | |
| 3827 | The default value of @var{boxcolor} is "white". |
| 3828 | |
| 3829 | @item borderw |
| 3830 | Set the width of the border to be drawn around the text using @var{bordercolor}. |
| 3831 | The default value of @var{borderw} is 0. |
| 3832 | |
| 3833 | @item bordercolor |
| 3834 | Set the color to be used for drawing border around text. For the syntax of this |
| 3835 | option, check the "Color" section in the ffmpeg-utils manual. |
| 3836 | |
| 3837 | The default value of @var{bordercolor} is "black". |
| 3838 | |
| 3839 | @item expansion |
| 3840 | Select how the @var{text} is expanded. Can be either @code{none}, |
| 3841 | @code{strftime} (deprecated) or |
| 3842 | @code{normal} (default). See the @ref{drawtext_expansion, Text expansion} section |
| 3843 | below for details. |
| 3844 | |
| 3845 | @item fix_bounds |
| 3846 | If true, check and fix text coords to avoid clipping. |
| 3847 | |
| 3848 | @item fontcolor |
| 3849 | The color to be used for drawing fonts. For the syntax of this option, check |
| 3850 | the "Color" section in the ffmpeg-utils manual. |
| 3851 | |
| 3852 | The default value of @var{fontcolor} is "black". |
| 3853 | |
| 3854 | @item fontcolor_expr |
| 3855 | String which is expanded the same way as @var{text} to obtain dynamic |
| 3856 | @var{fontcolor} value. By default this option has empty value and is not |
| 3857 | processed. When this option is set, it overrides @var{fontcolor} option. |
| 3858 | |
| 3859 | @item font |
| 3860 | The font family to be used for drawing text. By default Sans. |
| 3861 | |
| 3862 | @item fontfile |
| 3863 | The font file to be used for drawing text. The path must be included. |
| 3864 | This parameter is mandatory if the fontconfig support is disabled. |
| 3865 | |
| 3866 | @item fontsize |
| 3867 | The font size to be used for drawing text. |
| 3868 | The default value of @var{fontsize} is 16. |
| 3869 | |
| 3870 | @item text_shaping |
| 3871 | If set to 1, attempt to shape the text (for example, reverse the order of |
| 3872 | right-to-left text and join Arabic characters) before drawing it. |
| 3873 | Otherwise, just draw the text exactly as given. |
| 3874 | By default 1 (if supported). |
| 3875 | |
| 3876 | @item ft_load_flags |
| 3877 | The flags to be used for loading the fonts. |
| 3878 | |
| 3879 | The flags map the corresponding flags supported by libfreetype, and are |
| 3880 | a combination of the following values: |
| 3881 | @table @var |
| 3882 | @item default |
| 3883 | @item no_scale |
| 3884 | @item no_hinting |
| 3885 | @item render |
| 3886 | @item no_bitmap |
| 3887 | @item vertical_layout |
| 3888 | @item force_autohint |
| 3889 | @item crop_bitmap |
| 3890 | @item pedantic |
| 3891 | @item ignore_global_advance_width |
| 3892 | @item no_recurse |
| 3893 | @item ignore_transform |
| 3894 | @item monochrome |
| 3895 | @item linear_design |
| 3896 | @item no_autohint |
| 3897 | @end table |
| 3898 | |
| 3899 | Default value is "default". |
| 3900 | |
| 3901 | For more information consult the documentation for the FT_LOAD_* |
| 3902 | libfreetype flags. |
| 3903 | |
| 3904 | @item shadowcolor |
| 3905 | The color to be used for drawing a shadow behind the drawn text. For the |
| 3906 | syntax of this option, check the "Color" section in the ffmpeg-utils manual. |
| 3907 | |
| 3908 | The default value of @var{shadowcolor} is "black". |
| 3909 | |
| 3910 | @item shadowx |
| 3911 | @item shadowy |
| 3912 | The x and y offsets for the text shadow position with respect to the |
| 3913 | position of the text. They can be either positive or negative |
| 3914 | values. The default value for both is "0". |
| 3915 | |
| 3916 | @item start_number |
| 3917 | The starting frame number for the n/frame_num variable. The default value |
| 3918 | is "0". |
| 3919 | |
| 3920 | @item tabsize |
| 3921 | The size in number of spaces to use for rendering the tab. |
| 3922 | Default value is 4. |
| 3923 | |
| 3924 | @item timecode |
| 3925 | Set the initial timecode representation in "hh:mm:ss[:;.]ff" |
| 3926 | format. It can be used with or without text parameter. @var{timecode_rate} |
| 3927 | option must be specified. |
| 3928 | |
| 3929 | @item timecode_rate, rate, r |
| 3930 | Set the timecode frame rate (timecode only). |
| 3931 | |
| 3932 | @item text |
| 3933 | The text string to be drawn. The text must be a sequence of UTF-8 |
| 3934 | encoded characters. |
| 3935 | This parameter is mandatory if no file is specified with the parameter |
| 3936 | @var{textfile}. |
| 3937 | |
| 3938 | @item textfile |
| 3939 | A text file containing text to be drawn. The text must be a sequence |
| 3940 | of UTF-8 encoded characters. |
| 3941 | |
| 3942 | This parameter is mandatory if no text string is specified with the |
| 3943 | parameter @var{text}. |
| 3944 | |
| 3945 | If both @var{text} and @var{textfile} are specified, an error is thrown. |
| 3946 | |
| 3947 | @item reload |
| 3948 | If set to 1, the @var{textfile} will be reloaded before each frame. |
| 3949 | Be sure to update it atomically, or it may be read partially, or even fail. |
| 3950 | |
| 3951 | @item x |
| 3952 | @item y |
| 3953 | The expressions which specify the offsets where text will be drawn |
| 3954 | within the video frame. They are relative to the top/left border of the |
| 3955 | output image. |
| 3956 | |
| 3957 | The default value of @var{x} and @var{y} is "0". |
| 3958 | |
| 3959 | See below for the list of accepted constants and functions. |
| 3960 | @end table |
| 3961 | |
| 3962 | The parameters for @var{x} and @var{y} are expressions containing the |
| 3963 | following constants and functions: |
| 3964 | |
| 3965 | @table @option |
| 3966 | @item dar |
| 3967 | input display aspect ratio, it is the same as (@var{w} / @var{h}) * @var{sar} |
| 3968 | |
| 3969 | @item hsub |
| 3970 | @item vsub |
| 3971 | horizontal and vertical chroma subsample values. For example for the |
| 3972 | pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1. |
| 3973 | |
| 3974 | @item line_h, lh |
| 3975 | the height of each text line |
| 3976 | |
| 3977 | @item main_h, h, H |
| 3978 | the input height |
| 3979 | |
| 3980 | @item main_w, w, W |
| 3981 | the input width |
| 3982 | |
| 3983 | @item max_glyph_a, ascent |
| 3984 | the maximum distance from the baseline to the highest/upper grid |
| 3985 | coordinate used to place a glyph outline point, for all the rendered |
| 3986 | glyphs. |
| 3987 | It is a positive value, due to the grid's orientation with the Y axis |
| 3988 | upwards. |
| 3989 | |
| 3990 | @item max_glyph_d, descent |
| 3991 | the maximum distance from the baseline to the lowest grid coordinate |
| 3992 | used to place a glyph outline point, for all the rendered glyphs. |
| 3993 | This is a negative value, due to the grid's orientation, with the Y axis |
| 3994 | upwards. |
| 3995 | |
| 3996 | @item max_glyph_h |
| 3997 | maximum glyph height, that is the maximum height for all the glyphs |
| 3998 | contained in the rendered text, it is equivalent to @var{ascent} - |
| 3999 | @var{descent}. |
| 4000 | |
| 4001 | @item max_glyph_w |
| 4002 | maximum glyph width, that is the maximum width for all the glyphs |
| 4003 | contained in the rendered text |
| 4004 | |
| 4005 | @item n |
| 4006 | the number of input frame, starting from 0 |
| 4007 | |
| 4008 | @item rand(min, max) |
| 4009 | return a random number included between @var{min} and @var{max} |
| 4010 | |
| 4011 | @item sar |
| 4012 | The input sample aspect ratio. |
| 4013 | |
| 4014 | @item t |
| 4015 | timestamp expressed in seconds, NAN if the input timestamp is unknown |
| 4016 | |
| 4017 | @item text_h, th |
| 4018 | the height of the rendered text |
| 4019 | |
| 4020 | @item text_w, tw |
| 4021 | the width of the rendered text |
| 4022 | |
| 4023 | @item x |
| 4024 | @item y |
| 4025 | the x and y offset coordinates where the text is drawn. |
| 4026 | |
| 4027 | These parameters allow the @var{x} and @var{y} expressions to refer |
| 4028 | each other, so you can for example specify @code{y=x/dar}. |
| 4029 | @end table |
| 4030 | |
| 4031 | @anchor{drawtext_expansion} |
| 4032 | @subsection Text expansion |
| 4033 | |
| 4034 | If @option{expansion} is set to @code{strftime}, |
| 4035 | the filter recognizes strftime() sequences in the provided text and |
| 4036 | expands them accordingly. Check the documentation of strftime(). This |
| 4037 | feature is deprecated. |
| 4038 | |
| 4039 | If @option{expansion} is set to @code{none}, the text is printed verbatim. |
| 4040 | |
| 4041 | If @option{expansion} is set to @code{normal} (which is the default), |
| 4042 | the following expansion mechanism is used. |
| 4043 | |
| 4044 | The backslash character '\', followed by any character, always expands to |
| 4045 | the second character. |
| 4046 | |
| 4047 | Sequence of the form @code{%@{...@}} are expanded. The text between the |
| 4048 | braces is a function name, possibly followed by arguments separated by ':'. |
| 4049 | If the arguments contain special characters or delimiters (':' or '@}'), |
| 4050 | they should be escaped. |
| 4051 | |
| 4052 | Note that they probably must also be escaped as the value for the |
| 4053 | @option{text} option in the filter argument string and as the filter |
| 4054 | argument in the filtergraph description, and possibly also for the shell, |
| 4055 | that makes up to four levels of escaping; using a text file avoids these |
| 4056 | problems. |
| 4057 | |
| 4058 | The following functions are available: |
| 4059 | |
| 4060 | @table @command |
| 4061 | |
| 4062 | @item expr, e |
| 4063 | The expression evaluation result. |
| 4064 | |
| 4065 | It must take one argument specifying the expression to be evaluated, |
| 4066 | which accepts the same constants and functions as the @var{x} and |
| 4067 | @var{y} values. Note that not all constants should be used, for |
| 4068 | example the text size is not known when evaluating the expression, so |
| 4069 | the constants @var{text_w} and @var{text_h} will have an undefined |
| 4070 | value. |
| 4071 | |
| 4072 | @item expr_int_format, eif |
| 4073 | Evaluate the expression's value and output as formatted integer. |
| 4074 | |
| 4075 | The first argument is the expression to be evaluated, just as for the @var{expr} function. |
| 4076 | The second argument specifies the output format. Allowed values are 'x', 'X', 'd' and |
| 4077 | 'u'. They are treated exactly as in the printf function. |
| 4078 | The third parameter is optional and sets the number of positions taken by the output. |
| 4079 | It can be used to add padding with zeros from the left. |
| 4080 | |
| 4081 | @item gmtime |
| 4082 | The time at which the filter is running, expressed in UTC. |
| 4083 | It can accept an argument: a strftime() format string. |
| 4084 | |
| 4085 | @item localtime |
| 4086 | The time at which the filter is running, expressed in the local time zone. |
| 4087 | It can accept an argument: a strftime() format string. |
| 4088 | |
| 4089 | @item metadata |
| 4090 | Frame metadata. It must take one argument specifying metadata key. |
| 4091 | |
| 4092 | @item n, frame_num |
| 4093 | The frame number, starting from 0. |
| 4094 | |
| 4095 | @item pict_type |
| 4096 | A 1 character description of the current picture type. |
| 4097 | |
| 4098 | @item pts |
| 4099 | The timestamp of the current frame. |
| 4100 | It can take up to two arguments. |
| 4101 | |
| 4102 | The first argument is the format of the timestamp; it defaults to @code{flt} |
| 4103 | for seconds as a decimal number with microsecond accuracy; @code{hms} stands |
| 4104 | for a formatted @var{[-]HH:MM:SS.mmm} timestamp with millisecond accuracy. |
| 4105 | |
| 4106 | The second argument is an offset added to the timestamp. |
| 4107 | |
| 4108 | @end table |
| 4109 | |
| 4110 | @subsection Examples |
| 4111 | |
| 4112 | @itemize |
| 4113 | @item |
| 4114 | Draw "Test Text" with font FreeSerif, using the default values for the |
| 4115 | optional parameters. |
| 4116 | |
| 4117 | @example |
| 4118 | drawtext="fontfile=/usr/share/fonts/truetype/freefont/FreeSerif.ttf: text='Test Text'" |
| 4119 | @end example |
| 4120 | |
| 4121 | @item |
| 4122 | Draw 'Test Text' with font FreeSerif of size 24 at position x=100 |
| 4123 | and y=50 (counting from the top-left corner of the screen), text is |
| 4124 | yellow with a red box around it. Both the text and the box have an |
| 4125 | opacity of 20%. |
| 4126 | |
| 4127 | @example |
| 4128 | drawtext="fontfile=/usr/share/fonts/truetype/freefont/FreeSerif.ttf: text='Test Text':\ |
| 4129 | x=100: y=50: fontsize=24: fontcolor=yellow@@0.2: box=1: boxcolor=red@@0.2" |
| 4130 | @end example |
| 4131 | |
| 4132 | Note that the double quotes are not necessary if spaces are not used |
| 4133 | within the parameter list. |
| 4134 | |
| 4135 | @item |
| 4136 | Show the text at the center of the video frame: |
| 4137 | @example |
| 4138 | drawtext="fontsize=30:fontfile=FreeSerif.ttf:text='hello world':x=(w-text_w)/2:y=(h-text_h-line_h)/2" |
| 4139 | @end example |
| 4140 | |
| 4141 | @item |
| 4142 | Show a text line sliding from right to left in the last row of the video |
| 4143 | frame. The file @file{LONG_LINE} is assumed to contain a single line |
| 4144 | with no newlines. |
| 4145 | @example |
| 4146 | drawtext="fontsize=15:fontfile=FreeSerif.ttf:text=LONG_LINE:y=h-line_h:x=-50*t" |
| 4147 | @end example |
| 4148 | |
| 4149 | @item |
| 4150 | Show the content of file @file{CREDITS} off the bottom of the frame and scroll up. |
| 4151 | @example |
| 4152 | drawtext="fontsize=20:fontfile=FreeSerif.ttf:textfile=CREDITS:y=h-20*t" |
| 4153 | @end example |
| 4154 | |
| 4155 | @item |
| 4156 | Draw a single green letter "g", at the center of the input video. |
| 4157 | The glyph baseline is placed at half screen height. |
| 4158 | @example |
| 4159 | drawtext="fontsize=60:fontfile=FreeSerif.ttf:fontcolor=green:text=g:x=(w-max_glyph_w)/2:y=h/2-ascent" |
| 4160 | @end example |
| 4161 | |
| 4162 | @item |
| 4163 | Show text for 1 second every 3 seconds: |
| 4164 | @example |
| 4165 | drawtext="fontfile=FreeSerif.ttf:fontcolor=white:x=100:y=x/dar:enable=lt(mod(t\,3)\,1):text='blink'" |
| 4166 | @end example |
| 4167 | |
| 4168 | @item |
| 4169 | Use fontconfig to set the font. Note that the colons need to be escaped. |
| 4170 | @example |
| 4171 | drawtext='fontfile=Linux Libertine O-40\:style=Semibold:text=FFmpeg' |
| 4172 | @end example |
| 4173 | |
| 4174 | @item |
| 4175 | Print the date of a real-time encoding (see strftime(3)): |
| 4176 | @example |
| 4177 | drawtext='fontfile=FreeSans.ttf:text=%@{localtime\:%a %b %d %Y@}' |
| 4178 | @end example |
| 4179 | |
| 4180 | @item |
| 4181 | Show text fading in and out (appearing/disappearing): |
| 4182 | @example |
| 4183 | #!/bin/sh |
| 4184 | DS=1.0 # display start |
| 4185 | DE=10.0 # display end |
| 4186 | FID=1.5 # fade in duration |
| 4187 | FOD=5 # fade out duration |
| 4188 | ffplay -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 @}" |
| 4189 | @end example |
| 4190 | |
| 4191 | @end itemize |
| 4192 | |
| 4193 | For more information about libfreetype, check: |
| 4194 | @url{http://www.freetype.org/}. |
| 4195 | |
| 4196 | For more information about fontconfig, check: |
| 4197 | @url{http://freedesktop.org/software/fontconfig/fontconfig-user.html}. |
| 4198 | |
| 4199 | For more information about libfribidi, check: |
| 4200 | @url{http://fribidi.org/}. |
| 4201 | |
| 4202 | @section edgedetect |
| 4203 | |
| 4204 | Detect and draw edges. The filter uses the Canny Edge Detection algorithm. |
| 4205 | |
| 4206 | The filter accepts the following options: |
| 4207 | |
| 4208 | @table @option |
| 4209 | @item low |
| 4210 | @item high |
| 4211 | Set low and high threshold values used by the Canny thresholding |
| 4212 | algorithm. |
| 4213 | |
| 4214 | The high threshold selects the "strong" edge pixels, which are then |
| 4215 | connected through 8-connectivity with the "weak" edge pixels selected |
| 4216 | by the low threshold. |
| 4217 | |
| 4218 | @var{low} and @var{high} threshold values must be chosen in the range |
| 4219 | [0,1], and @var{low} should be lesser or equal to @var{high}. |
| 4220 | |
| 4221 | Default value for @var{low} is @code{20/255}, and default value for @var{high} |
| 4222 | is @code{50/255}. |
| 4223 | |
| 4224 | @item mode |
| 4225 | Define the drawing mode. |
| 4226 | |
| 4227 | @table @samp |
| 4228 | @item wires |
| 4229 | Draw white/gray wires on black background. |
| 4230 | |
| 4231 | @item colormix |
| 4232 | Mix the colors to create a paint/cartoon effect. |
| 4233 | @end table |
| 4234 | |
| 4235 | Default value is @var{wires}. |
| 4236 | @end table |
| 4237 | |
| 4238 | @subsection Examples |
| 4239 | |
| 4240 | @itemize |
| 4241 | @item |
| 4242 | Standard edge detection with custom values for the hysteresis thresholding: |
| 4243 | @example |
| 4244 | edgedetect=low=0.1:high=0.4 |
| 4245 | @end example |
| 4246 | |
| 4247 | @item |
| 4248 | Painting effect without thresholding: |
| 4249 | @example |
| 4250 | edgedetect=mode=colormix:high=0 |
| 4251 | @end example |
| 4252 | @end itemize |
| 4253 | |
| 4254 | @section extractplanes |
| 4255 | |
| 4256 | Extract color channel components from input video stream into |
| 4257 | separate grayscale video streams. |
| 4258 | |
| 4259 | The filter accepts the following option: |
| 4260 | |
| 4261 | @table @option |
| 4262 | @item planes |
| 4263 | Set plane(s) to extract. |
| 4264 | |
| 4265 | Available values for planes are: |
| 4266 | @table @samp |
| 4267 | @item y |
| 4268 | @item u |
| 4269 | @item v |
| 4270 | @item a |
| 4271 | @item r |
| 4272 | @item g |
| 4273 | @item b |
| 4274 | @end table |
| 4275 | |
| 4276 | Choosing planes not available in the input will result in an error. |
| 4277 | That means you cannot select @code{r}, @code{g}, @code{b} planes |
| 4278 | with @code{y}, @code{u}, @code{v} planes at same time. |
| 4279 | @end table |
| 4280 | |
| 4281 | @subsection Examples |
| 4282 | |
| 4283 | @itemize |
| 4284 | @item |
| 4285 | Extract luma, u and v color channel component from input video frame |
| 4286 | into 3 grayscale outputs: |
| 4287 | @example |
| 4288 | ffmpeg -i video.avi -filter_complex 'extractplanes=y+u+v[y][u][v]' -map '[y]' y.avi -map '[u]' u.avi -map '[v]' v.avi |
| 4289 | @end example |
| 4290 | @end itemize |
| 4291 | |
| 4292 | @section elbg |
| 4293 | |
| 4294 | Apply a posterize effect using the ELBG (Enhanced LBG) algorithm. |
| 4295 | |
| 4296 | For each input image, the filter will compute the optimal mapping from |
| 4297 | the input to the output given the codebook length, that is the number |
| 4298 | of distinct output colors. |
| 4299 | |
| 4300 | This filter accepts the following options. |
| 4301 | |
| 4302 | @table @option |
| 4303 | @item codebook_length, l |
| 4304 | Set codebook length. The value must be a positive integer, and |
| 4305 | represents the number of distinct output colors. Default value is 256. |
| 4306 | |
| 4307 | @item nb_steps, n |
| 4308 | Set the maximum number of iterations to apply for computing the optimal |
| 4309 | mapping. The higher the value the better the result and the higher the |
| 4310 | computation time. Default value is 1. |
| 4311 | |
| 4312 | @item seed, s |
| 4313 | Set a random seed, must be an integer included between 0 and |
| 4314 | UINT32_MAX. If not specified, or if explicitly set to -1, the filter |
| 4315 | will try to use a good random seed on a best effort basis. |
| 4316 | @end table |
| 4317 | |
| 4318 | @section fade |
| 4319 | |
| 4320 | Apply a fade-in/out effect to the input video. |
| 4321 | |
| 4322 | It accepts the following parameters: |
| 4323 | |
| 4324 | @table @option |
| 4325 | @item type, t |
| 4326 | The effect type can be either "in" for a fade-in, or "out" for a fade-out |
| 4327 | effect. |
| 4328 | Default is @code{in}. |
| 4329 | |
| 4330 | @item start_frame, s |
| 4331 | Specify the number of the frame to start applying the fade |
| 4332 | effect at. Default is 0. |
| 4333 | |
| 4334 | @item nb_frames, n |
| 4335 | The number of frames that the fade effect lasts. At the end of the |
| 4336 | fade-in effect, the output video will have the same intensity as the input video. |
| 4337 | At the end of the fade-out transition, the output video will be filled with the |
| 4338 | selected @option{color}. |
| 4339 | Default is 25. |
| 4340 | |
| 4341 | @item alpha |
| 4342 | If set to 1, fade only alpha channel, if one exists on the input. |
| 4343 | Default value is 0. |
| 4344 | |
| 4345 | @item start_time, st |
| 4346 | Specify the timestamp (in seconds) of the frame to start to apply the fade |
| 4347 | effect. If both start_frame and start_time are specified, the fade will start at |
| 4348 | whichever comes last. Default is 0. |
| 4349 | |
| 4350 | @item duration, d |
| 4351 | The number of seconds for which the fade effect has to last. At the end of the |
| 4352 | fade-in effect the output video will have the same intensity as the input video, |
| 4353 | at the end of the fade-out transition the output video will be filled with the |
| 4354 | selected @option{color}. |
| 4355 | If both duration and nb_frames are specified, duration is used. Default is 0. |
| 4356 | |
| 4357 | @item color, c |
| 4358 | Specify the color of the fade. Default is "black". |
| 4359 | @end table |
| 4360 | |
| 4361 | @subsection Examples |
| 4362 | |
| 4363 | @itemize |
| 4364 | @item |
| 4365 | Fade in the first 30 frames of video: |
| 4366 | @example |
| 4367 | fade=in:0:30 |
| 4368 | @end example |
| 4369 | |
| 4370 | The command above is equivalent to: |
| 4371 | @example |
| 4372 | fade=t=in:s=0:n=30 |
| 4373 | @end example |
| 4374 | |
| 4375 | @item |
| 4376 | Fade out the last 45 frames of a 200-frame video: |
| 4377 | @example |
| 4378 | fade=out:155:45 |
| 4379 | fade=type=out:start_frame=155:nb_frames=45 |
| 4380 | @end example |
| 4381 | |
| 4382 | @item |
| 4383 | Fade in the first 25 frames and fade out the last 25 frames of a 1000-frame video: |
| 4384 | @example |
| 4385 | fade=in:0:25, fade=out:975:25 |
| 4386 | @end example |
| 4387 | |
| 4388 | @item |
| 4389 | Make the first 5 frames yellow, then fade in from frame 5-24: |
| 4390 | @example |
| 4391 | fade=in:5:20:color=yellow |
| 4392 | @end example |
| 4393 | |
| 4394 | @item |
| 4395 | Fade in alpha over first 25 frames of video: |
| 4396 | @example |
| 4397 | fade=in:0:25:alpha=1 |
| 4398 | @end example |
| 4399 | |
| 4400 | @item |
| 4401 | Make the first 5.5 seconds black, then fade in for 0.5 seconds: |
| 4402 | @example |
| 4403 | fade=t=in:st=5.5:d=0.5 |
| 4404 | @end example |
| 4405 | |
| 4406 | @end itemize |
| 4407 | |
| 4408 | @section field |
| 4409 | |
| 4410 | Extract a single field from an interlaced image using stride |
| 4411 | arithmetic to avoid wasting CPU time. The output frames are marked as |
| 4412 | non-interlaced. |
| 4413 | |
| 4414 | The filter accepts the following options: |
| 4415 | |
| 4416 | @table @option |
| 4417 | @item type |
| 4418 | Specify whether to extract the top (if the value is @code{0} or |
| 4419 | @code{top}) or the bottom field (if the value is @code{1} or |
| 4420 | @code{bottom}). |
| 4421 | @end table |
| 4422 | |
| 4423 | @section fieldmatch |
| 4424 | |
| 4425 | Field matching filter for inverse telecine. It is meant to reconstruct the |
| 4426 | progressive frames from a telecined stream. The filter does not drop duplicated |
| 4427 | frames, so to achieve a complete inverse telecine @code{fieldmatch} needs to be |
| 4428 | followed by a decimation filter such as @ref{decimate} in the filtergraph. |
| 4429 | |
| 4430 | The separation of the field matching and the decimation is notably motivated by |
| 4431 | the possibility of inserting a de-interlacing filter fallback between the two. |
| 4432 | If the source has mixed telecined and real interlaced content, |
| 4433 | @code{fieldmatch} will not be able to match fields for the interlaced parts. |
| 4434 | But these remaining combed frames will be marked as interlaced, and thus can be |
| 4435 | de-interlaced by a later filter such as @ref{yadif} before decimation. |
| 4436 | |
| 4437 | In addition to the various configuration options, @code{fieldmatch} can take an |
| 4438 | optional second stream, activated through the @option{ppsrc} option. If |
| 4439 | enabled, the frames reconstruction will be based on the fields and frames from |
| 4440 | this second stream. This allows the first input to be pre-processed in order to |
| 4441 | help the various algorithms of the filter, while keeping the output lossless |
| 4442 | (assuming the fields are matched properly). Typically, a field-aware denoiser, |
| 4443 | or brightness/contrast adjustments can help. |
| 4444 | |
| 4445 | Note that this filter uses the same algorithms as TIVTC/TFM (AviSynth project) |
| 4446 | and VIVTC/VFM (VapourSynth project). The later is a light clone of TFM from |
| 4447 | which @code{fieldmatch} is based on. While the semantic and usage are very |
| 4448 | close, some behaviour and options names can differ. |
| 4449 | |
| 4450 | The @ref{decimate} filter currently only works for constant frame rate input. |
| 4451 | Do not use @code{fieldmatch} and @ref{decimate} if your input has mixed |
| 4452 | telecined and progressive content with changing framerate. |
| 4453 | |
| 4454 | The filter accepts the following options: |
| 4455 | |
| 4456 | @table @option |
| 4457 | @item order |
| 4458 | Specify the assumed field order of the input stream. Available values are: |
| 4459 | |
| 4460 | @table @samp |
| 4461 | @item auto |
| 4462 | Auto detect parity (use FFmpeg's internal parity value). |
| 4463 | @item bff |
| 4464 | Assume bottom field first. |
| 4465 | @item tff |
| 4466 | Assume top field first. |
| 4467 | @end table |
| 4468 | |
| 4469 | Note that it is sometimes recommended not to trust the parity announced by the |
| 4470 | stream. |
| 4471 | |
| 4472 | Default value is @var{auto}. |
| 4473 | |
| 4474 | @item mode |
| 4475 | Set the matching mode or strategy to use. @option{pc} mode is the safest in the |
| 4476 | sense that it won't risk creating jerkiness due to duplicate frames when |
| 4477 | possible, but if there are bad edits or blended fields it will end up |
| 4478 | outputting combed frames when a good match might actually exist. On the other |
| 4479 | hand, @option{pcn_ub} mode is the most risky in terms of creating jerkiness, |
| 4480 | but will almost always find a good frame if there is one. The other values are |
| 4481 | all somewhere in between @option{pc} and @option{pcn_ub} in terms of risking |
| 4482 | jerkiness and creating duplicate frames versus finding good matches in sections |
| 4483 | with bad edits, orphaned fields, blended fields, etc. |
| 4484 | |
| 4485 | More details about p/c/n/u/b are available in @ref{p/c/n/u/b meaning} section. |
| 4486 | |
| 4487 | Available values are: |
| 4488 | |
| 4489 | @table @samp |
| 4490 | @item pc |
| 4491 | 2-way matching (p/c) |
| 4492 | @item pc_n |
| 4493 | 2-way matching, and trying 3rd match if still combed (p/c + n) |
| 4494 | @item pc_u |
| 4495 | 2-way matching, and trying 3rd match (same order) if still combed (p/c + u) |
| 4496 | @item pc_n_ub |
| 4497 | 2-way matching, trying 3rd match if still combed, and trying 4th/5th matches if |
| 4498 | still combed (p/c + n + u/b) |
| 4499 | @item pcn |
| 4500 | 3-way matching (p/c/n) |
| 4501 | @item pcn_ub |
| 4502 | 3-way matching, and trying 4th/5th matches if all 3 of the original matches are |
| 4503 | detected as combed (p/c/n + u/b) |
| 4504 | @end table |
| 4505 | |
| 4506 | The parenthesis at the end indicate the matches that would be used for that |
| 4507 | mode assuming @option{order}=@var{tff} (and @option{field} on @var{auto} or |
| 4508 | @var{top}). |
| 4509 | |
| 4510 | In terms of speed @option{pc} mode is by far the fastest and @option{pcn_ub} is |
| 4511 | the slowest. |
| 4512 | |
| 4513 | Default value is @var{pc_n}. |
| 4514 | |
| 4515 | @item ppsrc |
| 4516 | Mark the main input stream as a pre-processed input, and enable the secondary |
| 4517 | input stream as the clean source to pick the fields from. See the filter |
| 4518 | introduction for more details. It is similar to the @option{clip2} feature from |
| 4519 | VFM/TFM. |
| 4520 | |
| 4521 | Default value is @code{0} (disabled). |
| 4522 | |
| 4523 | @item field |
| 4524 | Set the field to match from. It is recommended to set this to the same value as |
| 4525 | @option{order} unless you experience matching failures with that setting. In |
| 4526 | certain circumstances changing the field that is used to match from can have a |
| 4527 | large impact on matching performance. Available values are: |
| 4528 | |
| 4529 | @table @samp |
| 4530 | @item auto |
| 4531 | Automatic (same value as @option{order}). |
| 4532 | @item bottom |
| 4533 | Match from the bottom field. |
| 4534 | @item top |
| 4535 | Match from the top field. |
| 4536 | @end table |
| 4537 | |
| 4538 | Default value is @var{auto}. |
| 4539 | |
| 4540 | @item mchroma |
| 4541 | Set whether or not chroma is included during the match comparisons. In most |
| 4542 | cases it is recommended to leave this enabled. You should set this to @code{0} |
| 4543 | only if your clip has bad chroma problems such as heavy rainbowing or other |
| 4544 | artifacts. Setting this to @code{0} could also be used to speed things up at |
| 4545 | the cost of some accuracy. |
| 4546 | |
| 4547 | Default value is @code{1}. |
| 4548 | |
| 4549 | @item y0 |
| 4550 | @item y1 |
| 4551 | These define an exclusion band which excludes the lines between @option{y0} and |
| 4552 | @option{y1} from being included in the field matching decision. An exclusion |
| 4553 | band can be used to ignore subtitles, a logo, or other things that may |
| 4554 | interfere with the matching. @option{y0} sets the starting scan line and |
| 4555 | @option{y1} sets the ending line; all lines in between @option{y0} and |
| 4556 | @option{y1} (including @option{y0} and @option{y1}) will be ignored. Setting |
| 4557 | @option{y0} and @option{y1} to the same value will disable the feature. |
| 4558 | @option{y0} and @option{y1} defaults to @code{0}. |
| 4559 | |
| 4560 | @item scthresh |
| 4561 | Set the scene change detection threshold as a percentage of maximum change on |
| 4562 | the luma plane. Good values are in the @code{[8.0, 14.0]} range. Scene change |
| 4563 | detection is only relevant in case @option{combmatch}=@var{sc}. The range for |
| 4564 | @option{scthresh} is @code{[0.0, 100.0]}. |
| 4565 | |
| 4566 | Default value is @code{12.0}. |
| 4567 | |
| 4568 | @item combmatch |
| 4569 | When @option{combatch} is not @var{none}, @code{fieldmatch} will take into |
| 4570 | account the combed scores of matches when deciding what match to use as the |
| 4571 | final match. Available values are: |
| 4572 | |
| 4573 | @table @samp |
| 4574 | @item none |
| 4575 | No final matching based on combed scores. |
| 4576 | @item sc |
| 4577 | Combed scores are only used when a scene change is detected. |
| 4578 | @item full |
| 4579 | Use combed scores all the time. |
| 4580 | @end table |
| 4581 | |
| 4582 | Default is @var{sc}. |
| 4583 | |
| 4584 | @item combdbg |
| 4585 | Force @code{fieldmatch} to calculate the combed metrics for certain matches and |
| 4586 | print them. This setting is known as @option{micout} in TFM/VFM vocabulary. |
| 4587 | Available values are: |
| 4588 | |
| 4589 | @table @samp |
| 4590 | @item none |
| 4591 | No forced calculation. |
| 4592 | @item pcn |
| 4593 | Force p/c/n calculations. |
| 4594 | @item pcnub |
| 4595 | Force p/c/n/u/b calculations. |
| 4596 | @end table |
| 4597 | |
| 4598 | Default value is @var{none}. |
| 4599 | |
| 4600 | @item cthresh |
| 4601 | This is the area combing threshold used for combed frame detection. This |
| 4602 | essentially controls how "strong" or "visible" combing must be to be detected. |
| 4603 | Larger values mean combing must be more visible and smaller values mean combing |
| 4604 | can be less visible or strong and still be detected. Valid settings are from |
| 4605 | @code{-1} (every pixel will be detected as combed) to @code{255} (no pixel will |
| 4606 | be detected as combed). This is basically a pixel difference value. A good |
| 4607 | range is @code{[8, 12]}. |
| 4608 | |
| 4609 | Default value is @code{9}. |
| 4610 | |
| 4611 | @item chroma |
| 4612 | Sets whether or not chroma is considered in the combed frame decision. Only |
| 4613 | disable this if your source has chroma problems (rainbowing, etc.) that are |
| 4614 | causing problems for the combed frame detection with chroma enabled. Actually, |
| 4615 | using @option{chroma}=@var{0} is usually more reliable, except for the case |
| 4616 | where there is chroma only combing in the source. |
| 4617 | |
| 4618 | Default value is @code{0}. |
| 4619 | |
| 4620 | @item blockx |
| 4621 | @item blocky |
| 4622 | Respectively set the x-axis and y-axis size of the window used during combed |
| 4623 | frame detection. This has to do with the size of the area in which |
| 4624 | @option{combpel} pixels are required to be detected as combed for a frame to be |
| 4625 | declared combed. See the @option{combpel} parameter description for more info. |
| 4626 | Possible values are any number that is a power of 2 starting at 4 and going up |
| 4627 | to 512. |
| 4628 | |
| 4629 | Default value is @code{16}. |
| 4630 | |
| 4631 | @item combpel |
| 4632 | The number of combed pixels inside any of the @option{blocky} by |
| 4633 | @option{blockx} size blocks on the frame for the frame to be detected as |
| 4634 | combed. While @option{cthresh} controls how "visible" the combing must be, this |
| 4635 | setting controls "how much" combing there must be in any localized area (a |
| 4636 | window defined by the @option{blockx} and @option{blocky} settings) on the |
| 4637 | frame. Minimum value is @code{0} and maximum is @code{blocky x blockx} (at |
| 4638 | which point no frames will ever be detected as combed). This setting is known |
| 4639 | as @option{MI} in TFM/VFM vocabulary. |
| 4640 | |
| 4641 | Default value is @code{80}. |
| 4642 | @end table |
| 4643 | |
| 4644 | @anchor{p/c/n/u/b meaning} |
| 4645 | @subsection p/c/n/u/b meaning |
| 4646 | |
| 4647 | @subsubsection p/c/n |
| 4648 | |
| 4649 | We assume the following telecined stream: |
| 4650 | |
| 4651 | @example |
| 4652 | Top fields: 1 2 2 3 4 |
| 4653 | Bottom fields: 1 2 3 4 4 |
| 4654 | @end example |
| 4655 | |
| 4656 | The numbers correspond to the progressive frame the fields relate to. Here, the |
| 4657 | first two frames are progressive, the 3rd and 4th are combed, and so on. |
| 4658 | |
| 4659 | When @code{fieldmatch} is configured to run a matching from bottom |
| 4660 | (@option{field}=@var{bottom}) this is how this input stream get transformed: |
| 4661 | |
| 4662 | @example |
| 4663 | Input stream: |
| 4664 | T 1 2 2 3 4 |
| 4665 | B 1 2 3 4 4 <-- matching reference |
| 4666 | |
| 4667 | Matches: c c n n c |
| 4668 | |
| 4669 | Output stream: |
| 4670 | T 1 2 3 4 4 |
| 4671 | B 1 2 3 4 4 |
| 4672 | @end example |
| 4673 | |
| 4674 | As a result of the field matching, we can see that some frames get duplicated. |
| 4675 | To perform a complete inverse telecine, you need to rely on a decimation filter |
| 4676 | after this operation. See for instance the @ref{decimate} filter. |
| 4677 | |
| 4678 | The same operation now matching from top fields (@option{field}=@var{top}) |
| 4679 | looks like this: |
| 4680 | |
| 4681 | @example |
| 4682 | Input stream: |
| 4683 | T 1 2 2 3 4 <-- matching reference |
| 4684 | B 1 2 3 4 4 |
| 4685 | |
| 4686 | Matches: c c p p c |
| 4687 | |
| 4688 | Output stream: |
| 4689 | T 1 2 2 3 4 |
| 4690 | B 1 2 2 3 4 |
| 4691 | @end example |
| 4692 | |
| 4693 | In these examples, we can see what @var{p}, @var{c} and @var{n} mean; |
| 4694 | basically, they refer to the frame and field of the opposite parity: |
| 4695 | |
| 4696 | @itemize |
| 4697 | @item @var{p} matches the field of the opposite parity in the previous frame |
| 4698 | @item @var{c} matches the field of the opposite parity in the current frame |
| 4699 | @item @var{n} matches the field of the opposite parity in the next frame |
| 4700 | @end itemize |
| 4701 | |
| 4702 | @subsubsection u/b |
| 4703 | |
| 4704 | The @var{u} and @var{b} matching are a bit special in the sense that they match |
| 4705 | from the opposite parity flag. In the following examples, we assume that we are |
| 4706 | currently matching the 2nd frame (Top:2, bottom:2). According to the match, a |
| 4707 | 'x' is placed above and below each matched fields. |
| 4708 | |
| 4709 | With bottom matching (@option{field}=@var{bottom}): |
| 4710 | @example |
| 4711 | Match: c p n b u |
| 4712 | |
| 4713 | x x x x x |
| 4714 | Top 1 2 2 1 2 2 1 2 2 1 2 2 1 2 2 |
| 4715 | Bottom 1 2 3 1 2 3 1 2 3 1 2 3 1 2 3 |
| 4716 | x x x x x |
| 4717 | |
| 4718 | Output frames: |
| 4719 | 2 1 2 2 2 |
| 4720 | 2 2 2 1 3 |
| 4721 | @end example |
| 4722 | |
| 4723 | With top matching (@option{field}=@var{top}): |
| 4724 | @example |
| 4725 | Match: c p n b u |
| 4726 | |
| 4727 | x x x x x |
| 4728 | Top 1 2 2 1 2 2 1 2 2 1 2 2 1 2 2 |
| 4729 | Bottom 1 2 3 1 2 3 1 2 3 1 2 3 1 2 3 |
| 4730 | x x x x x |
| 4731 | |
| 4732 | Output frames: |
| 4733 | 2 2 2 1 2 |
| 4734 | 2 1 3 2 2 |
| 4735 | @end example |
| 4736 | |
| 4737 | @subsection Examples |
| 4738 | |
| 4739 | Simple IVTC of a top field first telecined stream: |
| 4740 | @example |
| 4741 | fieldmatch=order=tff:combmatch=none, decimate |
| 4742 | @end example |
| 4743 | |
| 4744 | Advanced IVTC, with fallback on @ref{yadif} for still combed frames: |
| 4745 | @example |
| 4746 | fieldmatch=order=tff:combmatch=full, yadif=deint=interlaced, decimate |
| 4747 | @end example |
| 4748 | |
| 4749 | @section fieldorder |
| 4750 | |
| 4751 | Transform the field order of the input video. |
| 4752 | |
| 4753 | It accepts the following parameters: |
| 4754 | |
| 4755 | @table @option |
| 4756 | |
| 4757 | @item order |
| 4758 | The output field order. Valid values are @var{tff} for top field first or @var{bff} |
| 4759 | for bottom field first. |
| 4760 | @end table |
| 4761 | |
| 4762 | The default value is @samp{tff}. |
| 4763 | |
| 4764 | The transformation is done by shifting the picture content up or down |
| 4765 | by one line, and filling the remaining line with appropriate picture content. |
| 4766 | This method is consistent with most broadcast field order converters. |
| 4767 | |
| 4768 | If the input video is not flagged as being interlaced, or it is already |
| 4769 | flagged as being of the required output field order, then this filter does |
| 4770 | not alter the incoming video. |
| 4771 | |
| 4772 | It is very useful when converting to or from PAL DV material, |
| 4773 | which is bottom field first. |
| 4774 | |
| 4775 | For example: |
| 4776 | @example |
| 4777 | ffmpeg -i in.vob -vf "fieldorder=bff" out.dv |
| 4778 | @end example |
| 4779 | |
| 4780 | @section fifo |
| 4781 | |
| 4782 | Buffer input images and send them when they are requested. |
| 4783 | |
| 4784 | It is mainly useful when auto-inserted by the libavfilter |
| 4785 | framework. |
| 4786 | |
| 4787 | It does not take parameters. |
| 4788 | |
| 4789 | @anchor{format} |
| 4790 | @section format |
| 4791 | |
| 4792 | Convert the input video to one of the specified pixel formats. |
| 4793 | Libavfilter will try to pick one that is suitable as input to |
| 4794 | the next filter. |
| 4795 | |
| 4796 | It accepts the following parameters: |
| 4797 | @table @option |
| 4798 | |
| 4799 | @item pix_fmts |
| 4800 | A '|'-separated list of pixel format names, such as |
| 4801 | "pix_fmts=yuv420p|monow|rgb24". |
| 4802 | |
| 4803 | @end table |
| 4804 | |
| 4805 | @subsection Examples |
| 4806 | |
| 4807 | @itemize |
| 4808 | @item |
| 4809 | Convert the input video to the @var{yuv420p} format |
| 4810 | @example |
| 4811 | format=pix_fmts=yuv420p |
| 4812 | @end example |
| 4813 | |
| 4814 | Convert the input video to any of the formats in the list |
| 4815 | @example |
| 4816 | format=pix_fmts=yuv420p|yuv444p|yuv410p |
| 4817 | @end example |
| 4818 | @end itemize |
| 4819 | |
| 4820 | @anchor{fps} |
| 4821 | @section fps |
| 4822 | |
| 4823 | Convert the video to specified constant frame rate by duplicating or dropping |
| 4824 | frames as necessary. |
| 4825 | |
| 4826 | It accepts the following parameters: |
| 4827 | @table @option |
| 4828 | |
| 4829 | @item fps |
| 4830 | The desired output frame rate. The default is @code{25}. |
| 4831 | |
| 4832 | @item round |
| 4833 | Rounding method. |
| 4834 | |
| 4835 | Possible values are: |
| 4836 | @table @option |
| 4837 | @item zero |
| 4838 | zero round towards 0 |
| 4839 | @item inf |
| 4840 | round away from 0 |
| 4841 | @item down |
| 4842 | round towards -infinity |
| 4843 | @item up |
| 4844 | round towards +infinity |
| 4845 | @item near |
| 4846 | round to nearest |
| 4847 | @end table |
| 4848 | The default is @code{near}. |
| 4849 | |
| 4850 | @item start_time |
| 4851 | Assume the first PTS should be the given value, in seconds. This allows for |
| 4852 | padding/trimming at the start of stream. By default, no assumption is made |
| 4853 | about the first frame's expected PTS, so no padding or trimming is done. |
| 4854 | For example, this could be set to 0 to pad the beginning with duplicates of |
| 4855 | the first frame if a video stream starts after the audio stream or to trim any |
| 4856 | frames with a negative PTS. |
| 4857 | |
| 4858 | @end table |
| 4859 | |
| 4860 | Alternatively, the options can be specified as a flat string: |
| 4861 | @var{fps}[:@var{round}]. |
| 4862 | |
| 4863 | See also the @ref{setpts} filter. |
| 4864 | |
| 4865 | @subsection Examples |
| 4866 | |
| 4867 | @itemize |
| 4868 | @item |
| 4869 | A typical usage in order to set the fps to 25: |
| 4870 | @example |
| 4871 | fps=fps=25 |
| 4872 | @end example |
| 4873 | |
| 4874 | @item |
| 4875 | Sets the fps to 24, using abbreviation and rounding method to round to nearest: |
| 4876 | @example |
| 4877 | fps=fps=film:round=near |
| 4878 | @end example |
| 4879 | @end itemize |
| 4880 | |
| 4881 | @section framepack |
| 4882 | |
| 4883 | Pack two different video streams into a stereoscopic video, setting proper |
| 4884 | metadata on supported codecs. The two views should have the same size and |
| 4885 | framerate and processing will stop when the shorter video ends. Please note |
| 4886 | that you may conveniently adjust view properties with the @ref{scale} and |
| 4887 | @ref{fps} filters. |
| 4888 | |
| 4889 | It accepts the following parameters: |
| 4890 | @table @option |
| 4891 | |
| 4892 | @item format |
| 4893 | The desired packing format. Supported values are: |
| 4894 | |
| 4895 | @table @option |
| 4896 | |
| 4897 | @item sbs |
| 4898 | The views are next to each other (default). |
| 4899 | |
| 4900 | @item tab |
| 4901 | The views are on top of each other. |
| 4902 | |
| 4903 | @item lines |
| 4904 | The views are packed by line. |
| 4905 | |
| 4906 | @item columns |
| 4907 | The views are packed by column. |
| 4908 | |
| 4909 | @item frameseq |
| 4910 | The views are temporally interleaved. |
| 4911 | |
| 4912 | @end table |
| 4913 | |
| 4914 | @end table |
| 4915 | |
| 4916 | Some examples: |
| 4917 | |
| 4918 | @example |
| 4919 | # Convert left and right views into a frame-sequential video |
| 4920 | ffmpeg -i LEFT -i RIGHT -filter_complex framepack=frameseq OUTPUT |
| 4921 | |
| 4922 | # Convert views into a side-by-side video with the same output resolution as the input |
| 4923 | ffmpeg -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 |
| 4924 | @end example |
| 4925 | |
| 4926 | @section framestep |
| 4927 | |
| 4928 | Select one frame every N-th frame. |
| 4929 | |
| 4930 | This filter accepts the following option: |
| 4931 | @table @option |
| 4932 | @item step |
| 4933 | Select frame after every @code{step} frames. |
| 4934 | Allowed values are positive integers higher than 0. Default value is @code{1}. |
| 4935 | @end table |
| 4936 | |
| 4937 | @anchor{frei0r} |
| 4938 | @section frei0r |
| 4939 | |
| 4940 | Apply a frei0r effect to the input video. |
| 4941 | |
| 4942 | To enable the compilation of this filter, you need to install the frei0r |
| 4943 | header and configure FFmpeg with @code{--enable-frei0r}. |
| 4944 | |
| 4945 | It accepts the following parameters: |
| 4946 | |
| 4947 | @table @option |
| 4948 | |
| 4949 | @item filter_name |
| 4950 | The name of the frei0r effect to load. If the environment variable |
| 4951 | @env{FREI0R_PATH} is defined, the frei0r effect is searched for in each of the |
| 4952 | directories specified by the colon-separated list in @env{FREIOR_PATH}. |
| 4953 | Otherwise, the standard frei0r paths are searched, in this order: |
| 4954 | @file{HOME/.frei0r-1/lib/}, @file{/usr/local/lib/frei0r-1/}, |
| 4955 | @file{/usr/lib/frei0r-1/}. |
| 4956 | |
| 4957 | @item filter_params |
| 4958 | A '|'-separated list of parameters to pass to the frei0r effect. |
| 4959 | |
| 4960 | @end table |
| 4961 | |
| 4962 | A frei0r effect parameter can be a boolean (its value is either |
| 4963 | "y" or "n"), a double, a color (specified as |
| 4964 | @var{R}/@var{G}/@var{B}, where @var{R}, @var{G}, and @var{B} are floating point |
| 4965 | numbers between 0.0 and 1.0, inclusive) or by a color description specified in the "Color" |
| 4966 | section in the ffmpeg-utils manual), a position (specified as @var{X}/@var{Y}, where |
| 4967 | @var{X} and @var{Y} are floating point numbers) and/or a string. |
| 4968 | |
| 4969 | The number and types of parameters depend on the loaded effect. If an |
| 4970 | effect parameter is not specified, the default value is set. |
| 4971 | |
| 4972 | @subsection Examples |
| 4973 | |
| 4974 | @itemize |
| 4975 | @item |
| 4976 | Apply the distort0r effect, setting the first two double parameters: |
| 4977 | @example |
| 4978 | frei0r=filter_name=distort0r:filter_params=0.5|0.01 |
| 4979 | @end example |
| 4980 | |
| 4981 | @item |
| 4982 | Apply the colordistance effect, taking a color as the first parameter: |
| 4983 | @example |
| 4984 | frei0r=colordistance:0.2/0.3/0.4 |
| 4985 | frei0r=colordistance:violet |
| 4986 | frei0r=colordistance:0x112233 |
| 4987 | @end example |
| 4988 | |
| 4989 | @item |
| 4990 | Apply the perspective effect, specifying the top left and top right image |
| 4991 | positions: |
| 4992 | @example |
| 4993 | frei0r=perspective:0.2/0.2|0.8/0.2 |
| 4994 | @end example |
| 4995 | @end itemize |
| 4996 | |
| 4997 | For more information, see |
| 4998 | @url{http://frei0r.dyne.org} |
| 4999 | |
| 5000 | @section geq |
| 5001 | |
| 5002 | The filter accepts the following options: |
| 5003 | |
| 5004 | @table @option |
| 5005 | @item lum_expr, lum |
| 5006 | Set the luminance expression. |
| 5007 | @item cb_expr, cb |
| 5008 | Set the chrominance blue expression. |
| 5009 | @item cr_expr, cr |
| 5010 | Set the chrominance red expression. |
| 5011 | @item alpha_expr, a |
| 5012 | Set the alpha expression. |
| 5013 | @item red_expr, r |
| 5014 | Set the red expression. |
| 5015 | @item green_expr, g |
| 5016 | Set the green expression. |
| 5017 | @item blue_expr, b |
| 5018 | Set the blue expression. |
| 5019 | @end table |
| 5020 | |
| 5021 | The colorspace is selected according to the specified options. If one |
| 5022 | of the @option{lum_expr}, @option{cb_expr}, or @option{cr_expr} |
| 5023 | options is specified, the filter will automatically select a YCbCr |
| 5024 | colorspace. If one of the @option{red_expr}, @option{green_expr}, or |
| 5025 | @option{blue_expr} options is specified, it will select an RGB |
| 5026 | colorspace. |
| 5027 | |
| 5028 | If one of the chrominance expression is not defined, it falls back on the other |
| 5029 | one. If no alpha expression is specified it will evaluate to opaque value. |
| 5030 | If none of chrominance expressions are specified, they will evaluate |
| 5031 | to the luminance expression. |
| 5032 | |
| 5033 | The expressions can use the following variables and functions: |
| 5034 | |
| 5035 | @table @option |
| 5036 | @item N |
| 5037 | The sequential number of the filtered frame, starting from @code{0}. |
| 5038 | |
| 5039 | @item X |
| 5040 | @item Y |
| 5041 | The coordinates of the current sample. |
| 5042 | |
| 5043 | @item W |
| 5044 | @item H |
| 5045 | The width and height of the image. |
| 5046 | |
| 5047 | @item SW |
| 5048 | @item SH |
| 5049 | Width and height scale depending on the currently filtered plane. It is the |
| 5050 | ratio between the corresponding luma plane number of pixels and the current |
| 5051 | plane ones. E.g. for YUV4:2:0 the values are @code{1,1} for the luma plane, and |
| 5052 | @code{0.5,0.5} for chroma planes. |
| 5053 | |
| 5054 | @item T |
| 5055 | Time of the current frame, expressed in seconds. |
| 5056 | |
| 5057 | @item p(x, y) |
| 5058 | Return the value of the pixel at location (@var{x},@var{y}) of the current |
| 5059 | plane. |
| 5060 | |
| 5061 | @item lum(x, y) |
| 5062 | Return the value of the pixel at location (@var{x},@var{y}) of the luminance |
| 5063 | plane. |
| 5064 | |
| 5065 | @item cb(x, y) |
| 5066 | Return the value of the pixel at location (@var{x},@var{y}) of the |
| 5067 | blue-difference chroma plane. Return 0 if there is no such plane. |
| 5068 | |
| 5069 | @item cr(x, y) |
| 5070 | Return the value of the pixel at location (@var{x},@var{y}) of the |
| 5071 | red-difference chroma plane. Return 0 if there is no such plane. |
| 5072 | |
| 5073 | @item r(x, y) |
| 5074 | @item g(x, y) |
| 5075 | @item b(x, y) |
| 5076 | Return the value of the pixel at location (@var{x},@var{y}) of the |
| 5077 | red/green/blue component. Return 0 if there is no such component. |
| 5078 | |
| 5079 | @item alpha(x, y) |
| 5080 | Return the value of the pixel at location (@var{x},@var{y}) of the alpha |
| 5081 | plane. Return 0 if there is no such plane. |
| 5082 | @end table |
| 5083 | |
| 5084 | For functions, if @var{x} and @var{y} are outside the area, the value will be |
| 5085 | automatically clipped to the closer edge. |
| 5086 | |
| 5087 | @subsection Examples |
| 5088 | |
| 5089 | @itemize |
| 5090 | @item |
| 5091 | Flip the image horizontally: |
| 5092 | @example |
| 5093 | geq=p(W-X\,Y) |
| 5094 | @end example |
| 5095 | |
| 5096 | @item |
| 5097 | Generate a bidimensional sine wave, with angle @code{PI/3} and a |
| 5098 | wavelength of 100 pixels: |
| 5099 | @example |
| 5100 | geq=128 + 100*sin(2*(PI/100)*(cos(PI/3)*(X-50*T) + sin(PI/3)*Y)):128:128 |
| 5101 | @end example |
| 5102 | |
| 5103 | @item |
| 5104 | Generate a fancy enigmatic moving light: |
| 5105 | @example |
| 5106 | nullsrc=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 |
| 5107 | @end example |
| 5108 | |
| 5109 | @item |
| 5110 | Generate a quick emboss effect: |
| 5111 | @example |
| 5112 | format=gray,geq=lum_expr='(p(X,Y)+(256-p(X-4,Y-4)))/2' |
| 5113 | @end example |
| 5114 | |
| 5115 | @item |
| 5116 | Modify RGB components depending on pixel position: |
| 5117 | @example |
| 5118 | geq=r='X/W*r(X,Y)':g='(1-X/W)*g(X,Y)':b='(H-Y)/H*b(X,Y)' |
| 5119 | @end example |
| 5120 | |
| 5121 | @item |
| 5122 | Create a radial gradient that is the same size as the input (also see |
| 5123 | the @ref{vignette} filter): |
| 5124 | @example |
| 5125 | geq=lum=255*gauss((X/W-0.5)*3)*gauss((Y/H-0.5)*3)/gauss(0)/gauss(0),format=gray |
| 5126 | @end example |
| 5127 | |
| 5128 | @item |
| 5129 | Create a linear gradient to use as a mask for another filter, then |
| 5130 | compose with @ref{overlay}. In this example the video will gradually |
| 5131 | become more blurry from the top to the bottom of the y-axis as defined |
| 5132 | by the linear gradient: |
| 5133 | @example |
| 5134 | ffmpeg -i input.mp4 -filter_complex "geq=lum=255*(Y/H),format=gray[grad];[0:v]boxblur=4[blur];[blur][grad]alphamerge[alpha];[0:v][alpha]overlay" output.mp4 |
| 5135 | @end example |
| 5136 | @end itemize |
| 5137 | |
| 5138 | @section gradfun |
| 5139 | |
| 5140 | Fix the banding artifacts that are sometimes introduced into nearly flat |
| 5141 | regions by truncation to 8bit color depth. |
| 5142 | Interpolate the gradients that should go where the bands are, and |
| 5143 | dither them. |
| 5144 | |
| 5145 | It is designed for playback only. Do not use it prior to |
| 5146 | lossy compression, because compression tends to lose the dither and |
| 5147 | bring back the bands. |
| 5148 | |
| 5149 | It accepts the following parameters: |
| 5150 | |
| 5151 | @table @option |
| 5152 | |
| 5153 | @item strength |
| 5154 | The maximum amount by which the filter will change any one pixel. This is also |
| 5155 | the threshold for detecting nearly flat regions. Acceptable values range from |
| 5156 | .51 to 64; the default value is 1.2. Out-of-range values will be clipped to the |
| 5157 | valid range. |
| 5158 | |
| 5159 | @item radius |
| 5160 | The neighborhood to fit the gradient to. A larger radius makes for smoother |
| 5161 | gradients, but also prevents the filter from modifying the pixels near detailed |
| 5162 | regions. Acceptable values are 8-32; the default value is 16. Out-of-range |
| 5163 | values will be clipped to the valid range. |
| 5164 | |
| 5165 | @end table |
| 5166 | |
| 5167 | Alternatively, the options can be specified as a flat string: |
| 5168 | @var{strength}[:@var{radius}] |
| 5169 | |
| 5170 | @subsection Examples |
| 5171 | |
| 5172 | @itemize |
| 5173 | @item |
| 5174 | Apply the filter with a @code{3.5} strength and radius of @code{8}: |
| 5175 | @example |
| 5176 | gradfun=3.5:8 |
| 5177 | @end example |
| 5178 | |
| 5179 | @item |
| 5180 | Specify radius, omitting the strength (which will fall-back to the default |
| 5181 | value): |
| 5182 | @example |
| 5183 | gradfun=radius=8 |
| 5184 | @end example |
| 5185 | |
| 5186 | @end itemize |
| 5187 | |
| 5188 | @anchor{haldclut} |
| 5189 | @section haldclut |
| 5190 | |
| 5191 | Apply a Hald CLUT to a video stream. |
| 5192 | |
| 5193 | First input is the video stream to process, and second one is the Hald CLUT. |
| 5194 | The Hald CLUT input can be a simple picture or a complete video stream. |
| 5195 | |
| 5196 | The filter accepts the following options: |
| 5197 | |
| 5198 | @table @option |
| 5199 | @item shortest |
| 5200 | Force termination when the shortest input terminates. Default is @code{0}. |
| 5201 | @item repeatlast |
| 5202 | Continue applying the last CLUT after the end of the stream. A value of |
| 5203 | @code{0} disable the filter after the last frame of the CLUT is reached. |
| 5204 | Default is @code{1}. |
| 5205 | @end table |
| 5206 | |
| 5207 | @code{haldclut} also has the same interpolation options as @ref{lut3d} (both |
| 5208 | filters share the same internals). |
| 5209 | |
| 5210 | More information about the Hald CLUT can be found on Eskil Steenberg's website |
| 5211 | (Hald CLUT author) at @url{http://www.quelsolaar.com/technology/clut.html}. |
| 5212 | |
| 5213 | @subsection Workflow examples |
| 5214 | |
| 5215 | @subsubsection Hald CLUT video stream |
| 5216 | |
| 5217 | Generate an identity Hald CLUT stream altered with various effects: |
| 5218 | @example |
| 5219 | ffmpeg -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 |
| 5220 | @end example |
| 5221 | |
| 5222 | Note: make sure you use a lossless codec. |
| 5223 | |
| 5224 | Then use it with @code{haldclut} to apply it on some random stream: |
| 5225 | @example |
| 5226 | ffmpeg -f lavfi -i mandelbrot -i clut.nut -filter_complex '[0][1] haldclut' -t 20 mandelclut.mkv |
| 5227 | @end example |
| 5228 | |
| 5229 | The Hald CLUT will be applied to the 10 first seconds (duration of |
| 5230 | @file{clut.nut}), then the latest picture of that CLUT stream will be applied |
| 5231 | to the remaining frames of the @code{mandelbrot} stream. |
| 5232 | |
| 5233 | @subsubsection Hald CLUT with preview |
| 5234 | |
| 5235 | A Hald CLUT is supposed to be a squared image of @code{Level*Level*Level} by |
| 5236 | @code{Level*Level*Level} pixels. For a given Hald CLUT, FFmpeg will select the |
| 5237 | biggest possible square starting at the top left of the picture. The remaining |
| 5238 | padding pixels (bottom or right) will be ignored. This area can be used to add |
| 5239 | a preview of the Hald CLUT. |
| 5240 | |
| 5241 | Typically, the following generated Hald CLUT will be supported by the |
| 5242 | @code{haldclut} filter: |
| 5243 | |
| 5244 | @example |
| 5245 | ffmpeg -f lavfi -i @ref{haldclutsrc}=8 -vf " |
| 5246 | pad=iw+320 [padded_clut]; |
| 5247 | smptebars=s=320x256, split [a][b]; |
| 5248 | [padded_clut][a] overlay=W-320:h, curves=color_negative [main]; |
| 5249 | [main][b] overlay=W-320" -frames:v 1 clut.png |
| 5250 | @end example |
| 5251 | |
| 5252 | It contains the original and a preview of the effect of the CLUT: SMPTE color |
| 5253 | bars are displayed on the right-top, and below the same color bars processed by |
| 5254 | the color changes. |
| 5255 | |
| 5256 | Then, the effect of this Hald CLUT can be visualized with: |
| 5257 | @example |
| 5258 | ffplay input.mkv -vf "movie=clut.png, [in] haldclut" |
| 5259 | @end example |
| 5260 | |
| 5261 | @section hflip |
| 5262 | |
| 5263 | Flip the input video horizontally. |
| 5264 | |
| 5265 | For example, to horizontally flip the input video with @command{ffmpeg}: |
| 5266 | @example |
| 5267 | ffmpeg -i in.avi -vf "hflip" out.avi |
| 5268 | @end example |
| 5269 | |
| 5270 | @section histeq |
| 5271 | This filter applies a global color histogram equalization on a |
| 5272 | per-frame basis. |
| 5273 | |
| 5274 | It can be used to correct video that has a compressed range of pixel |
| 5275 | intensities. The filter redistributes the pixel intensities to |
| 5276 | equalize their distribution across the intensity range. It may be |
| 5277 | viewed as an "automatically adjusting contrast filter". This filter is |
| 5278 | useful only for correcting degraded or poorly captured source |
| 5279 | video. |
| 5280 | |
| 5281 | The filter accepts the following options: |
| 5282 | |
| 5283 | @table @option |
| 5284 | @item strength |
| 5285 | Determine the amount of equalization to be applied. As the strength |
| 5286 | is reduced, the distribution of pixel intensities more-and-more |
| 5287 | approaches that of the input frame. The value must be a float number |
| 5288 | in the range [0,1] and defaults to 0.200. |
| 5289 | |
| 5290 | @item intensity |
| 5291 | Set the maximum intensity that can generated and scale the output |
| 5292 | values appropriately. The strength should be set as desired and then |
| 5293 | the intensity can be limited if needed to avoid washing-out. The value |
| 5294 | must be a float number in the range [0,1] and defaults to 0.210. |
| 5295 | |
| 5296 | @item antibanding |
| 5297 | Set the antibanding level. If enabled the filter will randomly vary |
| 5298 | the luminance of output pixels by a small amount to avoid banding of |
| 5299 | the histogram. Possible values are @code{none}, @code{weak} or |
| 5300 | @code{strong}. It defaults to @code{none}. |
| 5301 | @end table |
| 5302 | |
| 5303 | @section histogram |
| 5304 | |
| 5305 | Compute and draw a color distribution histogram for the input video. |
| 5306 | |
| 5307 | The computed histogram is a representation of the color component |
| 5308 | distribution in an image. |
| 5309 | |
| 5310 | The filter accepts the following options: |
| 5311 | |
| 5312 | @table @option |
| 5313 | @item mode |
| 5314 | Set histogram mode. |
| 5315 | |
| 5316 | It accepts the following values: |
| 5317 | @table @samp |
| 5318 | @item levels |
| 5319 | Standard histogram that displays the color components distribution in an |
| 5320 | image. Displays color graph for each color component. Shows distribution of |
| 5321 | the Y, U, V, A or R, G, B components, depending on input format, in the |
| 5322 | current frame. Below each graph a color component scale meter is shown. |
| 5323 | |
| 5324 | @item color |
| 5325 | Displays chroma values (U/V color placement) in a two dimensional |
| 5326 | graph (which is called a vectorscope). The brighter a pixel in the |
| 5327 | vectorscope, the more pixels of the input frame correspond to that pixel |
| 5328 | (i.e., more pixels have this chroma value). The V component is displayed on |
| 5329 | the horizontal (X) axis, with the leftmost side being V = 0 and the rightmost |
| 5330 | side being V = 255. The U component is displayed on the vertical (Y) axis, |
| 5331 | with the top representing U = 0 and the bottom representing U = 255. |
| 5332 | |
| 5333 | The position of a white pixel in the graph corresponds to the chroma value of |
| 5334 | a pixel of the input clip. The graph can therefore be used to read the hue |
| 5335 | (color flavor) and the saturation (the dominance of the hue in the color). As |
| 5336 | the hue of a color changes, it moves around the square. At the center of the |
| 5337 | square the saturation is zero, which means that the corresponding pixel has no |
| 5338 | color. If the amount of a specific color is increased (while leaving the other |
| 5339 | colors unchanged) the saturation increases, and the indicator moves towards |
| 5340 | the edge of the square. |
| 5341 | |
| 5342 | @item color2 |
| 5343 | Chroma values in vectorscope, similar as @code{color} but actual chroma values |
| 5344 | are displayed. |
| 5345 | |
| 5346 | @item waveform |
| 5347 | Per row/column color component graph. In row mode, the graph on the left side |
| 5348 | represents color component value 0 and the right side represents value = 255. |
| 5349 | In column mode, the top side represents color component value = 0 and bottom |
| 5350 | side represents value = 255. |
| 5351 | @end table |
| 5352 | Default value is @code{levels}. |
| 5353 | |
| 5354 | @item level_height |
| 5355 | Set height of level in @code{levels}. Default value is @code{200}. |
| 5356 | Allowed range is [50, 2048]. |
| 5357 | |
| 5358 | @item scale_height |
| 5359 | Set height of color scale in @code{levels}. Default value is @code{12}. |
| 5360 | Allowed range is [0, 40]. |
| 5361 | |
| 5362 | @item step |
| 5363 | Set step for @code{waveform} mode. Smaller values are useful to find out how |
| 5364 | many values of the same luminance are distributed across input rows/columns. |
| 5365 | Default value is @code{10}. Allowed range is [1, 255]. |
| 5366 | |
| 5367 | @item waveform_mode |
| 5368 | Set mode for @code{waveform}. Can be either @code{row}, or @code{column}. |
| 5369 | Default is @code{row}. |
| 5370 | |
| 5371 | @item waveform_mirror |
| 5372 | Set mirroring mode for @code{waveform}. @code{0} means unmirrored, @code{1} |
| 5373 | means mirrored. In mirrored mode, higher values will be represented on the left |
| 5374 | side for @code{row} mode and at the top for @code{column} mode. Default is |
| 5375 | @code{0} (unmirrored). |
| 5376 | |
| 5377 | @item display_mode |
| 5378 | Set display mode for @code{waveform} and @code{levels}. |
| 5379 | It accepts the following values: |
| 5380 | @table @samp |
| 5381 | @item parade |
| 5382 | Display separate graph for the color components side by side in |
| 5383 | @code{row} waveform mode or one below the other in @code{column} waveform mode |
| 5384 | for @code{waveform} histogram mode. For @code{levels} histogram mode, |
| 5385 | per color component graphs are placed below each other. |
| 5386 | |
| 5387 | Using this display mode in @code{waveform} histogram mode makes it easy to |
| 5388 | spot color casts in the highlights and shadows of an image, by comparing the |
| 5389 | contours of the top and the bottom graphs of each waveform. Since whites, |
| 5390 | grays, and blacks are characterized by exactly equal amounts of red, green, |
| 5391 | and blue, neutral areas of the picture should display three waveforms of |
| 5392 | roughly equal width/height. If not, the correction is easy to perform by |
| 5393 | making level adjustments the three waveforms. |
| 5394 | |
| 5395 | @item overlay |
| 5396 | Presents information identical to that in the @code{parade}, except |
| 5397 | that the graphs representing color components are superimposed directly |
| 5398 | over one another. |
| 5399 | |
| 5400 | This display mode in @code{waveform} histogram mode makes it easier to spot |
| 5401 | relative differences or similarities in overlapping areas of the color |
| 5402 | components that are supposed to be identical, such as neutral whites, grays, |
| 5403 | or blacks. |
| 5404 | @end table |
| 5405 | Default is @code{parade}. |
| 5406 | |
| 5407 | @item levels_mode |
| 5408 | Set mode for @code{levels}. Can be either @code{linear}, or @code{logarithmic}. |
| 5409 | Default is @code{linear}. |
| 5410 | @end table |
| 5411 | |
| 5412 | @subsection Examples |
| 5413 | |
| 5414 | @itemize |
| 5415 | |
| 5416 | @item |
| 5417 | Calculate and draw histogram: |
| 5418 | @example |
| 5419 | ffplay -i input -vf histogram |
| 5420 | @end example |
| 5421 | |
| 5422 | @end itemize |
| 5423 | |
| 5424 | @anchor{hqdn3d} |
| 5425 | @section hqdn3d |
| 5426 | |
| 5427 | This is a high precision/quality 3d denoise filter. It aims to reduce |
| 5428 | image noise, producing smooth images and making still images really |
| 5429 | still. It should enhance compressibility. |
| 5430 | |
| 5431 | It accepts the following optional parameters: |
| 5432 | |
| 5433 | @table @option |
| 5434 | @item luma_spatial |
| 5435 | A non-negative floating point number which specifies spatial luma strength. |
| 5436 | It defaults to 4.0. |
| 5437 | |
| 5438 | @item chroma_spatial |
| 5439 | A non-negative floating point number which specifies spatial chroma strength. |
| 5440 | It defaults to 3.0*@var{luma_spatial}/4.0. |
| 5441 | |
| 5442 | @item luma_tmp |
| 5443 | A floating point number which specifies luma temporal strength. It defaults to |
| 5444 | 6.0*@var{luma_spatial}/4.0. |
| 5445 | |
| 5446 | @item chroma_tmp |
| 5447 | A floating point number which specifies chroma temporal strength. It defaults to |
| 5448 | @var{luma_tmp}*@var{chroma_spatial}/@var{luma_spatial}. |
| 5449 | @end table |
| 5450 | |
| 5451 | @section hqx |
| 5452 | |
| 5453 | Apply a high-quality magnification filter designed for pixel art. This filter |
| 5454 | was originally created by Maxim Stepin. |
| 5455 | |
| 5456 | It accepts the following option: |
| 5457 | |
| 5458 | @table @option |
| 5459 | @item n |
| 5460 | Set the scaling dimension: @code{2} for @code{hq2x}, @code{3} for |
| 5461 | @code{hq3x} and @code{4} for @code{hq4x}. |
| 5462 | Default is @code{3}. |
| 5463 | @end table |
| 5464 | |
| 5465 | @section hue |
| 5466 | |
| 5467 | Modify the hue and/or the saturation of the input. |
| 5468 | |
| 5469 | It accepts the following parameters: |
| 5470 | |
| 5471 | @table @option |
| 5472 | @item h |
| 5473 | Specify the hue angle as a number of degrees. It accepts an expression, |
| 5474 | and defaults to "0". |
| 5475 | |
| 5476 | @item s |
| 5477 | Specify the saturation in the [-10,10] range. It accepts an expression and |
| 5478 | defaults to "1". |
| 5479 | |
| 5480 | @item H |
| 5481 | Specify the hue angle as a number of radians. It accepts an |
| 5482 | expression, and defaults to "0". |
| 5483 | |
| 5484 | @item b |
| 5485 | Specify the brightness in the [-10,10] range. It accepts an expression and |
| 5486 | defaults to "0". |
| 5487 | @end table |
| 5488 | |
| 5489 | @option{h} and @option{H} are mutually exclusive, and can't be |
| 5490 | specified at the same time. |
| 5491 | |
| 5492 | The @option{b}, @option{h}, @option{H} and @option{s} option values are |
| 5493 | expressions containing the following constants: |
| 5494 | |
| 5495 | @table @option |
| 5496 | @item n |
| 5497 | frame count of the input frame starting from 0 |
| 5498 | |
| 5499 | @item pts |
| 5500 | presentation timestamp of the input frame expressed in time base units |
| 5501 | |
| 5502 | @item r |
| 5503 | frame rate of the input video, NAN if the input frame rate is unknown |
| 5504 | |
| 5505 | @item t |
| 5506 | timestamp expressed in seconds, NAN if the input timestamp is unknown |
| 5507 | |
| 5508 | @item tb |
| 5509 | time base of the input video |
| 5510 | @end table |
| 5511 | |
| 5512 | @subsection Examples |
| 5513 | |
| 5514 | @itemize |
| 5515 | @item |
| 5516 | Set the hue to 90 degrees and the saturation to 1.0: |
| 5517 | @example |
| 5518 | hue=h=90:s=1 |
| 5519 | @end example |
| 5520 | |
| 5521 | @item |
| 5522 | Same command but expressing the hue in radians: |
| 5523 | @example |
| 5524 | hue=H=PI/2:s=1 |
| 5525 | @end example |
| 5526 | |
| 5527 | @item |
| 5528 | Rotate hue and make the saturation swing between 0 |
| 5529 | and 2 over a period of 1 second: |
| 5530 | @example |
| 5531 | hue="H=2*PI*t: s=sin(2*PI*t)+1" |
| 5532 | @end example |
| 5533 | |
| 5534 | @item |
| 5535 | Apply a 3 seconds saturation fade-in effect starting at 0: |
| 5536 | @example |
| 5537 | hue="s=min(t/3\,1)" |
| 5538 | @end example |
| 5539 | |
| 5540 | The general fade-in expression can be written as: |
| 5541 | @example |
| 5542 | hue="s=min(0\, max((t-START)/DURATION\, 1))" |
| 5543 | @end example |
| 5544 | |
| 5545 | @item |
| 5546 | Apply a 3 seconds saturation fade-out effect starting at 5 seconds: |
| 5547 | @example |
| 5548 | hue="s=max(0\, min(1\, (8-t)/3))" |
| 5549 | @end example |
| 5550 | |
| 5551 | The general fade-out expression can be written as: |
| 5552 | @example |
| 5553 | hue="s=max(0\, min(1\, (START+DURATION-t)/DURATION))" |
| 5554 | @end example |
| 5555 | |
| 5556 | @end itemize |
| 5557 | |
| 5558 | @subsection Commands |
| 5559 | |
| 5560 | This filter supports the following commands: |
| 5561 | @table @option |
| 5562 | @item b |
| 5563 | @item s |
| 5564 | @item h |
| 5565 | @item H |
| 5566 | Modify the hue and/or the saturation and/or brightness of the input video. |
| 5567 | The command accepts the same syntax of the corresponding option. |
| 5568 | |
| 5569 | If the specified expression is not valid, it is kept at its current |
| 5570 | value. |
| 5571 | @end table |
| 5572 | |
| 5573 | @section idet |
| 5574 | |
| 5575 | Detect video interlacing type. |
| 5576 | |
| 5577 | This filter tries to detect if the input frames as interlaced, progressive, |
| 5578 | top or bottom field first. It will also try and detect fields that are |
| 5579 | repeated between adjacent frames (a sign of telecine). |
| 5580 | |
| 5581 | Single frame detection considers only immediately adjacent frames when classifying each frame. |
| 5582 | Multiple frame detection incorporates the classification history of previous frames. |
| 5583 | |
| 5584 | The filter will log these metadata values: |
| 5585 | |
| 5586 | @table @option |
| 5587 | @item single.current_frame |
| 5588 | Detected type of current frame using single-frame detection. One of: |
| 5589 | ``tff'' (top field first), ``bff'' (bottom field first), |
| 5590 | ``progressive'', or ``undetermined'' |
| 5591 | |
| 5592 | @item single.tff |
| 5593 | Cumulative number of frames detected as top field first using single-frame detection. |
| 5594 | |
| 5595 | @item multiple.tff |
| 5596 | Cumulative number of frames detected as top field first using multiple-frame detection. |
| 5597 | |
| 5598 | @item single.bff |
| 5599 | Cumulative number of frames detected as bottom field first using single-frame detection. |
| 5600 | |
| 5601 | @item multiple.current_frame |
| 5602 | Detected type of current frame using multiple-frame detection. One of: |
| 5603 | ``tff'' (top field first), ``bff'' (bottom field first), |
| 5604 | ``progressive'', or ``undetermined'' |
| 5605 | |
| 5606 | @item multiple.bff |
| 5607 | Cumulative number of frames detected as bottom field first using multiple-frame detection. |
| 5608 | |
| 5609 | @item single.progressive |
| 5610 | Cumulative number of frames detected as progressive using single-frame detection. |
| 5611 | |
| 5612 | @item multiple.progressive |
| 5613 | Cumulative number of frames detected as progressive using multiple-frame detection. |
| 5614 | |
| 5615 | @item single.undetermined |
| 5616 | Cumulative number of frames that could not be classified using single-frame detection. |
| 5617 | |
| 5618 | @item multiple.undetermined |
| 5619 | Cumulative number of frames that could not be classified using multiple-frame detection. |
| 5620 | |
| 5621 | @item repeated.current_frame |
| 5622 | Which field in the current frame is repeated from the last. One of ``neither'', ``top'', or ``bottom''. |
| 5623 | |
| 5624 | @item repeated.neither |
| 5625 | Cumulative number of frames with no repeated field. |
| 5626 | |
| 5627 | @item repeated.top |
| 5628 | Cumulative number of frames with the top field repeated from the previous frame's top field. |
| 5629 | |
| 5630 | @item repeated.bottom |
| 5631 | Cumulative number of frames with the bottom field repeated from the previous frame's bottom field. |
| 5632 | @end table |
| 5633 | |
| 5634 | The filter accepts the following options: |
| 5635 | |
| 5636 | @table @option |
| 5637 | @item intl_thres |
| 5638 | Set interlacing threshold. |
| 5639 | @item prog_thres |
| 5640 | Set progressive threshold. |
| 5641 | @item repeat_thres |
| 5642 | Threshold for repeated field detection. |
| 5643 | @item half_life |
| 5644 | Number of frames after which a given frame's contribution to the |
| 5645 | statistics is halved (i.e., it contributes only 0.5 to it's |
| 5646 | classification). The default of 0 means that all frames seen are given |
| 5647 | full weight of 1.0 forever. |
| 5648 | @end table |
| 5649 | |
| 5650 | @section il |
| 5651 | |
| 5652 | Deinterleave or interleave fields. |
| 5653 | |
| 5654 | This filter allows one to process interlaced images fields without |
| 5655 | deinterlacing them. Deinterleaving splits the input frame into 2 |
| 5656 | fields (so called half pictures). Odd lines are moved to the top |
| 5657 | half of the output image, even lines to the bottom half. |
| 5658 | You can process (filter) them independently and then re-interleave them. |
| 5659 | |
| 5660 | The filter accepts the following options: |
| 5661 | |
| 5662 | @table @option |
| 5663 | @item luma_mode, l |
| 5664 | @item chroma_mode, c |
| 5665 | @item alpha_mode, a |
| 5666 | Available values for @var{luma_mode}, @var{chroma_mode} and |
| 5667 | @var{alpha_mode} are: |
| 5668 | |
| 5669 | @table @samp |
| 5670 | @item none |
| 5671 | Do nothing. |
| 5672 | |
| 5673 | @item deinterleave, d |
| 5674 | Deinterleave fields, placing one above the other. |
| 5675 | |
| 5676 | @item interleave, i |
| 5677 | Interleave fields. Reverse the effect of deinterleaving. |
| 5678 | @end table |
| 5679 | Default value is @code{none}. |
| 5680 | |
| 5681 | @item luma_swap, ls |
| 5682 | @item chroma_swap, cs |
| 5683 | @item alpha_swap, as |
| 5684 | Swap luma/chroma/alpha fields. Exchange even & odd lines. Default value is @code{0}. |
| 5685 | @end table |
| 5686 | |
| 5687 | @section interlace |
| 5688 | |
| 5689 | Simple interlacing filter from progressive contents. This interleaves upper (or |
| 5690 | lower) lines from odd frames with lower (or upper) lines from even frames, |
| 5691 | halving the frame rate and preserving image height. |
| 5692 | |
| 5693 | @example |
| 5694 | Original Original New Frame |
| 5695 | Frame 'j' Frame 'j+1' (tff) |
| 5696 | ========== =========== ================== |
| 5697 | Line 0 --------------------> Frame 'j' Line 0 |
| 5698 | Line 1 Line 1 ----> Frame 'j+1' Line 1 |
| 5699 | Line 2 ---------------------> Frame 'j' Line 2 |
| 5700 | Line 3 Line 3 ----> Frame 'j+1' Line 3 |
| 5701 | ... ... ... |
| 5702 | New Frame + 1 will be generated by Frame 'j+2' and Frame 'j+3' and so on |
| 5703 | @end example |
| 5704 | |
| 5705 | It accepts the following optional parameters: |
| 5706 | |
| 5707 | @table @option |
| 5708 | @item scan |
| 5709 | This determines whether the interlaced frame is taken from the even |
| 5710 | (tff - default) or odd (bff) lines of the progressive frame. |
| 5711 | |
| 5712 | @item lowpass |
| 5713 | Enable (default) or disable the vertical lowpass filter to avoid twitter |
| 5714 | interlacing and reduce moire patterns. |
| 5715 | @end table |
| 5716 | |
| 5717 | @section kerndeint |
| 5718 | |
| 5719 | Deinterlace input video by applying Donald Graft's adaptive kernel |
| 5720 | deinterling. Work on interlaced parts of a video to produce |
| 5721 | progressive frames. |
| 5722 | |
| 5723 | The description of the accepted parameters follows. |
| 5724 | |
| 5725 | @table @option |
| 5726 | @item thresh |
| 5727 | Set the threshold which affects the filter's tolerance when |
| 5728 | determining if a pixel line must be processed. It must be an integer |
| 5729 | in the range [0,255] and defaults to 10. A value of 0 will result in |
| 5730 | applying the process on every pixels. |
| 5731 | |
| 5732 | @item map |
| 5733 | Paint pixels exceeding the threshold value to white if set to 1. |
| 5734 | Default is 0. |
| 5735 | |
| 5736 | @item order |
| 5737 | Set the fields order. Swap fields if set to 1, leave fields alone if |
| 5738 | 0. Default is 0. |
| 5739 | |
| 5740 | @item sharp |
| 5741 | Enable additional sharpening if set to 1. Default is 0. |
| 5742 | |
| 5743 | @item twoway |
| 5744 | Enable twoway sharpening if set to 1. Default is 0. |
| 5745 | @end table |
| 5746 | |
| 5747 | @subsection Examples |
| 5748 | |
| 5749 | @itemize |
| 5750 | @item |
| 5751 | Apply default values: |
| 5752 | @example |
| 5753 | kerndeint=thresh=10:map=0:order=0:sharp=0:twoway=0 |
| 5754 | @end example |
| 5755 | |
| 5756 | @item |
| 5757 | Enable additional sharpening: |
| 5758 | @example |
| 5759 | kerndeint=sharp=1 |
| 5760 | @end example |
| 5761 | |
| 5762 | @item |
| 5763 | Paint processed pixels in white: |
| 5764 | @example |
| 5765 | kerndeint=map=1 |
| 5766 | @end example |
| 5767 | @end itemize |
| 5768 | |
| 5769 | @section lenscorrection |
| 5770 | |
| 5771 | Correct radial lens distortion |
| 5772 | |
| 5773 | This filter can be used to correct for radial distortion as can result from the use |
| 5774 | of wide angle lenses, and thereby re-rectify the image. To find the right parameters |
| 5775 | one can use tools available for example as part of opencv or simply trial-and-error. |
| 5776 | To use opencv use the calibration sample (under samples/cpp) from the opencv sources |
| 5777 | and extract the k1 and k2 coefficients from the resulting matrix. |
| 5778 | |
| 5779 | Note that effectively the same filter is available in the open-source tools Krita and |
| 5780 | Digikam from the KDE project. |
| 5781 | |
| 5782 | In contrast to the @ref{vignette} filter, which can also be used to compensate lens errors, |
| 5783 | this filter corrects the distortion of the image, whereas @ref{vignette} corrects the |
| 5784 | brightness distribution, so you may want to use both filters together in certain |
| 5785 | cases, though you will have to take care of ordering, i.e. whether vignetting should |
| 5786 | be applied before or after lens correction. |
| 5787 | |
| 5788 | @subsection Options |
| 5789 | |
| 5790 | The filter accepts the following options: |
| 5791 | |
| 5792 | @table @option |
| 5793 | @item cx |
| 5794 | Relative x-coordinate of the focal point of the image, and thereby the center of the |
| 5795 | distrortion. This value has a range [0,1] and is expressed as fractions of the image |
| 5796 | width. |
| 5797 | @item cy |
| 5798 | Relative y-coordinate of the focal point of the image, and thereby the center of the |
| 5799 | distrortion. This value has a range [0,1] and is expressed as fractions of the image |
| 5800 | height. |
| 5801 | @item k1 |
| 5802 | Coefficient of the quadratic correction term. 0.5 means no correction. |
| 5803 | @item k2 |
| 5804 | Coefficient of the double quadratic correction term. 0.5 means no correction. |
| 5805 | @end table |
| 5806 | |
| 5807 | The formula that generates the correction is: |
| 5808 | |
| 5809 | @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) |
| 5810 | |
| 5811 | where @var{r_0} is halve of the image diagonal and @var{r_src} and @var{r_tgt} are the |
| 5812 | distances from the focal point in the source and target images, respectively. |
| 5813 | |
| 5814 | @anchor{lut3d} |
| 5815 | @section lut3d |
| 5816 | |
| 5817 | Apply a 3D LUT to an input video. |
| 5818 | |
| 5819 | The filter accepts the following options: |
| 5820 | |
| 5821 | @table @option |
| 5822 | @item file |
| 5823 | Set the 3D LUT file name. |
| 5824 | |
| 5825 | Currently supported formats: |
| 5826 | @table @samp |
| 5827 | @item 3dl |
| 5828 | AfterEffects |
| 5829 | @item cube |
| 5830 | Iridas |
| 5831 | @item dat |
| 5832 | DaVinci |
| 5833 | @item m3d |
| 5834 | Pandora |
| 5835 | @end table |
| 5836 | @item interp |
| 5837 | Select interpolation mode. |
| 5838 | |
| 5839 | Available values are: |
| 5840 | |
| 5841 | @table @samp |
| 5842 | @item nearest |
| 5843 | Use values from the nearest defined point. |
| 5844 | @item trilinear |
| 5845 | Interpolate values using the 8 points defining a cube. |
| 5846 | @item tetrahedral |
| 5847 | Interpolate values using a tetrahedron. |
| 5848 | @end table |
| 5849 | @end table |
| 5850 | |
| 5851 | @section lut, lutrgb, lutyuv |
| 5852 | |
| 5853 | Compute a look-up table for binding each pixel component input value |
| 5854 | to an output value, and apply it to the input video. |
| 5855 | |
| 5856 | @var{lutyuv} applies a lookup table to a YUV input video, @var{lutrgb} |
| 5857 | to an RGB input video. |
| 5858 | |
| 5859 | These filters accept the following parameters: |
| 5860 | @table @option |
| 5861 | @item c0 |
| 5862 | set first pixel component expression |
| 5863 | @item c1 |
| 5864 | set second pixel component expression |
| 5865 | @item c2 |
| 5866 | set third pixel component expression |
| 5867 | @item c3 |
| 5868 | set fourth pixel component expression, corresponds to the alpha component |
| 5869 | |
| 5870 | @item r |
| 5871 | set red component expression |
| 5872 | @item g |
| 5873 | set green component expression |
| 5874 | @item b |
| 5875 | set blue component expression |
| 5876 | @item a |
| 5877 | alpha component expression |
| 5878 | |
| 5879 | @item y |
| 5880 | set Y/luminance component expression |
| 5881 | @item u |
| 5882 | set U/Cb component expression |
| 5883 | @item v |
| 5884 | set V/Cr component expression |
| 5885 | @end table |
| 5886 | |
| 5887 | Each of them specifies the expression to use for computing the lookup table for |
| 5888 | the corresponding pixel component values. |
| 5889 | |
| 5890 | The exact component associated to each of the @var{c*} options depends on the |
| 5891 | format in input. |
| 5892 | |
| 5893 | The @var{lut} filter requires either YUV or RGB pixel formats in input, |
| 5894 | @var{lutrgb} requires RGB pixel formats in input, and @var{lutyuv} requires YUV. |
| 5895 | |
| 5896 | The expressions can contain the following constants and functions: |
| 5897 | |
| 5898 | @table @option |
| 5899 | @item w |
| 5900 | @item h |
| 5901 | The input width and height. |
| 5902 | |
| 5903 | @item val |
| 5904 | The input value for the pixel component. |
| 5905 | |
| 5906 | @item clipval |
| 5907 | The input value, clipped to the @var{minval}-@var{maxval} range. |
| 5908 | |
| 5909 | @item maxval |
| 5910 | The maximum value for the pixel component. |
| 5911 | |
| 5912 | @item minval |
| 5913 | The minimum value for the pixel component. |
| 5914 | |
| 5915 | @item negval |
| 5916 | The negated value for the pixel component value, clipped to the |
| 5917 | @var{minval}-@var{maxval} range; it corresponds to the expression |
| 5918 | "maxval-clipval+minval". |
| 5919 | |
| 5920 | @item clip(val) |
| 5921 | The computed value in @var{val}, clipped to the |
| 5922 | @var{minval}-@var{maxval} range. |
| 5923 | |
| 5924 | @item gammaval(gamma) |
| 5925 | The computed gamma correction value of the pixel component value, |
| 5926 | clipped to the @var{minval}-@var{maxval} range. It corresponds to the |
| 5927 | expression |
| 5928 | "pow((clipval-minval)/(maxval-minval)\,@var{gamma})*(maxval-minval)+minval" |
| 5929 | |
| 5930 | @end table |
| 5931 | |
| 5932 | All expressions default to "val". |
| 5933 | |
| 5934 | @subsection Examples |
| 5935 | |
| 5936 | @itemize |
| 5937 | @item |
| 5938 | Negate input video: |
| 5939 | @example |
| 5940 | lutrgb="r=maxval+minval-val:g=maxval+minval-val:b=maxval+minval-val" |
| 5941 | lutyuv="y=maxval+minval-val:u=maxval+minval-val:v=maxval+minval-val" |
| 5942 | @end example |
| 5943 | |
| 5944 | The above is the same as: |
| 5945 | @example |
| 5946 | lutrgb="r=negval:g=negval:b=negval" |
| 5947 | lutyuv="y=negval:u=negval:v=negval" |
| 5948 | @end example |
| 5949 | |
| 5950 | @item |
| 5951 | Negate luminance: |
| 5952 | @example |
| 5953 | lutyuv=y=negval |
| 5954 | @end example |
| 5955 | |
| 5956 | @item |
| 5957 | Remove chroma components, turning the video into a graytone image: |
| 5958 | @example |
| 5959 | lutyuv="u=128:v=128" |
| 5960 | @end example |
| 5961 | |
| 5962 | @item |
| 5963 | Apply a luma burning effect: |
| 5964 | @example |
| 5965 | lutyuv="y=2*val" |
| 5966 | @end example |
| 5967 | |
| 5968 | @item |
| 5969 | Remove green and blue components: |
| 5970 | @example |
| 5971 | lutrgb="g=0:b=0" |
| 5972 | @end example |
| 5973 | |
| 5974 | @item |
| 5975 | Set a constant alpha channel value on input: |
| 5976 | @example |
| 5977 | format=rgba,lutrgb=a="maxval-minval/2" |
| 5978 | @end example |
| 5979 | |
| 5980 | @item |
| 5981 | Correct luminance gamma by a factor of 0.5: |
| 5982 | @example |
| 5983 | lutyuv=y=gammaval(0.5) |
| 5984 | @end example |
| 5985 | |
| 5986 | @item |
| 5987 | Discard least significant bits of luma: |
| 5988 | @example |
| 5989 | lutyuv=y='bitand(val, 128+64+32)' |
| 5990 | @end example |
| 5991 | @end itemize |
| 5992 | |
| 5993 | @section mergeplanes |
| 5994 | |
| 5995 | Merge color channel components from several video streams. |
| 5996 | |
| 5997 | The filter accepts up to 4 input streams, and merge selected input |
| 5998 | planes to the output video. |
| 5999 | |
| 6000 | This filter accepts the following options: |
| 6001 | @table @option |
| 6002 | @item mapping |
| 6003 | Set input to output plane mapping. Default is @code{0}. |
| 6004 | |
| 6005 | The mappings is specified as a bitmap. It should be specified as a |
| 6006 | hexadecimal number in the form 0xAa[Bb[Cc[Dd]]]. 'Aa' describes the |
| 6007 | mapping for the first plane of the output stream. 'A' sets the number of |
| 6008 | the input stream to use (from 0 to 3), and 'a' the plane number of the |
| 6009 | corresponding input to use (from 0 to 3). The rest of the mappings is |
| 6010 | similar, 'Bb' describes the mapping for the output stream second |
| 6011 | plane, 'Cc' describes the mapping for the output stream third plane and |
| 6012 | 'Dd' describes the mapping for the output stream fourth plane. |
| 6013 | |
| 6014 | @item format |
| 6015 | Set output pixel format. Default is @code{yuva444p}. |
| 6016 | @end table |
| 6017 | |
| 6018 | @subsection Examples |
| 6019 | |
| 6020 | @itemize |
| 6021 | @item |
| 6022 | Merge three gray video streams of same width and height into single video stream: |
| 6023 | @example |
| 6024 | [a0][a1][a2]mergeplanes=0x001020:yuv444p |
| 6025 | @end example |
| 6026 | |
| 6027 | @item |
| 6028 | Merge 1st yuv444p stream and 2nd gray video stream into yuva444p video stream: |
| 6029 | @example |
| 6030 | [a0][a1]mergeplanes=0x00010210:yuva444p |
| 6031 | @end example |
| 6032 | |
| 6033 | @item |
| 6034 | Swap Y and A plane in yuva444p stream: |
| 6035 | @example |
| 6036 | format=yuva444p,mergeplanes=0x03010200:yuva444p |
| 6037 | @end example |
| 6038 | |
| 6039 | @item |
| 6040 | Swap U and V plane in yuv420p stream: |
| 6041 | @example |
| 6042 | format=yuv420p,mergeplanes=0x000201:yuv420p |
| 6043 | @end example |
| 6044 | |
| 6045 | @item |
| 6046 | Cast a rgb24 clip to yuv444p: |
| 6047 | @example |
| 6048 | format=rgb24,mergeplanes=0x000102:yuv444p |
| 6049 | @end example |
| 6050 | @end itemize |
| 6051 | |
| 6052 | @section mcdeint |
| 6053 | |
| 6054 | Apply motion-compensation deinterlacing. |
| 6055 | |
| 6056 | It needs one field per frame as input and must thus be used together |
| 6057 | with yadif=1/3 or equivalent. |
| 6058 | |
| 6059 | This filter accepts the following options: |
| 6060 | @table @option |
| 6061 | @item mode |
| 6062 | Set the deinterlacing mode. |
| 6063 | |
| 6064 | It accepts one of the following values: |
| 6065 | @table @samp |
| 6066 | @item fast |
| 6067 | @item medium |
| 6068 | @item slow |
| 6069 | use iterative motion estimation |
| 6070 | @item extra_slow |
| 6071 | like @samp{slow}, but use multiple reference frames. |
| 6072 | @end table |
| 6073 | Default value is @samp{fast}. |
| 6074 | |
| 6075 | @item parity |
| 6076 | Set the picture field parity assumed for the input video. It must be |
| 6077 | one of the following values: |
| 6078 | |
| 6079 | @table @samp |
| 6080 | @item 0, tff |
| 6081 | assume top field first |
| 6082 | @item 1, bff |
| 6083 | assume bottom field first |
| 6084 | @end table |
| 6085 | |
| 6086 | Default value is @samp{bff}. |
| 6087 | |
| 6088 | @item qp |
| 6089 | Set per-block quantization parameter (QP) used by the internal |
| 6090 | encoder. |
| 6091 | |
| 6092 | Higher values should result in a smoother motion vector field but less |
| 6093 | optimal individual vectors. Default value is 1. |
| 6094 | @end table |
| 6095 | |
| 6096 | @section mp |
| 6097 | |
| 6098 | Apply an MPlayer filter to the input video. |
| 6099 | |
| 6100 | This filter provides a wrapper around some of the filters of |
| 6101 | MPlayer/MEncoder. |
| 6102 | |
| 6103 | This wrapper is considered experimental. Some of the wrapped filters |
| 6104 | may not work properly and we may drop support for them, as they will |
| 6105 | be implemented natively into FFmpeg. Thus you should avoid |
| 6106 | depending on them when writing portable scripts. |
| 6107 | |
| 6108 | The filter accepts the parameters: |
| 6109 | @var{filter_name}[:=]@var{filter_params} |
| 6110 | |
| 6111 | @var{filter_name} is the name of a supported MPlayer filter, |
| 6112 | @var{filter_params} is a string containing the parameters accepted by |
| 6113 | the named filter. |
| 6114 | |
| 6115 | The list of the currently supported filters follows: |
| 6116 | @table @var |
| 6117 | @item eq2 |
| 6118 | @item eq |
| 6119 | @item fspp |
| 6120 | @item ilpack |
| 6121 | @item pp7 |
| 6122 | @item softpulldown |
| 6123 | @item uspp |
| 6124 | @end table |
| 6125 | |
| 6126 | The parameter syntax and behavior for the listed filters are the same |
| 6127 | of the corresponding MPlayer filters. For detailed instructions check |
| 6128 | the "VIDEO FILTERS" section in the MPlayer manual. |
| 6129 | |
| 6130 | @subsection Examples |
| 6131 | |
| 6132 | @itemize |
| 6133 | @item |
| 6134 | Adjust gamma, brightness, contrast: |
| 6135 | @example |
| 6136 | mp=eq2=1.0:2:0.5 |
| 6137 | @end example |
| 6138 | @end itemize |
| 6139 | |
| 6140 | See also mplayer(1), @url{http://www.mplayerhq.hu/}. |
| 6141 | |
| 6142 | @section mpdecimate |
| 6143 | |
| 6144 | Drop frames that do not differ greatly from the previous frame in |
| 6145 | order to reduce frame rate. |
| 6146 | |
| 6147 | The main use of this filter is for very-low-bitrate encoding |
| 6148 | (e.g. streaming over dialup modem), but it could in theory be used for |
| 6149 | fixing movies that were inverse-telecined incorrectly. |
| 6150 | |
| 6151 | A description of the accepted options follows. |
| 6152 | |
| 6153 | @table @option |
| 6154 | @item max |
| 6155 | Set the maximum number of consecutive frames which can be dropped (if |
| 6156 | positive), or the minimum interval between dropped frames (if |
| 6157 | negative). If the value is 0, the frame is dropped unregarding the |
| 6158 | number of previous sequentially dropped frames. |
| 6159 | |
| 6160 | Default value is 0. |
| 6161 | |
| 6162 | @item hi |
| 6163 | @item lo |
| 6164 | @item frac |
| 6165 | Set the dropping threshold values. |
| 6166 | |
| 6167 | Values for @option{hi} and @option{lo} are for 8x8 pixel blocks and |
| 6168 | represent actual pixel value differences, so a threshold of 64 |
| 6169 | corresponds to 1 unit of difference for each pixel, or the same spread |
| 6170 | out differently over the block. |
| 6171 | |
| 6172 | A frame is a candidate for dropping if no 8x8 blocks differ by more |
| 6173 | than a threshold of @option{hi}, and if no more than @option{frac} blocks (1 |
| 6174 | meaning the whole image) differ by more than a threshold of @option{lo}. |
| 6175 | |
| 6176 | Default value for @option{hi} is 64*12, default value for @option{lo} is |
| 6177 | 64*5, and default value for @option{frac} is 0.33. |
| 6178 | @end table |
| 6179 | |
| 6180 | |
| 6181 | @section negate |
| 6182 | |
| 6183 | Negate input video. |
| 6184 | |
| 6185 | It accepts an integer in input; if non-zero it negates the |
| 6186 | alpha component (if available). The default value in input is 0. |
| 6187 | |
| 6188 | @section noformat |
| 6189 | |
| 6190 | Force libavfilter not to use any of the specified pixel formats for the |
| 6191 | input to the next filter. |
| 6192 | |
| 6193 | It accepts the following parameters: |
| 6194 | @table @option |
| 6195 | |
| 6196 | @item pix_fmts |
| 6197 | A '|'-separated list of pixel format names, such as |
| 6198 | apix_fmts=yuv420p|monow|rgb24". |
| 6199 | |
| 6200 | @end table |
| 6201 | |
| 6202 | @subsection Examples |
| 6203 | |
| 6204 | @itemize |
| 6205 | @item |
| 6206 | Force libavfilter to use a format different from @var{yuv420p} for the |
| 6207 | input to the vflip filter: |
| 6208 | @example |
| 6209 | noformat=pix_fmts=yuv420p,vflip |
| 6210 | @end example |
| 6211 | |
| 6212 | @item |
| 6213 | Convert the input video to any of the formats not contained in the list: |
| 6214 | @example |
| 6215 | noformat=yuv420p|yuv444p|yuv410p |
| 6216 | @end example |
| 6217 | @end itemize |
| 6218 | |
| 6219 | @section noise |
| 6220 | |
| 6221 | Add noise on video input frame. |
| 6222 | |
| 6223 | The filter accepts the following options: |
| 6224 | |
| 6225 | @table @option |
| 6226 | @item all_seed |
| 6227 | @item c0_seed |
| 6228 | @item c1_seed |
| 6229 | @item c2_seed |
| 6230 | @item c3_seed |
| 6231 | Set noise seed for specific pixel component or all pixel components in case |
| 6232 | of @var{all_seed}. Default value is @code{123457}. |
| 6233 | |
| 6234 | @item all_strength, alls |
| 6235 | @item c0_strength, c0s |
| 6236 | @item c1_strength, c1s |
| 6237 | @item c2_strength, c2s |
| 6238 | @item c3_strength, c3s |
| 6239 | Set noise strength for specific pixel component or all pixel components in case |
| 6240 | @var{all_strength}. Default value is @code{0}. Allowed range is [0, 100]. |
| 6241 | |
| 6242 | @item all_flags, allf |
| 6243 | @item c0_flags, c0f |
| 6244 | @item c1_flags, c1f |
| 6245 | @item c2_flags, c2f |
| 6246 | @item c3_flags, c3f |
| 6247 | Set pixel component flags or set flags for all components if @var{all_flags}. |
| 6248 | Available values for component flags are: |
| 6249 | @table @samp |
| 6250 | @item a |
| 6251 | averaged temporal noise (smoother) |
| 6252 | @item p |
| 6253 | mix random noise with a (semi)regular pattern |
| 6254 | @item t |
| 6255 | temporal noise (noise pattern changes between frames) |
| 6256 | @item u |
| 6257 | uniform noise (gaussian otherwise) |
| 6258 | @end table |
| 6259 | @end table |
| 6260 | |
| 6261 | @subsection Examples |
| 6262 | |
| 6263 | Add temporal and uniform noise to input video: |
| 6264 | @example |
| 6265 | noise=alls=20:allf=t+u |
| 6266 | @end example |
| 6267 | |
| 6268 | @section null |
| 6269 | |
| 6270 | Pass the video source unchanged to the output. |
| 6271 | |
| 6272 | @section ocv |
| 6273 | |
| 6274 | Apply a video transform using libopencv. |
| 6275 | |
| 6276 | To enable this filter, install the libopencv library and headers and |
| 6277 | configure FFmpeg with @code{--enable-libopencv}. |
| 6278 | |
| 6279 | It accepts the following parameters: |
| 6280 | |
| 6281 | @table @option |
| 6282 | |
| 6283 | @item filter_name |
| 6284 | The name of the libopencv filter to apply. |
| 6285 | |
| 6286 | @item filter_params |
| 6287 | The parameters to pass to the libopencv filter. If not specified, the default |
| 6288 | values are assumed. |
| 6289 | |
| 6290 | @end table |
| 6291 | |
| 6292 | Refer to the official libopencv documentation for more precise |
| 6293 | information: |
| 6294 | @url{http://docs.opencv.org/master/modules/imgproc/doc/filtering.html} |
| 6295 | |
| 6296 | Several libopencv filters are supported; see the following subsections. |
| 6297 | |
| 6298 | @anchor{dilate} |
| 6299 | @subsection dilate |
| 6300 | |
| 6301 | Dilate an image by using a specific structuring element. |
| 6302 | It corresponds to the libopencv function @code{cvDilate}. |
| 6303 | |
| 6304 | It accepts the parameters: @var{struct_el}|@var{nb_iterations}. |
| 6305 | |
| 6306 | @var{struct_el} represents a structuring element, and has the syntax: |
| 6307 | @var{cols}x@var{rows}+@var{anchor_x}x@var{anchor_y}/@var{shape} |
| 6308 | |
| 6309 | @var{cols} and @var{rows} represent the number of columns and rows of |
| 6310 | the structuring element, @var{anchor_x} and @var{anchor_y} the anchor |
| 6311 | point, and @var{shape} the shape for the structuring element. @var{shape} |
| 6312 | must be "rect", "cross", "ellipse", or "custom". |
| 6313 | |
| 6314 | If the value for @var{shape} is "custom", it must be followed by a |
| 6315 | string of the form "=@var{filename}". The file with name |
| 6316 | @var{filename} is assumed to represent a binary image, with each |
| 6317 | printable character corresponding to a bright pixel. When a custom |
| 6318 | @var{shape} is used, @var{cols} and @var{rows} are ignored, the number |
| 6319 | or columns and rows of the read file are assumed instead. |
| 6320 | |
| 6321 | The default value for @var{struct_el} is "3x3+0x0/rect". |
| 6322 | |
| 6323 | @var{nb_iterations} specifies the number of times the transform is |
| 6324 | applied to the image, and defaults to 1. |
| 6325 | |
| 6326 | Some examples: |
| 6327 | @example |
| 6328 | # Use the default values |
| 6329 | ocv=dilate |
| 6330 | |
| 6331 | # Dilate using a structuring element with a 5x5 cross, iterating two times |
| 6332 | ocv=filter_name=dilate:filter_params=5x5+2x2/cross|2 |
| 6333 | |
| 6334 | # Read the shape from the file diamond.shape, iterating two times. |
| 6335 | # The file diamond.shape may contain a pattern of characters like this |
| 6336 | # * |
| 6337 | # *** |
| 6338 | # ***** |
| 6339 | # *** |
| 6340 | # * |
| 6341 | # The specified columns and rows are ignored |
| 6342 | # but the anchor point coordinates are not |
| 6343 | ocv=dilate:0x0+2x2/custom=diamond.shape|2 |
| 6344 | @end example |
| 6345 | |
| 6346 | @subsection erode |
| 6347 | |
| 6348 | Erode an image by using a specific structuring element. |
| 6349 | It corresponds to the libopencv function @code{cvErode}. |
| 6350 | |
| 6351 | It accepts the parameters: @var{struct_el}:@var{nb_iterations}, |
| 6352 | with the same syntax and semantics as the @ref{dilate} filter. |
| 6353 | |
| 6354 | @subsection smooth |
| 6355 | |
| 6356 | Smooth the input video. |
| 6357 | |
| 6358 | The filter takes the following parameters: |
| 6359 | @var{type}|@var{param1}|@var{param2}|@var{param3}|@var{param4}. |
| 6360 | |
| 6361 | @var{type} is the type of smooth filter to apply, and must be one of |
| 6362 | the following values: "blur", "blur_no_scale", "median", "gaussian", |
| 6363 | or "bilateral". The default value is "gaussian". |
| 6364 | |
| 6365 | The meaning of @var{param1}, @var{param2}, @var{param3}, and @var{param4} |
| 6366 | depend on the smooth type. @var{param1} and |
| 6367 | @var{param2} accept integer positive values or 0. @var{param3} and |
| 6368 | @var{param4} accept floating point values. |
| 6369 | |
| 6370 | The default value for @var{param1} is 3. The default value for the |
| 6371 | other parameters is 0. |
| 6372 | |
| 6373 | These parameters correspond to the parameters assigned to the |
| 6374 | libopencv function @code{cvSmooth}. |
| 6375 | |
| 6376 | @anchor{overlay} |
| 6377 | @section overlay |
| 6378 | |
| 6379 | Overlay one video on top of another. |
| 6380 | |
| 6381 | It takes two inputs and has one output. The first input is the "main" |
| 6382 | video on which the second input is overlayed. |
| 6383 | |
| 6384 | It accepts the following parameters: |
| 6385 | |
| 6386 | A description of the accepted options follows. |
| 6387 | |
| 6388 | @table @option |
| 6389 | @item x |
| 6390 | @item y |
| 6391 | Set the expression for the x and y coordinates of the overlayed video |
| 6392 | on the main video. Default value is "0" for both expressions. In case |
| 6393 | the expression is invalid, it is set to a huge value (meaning that the |
| 6394 | overlay will not be displayed within the output visible area). |
| 6395 | |
| 6396 | @item eof_action |
| 6397 | The action to take when EOF is encountered on the secondary input; it accepts |
| 6398 | one of the following values: |
| 6399 | |
| 6400 | @table @option |
| 6401 | @item repeat |
| 6402 | Repeat the last frame (the default). |
| 6403 | @item endall |
| 6404 | End both streams. |
| 6405 | @item pass |
| 6406 | Pass the main input through. |
| 6407 | @end table |
| 6408 | |
| 6409 | @item eval |
| 6410 | Set when the expressions for @option{x}, and @option{y} are evaluated. |
| 6411 | |
| 6412 | It accepts the following values: |
| 6413 | @table @samp |
| 6414 | @item init |
| 6415 | only evaluate expressions once during the filter initialization or |
| 6416 | when a command is processed |
| 6417 | |
| 6418 | @item frame |
| 6419 | evaluate expressions for each incoming frame |
| 6420 | @end table |
| 6421 | |
| 6422 | Default value is @samp{frame}. |
| 6423 | |
| 6424 | @item shortest |
| 6425 | If set to 1, force the output to terminate when the shortest input |
| 6426 | terminates. Default value is 0. |
| 6427 | |
| 6428 | @item format |
| 6429 | Set the format for the output video. |
| 6430 | |
| 6431 | It accepts the following values: |
| 6432 | @table @samp |
| 6433 | @item yuv420 |
| 6434 | force YUV420 output |
| 6435 | |
| 6436 | @item yuv422 |
| 6437 | force YUV422 output |
| 6438 | |
| 6439 | @item yuv444 |
| 6440 | force YUV444 output |
| 6441 | |
| 6442 | @item rgb |
| 6443 | force RGB output |
| 6444 | @end table |
| 6445 | |
| 6446 | Default value is @samp{yuv420}. |
| 6447 | |
| 6448 | @item rgb @emph{(deprecated)} |
| 6449 | If set to 1, force the filter to accept inputs in the RGB |
| 6450 | color space. Default value is 0. This option is deprecated, use |
| 6451 | @option{format} instead. |
| 6452 | |
| 6453 | @item repeatlast |
| 6454 | If set to 1, force the filter to draw the last overlay frame over the |
| 6455 | main input until the end of the stream. A value of 0 disables this |
| 6456 | behavior. Default value is 1. |
| 6457 | @end table |
| 6458 | |
| 6459 | The @option{x}, and @option{y} expressions can contain the following |
| 6460 | parameters. |
| 6461 | |
| 6462 | @table @option |
| 6463 | @item main_w, W |
| 6464 | @item main_h, H |
| 6465 | The main input width and height. |
| 6466 | |
| 6467 | @item overlay_w, w |
| 6468 | @item overlay_h, h |
| 6469 | The overlay input width and height. |
| 6470 | |
| 6471 | @item x |
| 6472 | @item y |
| 6473 | The computed values for @var{x} and @var{y}. They are evaluated for |
| 6474 | each new frame. |
| 6475 | |
| 6476 | @item hsub |
| 6477 | @item vsub |
| 6478 | horizontal and vertical chroma subsample values of the output |
| 6479 | format. For example for the pixel format "yuv422p" @var{hsub} is 2 and |
| 6480 | @var{vsub} is 1. |
| 6481 | |
| 6482 | @item n |
| 6483 | the number of input frame, starting from 0 |
| 6484 | |
| 6485 | @item pos |
| 6486 | the position in the file of the input frame, NAN if unknown |
| 6487 | |
| 6488 | @item t |
| 6489 | The timestamp, expressed in seconds. It's NAN if the input timestamp is unknown. |
| 6490 | |
| 6491 | @end table |
| 6492 | |
| 6493 | Note that the @var{n}, @var{pos}, @var{t} variables are available only |
| 6494 | when evaluation is done @emph{per frame}, and will evaluate to NAN |
| 6495 | when @option{eval} is set to @samp{init}. |
| 6496 | |
| 6497 | Be aware that frames are taken from each input video in timestamp |
| 6498 | order, hence, if their initial timestamps differ, it is a good idea |
| 6499 | to pass the two inputs through a @var{setpts=PTS-STARTPTS} filter to |
| 6500 | have them begin in the same zero timestamp, as the example for |
| 6501 | the @var{movie} filter does. |
| 6502 | |
| 6503 | You can chain together more overlays but you should test the |
| 6504 | efficiency of such approach. |
| 6505 | |
| 6506 | @subsection Commands |
| 6507 | |
| 6508 | This filter supports the following commands: |
| 6509 | @table @option |
| 6510 | @item x |
| 6511 | @item y |
| 6512 | Modify the x and y of the overlay input. |
| 6513 | The command accepts the same syntax of the corresponding option. |
| 6514 | |
| 6515 | If the specified expression is not valid, it is kept at its current |
| 6516 | value. |
| 6517 | @end table |
| 6518 | |
| 6519 | @subsection Examples |
| 6520 | |
| 6521 | @itemize |
| 6522 | @item |
| 6523 | Draw the overlay at 10 pixels from the bottom right corner of the main |
| 6524 | video: |
| 6525 | @example |
| 6526 | overlay=main_w-overlay_w-10:main_h-overlay_h-10 |
| 6527 | @end example |
| 6528 | |
| 6529 | Using named options the example above becomes: |
| 6530 | @example |
| 6531 | overlay=x=main_w-overlay_w-10:y=main_h-overlay_h-10 |
| 6532 | @end example |
| 6533 | |
| 6534 | @item |
| 6535 | Insert a transparent PNG logo in the bottom left corner of the input, |
| 6536 | using the @command{ffmpeg} tool with the @code{-filter_complex} option: |
| 6537 | @example |
| 6538 | ffmpeg -i input -i logo -filter_complex 'overlay=10:main_h-overlay_h-10' output |
| 6539 | @end example |
| 6540 | |
| 6541 | @item |
| 6542 | Insert 2 different transparent PNG logos (second logo on bottom |
| 6543 | right corner) using the @command{ffmpeg} tool: |
| 6544 | @example |
| 6545 | ffmpeg -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 |
| 6546 | @end example |
| 6547 | |
| 6548 | @item |
| 6549 | Add a transparent color layer on top of the main video; @code{WxH} |
| 6550 | must specify the size of the main input to the overlay filter: |
| 6551 | @example |
| 6552 | color=color=red@@.3:size=WxH [over]; [in][over] overlay [out] |
| 6553 | @end example |
| 6554 | |
| 6555 | @item |
| 6556 | Play an original video and a filtered version (here with the deshake |
| 6557 | filter) side by side using the @command{ffplay} tool: |
| 6558 | @example |
| 6559 | ffplay input.avi -vf 'split[a][b]; [a]pad=iw*2:ih[src]; [b]deshake[filt]; [src][filt]overlay=w' |
| 6560 | @end example |
| 6561 | |
| 6562 | The above command is the same as: |
| 6563 | @example |
| 6564 | ffplay input.avi -vf 'split[b], pad=iw*2[src], [b]deshake, [src]overlay=w' |
| 6565 | @end example |
| 6566 | |
| 6567 | @item |
| 6568 | Make a sliding overlay appearing from the left to the right top part of the |
| 6569 | screen starting since time 2: |
| 6570 | @example |
| 6571 | overlay=x='if(gte(t,2), -w+(t-2)*20, NAN)':y=0 |
| 6572 | @end example |
| 6573 | |
| 6574 | @item |
| 6575 | Compose output by putting two input videos side to side: |
| 6576 | @example |
| 6577 | ffmpeg -i left.avi -i right.avi -filter_complex " |
| 6578 | nullsrc=size=200x100 [background]; |
| 6579 | [0:v] setpts=PTS-STARTPTS, scale=100x100 [left]; |
| 6580 | [1:v] setpts=PTS-STARTPTS, scale=100x100 [right]; |
| 6581 | [background][left] overlay=shortest=1 [background+left]; |
| 6582 | [background+left][right] overlay=shortest=1:x=100 [left+right] |
| 6583 | " |
| 6584 | @end example |
| 6585 | |
| 6586 | @item |
| 6587 | Mask 10-20 seconds of a video by applying the delogo filter to a section |
| 6588 | @example |
| 6589 | ffmpeg -i test.avi -codec:v:0 wmv2 -ar 11025 -b:v 9000k |
| 6590 | -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]' |
| 6591 | masked.avi |
| 6592 | @end example |
| 6593 | |
| 6594 | @item |
| 6595 | Chain several overlays in cascade: |
| 6596 | @example |
| 6597 | nullsrc=s=200x200 [bg]; |
| 6598 | testsrc=s=100x100, split=4 [in0][in1][in2][in3]; |
| 6599 | [in0] lutrgb=r=0, [bg] overlay=0:0 [mid0]; |
| 6600 | [in1] lutrgb=g=0, [mid0] overlay=100:0 [mid1]; |
| 6601 | [in2] lutrgb=b=0, [mid1] overlay=0:100 [mid2]; |
| 6602 | [in3] null, [mid2] overlay=100:100 [out0] |
| 6603 | @end example |
| 6604 | |
| 6605 | @end itemize |
| 6606 | |
| 6607 | @section owdenoise |
| 6608 | |
| 6609 | Apply Overcomplete Wavelet denoiser. |
| 6610 | |
| 6611 | The filter accepts the following options: |
| 6612 | |
| 6613 | @table @option |
| 6614 | @item depth |
| 6615 | Set depth. |
| 6616 | |
| 6617 | Larger depth values will denoise lower frequency components more, but |
| 6618 | slow down filtering. |
| 6619 | |
| 6620 | Must be an int in the range 8-16, default is @code{8}. |
| 6621 | |
| 6622 | @item luma_strength, ls |
| 6623 | Set luma strength. |
| 6624 | |
| 6625 | Must be a double value in the range 0-1000, default is @code{1.0}. |
| 6626 | |
| 6627 | @item chroma_strength, cs |
| 6628 | Set chroma strength. |
| 6629 | |
| 6630 | Must be a double value in the range 0-1000, default is @code{1.0}. |
| 6631 | @end table |
| 6632 | |
| 6633 | @section pad |
| 6634 | |
| 6635 | Add paddings to the input image, and place the original input at the |
| 6636 | provided @var{x}, @var{y} coordinates. |
| 6637 | |
| 6638 | It accepts the following parameters: |
| 6639 | |
| 6640 | @table @option |
| 6641 | @item width, w |
| 6642 | @item height, h |
| 6643 | Specify an expression for the size of the output image with the |
| 6644 | paddings added. If the value for @var{width} or @var{height} is 0, the |
| 6645 | corresponding input size is used for the output. |
| 6646 | |
| 6647 | The @var{width} expression can reference the value set by the |
| 6648 | @var{height} expression, and vice versa. |
| 6649 | |
| 6650 | The default value of @var{width} and @var{height} is 0. |
| 6651 | |
| 6652 | @item x |
| 6653 | @item y |
| 6654 | Specify the offsets to place the input image at within the padded area, |
| 6655 | with respect to the top/left border of the output image. |
| 6656 | |
| 6657 | The @var{x} expression can reference the value set by the @var{y} |
| 6658 | expression, and vice versa. |
| 6659 | |
| 6660 | The default value of @var{x} and @var{y} is 0. |
| 6661 | |
| 6662 | @item color |
| 6663 | Specify the color of the padded area. For the syntax of this option, |
| 6664 | check the "Color" section in the ffmpeg-utils manual. |
| 6665 | |
| 6666 | The default value of @var{color} is "black". |
| 6667 | @end table |
| 6668 | |
| 6669 | The value for the @var{width}, @var{height}, @var{x}, and @var{y} |
| 6670 | options are expressions containing the following constants: |
| 6671 | |
| 6672 | @table @option |
| 6673 | @item in_w |
| 6674 | @item in_h |
| 6675 | The input video width and height. |
| 6676 | |
| 6677 | @item iw |
| 6678 | @item ih |
| 6679 | These are the same as @var{in_w} and @var{in_h}. |
| 6680 | |
| 6681 | @item out_w |
| 6682 | @item out_h |
| 6683 | The output width and height (the size of the padded area), as |
| 6684 | specified by the @var{width} and @var{height} expressions. |
| 6685 | |
| 6686 | @item ow |
| 6687 | @item oh |
| 6688 | These are the same as @var{out_w} and @var{out_h}. |
| 6689 | |
| 6690 | @item x |
| 6691 | @item y |
| 6692 | The x and y offsets as specified by the @var{x} and @var{y} |
| 6693 | expressions, or NAN if not yet specified. |
| 6694 | |
| 6695 | @item a |
| 6696 | same as @var{iw} / @var{ih} |
| 6697 | |
| 6698 | @item sar |
| 6699 | input sample aspect ratio |
| 6700 | |
| 6701 | @item dar |
| 6702 | input display aspect ratio, it is the same as (@var{iw} / @var{ih}) * @var{sar} |
| 6703 | |
| 6704 | @item hsub |
| 6705 | @item vsub |
| 6706 | The horizontal and vertical chroma subsample values. For example for the |
| 6707 | pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1. |
| 6708 | @end table |
| 6709 | |
| 6710 | @subsection Examples |
| 6711 | |
| 6712 | @itemize |
| 6713 | @item |
| 6714 | Add paddings with the color "violet" to the input video. The output video |
| 6715 | size is 640x480, and the top-left corner of the input video is placed at |
| 6716 | column 0, row 40 |
| 6717 | @example |
| 6718 | pad=640:480:0:40:violet |
| 6719 | @end example |
| 6720 | |
| 6721 | The example above is equivalent to the following command: |
| 6722 | @example |
| 6723 | pad=width=640:height=480:x=0:y=40:color=violet |
| 6724 | @end example |
| 6725 | |
| 6726 | @item |
| 6727 | Pad the input to get an output with dimensions increased by 3/2, |
| 6728 | and put the input video at the center of the padded area: |
| 6729 | @example |
| 6730 | pad="3/2*iw:3/2*ih:(ow-iw)/2:(oh-ih)/2" |
| 6731 | @end example |
| 6732 | |
| 6733 | @item |
| 6734 | Pad the input to get a squared output with size equal to the maximum |
| 6735 | value between the input width and height, and put the input video at |
| 6736 | the center of the padded area: |
| 6737 | @example |
| 6738 | pad="max(iw\,ih):ow:(ow-iw)/2:(oh-ih)/2" |
| 6739 | @end example |
| 6740 | |
| 6741 | @item |
| 6742 | Pad the input to get a final w/h ratio of 16:9: |
| 6743 | @example |
| 6744 | pad="ih*16/9:ih:(ow-iw)/2:(oh-ih)/2" |
| 6745 | @end example |
| 6746 | |
| 6747 | @item |
| 6748 | In case of anamorphic video, in order to set the output display aspect |
| 6749 | correctly, it is necessary to use @var{sar} in the expression, |
| 6750 | according to the relation: |
| 6751 | @example |
| 6752 | (ih * X / ih) * sar = output_dar |
| 6753 | X = output_dar / sar |
| 6754 | @end example |
| 6755 | |
| 6756 | Thus the previous example needs to be modified to: |
| 6757 | @example |
| 6758 | pad="ih*16/9/sar:ih:(ow-iw)/2:(oh-ih)/2" |
| 6759 | @end example |
| 6760 | |
| 6761 | @item |
| 6762 | Double the output size and put the input video in the bottom-right |
| 6763 | corner of the output padded area: |
| 6764 | @example |
| 6765 | pad="2*iw:2*ih:ow-iw:oh-ih" |
| 6766 | @end example |
| 6767 | @end itemize |
| 6768 | |
| 6769 | @section perspective |
| 6770 | |
| 6771 | Correct perspective of video not recorded perpendicular to the screen. |
| 6772 | |
| 6773 | A description of the accepted parameters follows. |
| 6774 | |
| 6775 | @table @option |
| 6776 | @item x0 |
| 6777 | @item y0 |
| 6778 | @item x1 |
| 6779 | @item y1 |
| 6780 | @item x2 |
| 6781 | @item y2 |
| 6782 | @item x3 |
| 6783 | @item y3 |
| 6784 | Set coordinates expression for top left, top right, bottom left and bottom right corners. |
| 6785 | Default values are @code{0:0:W:0:0:H:W:H} with which perspective will remain unchanged. |
| 6786 | If the @code{sense} option is set to @code{source}, then the specified points will be sent |
| 6787 | to the corners of the destination. If the @code{sense} option is set to @code{destination}, |
| 6788 | then the corners of the source will be sent to the specified coordinates. |
| 6789 | |
| 6790 | The expressions can use the following variables: |
| 6791 | |
| 6792 | @table @option |
| 6793 | @item W |
| 6794 | @item H |
| 6795 | the width and height of video frame. |
| 6796 | @end table |
| 6797 | |
| 6798 | @item interpolation |
| 6799 | Set interpolation for perspective correction. |
| 6800 | |
| 6801 | It accepts the following values: |
| 6802 | @table @samp |
| 6803 | @item linear |
| 6804 | @item cubic |
| 6805 | @end table |
| 6806 | |
| 6807 | Default value is @samp{linear}. |
| 6808 | |
| 6809 | @item sense |
| 6810 | Set interpretation of coordinate options. |
| 6811 | |
| 6812 | It accepts the following values: |
| 6813 | @table @samp |
| 6814 | @item 0, source |
| 6815 | |
| 6816 | Send point in the source specified by the given coordinates to |
| 6817 | the corners of the destination. |
| 6818 | |
| 6819 | @item 1, destination |
| 6820 | |
| 6821 | Send the corners of the source to the point in the destination specified |
| 6822 | by the given coordinates. |
| 6823 | |
| 6824 | Default value is @samp{source}. |
| 6825 | @end table |
| 6826 | @end table |
| 6827 | |
| 6828 | @section phase |
| 6829 | |
| 6830 | Delay interlaced video by one field time so that the field order changes. |
| 6831 | |
| 6832 | The intended use is to fix PAL movies that have been captured with the |
| 6833 | opposite field order to the film-to-video transfer. |
| 6834 | |
| 6835 | A description of the accepted parameters follows. |
| 6836 | |
| 6837 | @table @option |
| 6838 | @item mode |
| 6839 | Set phase mode. |
| 6840 | |
| 6841 | It accepts the following values: |
| 6842 | @table @samp |
| 6843 | @item t |
| 6844 | Capture field order top-first, transfer bottom-first. |
| 6845 | Filter will delay the bottom field. |
| 6846 | |
| 6847 | @item b |
| 6848 | Capture field order bottom-first, transfer top-first. |
| 6849 | Filter will delay the top field. |
| 6850 | |
| 6851 | @item p |
| 6852 | Capture and transfer with the same field order. This mode only exists |
| 6853 | for the documentation of the other options to refer to, but if you |
| 6854 | actually select it, the filter will faithfully do nothing. |
| 6855 | |
| 6856 | @item a |
| 6857 | Capture field order determined automatically by field flags, transfer |
| 6858 | opposite. |
| 6859 | Filter selects among @samp{t} and @samp{b} modes on a frame by frame |
| 6860 | basis using field flags. If no field information is available, |
| 6861 | then this works just like @samp{u}. |
| 6862 | |
| 6863 | @item u |
| 6864 | Capture unknown or varying, transfer opposite. |
| 6865 | Filter selects among @samp{t} and @samp{b} on a frame by frame basis by |
| 6866 | analyzing the images and selecting the alternative that produces best |
| 6867 | match between the fields. |
| 6868 | |
| 6869 | @item T |
| 6870 | Capture top-first, transfer unknown or varying. |
| 6871 | Filter selects among @samp{t} and @samp{p} using image analysis. |
| 6872 | |
| 6873 | @item B |
| 6874 | Capture bottom-first, transfer unknown or varying. |
| 6875 | Filter selects among @samp{b} and @samp{p} using image analysis. |
| 6876 | |
| 6877 | @item A |
| 6878 | Capture determined by field flags, transfer unknown or varying. |
| 6879 | Filter selects among @samp{t}, @samp{b} and @samp{p} using field flags and |
| 6880 | image analysis. If no field information is available, then this works just |
| 6881 | like @samp{U}. This is the default mode. |
| 6882 | |
| 6883 | @item U |
| 6884 | Both capture and transfer unknown or varying. |
| 6885 | Filter selects among @samp{t}, @samp{b} and @samp{p} using image analysis only. |
| 6886 | @end table |
| 6887 | @end table |
| 6888 | |
| 6889 | @section pixdesctest |
| 6890 | |
| 6891 | Pixel format descriptor test filter, mainly useful for internal |
| 6892 | testing. The output video should be equal to the input video. |
| 6893 | |
| 6894 | For example: |
| 6895 | @example |
| 6896 | format=monow, pixdesctest |
| 6897 | @end example |
| 6898 | |
| 6899 | can be used to test the monowhite pixel format descriptor definition. |
| 6900 | |
| 6901 | @section pp |
| 6902 | |
| 6903 | Enable the specified chain of postprocessing subfilters using libpostproc. This |
| 6904 | library should be automatically selected with a GPL build (@code{--enable-gpl}). |
| 6905 | Subfilters must be separated by '/' and can be disabled by prepending a '-'. |
| 6906 | Each subfilter and some options have a short and a long name that can be used |
| 6907 | interchangeably, i.e. dr/dering are the same. |
| 6908 | |
| 6909 | The filters accept the following options: |
| 6910 | |
| 6911 | @table @option |
| 6912 | @item subfilters |
| 6913 | Set postprocessing subfilters string. |
| 6914 | @end table |
| 6915 | |
| 6916 | All subfilters share common options to determine their scope: |
| 6917 | |
| 6918 | @table @option |
| 6919 | @item a/autoq |
| 6920 | Honor the quality commands for this subfilter. |
| 6921 | |
| 6922 | @item c/chrom |
| 6923 | Do chrominance filtering, too (default). |
| 6924 | |
| 6925 | @item y/nochrom |
| 6926 | Do luminance filtering only (no chrominance). |
| 6927 | |
| 6928 | @item n/noluma |
| 6929 | Do chrominance filtering only (no luminance). |
| 6930 | @end table |
| 6931 | |
| 6932 | These options can be appended after the subfilter name, separated by a '|'. |
| 6933 | |
| 6934 | Available subfilters are: |
| 6935 | |
| 6936 | @table @option |
| 6937 | @item hb/hdeblock[|difference[|flatness]] |
| 6938 | Horizontal deblocking filter |
| 6939 | @table @option |
| 6940 | @item difference |
| 6941 | Difference factor where higher values mean more deblocking (default: @code{32}). |
| 6942 | @item flatness |
| 6943 | Flatness threshold where lower values mean more deblocking (default: @code{39}). |
| 6944 | @end table |
| 6945 | |
| 6946 | @item vb/vdeblock[|difference[|flatness]] |
| 6947 | Vertical deblocking filter |
| 6948 | @table @option |
| 6949 | @item difference |
| 6950 | Difference factor where higher values mean more deblocking (default: @code{32}). |
| 6951 | @item flatness |
| 6952 | Flatness threshold where lower values mean more deblocking (default: @code{39}). |
| 6953 | @end table |
| 6954 | |
| 6955 | @item ha/hadeblock[|difference[|flatness]] |
| 6956 | Accurate horizontal deblocking filter |
| 6957 | @table @option |
| 6958 | @item difference |
| 6959 | Difference factor where higher values mean more deblocking (default: @code{32}). |
| 6960 | @item flatness |
| 6961 | Flatness threshold where lower values mean more deblocking (default: @code{39}). |
| 6962 | @end table |
| 6963 | |
| 6964 | @item va/vadeblock[|difference[|flatness]] |
| 6965 | Accurate vertical deblocking filter |
| 6966 | @table @option |
| 6967 | @item difference |
| 6968 | Difference factor where higher values mean more deblocking (default: @code{32}). |
| 6969 | @item flatness |
| 6970 | Flatness threshold where lower values mean more deblocking (default: @code{39}). |
| 6971 | @end table |
| 6972 | @end table |
| 6973 | |
| 6974 | The horizontal and vertical deblocking filters share the difference and |
| 6975 | flatness values so you cannot set different horizontal and vertical |
| 6976 | thresholds. |
| 6977 | |
| 6978 | @table @option |
| 6979 | @item h1/x1hdeblock |
| 6980 | Experimental horizontal deblocking filter |
| 6981 | |
| 6982 | @item v1/x1vdeblock |
| 6983 | Experimental vertical deblocking filter |
| 6984 | |
| 6985 | @item dr/dering |
| 6986 | Deringing filter |
| 6987 | |
| 6988 | @item tn/tmpnoise[|threshold1[|threshold2[|threshold3]]], temporal noise reducer |
| 6989 | @table @option |
| 6990 | @item threshold1 |
| 6991 | larger -> stronger filtering |
| 6992 | @item threshold2 |
| 6993 | larger -> stronger filtering |
| 6994 | @item threshold3 |
| 6995 | larger -> stronger filtering |
| 6996 | @end table |
| 6997 | |
| 6998 | @item al/autolevels[:f/fullyrange], automatic brightness / contrast correction |
| 6999 | @table @option |
| 7000 | @item f/fullyrange |
| 7001 | Stretch luminance to @code{0-255}. |
| 7002 | @end table |
| 7003 | |
| 7004 | @item lb/linblenddeint |
| 7005 | Linear blend deinterlacing filter that deinterlaces the given block by |
| 7006 | filtering all lines with a @code{(1 2 1)} filter. |
| 7007 | |
| 7008 | @item li/linipoldeint |
| 7009 | Linear interpolating deinterlacing filter that deinterlaces the given block by |
| 7010 | linearly interpolating every second line. |
| 7011 | |
| 7012 | @item ci/cubicipoldeint |
| 7013 | Cubic interpolating deinterlacing filter deinterlaces the given block by |
| 7014 | cubically interpolating every second line. |
| 7015 | |
| 7016 | @item md/mediandeint |
| 7017 | Median deinterlacing filter that deinterlaces the given block by applying a |
| 7018 | median filter to every second line. |
| 7019 | |
| 7020 | @item fd/ffmpegdeint |
| 7021 | FFmpeg deinterlacing filter that deinterlaces the given block by filtering every |
| 7022 | second line with a @code{(-1 4 2 4 -1)} filter. |
| 7023 | |
| 7024 | @item l5/lowpass5 |
| 7025 | Vertically applied FIR lowpass deinterlacing filter that deinterlaces the given |
| 7026 | block by filtering all lines with a @code{(-1 2 6 2 -1)} filter. |
| 7027 | |
| 7028 | @item fq/forceQuant[|quantizer] |
| 7029 | Overrides the quantizer table from the input with the constant quantizer you |
| 7030 | specify. |
| 7031 | @table @option |
| 7032 | @item quantizer |
| 7033 | Quantizer to use |
| 7034 | @end table |
| 7035 | |
| 7036 | @item de/default |
| 7037 | Default pp filter combination (@code{hb|a,vb|a,dr|a}) |
| 7038 | |
| 7039 | @item fa/fast |
| 7040 | Fast pp filter combination (@code{h1|a,v1|a,dr|a}) |
| 7041 | |
| 7042 | @item ac |
| 7043 | High quality pp filter combination (@code{ha|a|128|7,va|a,dr|a}) |
| 7044 | @end table |
| 7045 | |
| 7046 | @subsection Examples |
| 7047 | |
| 7048 | @itemize |
| 7049 | @item |
| 7050 | Apply horizontal and vertical deblocking, deringing and automatic |
| 7051 | brightness/contrast: |
| 7052 | @example |
| 7053 | pp=hb/vb/dr/al |
| 7054 | @end example |
| 7055 | |
| 7056 | @item |
| 7057 | Apply default filters without brightness/contrast correction: |
| 7058 | @example |
| 7059 | pp=de/-al |
| 7060 | @end example |
| 7061 | |
| 7062 | @item |
| 7063 | Apply default filters and temporal denoiser: |
| 7064 | @example |
| 7065 | pp=default/tmpnoise|1|2|3 |
| 7066 | @end example |
| 7067 | |
| 7068 | @item |
| 7069 | Apply deblocking on luminance only, and switch vertical deblocking on or off |
| 7070 | automatically depending on available CPU time: |
| 7071 | @example |
| 7072 | pp=hb|y/vb|a |
| 7073 | @end example |
| 7074 | @end itemize |
| 7075 | |
| 7076 | @section psnr |
| 7077 | |
| 7078 | Obtain the average, maximum and minimum PSNR (Peak Signal to Noise |
| 7079 | Ratio) between two input videos. |
| 7080 | |
| 7081 | This filter takes in input two input videos, the first input is |
| 7082 | considered the "main" source and is passed unchanged to the |
| 7083 | output. The second input is used as a "reference" video for computing |
| 7084 | the PSNR. |
| 7085 | |
| 7086 | Both video inputs must have the same resolution and pixel format for |
| 7087 | this filter to work correctly. Also it assumes that both inputs |
| 7088 | have the same number of frames, which are compared one by one. |
| 7089 | |
| 7090 | The obtained average PSNR is printed through the logging system. |
| 7091 | |
| 7092 | The filter stores the accumulated MSE (mean squared error) of each |
| 7093 | frame, and at the end of the processing it is averaged across all frames |
| 7094 | equally, and the following formula is applied to obtain the PSNR: |
| 7095 | |
| 7096 | @example |
| 7097 | PSNR = 10*log10(MAX^2/MSE) |
| 7098 | @end example |
| 7099 | |
| 7100 | Where MAX is the average of the maximum values of each component of the |
| 7101 | image. |
| 7102 | |
| 7103 | The description of the accepted parameters follows. |
| 7104 | |
| 7105 | @table @option |
| 7106 | @item stats_file, f |
| 7107 | If specified the filter will use the named file to save the PSNR of |
| 7108 | each individual frame. |
| 7109 | @end table |
| 7110 | |
| 7111 | The file printed if @var{stats_file} is selected, contains a sequence of |
| 7112 | key/value pairs of the form @var{key}:@var{value} for each compared |
| 7113 | couple of frames. |
| 7114 | |
| 7115 | A description of each shown parameter follows: |
| 7116 | |
| 7117 | @table @option |
| 7118 | @item n |
| 7119 | sequential number of the input frame, starting from 1 |
| 7120 | |
| 7121 | @item mse_avg |
| 7122 | Mean Square Error pixel-by-pixel average difference of the compared |
| 7123 | frames, averaged over all the image components. |
| 7124 | |
| 7125 | @item mse_y, mse_u, mse_v, mse_r, mse_g, mse_g, mse_a |
| 7126 | Mean Square Error pixel-by-pixel average difference of the compared |
| 7127 | frames for the component specified by the suffix. |
| 7128 | |
| 7129 | @item psnr_y, psnr_u, psnr_v, psnr_r, psnr_g, psnr_b, psnr_a |
| 7130 | Peak Signal to Noise ratio of the compared frames for the component |
| 7131 | specified by the suffix. |
| 7132 | @end table |
| 7133 | |
| 7134 | For example: |
| 7135 | @example |
| 7136 | movie=ref_movie.mpg, setpts=PTS-STARTPTS [main]; |
| 7137 | [main][ref] psnr="stats_file=stats.log" [out] |
| 7138 | @end example |
| 7139 | |
| 7140 | On this example the input file being processed is compared with the |
| 7141 | reference file @file{ref_movie.mpg}. The PSNR of each individual frame |
| 7142 | is stored in @file{stats.log}. |
| 7143 | |
| 7144 | @anchor{pullup} |
| 7145 | @section pullup |
| 7146 | |
| 7147 | Pulldown reversal (inverse telecine) filter, capable of handling mixed |
| 7148 | hard-telecine, 24000/1001 fps progressive, and 30000/1001 fps progressive |
| 7149 | content. |
| 7150 | |
| 7151 | The pullup filter is designed to take advantage of future context in making |
| 7152 | its decisions. This filter is stateless in the sense that it does not lock |
| 7153 | onto a pattern to follow, but it instead looks forward to the following |
| 7154 | fields in order to identify matches and rebuild progressive frames. |
| 7155 | |
| 7156 | To produce content with an even framerate, insert the fps filter after |
| 7157 | pullup, use @code{fps=24000/1001} if the input frame rate is 29.97fps, |
| 7158 | @code{fps=24} for 30fps and the (rare) telecined 25fps input. |
| 7159 | |
| 7160 | The filter accepts the following options: |
| 7161 | |
| 7162 | @table @option |
| 7163 | @item jl |
| 7164 | @item jr |
| 7165 | @item jt |
| 7166 | @item jb |
| 7167 | These options set the amount of "junk" to ignore at the left, right, top, and |
| 7168 | bottom of the image, respectively. Left and right are in units of 8 pixels, |
| 7169 | while top and bottom are in units of 2 lines. |
| 7170 | The default is 8 pixels on each side. |
| 7171 | |
| 7172 | @item sb |
| 7173 | Set the strict breaks. Setting this option to 1 will reduce the chances of |
| 7174 | filter generating an occasional mismatched frame, but it may also cause an |
| 7175 | excessive number of frames to be dropped during high motion sequences. |
| 7176 | Conversely, setting it to -1 will make filter match fields more easily. |
| 7177 | This may help processing of video where there is slight blurring between |
| 7178 | the fields, but may also cause there to be interlaced frames in the output. |
| 7179 | Default value is @code{0}. |
| 7180 | |
| 7181 | @item mp |
| 7182 | Set the metric plane to use. It accepts the following values: |
| 7183 | @table @samp |
| 7184 | @item l |
| 7185 | Use luma plane. |
| 7186 | |
| 7187 | @item u |
| 7188 | Use chroma blue plane. |
| 7189 | |
| 7190 | @item v |
| 7191 | Use chroma red plane. |
| 7192 | @end table |
| 7193 | |
| 7194 | This option may be set to use chroma plane instead of the default luma plane |
| 7195 | for doing filter's computations. This may improve accuracy on very clean |
| 7196 | source material, but more likely will decrease accuracy, especially if there |
| 7197 | is chroma noise (rainbow effect) or any grayscale video. |
| 7198 | The main purpose of setting @option{mp} to a chroma plane is to reduce CPU |
| 7199 | load and make pullup usable in realtime on slow machines. |
| 7200 | @end table |
| 7201 | |
| 7202 | For best results (without duplicated frames in the output file) it is |
| 7203 | necessary to change the output frame rate. For example, to inverse |
| 7204 | telecine NTSC input: |
| 7205 | @example |
| 7206 | ffmpeg -i input -vf pullup -r 24000/1001 ... |
| 7207 | @end example |
| 7208 | |
| 7209 | @section removelogo |
| 7210 | |
| 7211 | Suppress a TV station logo, using an image file to determine which |
| 7212 | pixels comprise the logo. It works by filling in the pixels that |
| 7213 | comprise the logo with neighboring pixels. |
| 7214 | |
| 7215 | The filter accepts the following options: |
| 7216 | |
| 7217 | @table @option |
| 7218 | @item filename, f |
| 7219 | Set the filter bitmap file, which can be any image format supported by |
| 7220 | libavformat. The width and height of the image file must match those of the |
| 7221 | video stream being processed. |
| 7222 | @end table |
| 7223 | |
| 7224 | Pixels in the provided bitmap image with a value of zero are not |
| 7225 | considered part of the logo, non-zero pixels are considered part of |
| 7226 | the logo. If you use white (255) for the logo and black (0) for the |
| 7227 | rest, you will be safe. For making the filter bitmap, it is |
| 7228 | recommended to take a screen capture of a black frame with the logo |
| 7229 | visible, and then using a threshold filter followed by the erode |
| 7230 | filter once or twice. |
| 7231 | |
| 7232 | If needed, little splotches can be fixed manually. Remember that if |
| 7233 | logo pixels are not covered, the filter quality will be much |
| 7234 | reduced. Marking too many pixels as part of the logo does not hurt as |
| 7235 | much, but it will increase the amount of blurring needed to cover over |
| 7236 | the image and will destroy more information than necessary, and extra |
| 7237 | pixels will slow things down on a large logo. |
| 7238 | |
| 7239 | @section rotate |
| 7240 | |
| 7241 | Rotate video by an arbitrary angle expressed in radians. |
| 7242 | |
| 7243 | The filter accepts the following options: |
| 7244 | |
| 7245 | A description of the optional parameters follows. |
| 7246 | @table @option |
| 7247 | @item angle, a |
| 7248 | Set an expression for the angle by which to rotate the input video |
| 7249 | clockwise, expressed as a number of radians. A negative value will |
| 7250 | result in a counter-clockwise rotation. By default it is set to "0". |
| 7251 | |
| 7252 | This expression is evaluated for each frame. |
| 7253 | |
| 7254 | @item out_w, ow |
| 7255 | Set the output width expression, default value is "iw". |
| 7256 | This expression is evaluated just once during configuration. |
| 7257 | |
| 7258 | @item out_h, oh |
| 7259 | Set the output height expression, default value is "ih". |
| 7260 | This expression is evaluated just once during configuration. |
| 7261 | |
| 7262 | @item bilinear |
| 7263 | Enable bilinear interpolation if set to 1, a value of 0 disables |
| 7264 | it. Default value is 1. |
| 7265 | |
| 7266 | @item fillcolor, c |
| 7267 | Set the color used to fill the output area not covered by the rotated |
| 7268 | image. For the generalsyntax of this option, check the "Color" section in the |
| 7269 | ffmpeg-utils manual. If the special value "none" is selected then no |
| 7270 | background is printed (useful for example if the background is never shown). |
| 7271 | |
| 7272 | Default value is "black". |
| 7273 | @end table |
| 7274 | |
| 7275 | The expressions for the angle and the output size can contain the |
| 7276 | following constants and functions: |
| 7277 | |
| 7278 | @table @option |
| 7279 | @item n |
| 7280 | sequential number of the input frame, starting from 0. It is always NAN |
| 7281 | before the first frame is filtered. |
| 7282 | |
| 7283 | @item t |
| 7284 | time in seconds of the input frame, it is set to 0 when the filter is |
| 7285 | configured. It is always NAN before the first frame is filtered. |
| 7286 | |
| 7287 | @item hsub |
| 7288 | @item vsub |
| 7289 | horizontal and vertical chroma subsample values. For example for the |
| 7290 | pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1. |
| 7291 | |
| 7292 | @item in_w, iw |
| 7293 | @item in_h, ih |
| 7294 | the input video width and height |
| 7295 | |
| 7296 | @item out_w, ow |
| 7297 | @item out_h, oh |
| 7298 | the output width and height, that is the size of the padded area as |
| 7299 | specified by the @var{width} and @var{height} expressions |
| 7300 | |
| 7301 | @item rotw(a) |
| 7302 | @item roth(a) |
| 7303 | the minimal width/height required for completely containing the input |
| 7304 | video rotated by @var{a} radians. |
| 7305 | |
| 7306 | These are only available when computing the @option{out_w} and |
| 7307 | @option{out_h} expressions. |
| 7308 | @end table |
| 7309 | |
| 7310 | @subsection Examples |
| 7311 | |
| 7312 | @itemize |
| 7313 | @item |
| 7314 | Rotate the input by PI/6 radians clockwise: |
| 7315 | @example |
| 7316 | rotate=PI/6 |
| 7317 | @end example |
| 7318 | |
| 7319 | @item |
| 7320 | Rotate the input by PI/6 radians counter-clockwise: |
| 7321 | @example |
| 7322 | rotate=-PI/6 |
| 7323 | @end example |
| 7324 | |
| 7325 | @item |
| 7326 | Rotate the input by 45 degrees clockwise: |
| 7327 | @example |
| 7328 | rotate=45*PI/180 |
| 7329 | @end example |
| 7330 | |
| 7331 | @item |
| 7332 | Apply a constant rotation with period T, starting from an angle of PI/3: |
| 7333 | @example |
| 7334 | rotate=PI/3+2*PI*t/T |
| 7335 | @end example |
| 7336 | |
| 7337 | @item |
| 7338 | Make the input video rotation oscillating with a period of T |
| 7339 | seconds and an amplitude of A radians: |
| 7340 | @example |
| 7341 | rotate=A*sin(2*PI/T*t) |
| 7342 | @end example |
| 7343 | |
| 7344 | @item |
| 7345 | Rotate the video, output size is chosen so that the whole rotating |
| 7346 | input video is always completely contained in the output: |
| 7347 | @example |
| 7348 | rotate='2*PI*t:ow=hypot(iw,ih):oh=ow' |
| 7349 | @end example |
| 7350 | |
| 7351 | @item |
| 7352 | Rotate the video, reduce the output size so that no background is ever |
| 7353 | shown: |
| 7354 | @example |
| 7355 | rotate=2*PI*t:ow='min(iw,ih)/sqrt(2)':oh=ow:c=none |
| 7356 | @end example |
| 7357 | @end itemize |
| 7358 | |
| 7359 | @subsection Commands |
| 7360 | |
| 7361 | The filter supports the following commands: |
| 7362 | |
| 7363 | @table @option |
| 7364 | @item a, angle |
| 7365 | Set the angle expression. |
| 7366 | The command accepts the same syntax of the corresponding option. |
| 7367 | |
| 7368 | If the specified expression is not valid, it is kept at its current |
| 7369 | value. |
| 7370 | @end table |
| 7371 | |
| 7372 | @section sab |
| 7373 | |
| 7374 | Apply Shape Adaptive Blur. |
| 7375 | |
| 7376 | The filter accepts the following options: |
| 7377 | |
| 7378 | @table @option |
| 7379 | @item luma_radius, lr |
| 7380 | Set luma blur filter strength, must be a value in range 0.1-4.0, default |
| 7381 | value is 1.0. A greater value will result in a more blurred image, and |
| 7382 | in slower processing. |
| 7383 | |
| 7384 | @item luma_pre_filter_radius, lpfr |
| 7385 | Set luma pre-filter radius, must be a value in the 0.1-2.0 range, default |
| 7386 | value is 1.0. |
| 7387 | |
| 7388 | @item luma_strength, ls |
| 7389 | Set luma maximum difference between pixels to still be considered, must |
| 7390 | be a value in the 0.1-100.0 range, default value is 1.0. |
| 7391 | |
| 7392 | @item chroma_radius, cr |
| 7393 | Set chroma blur filter strength, must be a value in range 0.1-4.0. A |
| 7394 | greater value will result in a more blurred image, and in slower |
| 7395 | processing. |
| 7396 | |
| 7397 | @item chroma_pre_filter_radius, cpfr |
| 7398 | Set chroma pre-filter radius, must be a value in the 0.1-2.0 range. |
| 7399 | |
| 7400 | @item chroma_strength, cs |
| 7401 | Set chroma maximum difference between pixels to still be considered, |
| 7402 | must be a value in the 0.1-100.0 range. |
| 7403 | @end table |
| 7404 | |
| 7405 | Each chroma option value, if not explicitly specified, is set to the |
| 7406 | corresponding luma option value. |
| 7407 | |
| 7408 | @anchor{scale} |
| 7409 | @section scale |
| 7410 | |
| 7411 | Scale (resize) the input video, using the libswscale library. |
| 7412 | |
| 7413 | The scale filter forces the output display aspect ratio to be the same |
| 7414 | of the input, by changing the output sample aspect ratio. |
| 7415 | |
| 7416 | If the input image format is different from the format requested by |
| 7417 | the next filter, the scale filter will convert the input to the |
| 7418 | requested format. |
| 7419 | |
| 7420 | @subsection Options |
| 7421 | The filter accepts the following options, or any of the options |
| 7422 | supported by the libswscale scaler. |
| 7423 | |
| 7424 | See @ref{scaler_options,,the ffmpeg-scaler manual,ffmpeg-scaler} for |
| 7425 | the complete list of scaler options. |
| 7426 | |
| 7427 | @table @option |
| 7428 | @item width, w |
| 7429 | @item height, h |
| 7430 | Set the output video dimension expression. Default value is the input |
| 7431 | dimension. |
| 7432 | |
| 7433 | If the value is 0, the input width is used for the output. |
| 7434 | |
| 7435 | If one of the values is -1, the scale filter will use a value that |
| 7436 | maintains the aspect ratio of the input image, calculated from the |
| 7437 | other specified dimension. If both of them are -1, the input size is |
| 7438 | used |
| 7439 | |
| 7440 | If one of the values is -n with n > 1, the scale filter will also use a value |
| 7441 | that maintains the aspect ratio of the input image, calculated from the other |
| 7442 | specified dimension. After that it will, however, make sure that the calculated |
| 7443 | dimension is divisible by n and adjust the value if necessary. |
| 7444 | |
| 7445 | See below for the list of accepted constants for use in the dimension |
| 7446 | expression. |
| 7447 | |
| 7448 | @item interl |
| 7449 | Set the interlacing mode. It accepts the following values: |
| 7450 | |
| 7451 | @table @samp |
| 7452 | @item 1 |
| 7453 | Force interlaced aware scaling. |
| 7454 | |
| 7455 | @item 0 |
| 7456 | Do not apply interlaced scaling. |
| 7457 | |
| 7458 | @item -1 |
| 7459 | Select interlaced aware scaling depending on whether the source frames |
| 7460 | are flagged as interlaced or not. |
| 7461 | @end table |
| 7462 | |
| 7463 | Default value is @samp{0}. |
| 7464 | |
| 7465 | @item flags |
| 7466 | Set libswscale scaling flags. See |
| 7467 | @ref{sws_flags,,the ffmpeg-scaler manual,ffmpeg-scaler} for the |
| 7468 | complete list of values. If not explicitly specified the filter applies |
| 7469 | the default flags. |
| 7470 | |
| 7471 | @item size, s |
| 7472 | Set the video size. For the syntax of this option, check the "Video size" |
| 7473 | section in the ffmpeg-utils manual. |
| 7474 | |
| 7475 | @item in_color_matrix |
| 7476 | @item out_color_matrix |
| 7477 | Set in/output YCbCr color space type. |
| 7478 | |
| 7479 | This allows the autodetected value to be overridden as well as allows forcing |
| 7480 | a specific value used for the output and encoder. |
| 7481 | |
| 7482 | If not specified, the color space type depends on the pixel format. |
| 7483 | |
| 7484 | Possible values: |
| 7485 | |
| 7486 | @table @samp |
| 7487 | @item auto |
| 7488 | Choose automatically. |
| 7489 | |
| 7490 | @item bt709 |
| 7491 | Format conforming to International Telecommunication Union (ITU) |
| 7492 | Recommendation BT.709. |
| 7493 | |
| 7494 | @item fcc |
| 7495 | Set color space conforming to the United States Federal Communications |
| 7496 | Commission (FCC) Code of Federal Regulations (CFR) Title 47 (2003) 73.682 (a). |
| 7497 | |
| 7498 | @item bt601 |
| 7499 | Set color space conforming to: |
| 7500 | |
| 7501 | @itemize |
| 7502 | @item |
| 7503 | ITU Radiocommunication Sector (ITU-R) Recommendation BT.601 |
| 7504 | |
| 7505 | @item |
| 7506 | ITU-R Rec. BT.470-6 (1998) Systems B, B1, and G |
| 7507 | |
| 7508 | @item |
| 7509 | Society of Motion Picture and Television Engineers (SMPTE) ST 170:2004 |
| 7510 | |
| 7511 | @end itemize |
| 7512 | |
| 7513 | @item smpte240m |
| 7514 | Set color space conforming to SMPTE ST 240:1999. |
| 7515 | @end table |
| 7516 | |
| 7517 | @item in_range |
| 7518 | @item out_range |
| 7519 | Set in/output YCbCr sample range. |
| 7520 | |
| 7521 | This allows the autodetected value to be overridden as well as allows forcing |
| 7522 | a specific value used for the output and encoder. If not specified, the |
| 7523 | range depends on the pixel format. Possible values: |
| 7524 | |
| 7525 | @table @samp |
| 7526 | @item auto |
| 7527 | Choose automatically. |
| 7528 | |
| 7529 | @item jpeg/full/pc |
| 7530 | Set full range (0-255 in case of 8-bit luma). |
| 7531 | |
| 7532 | @item mpeg/tv |
| 7533 | Set "MPEG" range (16-235 in case of 8-bit luma). |
| 7534 | @end table |
| 7535 | |
| 7536 | @item force_original_aspect_ratio |
| 7537 | Enable decreasing or increasing output video width or height if necessary to |
| 7538 | keep the original aspect ratio. Possible values: |
| 7539 | |
| 7540 | @table @samp |
| 7541 | @item disable |
| 7542 | Scale the video as specified and disable this feature. |
| 7543 | |
| 7544 | @item decrease |
| 7545 | The output video dimensions will automatically be decreased if needed. |
| 7546 | |
| 7547 | @item increase |
| 7548 | The output video dimensions will automatically be increased if needed. |
| 7549 | |
| 7550 | @end table |
| 7551 | |
| 7552 | One useful instance of this option is that when you know a specific device's |
| 7553 | maximum allowed resolution, you can use this to limit the output video to |
| 7554 | that, while retaining the aspect ratio. For example, device A allows |
| 7555 | 1280x720 playback, and your video is 1920x800. Using this option (set it to |
| 7556 | decrease) and specifying 1280x720 to the command line makes the output |
| 7557 | 1280x533. |
| 7558 | |
| 7559 | Please note that this is a different thing than specifying -1 for @option{w} |
| 7560 | or @option{h}, you still need to specify the output resolution for this option |
| 7561 | to work. |
| 7562 | |
| 7563 | @end table |
| 7564 | |
| 7565 | The values of the @option{w} and @option{h} options are expressions |
| 7566 | containing the following constants: |
| 7567 | |
| 7568 | @table @var |
| 7569 | @item in_w |
| 7570 | @item in_h |
| 7571 | The input width and height |
| 7572 | |
| 7573 | @item iw |
| 7574 | @item ih |
| 7575 | These are the same as @var{in_w} and @var{in_h}. |
| 7576 | |
| 7577 | @item out_w |
| 7578 | @item out_h |
| 7579 | The output (scaled) width and height |
| 7580 | |
| 7581 | @item ow |
| 7582 | @item oh |
| 7583 | These are the same as @var{out_w} and @var{out_h} |
| 7584 | |
| 7585 | @item a |
| 7586 | The same as @var{iw} / @var{ih} |
| 7587 | |
| 7588 | @item sar |
| 7589 | input sample aspect ratio |
| 7590 | |
| 7591 | @item dar |
| 7592 | The input display aspect ratio. Calculated from @code{(iw / ih) * sar}. |
| 7593 | |
| 7594 | @item hsub |
| 7595 | @item vsub |
| 7596 | horizontal and vertical input chroma subsample values. For example for the |
| 7597 | pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1. |
| 7598 | |
| 7599 | @item ohsub |
| 7600 | @item ovsub |
| 7601 | horizontal and vertical output chroma subsample values. For example for the |
| 7602 | pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1. |
| 7603 | @end table |
| 7604 | |
| 7605 | @subsection Examples |
| 7606 | |
| 7607 | @itemize |
| 7608 | @item |
| 7609 | Scale the input video to a size of 200x100 |
| 7610 | @example |
| 7611 | scale=w=200:h=100 |
| 7612 | @end example |
| 7613 | |
| 7614 | This is equivalent to: |
| 7615 | @example |
| 7616 | scale=200:100 |
| 7617 | @end example |
| 7618 | |
| 7619 | or: |
| 7620 | @example |
| 7621 | scale=200x100 |
| 7622 | @end example |
| 7623 | |
| 7624 | @item |
| 7625 | Specify a size abbreviation for the output size: |
| 7626 | @example |
| 7627 | scale=qcif |
| 7628 | @end example |
| 7629 | |
| 7630 | which can also be written as: |
| 7631 | @example |
| 7632 | scale=size=qcif |
| 7633 | @end example |
| 7634 | |
| 7635 | @item |
| 7636 | Scale the input to 2x: |
| 7637 | @example |
| 7638 | scale=w=2*iw:h=2*ih |
| 7639 | @end example |
| 7640 | |
| 7641 | @item |
| 7642 | The above is the same as: |
| 7643 | @example |
| 7644 | scale=2*in_w:2*in_h |
| 7645 | @end example |
| 7646 | |
| 7647 | @item |
| 7648 | Scale the input to 2x with forced interlaced scaling: |
| 7649 | @example |
| 7650 | scale=2*iw:2*ih:interl=1 |
| 7651 | @end example |
| 7652 | |
| 7653 | @item |
| 7654 | Scale the input to half size: |
| 7655 | @example |
| 7656 | scale=w=iw/2:h=ih/2 |
| 7657 | @end example |
| 7658 | |
| 7659 | @item |
| 7660 | Increase the width, and set the height to the same size: |
| 7661 | @example |
| 7662 | scale=3/2*iw:ow |
| 7663 | @end example |
| 7664 | |
| 7665 | @item |
| 7666 | Seek Greek harmony: |
| 7667 | @example |
| 7668 | scale=iw:1/PHI*iw |
| 7669 | scale=ih*PHI:ih |
| 7670 | @end example |
| 7671 | |
| 7672 | @item |
| 7673 | Increase the height, and set the width to 3/2 of the height: |
| 7674 | @example |
| 7675 | scale=w=3/2*oh:h=3/5*ih |
| 7676 | @end example |
| 7677 | |
| 7678 | @item |
| 7679 | Increase the size, making the size a multiple of the chroma |
| 7680 | subsample values: |
| 7681 | @example |
| 7682 | scale="trunc(3/2*iw/hsub)*hsub:trunc(3/2*ih/vsub)*vsub" |
| 7683 | @end example |
| 7684 | |
| 7685 | @item |
| 7686 | Increase the width to a maximum of 500 pixels, |
| 7687 | keeping the same aspect ratio as the input: |
| 7688 | @example |
| 7689 | scale=w='min(500\, iw*3/2):h=-1' |
| 7690 | @end example |
| 7691 | @end itemize |
| 7692 | |
| 7693 | @section separatefields |
| 7694 | |
| 7695 | The @code{separatefields} takes a frame-based video input and splits |
| 7696 | each frame into its components fields, producing a new half height clip |
| 7697 | with twice the frame rate and twice the frame count. |
| 7698 | |
| 7699 | This filter use field-dominance information in frame to decide which |
| 7700 | of each pair of fields to place first in the output. |
| 7701 | If it gets it wrong use @ref{setfield} filter before @code{separatefields} filter. |
| 7702 | |
| 7703 | @section setdar, setsar |
| 7704 | |
| 7705 | The @code{setdar} filter sets the Display Aspect Ratio for the filter |
| 7706 | output video. |
| 7707 | |
| 7708 | This is done by changing the specified Sample (aka Pixel) Aspect |
| 7709 | Ratio, according to the following equation: |
| 7710 | @example |
| 7711 | @var{DAR} = @var{HORIZONTAL_RESOLUTION} / @var{VERTICAL_RESOLUTION} * @var{SAR} |
| 7712 | @end example |
| 7713 | |
| 7714 | Keep in mind that the @code{setdar} filter does not modify the pixel |
| 7715 | dimensions of the video frame. Also, the display aspect ratio set by |
| 7716 | this filter may be changed by later filters in the filterchain, |
| 7717 | e.g. in case of scaling or if another "setdar" or a "setsar" filter is |
| 7718 | applied. |
| 7719 | |
| 7720 | The @code{setsar} filter sets the Sample (aka Pixel) Aspect Ratio for |
| 7721 | the filter output video. |
| 7722 | |
| 7723 | Note that as a consequence of the application of this filter, the |
| 7724 | output display aspect ratio will change according to the equation |
| 7725 | above. |
| 7726 | |
| 7727 | Keep in mind that the sample aspect ratio set by the @code{setsar} |
| 7728 | filter may be changed by later filters in the filterchain, e.g. if |
| 7729 | another "setsar" or a "setdar" filter is applied. |
| 7730 | |
| 7731 | It accepts the following parameters: |
| 7732 | |
| 7733 | @table @option |
| 7734 | @item r, ratio, dar (@code{setdar} only), sar (@code{setsar} only) |
| 7735 | Set the aspect ratio used by the filter. |
| 7736 | |
| 7737 | The parameter can be a floating point number string, an expression, or |
| 7738 | a string of the form @var{num}:@var{den}, where @var{num} and |
| 7739 | @var{den} are the numerator and denominator of the aspect ratio. If |
| 7740 | the parameter is not specified, it is assumed the value "0". |
| 7741 | In case the form "@var{num}:@var{den}" is used, the @code{:} character |
| 7742 | should be escaped. |
| 7743 | |
| 7744 | @item max |
| 7745 | Set the maximum integer value to use for expressing numerator and |
| 7746 | denominator when reducing the expressed aspect ratio to a rational. |
| 7747 | Default value is @code{100}. |
| 7748 | |
| 7749 | @end table |
| 7750 | |
| 7751 | The parameter @var{sar} is an expression containing |
| 7752 | the following constants: |
| 7753 | |
| 7754 | @table @option |
| 7755 | @item E, PI, PHI |
| 7756 | These are approximated values for the mathematical constants e |
| 7757 | (Euler's number), pi (Greek pi), and phi (the golden ratio). |
| 7758 | |
| 7759 | @item w, h |
| 7760 | The input width and height. |
| 7761 | |
| 7762 | @item a |
| 7763 | These are the same as @var{w} / @var{h}. |
| 7764 | |
| 7765 | @item sar |
| 7766 | The input sample aspect ratio. |
| 7767 | |
| 7768 | @item dar |
| 7769 | The input display aspect ratio. It is the same as |
| 7770 | (@var{w} / @var{h}) * @var{sar}. |
| 7771 | |
| 7772 | @item hsub, vsub |
| 7773 | Horizontal and vertical chroma subsample values. For example, for the |
| 7774 | pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1. |
| 7775 | @end table |
| 7776 | |
| 7777 | @subsection Examples |
| 7778 | |
| 7779 | @itemize |
| 7780 | |
| 7781 | @item |
| 7782 | To change the display aspect ratio to 16:9, specify one of the following: |
| 7783 | @example |
| 7784 | setdar=dar=1.77777 |
| 7785 | setdar=dar=16/9 |
| 7786 | setdar=dar=1.77777 |
| 7787 | @end example |
| 7788 | |
| 7789 | @item |
| 7790 | To change the sample aspect ratio to 10:11, specify: |
| 7791 | @example |
| 7792 | setsar=sar=10/11 |
| 7793 | @end example |
| 7794 | |
| 7795 | @item |
| 7796 | To set a display aspect ratio of 16:9, and specify a maximum integer value of |
| 7797 | 1000 in the aspect ratio reduction, use the command: |
| 7798 | @example |
| 7799 | setdar=ratio=16/9:max=1000 |
| 7800 | @end example |
| 7801 | |
| 7802 | @end itemize |
| 7803 | |
| 7804 | @anchor{setfield} |
| 7805 | @section setfield |
| 7806 | |
| 7807 | Force field for the output video frame. |
| 7808 | |
| 7809 | The @code{setfield} filter marks the interlace type field for the |
| 7810 | output frames. It does not change the input frame, but only sets the |
| 7811 | corresponding property, which affects how the frame is treated by |
| 7812 | following filters (e.g. @code{fieldorder} or @code{yadif}). |
| 7813 | |
| 7814 | The filter accepts the following options: |
| 7815 | |
| 7816 | @table @option |
| 7817 | |
| 7818 | @item mode |
| 7819 | Available values are: |
| 7820 | |
| 7821 | @table @samp |
| 7822 | @item auto |
| 7823 | Keep the same field property. |
| 7824 | |
| 7825 | @item bff |
| 7826 | Mark the frame as bottom-field-first. |
| 7827 | |
| 7828 | @item tff |
| 7829 | Mark the frame as top-field-first. |
| 7830 | |
| 7831 | @item prog |
| 7832 | Mark the frame as progressive. |
| 7833 | @end table |
| 7834 | @end table |
| 7835 | |
| 7836 | @section showinfo |
| 7837 | |
| 7838 | Show a line containing various information for each input video frame. |
| 7839 | The input video is not modified. |
| 7840 | |
| 7841 | The shown line contains a sequence of key/value pairs of the form |
| 7842 | @var{key}:@var{value}. |
| 7843 | |
| 7844 | The following values are shown in the output: |
| 7845 | |
| 7846 | @table @option |
| 7847 | @item n |
| 7848 | The (sequential) number of the input frame, starting from 0. |
| 7849 | |
| 7850 | @item pts |
| 7851 | The Presentation TimeStamp of the input frame, expressed as a number of |
| 7852 | time base units. The time base unit depends on the filter input pad. |
| 7853 | |
| 7854 | @item pts_time |
| 7855 | The Presentation TimeStamp of the input frame, expressed as a number of |
| 7856 | seconds. |
| 7857 | |
| 7858 | @item pos |
| 7859 | The position of the frame in the input stream, or -1 if this information is |
| 7860 | unavailable and/or meaningless (for example in case of synthetic video). |
| 7861 | |
| 7862 | @item fmt |
| 7863 | The pixel format name. |
| 7864 | |
| 7865 | @item sar |
| 7866 | The sample aspect ratio of the input frame, expressed in the form |
| 7867 | @var{num}/@var{den}. |
| 7868 | |
| 7869 | @item s |
| 7870 | The size of the input frame. For the syntax of this option, check the "Video size" |
| 7871 | section in the ffmpeg-utils manual. |
| 7872 | |
| 7873 | @item i |
| 7874 | The type of interlaced mode ("P" for "progressive", "T" for top field first, "B" |
| 7875 | for bottom field first). |
| 7876 | |
| 7877 | @item iskey |
| 7878 | This is 1 if the frame is a key frame, 0 otherwise. |
| 7879 | |
| 7880 | @item type |
| 7881 | The picture type of the input frame ("I" for an I-frame, "P" for a |
| 7882 | P-frame, "B" for a B-frame, or "?" for an unknown type). |
| 7883 | Also refer to the documentation of the @code{AVPictureType} enum and of |
| 7884 | the @code{av_get_picture_type_char} function defined in |
| 7885 | @file{libavutil/avutil.h}. |
| 7886 | |
| 7887 | @item checksum |
| 7888 | The Adler-32 checksum (printed in hexadecimal) of all the planes of the input frame. |
| 7889 | |
| 7890 | @item plane_checksum |
| 7891 | The Adler-32 checksum (printed in hexadecimal) of each plane of the input frame, |
| 7892 | expressed in the form "[@var{c0} @var{c1} @var{c2} @var{c3}]". |
| 7893 | @end table |
| 7894 | |
| 7895 | @section shuffleplanes |
| 7896 | |
| 7897 | Reorder and/or duplicate video planes. |
| 7898 | |
| 7899 | It accepts the following parameters: |
| 7900 | |
| 7901 | @table @option |
| 7902 | |
| 7903 | @item map0 |
| 7904 | The index of the input plane to be used as the first output plane. |
| 7905 | |
| 7906 | @item map1 |
| 7907 | The index of the input plane to be used as the second output plane. |
| 7908 | |
| 7909 | @item map2 |
| 7910 | The index of the input plane to be used as the third output plane. |
| 7911 | |
| 7912 | @item map3 |
| 7913 | The index of the input plane to be used as the fourth output plane. |
| 7914 | |
| 7915 | @end table |
| 7916 | |
| 7917 | The first plane has the index 0. The default is to keep the input unchanged. |
| 7918 | |
| 7919 | Swap the second and third planes of the input: |
| 7920 | @example |
| 7921 | ffmpeg -i INPUT -vf shuffleplanes=0:2:1:3 OUTPUT |
| 7922 | @end example |
| 7923 | |
| 7924 | @section signalstats |
| 7925 | Evaluate various visual metrics that assist in determining issues associated |
| 7926 | with the digitization of analog video media. |
| 7927 | |
| 7928 | By default the filter will log these metadata values: |
| 7929 | |
| 7930 | @table @option |
| 7931 | @item YMIN |
| 7932 | Display the minimal Y value contained within the input frame. Expressed in |
| 7933 | range of [0-255]. |
| 7934 | |
| 7935 | @item YLOW |
| 7936 | Display the Y value at the 10% percentile within the input frame. Expressed in |
| 7937 | range of [0-255]. |
| 7938 | |
| 7939 | @item YAVG |
| 7940 | Display the average Y value within the input frame. Expressed in range of |
| 7941 | [0-255]. |
| 7942 | |
| 7943 | @item YHIGH |
| 7944 | Display the Y value at the 90% percentile within the input frame. Expressed in |
| 7945 | range of [0-255]. |
| 7946 | |
| 7947 | @item YMAX |
| 7948 | Display the maximum Y value contained within the input frame. Expressed in |
| 7949 | range of [0-255]. |
| 7950 | |
| 7951 | @item UMIN |
| 7952 | Display the minimal U value contained within the input frame. Expressed in |
| 7953 | range of [0-255]. |
| 7954 | |
| 7955 | @item ULOW |
| 7956 | Display the U value at the 10% percentile within the input frame. Expressed in |
| 7957 | range of [0-255]. |
| 7958 | |
| 7959 | @item UAVG |
| 7960 | Display the average U value within the input frame. Expressed in range of |
| 7961 | [0-255]. |
| 7962 | |
| 7963 | @item UHIGH |
| 7964 | Display the U value at the 90% percentile within the input frame. Expressed in |
| 7965 | range of [0-255]. |
| 7966 | |
| 7967 | @item UMAX |
| 7968 | Display the maximum U value contained within the input frame. Expressed in |
| 7969 | range of [0-255]. |
| 7970 | |
| 7971 | @item VMIN |
| 7972 | Display the minimal V value contained within the input frame. Expressed in |
| 7973 | range of [0-255]. |
| 7974 | |
| 7975 | @item VLOW |
| 7976 | Display the V value at the 10% percentile within the input frame. Expressed in |
| 7977 | range of [0-255]. |
| 7978 | |
| 7979 | @item VAVG |
| 7980 | Display the average V value within the input frame. Expressed in range of |
| 7981 | [0-255]. |
| 7982 | |
| 7983 | @item VHIGH |
| 7984 | Display the V value at the 90% percentile within the input frame. Expressed in |
| 7985 | range of [0-255]. |
| 7986 | |
| 7987 | @item VMAX |
| 7988 | Display the maximum V value contained within the input frame. Expressed in |
| 7989 | range of [0-255]. |
| 7990 | |
| 7991 | @item SATMIN |
| 7992 | Display the minimal saturation value contained within the input frame. |
| 7993 | Expressed in range of [0-~181.02]. |
| 7994 | |
| 7995 | @item SATLOW |
| 7996 | Display the saturation value at the 10% percentile within the input frame. |
| 7997 | Expressed in range of [0-~181.02]. |
| 7998 | |
| 7999 | @item SATAVG |
| 8000 | Display the average saturation value within the input frame. Expressed in range |
| 8001 | of [0-~181.02]. |
| 8002 | |
| 8003 | @item SATHIGH |
| 8004 | Display the saturation value at the 90% percentile within the input frame. |
| 8005 | Expressed in range of [0-~181.02]. |
| 8006 | |
| 8007 | @item SATMAX |
| 8008 | Display the maximum saturation value contained within the input frame. |
| 8009 | Expressed in range of [0-~181.02]. |
| 8010 | |
| 8011 | @item HUEMED |
| 8012 | Display the median value for hue within the input frame. Expressed in range of |
| 8013 | [0-360]. |
| 8014 | |
| 8015 | @item HUEAVG |
| 8016 | Display the average value for hue within the input frame. Expressed in range of |
| 8017 | [0-360]. |
| 8018 | |
| 8019 | @item YDIF |
| 8020 | Display the average of sample value difference between all values of the Y |
| 8021 | plane in the current frame and corresponding values of the previous input frame. |
| 8022 | Expressed in range of [0-255]. |
| 8023 | |
| 8024 | @item UDIF |
| 8025 | Display the average of sample value difference between all values of the U |
| 8026 | plane in the current frame and corresponding values of the previous input frame. |
| 8027 | Expressed in range of [0-255]. |
| 8028 | |
| 8029 | @item VDIF |
| 8030 | Display the average of sample value difference between all values of the V |
| 8031 | plane in the current frame and corresponding values of the previous input frame. |
| 8032 | Expressed in range of [0-255]. |
| 8033 | @end table |
| 8034 | |
| 8035 | The filter accepts the following options: |
| 8036 | |
| 8037 | @table @option |
| 8038 | @item stat |
| 8039 | @item out |
| 8040 | |
| 8041 | @option{stat} specify an additional form of image analysis. |
| 8042 | @option{out} output video with the specified type of pixel highlighted. |
| 8043 | |
| 8044 | Both options accept the following values: |
| 8045 | |
| 8046 | @table @samp |
| 8047 | @item tout |
| 8048 | Identify @var{temporal outliers} pixels. A @var{temporal outlier} is a pixel |
| 8049 | unlike the neighboring pixels of the same field. Examples of temporal outliers |
| 8050 | include the results of video dropouts, head clogs, or tape tracking issues. |
| 8051 | |
| 8052 | @item vrep |
| 8053 | Identify @var{vertical line repetition}. Vertical line repetition includes |
| 8054 | similar rows of pixels within a frame. In born-digital video vertical line |
| 8055 | repetition is common, but this pattern is uncommon in video digitized from an |
| 8056 | analog source. When it occurs in video that results from the digitization of an |
| 8057 | analog source it can indicate concealment from a dropout compensator. |
| 8058 | |
| 8059 | @item brng |
| 8060 | Identify pixels that fall outside of legal broadcast range. |
| 8061 | @end table |
| 8062 | |
| 8063 | @item color, c |
| 8064 | Set the highlight color for the @option{out} option. The default color is |
| 8065 | yellow. |
| 8066 | @end table |
| 8067 | |
| 8068 | @subsection Examples |
| 8069 | |
| 8070 | @itemize |
| 8071 | @item |
| 8072 | Output data of various video metrics: |
| 8073 | @example |
| 8074 | ffprobe -f lavfi movie=example.mov,signalstats="stat=tout+vrep+brng" -show_frames |
| 8075 | @end example |
| 8076 | |
| 8077 | @item |
| 8078 | Output specific data about the minimum and maximum values of the Y plane per frame: |
| 8079 | @example |
| 8080 | ffprobe -f lavfi movie=example.mov,signalstats -show_entries frame_tags=lavfi.signalstats.YMAX,lavfi.signalstats.YMIN |
| 8081 | @end example |
| 8082 | |
| 8083 | @item |
| 8084 | Playback video while highlighting pixels that are outside of broadcast range in red. |
| 8085 | @example |
| 8086 | ffplay example.mov -vf signalstats="out=brng:color=red" |
| 8087 | @end example |
| 8088 | |
| 8089 | @item |
| 8090 | Playback video with signalstats metadata drawn over the frame. |
| 8091 | @example |
| 8092 | ffplay example.mov -vf signalstats=stat=brng+vrep+tout,drawtext=fontfile=FreeSerif.ttf:textfile=signalstat_drawtext.txt |
| 8093 | @end example |
| 8094 | |
| 8095 | The contents of signalstat_drawtext.txt used in the command are: |
| 8096 | @example |
| 8097 | time %@{pts:hms@} |
| 8098 | Y (%@{metadata:lavfi.signalstats.YMIN@}-%@{metadata:lavfi.signalstats.YMAX@}) |
| 8099 | U (%@{metadata:lavfi.signalstats.UMIN@}-%@{metadata:lavfi.signalstats.UMAX@}) |
| 8100 | V (%@{metadata:lavfi.signalstats.VMIN@}-%@{metadata:lavfi.signalstats.VMAX@}) |
| 8101 | saturation maximum: %@{metadata:lavfi.signalstats.SATMAX@} |
| 8102 | |
| 8103 | @end example |
| 8104 | @end itemize |
| 8105 | |
| 8106 | @anchor{smartblur} |
| 8107 | @section smartblur |
| 8108 | |
| 8109 | Blur the input video without impacting the outlines. |
| 8110 | |
| 8111 | It accepts the following options: |
| 8112 | |
| 8113 | @table @option |
| 8114 | @item luma_radius, lr |
| 8115 | Set the luma radius. The option value must be a float number in |
| 8116 | the range [0.1,5.0] that specifies the variance of the gaussian filter |
| 8117 | used to blur the image (slower if larger). Default value is 1.0. |
| 8118 | |
| 8119 | @item luma_strength, ls |
| 8120 | Set the luma strength. The option value must be a float number |
| 8121 | in the range [-1.0,1.0] that configures the blurring. A value included |
| 8122 | in [0.0,1.0] will blur the image whereas a value included in |
| 8123 | [-1.0,0.0] will sharpen the image. Default value is 1.0. |
| 8124 | |
| 8125 | @item luma_threshold, lt |
| 8126 | Set the luma threshold used as a coefficient to determine |
| 8127 | whether a pixel should be blurred or not. The option value must be an |
| 8128 | integer in the range [-30,30]. A value of 0 will filter all the image, |
| 8129 | a value included in [0,30] will filter flat areas and a value included |
| 8130 | in [-30,0] will filter edges. Default value is 0. |
| 8131 | |
| 8132 | @item chroma_radius, cr |
| 8133 | Set the chroma radius. The option value must be a float number in |
| 8134 | the range [0.1,5.0] that specifies the variance of the gaussian filter |
| 8135 | used to blur the image (slower if larger). Default value is 1.0. |
| 8136 | |
| 8137 | @item chroma_strength, cs |
| 8138 | Set the chroma strength. The option value must be a float number |
| 8139 | in the range [-1.0,1.0] that configures the blurring. A value included |
| 8140 | in [0.0,1.0] will blur the image whereas a value included in |
| 8141 | [-1.0,0.0] will sharpen the image. Default value is 1.0. |
| 8142 | |
| 8143 | @item chroma_threshold, ct |
| 8144 | Set the chroma threshold used as a coefficient to determine |
| 8145 | whether a pixel should be blurred or not. The option value must be an |
| 8146 | integer in the range [-30,30]. A value of 0 will filter all the image, |
| 8147 | a value included in [0,30] will filter flat areas and a value included |
| 8148 | in [-30,0] will filter edges. Default value is 0. |
| 8149 | @end table |
| 8150 | |
| 8151 | If a chroma option is not explicitly set, the corresponding luma value |
| 8152 | is set. |
| 8153 | |
| 8154 | @section stereo3d |
| 8155 | |
| 8156 | Convert between different stereoscopic image formats. |
| 8157 | |
| 8158 | The filters accept the following options: |
| 8159 | |
| 8160 | @table @option |
| 8161 | @item in |
| 8162 | Set stereoscopic image format of input. |
| 8163 | |
| 8164 | Available values for input image formats are: |
| 8165 | @table @samp |
| 8166 | @item sbsl |
| 8167 | side by side parallel (left eye left, right eye right) |
| 8168 | |
| 8169 | @item sbsr |
| 8170 | side by side crosseye (right eye left, left eye right) |
| 8171 | |
| 8172 | @item sbs2l |
| 8173 | side by side parallel with half width resolution |
| 8174 | (left eye left, right eye right) |
| 8175 | |
| 8176 | @item sbs2r |
| 8177 | side by side crosseye with half width resolution |
| 8178 | (right eye left, left eye right) |
| 8179 | |
| 8180 | @item abl |
| 8181 | above-below (left eye above, right eye below) |
| 8182 | |
| 8183 | @item abr |
| 8184 | above-below (right eye above, left eye below) |
| 8185 | |
| 8186 | @item ab2l |
| 8187 | above-below with half height resolution |
| 8188 | (left eye above, right eye below) |
| 8189 | |
| 8190 | @item ab2r |
| 8191 | above-below with half height resolution |
| 8192 | (right eye above, left eye below) |
| 8193 | |
| 8194 | @item al |
| 8195 | alternating frames (left eye first, right eye second) |
| 8196 | |
| 8197 | @item ar |
| 8198 | alternating frames (right eye first, left eye second) |
| 8199 | |
| 8200 | Default value is @samp{sbsl}. |
| 8201 | @end table |
| 8202 | |
| 8203 | @item out |
| 8204 | Set stereoscopic image format of output. |
| 8205 | |
| 8206 | Available values for output image formats are all the input formats as well as: |
| 8207 | @table @samp |
| 8208 | @item arbg |
| 8209 | anaglyph red/blue gray |
| 8210 | (red filter on left eye, blue filter on right eye) |
| 8211 | |
| 8212 | @item argg |
| 8213 | anaglyph red/green gray |
| 8214 | (red filter on left eye, green filter on right eye) |
| 8215 | |
| 8216 | @item arcg |
| 8217 | anaglyph red/cyan gray |
| 8218 | (red filter on left eye, cyan filter on right eye) |
| 8219 | |
| 8220 | @item arch |
| 8221 | anaglyph red/cyan half colored |
| 8222 | (red filter on left eye, cyan filter on right eye) |
| 8223 | |
| 8224 | @item arcc |
| 8225 | anaglyph red/cyan color |
| 8226 | (red filter on left eye, cyan filter on right eye) |
| 8227 | |
| 8228 | @item arcd |
| 8229 | anaglyph red/cyan color optimized with the least squares projection of dubois |
| 8230 | (red filter on left eye, cyan filter on right eye) |
| 8231 | |
| 8232 | @item agmg |
| 8233 | anaglyph green/magenta gray |
| 8234 | (green filter on left eye, magenta filter on right eye) |
| 8235 | |
| 8236 | @item agmh |
| 8237 | anaglyph green/magenta half colored |
| 8238 | (green filter on left eye, magenta filter on right eye) |
| 8239 | |
| 8240 | @item agmc |
| 8241 | anaglyph green/magenta colored |
| 8242 | (green filter on left eye, magenta filter on right eye) |
| 8243 | |
| 8244 | @item agmd |
| 8245 | anaglyph green/magenta color optimized with the least squares projection of dubois |
| 8246 | (green filter on left eye, magenta filter on right eye) |
| 8247 | |
| 8248 | @item aybg |
| 8249 | anaglyph yellow/blue gray |
| 8250 | (yellow filter on left eye, blue filter on right eye) |
| 8251 | |
| 8252 | @item aybh |
| 8253 | anaglyph yellow/blue half colored |
| 8254 | (yellow filter on left eye, blue filter on right eye) |
| 8255 | |
| 8256 | @item aybc |
| 8257 | anaglyph yellow/blue colored |
| 8258 | (yellow filter on left eye, blue filter on right eye) |
| 8259 | |
| 8260 | @item aybd |
| 8261 | anaglyph yellow/blue color optimized with the least squares projection of dubois |
| 8262 | (yellow filter on left eye, blue filter on right eye) |
| 8263 | |
| 8264 | @item irl |
| 8265 | interleaved rows (left eye has top row, right eye starts on next row) |
| 8266 | |
| 8267 | @item irr |
| 8268 | interleaved rows (right eye has top row, left eye starts on next row) |
| 8269 | |
| 8270 | @item ml |
| 8271 | mono output (left eye only) |
| 8272 | |
| 8273 | @item mr |
| 8274 | mono output (right eye only) |
| 8275 | @end table |
| 8276 | |
| 8277 | Default value is @samp{arcd}. |
| 8278 | @end table |
| 8279 | |
| 8280 | @subsection Examples |
| 8281 | |
| 8282 | @itemize |
| 8283 | @item |
| 8284 | Convert input video from side by side parallel to anaglyph yellow/blue dubois: |
| 8285 | @example |
| 8286 | stereo3d=sbsl:aybd |
| 8287 | @end example |
| 8288 | |
| 8289 | @item |
| 8290 | Convert input video from above bellow (left eye above, right eye below) to side by side crosseye. |
| 8291 | @example |
| 8292 | stereo3d=abl:sbsr |
| 8293 | @end example |
| 8294 | @end itemize |
| 8295 | |
| 8296 | @section spp |
| 8297 | |
| 8298 | Apply a simple postprocessing filter that compresses and decompresses the image |
| 8299 | at several (or - in the case of @option{quality} level @code{6} - all) shifts |
| 8300 | and average the results. |
| 8301 | |
| 8302 | The filter accepts the following options: |
| 8303 | |
| 8304 | @table @option |
| 8305 | @item quality |
| 8306 | Set quality. This option defines the number of levels for averaging. It accepts |
| 8307 | an integer in the range 0-6. If set to @code{0}, the filter will have no |
| 8308 | effect. A value of @code{6} means the higher quality. For each increment of |
| 8309 | that value the speed drops by a factor of approximately 2. Default value is |
| 8310 | @code{3}. |
| 8311 | |
| 8312 | @item qp |
| 8313 | Force a constant quantization parameter. If not set, the filter will use the QP |
| 8314 | from the video stream (if available). |
| 8315 | |
| 8316 | @item mode |
| 8317 | Set thresholding mode. Available modes are: |
| 8318 | |
| 8319 | @table @samp |
| 8320 | @item hard |
| 8321 | Set hard thresholding (default). |
| 8322 | @item soft |
| 8323 | Set soft thresholding (better de-ringing effect, but likely blurrier). |
| 8324 | @end table |
| 8325 | |
| 8326 | @item use_bframe_qp |
| 8327 | Enable the use of the QP from the B-Frames if set to @code{1}. Using this |
| 8328 | option may cause flicker since the B-Frames have often larger QP. Default is |
| 8329 | @code{0} (not enabled). |
| 8330 | @end table |
| 8331 | |
| 8332 | @anchor{subtitles} |
| 8333 | @section subtitles |
| 8334 | |
| 8335 | Draw subtitles on top of input video using the libass library. |
| 8336 | |
| 8337 | To enable compilation of this filter you need to configure FFmpeg with |
| 8338 | @code{--enable-libass}. This filter also requires a build with libavcodec and |
| 8339 | libavformat to convert the passed subtitles file to ASS (Advanced Substation |
| 8340 | Alpha) subtitles format. |
| 8341 | |
| 8342 | The filter accepts the following options: |
| 8343 | |
| 8344 | @table @option |
| 8345 | @item filename, f |
| 8346 | Set the filename of the subtitle file to read. It must be specified. |
| 8347 | |
| 8348 | @item original_size |
| 8349 | Specify the size of the original video, the video for which the ASS file |
| 8350 | was composed. For the syntax of this option, check the "Video size" section in |
| 8351 | the ffmpeg-utils manual. Due to a misdesign in ASS aspect ratio arithmetic, |
| 8352 | this is necessary to correctly scale the fonts if the aspect ratio has been |
| 8353 | changed. |
| 8354 | |
| 8355 | @item charenc |
| 8356 | Set subtitles input character encoding. @code{subtitles} filter only. Only |
| 8357 | useful if not UTF-8. |
| 8358 | |
| 8359 | @item stream_index, si |
| 8360 | Set subtitles stream index. @code{subtitles} filter only. |
| 8361 | @end table |
| 8362 | |
| 8363 | If the first key is not specified, it is assumed that the first value |
| 8364 | specifies the @option{filename}. |
| 8365 | |
| 8366 | For example, to render the file @file{sub.srt} on top of the input |
| 8367 | video, use the command: |
| 8368 | @example |
| 8369 | subtitles=sub.srt |
| 8370 | @end example |
| 8371 | |
| 8372 | which is equivalent to: |
| 8373 | @example |
| 8374 | subtitles=filename=sub.srt |
| 8375 | @end example |
| 8376 | |
| 8377 | To render the default subtitles stream from file @file{video.mkv}, use: |
| 8378 | @example |
| 8379 | subtitles=video.mkv |
| 8380 | @end example |
| 8381 | |
| 8382 | To render the second subtitles stream from that file, use: |
| 8383 | @example |
| 8384 | subtitles=video.mkv:si=1 |
| 8385 | @end example |
| 8386 | |
| 8387 | @section super2xsai |
| 8388 | |
| 8389 | Scale the input by 2x and smooth using the Super2xSaI (Scale and |
| 8390 | Interpolate) pixel art scaling algorithm. |
| 8391 | |
| 8392 | Useful for enlarging pixel art images without reducing sharpness. |
| 8393 | |
| 8394 | @section swapuv |
| 8395 | Swap U & V plane. |
| 8396 | |
| 8397 | @section telecine |
| 8398 | |
| 8399 | Apply telecine process to the video. |
| 8400 | |
| 8401 | This filter accepts the following options: |
| 8402 | |
| 8403 | @table @option |
| 8404 | @item first_field |
| 8405 | @table @samp |
| 8406 | @item top, t |
| 8407 | top field first |
| 8408 | @item bottom, b |
| 8409 | bottom field first |
| 8410 | The default value is @code{top}. |
| 8411 | @end table |
| 8412 | |
| 8413 | @item pattern |
| 8414 | A string of numbers representing the pulldown pattern you wish to apply. |
| 8415 | The default value is @code{23}. |
| 8416 | @end table |
| 8417 | |
| 8418 | @example |
| 8419 | Some typical patterns: |
| 8420 | |
| 8421 | NTSC output (30i): |
| 8422 | 27.5p: 32222 |
| 8423 | 24p: 23 (classic) |
| 8424 | 24p: 2332 (preferred) |
| 8425 | 20p: 33 |
| 8426 | 18p: 334 |
| 8427 | 16p: 3444 |
| 8428 | |
| 8429 | PAL output (25i): |
| 8430 | 27.5p: 12222 |
| 8431 | 24p: 222222222223 ("Euro pulldown") |
| 8432 | 16.67p: 33 |
| 8433 | 16p: 33333334 |
| 8434 | @end example |
| 8435 | |
| 8436 | @section thumbnail |
| 8437 | Select the most representative frame in a given sequence of consecutive frames. |
| 8438 | |
| 8439 | The filter accepts the following options: |
| 8440 | |
| 8441 | @table @option |
| 8442 | @item n |
| 8443 | Set the frames batch size to analyze; in a set of @var{n} frames, the filter |
| 8444 | will pick one of them, and then handle the next batch of @var{n} frames until |
| 8445 | the end. Default is @code{100}. |
| 8446 | @end table |
| 8447 | |
| 8448 | Since the filter keeps track of the whole frames sequence, a bigger @var{n} |
| 8449 | value will result in a higher memory usage, so a high value is not recommended. |
| 8450 | |
| 8451 | @subsection Examples |
| 8452 | |
| 8453 | @itemize |
| 8454 | @item |
| 8455 | Extract one picture each 50 frames: |
| 8456 | @example |
| 8457 | thumbnail=50 |
| 8458 | @end example |
| 8459 | |
| 8460 | @item |
| 8461 | Complete example of a thumbnail creation with @command{ffmpeg}: |
| 8462 | @example |
| 8463 | ffmpeg -i in.avi -vf thumbnail,scale=300:200 -frames:v 1 out.png |
| 8464 | @end example |
| 8465 | @end itemize |
| 8466 | |
| 8467 | @section tile |
| 8468 | |
| 8469 | Tile several successive frames together. |
| 8470 | |
| 8471 | The filter accepts the following options: |
| 8472 | |
| 8473 | @table @option |
| 8474 | |
| 8475 | @item layout |
| 8476 | Set the grid size (i.e. the number of lines and columns). For the syntax of |
| 8477 | this option, check the "Video size" section in the ffmpeg-utils manual. |
| 8478 | |
| 8479 | @item nb_frames |
| 8480 | Set the maximum number of frames to render in the given area. It must be less |
| 8481 | than or equal to @var{w}x@var{h}. The default value is @code{0}, meaning all |
| 8482 | the area will be used. |
| 8483 | |
| 8484 | @item margin |
| 8485 | Set the outer border margin in pixels. |
| 8486 | |
| 8487 | @item padding |
| 8488 | Set the inner border thickness (i.e. the number of pixels between frames). For |
| 8489 | more advanced padding options (such as having different values for the edges), |
| 8490 | refer to the pad video filter. |
| 8491 | |
| 8492 | @item color |
| 8493 | Specify the color of the unused areaFor the syntax of this option, check the |
| 8494 | "Color" section in the ffmpeg-utils manual. The default value of @var{color} |
| 8495 | is "black". |
| 8496 | @end table |
| 8497 | |
| 8498 | @subsection Examples |
| 8499 | |
| 8500 | @itemize |
| 8501 | @item |
| 8502 | Produce 8x8 PNG tiles of all keyframes (@option{-skip_frame nokey}) in a movie: |
| 8503 | @example |
| 8504 | ffmpeg -skip_frame nokey -i file.avi -vf 'scale=128:72,tile=8x8' -an -vsync 0 keyframes%03d.png |
| 8505 | @end example |
| 8506 | The @option{-vsync 0} is necessary to prevent @command{ffmpeg} from |
| 8507 | duplicating each output frame to accommodate the originally detected frame |
| 8508 | rate. |
| 8509 | |
| 8510 | @item |
| 8511 | Display @code{5} pictures in an area of @code{3x2} frames, |
| 8512 | with @code{7} pixels between them, and @code{2} pixels of initial margin, using |
| 8513 | mixed flat and named options: |
| 8514 | @example |
| 8515 | tile=3x2:nb_frames=5:padding=7:margin=2 |
| 8516 | @end example |
| 8517 | @end itemize |
| 8518 | |
| 8519 | @section tinterlace |
| 8520 | |
| 8521 | Perform various types of temporal field interlacing. |
| 8522 | |
| 8523 | Frames are counted starting from 1, so the first input frame is |
| 8524 | considered odd. |
| 8525 | |
| 8526 | The filter accepts the following options: |
| 8527 | |
| 8528 | @table @option |
| 8529 | |
| 8530 | @item mode |
| 8531 | Specify the mode of the interlacing. This option can also be specified |
| 8532 | as a value alone. See below for a list of values for this option. |
| 8533 | |
| 8534 | Available values are: |
| 8535 | |
| 8536 | @table @samp |
| 8537 | @item merge, 0 |
| 8538 | Move odd frames into the upper field, even into the lower field, |
| 8539 | generating a double height frame at half frame rate. |
| 8540 | |
| 8541 | @item drop_odd, 1 |
| 8542 | Only output even frames, odd frames are dropped, generating a frame with |
| 8543 | unchanged height at half frame rate. |
| 8544 | |
| 8545 | @item drop_even, 2 |
| 8546 | Only output odd frames, even frames are dropped, generating a frame with |
| 8547 | unchanged height at half frame rate. |
| 8548 | |
| 8549 | @item pad, 3 |
| 8550 | Expand each frame to full height, but pad alternate lines with black, |
| 8551 | generating a frame with double height at the same input frame rate. |
| 8552 | |
| 8553 | @item interleave_top, 4 |
| 8554 | Interleave the upper field from odd frames with the lower field from |
| 8555 | even frames, generating a frame with unchanged height at half frame rate. |
| 8556 | |
| 8557 | @item interleave_bottom, 5 |
| 8558 | Interleave the lower field from odd frames with the upper field from |
| 8559 | even frames, generating a frame with unchanged height at half frame rate. |
| 8560 | |
| 8561 | @item interlacex2, 6 |
| 8562 | Double frame rate with unchanged height. Frames are inserted each |
| 8563 | containing the second temporal field from the previous input frame and |
| 8564 | the first temporal field from the next input frame. This mode relies on |
| 8565 | the top_field_first flag. Useful for interlaced video displays with no |
| 8566 | field synchronisation. |
| 8567 | @end table |
| 8568 | |
| 8569 | Numeric values are deprecated but are accepted for backward |
| 8570 | compatibility reasons. |
| 8571 | |
| 8572 | Default mode is @code{merge}. |
| 8573 | |
| 8574 | @item flags |
| 8575 | Specify flags influencing the filter process. |
| 8576 | |
| 8577 | Available value for @var{flags} is: |
| 8578 | |
| 8579 | @table @option |
| 8580 | @item low_pass_filter, vlfp |
| 8581 | Enable vertical low-pass filtering in the filter. |
| 8582 | Vertical low-pass filtering is required when creating an interlaced |
| 8583 | destination from a progressive source which contains high-frequency |
| 8584 | vertical detail. Filtering will reduce interlace 'twitter' and Moire |
| 8585 | patterning. |
| 8586 | |
| 8587 | Vertical low-pass filtering can only be enabled for @option{mode} |
| 8588 | @var{interleave_top} and @var{interleave_bottom}. |
| 8589 | |
| 8590 | @end table |
| 8591 | @end table |
| 8592 | |
| 8593 | @section transpose |
| 8594 | |
| 8595 | Transpose rows with columns in the input video and optionally flip it. |
| 8596 | |
| 8597 | It accepts the following parameters: |
| 8598 | |
| 8599 | @table @option |
| 8600 | |
| 8601 | @item dir |
| 8602 | Specify the transposition direction. |
| 8603 | |
| 8604 | Can assume the following values: |
| 8605 | @table @samp |
| 8606 | @item 0, 4, cclock_flip |
| 8607 | Rotate by 90 degrees counterclockwise and vertically flip (default), that is: |
| 8608 | @example |
| 8609 | L.R L.l |
| 8610 | . . -> . . |
| 8611 | l.r R.r |
| 8612 | @end example |
| 8613 | |
| 8614 | @item 1, 5, clock |
| 8615 | Rotate by 90 degrees clockwise, that is: |
| 8616 | @example |
| 8617 | L.R l.L |
| 8618 | . . -> . . |
| 8619 | l.r r.R |
| 8620 | @end example |
| 8621 | |
| 8622 | @item 2, 6, cclock |
| 8623 | Rotate by 90 degrees counterclockwise, that is: |
| 8624 | @example |
| 8625 | L.R R.r |
| 8626 | . . -> . . |
| 8627 | l.r L.l |
| 8628 | @end example |
| 8629 | |
| 8630 | @item 3, 7, clock_flip |
| 8631 | Rotate by 90 degrees clockwise and vertically flip, that is: |
| 8632 | @example |
| 8633 | L.R r.R |
| 8634 | . . -> . . |
| 8635 | l.r l.L |
| 8636 | @end example |
| 8637 | @end table |
| 8638 | |
| 8639 | For values between 4-7, the transposition is only done if the input |
| 8640 | video geometry is portrait and not landscape. These values are |
| 8641 | deprecated, the @code{passthrough} option should be used instead. |
| 8642 | |
| 8643 | Numerical values are deprecated, and should be dropped in favor of |
| 8644 | symbolic constants. |
| 8645 | |
| 8646 | @item passthrough |
| 8647 | Do not apply the transposition if the input geometry matches the one |
| 8648 | specified by the specified value. It accepts the following values: |
| 8649 | @table @samp |
| 8650 | @item none |
| 8651 | Always apply transposition. |
| 8652 | @item portrait |
| 8653 | Preserve portrait geometry (when @var{height} >= @var{width}). |
| 8654 | @item landscape |
| 8655 | Preserve landscape geometry (when @var{width} >= @var{height}). |
| 8656 | @end table |
| 8657 | |
| 8658 | Default value is @code{none}. |
| 8659 | @end table |
| 8660 | |
| 8661 | For example to rotate by 90 degrees clockwise and preserve portrait |
| 8662 | layout: |
| 8663 | @example |
| 8664 | transpose=dir=1:passthrough=portrait |
| 8665 | @end example |
| 8666 | |
| 8667 | The command above can also be specified as: |
| 8668 | @example |
| 8669 | transpose=1:portrait |
| 8670 | @end example |
| 8671 | |
| 8672 | @section trim |
| 8673 | Trim the input so that the output contains one continuous subpart of the input. |
| 8674 | |
| 8675 | It accepts the following parameters: |
| 8676 | @table @option |
| 8677 | @item start |
| 8678 | Specify the time of the start of the kept section, i.e. the frame with the |
| 8679 | timestamp @var{start} will be the first frame in the output. |
| 8680 | |
| 8681 | @item end |
| 8682 | Specify the time of the first frame that will be dropped, i.e. the frame |
| 8683 | immediately preceding the one with the timestamp @var{end} will be the last |
| 8684 | frame in the output. |
| 8685 | |
| 8686 | @item start_pts |
| 8687 | This is the same as @var{start}, except this option sets the start timestamp |
| 8688 | in timebase units instead of seconds. |
| 8689 | |
| 8690 | @item end_pts |
| 8691 | This is the same as @var{end}, except this option sets the end timestamp |
| 8692 | in timebase units instead of seconds. |
| 8693 | |
| 8694 | @item duration |
| 8695 | The maximum duration of the output in seconds. |
| 8696 | |
| 8697 | @item start_frame |
| 8698 | The number of the first frame that should be passed to the output. |
| 8699 | |
| 8700 | @item end_frame |
| 8701 | The number of the first frame that should be dropped. |
| 8702 | @end table |
| 8703 | |
| 8704 | @option{start}, @option{end}, and @option{duration} are expressed as time |
| 8705 | duration specifications; see |
| 8706 | @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils} |
| 8707 | for the accepted syntax. |
| 8708 | |
| 8709 | Note that the first two sets of the start/end options and the @option{duration} |
| 8710 | option look at the frame timestamp, while the _frame variants simply count the |
| 8711 | frames that pass through the filter. Also note that this filter does not modify |
| 8712 | the timestamps. If you wish for the output timestamps to start at zero, insert a |
| 8713 | setpts filter after the trim filter. |
| 8714 | |
| 8715 | If multiple start or end options are set, this filter tries to be greedy and |
| 8716 | keep all the frames that match at least one of the specified constraints. To keep |
| 8717 | only the part that matches all the constraints at once, chain multiple trim |
| 8718 | filters. |
| 8719 | |
| 8720 | The defaults are such that all the input is kept. So it is possible to set e.g. |
| 8721 | just the end values to keep everything before the specified time. |
| 8722 | |
| 8723 | Examples: |
| 8724 | @itemize |
| 8725 | @item |
| 8726 | Drop everything except the second minute of input: |
| 8727 | @example |
| 8728 | ffmpeg -i INPUT -vf trim=60:120 |
| 8729 | @end example |
| 8730 | |
| 8731 | @item |
| 8732 | Keep only the first second: |
| 8733 | @example |
| 8734 | ffmpeg -i INPUT -vf trim=duration=1 |
| 8735 | @end example |
| 8736 | |
| 8737 | @end itemize |
| 8738 | |
| 8739 | |
| 8740 | @anchor{unsharp} |
| 8741 | @section unsharp |
| 8742 | |
| 8743 | Sharpen or blur the input video. |
| 8744 | |
| 8745 | It accepts the following parameters: |
| 8746 | |
| 8747 | @table @option |
| 8748 | @item luma_msize_x, lx |
| 8749 | Set the luma matrix horizontal size. It must be an odd integer between |
| 8750 | 3 and 63. The default value is 5. |
| 8751 | |
| 8752 | @item luma_msize_y, ly |
| 8753 | Set the luma matrix vertical size. It must be an odd integer between 3 |
| 8754 | and 63. The default value is 5. |
| 8755 | |
| 8756 | @item luma_amount, la |
| 8757 | Set the luma effect strength. It must be a floating point number, reasonable |
| 8758 | values lay between -1.5 and 1.5. |
| 8759 | |
| 8760 | Negative values will blur the input video, while positive values will |
| 8761 | sharpen it, a value of zero will disable the effect. |
| 8762 | |
| 8763 | Default value is 1.0. |
| 8764 | |
| 8765 | @item chroma_msize_x, cx |
| 8766 | Set the chroma matrix horizontal size. It must be an odd integer |
| 8767 | between 3 and 63. The default value is 5. |
| 8768 | |
| 8769 | @item chroma_msize_y, cy |
| 8770 | Set the chroma matrix vertical size. It must be an odd integer |
| 8771 | between 3 and 63. The default value is 5. |
| 8772 | |
| 8773 | @item chroma_amount, ca |
| 8774 | Set the chroma effect strength. It must be a floating point number, reasonable |
| 8775 | values lay between -1.5 and 1.5. |
| 8776 | |
| 8777 | Negative values will blur the input video, while positive values will |
| 8778 | sharpen it, a value of zero will disable the effect. |
| 8779 | |
| 8780 | Default value is 0.0. |
| 8781 | |
| 8782 | @item opencl |
| 8783 | If set to 1, specify using OpenCL capabilities, only available if |
| 8784 | FFmpeg was configured with @code{--enable-opencl}. Default value is 0. |
| 8785 | |
| 8786 | @end table |
| 8787 | |
| 8788 | All parameters are optional and default to the equivalent of the |
| 8789 | string '5:5:1.0:5:5:0.0'. |
| 8790 | |
| 8791 | @subsection Examples |
| 8792 | |
| 8793 | @itemize |
| 8794 | @item |
| 8795 | Apply strong luma sharpen effect: |
| 8796 | @example |
| 8797 | unsharp=luma_msize_x=7:luma_msize_y=7:luma_amount=2.5 |
| 8798 | @end example |
| 8799 | |
| 8800 | @item |
| 8801 | Apply a strong blur of both luma and chroma parameters: |
| 8802 | @example |
| 8803 | unsharp=7:7:-2:7:7:-2 |
| 8804 | @end example |
| 8805 | @end itemize |
| 8806 | |
| 8807 | @anchor{vidstabdetect} |
| 8808 | @section vidstabdetect |
| 8809 | |
| 8810 | Analyze video stabilization/deshaking. Perform pass 1 of 2, see |
| 8811 | @ref{vidstabtransform} for pass 2. |
| 8812 | |
| 8813 | This filter generates a file with relative translation and rotation |
| 8814 | transform information about subsequent frames, which is then used by |
| 8815 | the @ref{vidstabtransform} filter. |
| 8816 | |
| 8817 | To enable compilation of this filter you need to configure FFmpeg with |
| 8818 | @code{--enable-libvidstab}. |
| 8819 | |
| 8820 | This filter accepts the following options: |
| 8821 | |
| 8822 | @table @option |
| 8823 | @item result |
| 8824 | Set the path to the file used to write the transforms information. |
| 8825 | Default value is @file{transforms.trf}. |
| 8826 | |
| 8827 | @item shakiness |
| 8828 | Set how shaky the video is and how quick the camera is. It accepts an |
| 8829 | integer in the range 1-10, a value of 1 means little shakiness, a |
| 8830 | value of 10 means strong shakiness. Default value is 5. |
| 8831 | |
| 8832 | @item accuracy |
| 8833 | Set the accuracy of the detection process. It must be a value in the |
| 8834 | range 1-15. A value of 1 means low accuracy, a value of 15 means high |
| 8835 | accuracy. Default value is 15. |
| 8836 | |
| 8837 | @item stepsize |
| 8838 | Set stepsize of the search process. The region around minimum is |
| 8839 | scanned with 1 pixel resolution. Default value is 6. |
| 8840 | |
| 8841 | @item mincontrast |
| 8842 | Set minimum contrast. Below this value a local measurement field is |
| 8843 | discarded. Must be a floating point value in the range 0-1. Default |
| 8844 | value is 0.3. |
| 8845 | |
| 8846 | @item tripod |
| 8847 | Set reference frame number for tripod mode. |
| 8848 | |
| 8849 | If enabled, the motion of the frames is compared to a reference frame |
| 8850 | in the filtered stream, identified by the specified number. The idea |
| 8851 | is to compensate all movements in a more-or-less static scene and keep |
| 8852 | the camera view absolutely still. |
| 8853 | |
| 8854 | If set to 0, it is disabled. The frames are counted starting from 1. |
| 8855 | |
| 8856 | @item show |
| 8857 | Show fields and transforms in the resulting frames. It accepts an |
| 8858 | integer in the range 0-2. Default value is 0, which disables any |
| 8859 | visualization. |
| 8860 | @end table |
| 8861 | |
| 8862 | @subsection Examples |
| 8863 | |
| 8864 | @itemize |
| 8865 | @item |
| 8866 | Use default values: |
| 8867 | @example |
| 8868 | vidstabdetect |
| 8869 | @end example |
| 8870 | |
| 8871 | @item |
| 8872 | Analyze strongly shaky movie and put the results in file |
| 8873 | @file{mytransforms.trf}: |
| 8874 | @example |
| 8875 | vidstabdetect=shakiness=10:accuracy=15:result="mytransforms.trf" |
| 8876 | @end example |
| 8877 | |
| 8878 | @item |
| 8879 | Visualize the result of internal transformations in the resulting |
| 8880 | video: |
| 8881 | @example |
| 8882 | vidstabdetect=show=1 |
| 8883 | @end example |
| 8884 | |
| 8885 | @item |
| 8886 | Analyze a video with medium shakiness using @command{ffmpeg}: |
| 8887 | @example |
| 8888 | ffmpeg -i input -vf vidstabdetect=shakiness=5:show=1 dummy.avi |
| 8889 | @end example |
| 8890 | @end itemize |
| 8891 | |
| 8892 | @anchor{vidstabtransform} |
| 8893 | @section vidstabtransform |
| 8894 | |
| 8895 | Video stabilization/deshaking: pass 2 of 2, |
| 8896 | see @ref{vidstabdetect} for pass 1. |
| 8897 | |
| 8898 | Read a file with transform information for each frame and |
| 8899 | apply/compensate them. Together with the @ref{vidstabdetect} |
| 8900 | filter this can be used to deshake videos. See also |
| 8901 | @url{http://public.hronopik.de/vid.stab}. It is important to also use |
| 8902 | the @ref{unsharp} filter, see below. |
| 8903 | |
| 8904 | To enable compilation of this filter you need to configure FFmpeg with |
| 8905 | @code{--enable-libvidstab}. |
| 8906 | |
| 8907 | @subsection Options |
| 8908 | |
| 8909 | @table @option |
| 8910 | @item input |
| 8911 | Set path to the file used to read the transforms. Default value is |
| 8912 | @file{transforms.trf}. |
| 8913 | |
| 8914 | @item smoothing |
| 8915 | Set the number of frames (value*2 + 1) used for lowpass filtering the |
| 8916 | camera movements. Default value is 10. |
| 8917 | |
| 8918 | For example a number of 10 means that 21 frames are used (10 in the |
| 8919 | past and 10 in the future) to smoothen the motion in the video. A |
| 8920 | larger value leads to a smoother video, but limits the acceleration of |
| 8921 | the camera (pan/tilt movements). 0 is a special case where a static |
| 8922 | camera is simulated. |
| 8923 | |
| 8924 | @item optalgo |
| 8925 | Set the camera path optimization algorithm. |
| 8926 | |
| 8927 | Accepted values are: |
| 8928 | @table @samp |
| 8929 | @item gauss |
| 8930 | gaussian kernel low-pass filter on camera motion (default) |
| 8931 | @item avg |
| 8932 | averaging on transformations |
| 8933 | @end table |
| 8934 | |
| 8935 | @item maxshift |
| 8936 | Set maximal number of pixels to translate frames. Default value is -1, |
| 8937 | meaning no limit. |
| 8938 | |
| 8939 | @item maxangle |
| 8940 | Set maximal angle in radians (degree*PI/180) to rotate frames. Default |
| 8941 | value is -1, meaning no limit. |
| 8942 | |
| 8943 | @item crop |
| 8944 | Specify how to deal with borders that may be visible due to movement |
| 8945 | compensation. |
| 8946 | |
| 8947 | Available values are: |
| 8948 | @table @samp |
| 8949 | @item keep |
| 8950 | keep image information from previous frame (default) |
| 8951 | @item black |
| 8952 | fill the border black |
| 8953 | @end table |
| 8954 | |
| 8955 | @item invert |
| 8956 | Invert transforms if set to 1. Default value is 0. |
| 8957 | |
| 8958 | @item relative |
| 8959 | Consider transforms as relative to previous frame if set to 1, |
| 8960 | absolute if set to 0. Default value is 0. |
| 8961 | |
| 8962 | @item zoom |
| 8963 | Set percentage to zoom. A positive value will result in a zoom-in |
| 8964 | effect, a negative value in a zoom-out effect. Default value is 0 (no |
| 8965 | zoom). |
| 8966 | |
| 8967 | @item optzoom |
| 8968 | Set optimal zooming to avoid borders. |
| 8969 | |
| 8970 | Accepted values are: |
| 8971 | @table @samp |
| 8972 | @item 0 |
| 8973 | disabled |
| 8974 | @item 1 |
| 8975 | optimal static zoom value is determined (only very strong movements |
| 8976 | will lead to visible borders) (default) |
| 8977 | @item 2 |
| 8978 | optimal adaptive zoom value is determined (no borders will be |
| 8979 | visible), see @option{zoomspeed} |
| 8980 | @end table |
| 8981 | |
| 8982 | Note that the value given at zoom is added to the one calculated here. |
| 8983 | |
| 8984 | @item zoomspeed |
| 8985 | Set percent to zoom maximally each frame (enabled when |
| 8986 | @option{optzoom} is set to 2). Range is from 0 to 5, default value is |
| 8987 | 0.25. |
| 8988 | |
| 8989 | @item interpol |
| 8990 | Specify type of interpolation. |
| 8991 | |
| 8992 | Available values are: |
| 8993 | @table @samp |
| 8994 | @item no |
| 8995 | no interpolation |
| 8996 | @item linear |
| 8997 | linear only horizontal |
| 8998 | @item bilinear |
| 8999 | linear in both directions (default) |
| 9000 | @item bicubic |
| 9001 | cubic in both directions (slow) |
| 9002 | @end table |
| 9003 | |
| 9004 | @item tripod |
| 9005 | Enable virtual tripod mode if set to 1, which is equivalent to |
| 9006 | @code{relative=0:smoothing=0}. Default value is 0. |
| 9007 | |
| 9008 | Use also @code{tripod} option of @ref{vidstabdetect}. |
| 9009 | |
| 9010 | @item debug |
| 9011 | Increase log verbosity if set to 1. Also the detected global motions |
| 9012 | are written to the temporary file @file{global_motions.trf}. Default |
| 9013 | value is 0. |
| 9014 | @end table |
| 9015 | |
| 9016 | @subsection Examples |
| 9017 | |
| 9018 | @itemize |
| 9019 | @item |
| 9020 | Use @command{ffmpeg} for a typical stabilization with default values: |
| 9021 | @example |
| 9022 | ffmpeg -i inp.mpeg -vf vidstabtransform,unsharp=5:5:0.8:3:3:0.4 inp_stabilized.mpeg |
| 9023 | @end example |
| 9024 | |
| 9025 | Note the use of the @ref{unsharp} filter which is always recommended. |
| 9026 | |
| 9027 | @item |
| 9028 | Zoom in a bit more and load transform data from a given file: |
| 9029 | @example |
| 9030 | vidstabtransform=zoom=5:input="mytransforms.trf" |
| 9031 | @end example |
| 9032 | |
| 9033 | @item |
| 9034 | Smoothen the video even more: |
| 9035 | @example |
| 9036 | vidstabtransform=smoothing=30 |
| 9037 | @end example |
| 9038 | @end itemize |
| 9039 | |
| 9040 | @section vflip |
| 9041 | |
| 9042 | Flip the input video vertically. |
| 9043 | |
| 9044 | For example, to vertically flip a video with @command{ffmpeg}: |
| 9045 | @example |
| 9046 | ffmpeg -i in.avi -vf "vflip" out.avi |
| 9047 | @end example |
| 9048 | |
| 9049 | @anchor{vignette} |
| 9050 | @section vignette |
| 9051 | |
| 9052 | Make or reverse a natural vignetting effect. |
| 9053 | |
| 9054 | The filter accepts the following options: |
| 9055 | |
| 9056 | @table @option |
| 9057 | @item angle, a |
| 9058 | Set lens angle expression as a number of radians. |
| 9059 | |
| 9060 | The value is clipped in the @code{[0,PI/2]} range. |
| 9061 | |
| 9062 | Default value: @code{"PI/5"} |
| 9063 | |
| 9064 | @item x0 |
| 9065 | @item y0 |
| 9066 | Set center coordinates expressions. Respectively @code{"w/2"} and @code{"h/2"} |
| 9067 | by default. |
| 9068 | |
| 9069 | @item mode |
| 9070 | Set forward/backward mode. |
| 9071 | |
| 9072 | Available modes are: |
| 9073 | @table @samp |
| 9074 | @item forward |
| 9075 | The larger the distance from the central point, the darker the image becomes. |
| 9076 | |
| 9077 | @item backward |
| 9078 | The larger the distance from the central point, the brighter the image becomes. |
| 9079 | This can be used to reverse a vignette effect, though there is no automatic |
| 9080 | detection to extract the lens @option{angle} and other settings (yet). It can |
| 9081 | also be used to create a burning effect. |
| 9082 | @end table |
| 9083 | |
| 9084 | Default value is @samp{forward}. |
| 9085 | |
| 9086 | @item eval |
| 9087 | Set evaluation mode for the expressions (@option{angle}, @option{x0}, @option{y0}). |
| 9088 | |
| 9089 | It accepts the following values: |
| 9090 | @table @samp |
| 9091 | @item init |
| 9092 | Evaluate expressions only once during the filter initialization. |
| 9093 | |
| 9094 | @item frame |
| 9095 | Evaluate expressions for each incoming frame. This is way slower than the |
| 9096 | @samp{init} mode since it requires all the scalers to be re-computed, but it |
| 9097 | allows advanced dynamic expressions. |
| 9098 | @end table |
| 9099 | |
| 9100 | Default value is @samp{init}. |
| 9101 | |
| 9102 | @item dither |
| 9103 | Set dithering to reduce the circular banding effects. Default is @code{1} |
| 9104 | (enabled). |
| 9105 | |
| 9106 | @item aspect |
| 9107 | Set vignette aspect. This setting allows one to adjust the shape of the vignette. |
| 9108 | Setting this value to the SAR of the input will make a rectangular vignetting |
| 9109 | following the dimensions of the video. |
| 9110 | |
| 9111 | Default is @code{1/1}. |
| 9112 | @end table |
| 9113 | |
| 9114 | @subsection Expressions |
| 9115 | |
| 9116 | The @option{alpha}, @option{x0} and @option{y0} expressions can contain the |
| 9117 | following parameters. |
| 9118 | |
| 9119 | @table @option |
| 9120 | @item w |
| 9121 | @item h |
| 9122 | input width and height |
| 9123 | |
| 9124 | @item n |
| 9125 | the number of input frame, starting from 0 |
| 9126 | |
| 9127 | @item pts |
| 9128 | the PTS (Presentation TimeStamp) time of the filtered video frame, expressed in |
| 9129 | @var{TB} units, NAN if undefined |
| 9130 | |
| 9131 | @item r |
| 9132 | frame rate of the input video, NAN if the input frame rate is unknown |
| 9133 | |
| 9134 | @item t |
| 9135 | the PTS (Presentation TimeStamp) of the filtered video frame, |
| 9136 | expressed in seconds, NAN if undefined |
| 9137 | |
| 9138 | @item tb |
| 9139 | time base of the input video |
| 9140 | @end table |
| 9141 | |
| 9142 | |
| 9143 | @subsection Examples |
| 9144 | |
| 9145 | @itemize |
| 9146 | @item |
| 9147 | Apply simple strong vignetting effect: |
| 9148 | @example |
| 9149 | vignette=PI/4 |
| 9150 | @end example |
| 9151 | |
| 9152 | @item |
| 9153 | Make a flickering vignetting: |
| 9154 | @example |
| 9155 | vignette='PI/4+random(1)*PI/50':eval=frame |
| 9156 | @end example |
| 9157 | |
| 9158 | @end itemize |
| 9159 | |
| 9160 | @section w3fdif |
| 9161 | |
| 9162 | Deinterlace the input video ("w3fdif" stands for "Weston 3 Field |
| 9163 | Deinterlacing Filter"). |
| 9164 | |
| 9165 | Based on the process described by Martin Weston for BBC R&D, and |
| 9166 | implemented based on the de-interlace algorithm written by Jim |
| 9167 | Easterbrook for BBC R&D, the Weston 3 field deinterlacing filter |
| 9168 | uses filter coefficients calculated by BBC R&D. |
| 9169 | |
| 9170 | There are two sets of filter coefficients, so called "simple": |
| 9171 | and "complex". Which set of filter coefficients is used can |
| 9172 | be set by passing an optional parameter: |
| 9173 | |
| 9174 | @table @option |
| 9175 | @item filter |
| 9176 | Set the interlacing filter coefficients. Accepts one of the following values: |
| 9177 | |
| 9178 | @table @samp |
| 9179 | @item simple |
| 9180 | Simple filter coefficient set. |
| 9181 | @item complex |
| 9182 | More-complex filter coefficient set. |
| 9183 | @end table |
| 9184 | Default value is @samp{complex}. |
| 9185 | |
| 9186 | @item deint |
| 9187 | Specify which frames to deinterlace. Accept one of the following values: |
| 9188 | |
| 9189 | @table @samp |
| 9190 | @item all |
| 9191 | Deinterlace all frames, |
| 9192 | @item interlaced |
| 9193 | Only deinterlace frames marked as interlaced. |
| 9194 | @end table |
| 9195 | |
| 9196 | Default value is @samp{all}. |
| 9197 | @end table |
| 9198 | |
| 9199 | @section xbr |
| 9200 | Apply the xBR high-quality magnification filter which is designed for pixel |
| 9201 | art. It follows a set of edge-detection rules, see |
| 9202 | @url{http://www.libretro.com/forums/viewtopic.php?f=6&t=134}. |
| 9203 | |
| 9204 | It accepts the following option: |
| 9205 | |
| 9206 | @table @option |
| 9207 | @item n |
| 9208 | Set the scaling dimension: @code{2} for @code{2xBR}, @code{3} for |
| 9209 | @code{3xBR} and @code{4} for @code{4xBR}. |
| 9210 | Default is @code{3}. |
| 9211 | @end table |
| 9212 | |
| 9213 | @anchor{yadif} |
| 9214 | @section yadif |
| 9215 | |
| 9216 | Deinterlace the input video ("yadif" means "yet another deinterlacing |
| 9217 | filter"). |
| 9218 | |
| 9219 | It accepts the following parameters: |
| 9220 | |
| 9221 | |
| 9222 | @table @option |
| 9223 | |
| 9224 | @item mode |
| 9225 | The interlacing mode to adopt. It accepts one of the following values: |
| 9226 | |
| 9227 | @table @option |
| 9228 | @item 0, send_frame |
| 9229 | Output one frame for each frame. |
| 9230 | @item 1, send_field |
| 9231 | Output one frame for each field. |
| 9232 | @item 2, send_frame_nospatial |
| 9233 | Like @code{send_frame}, but it skips the spatial interlacing check. |
| 9234 | @item 3, send_field_nospatial |
| 9235 | Like @code{send_field}, but it skips the spatial interlacing check. |
| 9236 | @end table |
| 9237 | |
| 9238 | The default value is @code{send_frame}. |
| 9239 | |
| 9240 | @item parity |
| 9241 | The picture field parity assumed for the input interlaced video. It accepts one |
| 9242 | of the following values: |
| 9243 | |
| 9244 | @table @option |
| 9245 | @item 0, tff |
| 9246 | Assume the top field is first. |
| 9247 | @item 1, bff |
| 9248 | Assume the bottom field is first. |
| 9249 | @item -1, auto |
| 9250 | Enable automatic detection of field parity. |
| 9251 | @end table |
| 9252 | |
| 9253 | The default value is @code{auto}. |
| 9254 | If the interlacing is unknown or the decoder does not export this information, |
| 9255 | top field first will be assumed. |
| 9256 | |
| 9257 | @item deint |
| 9258 | Specify which frames to deinterlace. Accept one of the following |
| 9259 | values: |
| 9260 | |
| 9261 | @table @option |
| 9262 | @item 0, all |
| 9263 | Deinterlace all frames. |
| 9264 | @item 1, interlaced |
| 9265 | Only deinterlace frames marked as interlaced. |
| 9266 | @end table |
| 9267 | |
| 9268 | The default value is @code{all}. |
| 9269 | @end table |
| 9270 | |
| 9271 | @section zoompan |
| 9272 | |
| 9273 | Apply Zoom & Pan effect. |
| 9274 | |
| 9275 | This filter accepts the following options: |
| 9276 | |
| 9277 | @table @option |
| 9278 | @item zoom, z |
| 9279 | Set the zoom expression. Default is 1. |
| 9280 | |
| 9281 | @item x |
| 9282 | @item y |
| 9283 | Set the x and y expression. Default is 0. |
| 9284 | |
| 9285 | @item d |
| 9286 | Set the duration expression in number of frames. |
| 9287 | This sets for how many number of frames effect will last for |
| 9288 | single input image. |
| 9289 | |
| 9290 | @item s |
| 9291 | Set the output image size, default is 'hd720'. |
| 9292 | @end table |
| 9293 | |
| 9294 | Each expression can contain the following constants: |
| 9295 | |
| 9296 | @table @option |
| 9297 | @item in_w, iw |
| 9298 | Input width. |
| 9299 | |
| 9300 | @item in_h, ih |
| 9301 | Input height. |
| 9302 | |
| 9303 | @item out_w, ow |
| 9304 | Output width. |
| 9305 | |
| 9306 | @item out_h, oh |
| 9307 | Output height. |
| 9308 | |
| 9309 | @item in |
| 9310 | Input frame count. |
| 9311 | |
| 9312 | @item on |
| 9313 | Output frame count. |
| 9314 | |
| 9315 | @item x |
| 9316 | @item y |
| 9317 | Last calculated 'x' and 'y' position from 'x' and 'y' expression |
| 9318 | for current input frame. |
| 9319 | |
| 9320 | @item px |
| 9321 | @item py |
| 9322 | 'x' and 'y' of last output frame of previous input frame or 0 when there was |
| 9323 | not yet such frame (first input frame). |
| 9324 | |
| 9325 | @item zoom |
| 9326 | Last calculated zoom from 'z' expression for current input frame. |
| 9327 | |
| 9328 | @item pzoom |
| 9329 | Last calculated zoom of last output frame of previous input frame. |
| 9330 | |
| 9331 | @item duration |
| 9332 | Number of output frames for current input frame. Calculated from 'd' expression |
| 9333 | for each input frame. |
| 9334 | |
| 9335 | @item pduration |
| 9336 | number of output frames created for previous input frame |
| 9337 | |
| 9338 | @item a |
| 9339 | Rational number: input width / input height |
| 9340 | |
| 9341 | @item sar |
| 9342 | sample aspect ratio |
| 9343 | |
| 9344 | @item dar |
| 9345 | display aspect ratio |
| 9346 | |
| 9347 | @end table |
| 9348 | |
| 9349 | @subsection Examples |
| 9350 | |
| 9351 | @itemize |
| 9352 | @item |
| 9353 | Zoom-in up to 1.5 and pan at same time to some spot near center of picture: |
| 9354 | @example |
| 9355 | zoompan=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 |
| 9356 | @end example |
| 9357 | @end itemize |
| 9358 | |
| 9359 | @c man end VIDEO FILTERS |
| 9360 | |
| 9361 | @chapter Video Sources |
| 9362 | @c man begin VIDEO SOURCES |
| 9363 | |
| 9364 | Below is a description of the currently available video sources. |
| 9365 | |
| 9366 | @section buffer |
| 9367 | |
| 9368 | Buffer video frames, and make them available to the filter chain. |
| 9369 | |
| 9370 | This source is mainly intended for a programmatic use, in particular |
| 9371 | through the interface defined in @file{libavfilter/vsrc_buffer.h}. |
| 9372 | |
| 9373 | It accepts the following parameters: |
| 9374 | |
| 9375 | @table @option |
| 9376 | |
| 9377 | @item video_size |
| 9378 | Specify the size (width and height) of the buffered video frames. For the |
| 9379 | syntax of this option, check the "Video size" section in the ffmpeg-utils |
| 9380 | manual. |
| 9381 | |
| 9382 | @item width |
| 9383 | The input video width. |
| 9384 | |
| 9385 | @item height |
| 9386 | The input video height. |
| 9387 | |
| 9388 | @item pix_fmt |
| 9389 | A string representing the pixel format of the buffered video frames. |
| 9390 | It may be a number corresponding to a pixel format, or a pixel format |
| 9391 | name. |
| 9392 | |
| 9393 | @item time_base |
| 9394 | Specify the timebase assumed by the timestamps of the buffered frames. |
| 9395 | |
| 9396 | @item frame_rate |
| 9397 | Specify the frame rate expected for the video stream. |
| 9398 | |
| 9399 | @item pixel_aspect, sar |
| 9400 | The sample (pixel) aspect ratio of the input video. |
| 9401 | |
| 9402 | @item sws_param |
| 9403 | Specify the optional parameters to be used for the scale filter which |
| 9404 | is automatically inserted when an input change is detected in the |
| 9405 | input size or format. |
| 9406 | @end table |
| 9407 | |
| 9408 | For example: |
| 9409 | @example |
| 9410 | buffer=width=320:height=240:pix_fmt=yuv410p:time_base=1/24:sar=1 |
| 9411 | @end example |
| 9412 | |
| 9413 | will instruct the source to accept video frames with size 320x240 and |
| 9414 | with format "yuv410p", assuming 1/24 as the timestamps timebase and |
| 9415 | square pixels (1:1 sample aspect ratio). |
| 9416 | Since the pixel format with name "yuv410p" corresponds to the number 6 |
| 9417 | (check the enum AVPixelFormat definition in @file{libavutil/pixfmt.h}), |
| 9418 | this example corresponds to: |
| 9419 | @example |
| 9420 | buffer=size=320x240:pixfmt=6:time_base=1/24:pixel_aspect=1/1 |
| 9421 | @end example |
| 9422 | |
| 9423 | Alternatively, the options can be specified as a flat string, but this |
| 9424 | syntax is deprecated: |
| 9425 | |
| 9426 | @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}] |
| 9427 | |
| 9428 | @section cellauto |
| 9429 | |
| 9430 | Create a pattern generated by an elementary cellular automaton. |
| 9431 | |
| 9432 | The initial state of the cellular automaton can be defined through the |
| 9433 | @option{filename}, and @option{pattern} options. If such options are |
| 9434 | not specified an initial state is created randomly. |
| 9435 | |
| 9436 | At each new frame a new row in the video is filled with the result of |
| 9437 | the cellular automaton next generation. The behavior when the whole |
| 9438 | frame is filled is defined by the @option{scroll} option. |
| 9439 | |
| 9440 | This source accepts the following options: |
| 9441 | |
| 9442 | @table @option |
| 9443 | @item filename, f |
| 9444 | Read the initial cellular automaton state, i.e. the starting row, from |
| 9445 | the specified file. |
| 9446 | In the file, each non-whitespace character is considered an alive |
| 9447 | cell, a newline will terminate the row, and further characters in the |
| 9448 | file will be ignored. |
| 9449 | |
| 9450 | @item pattern, p |
| 9451 | Read the initial cellular automaton state, i.e. the starting row, from |
| 9452 | the specified string. |
| 9453 | |
| 9454 | Each non-whitespace character in the string is considered an alive |
| 9455 | cell, a newline will terminate the row, and further characters in the |
| 9456 | string will be ignored. |
| 9457 | |
| 9458 | @item rate, r |
| 9459 | Set the video rate, that is the number of frames generated per second. |
| 9460 | Default is 25. |
| 9461 | |
| 9462 | @item random_fill_ratio, ratio |
| 9463 | Set the random fill ratio for the initial cellular automaton row. It |
| 9464 | is a floating point number value ranging from 0 to 1, defaults to |
| 9465 | 1/PHI. |
| 9466 | |
| 9467 | This option is ignored when a file or a pattern is specified. |
| 9468 | |
| 9469 | @item random_seed, seed |
| 9470 | Set the seed for filling randomly the initial row, must be an integer |
| 9471 | included between 0 and UINT32_MAX. If not specified, or if explicitly |
| 9472 | set to -1, the filter will try to use a good random seed on a best |
| 9473 | effort basis. |
| 9474 | |
| 9475 | @item rule |
| 9476 | Set the cellular automaton rule, it is a number ranging from 0 to 255. |
| 9477 | Default value is 110. |
| 9478 | |
| 9479 | @item size, s |
| 9480 | Set the size of the output video. For the syntax of this option, check |
| 9481 | the "Video size" section in the ffmpeg-utils manual. |
| 9482 | |
| 9483 | If @option{filename} or @option{pattern} is specified, the size is set |
| 9484 | by default to the width of the specified initial state row, and the |
| 9485 | height is set to @var{width} * PHI. |
| 9486 | |
| 9487 | If @option{size} is set, it must contain the width of the specified |
| 9488 | pattern string, and the specified pattern will be centered in the |
| 9489 | larger row. |
| 9490 | |
| 9491 | If a filename or a pattern string is not specified, the size value |
| 9492 | defaults to "320x518" (used for a randomly generated initial state). |
| 9493 | |
| 9494 | @item scroll |
| 9495 | If set to 1, scroll the output upward when all the rows in the output |
| 9496 | have been already filled. If set to 0, the new generated row will be |
| 9497 | written over the top row just after the bottom row is filled. |
| 9498 | Defaults to 1. |
| 9499 | |
| 9500 | @item start_full, full |
| 9501 | If set to 1, completely fill the output with generated rows before |
| 9502 | outputting the first frame. |
| 9503 | This is the default behavior, for disabling set the value to 0. |
| 9504 | |
| 9505 | @item stitch |
| 9506 | If set to 1, stitch the left and right row edges together. |
| 9507 | This is the default behavior, for disabling set the value to 0. |
| 9508 | @end table |
| 9509 | |
| 9510 | @subsection Examples |
| 9511 | |
| 9512 | @itemize |
| 9513 | @item |
| 9514 | Read the initial state from @file{pattern}, and specify an output of |
| 9515 | size 200x400. |
| 9516 | @example |
| 9517 | cellauto=f=pattern:s=200x400 |
| 9518 | @end example |
| 9519 | |
| 9520 | @item |
| 9521 | Generate a random initial row with a width of 200 cells, with a fill |
| 9522 | ratio of 2/3: |
| 9523 | @example |
| 9524 | cellauto=ratio=2/3:s=200x200 |
| 9525 | @end example |
| 9526 | |
| 9527 | @item |
| 9528 | Create a pattern generated by rule 18 starting by a single alive cell |
| 9529 | centered on an initial row with width 100: |
| 9530 | @example |
| 9531 | cellauto=p=@@:s=100x400:full=0:rule=18 |
| 9532 | @end example |
| 9533 | |
| 9534 | @item |
| 9535 | Specify a more elaborated initial pattern: |
| 9536 | @example |
| 9537 | cellauto=p='@@@@ @@ @@@@':s=100x400:full=0:rule=18 |
| 9538 | @end example |
| 9539 | |
| 9540 | @end itemize |
| 9541 | |
| 9542 | @section mandelbrot |
| 9543 | |
| 9544 | Generate a Mandelbrot set fractal, and progressively zoom towards the |
| 9545 | point specified with @var{start_x} and @var{start_y}. |
| 9546 | |
| 9547 | This source accepts the following options: |
| 9548 | |
| 9549 | @table @option |
| 9550 | |
| 9551 | @item end_pts |
| 9552 | Set the terminal pts value. Default value is 400. |
| 9553 | |
| 9554 | @item end_scale |
| 9555 | Set the terminal scale value. |
| 9556 | Must be a floating point value. Default value is 0.3. |
| 9557 | |
| 9558 | @item inner |
| 9559 | Set the inner coloring mode, that is the algorithm used to draw the |
| 9560 | Mandelbrot fractal internal region. |
| 9561 | |
| 9562 | It shall assume one of the following values: |
| 9563 | @table @option |
| 9564 | @item black |
| 9565 | Set black mode. |
| 9566 | @item convergence |
| 9567 | Show time until convergence. |
| 9568 | @item mincol |
| 9569 | Set color based on point closest to the origin of the iterations. |
| 9570 | @item period |
| 9571 | Set period mode. |
| 9572 | @end table |
| 9573 | |
| 9574 | Default value is @var{mincol}. |
| 9575 | |
| 9576 | @item bailout |
| 9577 | Set the bailout value. Default value is 10.0. |
| 9578 | |
| 9579 | @item maxiter |
| 9580 | Set the maximum of iterations performed by the rendering |
| 9581 | algorithm. Default value is 7189. |
| 9582 | |
| 9583 | @item outer |
| 9584 | Set outer coloring mode. |
| 9585 | It shall assume one of following values: |
| 9586 | @table @option |
| 9587 | @item iteration_count |
| 9588 | Set iteration cound mode. |
| 9589 | @item normalized_iteration_count |
| 9590 | set normalized iteration count mode. |
| 9591 | @end table |
| 9592 | Default value is @var{normalized_iteration_count}. |
| 9593 | |
| 9594 | @item rate, r |
| 9595 | Set frame rate, expressed as number of frames per second. Default |
| 9596 | value is "25". |
| 9597 | |
| 9598 | @item size, s |
| 9599 | Set frame size. For the syntax of this option, check the "Video |
| 9600 | size" section in the ffmpeg-utils manual. Default value is "640x480". |
| 9601 | |
| 9602 | @item start_scale |
| 9603 | Set the initial scale value. Default value is 3.0. |
| 9604 | |
| 9605 | @item start_x |
| 9606 | Set the initial x position. Must be a floating point value between |
| 9607 | -100 and 100. Default value is -0.743643887037158704752191506114774. |
| 9608 | |
| 9609 | @item start_y |
| 9610 | Set the initial y position. Must be a floating point value between |
| 9611 | -100 and 100. Default value is -0.131825904205311970493132056385139. |
| 9612 | @end table |
| 9613 | |
| 9614 | @section mptestsrc |
| 9615 | |
| 9616 | Generate various test patterns, as generated by the MPlayer test filter. |
| 9617 | |
| 9618 | The size of the generated video is fixed, and is 256x256. |
| 9619 | This source is useful in particular for testing encoding features. |
| 9620 | |
| 9621 | This source accepts the following options: |
| 9622 | |
| 9623 | @table @option |
| 9624 | |
| 9625 | @item rate, r |
| 9626 | Specify the frame rate of the sourced video, as the number of frames |
| 9627 | generated per second. It has to be a string in the format |
| 9628 | @var{frame_rate_num}/@var{frame_rate_den}, an integer number, a floating point |
| 9629 | number or a valid video frame rate abbreviation. The default value is |
| 9630 | "25". |
| 9631 | |
| 9632 | @item duration, d |
| 9633 | Set the duration of the sourced video. See |
| 9634 | @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils} |
| 9635 | for the accepted syntax. |
| 9636 | |
| 9637 | If not specified, or the expressed duration is negative, the video is |
| 9638 | supposed to be generated forever. |
| 9639 | |
| 9640 | @item test, t |
| 9641 | |
| 9642 | Set the number or the name of the test to perform. Supported tests are: |
| 9643 | @table @option |
| 9644 | @item dc_luma |
| 9645 | @item dc_chroma |
| 9646 | @item freq_luma |
| 9647 | @item freq_chroma |
| 9648 | @item amp_luma |
| 9649 | @item amp_chroma |
| 9650 | @item cbp |
| 9651 | @item mv |
| 9652 | @item ring1 |
| 9653 | @item ring2 |
| 9654 | @item all |
| 9655 | |
| 9656 | @end table |
| 9657 | |
| 9658 | Default value is "all", which will cycle through the list of all tests. |
| 9659 | @end table |
| 9660 | |
| 9661 | Some examples: |
| 9662 | @example |
| 9663 | mptestsrc=t=dc_luma |
| 9664 | @end example |
| 9665 | |
| 9666 | will generate a "dc_luma" test pattern. |
| 9667 | |
| 9668 | @section frei0r_src |
| 9669 | |
| 9670 | Provide a frei0r source. |
| 9671 | |
| 9672 | To enable compilation of this filter you need to install the frei0r |
| 9673 | header and configure FFmpeg with @code{--enable-frei0r}. |
| 9674 | |
| 9675 | This source accepts the following parameters: |
| 9676 | |
| 9677 | @table @option |
| 9678 | |
| 9679 | @item size |
| 9680 | The size of the video to generate. For the syntax of this option, check the |
| 9681 | "Video size" section in the ffmpeg-utils manual. |
| 9682 | |
| 9683 | @item framerate |
| 9684 | The framerate of the generated video. It may be a string of the form |
| 9685 | @var{num}/@var{den} or a frame rate abbreviation. |
| 9686 | |
| 9687 | @item filter_name |
| 9688 | The name to the frei0r source to load. For more information regarding frei0r and |
| 9689 | how to set the parameters, read the @ref{frei0r} section in the video filters |
| 9690 | documentation. |
| 9691 | |
| 9692 | @item filter_params |
| 9693 | A '|'-separated list of parameters to pass to the frei0r source. |
| 9694 | |
| 9695 | @end table |
| 9696 | |
| 9697 | For example, to generate a frei0r partik0l source with size 200x200 |
| 9698 | and frame rate 10 which is overlayed on the overlay filter main input: |
| 9699 | @example |
| 9700 | frei0r_src=size=200x200:framerate=10:filter_name=partik0l:filter_params=1234 [overlay]; [in][overlay] overlay |
| 9701 | @end example |
| 9702 | |
| 9703 | @section life |
| 9704 | |
| 9705 | Generate a life pattern. |
| 9706 | |
| 9707 | This source is based on a generalization of John Conway's life game. |
| 9708 | |
| 9709 | The sourced input represents a life grid, each pixel represents a cell |
| 9710 | which can be in one of two possible states, alive or dead. Every cell |
| 9711 | interacts with its eight neighbours, which are the cells that are |
| 9712 | horizontally, vertically, or diagonally adjacent. |
| 9713 | |
| 9714 | At each interaction the grid evolves according to the adopted rule, |
| 9715 | which specifies the number of neighbor alive cells which will make a |
| 9716 | cell stay alive or born. The @option{rule} option allows one to specify |
| 9717 | the rule to adopt. |
| 9718 | |
| 9719 | This source accepts the following options: |
| 9720 | |
| 9721 | @table @option |
| 9722 | @item filename, f |
| 9723 | Set the file from which to read the initial grid state. In the file, |
| 9724 | each non-whitespace character is considered an alive cell, and newline |
| 9725 | is used to delimit the end of each row. |
| 9726 | |
| 9727 | If this option is not specified, the initial grid is generated |
| 9728 | randomly. |
| 9729 | |
| 9730 | @item rate, r |
| 9731 | Set the video rate, that is the number of frames generated per second. |
| 9732 | Default is 25. |
| 9733 | |
| 9734 | @item random_fill_ratio, ratio |
| 9735 | Set the random fill ratio for the initial random grid. It is a |
| 9736 | floating point number value ranging from 0 to 1, defaults to 1/PHI. |
| 9737 | It is ignored when a file is specified. |
| 9738 | |
| 9739 | @item random_seed, seed |
| 9740 | Set the seed for filling the initial random grid, must be an integer |
| 9741 | included between 0 and UINT32_MAX. If not specified, or if explicitly |
| 9742 | set to -1, the filter will try to use a good random seed on a best |
| 9743 | effort basis. |
| 9744 | |
| 9745 | @item rule |
| 9746 | Set the life rule. |
| 9747 | |
| 9748 | A rule can be specified with a code of the kind "S@var{NS}/B@var{NB}", |
| 9749 | where @var{NS} and @var{NB} are sequences of numbers in the range 0-8, |
| 9750 | @var{NS} specifies the number of alive neighbor cells which make a |
| 9751 | live cell stay alive, and @var{NB} the number of alive neighbor cells |
| 9752 | which make a dead cell to become alive (i.e. to "born"). |
| 9753 | "s" and "b" can be used in place of "S" and "B", respectively. |
| 9754 | |
| 9755 | Alternatively a rule can be specified by an 18-bits integer. The 9 |
| 9756 | high order bits are used to encode the next cell state if it is alive |
| 9757 | for each number of neighbor alive cells, the low order bits specify |
| 9758 | the rule for "borning" new cells. Higher order bits encode for an |
| 9759 | higher number of neighbor cells. |
| 9760 | For example the number 6153 = @code{(12<<9)+9} specifies a stay alive |
| 9761 | rule of 12 and a born rule of 9, which corresponds to "S23/B03". |
| 9762 | |
| 9763 | Default value is "S23/B3", which is the original Conway's game of life |
| 9764 | rule, and will keep a cell alive if it has 2 or 3 neighbor alive |
| 9765 | cells, and will born a new cell if there are three alive cells around |
| 9766 | a dead cell. |
| 9767 | |
| 9768 | @item size, s |
| 9769 | Set the size of the output video. For the syntax of this option, check the |
| 9770 | "Video size" section in the ffmpeg-utils manual. |
| 9771 | |
| 9772 | If @option{filename} is specified, the size is set by default to the |
| 9773 | same size of the input file. If @option{size} is set, it must contain |
| 9774 | the size specified in the input file, and the initial grid defined in |
| 9775 | that file is centered in the larger resulting area. |
| 9776 | |
| 9777 | If a filename is not specified, the size value defaults to "320x240" |
| 9778 | (used for a randomly generated initial grid). |
| 9779 | |
| 9780 | @item stitch |
| 9781 | If set to 1, stitch the left and right grid edges together, and the |
| 9782 | top and bottom edges also. Defaults to 1. |
| 9783 | |
| 9784 | @item mold |
| 9785 | Set cell mold speed. If set, a dead cell will go from @option{death_color} to |
| 9786 | @option{mold_color} with a step of @option{mold}. @option{mold} can have a |
| 9787 | value from 0 to 255. |
| 9788 | |
| 9789 | @item life_color |
| 9790 | Set the color of living (or new born) cells. |
| 9791 | |
| 9792 | @item death_color |
| 9793 | Set the color of dead cells. If @option{mold} is set, this is the first color |
| 9794 | used to represent a dead cell. |
| 9795 | |
| 9796 | @item mold_color |
| 9797 | Set mold color, for definitely dead and moldy cells. |
| 9798 | |
| 9799 | For the syntax of these 3 color options, check the "Color" section in the |
| 9800 | ffmpeg-utils manual. |
| 9801 | @end table |
| 9802 | |
| 9803 | @subsection Examples |
| 9804 | |
| 9805 | @itemize |
| 9806 | @item |
| 9807 | Read a grid from @file{pattern}, and center it on a grid of size |
| 9808 | 300x300 pixels: |
| 9809 | @example |
| 9810 | life=f=pattern:s=300x300 |
| 9811 | @end example |
| 9812 | |
| 9813 | @item |
| 9814 | Generate a random grid of size 200x200, with a fill ratio of 2/3: |
| 9815 | @example |
| 9816 | life=ratio=2/3:s=200x200 |
| 9817 | @end example |
| 9818 | |
| 9819 | @item |
| 9820 | Specify a custom rule for evolving a randomly generated grid: |
| 9821 | @example |
| 9822 | life=rule=S14/B34 |
| 9823 | @end example |
| 9824 | |
| 9825 | @item |
| 9826 | Full example with slow death effect (mold) using @command{ffplay}: |
| 9827 | @example |
| 9828 | ffplay -f lavfi life=s=300x200:mold=10:r=60:ratio=0.1:death_color=#C83232:life_color=#00ff00,scale=1200:800:flags=16 |
| 9829 | @end example |
| 9830 | @end itemize |
| 9831 | |
| 9832 | @anchor{color} |
| 9833 | @anchor{haldclutsrc} |
| 9834 | @anchor{nullsrc} |
| 9835 | @anchor{rgbtestsrc} |
| 9836 | @anchor{smptebars} |
| 9837 | @anchor{smptehdbars} |
| 9838 | @anchor{testsrc} |
| 9839 | @section color, haldclutsrc, nullsrc, rgbtestsrc, smptebars, smptehdbars, testsrc |
| 9840 | |
| 9841 | The @code{color} source provides an uniformly colored input. |
| 9842 | |
| 9843 | The @code{haldclutsrc} source provides an identity Hald CLUT. See also |
| 9844 | @ref{haldclut} filter. |
| 9845 | |
| 9846 | The @code{nullsrc} source returns unprocessed video frames. It is |
| 9847 | mainly useful to be employed in analysis / debugging tools, or as the |
| 9848 | source for filters which ignore the input data. |
| 9849 | |
| 9850 | The @code{rgbtestsrc} source generates an RGB test pattern useful for |
| 9851 | detecting RGB vs BGR issues. You should see a red, green and blue |
| 9852 | stripe from top to bottom. |
| 9853 | |
| 9854 | The @code{smptebars} source generates a color bars pattern, based on |
| 9855 | the SMPTE Engineering Guideline EG 1-1990. |
| 9856 | |
| 9857 | The @code{smptehdbars} source generates a color bars pattern, based on |
| 9858 | the SMPTE RP 219-2002. |
| 9859 | |
| 9860 | The @code{testsrc} source generates a test video pattern, showing a |
| 9861 | color pattern, a scrolling gradient and a timestamp. This is mainly |
| 9862 | intended for testing purposes. |
| 9863 | |
| 9864 | The sources accept the following parameters: |
| 9865 | |
| 9866 | @table @option |
| 9867 | |
| 9868 | @item color, c |
| 9869 | Specify the color of the source, only available in the @code{color} |
| 9870 | source. For the syntax of this option, check the "Color" section in the |
| 9871 | ffmpeg-utils manual. |
| 9872 | |
| 9873 | @item level |
| 9874 | Specify the level of the Hald CLUT, only available in the @code{haldclutsrc} |
| 9875 | source. A level of @code{N} generates a picture of @code{N*N*N} by @code{N*N*N} |
| 9876 | pixels to be used as identity matrix for 3D lookup tables. Each component is |
| 9877 | coded on a @code{1/(N*N)} scale. |
| 9878 | |
| 9879 | @item size, s |
| 9880 | Specify the size of the sourced video. For the syntax of this option, check the |
| 9881 | "Video size" section in the ffmpeg-utils manual. The default value is |
| 9882 | "320x240". |
| 9883 | |
| 9884 | This option is not available with the @code{haldclutsrc} filter. |
| 9885 | |
| 9886 | @item rate, r |
| 9887 | Specify the frame rate of the sourced video, as the number of frames |
| 9888 | generated per second. It has to be a string in the format |
| 9889 | @var{frame_rate_num}/@var{frame_rate_den}, an integer number, a floating point |
| 9890 | number or a valid video frame rate abbreviation. The default value is |
| 9891 | "25". |
| 9892 | |
| 9893 | @item sar |
| 9894 | Set the sample aspect ratio of the sourced video. |
| 9895 | |
| 9896 | @item duration, d |
| 9897 | Set the duration of the sourced video. See |
| 9898 | @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils} |
| 9899 | for the accepted syntax. |
| 9900 | |
| 9901 | If not specified, or the expressed duration is negative, the video is |
| 9902 | supposed to be generated forever. |
| 9903 | |
| 9904 | @item decimals, n |
| 9905 | Set the number of decimals to show in the timestamp, only available in the |
| 9906 | @code{testsrc} source. |
| 9907 | |
| 9908 | The displayed timestamp value will correspond to the original |
| 9909 | timestamp value multiplied by the power of 10 of the specified |
| 9910 | value. Default value is 0. |
| 9911 | @end table |
| 9912 | |
| 9913 | For example the following: |
| 9914 | @example |
| 9915 | testsrc=duration=5.3:size=qcif:rate=10 |
| 9916 | @end example |
| 9917 | |
| 9918 | will generate a video with a duration of 5.3 seconds, with size |
| 9919 | 176x144 and a frame rate of 10 frames per second. |
| 9920 | |
| 9921 | The following graph description will generate a red source |
| 9922 | with an opacity of 0.2, with size "qcif" and a frame rate of 10 |
| 9923 | frames per second. |
| 9924 | @example |
| 9925 | color=c=red@@0.2:s=qcif:r=10 |
| 9926 | @end example |
| 9927 | |
| 9928 | If the input content is to be ignored, @code{nullsrc} can be used. The |
| 9929 | following command generates noise in the luminance plane by employing |
| 9930 | the @code{geq} filter: |
| 9931 | @example |
| 9932 | nullsrc=s=256x256, geq=random(1)*255:128:128 |
| 9933 | @end example |
| 9934 | |
| 9935 | @subsection Commands |
| 9936 | |
| 9937 | The @code{color} source supports the following commands: |
| 9938 | |
| 9939 | @table @option |
| 9940 | @item c, color |
| 9941 | Set the color of the created image. Accepts the same syntax of the |
| 9942 | corresponding @option{color} option. |
| 9943 | @end table |
| 9944 | |
| 9945 | @c man end VIDEO SOURCES |
| 9946 | |
| 9947 | @chapter Video Sinks |
| 9948 | @c man begin VIDEO SINKS |
| 9949 | |
| 9950 | Below is a description of the currently available video sinks. |
| 9951 | |
| 9952 | @section buffersink |
| 9953 | |
| 9954 | Buffer video frames, and make them available to the end of the filter |
| 9955 | graph. |
| 9956 | |
| 9957 | This sink is mainly intended for programmatic use, in particular |
| 9958 | through the interface defined in @file{libavfilter/buffersink.h} |
| 9959 | or the options system. |
| 9960 | |
| 9961 | It accepts a pointer to an AVBufferSinkContext structure, which |
| 9962 | defines the incoming buffers' formats, to be passed as the opaque |
| 9963 | parameter to @code{avfilter_init_filter} for initialization. |
| 9964 | |
| 9965 | @section nullsink |
| 9966 | |
| 9967 | Null video sink: do absolutely nothing with the input video. It is |
| 9968 | mainly useful as a template and for use in analysis / debugging |
| 9969 | tools. |
| 9970 | |
| 9971 | @c man end VIDEO SINKS |
| 9972 | |
| 9973 | @chapter Multimedia Filters |
| 9974 | @c man begin MULTIMEDIA FILTERS |
| 9975 | |
| 9976 | Below is a description of the currently available multimedia filters. |
| 9977 | |
| 9978 | @section avectorscope |
| 9979 | |
| 9980 | Convert input audio to a video output, representing the audio vector |
| 9981 | scope. |
| 9982 | |
| 9983 | The filter is used to measure the difference between channels of stereo |
| 9984 | audio stream. A monoaural signal, consisting of identical left and right |
| 9985 | signal, results in straight vertical line. Any stereo separation is visible |
| 9986 | as a deviation from this line, creating a Lissajous figure. |
| 9987 | If the straight (or deviation from it) but horizontal line appears this |
| 9988 | indicates that the left and right channels are out of phase. |
| 9989 | |
| 9990 | The filter accepts the following options: |
| 9991 | |
| 9992 | @table @option |
| 9993 | @item mode, m |
| 9994 | Set the vectorscope mode. |
| 9995 | |
| 9996 | Available values are: |
| 9997 | @table @samp |
| 9998 | @item lissajous |
| 9999 | Lissajous rotated by 45 degrees. |
| 10000 | |
| 10001 | @item lissajous_xy |
| 10002 | Same as above but not rotated. |
| 10003 | @end table |
| 10004 | |
| 10005 | Default value is @samp{lissajous}. |
| 10006 | |
| 10007 | @item size, s |
| 10008 | Set the video size for the output. For the syntax of this option, check the "Video size" |
| 10009 | section in the ffmpeg-utils manual. Default value is @code{400x400}. |
| 10010 | |
| 10011 | @item rate, r |
| 10012 | Set the output frame rate. Default value is @code{25}. |
| 10013 | |
| 10014 | @item rc |
| 10015 | @item gc |
| 10016 | @item bc |
| 10017 | Specify the red, green and blue contrast. Default values are @code{40}, @code{160} and @code{80}. |
| 10018 | Allowed range is @code{[0, 255]}. |
| 10019 | |
| 10020 | @item rf |
| 10021 | @item gf |
| 10022 | @item bf |
| 10023 | Specify the red, green and blue fade. Default values are @code{15}, @code{10} and @code{5}. |
| 10024 | Allowed range is @code{[0, 255]}. |
| 10025 | |
| 10026 | @item zoom |
| 10027 | Set the zoom factor. Default value is @code{1}. Allowed range is @code{[1, 10]}. |
| 10028 | @end table |
| 10029 | |
| 10030 | @subsection Examples |
| 10031 | |
| 10032 | @itemize |
| 10033 | @item |
| 10034 | Complete example using @command{ffplay}: |
| 10035 | @example |
| 10036 | ffplay -f lavfi 'amovie=input.mp3, asplit [a][out1]; |
| 10037 | [a] avectorscope=zoom=1.3:rc=2:gc=200:bc=10:rf=1:gf=8:bf=7 [out0]' |
| 10038 | @end example |
| 10039 | @end itemize |
| 10040 | |
| 10041 | @section concat |
| 10042 | |
| 10043 | Concatenate audio and video streams, joining them together one after the |
| 10044 | other. |
| 10045 | |
| 10046 | The filter works on segments of synchronized video and audio streams. All |
| 10047 | segments must have the same number of streams of each type, and that will |
| 10048 | also be the number of streams at output. |
| 10049 | |
| 10050 | The filter accepts the following options: |
| 10051 | |
| 10052 | @table @option |
| 10053 | |
| 10054 | @item n |
| 10055 | Set the number of segments. Default is 2. |
| 10056 | |
| 10057 | @item v |
| 10058 | Set the number of output video streams, that is also the number of video |
| 10059 | streams in each segment. Default is 1. |
| 10060 | |
| 10061 | @item a |
| 10062 | Set the number of output audio streams, that is also the number of audio |
| 10063 | streams in each segment. Default is 0. |
| 10064 | |
| 10065 | @item unsafe |
| 10066 | Activate unsafe mode: do not fail if segments have a different format. |
| 10067 | |
| 10068 | @end table |
| 10069 | |
| 10070 | The filter has @var{v}+@var{a} outputs: first @var{v} video outputs, then |
| 10071 | @var{a} audio outputs. |
| 10072 | |
| 10073 | There are @var{n}x(@var{v}+@var{a}) inputs: first the inputs for the first |
| 10074 | segment, in the same order as the outputs, then the inputs for the second |
| 10075 | segment, etc. |
| 10076 | |
| 10077 | Related streams do not always have exactly the same duration, for various |
| 10078 | reasons including codec frame size or sloppy authoring. For that reason, |
| 10079 | related synchronized streams (e.g. a video and its audio track) should be |
| 10080 | concatenated at once. The concat filter will use the duration of the longest |
| 10081 | stream in each segment (except the last one), and if necessary pad shorter |
| 10082 | audio streams with silence. |
| 10083 | |
| 10084 | For this filter to work correctly, all segments must start at timestamp 0. |
| 10085 | |
| 10086 | All corresponding streams must have the same parameters in all segments; the |
| 10087 | filtering system will automatically select a common pixel format for video |
| 10088 | streams, and a common sample format, sample rate and channel layout for |
| 10089 | audio streams, but other settings, such as resolution, must be converted |
| 10090 | explicitly by the user. |
| 10091 | |
| 10092 | Different frame rates are acceptable but will result in variable frame rate |
| 10093 | at output; be sure to configure the output file to handle it. |
| 10094 | |
| 10095 | @subsection Examples |
| 10096 | |
| 10097 | @itemize |
| 10098 | @item |
| 10099 | Concatenate an opening, an episode and an ending, all in bilingual version |
| 10100 | (video in stream 0, audio in streams 1 and 2): |
| 10101 | @example |
| 10102 | ffmpeg -i opening.mkv -i episode.mkv -i ending.mkv -filter_complex \ |
| 10103 | '[0:0] [0:1] [0:2] [1:0] [1:1] [1:2] [2:0] [2:1] [2:2] |
| 10104 | concat=n=3:v=1:a=2 [v] [a1] [a2]' \ |
| 10105 | -map '[v]' -map '[a1]' -map '[a2]' output.mkv |
| 10106 | @end example |
| 10107 | |
| 10108 | @item |
| 10109 | Concatenate two parts, handling audio and video separately, using the |
| 10110 | (a)movie sources, and adjusting the resolution: |
| 10111 | @example |
| 10112 | movie=part1.mp4, scale=512:288 [v1] ; amovie=part1.mp4 [a1] ; |
| 10113 | movie=part2.mp4, scale=512:288 [v2] ; amovie=part2.mp4 [a2] ; |
| 10114 | [v1] [v2] concat [outv] ; [a1] [a2] concat=v=0:a=1 [outa] |
| 10115 | @end example |
| 10116 | Note that a desync will happen at the stitch if the audio and video streams |
| 10117 | do not have exactly the same duration in the first file. |
| 10118 | |
| 10119 | @end itemize |
| 10120 | |
| 10121 | @section ebur128 |
| 10122 | |
| 10123 | EBU R128 scanner filter. This filter takes an audio stream as input and outputs |
| 10124 | it unchanged. By default, it logs a message at a frequency of 10Hz with the |
| 10125 | Momentary loudness (identified by @code{M}), Short-term loudness (@code{S}), |
| 10126 | Integrated loudness (@code{I}) and Loudness Range (@code{LRA}). |
| 10127 | |
| 10128 | The filter also has a video output (see the @var{video} option) with a real |
| 10129 | time graph to observe the loudness evolution. The graphic contains the logged |
| 10130 | message mentioned above, so it is not printed anymore when this option is set, |
| 10131 | unless the verbose logging is set. The main graphing area contains the |
| 10132 | short-term loudness (3 seconds of analysis), and the gauge on the right is for |
| 10133 | the momentary loudness (400 milliseconds). |
| 10134 | |
| 10135 | More information about the Loudness Recommendation EBU R128 on |
| 10136 | @url{http://tech.ebu.ch/loudness}. |
| 10137 | |
| 10138 | The filter accepts the following options: |
| 10139 | |
| 10140 | @table @option |
| 10141 | |
| 10142 | @item video |
| 10143 | Activate the video output. The audio stream is passed unchanged whether this |
| 10144 | option is set or no. The video stream will be the first output stream if |
| 10145 | activated. Default is @code{0}. |
| 10146 | |
| 10147 | @item size |
| 10148 | Set the video size. This option is for video only. For the syntax of this |
| 10149 | option, check the "Video size" section in the ffmpeg-utils manual. Default |
| 10150 | and minimum resolution is @code{640x480}. |
| 10151 | |
| 10152 | @item meter |
| 10153 | Set the EBU scale meter. Default is @code{9}. Common values are @code{9} and |
| 10154 | @code{18}, respectively for EBU scale meter +9 and EBU scale meter +18. Any |
| 10155 | other integer value between this range is allowed. |
| 10156 | |
| 10157 | @item metadata |
| 10158 | Set metadata injection. If set to @code{1}, the audio input will be segmented |
| 10159 | into 100ms output frames, each of them containing various loudness information |
| 10160 | in metadata. All the metadata keys are prefixed with @code{lavfi.r128.}. |
| 10161 | |
| 10162 | Default is @code{0}. |
| 10163 | |
| 10164 | @item framelog |
| 10165 | Force the frame logging level. |
| 10166 | |
| 10167 | Available values are: |
| 10168 | @table @samp |
| 10169 | @item info |
| 10170 | information logging level |
| 10171 | @item verbose |
| 10172 | verbose logging level |
| 10173 | @end table |
| 10174 | |
| 10175 | By default, the logging level is set to @var{info}. If the @option{video} or |
| 10176 | the @option{metadata} options are set, it switches to @var{verbose}. |
| 10177 | |
| 10178 | @item peak |
| 10179 | Set peak mode(s). |
| 10180 | |
| 10181 | Available modes can be cumulated (the option is a @code{flag} type). Possible |
| 10182 | values are: |
| 10183 | @table @samp |
| 10184 | @item none |
| 10185 | Disable any peak mode (default). |
| 10186 | @item sample |
| 10187 | Enable sample-peak mode. |
| 10188 | |
| 10189 | Simple peak mode looking for the higher sample value. It logs a message |
| 10190 | for sample-peak (identified by @code{SPK}). |
| 10191 | @item true |
| 10192 | Enable true-peak mode. |
| 10193 | |
| 10194 | If enabled, the peak lookup is done on an over-sampled version of the input |
| 10195 | stream for better peak accuracy. It logs a message for true-peak. |
| 10196 | (identified by @code{TPK}) and true-peak per frame (identified by @code{FTPK}). |
| 10197 | This mode requires a build with @code{libswresample}. |
| 10198 | @end table |
| 10199 | |
| 10200 | @end table |
| 10201 | |
| 10202 | @subsection Examples |
| 10203 | |
| 10204 | @itemize |
| 10205 | @item |
| 10206 | Real-time graph using @command{ffplay}, with a EBU scale meter +18: |
| 10207 | @example |
| 10208 | ffplay -f lavfi -i "amovie=input.mp3,ebur128=video=1:meter=18 [out0][out1]" |
| 10209 | @end example |
| 10210 | |
| 10211 | @item |
| 10212 | Run an analysis with @command{ffmpeg}: |
| 10213 | @example |
| 10214 | ffmpeg -nostats -i input.mp3 -filter_complex ebur128 -f null - |
| 10215 | @end example |
| 10216 | @end itemize |
| 10217 | |
| 10218 | @section interleave, ainterleave |
| 10219 | |
| 10220 | Temporally interleave frames from several inputs. |
| 10221 | |
| 10222 | @code{interleave} works with video inputs, @code{ainterleave} with audio. |
| 10223 | |
| 10224 | These filters read frames from several inputs and send the oldest |
| 10225 | queued frame to the output. |
| 10226 | |
| 10227 | Input streams must have a well defined, monotonically increasing frame |
| 10228 | timestamp values. |
| 10229 | |
| 10230 | In order to submit one frame to output, these filters need to enqueue |
| 10231 | at least one frame for each input, so they cannot work in case one |
| 10232 | input is not yet terminated and will not receive incoming frames. |
| 10233 | |
| 10234 | For example consider the case when one input is a @code{select} filter |
| 10235 | which always drop input frames. The @code{interleave} filter will keep |
| 10236 | reading from that input, but it will never be able to send new frames |
| 10237 | to output until the input will send an end-of-stream signal. |
| 10238 | |
| 10239 | Also, depending on inputs synchronization, the filters will drop |
| 10240 | frames in case one input receives more frames than the other ones, and |
| 10241 | the queue is already filled. |
| 10242 | |
| 10243 | These filters accept the following options: |
| 10244 | |
| 10245 | @table @option |
| 10246 | @item nb_inputs, n |
| 10247 | Set the number of different inputs, it is 2 by default. |
| 10248 | @end table |
| 10249 | |
| 10250 | @subsection Examples |
| 10251 | |
| 10252 | @itemize |
| 10253 | @item |
| 10254 | Interleave frames belonging to different streams using @command{ffmpeg}: |
| 10255 | @example |
| 10256 | ffmpeg -i bambi.avi -i pr0n.mkv -filter_complex "[0:v][1:v] interleave" out.avi |
| 10257 | @end example |
| 10258 | |
| 10259 | @item |
| 10260 | Add flickering blur effect: |
| 10261 | @example |
| 10262 | select='if(gt(random(0), 0.2), 1, 2)':n=2 [tmp], boxblur=2:2, [tmp] interleave |
| 10263 | @end example |
| 10264 | @end itemize |
| 10265 | |
| 10266 | @section perms, aperms |
| 10267 | |
| 10268 | Set read/write permissions for the output frames. |
| 10269 | |
| 10270 | These filters are mainly aimed at developers to test direct path in the |
| 10271 | following filter in the filtergraph. |
| 10272 | |
| 10273 | The filters accept the following options: |
| 10274 | |
| 10275 | @table @option |
| 10276 | @item mode |
| 10277 | Select the permissions mode. |
| 10278 | |
| 10279 | It accepts the following values: |
| 10280 | @table @samp |
| 10281 | @item none |
| 10282 | Do nothing. This is the default. |
| 10283 | @item ro |
| 10284 | Set all the output frames read-only. |
| 10285 | @item rw |
| 10286 | Set all the output frames directly writable. |
| 10287 | @item toggle |
| 10288 | Make the frame read-only if writable, and writable if read-only. |
| 10289 | @item random |
| 10290 | Set each output frame read-only or writable randomly. |
| 10291 | @end table |
| 10292 | |
| 10293 | @item seed |
| 10294 | Set the seed for the @var{random} mode, must be an integer included between |
| 10295 | @code{0} and @code{UINT32_MAX}. If not specified, or if explicitly set to |
| 10296 | @code{-1}, the filter will try to use a good random seed on a best effort |
| 10297 | basis. |
| 10298 | @end table |
| 10299 | |
| 10300 | Note: in case of auto-inserted filter between the permission filter and the |
| 10301 | following one, the permission might not be received as expected in that |
| 10302 | following filter. Inserting a @ref{format} or @ref{aformat} filter before the |
| 10303 | perms/aperms filter can avoid this problem. |
| 10304 | |
| 10305 | @section select, aselect |
| 10306 | |
| 10307 | Select frames to pass in output. |
| 10308 | |
| 10309 | This filter accepts the following options: |
| 10310 | |
| 10311 | @table @option |
| 10312 | |
| 10313 | @item expr, e |
| 10314 | Set expression, which is evaluated for each input frame. |
| 10315 | |
| 10316 | If the expression is evaluated to zero, the frame is discarded. |
| 10317 | |
| 10318 | If the evaluation result is negative or NaN, the frame is sent to the |
| 10319 | first output; otherwise it is sent to the output with index |
| 10320 | @code{ceil(val)-1}, assuming that the input index starts from 0. |
| 10321 | |
| 10322 | For example a value of @code{1.2} corresponds to the output with index |
| 10323 | @code{ceil(1.2)-1 = 2-1 = 1}, that is the second output. |
| 10324 | |
| 10325 | @item outputs, n |
| 10326 | Set the number of outputs. The output to which to send the selected |
| 10327 | frame is based on the result of the evaluation. Default value is 1. |
| 10328 | @end table |
| 10329 | |
| 10330 | The expression can contain the following constants: |
| 10331 | |
| 10332 | @table @option |
| 10333 | @item n |
| 10334 | The (sequential) number of the filtered frame, starting from 0. |
| 10335 | |
| 10336 | @item selected_n |
| 10337 | The (sequential) number of the selected frame, starting from 0. |
| 10338 | |
| 10339 | @item prev_selected_n |
| 10340 | The sequential number of the last selected frame. It's NAN if undefined. |
| 10341 | |
| 10342 | @item TB |
| 10343 | The timebase of the input timestamps. |
| 10344 | |
| 10345 | @item pts |
| 10346 | The PTS (Presentation TimeStamp) of the filtered video frame, |
| 10347 | expressed in @var{TB} units. It's NAN if undefined. |
| 10348 | |
| 10349 | @item t |
| 10350 | The PTS of the filtered video frame, |
| 10351 | expressed in seconds. It's NAN if undefined. |
| 10352 | |
| 10353 | @item prev_pts |
| 10354 | The PTS of the previously filtered video frame. It's NAN if undefined. |
| 10355 | |
| 10356 | @item prev_selected_pts |
| 10357 | The PTS of the last previously filtered video frame. It's NAN if undefined. |
| 10358 | |
| 10359 | @item prev_selected_t |
| 10360 | The PTS of the last previously selected video frame. It's NAN if undefined. |
| 10361 | |
| 10362 | @item start_pts |
| 10363 | The PTS of the first video frame in the video. It's NAN if undefined. |
| 10364 | |
| 10365 | @item start_t |
| 10366 | The time of the first video frame in the video. It's NAN if undefined. |
| 10367 | |
| 10368 | @item pict_type @emph{(video only)} |
| 10369 | The type of the filtered frame. It can assume one of the following |
| 10370 | values: |
| 10371 | @table @option |
| 10372 | @item I |
| 10373 | @item P |
| 10374 | @item B |
| 10375 | @item S |
| 10376 | @item SI |
| 10377 | @item SP |
| 10378 | @item BI |
| 10379 | @end table |
| 10380 | |
| 10381 | @item interlace_type @emph{(video only)} |
| 10382 | The frame interlace type. It can assume one of the following values: |
| 10383 | @table @option |
| 10384 | @item PROGRESSIVE |
| 10385 | The frame is progressive (not interlaced). |
| 10386 | @item TOPFIRST |
| 10387 | The frame is top-field-first. |
| 10388 | @item BOTTOMFIRST |
| 10389 | The frame is bottom-field-first. |
| 10390 | @end table |
| 10391 | |
| 10392 | @item consumed_sample_n @emph{(audio only)} |
| 10393 | the number of selected samples before the current frame |
| 10394 | |
| 10395 | @item samples_n @emph{(audio only)} |
| 10396 | the number of samples in the current frame |
| 10397 | |
| 10398 | @item sample_rate @emph{(audio only)} |
| 10399 | the input sample rate |
| 10400 | |
| 10401 | @item key |
| 10402 | This is 1 if the filtered frame is a key-frame, 0 otherwise. |
| 10403 | |
| 10404 | @item pos |
| 10405 | the position in the file of the filtered frame, -1 if the information |
| 10406 | is not available (e.g. for synthetic video) |
| 10407 | |
| 10408 | @item scene @emph{(video only)} |
| 10409 | value between 0 and 1 to indicate a new scene; a low value reflects a low |
| 10410 | probability for the current frame to introduce a new scene, while a higher |
| 10411 | value means the current frame is more likely to be one (see the example below) |
| 10412 | |
| 10413 | @end table |
| 10414 | |
| 10415 | The default value of the select expression is "1". |
| 10416 | |
| 10417 | @subsection Examples |
| 10418 | |
| 10419 | @itemize |
| 10420 | @item |
| 10421 | Select all frames in input: |
| 10422 | @example |
| 10423 | select |
| 10424 | @end example |
| 10425 | |
| 10426 | The example above is the same as: |
| 10427 | @example |
| 10428 | select=1 |
| 10429 | @end example |
| 10430 | |
| 10431 | @item |
| 10432 | Skip all frames: |
| 10433 | @example |
| 10434 | select=0 |
| 10435 | @end example |
| 10436 | |
| 10437 | @item |
| 10438 | Select only I-frames: |
| 10439 | @example |
| 10440 | select='eq(pict_type\,I)' |
| 10441 | @end example |
| 10442 | |
| 10443 | @item |
| 10444 | Select one frame every 100: |
| 10445 | @example |
| 10446 | select='not(mod(n\,100))' |
| 10447 | @end example |
| 10448 | |
| 10449 | @item |
| 10450 | Select only frames contained in the 10-20 time interval: |
| 10451 | @example |
| 10452 | select=between(t\,10\,20) |
| 10453 | @end example |
| 10454 | |
| 10455 | @item |
| 10456 | Select only I frames contained in the 10-20 time interval: |
| 10457 | @example |
| 10458 | select=between(t\,10\,20)*eq(pict_type\,I) |
| 10459 | @end example |
| 10460 | |
| 10461 | @item |
| 10462 | Select frames with a minimum distance of 10 seconds: |
| 10463 | @example |
| 10464 | select='isnan(prev_selected_t)+gte(t-prev_selected_t\,10)' |
| 10465 | @end example |
| 10466 | |
| 10467 | @item |
| 10468 | Use aselect to select only audio frames with samples number > 100: |
| 10469 | @example |
| 10470 | aselect='gt(samples_n\,100)' |
| 10471 | @end example |
| 10472 | |
| 10473 | @item |
| 10474 | Create a mosaic of the first scenes: |
| 10475 | @example |
| 10476 | ffmpeg -i video.avi -vf select='gt(scene\,0.4)',scale=160:120,tile -frames:v 1 preview.png |
| 10477 | @end example |
| 10478 | |
| 10479 | Comparing @var{scene} against a value between 0.3 and 0.5 is generally a sane |
| 10480 | choice. |
| 10481 | |
| 10482 | @item |
| 10483 | Send even and odd frames to separate outputs, and compose them: |
| 10484 | @example |
| 10485 | select=n=2:e='mod(n, 2)+1' [odd][even]; [odd] pad=h=2*ih [tmp]; [tmp][even] overlay=y=h |
| 10486 | @end example |
| 10487 | @end itemize |
| 10488 | |
| 10489 | @section sendcmd, asendcmd |
| 10490 | |
| 10491 | Send commands to filters in the filtergraph. |
| 10492 | |
| 10493 | These filters read commands to be sent to other filters in the |
| 10494 | filtergraph. |
| 10495 | |
| 10496 | @code{sendcmd} must be inserted between two video filters, |
| 10497 | @code{asendcmd} must be inserted between two audio filters, but apart |
| 10498 | from that they act the same way. |
| 10499 | |
| 10500 | The specification of commands can be provided in the filter arguments |
| 10501 | with the @var{commands} option, or in a file specified by the |
| 10502 | @var{filename} option. |
| 10503 | |
| 10504 | These filters accept the following options: |
| 10505 | @table @option |
| 10506 | @item commands, c |
| 10507 | Set the commands to be read and sent to the other filters. |
| 10508 | @item filename, f |
| 10509 | Set the filename of the commands to be read and sent to the other |
| 10510 | filters. |
| 10511 | @end table |
| 10512 | |
| 10513 | @subsection Commands syntax |
| 10514 | |
| 10515 | A commands description consists of a sequence of interval |
| 10516 | specifications, comprising a list of commands to be executed when a |
| 10517 | particular event related to that interval occurs. The occurring event |
| 10518 | is typically the current frame time entering or leaving a given time |
| 10519 | interval. |
| 10520 | |
| 10521 | An interval is specified by the following syntax: |
| 10522 | @example |
| 10523 | @var{START}[-@var{END}] @var{COMMANDS}; |
| 10524 | @end example |
| 10525 | |
| 10526 | The time interval is specified by the @var{START} and @var{END} times. |
| 10527 | @var{END} is optional and defaults to the maximum time. |
| 10528 | |
| 10529 | The current frame time is considered within the specified interval if |
| 10530 | it is included in the interval [@var{START}, @var{END}), that is when |
| 10531 | the time is greater or equal to @var{START} and is lesser than |
| 10532 | @var{END}. |
| 10533 | |
| 10534 | @var{COMMANDS} consists of a sequence of one or more command |
| 10535 | specifications, separated by ",", relating to that interval. The |
| 10536 | syntax of a command specification is given by: |
| 10537 | @example |
| 10538 | [@var{FLAGS}] @var{TARGET} @var{COMMAND} @var{ARG} |
| 10539 | @end example |
| 10540 | |
| 10541 | @var{FLAGS} is optional and specifies the type of events relating to |
| 10542 | the time interval which enable sending the specified command, and must |
| 10543 | be a non-null sequence of identifier flags separated by "+" or "|" and |
| 10544 | enclosed between "[" and "]". |
| 10545 | |
| 10546 | The following flags are recognized: |
| 10547 | @table @option |
| 10548 | @item enter |
| 10549 | The command is sent when the current frame timestamp enters the |
| 10550 | specified interval. In other words, the command is sent when the |
| 10551 | previous frame timestamp was not in the given interval, and the |
| 10552 | current is. |
| 10553 | |
| 10554 | @item leave |
| 10555 | The command is sent when the current frame timestamp leaves the |
| 10556 | specified interval. In other words, the command is sent when the |
| 10557 | previous frame timestamp was in the given interval, and the |
| 10558 | current is not. |
| 10559 | @end table |
| 10560 | |
| 10561 | If @var{FLAGS} is not specified, a default value of @code{[enter]} is |
| 10562 | assumed. |
| 10563 | |
| 10564 | @var{TARGET} specifies the target of the command, usually the name of |
| 10565 | the filter class or a specific filter instance name. |
| 10566 | |
| 10567 | @var{COMMAND} specifies the name of the command for the target filter. |
| 10568 | |
| 10569 | @var{ARG} is optional and specifies the optional list of argument for |
| 10570 | the given @var{COMMAND}. |
| 10571 | |
| 10572 | Between one interval specification and another, whitespaces, or |
| 10573 | sequences of characters starting with @code{#} until the end of line, |
| 10574 | are ignored and can be used to annotate comments. |
| 10575 | |
| 10576 | A simplified BNF description of the commands specification syntax |
| 10577 | follows: |
| 10578 | @example |
| 10579 | @var{COMMAND_FLAG} ::= "enter" | "leave" |
| 10580 | @var{COMMAND_FLAGS} ::= @var{COMMAND_FLAG} [(+|"|")@var{COMMAND_FLAG}] |
| 10581 | @var{COMMAND} ::= ["[" @var{COMMAND_FLAGS} "]"] @var{TARGET} @var{COMMAND} [@var{ARG}] |
| 10582 | @var{COMMANDS} ::= @var{COMMAND} [,@var{COMMANDS}] |
| 10583 | @var{INTERVAL} ::= @var{START}[-@var{END}] @var{COMMANDS} |
| 10584 | @var{INTERVALS} ::= @var{INTERVAL}[;@var{INTERVALS}] |
| 10585 | @end example |
| 10586 | |
| 10587 | @subsection Examples |
| 10588 | |
| 10589 | @itemize |
| 10590 | @item |
| 10591 | Specify audio tempo change at second 4: |
| 10592 | @example |
| 10593 | asendcmd=c='4.0 atempo tempo 1.5',atempo |
| 10594 | @end example |
| 10595 | |
| 10596 | @item |
| 10597 | Specify a list of drawtext and hue commands in a file. |
| 10598 | @example |
| 10599 | # show text in the interval 5-10 |
| 10600 | 5.0-10.0 [enter] drawtext reinit 'fontfile=FreeSerif.ttf:text=hello world', |
| 10601 | [leave] drawtext reinit 'fontfile=FreeSerif.ttf:text='; |
| 10602 | |
| 10603 | # desaturate the image in the interval 15-20 |
| 10604 | 15.0-20.0 [enter] hue s 0, |
| 10605 | [enter] drawtext reinit 'fontfile=FreeSerif.ttf:text=nocolor', |
| 10606 | [leave] hue s 1, |
| 10607 | [leave] drawtext reinit 'fontfile=FreeSerif.ttf:text=color'; |
| 10608 | |
| 10609 | # apply an exponential saturation fade-out effect, starting from time 25 |
| 10610 | 25 [enter] hue s exp(25-t) |
| 10611 | @end example |
| 10612 | |
| 10613 | A filtergraph allowing to read and process the above command list |
| 10614 | stored in a file @file{test.cmd}, can be specified with: |
| 10615 | @example |
| 10616 | sendcmd=f=test.cmd,drawtext=fontfile=FreeSerif.ttf:text='',hue |
| 10617 | @end example |
| 10618 | @end itemize |
| 10619 | |
| 10620 | @anchor{setpts} |
| 10621 | @section setpts, asetpts |
| 10622 | |
| 10623 | Change the PTS (presentation timestamp) of the input frames. |
| 10624 | |
| 10625 | @code{setpts} works on video frames, @code{asetpts} on audio frames. |
| 10626 | |
| 10627 | This filter accepts the following options: |
| 10628 | |
| 10629 | @table @option |
| 10630 | |
| 10631 | @item expr |
| 10632 | The expression which is evaluated for each frame to construct its timestamp. |
| 10633 | |
| 10634 | @end table |
| 10635 | |
| 10636 | The expression is evaluated through the eval API and can contain the following |
| 10637 | constants: |
| 10638 | |
| 10639 | @table @option |
| 10640 | @item FRAME_RATE |
| 10641 | frame rate, only defined for constant frame-rate video |
| 10642 | |
| 10643 | @item PTS |
| 10644 | The presentation timestamp in input |
| 10645 | |
| 10646 | @item N |
| 10647 | The count of the input frame for video or the number of consumed samples, |
| 10648 | not including the current frame for audio, starting from 0. |
| 10649 | |
| 10650 | @item NB_CONSUMED_SAMPLES |
| 10651 | The number of consumed samples, not including the current frame (only |
| 10652 | audio) |
| 10653 | |
| 10654 | @item NB_SAMPLES, S |
| 10655 | The number of samples in the current frame (only audio) |
| 10656 | |
| 10657 | @item SAMPLE_RATE, SR |
| 10658 | The audio sample rate. |
| 10659 | |
| 10660 | @item STARTPTS |
| 10661 | The PTS of the first frame. |
| 10662 | |
| 10663 | @item STARTT |
| 10664 | the time in seconds of the first frame |
| 10665 | |
| 10666 | @item INTERLACED |
| 10667 | State whether the current frame is interlaced. |
| 10668 | |
| 10669 | @item T |
| 10670 | the time in seconds of the current frame |
| 10671 | |
| 10672 | @item POS |
| 10673 | original position in the file of the frame, or undefined if undefined |
| 10674 | for the current frame |
| 10675 | |
| 10676 | @item PREV_INPTS |
| 10677 | The previous input PTS. |
| 10678 | |
| 10679 | @item PREV_INT |
| 10680 | previous input time in seconds |
| 10681 | |
| 10682 | @item PREV_OUTPTS |
| 10683 | The previous output PTS. |
| 10684 | |
| 10685 | @item PREV_OUTT |
| 10686 | previous output time in seconds |
| 10687 | |
| 10688 | @item RTCTIME |
| 10689 | The wallclock (RTC) time in microseconds.. This is deprecated, use time(0) |
| 10690 | instead. |
| 10691 | |
| 10692 | @item RTCSTART |
| 10693 | The wallclock (RTC) time at the start of the movie in microseconds. |
| 10694 | |
| 10695 | @item TB |
| 10696 | The timebase of the input timestamps. |
| 10697 | |
| 10698 | @end table |
| 10699 | |
| 10700 | @subsection Examples |
| 10701 | |
| 10702 | @itemize |
| 10703 | @item |
| 10704 | Start counting PTS from zero |
| 10705 | @example |
| 10706 | setpts=PTS-STARTPTS |
| 10707 | @end example |
| 10708 | |
| 10709 | @item |
| 10710 | Apply fast motion effect: |
| 10711 | @example |
| 10712 | setpts=0.5*PTS |
| 10713 | @end example |
| 10714 | |
| 10715 | @item |
| 10716 | Apply slow motion effect: |
| 10717 | @example |
| 10718 | setpts=2.0*PTS |
| 10719 | @end example |
| 10720 | |
| 10721 | @item |
| 10722 | Set fixed rate of 25 frames per second: |
| 10723 | @example |
| 10724 | setpts=N/(25*TB) |
| 10725 | @end example |
| 10726 | |
| 10727 | @item |
| 10728 | Set fixed rate 25 fps with some jitter: |
| 10729 | @example |
| 10730 | setpts='1/(25*TB) * (N + 0.05 * sin(N*2*PI/25))' |
| 10731 | @end example |
| 10732 | |
| 10733 | @item |
| 10734 | Apply an offset of 10 seconds to the input PTS: |
| 10735 | @example |
| 10736 | setpts=PTS+10/TB |
| 10737 | @end example |
| 10738 | |
| 10739 | @item |
| 10740 | Generate timestamps from a "live source" and rebase onto the current timebase: |
| 10741 | @example |
| 10742 | setpts='(RTCTIME - RTCSTART) / (TB * 1000000)' |
| 10743 | @end example |
| 10744 | |
| 10745 | @item |
| 10746 | Generate timestamps by counting samples: |
| 10747 | @example |
| 10748 | asetpts=N/SR/TB |
| 10749 | @end example |
| 10750 | |
| 10751 | @end itemize |
| 10752 | |
| 10753 | @section settb, asettb |
| 10754 | |
| 10755 | Set the timebase to use for the output frames timestamps. |
| 10756 | It is mainly useful for testing timebase configuration. |
| 10757 | |
| 10758 | It accepts the following parameters: |
| 10759 | |
| 10760 | @table @option |
| 10761 | |
| 10762 | @item expr, tb |
| 10763 | The expression which is evaluated into the output timebase. |
| 10764 | |
| 10765 | @end table |
| 10766 | |
| 10767 | The value for @option{tb} is an arithmetic expression representing a |
| 10768 | rational. The expression can contain the constants "AVTB" (the default |
| 10769 | timebase), "intb" (the input timebase) and "sr" (the sample rate, |
| 10770 | audio only). Default value is "intb". |
| 10771 | |
| 10772 | @subsection Examples |
| 10773 | |
| 10774 | @itemize |
| 10775 | @item |
| 10776 | Set the timebase to 1/25: |
| 10777 | @example |
| 10778 | settb=expr=1/25 |
| 10779 | @end example |
| 10780 | |
| 10781 | @item |
| 10782 | Set the timebase to 1/10: |
| 10783 | @example |
| 10784 | settb=expr=0.1 |
| 10785 | @end example |
| 10786 | |
| 10787 | @item |
| 10788 | Set the timebase to 1001/1000: |
| 10789 | @example |
| 10790 | settb=1+0.001 |
| 10791 | @end example |
| 10792 | |
| 10793 | @item |
| 10794 | Set the timebase to 2*intb: |
| 10795 | @example |
| 10796 | settb=2*intb |
| 10797 | @end example |
| 10798 | |
| 10799 | @item |
| 10800 | Set the default timebase value: |
| 10801 | @example |
| 10802 | settb=AVTB |
| 10803 | @end example |
| 10804 | @end itemize |
| 10805 | |
| 10806 | @section showcqt |
| 10807 | Convert input audio to a video output representing |
| 10808 | frequency spectrum logarithmically (using constant Q transform with |
| 10809 | Brown-Puckette algorithm), with musical tone scale, from E0 to D#10 (10 octaves). |
| 10810 | |
| 10811 | The filter accepts the following options: |
| 10812 | |
| 10813 | @table @option |
| 10814 | @item volume |
| 10815 | Specify transform volume (multiplier) expression. The expression can contain |
| 10816 | variables: |
| 10817 | @table @option |
| 10818 | @item frequency, freq, f |
| 10819 | the frequency where transform is evaluated |
| 10820 | @item timeclamp, tc |
| 10821 | value of timeclamp option |
| 10822 | @end table |
| 10823 | and functions: |
| 10824 | @table @option |
| 10825 | @item a_weighting(f) |
| 10826 | A-weighting of equal loudness |
| 10827 | @item b_weighting(f) |
| 10828 | B-weighting of equal loudness |
| 10829 | @item c_weighting(f) |
| 10830 | C-weighting of equal loudness |
| 10831 | @end table |
| 10832 | Default value is @code{16}. |
| 10833 | |
| 10834 | @item tlength |
| 10835 | Specify transform length expression. The expression can contain variables: |
| 10836 | @table @option |
| 10837 | @item frequency, freq, f |
| 10838 | the frequency where transform is evaluated |
| 10839 | @item timeclamp, tc |
| 10840 | value of timeclamp option |
| 10841 | @end table |
| 10842 | Default value is @code{384/f*tc/(384/f+tc)}. |
| 10843 | |
| 10844 | @item timeclamp |
| 10845 | Specify the transform timeclamp. At low frequency, there is trade-off between |
| 10846 | accuracy in time domain and frequency domain. If timeclamp is lower, |
| 10847 | event in time domain is represented more accurately (such as fast bass drum), |
| 10848 | otherwise event in frequency domain is represented more accurately |
| 10849 | (such as bass guitar). Acceptable value is [0.1, 1.0]. Default value is @code{0.17}. |
| 10850 | |
| 10851 | @item coeffclamp |
| 10852 | Specify the transform coeffclamp. If coeffclamp is lower, transform is |
| 10853 | more accurate, otherwise transform is faster. Acceptable value is [0.1, 10.0]. |
| 10854 | Default value is @code{1.0}. |
| 10855 | |
| 10856 | @item gamma |
| 10857 | Specify gamma. Lower gamma makes the spectrum more contrast, higher gamma |
| 10858 | makes the spectrum having more range. Acceptable value is [1.0, 7.0]. |
| 10859 | Default value is @code{3.0}. |
| 10860 | |
| 10861 | @item fontfile |
| 10862 | Specify font file for use with freetype. If not specified, use embedded font. |
| 10863 | |
| 10864 | @item fontcolor |
| 10865 | Specify font color expression. This is arithmetic expression that should return |
| 10866 | integer value 0xRRGGBB. The expression can contain variables: |
| 10867 | @table @option |
| 10868 | @item frequency, freq, f |
| 10869 | the frequency where transform is evaluated |
| 10870 | @item timeclamp, tc |
| 10871 | value of timeclamp option |
| 10872 | @end table |
| 10873 | and functions: |
| 10874 | @table @option |
| 10875 | @item midi(f) |
| 10876 | midi number of frequency f, some midi numbers: E0(16), C1(24), C2(36), A4(69) |
| 10877 | @item r(x), g(x), b(x) |
| 10878 | red, green, and blue value of intensity x |
| 10879 | @end table |
| 10880 | Default value is @code{st(0, (midi(f)-59.5)/12); |
| 10881 | st(1, if(between(ld(0),0,1), 0.5-0.5*cos(2*PI*ld(0)), 0)); |
| 10882 | r(1-ld(1)) + b(ld(1))} |
| 10883 | |
| 10884 | @item fullhd |
| 10885 | If set to 1 (the default), the video size is 1920x1080 (full HD), |
| 10886 | if set to 0, the video size is 960x540. Use this option to make CPU usage lower. |
| 10887 | |
| 10888 | @item fps |
| 10889 | Specify video fps. Default value is @code{25}. |
| 10890 | |
| 10891 | @item count |
| 10892 | Specify number of transform per frame, so there are fps*count transforms |
| 10893 | per second. Note that audio data rate must be divisible by fps*count. |
| 10894 | Default value is @code{6}. |
| 10895 | |
| 10896 | @end table |
| 10897 | |
| 10898 | @subsection Examples |
| 10899 | |
| 10900 | @itemize |
| 10901 | @item |
| 10902 | Playing audio while showing the spectrum: |
| 10903 | @example |
| 10904 | ffplay -f lavfi 'amovie=a.mp3, asplit [a][out1]; [a] showcqt [out0]' |
| 10905 | @end example |
| 10906 | |
| 10907 | @item |
| 10908 | Same as above, but with frame rate 30 fps: |
| 10909 | @example |
| 10910 | ffplay -f lavfi 'amovie=a.mp3, asplit [a][out1]; [a] showcqt=fps=30:count=5 [out0]' |
| 10911 | @end example |
| 10912 | |
| 10913 | @item |
| 10914 | Playing at 960x540 and lower CPU usage: |
| 10915 | @example |
| 10916 | ffplay -f lavfi 'amovie=a.mp3, asplit [a][out1]; [a] showcqt=fullhd=0:count=3 [out0]' |
| 10917 | @end example |
| 10918 | |
| 10919 | @item |
| 10920 | A1 and its harmonics: A1, A2, (near)E3, A3: |
| 10921 | @example |
| 10922 | ffplay -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), |
| 10923 | asplit[a][out1]; [a] showcqt [out0]' |
| 10924 | @end example |
| 10925 | |
| 10926 | @item |
| 10927 | Same as above, but with more accuracy in frequency domain (and slower): |
| 10928 | @example |
| 10929 | ffplay -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), |
| 10930 | asplit[a][out1]; [a] showcqt=timeclamp=0.5 [out0]' |
| 10931 | @end example |
| 10932 | |
| 10933 | @item |
| 10934 | B-weighting of equal loudness |
| 10935 | @example |
| 10936 | volume=16*b_weighting(f) |
| 10937 | @end example |
| 10938 | |
| 10939 | @item |
| 10940 | Lower Q factor |
| 10941 | @example |
| 10942 | tlength=100/f*tc/(100/f+tc) |
| 10943 | @end example |
| 10944 | |
| 10945 | @item |
| 10946 | Custom fontcolor, C-note is colored green, others are colored blue |
| 10947 | @example |
| 10948 | fontcolor='if(mod(floor(midi(f)+0.5),12), 0x0000FF, g(1))' |
| 10949 | @end example |
| 10950 | |
| 10951 | @end itemize |
| 10952 | |
| 10953 | @section showspectrum |
| 10954 | |
| 10955 | Convert input audio to a video output, representing the audio frequency |
| 10956 | spectrum. |
| 10957 | |
| 10958 | The filter accepts the following options: |
| 10959 | |
| 10960 | @table @option |
| 10961 | @item size, s |
| 10962 | Specify the video size for the output. For the syntax of this option, check |
| 10963 | the "Video size" section in the ffmpeg-utils manual. Default value is |
| 10964 | @code{640x512}. |
| 10965 | |
| 10966 | @item slide |
| 10967 | Specify how the spectrum should slide along the window. |
| 10968 | |
| 10969 | It accepts the following values: |
| 10970 | @table @samp |
| 10971 | @item replace |
| 10972 | the samples start again on the left when they reach the right |
| 10973 | @item scroll |
| 10974 | the samples scroll from right to left |
| 10975 | @item fullframe |
| 10976 | frames are only produced when the samples reach the right |
| 10977 | @end table |
| 10978 | |
| 10979 | Default value is @code{replace}. |
| 10980 | |
| 10981 | @item mode |
| 10982 | Specify display mode. |
| 10983 | |
| 10984 | It accepts the following values: |
| 10985 | @table @samp |
| 10986 | @item combined |
| 10987 | all channels are displayed in the same row |
| 10988 | @item separate |
| 10989 | all channels are displayed in separate rows |
| 10990 | @end table |
| 10991 | |
| 10992 | Default value is @samp{combined}. |
| 10993 | |
| 10994 | @item color |
| 10995 | Specify display color mode. |
| 10996 | |
| 10997 | It accepts the following values: |
| 10998 | @table @samp |
| 10999 | @item channel |
| 11000 | each channel is displayed in a separate color |
| 11001 | @item intensity |
| 11002 | each channel is is displayed using the same color scheme |
| 11003 | @end table |
| 11004 | |
| 11005 | Default value is @samp{channel}. |
| 11006 | |
| 11007 | @item scale |
| 11008 | Specify scale used for calculating intensity color values. |
| 11009 | |
| 11010 | It accepts the following values: |
| 11011 | @table @samp |
| 11012 | @item lin |
| 11013 | linear |
| 11014 | @item sqrt |
| 11015 | square root, default |
| 11016 | @item cbrt |
| 11017 | cubic root |
| 11018 | @item log |
| 11019 | logarithmic |
| 11020 | @end table |
| 11021 | |
| 11022 | Default value is @samp{sqrt}. |
| 11023 | |
| 11024 | @item saturation |
| 11025 | Set saturation modifier for displayed colors. Negative values provide |
| 11026 | alternative color scheme. @code{0} is no saturation at all. |
| 11027 | Saturation must be in [-10.0, 10.0] range. |
| 11028 | Default value is @code{1}. |
| 11029 | |
| 11030 | @item win_func |
| 11031 | Set window function. |
| 11032 | |
| 11033 | It accepts the following values: |
| 11034 | @table @samp |
| 11035 | @item none |
| 11036 | No samples pre-processing (do not expect this to be faster) |
| 11037 | @item hann |
| 11038 | Hann window |
| 11039 | @item hamming |
| 11040 | Hamming window |
| 11041 | @item blackman |
| 11042 | Blackman window |
| 11043 | @end table |
| 11044 | |
| 11045 | Default value is @code{hann}. |
| 11046 | @end table |
| 11047 | |
| 11048 | The usage is very similar to the showwaves filter; see the examples in that |
| 11049 | section. |
| 11050 | |
| 11051 | @subsection Examples |
| 11052 | |
| 11053 | @itemize |
| 11054 | @item |
| 11055 | Large window with logarithmic color scaling: |
| 11056 | @example |
| 11057 | showspectrum=s=1280x480:scale=log |
| 11058 | @end example |
| 11059 | |
| 11060 | @item |
| 11061 | Complete example for a colored and sliding spectrum per channel using @command{ffplay}: |
| 11062 | @example |
| 11063 | ffplay -f lavfi 'amovie=input.mp3, asplit [a][out1]; |
| 11064 | [a] showspectrum=mode=separate:color=intensity:slide=1:scale=cbrt [out0]' |
| 11065 | @end example |
| 11066 | @end itemize |
| 11067 | |
| 11068 | @section showwaves |
| 11069 | |
| 11070 | Convert input audio to a video output, representing the samples waves. |
| 11071 | |
| 11072 | The filter accepts the following options: |
| 11073 | |
| 11074 | @table @option |
| 11075 | @item size, s |
| 11076 | Specify the video size for the output. For the syntax of this option, check |
| 11077 | the "Video size" section in the ffmpeg-utils manual. Default value |
| 11078 | is "600x240". |
| 11079 | |
| 11080 | @item mode |
| 11081 | Set display mode. |
| 11082 | |
| 11083 | Available values are: |
| 11084 | @table @samp |
| 11085 | @item point |
| 11086 | Draw a point for each sample. |
| 11087 | |
| 11088 | @item line |
| 11089 | Draw a vertical line for each sample. |
| 11090 | |
| 11091 | @item p2p |
| 11092 | Draw a point for each sample and a line between them. |
| 11093 | |
| 11094 | @item cline |
| 11095 | Draw a centered vertical line for each sample. |
| 11096 | @end table |
| 11097 | |
| 11098 | Default value is @code{point}. |
| 11099 | |
| 11100 | @item n |
| 11101 | Set the number of samples which are printed on the same column. A |
| 11102 | larger value will decrease the frame rate. Must be a positive |
| 11103 | integer. This option can be set only if the value for @var{rate} |
| 11104 | is not explicitly specified. |
| 11105 | |
| 11106 | @item rate, r |
| 11107 | Set the (approximate) output frame rate. This is done by setting the |
| 11108 | option @var{n}. Default value is "25". |
| 11109 | |
| 11110 | @item split_channels |
| 11111 | Set if channels should be drawn separately or overlap. Default value is 0. |
| 11112 | |
| 11113 | @end table |
| 11114 | |
| 11115 | @subsection Examples |
| 11116 | |
| 11117 | @itemize |
| 11118 | @item |
| 11119 | Output the input file audio and the corresponding video representation |
| 11120 | at the same time: |
| 11121 | @example |
| 11122 | amovie=a.mp3,asplit[out0],showwaves[out1] |
| 11123 | @end example |
| 11124 | |
| 11125 | @item |
| 11126 | Create a synthetic signal and show it with showwaves, forcing a |
| 11127 | frame rate of 30 frames per second: |
| 11128 | @example |
| 11129 | aevalsrc=sin(1*2*PI*t)*sin(880*2*PI*t):cos(2*PI*200*t),asplit[out0],showwaves=r=30[out1] |
| 11130 | @end example |
| 11131 | @end itemize |
| 11132 | |
| 11133 | @section split, asplit |
| 11134 | |
| 11135 | Split input into several identical outputs. |
| 11136 | |
| 11137 | @code{asplit} works with audio input, @code{split} with video. |
| 11138 | |
| 11139 | The filter accepts a single parameter which specifies the number of outputs. If |
| 11140 | unspecified, it defaults to 2. |
| 11141 | |
| 11142 | @subsection Examples |
| 11143 | |
| 11144 | @itemize |
| 11145 | @item |
| 11146 | Create two separate outputs from the same input: |
| 11147 | @example |
| 11148 | [in] split [out0][out1] |
| 11149 | @end example |
| 11150 | |
| 11151 | @item |
| 11152 | To create 3 or more outputs, you need to specify the number of |
| 11153 | outputs, like in: |
| 11154 | @example |
| 11155 | [in] asplit=3 [out0][out1][out2] |
| 11156 | @end example |
| 11157 | |
| 11158 | @item |
| 11159 | Create two separate outputs from the same input, one cropped and |
| 11160 | one padded: |
| 11161 | @example |
| 11162 | [in] split [splitout1][splitout2]; |
| 11163 | [splitout1] crop=100:100:0:0 [cropout]; |
| 11164 | [splitout2] pad=200:200:100:100 [padout]; |
| 11165 | @end example |
| 11166 | |
| 11167 | @item |
| 11168 | Create 5 copies of the input audio with @command{ffmpeg}: |
| 11169 | @example |
| 11170 | ffmpeg -i INPUT -filter_complex asplit=5 OUTPUT |
| 11171 | @end example |
| 11172 | @end itemize |
| 11173 | |
| 11174 | @section zmq, azmq |
| 11175 | |
| 11176 | Receive commands sent through a libzmq client, and forward them to |
| 11177 | filters in the filtergraph. |
| 11178 | |
| 11179 | @code{zmq} and @code{azmq} work as a pass-through filters. @code{zmq} |
| 11180 | must be inserted between two video filters, @code{azmq} between two |
| 11181 | audio filters. |
| 11182 | |
| 11183 | To enable these filters you need to install the libzmq library and |
| 11184 | headers and configure FFmpeg with @code{--enable-libzmq}. |
| 11185 | |
| 11186 | For more information about libzmq see: |
| 11187 | @url{http://www.zeromq.org/} |
| 11188 | |
| 11189 | The @code{zmq} and @code{azmq} filters work as a libzmq server, which |
| 11190 | receives messages sent through a network interface defined by the |
| 11191 | @option{bind_address} option. |
| 11192 | |
| 11193 | The received message must be in the form: |
| 11194 | @example |
| 11195 | @var{TARGET} @var{COMMAND} [@var{ARG}] |
| 11196 | @end example |
| 11197 | |
| 11198 | @var{TARGET} specifies the target of the command, usually the name of |
| 11199 | the filter class or a specific filter instance name. |
| 11200 | |
| 11201 | @var{COMMAND} specifies the name of the command for the target filter. |
| 11202 | |
| 11203 | @var{ARG} is optional and specifies the optional argument list for the |
| 11204 | given @var{COMMAND}. |
| 11205 | |
| 11206 | Upon reception, the message is processed and the corresponding command |
| 11207 | is injected into the filtergraph. Depending on the result, the filter |
| 11208 | will send a reply to the client, adopting the format: |
| 11209 | @example |
| 11210 | @var{ERROR_CODE} @var{ERROR_REASON} |
| 11211 | @var{MESSAGE} |
| 11212 | @end example |
| 11213 | |
| 11214 | @var{MESSAGE} is optional. |
| 11215 | |
| 11216 | @subsection Examples |
| 11217 | |
| 11218 | Look at @file{tools/zmqsend} for an example of a zmq client which can |
| 11219 | be used to send commands processed by these filters. |
| 11220 | |
| 11221 | Consider the following filtergraph generated by @command{ffplay} |
| 11222 | @example |
| 11223 | ffplay -dumpgraph 1 -f lavfi " |
| 11224 | color=s=100x100:c=red [l]; |
| 11225 | color=s=100x100:c=blue [r]; |
| 11226 | nullsrc=s=200x100, zmq [bg]; |
| 11227 | [bg][l] overlay [bg+l]; |
| 11228 | [bg+l][r] overlay=x=100 " |
| 11229 | @end example |
| 11230 | |
| 11231 | To change the color of the left side of the video, the following |
| 11232 | command can be used: |
| 11233 | @example |
| 11234 | echo Parsed_color_0 c yellow | tools/zmqsend |
| 11235 | @end example |
| 11236 | |
| 11237 | To change the right side: |
| 11238 | @example |
| 11239 | echo Parsed_color_1 c pink | tools/zmqsend |
| 11240 | @end example |
| 11241 | |
| 11242 | @c man end MULTIMEDIA FILTERS |
| 11243 | |
| 11244 | @chapter Multimedia Sources |
| 11245 | @c man begin MULTIMEDIA SOURCES |
| 11246 | |
| 11247 | Below is a description of the currently available multimedia sources. |
| 11248 | |
| 11249 | @section amovie |
| 11250 | |
| 11251 | This is the same as @ref{movie} source, except it selects an audio |
| 11252 | stream by default. |
| 11253 | |
| 11254 | @anchor{movie} |
| 11255 | @section movie |
| 11256 | |
| 11257 | Read audio and/or video stream(s) from a movie container. |
| 11258 | |
| 11259 | It accepts the following parameters: |
| 11260 | |
| 11261 | @table @option |
| 11262 | @item filename |
| 11263 | The name of the resource to read (not necessarily a file; it can also be a |
| 11264 | device or a stream accessed through some protocol). |
| 11265 | |
| 11266 | @item format_name, f |
| 11267 | Specifies the format assumed for the movie to read, and can be either |
| 11268 | the name of a container or an input device. If not specified, the |
| 11269 | format is guessed from @var{movie_name} or by probing. |
| 11270 | |
| 11271 | @item seek_point, sp |
| 11272 | Specifies the seek point in seconds. The frames will be output |
| 11273 | starting from this seek point. The parameter is evaluated with |
| 11274 | @code{av_strtod}, so the numerical value may be suffixed by an IS |
| 11275 | postfix. The default value is "0". |
| 11276 | |
| 11277 | @item streams, s |
| 11278 | Specifies the streams to read. Several streams can be specified, |
| 11279 | separated by "+". The source will then have as many outputs, in the |
| 11280 | same order. The syntax is explained in the ``Stream specifiers'' |
| 11281 | section in the ffmpeg manual. Two special names, "dv" and "da" specify |
| 11282 | respectively the default (best suited) video and audio stream. Default |
| 11283 | is "dv", or "da" if the filter is called as "amovie". |
| 11284 | |
| 11285 | @item stream_index, si |
| 11286 | Specifies the index of the video stream to read. If the value is -1, |
| 11287 | the most suitable video stream will be automatically selected. The default |
| 11288 | value is "-1". Deprecated. If the filter is called "amovie", it will select |
| 11289 | audio instead of video. |
| 11290 | |
| 11291 | @item loop |
| 11292 | Specifies how many times to read the stream in sequence. |
| 11293 | If the value is less than 1, the stream will be read again and again. |
| 11294 | Default value is "1". |
| 11295 | |
| 11296 | Note that when the movie is looped the source timestamps are not |
| 11297 | changed, so it will generate non monotonically increasing timestamps. |
| 11298 | @end table |
| 11299 | |
| 11300 | It allows overlaying a second video on top of the main input of |
| 11301 | a filtergraph, as shown in this graph: |
| 11302 | @example |
| 11303 | input -----------> deltapts0 --> overlay --> output |
| 11304 | ^ |
| 11305 | | |
| 11306 | movie --> scale--> deltapts1 -------+ |
| 11307 | @end example |
| 11308 | @subsection Examples |
| 11309 | |
| 11310 | @itemize |
| 11311 | @item |
| 11312 | Skip 3.2 seconds from the start of the AVI file in.avi, and overlay it |
| 11313 | on top of the input labelled "in": |
| 11314 | @example |
| 11315 | movie=in.avi:seek_point=3.2, scale=180:-1, setpts=PTS-STARTPTS [over]; |
| 11316 | [in] setpts=PTS-STARTPTS [main]; |
| 11317 | [main][over] overlay=16:16 [out] |
| 11318 | @end example |
| 11319 | |
| 11320 | @item |
| 11321 | Read from a video4linux2 device, and overlay it on top of the input |
| 11322 | labelled "in": |
| 11323 | @example |
| 11324 | movie=/dev/video0:f=video4linux2, scale=180:-1, setpts=PTS-STARTPTS [over]; |
| 11325 | [in] setpts=PTS-STARTPTS [main]; |
| 11326 | [main][over] overlay=16:16 [out] |
| 11327 | @end example |
| 11328 | |
| 11329 | @item |
| 11330 | Read the first video stream and the audio stream with id 0x81 from |
| 11331 | dvd.vob; the video is connected to the pad named "video" and the audio is |
| 11332 | connected to the pad named "audio": |
| 11333 | @example |
| 11334 | movie=dvd.vob:s=v:0+#0x81 [video] [audio] |
| 11335 | @end example |
| 11336 | @end itemize |
| 11337 | |
| 11338 | @c man end MULTIMEDIA SOURCES |