Commit | Line | Data |
---|---|---|
2ba45a60 DM |
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 | |
f6fa7814 DM |
285 | |
286 | @item w | |
287 | @item h | |
288 | width and height of the input frame if video | |
2ba45a60 DM |
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 | ||
2ba45a60 DM |
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 | ||
f6fa7814 | 1713 | This filter is also designed to efficiently remap the channels of an audio |
2ba45a60 DM |
1714 | stream. |
1715 | ||
1716 | The filter accepts parameters of the form: | |
f6fa7814 | 1717 | "@var{l}|@var{outdef}|@var{outdef}|..." |
2ba45a60 DM |
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 | |
f6fa7814 | 1748 | pan=1c|c0=0.9*c0+0.1*c1 |
2ba45a60 DM |
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 | |
f6fa7814 | 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 |
2ba45a60 DM |
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 | |
f6fa7814 | 1777 | pan="stereo| c0=FL | c1=FR" |
2ba45a60 DM |
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 | |
f6fa7814 | 1783 | pan="5.1| c0=c1 | c1=c0 | c2=c2 | c3=c3 | c4=c4 | c5=c5" |
2ba45a60 DM |
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 | |
f6fa7814 | 1789 | pan="stereo|c1=c1" |
2ba45a60 DM |
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 | |
f6fa7814 | 1795 | pan="stereo| c0=FR | c1=FR" |
2ba45a60 DM |
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 | ||
f6fa7814 DM |
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 | ||
2ba45a60 DM |
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 | |
f6fa7814 | 4177 | drawtext='fontfile=FreeSans.ttf:text=%@{localtime\:%a %b %d %Y@}' |
2ba45a60 DM |
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 | ||
f6fa7814 DM |
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 | ||
2ba45a60 DM |
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 | |
f6fa7814 DM |
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 | |
2ba45a60 DM |
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 | ||
f6fa7814 DM |
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 | |
2ba45a60 DM |
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. | |
f6fa7814 DM |
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. | |
2ba45a60 DM |
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: | |
f6fa7814 | 6294 | @url{http://docs.opencv.org/master/modules/imgproc/doc/filtering.html} |
2ba45a60 DM |
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. | |
f6fa7814 DM |
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. | |
2ba45a60 DM |
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}. | |
f6fa7814 DM |
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 | |
2ba45a60 DM |
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 | ||
f6fa7814 | 8740 | @anchor{unsharp} |
2ba45a60 DM |
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 | |
f6fa7814 | 8902 | the @ref{unsharp} filter, see below. |
2ba45a60 DM |
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 | |
f6fa7814 | 8912 | @file{transforms.trf}. |
2ba45a60 DM |
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 | |
f6fa7814 DM |
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. | |
2ba45a60 DM |
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 | |
f6fa7814 | 8959 | Consider transforms as relative to previous frame if set to 1, |
2ba45a60 DM |
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 | ||
f6fa7814 | 9025 | Note the use of the @ref{unsharp} filter which is always recommended. |
2ba45a60 DM |
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 | ||
f6fa7814 DM |
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 | ||
2ba45a60 DM |
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 |