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 | |
285 | @end table | |
286 | ||
287 | Additionally, these filters support an @option{enable} command that can be used | |
288 | to re-define the expression. | |
289 | ||
290 | Like any other filtering option, the @option{enable} option follows the same | |
291 | rules. | |
292 | ||
293 | For example, to enable a blur filter (@ref{smartblur}) from 10 seconds to 3 | |
294 | minutes, and a @ref{curves} filter starting at 3 seconds: | |
295 | @example | |
296 | smartblur = enable='between(t,10,3*60)', | |
297 | curves = enable='gte(t,3)' : preset=cross_process | |
298 | @end example | |
299 | ||
300 | @c man end FILTERGRAPH DESCRIPTION | |
301 | ||
302 | @chapter Audio Filters | |
303 | @c man begin AUDIO FILTERS | |
304 | ||
305 | When you configure your FFmpeg build, you can disable any of the | |
306 | existing filters using @code{--disable-filters}. | |
307 | The configure output will show the audio filters included in your | |
308 | build. | |
309 | ||
310 | Below is a description of the currently available audio filters. | |
311 | ||
312 | @section aconvert | |
313 | ||
314 | Convert the input audio format to the specified formats. | |
315 | ||
316 | @emph{This filter is deprecated. Use @ref{aformat} instead.} | |
317 | ||
318 | The filter accepts a string of the form: | |
319 | "@var{sample_format}:@var{channel_layout}". | |
320 | ||
321 | @var{sample_format} specifies the sample format, and can be a string or the | |
322 | corresponding numeric value defined in @file{libavutil/samplefmt.h}. Use 'p' | |
323 | suffix for a planar sample format. | |
324 | ||
325 | @var{channel_layout} specifies the channel layout, and can be a string | |
326 | or the corresponding number value defined in @file{libavutil/channel_layout.h}. | |
327 | ||
328 | The special parameter "auto", signifies that the filter will | |
329 | automatically select the output format depending on the output filter. | |
330 | ||
331 | @subsection Examples | |
332 | ||
333 | @itemize | |
334 | @item | |
335 | Convert input to float, planar, stereo: | |
336 | @example | |
337 | aconvert=fltp:stereo | |
338 | @end example | |
339 | ||
340 | @item | |
341 | Convert input to unsigned 8-bit, automatically select out channel layout: | |
342 | @example | |
343 | aconvert=u8:auto | |
344 | @end example | |
345 | @end itemize | |
346 | ||
347 | @section adelay | |
348 | ||
349 | Delay one or more audio channels. | |
350 | ||
351 | Samples in delayed channel are filled with silence. | |
352 | ||
353 | The filter accepts the following option: | |
354 | ||
355 | @table @option | |
356 | @item delays | |
357 | Set list of delays in milliseconds for each channel separated by '|'. | |
358 | At least one delay greater than 0 should be provided. | |
359 | Unused delays will be silently ignored. If number of given delays is | |
360 | smaller than number of channels all remaining channels will not be delayed. | |
361 | @end table | |
362 | ||
363 | @subsection Examples | |
364 | ||
365 | @itemize | |
366 | @item | |
367 | Delay first channel by 1.5 seconds, the third channel by 0.5 seconds and leave | |
368 | the second channel (and any other channels that may be present) unchanged. | |
369 | @example | |
370 | adelay=1500|0|500 | |
371 | @end example | |
372 | @end itemize | |
373 | ||
374 | @section aecho | |
375 | ||
376 | Apply echoing to the input audio. | |
377 | ||
378 | Echoes are reflected sound and can occur naturally amongst mountains | |
379 | (and sometimes large buildings) when talking or shouting; digital echo | |
380 | effects emulate this behaviour and are often used to help fill out the | |
381 | sound of a single instrument or vocal. The time difference between the | |
382 | original signal and the reflection is the @code{delay}, and the | |
383 | loudness of the reflected signal is the @code{decay}. | |
384 | Multiple echoes can have different delays and decays. | |
385 | ||
386 | A description of the accepted parameters follows. | |
387 | ||
388 | @table @option | |
389 | @item in_gain | |
390 | Set input gain of reflected signal. Default is @code{0.6}. | |
391 | ||
392 | @item out_gain | |
393 | Set output gain of reflected signal. Default is @code{0.3}. | |
394 | ||
395 | @item delays | |
396 | Set list of time intervals in milliseconds between original signal and reflections | |
397 | separated by '|'. Allowed range for each @code{delay} is @code{(0 - 90000.0]}. | |
398 | Default is @code{1000}. | |
399 | ||
400 | @item decays | |
401 | Set list of loudnesses of reflected signals separated by '|'. | |
402 | Allowed range for each @code{decay} is @code{(0 - 1.0]}. | |
403 | Default is @code{0.5}. | |
404 | @end table | |
405 | ||
406 | @subsection Examples | |
407 | ||
408 | @itemize | |
409 | @item | |
410 | Make it sound as if there are twice as many instruments as are actually playing: | |
411 | @example | |
412 | aecho=0.8:0.88:60:0.4 | |
413 | @end example | |
414 | ||
415 | @item | |
416 | If delay is very short, then it sound like a (metallic) robot playing music: | |
417 | @example | |
418 | aecho=0.8:0.88:6:0.4 | |
419 | @end example | |
420 | ||
421 | @item | |
422 | A longer delay will sound like an open air concert in the mountains: | |
423 | @example | |
424 | aecho=0.8:0.9:1000:0.3 | |
425 | @end example | |
426 | ||
427 | @item | |
428 | Same as above but with one more mountain: | |
429 | @example | |
430 | aecho=0.8:0.9:1000|1800:0.3|0.25 | |
431 | @end example | |
432 | @end itemize | |
433 | ||
434 | @section aeval | |
435 | ||
436 | Modify an audio signal according to the specified expressions. | |
437 | ||
438 | This filter accepts one or more expressions (one for each channel), | |
439 | which are evaluated and used to modify a corresponding audio signal. | |
440 | ||
441 | It accepts the following parameters: | |
442 | ||
443 | @table @option | |
444 | @item exprs | |
445 | Set the '|'-separated expressions list for each separate channel. If | |
446 | the number of input channels is greater than the number of | |
447 | expressions, the last specified expression is used for the remaining | |
448 | output channels. | |
449 | ||
450 | @item channel_layout, c | |
451 | Set output channel layout. If not specified, the channel layout is | |
452 | specified by the number of expressions. If set to @samp{same}, it will | |
453 | use by default the same input channel layout. | |
454 | @end table | |
455 | ||
456 | Each expression in @var{exprs} can contain the following constants and functions: | |
457 | ||
458 | @table @option | |
459 | @item ch | |
460 | channel number of the current expression | |
461 | ||
462 | @item n | |
463 | number of the evaluated sample, starting from 0 | |
464 | ||
465 | @item s | |
466 | sample rate | |
467 | ||
468 | @item t | |
469 | time of the evaluated sample expressed in seconds | |
470 | ||
471 | @item nb_in_channels | |
472 | @item nb_out_channels | |
473 | input and output number of channels | |
474 | ||
475 | @item val(CH) | |
476 | the value of input channel with number @var{CH} | |
477 | @end table | |
478 | ||
479 | Note: this filter is slow. For faster processing you should use a | |
480 | dedicated filter. | |
481 | ||
482 | @subsection Examples | |
483 | ||
484 | @itemize | |
485 | @item | |
486 | Half volume: | |
487 | @example | |
488 | aeval=val(ch)/2:c=same | |
489 | @end example | |
490 | ||
491 | @item | |
492 | Invert phase of the second channel: | |
493 | @example | |
494 | aeval=val(0)|-val(1) | |
495 | @end example | |
496 | @end itemize | |
497 | ||
498 | @section afade | |
499 | ||
500 | Apply fade-in/out effect to input audio. | |
501 | ||
502 | A description of the accepted parameters follows. | |
503 | ||
504 | @table @option | |
505 | @item type, t | |
506 | Specify the effect type, can be either @code{in} for fade-in, or | |
507 | @code{out} for a fade-out effect. Default is @code{in}. | |
508 | ||
509 | @item start_sample, ss | |
510 | Specify the number of the start sample for starting to apply the fade | |
511 | effect. Default is 0. | |
512 | ||
513 | @item nb_samples, ns | |
514 | Specify the number of samples for which the fade effect has to last. At | |
515 | the end of the fade-in effect the output audio will have the same | |
516 | volume as the input audio, at the end of the fade-out transition | |
517 | the output audio will be silence. Default is 44100. | |
518 | ||
519 | @item start_time, st | |
520 | Specify the start time of the fade effect. Default is 0. | |
521 | The value must be specified as a time duration; see | |
522 | @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils} | |
523 | for the accepted syntax. | |
524 | If set this option is used instead of @var{start_sample}. | |
525 | ||
526 | @item duration, d | |
527 | Specify the duration of the fade effect. See | |
528 | @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils} | |
529 | for the accepted syntax. | |
530 | At the end of the fade-in effect the output audio will have the same | |
531 | volume as the input audio, at the end of the fade-out transition | |
532 | the output audio will be silence. | |
533 | By default the duration is determined by @var{nb_samples}. | |
534 | If set this option is used instead of @var{nb_samples}. | |
535 | ||
536 | @item curve | |
537 | Set curve for fade transition. | |
538 | ||
539 | It accepts the following values: | |
540 | @table @option | |
541 | @item tri | |
542 | select triangular, linear slope (default) | |
543 | @item qsin | |
544 | select quarter of sine wave | |
545 | @item hsin | |
546 | select half of sine wave | |
547 | @item esin | |
548 | select exponential sine wave | |
549 | @item log | |
550 | select logarithmic | |
551 | @item par | |
552 | select inverted parabola | |
553 | @item qua | |
554 | select quadratic | |
555 | @item cub | |
556 | select cubic | |
557 | @item squ | |
558 | select square root | |
559 | @item cbr | |
560 | select cubic root | |
561 | @end table | |
562 | @end table | |
563 | ||
564 | @subsection Examples | |
565 | ||
566 | @itemize | |
567 | @item | |
568 | Fade in first 15 seconds of audio: | |
569 | @example | |
570 | afade=t=in:ss=0:d=15 | |
571 | @end example | |
572 | ||
573 | @item | |
574 | Fade out last 25 seconds of a 900 seconds audio: | |
575 | @example | |
576 | afade=t=out:st=875:d=25 | |
577 | @end example | |
578 | @end itemize | |
579 | ||
580 | @anchor{aformat} | |
581 | @section aformat | |
582 | ||
583 | Set output format constraints for the input audio. The framework will | |
584 | negotiate the most appropriate format to minimize conversions. | |
585 | ||
586 | It accepts the following parameters: | |
587 | @table @option | |
588 | ||
589 | @item sample_fmts | |
590 | A '|'-separated list of requested sample formats. | |
591 | ||
592 | @item sample_rates | |
593 | A '|'-separated list of requested sample rates. | |
594 | ||
595 | @item channel_layouts | |
596 | A '|'-separated list of requested channel layouts. | |
597 | ||
598 | See @ref{channel layout syntax,,the Channel Layout section in the ffmpeg-utils(1) manual,ffmpeg-utils} | |
599 | for the required syntax. | |
600 | @end table | |
601 | ||
602 | If a parameter is omitted, all values are allowed. | |
603 | ||
604 | Force the output to either unsigned 8-bit or signed 16-bit stereo | |
605 | @example | |
606 | aformat=sample_fmts=u8|s16:channel_layouts=stereo | |
607 | @end example | |
608 | ||
609 | @section allpass | |
610 | ||
611 | Apply a two-pole all-pass filter with central frequency (in Hz) | |
612 | @var{frequency}, and filter-width @var{width}. | |
613 | An all-pass filter changes the audio's frequency to phase relationship | |
614 | without changing its frequency to amplitude relationship. | |
615 | ||
616 | The filter accepts the following options: | |
617 | ||
618 | @table @option | |
619 | @item frequency, f | |
620 | Set frequency in Hz. | |
621 | ||
622 | @item width_type | |
623 | Set method to specify band-width of filter. | |
624 | @table @option | |
625 | @item h | |
626 | Hz | |
627 | @item q | |
628 | Q-Factor | |
629 | @item o | |
630 | octave | |
631 | @item s | |
632 | slope | |
633 | @end table | |
634 | ||
635 | @item width, w | |
636 | Specify the band-width of a filter in width_type units. | |
637 | @end table | |
638 | ||
639 | @section amerge | |
640 | ||
641 | Merge two or more audio streams into a single multi-channel stream. | |
642 | ||
643 | The filter accepts the following options: | |
644 | ||
645 | @table @option | |
646 | ||
647 | @item inputs | |
648 | Set the number of inputs. Default is 2. | |
649 | ||
650 | @end table | |
651 | ||
652 | If the channel layouts of the inputs are disjoint, and therefore compatible, | |
653 | the channel layout of the output will be set accordingly and the channels | |
654 | will be reordered as necessary. If the channel layouts of the inputs are not | |
655 | disjoint, the output will have all the channels of the first input then all | |
656 | the channels of the second input, in that order, and the channel layout of | |
657 | the output will be the default value corresponding to the total number of | |
658 | channels. | |
659 | ||
660 | For example, if the first input is in 2.1 (FL+FR+LF) and the second input | |
661 | is FC+BL+BR, then the output will be in 5.1, with the channels in the | |
662 | following order: a1, a2, b1, a3, b2, b3 (a1 is the first channel of the | |
663 | first input, b1 is the first channel of the second input). | |
664 | ||
665 | On the other hand, if both input are in stereo, the output channels will be | |
666 | in the default order: a1, a2, b1, b2, and the channel layout will be | |
667 | arbitrarily set to 4.0, which may or may not be the expected value. | |
668 | ||
669 | All inputs must have the same sample rate, and format. | |
670 | ||
671 | If inputs do not have the same duration, the output will stop with the | |
672 | shortest. | |
673 | ||
674 | @subsection Examples | |
675 | ||
676 | @itemize | |
677 | @item | |
678 | Merge two mono files into a stereo stream: | |
679 | @example | |
680 | amovie=left.wav [l] ; amovie=right.mp3 [r] ; [l] [r] amerge | |
681 | @end example | |
682 | ||
683 | @item | |
684 | Multiple merges assuming 1 video stream and 6 audio streams in @file{input.mkv}: | |
685 | @example | |
686 | 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 | |
687 | @end example | |
688 | @end itemize | |
689 | ||
690 | @section amix | |
691 | ||
692 | Mixes multiple audio inputs into a single output. | |
693 | ||
694 | Note that this filter only supports float samples (the @var{amerge} | |
695 | and @var{pan} audio filters support many formats). If the @var{amix} | |
696 | input has integer samples then @ref{aresample} will be automatically | |
697 | inserted to perform the conversion to float samples. | |
698 | ||
699 | For example | |
700 | @example | |
701 | ffmpeg -i INPUT1 -i INPUT2 -i INPUT3 -filter_complex amix=inputs=3:duration=first:dropout_transition=3 OUTPUT | |
702 | @end example | |
703 | will mix 3 input audio streams to a single output with the same duration as the | |
704 | first input and a dropout transition time of 3 seconds. | |
705 | ||
706 | It accepts the following parameters: | |
707 | @table @option | |
708 | ||
709 | @item inputs | |
710 | The number of inputs. If unspecified, it defaults to 2. | |
711 | ||
712 | @item duration | |
713 | How to determine the end-of-stream. | |
714 | @table @option | |
715 | ||
716 | @item longest | |
717 | The duration of the longest input. (default) | |
718 | ||
719 | @item shortest | |
720 | The duration of the shortest input. | |
721 | ||
722 | @item first | |
723 | The duration of the first input. | |
724 | ||
725 | @end table | |
726 | ||
727 | @item dropout_transition | |
728 | The transition time, in seconds, for volume renormalization when an input | |
729 | stream ends. The default value is 2 seconds. | |
730 | ||
731 | @end table | |
732 | ||
733 | @section anull | |
734 | ||
735 | Pass the audio source unchanged to the output. | |
736 | ||
737 | @section apad | |
738 | ||
739 | Pad the end of an audio stream with silence. | |
740 | ||
741 | This can be used together with @command{ffmpeg} @option{-shortest} to | |
742 | extend audio streams to the same length as the video stream. | |
743 | ||
744 | A description of the accepted options follows. | |
745 | ||
746 | @table @option | |
747 | @item packet_size | |
748 | Set silence packet size. Default value is 4096. | |
749 | ||
750 | @item pad_len | |
751 | Set the number of samples of silence to add to the end. After the | |
752 | value is reached, the stream is terminated. This option is mutually | |
753 | exclusive with @option{whole_len}. | |
754 | ||
755 | @item whole_len | |
756 | Set the minimum total number of samples in the output audio stream. If | |
757 | the value is longer than the input audio length, silence is added to | |
758 | the end, until the value is reached. This option is mutually exclusive | |
759 | with @option{pad_len}. | |
760 | @end table | |
761 | ||
762 | If neither the @option{pad_len} nor the @option{whole_len} option is | |
763 | set, the filter will add silence to the end of the input stream | |
764 | indefinitely. | |
765 | ||
766 | @subsection Examples | |
767 | ||
768 | @itemize | |
769 | @item | |
770 | Add 1024 samples of silence to the end of the input: | |
771 | @example | |
772 | apad=pad_len=1024 | |
773 | @end example | |
774 | ||
775 | @item | |
776 | Make sure the audio output will contain at least 10000 samples, pad | |
777 | the input with silence if required: | |
778 | @example | |
779 | apad=whole_len=10000 | |
780 | @end example | |
781 | ||
782 | @item | |
783 | Use @command{ffmpeg} to pad the audio input with silence, so that the | |
784 | video stream will always result the shortest and will be converted | |
785 | until the end in the output file when using the @option{shortest} | |
786 | option: | |
787 | @example | |
788 | ffmpeg -i VIDEO -i AUDIO -filter_complex "[1:0]apad" -shortest OUTPUT | |
789 | @end example | |
790 | @end itemize | |
791 | ||
792 | @section aphaser | |
793 | Add a phasing effect to the input audio. | |
794 | ||
795 | A phaser filter creates series of peaks and troughs in the frequency spectrum. | |
796 | The position of the peaks and troughs are modulated so that they vary over time, creating a sweeping effect. | |
797 | ||
798 | A description of the accepted parameters follows. | |
799 | ||
800 | @table @option | |
801 | @item in_gain | |
802 | Set input gain. Default is 0.4. | |
803 | ||
804 | @item out_gain | |
805 | Set output gain. Default is 0.74 | |
806 | ||
807 | @item delay | |
808 | Set delay in milliseconds. Default is 3.0. | |
809 | ||
810 | @item decay | |
811 | Set decay. Default is 0.4. | |
812 | ||
813 | @item speed | |
814 | Set modulation speed in Hz. Default is 0.5. | |
815 | ||
816 | @item type | |
817 | Set modulation type. Default is triangular. | |
818 | ||
819 | It accepts the following values: | |
820 | @table @samp | |
821 | @item triangular, t | |
822 | @item sinusoidal, s | |
823 | @end table | |
824 | @end table | |
825 | ||
826 | @anchor{aresample} | |
827 | @section aresample | |
828 | ||
829 | Resample the input audio to the specified parameters, using the | |
830 | libswresample library. If none are specified then the filter will | |
831 | automatically convert between its input and output. | |
832 | ||
833 | This filter is also able to stretch/squeeze the audio data to make it match | |
834 | the timestamps or to inject silence / cut out audio to make it match the | |
835 | timestamps, do a combination of both or do neither. | |
836 | ||
837 | The filter accepts the syntax | |
838 | [@var{sample_rate}:]@var{resampler_options}, where @var{sample_rate} | |
839 | expresses a sample rate and @var{resampler_options} is a list of | |
840 | @var{key}=@var{value} pairs, separated by ":". See the | |
841 | ffmpeg-resampler manual for the complete list of supported options. | |
842 | ||
843 | @subsection Examples | |
844 | ||
845 | @itemize | |
846 | @item | |
847 | Resample the input audio to 44100Hz: | |
848 | @example | |
849 | aresample=44100 | |
850 | @end example | |
851 | ||
852 | @item | |
853 | Stretch/squeeze samples to the given timestamps, with a maximum of 1000 | |
854 | samples per second compensation: | |
855 | @example | |
856 | aresample=async=1000 | |
857 | @end example | |
858 | @end itemize | |
859 | ||
860 | @section asetnsamples | |
861 | ||
862 | Set the number of samples per each output audio frame. | |
863 | ||
864 | The last output packet may contain a different number of samples, as | |
865 | the filter will flush all the remaining samples when the input audio | |
866 | signal its end. | |
867 | ||
868 | The filter accepts the following options: | |
869 | ||
870 | @table @option | |
871 | ||
872 | @item nb_out_samples, n | |
873 | Set the number of frames per each output audio frame. The number is | |
874 | intended as the number of samples @emph{per each channel}. | |
875 | Default value is 1024. | |
876 | ||
877 | @item pad, p | |
878 | If set to 1, the filter will pad the last audio frame with zeroes, so | |
879 | that the last frame will contain the same number of samples as the | |
880 | previous ones. Default value is 1. | |
881 | @end table | |
882 | ||
883 | For example, to set the number of per-frame samples to 1234 and | |
884 | disable padding for the last frame, use: | |
885 | @example | |
886 | asetnsamples=n=1234:p=0 | |
887 | @end example | |
888 | ||
889 | @section asetrate | |
890 | ||
891 | Set the sample rate without altering the PCM data. | |
892 | This will result in a change of speed and pitch. | |
893 | ||
894 | The filter accepts the following options: | |
895 | ||
896 | @table @option | |
897 | @item sample_rate, r | |
898 | Set the output sample rate. Default is 44100 Hz. | |
899 | @end table | |
900 | ||
901 | @section ashowinfo | |
902 | ||
903 | Show a line containing various information for each input audio frame. | |
904 | The input audio is not modified. | |
905 | ||
906 | The shown line contains a sequence of key/value pairs of the form | |
907 | @var{key}:@var{value}. | |
908 | ||
909 | The following values are shown in the output: | |
910 | ||
911 | @table @option | |
912 | @item n | |
913 | The (sequential) number of the input frame, starting from 0. | |
914 | ||
915 | @item pts | |
916 | The presentation timestamp of the input frame, in time base units; the time base | |
917 | depends on the filter input pad, and is usually 1/@var{sample_rate}. | |
918 | ||
919 | @item pts_time | |
920 | The presentation timestamp of the input frame in seconds. | |
921 | ||
922 | @item pos | |
923 | position of the frame in the input stream, -1 if this information in | |
924 | unavailable and/or meaningless (for example in case of synthetic audio) | |
925 | ||
926 | @item fmt | |
927 | The sample format. | |
928 | ||
929 | @item chlayout | |
930 | The channel layout. | |
931 | ||
932 | @item rate | |
933 | The sample rate for the audio frame. | |
934 | ||
935 | @item nb_samples | |
936 | The number of samples (per channel) in the frame. | |
937 | ||
938 | @item checksum | |
939 | The Adler-32 checksum (printed in hexadecimal) of the audio data. For planar | |
940 | audio, the data is treated as if all the planes were concatenated. | |
941 | ||
942 | @item plane_checksums | |
943 | A list of Adler-32 checksums for each data plane. | |
944 | @end table | |
945 | ||
946 | @section astats | |
947 | ||
948 | Display time domain statistical information about the audio channels. | |
949 | Statistics are calculated and displayed for each audio channel and, | |
950 | where applicable, an overall figure is also given. | |
951 | ||
952 | It accepts the following option: | |
953 | @table @option | |
954 | @item length | |
955 | Short window length in seconds, used for peak and trough RMS measurement. | |
956 | Default is @code{0.05} (50 miliseconds). Allowed range is @code{[0.1 - 10]}. | |
957 | @end table | |
958 | ||
959 | A description of each shown parameter follows: | |
960 | ||
961 | @table @option | |
962 | @item DC offset | |
963 | Mean amplitude displacement from zero. | |
964 | ||
965 | @item Min level | |
966 | Minimal sample level. | |
967 | ||
968 | @item Max level | |
969 | Maximal sample level. | |
970 | ||
971 | @item Peak level dB | |
972 | @item RMS level dB | |
973 | Standard peak and RMS level measured in dBFS. | |
974 | ||
975 | @item RMS peak dB | |
976 | @item RMS trough dB | |
977 | Peak and trough values for RMS level measured over a short window. | |
978 | ||
979 | @item Crest factor | |
980 | Standard ratio of peak to RMS level (note: not in dB). | |
981 | ||
982 | @item Flat factor | |
983 | Flatness (i.e. consecutive samples with the same value) of the signal at its peak levels | |
984 | (i.e. either @var{Min level} or @var{Max level}). | |
985 | ||
986 | @item Peak count | |
987 | Number of occasions (not the number of samples) that the signal attained either | |
988 | @var{Min level} or @var{Max level}. | |
989 | @end table | |
990 | ||
991 | @section astreamsync | |
992 | ||
993 | Forward two audio streams and control the order the buffers are forwarded. | |
994 | ||
995 | The filter accepts the following options: | |
996 | ||
997 | @table @option | |
998 | @item expr, e | |
999 | Set the expression deciding which stream should be | |
1000 | forwarded next: if the result is negative, the first stream is forwarded; if | |
1001 | the result is positive or zero, the second stream is forwarded. It can use | |
1002 | the following variables: | |
1003 | ||
1004 | @table @var | |
1005 | @item b1 b2 | |
1006 | number of buffers forwarded so far on each stream | |
1007 | @item s1 s2 | |
1008 | number of samples forwarded so far on each stream | |
1009 | @item t1 t2 | |
1010 | current timestamp of each stream | |
1011 | @end table | |
1012 | ||
1013 | The default value is @code{t1-t2}, which means to always forward the stream | |
1014 | that has a smaller timestamp. | |
1015 | @end table | |
1016 | ||
1017 | @subsection Examples | |
1018 | ||
1019 | Stress-test @code{amerge} by randomly sending buffers on the wrong | |
1020 | input, while avoiding too much of a desynchronization: | |
1021 | @example | |
1022 | amovie=file.ogg [a] ; amovie=file.mp3 [b] ; | |
1023 | [a] [b] astreamsync=(2*random(1))-1+tanh(5*(t1-t2)) [a2] [b2] ; | |
1024 | [a2] [b2] amerge | |
1025 | @end example | |
1026 | ||
1027 | @section asyncts | |
1028 | ||
1029 | Synchronize audio data with timestamps by squeezing/stretching it and/or | |
1030 | dropping samples/adding silence when needed. | |
1031 | ||
1032 | This filter is not built by default, please use @ref{aresample} to do squeezing/stretching. | |
1033 | ||
1034 | It accepts the following parameters: | |
1035 | @table @option | |
1036 | ||
1037 | @item compensate | |
1038 | Enable stretching/squeezing the data to make it match the timestamps. Disabled | |
1039 | by default. When disabled, time gaps are covered with silence. | |
1040 | ||
1041 | @item min_delta | |
1042 | The minimum difference between timestamps and audio data (in seconds) to trigger | |
1043 | adding/dropping samples. The default value is 0.1. If you get an imperfect | |
1044 | sync with this filter, try setting this parameter to 0. | |
1045 | ||
1046 | @item max_comp | |
1047 | The maximum compensation in samples per second. Only relevant with compensate=1. | |
1048 | The default value is 500. | |
1049 | ||
1050 | @item first_pts | |
1051 | Assume that the first PTS should be this value. The time base is 1 / sample | |
1052 | rate. This allows for padding/trimming at the start of the stream. By default, | |
1053 | no assumption is made about the first frame's expected PTS, so no padding or | |
1054 | trimming is done. For example, this could be set to 0 to pad the beginning with | |
1055 | silence if an audio stream starts after the video stream or to trim any samples | |
1056 | with a negative PTS due to encoder delay. | |
1057 | ||
1058 | @end table | |
1059 | ||
1060 | @section atempo | |
1061 | ||
1062 | Adjust audio tempo. | |
1063 | ||
1064 | The filter accepts exactly one parameter, the audio tempo. If not | |
1065 | specified then the filter will assume nominal 1.0 tempo. Tempo must | |
1066 | be in the [0.5, 2.0] range. | |
1067 | ||
1068 | @subsection Examples | |
1069 | ||
1070 | @itemize | |
1071 | @item | |
1072 | Slow down audio to 80% tempo: | |
1073 | @example | |
1074 | atempo=0.8 | |
1075 | @end example | |
1076 | ||
1077 | @item | |
1078 | To speed up audio to 125% tempo: | |
1079 | @example | |
1080 | atempo=1.25 | |
1081 | @end example | |
1082 | @end itemize | |
1083 | ||
1084 | @section atrim | |
1085 | ||
1086 | Trim the input so that the output contains one continuous subpart of the input. | |
1087 | ||
1088 | It accepts the following parameters: | |
1089 | @table @option | |
1090 | @item start | |
1091 | Timestamp (in seconds) of the start of the section to keep. I.e. the audio | |
1092 | sample with the timestamp @var{start} will be the first sample in the output. | |
1093 | ||
1094 | @item end | |
1095 | Specify time of the first audio sample that will be dropped, i.e. the | |
1096 | audio sample immediately preceding the one with the timestamp @var{end} will be | |
1097 | the last sample in the output. | |
1098 | ||
1099 | @item start_pts | |
1100 | Same as @var{start}, except this option sets the start timestamp in samples | |
1101 | instead of seconds. | |
1102 | ||
1103 | @item end_pts | |
1104 | Same as @var{end}, except this option sets the end timestamp in samples instead | |
1105 | of seconds. | |
1106 | ||
1107 | @item duration | |
1108 | The maximum duration of the output in seconds. | |
1109 | ||
1110 | @item start_sample | |
1111 | The number of the first sample that should be output. | |
1112 | ||
1113 | @item end_sample | |
1114 | The number of the first sample that should be dropped. | |
1115 | @end table | |
1116 | ||
1117 | @option{start}, @option{end}, and @option{duration} are expressed as time | |
1118 | duration specifications; see | |
1119 | @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}. | |
1120 | ||
1121 | Note that the first two sets of the start/end options and the @option{duration} | |
1122 | option look at the frame timestamp, while the _sample options simply count the | |
1123 | samples that pass through the filter. So start/end_pts and start/end_sample will | |
1124 | give different results when the timestamps are wrong, inexact or do not start at | |
1125 | zero. Also note that this filter does not modify the timestamps. If you wish | |
1126 | to have the output timestamps start at zero, insert the asetpts filter after the | |
1127 | atrim filter. | |
1128 | ||
1129 | If multiple start or end options are set, this filter tries to be greedy and | |
1130 | keep all samples that match at least one of the specified constraints. To keep | |
1131 | only the part that matches all the constraints at once, chain multiple atrim | |
1132 | filters. | |
1133 | ||
1134 | The defaults are such that all the input is kept. So it is possible to set e.g. | |
1135 | just the end values to keep everything before the specified time. | |
1136 | ||
1137 | Examples: | |
1138 | @itemize | |
1139 | @item | |
1140 | Drop everything except the second minute of input: | |
1141 | @example | |
1142 | ffmpeg -i INPUT -af atrim=60:120 | |
1143 | @end example | |
1144 | ||
1145 | @item | |
1146 | Keep only the first 1000 samples: | |
1147 | @example | |
1148 | ffmpeg -i INPUT -af atrim=end_sample=1000 | |
1149 | @end example | |
1150 | ||
1151 | @end itemize | |
1152 | ||
1153 | @section bandpass | |
1154 | ||
1155 | Apply a two-pole Butterworth band-pass filter with central | |
1156 | frequency @var{frequency}, and (3dB-point) band-width width. | |
1157 | The @var{csg} option selects a constant skirt gain (peak gain = Q) | |
1158 | instead of the default: constant 0dB peak gain. | |
1159 | The filter roll off at 6dB per octave (20dB per decade). | |
1160 | ||
1161 | The filter accepts the following options: | |
1162 | ||
1163 | @table @option | |
1164 | @item frequency, f | |
1165 | Set the filter's central frequency. Default is @code{3000}. | |
1166 | ||
1167 | @item csg | |
1168 | Constant skirt gain if set to 1. Defaults to 0. | |
1169 | ||
1170 | @item width_type | |
1171 | Set method to specify band-width of filter. | |
1172 | @table @option | |
1173 | @item h | |
1174 | Hz | |
1175 | @item q | |
1176 | Q-Factor | |
1177 | @item o | |
1178 | octave | |
1179 | @item s | |
1180 | slope | |
1181 | @end table | |
1182 | ||
1183 | @item width, w | |
1184 | Specify the band-width of a filter in width_type units. | |
1185 | @end table | |
1186 | ||
1187 | @section bandreject | |
1188 | ||
1189 | Apply a two-pole Butterworth band-reject filter with central | |
1190 | frequency @var{frequency}, and (3dB-point) band-width @var{width}. | |
1191 | The filter roll off at 6dB per octave (20dB per decade). | |
1192 | ||
1193 | The filter accepts the following options: | |
1194 | ||
1195 | @table @option | |
1196 | @item frequency, f | |
1197 | Set the filter's central frequency. Default is @code{3000}. | |
1198 | ||
1199 | @item width_type | |
1200 | Set method to specify band-width of filter. | |
1201 | @table @option | |
1202 | @item h | |
1203 | Hz | |
1204 | @item q | |
1205 | Q-Factor | |
1206 | @item o | |
1207 | octave | |
1208 | @item s | |
1209 | slope | |
1210 | @end table | |
1211 | ||
1212 | @item width, w | |
1213 | Specify the band-width of a filter in width_type units. | |
1214 | @end table | |
1215 | ||
1216 | @section bass | |
1217 | ||
1218 | Boost or cut the bass (lower) frequencies of the audio using a two-pole | |
1219 | shelving filter with a response similar to that of a standard | |
1220 | hi-fi's tone-controls. This is also known as shelving equalisation (EQ). | |
1221 | ||
1222 | The filter accepts the following options: | |
1223 | ||
1224 | @table @option | |
1225 | @item gain, g | |
1226 | Give the gain at 0 Hz. Its useful range is about -20 | |
1227 | (for a large cut) to +20 (for a large boost). | |
1228 | Beware of clipping when using a positive gain. | |
1229 | ||
1230 | @item frequency, f | |
1231 | Set the filter's central frequency and so can be used | |
1232 | to extend or reduce the frequency range to be boosted or cut. | |
1233 | The default value is @code{100} Hz. | |
1234 | ||
1235 | @item width_type | |
1236 | Set method to specify band-width of filter. | |
1237 | @table @option | |
1238 | @item h | |
1239 | Hz | |
1240 | @item q | |
1241 | Q-Factor | |
1242 | @item o | |
1243 | octave | |
1244 | @item s | |
1245 | slope | |
1246 | @end table | |
1247 | ||
1248 | @item width, w | |
1249 | Determine how steep is the filter's shelf transition. | |
1250 | @end table | |
1251 | ||
1252 | @section biquad | |
1253 | ||
1254 | Apply a biquad IIR filter with the given coefficients. | |
1255 | Where @var{b0}, @var{b1}, @var{b2} and @var{a0}, @var{a1}, @var{a2} | |
1256 | are the numerator and denominator coefficients respectively. | |
1257 | ||
1258 | @section bs2b | |
1259 | Bauer stereo to binaural transformation, which improves headphone listening of | |
1260 | stereo audio records. | |
1261 | ||
1262 | It accepts the following parameters: | |
1263 | @table @option | |
1264 | ||
1265 | @item profile | |
1266 | Pre-defined crossfeed level. | |
1267 | @table @option | |
1268 | ||
1269 | @item default | |
1270 | Default level (fcut=700, feed=50). | |
1271 | ||
1272 | @item cmoy | |
1273 | Chu Moy circuit (fcut=700, feed=60). | |
1274 | ||
1275 | @item jmeier | |
1276 | Jan Meier circuit (fcut=650, feed=95). | |
1277 | ||
1278 | @end table | |
1279 | ||
1280 | @item fcut | |
1281 | Cut frequency (in Hz). | |
1282 | ||
1283 | @item feed | |
1284 | Feed level (in Hz). | |
1285 | ||
1286 | @end table | |
1287 | ||
1288 | @section channelmap | |
1289 | ||
1290 | Remap input channels to new locations. | |
1291 | ||
1292 | It accepts the following parameters: | |
1293 | @table @option | |
1294 | @item channel_layout | |
1295 | The channel layout of the output stream. | |
1296 | ||
1297 | @item map | |
1298 | Map channels from input to output. The argument is a '|'-separated list of | |
1299 | mappings, each in the @code{@var{in_channel}-@var{out_channel}} or | |
1300 | @var{in_channel} form. @var{in_channel} can be either the name of the input | |
1301 | channel (e.g. FL for front left) or its index in the input channel layout. | |
1302 | @var{out_channel} is the name of the output channel or its index in the output | |
1303 | channel layout. If @var{out_channel} is not given then it is implicitly an | |
1304 | index, starting with zero and increasing by one for each mapping. | |
1305 | @end table | |
1306 | ||
1307 | If no mapping is present, the filter will implicitly map input channels to | |
1308 | output channels, preserving indices. | |
1309 | ||
1310 | For example, assuming a 5.1+downmix input MOV file, | |
1311 | @example | |
1312 | ffmpeg -i in.mov -filter 'channelmap=map=DL-FL|DR-FR' out.wav | |
1313 | @end example | |
1314 | will create an output WAV file tagged as stereo from the downmix channels of | |
1315 | the input. | |
1316 | ||
1317 | To fix a 5.1 WAV improperly encoded in AAC's native channel order | |
1318 | @example | |
1319 | ffmpeg -i in.wav -filter 'channelmap=1|2|0|5|3|4:channel_layout=5.1' out.wav | |
1320 | @end example | |
1321 | ||
1322 | @section channelsplit | |
1323 | ||
1324 | Split each channel from an input audio stream into a separate output stream. | |
1325 | ||
1326 | It accepts the following parameters: | |
1327 | @table @option | |
1328 | @item channel_layout | |
1329 | The channel layout of the input stream. The default is "stereo". | |
1330 | @end table | |
1331 | ||
1332 | For example, assuming a stereo input MP3 file, | |
1333 | @example | |
1334 | ffmpeg -i in.mp3 -filter_complex channelsplit out.mkv | |
1335 | @end example | |
1336 | will create an output Matroska file with two audio streams, one containing only | |
1337 | the left channel and the other the right channel. | |
1338 | ||
1339 | Split a 5.1 WAV file into per-channel files: | |
1340 | @example | |
1341 | ffmpeg -i in.wav -filter_complex | |
1342 | 'channelsplit=channel_layout=5.1[FL][FR][FC][LFE][SL][SR]' | |
1343 | -map '[FL]' front_left.wav -map '[FR]' front_right.wav -map '[FC]' | |
1344 | front_center.wav -map '[LFE]' lfe.wav -map '[SL]' side_left.wav -map '[SR]' | |
1345 | side_right.wav | |
1346 | @end example | |
1347 | ||
1348 | @section compand | |
1349 | Compress or expand the audio's dynamic range. | |
1350 | ||
1351 | It accepts the following parameters: | |
1352 | ||
1353 | @table @option | |
1354 | ||
1355 | @item attacks | |
1356 | @item decays | |
1357 | A list of times in seconds for each channel over which the instantaneous level | |
1358 | of the input signal is averaged to determine its volume. @var{attacks} refers to | |
1359 | increase of volume and @var{decays} refers to decrease of volume. For most | |
1360 | situations, the attack time (response to the audio getting louder) should be | |
1361 | shorter than the decay time, because the human ear is more sensitive to sudden | |
1362 | loud audio than sudden soft audio. A typical value for attack is 0.3 seconds and | |
1363 | a typical value for decay is 0.8 seconds. | |
1364 | ||
1365 | @item points | |
1366 | A list of points for the transfer function, specified in dB relative to the | |
1367 | maximum possible signal amplitude. Each key points list must be defined using | |
1368 | the following syntax: @code{x0/y0|x1/y1|x2/y2|....} or | |
1369 | @code{x0/y0 x1/y1 x2/y2 ....} | |
1370 | ||
1371 | The input values must be in strictly increasing order but the transfer function | |
1372 | does not have to be monotonically rising. The point @code{0/0} is assumed but | |
1373 | may be overridden (by @code{0/out-dBn}). Typical values for the transfer | |
1374 | function are @code{-70/-70|-60/-20}. | |
1375 | ||
1376 | @item soft-knee | |
1377 | Set the curve radius in dB for all joints. It defaults to 0.01. | |
1378 | ||
1379 | @item gain | |
1380 | Set the additional gain in dB to be applied at all points on the transfer | |
1381 | function. This allows for easy adjustment of the overall gain. | |
1382 | It defaults to 0. | |
1383 | ||
1384 | @item volume | |
1385 | Set an initial volume, in dB, to be assumed for each channel when filtering | |
1386 | starts. This permits the user to supply a nominal level initially, so that, for | |
1387 | example, a very large gain is not applied to initial signal levels before the | |
1388 | companding has begun to operate. A typical value for audio which is initially | |
1389 | quiet is -90 dB. It defaults to 0. | |
1390 | ||
1391 | @item delay | |
1392 | Set a delay, in seconds. The input audio is analyzed immediately, but audio is | |
1393 | delayed before being fed to the volume adjuster. Specifying a delay | |
1394 | approximately equal to the attack/decay times allows the filter to effectively | |
1395 | operate in predictive rather than reactive mode. It defaults to 0. | |
1396 | ||
1397 | @end table | |
1398 | ||
1399 | @subsection Examples | |
1400 | ||
1401 | @itemize | |
1402 | @item | |
1403 | Make music with both quiet and loud passages suitable for listening to in a | |
1404 | noisy environment: | |
1405 | @example | |
1406 | compand=.3|.3:1|1:-90/-60|-60/-40|-40/-30|-20/-20:6:0:-90:0.2 | |
1407 | @end example | |
1408 | ||
1409 | @item | |
1410 | A noise gate for when the noise is at a lower level than the signal: | |
1411 | @example | |
1412 | compand=.1|.1:.2|.2:-900/-900|-50.1/-900|-50/-50:.01:0:-90:.1 | |
1413 | @end example | |
1414 | ||
1415 | @item | |
1416 | Here is another noise gate, this time for when the noise is at a higher level | |
1417 | than the signal (making it, in some ways, similar to squelch): | |
1418 | @example | |
1419 | compand=.1|.1:.1|.1:-45.1/-45.1|-45/-900|0/-900:.01:45:-90:.1 | |
1420 | @end example | |
1421 | @end itemize | |
1422 | ||
1423 | @section earwax | |
1424 | ||
1425 | Make audio easier to listen to on headphones. | |
1426 | ||
1427 | This filter adds `cues' to 44.1kHz stereo (i.e. audio CD format) audio | |
1428 | so that when listened to on headphones the stereo image is moved from | |
1429 | inside your head (standard for headphones) to outside and in front of | |
1430 | the listener (standard for speakers). | |
1431 | ||
1432 | Ported from SoX. | |
1433 | ||
1434 | @section equalizer | |
1435 | ||
1436 | Apply a two-pole peaking equalisation (EQ) filter. With this | |
1437 | filter, the signal-level at and around a selected frequency can | |
1438 | be increased or decreased, whilst (unlike bandpass and bandreject | |
1439 | filters) that at all other frequencies is unchanged. | |
1440 | ||
1441 | In order to produce complex equalisation curves, this filter can | |
1442 | be given several times, each with a different central frequency. | |
1443 | ||
1444 | The filter accepts the following options: | |
1445 | ||
1446 | @table @option | |
1447 | @item frequency, f | |
1448 | Set the filter's central frequency in Hz. | |
1449 | ||
1450 | @item width_type | |
1451 | Set method to specify band-width of filter. | |
1452 | @table @option | |
1453 | @item h | |
1454 | Hz | |
1455 | @item q | |
1456 | Q-Factor | |
1457 | @item o | |
1458 | octave | |
1459 | @item s | |
1460 | slope | |
1461 | @end table | |
1462 | ||
1463 | @item width, w | |
1464 | Specify the band-width of a filter in width_type units. | |
1465 | ||
1466 | @item gain, g | |
1467 | Set the required gain or attenuation in dB. | |
1468 | Beware of clipping when using a positive gain. | |
1469 | @end table | |
1470 | ||
1471 | @subsection Examples | |
1472 | @itemize | |
1473 | @item | |
1474 | Attenuate 10 dB at 1000 Hz, with a bandwidth of 200 Hz: | |
1475 | @example | |
1476 | equalizer=f=1000:width_type=h:width=200:g=-10 | |
1477 | @end example | |
1478 | ||
1479 | @item | |
1480 | Apply 2 dB gain at 1000 Hz with Q 1 and attenuate 5 dB at 100 Hz with Q 2: | |
1481 | @example | |
1482 | equalizer=f=1000:width_type=q:width=1:g=2,equalizer=f=100:width_type=q:width=2:g=-5 | |
1483 | @end example | |
1484 | @end itemize | |
1485 | ||
1486 | @section flanger | |
1487 | Apply a flanging effect to the audio. | |
1488 | ||
1489 | The filter accepts the following options: | |
1490 | ||
1491 | @table @option | |
1492 | @item delay | |
1493 | Set base delay in milliseconds. Range from 0 to 30. Default value is 0. | |
1494 | ||
1495 | @item depth | |
1496 | Set added swep delay in milliseconds. Range from 0 to 10. Default value is 2. | |
1497 | ||
1498 | @item regen | |
1499 | Set percentage regeneneration (delayed signal feedback). Range from -95 to 95. | |
1500 | Default value is 0. | |
1501 | ||
1502 | @item width | |
1503 | Set percentage of delayed signal mixed with original. Range from 0 to 100. | |
1504 | Default valu is 71. | |
1505 | ||
1506 | @item speed | |
1507 | Set sweeps per second (Hz). Range from 0.1 to 10. Default value is 0.5. | |
1508 | ||
1509 | @item shape | |
1510 | Set swept wave shape, can be @var{triangular} or @var{sinusoidal}. | |
1511 | Default value is @var{sinusoidal}. | |
1512 | ||
1513 | @item phase | |
1514 | Set swept wave percentage-shift for multi channel. Range from 0 to 100. | |
1515 | Default value is 25. | |
1516 | ||
1517 | @item interp | |
1518 | Set delay-line interpolation, @var{linear} or @var{quadratic}. | |
1519 | Default is @var{linear}. | |
1520 | @end table | |
1521 | ||
1522 | @section highpass | |
1523 | ||
1524 | Apply a high-pass filter with 3dB point frequency. | |
1525 | The filter can be either single-pole, or double-pole (the default). | |
1526 | The filter roll off at 6dB per pole per octave (20dB per pole per decade). | |
1527 | ||
1528 | The filter accepts the following options: | |
1529 | ||
1530 | @table @option | |
1531 | @item frequency, f | |
1532 | Set frequency in Hz. Default is 3000. | |
1533 | ||
1534 | @item poles, p | |
1535 | Set number of poles. Default is 2. | |
1536 | ||
1537 | @item width_type | |
1538 | Set method to specify band-width of filter. | |
1539 | @table @option | |
1540 | @item h | |
1541 | Hz | |
1542 | @item q | |
1543 | Q-Factor | |
1544 | @item o | |
1545 | octave | |
1546 | @item s | |
1547 | slope | |
1548 | @end table | |
1549 | ||
1550 | @item width, w | |
1551 | Specify the band-width of a filter in width_type units. | |
1552 | Applies only to double-pole filter. | |
1553 | The default is 0.707q and gives a Butterworth response. | |
1554 | @end table | |
1555 | ||
1556 | @section join | |
1557 | ||
1558 | Join multiple input streams into one multi-channel stream. | |
1559 | ||
1560 | It accepts the following parameters: | |
1561 | @table @option | |
1562 | ||
1563 | @item inputs | |
1564 | The number of input streams. It defaults to 2. | |
1565 | ||
1566 | @item channel_layout | |
1567 | The desired output channel layout. It defaults to stereo. | |
1568 | ||
1569 | @item map | |
1570 | Map channels from inputs to output. The argument is a '|'-separated list of | |
1571 | mappings, each in the @code{@var{input_idx}.@var{in_channel}-@var{out_channel}} | |
1572 | form. @var{input_idx} is the 0-based index of the input stream. @var{in_channel} | |
1573 | can be either the name of the input channel (e.g. FL for front left) or its | |
1574 | index in the specified input stream. @var{out_channel} is the name of the output | |
1575 | channel. | |
1576 | @end table | |
1577 | ||
1578 | The filter will attempt to guess the mappings when they are not specified | |
1579 | explicitly. It does so by first trying to find an unused matching input channel | |
1580 | and if that fails it picks the first unused input channel. | |
1581 | ||
1582 | Join 3 inputs (with properly set channel layouts): | |
1583 | @example | |
1584 | ffmpeg -i INPUT1 -i INPUT2 -i INPUT3 -filter_complex join=inputs=3 OUTPUT | |
1585 | @end example | |
1586 | ||
1587 | Build a 5.1 output from 6 single-channel streams: | |
1588 | @example | |
1589 | ffmpeg -i fl -i fr -i fc -i sl -i sr -i lfe -filter_complex | |
1590 | 'join=inputs=6:channel_layout=5.1:map=0.0-FL|1.0-FR|2.0-FC|3.0-SL|4.0-SR|5.0-LFE' | |
1591 | out | |
1592 | @end example | |
1593 | ||
1594 | @section ladspa | |
1595 | ||
1596 | Load a LADSPA (Linux Audio Developer's Simple Plugin API) plugin. | |
1597 | ||
1598 | To enable compilation of this filter you need to configure FFmpeg with | |
1599 | @code{--enable-ladspa}. | |
1600 | ||
1601 | @table @option | |
1602 | @item file, f | |
1603 | Specifies the name of LADSPA plugin library to load. If the environment | |
1604 | variable @env{LADSPA_PATH} is defined, the LADSPA plugin is searched in | |
1605 | each one of the directories specified by the colon separated list in | |
1606 | @env{LADSPA_PATH}, otherwise in the standard LADSPA paths, which are in | |
1607 | this order: @file{HOME/.ladspa/lib/}, @file{/usr/local/lib/ladspa/}, | |
1608 | @file{/usr/lib/ladspa/}. | |
1609 | ||
1610 | @item plugin, p | |
1611 | Specifies the plugin within the library. Some libraries contain only | |
1612 | one plugin, but others contain many of them. If this is not set filter | |
1613 | will list all available plugins within the specified library. | |
1614 | ||
1615 | @item controls, c | |
1616 | Set the '|' separated list of controls which are zero or more floating point | |
1617 | values that determine the behavior of the loaded plugin (for example delay, | |
1618 | threshold or gain). | |
1619 | Controls need to be defined using the following syntax: | |
1620 | c0=@var{value0}|c1=@var{value1}|c2=@var{value2}|..., where | |
1621 | @var{valuei} is the value set on the @var{i}-th control. | |
1622 | If @option{controls} is set to @code{help}, all available controls and | |
1623 | their valid ranges are printed. | |
1624 | ||
1625 | @item sample_rate, s | |
1626 | Specify the sample rate, default to 44100. Only used if plugin have | |
1627 | zero inputs. | |
1628 | ||
1629 | @item nb_samples, n | |
1630 | Set the number of samples per channel per each output frame, default | |
1631 | is 1024. Only used if plugin have zero inputs. | |
1632 | ||
1633 | @item duration, d | |
1634 | Set the minimum duration of the sourced audio. See | |
1635 | @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils} | |
1636 | for the accepted syntax. | |
1637 | Note that the resulting duration may be greater than the specified duration, | |
1638 | as the generated audio is always cut at the end of a complete frame. | |
1639 | If not specified, or the expressed duration is negative, the audio is | |
1640 | supposed to be generated forever. | |
1641 | Only used if plugin have zero inputs. | |
1642 | ||
1643 | @end table | |
1644 | ||
1645 | @subsection Examples | |
1646 | ||
1647 | @itemize | |
1648 | @item | |
1649 | List all available plugins within amp (LADSPA example plugin) library: | |
1650 | @example | |
1651 | ladspa=file=amp | |
1652 | @end example | |
1653 | ||
1654 | @item | |
1655 | List all available controls and their valid ranges for @code{vcf_notch} | |
1656 | plugin from @code{VCF} library: | |
1657 | @example | |
1658 | ladspa=f=vcf:p=vcf_notch:c=help | |
1659 | @end example | |
1660 | ||
1661 | @item | |
1662 | Simulate low quality audio equipment using @code{Computer Music Toolkit} (CMT) | |
1663 | plugin library: | |
1664 | @example | |
1665 | ladspa=file=cmt:plugin=lofi:controls=c0=22|c1=12|c2=12 | |
1666 | @end example | |
1667 | ||
1668 | @item | |
1669 | Add reverberation to the audio using TAP-plugins | |
1670 | (Tom's Audio Processing plugins): | |
1671 | @example | |
1672 | ladspa=file=tap_reverb:tap_reverb | |
1673 | @end example | |
1674 | ||
1675 | @item | |
1676 | Generate white noise, with 0.2 amplitude: | |
1677 | @example | |
1678 | ladspa=file=cmt:noise_source_white:c=c0=.2 | |
1679 | @end example | |
1680 | ||
1681 | @item | |
1682 | Generate 20 bpm clicks using plugin @code{C* Click - Metronome} from the | |
1683 | @code{C* Audio Plugin Suite} (CAPS) library: | |
1684 | @example | |
1685 | ladspa=file=caps:Click:c=c1=20' | |
1686 | @end example | |
1687 | ||
1688 | @item | |
1689 | Apply @code{C* Eq10X2 - Stereo 10-band equaliser} effect: | |
1690 | @example | |
1691 | ladspa=caps:Eq10X2:c=c0=-48|c9=-24|c3=12|c4=2 | |
1692 | @end example | |
1693 | @end itemize | |
1694 | ||
1695 | @subsection Commands | |
1696 | ||
1697 | This filter supports the following commands: | |
1698 | @table @option | |
1699 | @item cN | |
1700 | Modify the @var{N}-th control value. | |
1701 | ||
1702 | If the specified value is not valid, it is ignored and prior one is kept. | |
1703 | @end table | |
1704 | ||
1705 | @section lowpass | |
1706 | ||
1707 | Apply a low-pass filter with 3dB point frequency. | |
1708 | The filter can be either single-pole or double-pole (the default). | |
1709 | The filter roll off at 6dB per pole per octave (20dB per pole per decade). | |
1710 | ||
1711 | The filter accepts the following options: | |
1712 | ||
1713 | @table @option | |
1714 | @item frequency, f | |
1715 | Set frequency in Hz. Default is 500. | |
1716 | ||
1717 | @item poles, p | |
1718 | Set number of poles. Default is 2. | |
1719 | ||
1720 | @item width_type | |
1721 | Set method to specify band-width of filter. | |
1722 | @table @option | |
1723 | @item h | |
1724 | Hz | |
1725 | @item q | |
1726 | Q-Factor | |
1727 | @item o | |
1728 | octave | |
1729 | @item s | |
1730 | slope | |
1731 | @end table | |
1732 | ||
1733 | @item width, w | |
1734 | Specify the band-width of a filter in width_type units. | |
1735 | Applies only to double-pole filter. | |
1736 | The default is 0.707q and gives a Butterworth response. | |
1737 | @end table | |
1738 | ||
1739 | @section pan | |
1740 | ||
1741 | Mix channels with specific gain levels. The filter accepts the output | |
1742 | channel layout followed by a set of channels definitions. | |
1743 | ||
1744 | This filter is also designed to remap efficiently the channels of an audio | |
1745 | stream. | |
1746 | ||
1747 | The filter accepts parameters of the form: | |
1748 | "@var{l}:@var{outdef}:@var{outdef}:..." | |
1749 | ||
1750 | @table @option | |
1751 | @item l | |
1752 | output channel layout or number of channels | |
1753 | ||
1754 | @item outdef | |
1755 | output channel specification, of the form: | |
1756 | "@var{out_name}=[@var{gain}*]@var{in_name}[+[@var{gain}*]@var{in_name}...]" | |
1757 | ||
1758 | @item out_name | |
1759 | output channel to define, either a channel name (FL, FR, etc.) or a channel | |
1760 | number (c0, c1, etc.) | |
1761 | ||
1762 | @item gain | |
1763 | multiplicative coefficient for the channel, 1 leaving the volume unchanged | |
1764 | ||
1765 | @item in_name | |
1766 | input channel to use, see out_name for details; it is not possible to mix | |
1767 | named and numbered input channels | |
1768 | @end table | |
1769 | ||
1770 | If the `=' in a channel specification is replaced by `<', then the gains for | |
1771 | that specification will be renormalized so that the total is 1, thus | |
1772 | avoiding clipping noise. | |
1773 | ||
1774 | @subsection Mixing examples | |
1775 | ||
1776 | For example, if you want to down-mix from stereo to mono, but with a bigger | |
1777 | factor for the left channel: | |
1778 | @example | |
1779 | pan=1:c0=0.9*c0+0.1*c1 | |
1780 | @end example | |
1781 | ||
1782 | A customized down-mix to stereo that works automatically for 3-, 4-, 5- and | |
1783 | 7-channels surround: | |
1784 | @example | |
1785 | pan=stereo: FL < FL + 0.5*FC + 0.6*BL + 0.6*SL : FR < FR + 0.5*FC + 0.6*BR + 0.6*SR | |
1786 | @end example | |
1787 | ||
1788 | Note that @command{ffmpeg} integrates a default down-mix (and up-mix) system | |
1789 | that should be preferred (see "-ac" option) unless you have very specific | |
1790 | needs. | |
1791 | ||
1792 | @subsection Remapping examples | |
1793 | ||
1794 | The channel remapping will be effective if, and only if: | |
1795 | ||
1796 | @itemize | |
1797 | @item gain coefficients are zeroes or ones, | |
1798 | @item only one input per channel output, | |
1799 | @end itemize | |
1800 | ||
1801 | If all these conditions are satisfied, the filter will notify the user ("Pure | |
1802 | channel mapping detected"), and use an optimized and lossless method to do the | |
1803 | remapping. | |
1804 | ||
1805 | For example, if you have a 5.1 source and want a stereo audio stream by | |
1806 | dropping the extra channels: | |
1807 | @example | |
1808 | pan="stereo: c0=FL : c1=FR" | |
1809 | @end example | |
1810 | ||
1811 | Given the same source, you can also switch front left and front right channels | |
1812 | and keep the input channel layout: | |
1813 | @example | |
1814 | pan="5.1: c0=c1 : c1=c0 : c2=c2 : c3=c3 : c4=c4 : c5=c5" | |
1815 | @end example | |
1816 | ||
1817 | If the input is a stereo audio stream, you can mute the front left channel (and | |
1818 | still keep the stereo channel layout) with: | |
1819 | @example | |
1820 | pan="stereo:c1=c1" | |
1821 | @end example | |
1822 | ||
1823 | Still with a stereo audio stream input, you can copy the right channel in both | |
1824 | front left and right: | |
1825 | @example | |
1826 | pan="stereo: c0=FR : c1=FR" | |
1827 | @end example | |
1828 | ||
1829 | @section replaygain | |
1830 | ||
1831 | ReplayGain scanner filter. This filter takes an audio stream as an input and | |
1832 | outputs it unchanged. | |
1833 | At end of filtering it displays @code{track_gain} and @code{track_peak}. | |
1834 | ||
1835 | @section resample | |
1836 | ||
1837 | Convert the audio sample format, sample rate and channel layout. It is | |
1838 | not meant to be used directly. | |
1839 | ||
1840 | @section silencedetect | |
1841 | ||
1842 | Detect silence in an audio stream. | |
1843 | ||
1844 | This filter logs a message when it detects that the input audio volume is less | |
1845 | or equal to a noise tolerance value for a duration greater or equal to the | |
1846 | minimum detected noise duration. | |
1847 | ||
1848 | The printed times and duration are expressed in seconds. | |
1849 | ||
1850 | The filter accepts the following options: | |
1851 | ||
1852 | @table @option | |
1853 | @item duration, d | |
1854 | Set silence duration until notification (default is 2 seconds). | |
1855 | ||
1856 | @item noise, n | |
1857 | Set noise tolerance. Can be specified in dB (in case "dB" is appended to the | |
1858 | specified value) or amplitude ratio. Default is -60dB, or 0.001. | |
1859 | @end table | |
1860 | ||
1861 | @subsection Examples | |
1862 | ||
1863 | @itemize | |
1864 | @item | |
1865 | Detect 5 seconds of silence with -50dB noise tolerance: | |
1866 | @example | |
1867 | silencedetect=n=-50dB:d=5 | |
1868 | @end example | |
1869 | ||
1870 | @item | |
1871 | Complete example with @command{ffmpeg} to detect silence with 0.0001 noise | |
1872 | tolerance in @file{silence.mp3}: | |
1873 | @example | |
1874 | ffmpeg -i silence.mp3 -af silencedetect=noise=0.0001 -f null - | |
1875 | @end example | |
1876 | @end itemize | |
1877 | ||
1878 | @section silenceremove | |
1879 | ||
1880 | Remove silence from the beginning, middle or end of the audio. | |
1881 | ||
1882 | The filter accepts the following options: | |
1883 | ||
1884 | @table @option | |
1885 | @item start_periods | |
1886 | This value is used to indicate if audio should be trimmed at beginning of | |
1887 | the audio. A value of zero indicates no silence should be trimmed from the | |
1888 | beginning. When specifying a non-zero value, it trims audio up until it | |
1889 | finds non-silence. Normally, when trimming silence from beginning of audio | |
1890 | the @var{start_periods} will be @code{1} but it can be increased to higher | |
1891 | values to trim all audio up to specific count of non-silence periods. | |
1892 | Default value is @code{0}. | |
1893 | ||
1894 | @item start_duration | |
1895 | Specify the amount of time that non-silence must be detected before it stops | |
1896 | trimming audio. By increasing the duration, bursts of noises can be treated | |
1897 | as silence and trimmed off. Default value is @code{0}. | |
1898 | ||
1899 | @item start_threshold | |
1900 | This indicates what sample value should be treated as silence. For digital | |
1901 | audio, a value of @code{0} may be fine but for audio recorded from analog, | |
1902 | you may wish to increase the value to account for background noise. | |
1903 | Can be specified in dB (in case "dB" is appended to the specified value) | |
1904 | or amplitude ratio. Default value is @code{0}. | |
1905 | ||
1906 | @item stop_periods | |
1907 | Set the count for trimming silence from the end of audio. | |
1908 | To remove silence from the middle of a file, specify a @var{stop_periods} | |
1909 | that is negative. This value is then threated as a positive value and is | |
1910 | used to indicate the effect should restart processing as specified by | |
1911 | @var{start_periods}, making it suitable for removing periods of silence | |
1912 | in the middle of the audio. | |
1913 | Default value is @code{0}. | |
1914 | ||
1915 | @item stop_duration | |
1916 | Specify a duration of silence that must exist before audio is not copied any | |
1917 | more. By specifying a higher duration, silence that is wanted can be left in | |
1918 | the audio. | |
1919 | Default value is @code{0}. | |
1920 | ||
1921 | @item stop_threshold | |
1922 | This is the same as @option{start_threshold} but for trimming silence from | |
1923 | the end of audio. | |
1924 | Can be specified in dB (in case "dB" is appended to the specified value) | |
1925 | or amplitude ratio. Default value is @code{0}. | |
1926 | ||
1927 | @item leave_silence | |
1928 | This indicate that @var{stop_duration} length of audio should be left intact | |
1929 | at the beginning of each period of silence. | |
1930 | For example, if you want to remove long pauses between words but do not want | |
1931 | to remove the pauses completely. Default value is @code{0}. | |
1932 | ||
1933 | @end table | |
1934 | ||
1935 | @subsection Examples | |
1936 | ||
1937 | @itemize | |
1938 | @item | |
1939 | The following example shows how this filter can be used to start a recording | |
1940 | that does not contain the delay at the start which usually occurs between | |
1941 | pressing the record button and the start of the performance: | |
1942 | @example | |
1943 | silenceremove=1:5:0.02 | |
1944 | @end example | |
1945 | @end itemize | |
1946 | ||
1947 | @section treble | |
1948 | ||
1949 | Boost or cut treble (upper) frequencies of the audio using a two-pole | |
1950 | shelving filter with a response similar to that of a standard | |
1951 | hi-fi's tone-controls. This is also known as shelving equalisation (EQ). | |
1952 | ||
1953 | The filter accepts the following options: | |
1954 | ||
1955 | @table @option | |
1956 | @item gain, g | |
1957 | Give the gain at whichever is the lower of ~22 kHz and the | |
1958 | Nyquist frequency. Its useful range is about -20 (for a large cut) | |
1959 | to +20 (for a large boost). Beware of clipping when using a positive gain. | |
1960 | ||
1961 | @item frequency, f | |
1962 | Set the filter's central frequency and so can be used | |
1963 | to extend or reduce the frequency range to be boosted or cut. | |
1964 | The default value is @code{3000} Hz. | |
1965 | ||
1966 | @item width_type | |
1967 | Set method to specify band-width of filter. | |
1968 | @table @option | |
1969 | @item h | |
1970 | Hz | |
1971 | @item q | |
1972 | Q-Factor | |
1973 | @item o | |
1974 | octave | |
1975 | @item s | |
1976 | slope | |
1977 | @end table | |
1978 | ||
1979 | @item width, w | |
1980 | Determine how steep is the filter's shelf transition. | |
1981 | @end table | |
1982 | ||
1983 | @section volume | |
1984 | ||
1985 | Adjust the input audio volume. | |
1986 | ||
1987 | It accepts the following parameters: | |
1988 | @table @option | |
1989 | ||
1990 | @item volume | |
1991 | Set audio volume expression. | |
1992 | ||
1993 | Output values are clipped to the maximum value. | |
1994 | ||
1995 | The output audio volume is given by the relation: | |
1996 | @example | |
1997 | @var{output_volume} = @var{volume} * @var{input_volume} | |
1998 | @end example | |
1999 | ||
2000 | The default value for @var{volume} is "1.0". | |
2001 | ||
2002 | @item precision | |
2003 | This parameter represents the mathematical precision. | |
2004 | ||
2005 | It determines which input sample formats will be allowed, which affects the | |
2006 | precision of the volume scaling. | |
2007 | ||
2008 | @table @option | |
2009 | @item fixed | |
2010 | 8-bit fixed-point; this limits input sample format to U8, S16, and S32. | |
2011 | @item float | |
2012 | 32-bit floating-point; this limits input sample format to FLT. (default) | |
2013 | @item double | |
2014 | 64-bit floating-point; this limits input sample format to DBL. | |
2015 | @end table | |
2016 | ||
2017 | @item replaygain | |
2018 | Choose the behaviour on encountering ReplayGain side data in input frames. | |
2019 | ||
2020 | @table @option | |
2021 | @item drop | |
2022 | Remove ReplayGain side data, ignoring its contents (the default). | |
2023 | ||
2024 | @item ignore | |
2025 | Ignore ReplayGain side data, but leave it in the frame. | |
2026 | ||
2027 | @item track | |
2028 | Prefer the track gain, if present. | |
2029 | ||
2030 | @item album | |
2031 | Prefer the album gain, if present. | |
2032 | @end table | |
2033 | ||
2034 | @item replaygain_preamp | |
2035 | Pre-amplification gain in dB to apply to the selected replaygain gain. | |
2036 | ||
2037 | Default value for @var{replaygain_preamp} is 0.0. | |
2038 | ||
2039 | @item eval | |
2040 | Set when the volume expression is evaluated. | |
2041 | ||
2042 | It accepts the following values: | |
2043 | @table @samp | |
2044 | @item once | |
2045 | only evaluate expression once during the filter initialization, or | |
2046 | when the @samp{volume} command is sent | |
2047 | ||
2048 | @item frame | |
2049 | evaluate expression for each incoming frame | |
2050 | @end table | |
2051 | ||
2052 | Default value is @samp{once}. | |
2053 | @end table | |
2054 | ||
2055 | The volume expression can contain the following parameters. | |
2056 | ||
2057 | @table @option | |
2058 | @item n | |
2059 | frame number (starting at zero) | |
2060 | @item nb_channels | |
2061 | number of channels | |
2062 | @item nb_consumed_samples | |
2063 | number of samples consumed by the filter | |
2064 | @item nb_samples | |
2065 | number of samples in the current frame | |
2066 | @item pos | |
2067 | original frame position in the file | |
2068 | @item pts | |
2069 | frame PTS | |
2070 | @item sample_rate | |
2071 | sample rate | |
2072 | @item startpts | |
2073 | PTS at start of stream | |
2074 | @item startt | |
2075 | time at start of stream | |
2076 | @item t | |
2077 | frame time | |
2078 | @item tb | |
2079 | timestamp timebase | |
2080 | @item volume | |
2081 | last set volume value | |
2082 | @end table | |
2083 | ||
2084 | Note that when @option{eval} is set to @samp{once} only the | |
2085 | @var{sample_rate} and @var{tb} variables are available, all other | |
2086 | variables will evaluate to NAN. | |
2087 | ||
2088 | @subsection Commands | |
2089 | ||
2090 | This filter supports the following commands: | |
2091 | @table @option | |
2092 | @item volume | |
2093 | Modify the volume expression. | |
2094 | The command accepts the same syntax of the corresponding option. | |
2095 | ||
2096 | If the specified expression is not valid, it is kept at its current | |
2097 | value. | |
2098 | @item replaygain_noclip | |
2099 | Prevent clipping by limiting the gain applied. | |
2100 | ||
2101 | Default value for @var{replaygain_noclip} is 1. | |
2102 | ||
2103 | @end table | |
2104 | ||
2105 | @subsection Examples | |
2106 | ||
2107 | @itemize | |
2108 | @item | |
2109 | Halve the input audio volume: | |
2110 | @example | |
2111 | volume=volume=0.5 | |
2112 | volume=volume=1/2 | |
2113 | volume=volume=-6.0206dB | |
2114 | @end example | |
2115 | ||
2116 | In all the above example the named key for @option{volume} can be | |
2117 | omitted, for example like in: | |
2118 | @example | |
2119 | volume=0.5 | |
2120 | @end example | |
2121 | ||
2122 | @item | |
2123 | Increase input audio power by 6 decibels using fixed-point precision: | |
2124 | @example | |
2125 | volume=volume=6dB:precision=fixed | |
2126 | @end example | |
2127 | ||
2128 | @item | |
2129 | Fade volume after time 10 with an annihilation period of 5 seconds: | |
2130 | @example | |
2131 | volume='if(lt(t,10),1,max(1-(t-10)/5,0))':eval=frame | |
2132 | @end example | |
2133 | @end itemize | |
2134 | ||
2135 | @section volumedetect | |
2136 | ||
2137 | Detect the volume of the input video. | |
2138 | ||
2139 | The filter has no parameters. The input is not modified. Statistics about | |
2140 | the volume will be printed in the log when the input stream end is reached. | |
2141 | ||
2142 | In particular it will show the mean volume (root mean square), maximum | |
2143 | volume (on a per-sample basis), and the beginning of a histogram of the | |
2144 | registered volume values (from the maximum value to a cumulated 1/1000 of | |
2145 | the samples). | |
2146 | ||
2147 | All volumes are in decibels relative to the maximum PCM value. | |
2148 | ||
2149 | @subsection Examples | |
2150 | ||
2151 | Here is an excerpt of the output: | |
2152 | @example | |
2153 | [Parsed_volumedetect_0 @ 0xa23120] mean_volume: -27 dB | |
2154 | [Parsed_volumedetect_0 @ 0xa23120] max_volume: -4 dB | |
2155 | [Parsed_volumedetect_0 @ 0xa23120] histogram_4db: 6 | |
2156 | [Parsed_volumedetect_0 @ 0xa23120] histogram_5db: 62 | |
2157 | [Parsed_volumedetect_0 @ 0xa23120] histogram_6db: 286 | |
2158 | [Parsed_volumedetect_0 @ 0xa23120] histogram_7db: 1042 | |
2159 | [Parsed_volumedetect_0 @ 0xa23120] histogram_8db: 2551 | |
2160 | [Parsed_volumedetect_0 @ 0xa23120] histogram_9db: 4609 | |
2161 | [Parsed_volumedetect_0 @ 0xa23120] histogram_10db: 8409 | |
2162 | @end example | |
2163 | ||
2164 | It means that: | |
2165 | @itemize | |
2166 | @item | |
2167 | The mean square energy is approximately -27 dB, or 10^-2.7. | |
2168 | @item | |
2169 | The largest sample is at -4 dB, or more precisely between -4 dB and -5 dB. | |
2170 | @item | |
2171 | There are 6 samples at -4 dB, 62 at -5 dB, 286 at -6 dB, etc. | |
2172 | @end itemize | |
2173 | ||
2174 | In other words, raising the volume by +4 dB does not cause any clipping, | |
2175 | raising it by +5 dB causes clipping for 6 samples, etc. | |
2176 | ||
2177 | @c man end AUDIO FILTERS | |
2178 | ||
2179 | @chapter Audio Sources | |
2180 | @c man begin AUDIO SOURCES | |
2181 | ||
2182 | Below is a description of the currently available audio sources. | |
2183 | ||
2184 | @section abuffer | |
2185 | ||
2186 | Buffer audio frames, and make them available to the filter chain. | |
2187 | ||
2188 | This source is mainly intended for a programmatic use, in particular | |
2189 | through the interface defined in @file{libavfilter/asrc_abuffer.h}. | |
2190 | ||
2191 | It accepts the following parameters: | |
2192 | @table @option | |
2193 | ||
2194 | @item time_base | |
2195 | The timebase which will be used for timestamps of submitted frames. It must be | |
2196 | either a floating-point number or in @var{numerator}/@var{denominator} form. | |
2197 | ||
2198 | @item sample_rate | |
2199 | The sample rate of the incoming audio buffers. | |
2200 | ||
2201 | @item sample_fmt | |
2202 | The sample format of the incoming audio buffers. | |
2203 | Either a sample format name or its corresponging integer representation from | |
2204 | the enum AVSampleFormat in @file{libavutil/samplefmt.h} | |
2205 | ||
2206 | @item channel_layout | |
2207 | The channel layout of the incoming audio buffers. | |
2208 | Either a channel layout name from channel_layout_map in | |
2209 | @file{libavutil/channel_layout.c} or its corresponding integer representation | |
2210 | from the AV_CH_LAYOUT_* macros in @file{libavutil/channel_layout.h} | |
2211 | ||
2212 | @item channels | |
2213 | The number of channels of the incoming audio buffers. | |
2214 | If both @var{channels} and @var{channel_layout} are specified, then they | |
2215 | must be consistent. | |
2216 | ||
2217 | @end table | |
2218 | ||
2219 | @subsection Examples | |
2220 | ||
2221 | @example | |
2222 | abuffer=sample_rate=44100:sample_fmt=s16p:channel_layout=stereo | |
2223 | @end example | |
2224 | ||
2225 | will instruct the source to accept planar 16bit signed stereo at 44100Hz. | |
2226 | Since the sample format with name "s16p" corresponds to the number | |
2227 | 6 and the "stereo" channel layout corresponds to the value 0x3, this is | |
2228 | equivalent to: | |
2229 | @example | |
2230 | abuffer=sample_rate=44100:sample_fmt=6:channel_layout=0x3 | |
2231 | @end example | |
2232 | ||
2233 | @section aevalsrc | |
2234 | ||
2235 | Generate an audio signal specified by an expression. | |
2236 | ||
2237 | This source accepts in input one or more expressions (one for each | |
2238 | channel), which are evaluated and used to generate a corresponding | |
2239 | audio signal. | |
2240 | ||
2241 | This source accepts the following options: | |
2242 | ||
2243 | @table @option | |
2244 | @item exprs | |
2245 | Set the '|'-separated expressions list for each separate channel. In case the | |
2246 | @option{channel_layout} option is not specified, the selected channel layout | |
2247 | depends on the number of provided expressions. Otherwise the last | |
2248 | specified expression is applied to the remaining output channels. | |
2249 | ||
2250 | @item channel_layout, c | |
2251 | Set the channel layout. The number of channels in the specified layout | |
2252 | must be equal to the number of specified expressions. | |
2253 | ||
2254 | @item duration, d | |
2255 | Set the minimum duration of the sourced audio. See | |
2256 | @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils} | |
2257 | for the accepted syntax. | |
2258 | Note that the resulting duration may be greater than the specified | |
2259 | duration, as the generated audio is always cut at the end of a | |
2260 | complete frame. | |
2261 | ||
2262 | If not specified, or the expressed duration is negative, the audio is | |
2263 | supposed to be generated forever. | |
2264 | ||
2265 | @item nb_samples, n | |
2266 | Set the number of samples per channel per each output frame, | |
2267 | default to 1024. | |
2268 | ||
2269 | @item sample_rate, s | |
2270 | Specify the sample rate, default to 44100. | |
2271 | @end table | |
2272 | ||
2273 | Each expression in @var{exprs} can contain the following constants: | |
2274 | ||
2275 | @table @option | |
2276 | @item n | |
2277 | number of the evaluated sample, starting from 0 | |
2278 | ||
2279 | @item t | |
2280 | time of the evaluated sample expressed in seconds, starting from 0 | |
2281 | ||
2282 | @item s | |
2283 | sample rate | |
2284 | ||
2285 | @end table | |
2286 | ||
2287 | @subsection Examples | |
2288 | ||
2289 | @itemize | |
2290 | @item | |
2291 | Generate silence: | |
2292 | @example | |
2293 | aevalsrc=0 | |
2294 | @end example | |
2295 | ||
2296 | @item | |
2297 | Generate a sin signal with frequency of 440 Hz, set sample rate to | |
2298 | 8000 Hz: | |
2299 | @example | |
2300 | aevalsrc="sin(440*2*PI*t):s=8000" | |
2301 | @end example | |
2302 | ||
2303 | @item | |
2304 | Generate a two channels signal, specify the channel layout (Front | |
2305 | Center + Back Center) explicitly: | |
2306 | @example | |
2307 | aevalsrc="sin(420*2*PI*t)|cos(430*2*PI*t):c=FC|BC" | |
2308 | @end example | |
2309 | ||
2310 | @item | |
2311 | Generate white noise: | |
2312 | @example | |
2313 | aevalsrc="-2+random(0)" | |
2314 | @end example | |
2315 | ||
2316 | @item | |
2317 | Generate an amplitude modulated signal: | |
2318 | @example | |
2319 | aevalsrc="sin(10*2*PI*t)*sin(880*2*PI*t)" | |
2320 | @end example | |
2321 | ||
2322 | @item | |
2323 | Generate 2.5 Hz binaural beats on a 360 Hz carrier: | |
2324 | @example | |
2325 | aevalsrc="0.1*sin(2*PI*(360-2.5/2)*t) | 0.1*sin(2*PI*(360+2.5/2)*t)" | |
2326 | @end example | |
2327 | ||
2328 | @end itemize | |
2329 | ||
2330 | @section anullsrc | |
2331 | ||
2332 | The null audio source, return unprocessed audio frames. It is mainly useful | |
2333 | as a template and to be employed in analysis / debugging tools, or as | |
2334 | the source for filters which ignore the input data (for example the sox | |
2335 | synth filter). | |
2336 | ||
2337 | This source accepts the following options: | |
2338 | ||
2339 | @table @option | |
2340 | ||
2341 | @item channel_layout, cl | |
2342 | ||
2343 | Specifies the channel layout, and can be either an integer or a string | |
2344 | representing a channel layout. The default value of @var{channel_layout} | |
2345 | is "stereo". | |
2346 | ||
2347 | Check the channel_layout_map definition in | |
2348 | @file{libavutil/channel_layout.c} for the mapping between strings and | |
2349 | channel layout values. | |
2350 | ||
2351 | @item sample_rate, r | |
2352 | Specifies the sample rate, and defaults to 44100. | |
2353 | ||
2354 | @item nb_samples, n | |
2355 | Set the number of samples per requested frames. | |
2356 | ||
2357 | @end table | |
2358 | ||
2359 | @subsection Examples | |
2360 | ||
2361 | @itemize | |
2362 | @item | |
2363 | Set the sample rate to 48000 Hz and the channel layout to AV_CH_LAYOUT_MONO. | |
2364 | @example | |
2365 | anullsrc=r=48000:cl=4 | |
2366 | @end example | |
2367 | ||
2368 | @item | |
2369 | Do the same operation with a more obvious syntax: | |
2370 | @example | |
2371 | anullsrc=r=48000:cl=mono | |
2372 | @end example | |
2373 | @end itemize | |
2374 | ||
2375 | All the parameters need to be explicitly defined. | |
2376 | ||
2377 | @section flite | |
2378 | ||
2379 | Synthesize a voice utterance using the libflite library. | |
2380 | ||
2381 | To enable compilation of this filter you need to configure FFmpeg with | |
2382 | @code{--enable-libflite}. | |
2383 | ||
2384 | Note that the flite library is not thread-safe. | |
2385 | ||
2386 | The filter accepts the following options: | |
2387 | ||
2388 | @table @option | |
2389 | ||
2390 | @item list_voices | |
2391 | If set to 1, list the names of the available voices and exit | |
2392 | immediately. Default value is 0. | |
2393 | ||
2394 | @item nb_samples, n | |
2395 | Set the maximum number of samples per frame. Default value is 512. | |
2396 | ||
2397 | @item textfile | |
2398 | Set the filename containing the text to speak. | |
2399 | ||
2400 | @item text | |
2401 | Set the text to speak. | |
2402 | ||
2403 | @item voice, v | |
2404 | Set the voice to use for the speech synthesis. Default value is | |
2405 | @code{kal}. See also the @var{list_voices} option. | |
2406 | @end table | |
2407 | ||
2408 | @subsection Examples | |
2409 | ||
2410 | @itemize | |
2411 | @item | |
2412 | Read from file @file{speech.txt}, and synthetize the text using the | |
2413 | standard flite voice: | |
2414 | @example | |
2415 | flite=textfile=speech.txt | |
2416 | @end example | |
2417 | ||
2418 | @item | |
2419 | Read the specified text selecting the @code{slt} voice: | |
2420 | @example | |
2421 | flite=text='So fare thee well, poor devil of a Sub-Sub, whose commentator I am':voice=slt | |
2422 | @end example | |
2423 | ||
2424 | @item | |
2425 | Input text to ffmpeg: | |
2426 | @example | |
2427 | ffmpeg -f lavfi -i flite=text='So fare thee well, poor devil of a Sub-Sub, whose commentator I am':voice=slt | |
2428 | @end example | |
2429 | ||
2430 | @item | |
2431 | Make @file{ffplay} speak the specified text, using @code{flite} and | |
2432 | the @code{lavfi} device: | |
2433 | @example | |
2434 | ffplay -f lavfi flite=text='No more be grieved for which that thou hast done.' | |
2435 | @end example | |
2436 | @end itemize | |
2437 | ||
2438 | For more information about libflite, check: | |
2439 | @url{http://www.speech.cs.cmu.edu/flite/} | |
2440 | ||
2441 | @section sine | |
2442 | ||
2443 | Generate an audio signal made of a sine wave with amplitude 1/8. | |
2444 | ||
2445 | The audio signal is bit-exact. | |
2446 | ||
2447 | The filter accepts the following options: | |
2448 | ||
2449 | @table @option | |
2450 | ||
2451 | @item frequency, f | |
2452 | Set the carrier frequency. Default is 440 Hz. | |
2453 | ||
2454 | @item beep_factor, b | |
2455 | Enable a periodic beep every second with frequency @var{beep_factor} times | |
2456 | the carrier frequency. Default is 0, meaning the beep is disabled. | |
2457 | ||
2458 | @item sample_rate, r | |
2459 | Specify the sample rate, default is 44100. | |
2460 | ||
2461 | @item duration, d | |
2462 | Specify the duration of the generated audio stream. | |
2463 | ||
2464 | @item samples_per_frame | |
2465 | Set the number of samples per output frame, default is 1024. | |
2466 | @end table | |
2467 | ||
2468 | @subsection Examples | |
2469 | ||
2470 | @itemize | |
2471 | ||
2472 | @item | |
2473 | Generate a simple 440 Hz sine wave: | |
2474 | @example | |
2475 | sine | |
2476 | @end example | |
2477 | ||
2478 | @item | |
2479 | Generate a 220 Hz sine wave with a 880 Hz beep each second, for 5 seconds: | |
2480 | @example | |
2481 | sine=220:4:d=5 | |
2482 | sine=f=220:b=4:d=5 | |
2483 | sine=frequency=220:beep_factor=4:duration=5 | |
2484 | @end example | |
2485 | ||
2486 | @end itemize | |
2487 | ||
2488 | @c man end AUDIO SOURCES | |
2489 | ||
2490 | @chapter Audio Sinks | |
2491 | @c man begin AUDIO SINKS | |
2492 | ||
2493 | Below is a description of the currently available audio sinks. | |
2494 | ||
2495 | @section abuffersink | |
2496 | ||
2497 | Buffer audio frames, and make them available to the end of filter chain. | |
2498 | ||
2499 | This sink is mainly intended for programmatic use, in particular | |
2500 | through the interface defined in @file{libavfilter/buffersink.h} | |
2501 | or the options system. | |
2502 | ||
2503 | It accepts a pointer to an AVABufferSinkContext structure, which | |
2504 | defines the incoming buffers' formats, to be passed as the opaque | |
2505 | parameter to @code{avfilter_init_filter} for initialization. | |
2506 | @section anullsink | |
2507 | ||
2508 | Null audio sink; do absolutely nothing with the input audio. It is | |
2509 | mainly useful as a template and for use in analysis / debugging | |
2510 | tools. | |
2511 | ||
2512 | @c man end AUDIO SINKS | |
2513 | ||
2514 | @chapter Video Filters | |
2515 | @c man begin VIDEO FILTERS | |
2516 | ||
2517 | When you configure your FFmpeg build, you can disable any of the | |
2518 | existing filters using @code{--disable-filters}. | |
2519 | The configure output will show the video filters included in your | |
2520 | build. | |
2521 | ||
2522 | Below is a description of the currently available video filters. | |
2523 | ||
2524 | @section alphaextract | |
2525 | ||
2526 | Extract the alpha component from the input as a grayscale video. This | |
2527 | is especially useful with the @var{alphamerge} filter. | |
2528 | ||
2529 | @section alphamerge | |
2530 | ||
2531 | Add or replace the alpha component of the primary input with the | |
2532 | grayscale value of a second input. This is intended for use with | |
2533 | @var{alphaextract} to allow the transmission or storage of frame | |
2534 | sequences that have alpha in a format that doesn't support an alpha | |
2535 | channel. | |
2536 | ||
2537 | For example, to reconstruct full frames from a normal YUV-encoded video | |
2538 | and a separate video created with @var{alphaextract}, you might use: | |
2539 | @example | |
2540 | movie=in_alpha.mkv [alpha]; [in][alpha] alphamerge [out] | |
2541 | @end example | |
2542 | ||
2543 | Since this filter is designed for reconstruction, it operates on frame | |
2544 | sequences without considering timestamps, and terminates when either | |
2545 | input reaches end of stream. This will cause problems if your encoding | |
2546 | pipeline drops frames. If you're trying to apply an image as an | |
2547 | overlay to a video stream, consider the @var{overlay} filter instead. | |
2548 | ||
2549 | @section ass | |
2550 | ||
2551 | Same as the @ref{subtitles} filter, except that it doesn't require libavcodec | |
2552 | and libavformat to work. On the other hand, it is limited to ASS (Advanced | |
2553 | Substation Alpha) subtitles files. | |
2554 | ||
2555 | @section bbox | |
2556 | ||
2557 | Compute the bounding box for the non-black pixels in the input frame | |
2558 | luminance plane. | |
2559 | ||
2560 | This filter computes the bounding box containing all the pixels with a | |
2561 | luminance value greater than the minimum allowed value. | |
2562 | The parameters describing the bounding box are printed on the filter | |
2563 | log. | |
2564 | ||
2565 | The filter accepts the following option: | |
2566 | ||
2567 | @table @option | |
2568 | @item min_val | |
2569 | Set the minimal luminance value. Default is @code{16}. | |
2570 | @end table | |
2571 | ||
2572 | @section blackdetect | |
2573 | ||
2574 | Detect video intervals that are (almost) completely black. Can be | |
2575 | useful to detect chapter transitions, commercials, or invalid | |
2576 | recordings. Output lines contains the time for the start, end and | |
2577 | duration of the detected black interval expressed in seconds. | |
2578 | ||
2579 | In order to display the output lines, you need to set the loglevel at | |
2580 | least to the AV_LOG_INFO value. | |
2581 | ||
2582 | The filter accepts the following options: | |
2583 | ||
2584 | @table @option | |
2585 | @item black_min_duration, d | |
2586 | Set the minimum detected black duration expressed in seconds. It must | |
2587 | be a non-negative floating point number. | |
2588 | ||
2589 | Default value is 2.0. | |
2590 | ||
2591 | @item picture_black_ratio_th, pic_th | |
2592 | Set the threshold for considering a picture "black". | |
2593 | Express the minimum value for the ratio: | |
2594 | @example | |
2595 | @var{nb_black_pixels} / @var{nb_pixels} | |
2596 | @end example | |
2597 | ||
2598 | for which a picture is considered black. | |
2599 | Default value is 0.98. | |
2600 | ||
2601 | @item pixel_black_th, pix_th | |
2602 | Set the threshold for considering a pixel "black". | |
2603 | ||
2604 | The threshold expresses the maximum pixel luminance value for which a | |
2605 | pixel is considered "black". The provided value is scaled according to | |
2606 | the following equation: | |
2607 | @example | |
2608 | @var{absolute_threshold} = @var{luminance_minimum_value} + @var{pixel_black_th} * @var{luminance_range_size} | |
2609 | @end example | |
2610 | ||
2611 | @var{luminance_range_size} and @var{luminance_minimum_value} depend on | |
2612 | the input video format, the range is [0-255] for YUV full-range | |
2613 | formats and [16-235] for YUV non full-range formats. | |
2614 | ||
2615 | Default value is 0.10. | |
2616 | @end table | |
2617 | ||
2618 | The following example sets the maximum pixel threshold to the minimum | |
2619 | value, and detects only black intervals of 2 or more seconds: | |
2620 | @example | |
2621 | blackdetect=d=2:pix_th=0.00 | |
2622 | @end example | |
2623 | ||
2624 | @section blackframe | |
2625 | ||
2626 | Detect frames that are (almost) completely black. Can be useful to | |
2627 | detect chapter transitions or commercials. Output lines consist of | |
2628 | the frame number of the detected frame, the percentage of blackness, | |
2629 | the position in the file if known or -1 and the timestamp in seconds. | |
2630 | ||
2631 | In order to display the output lines, you need to set the loglevel at | |
2632 | least to the AV_LOG_INFO value. | |
2633 | ||
2634 | It accepts the following parameters: | |
2635 | ||
2636 | @table @option | |
2637 | ||
2638 | @item amount | |
2639 | The percentage of the pixels that have to be below the threshold; it defaults to | |
2640 | @code{98}. | |
2641 | ||
2642 | @item threshold, thresh | |
2643 | The threshold below which a pixel value is considered black; it defaults to | |
2644 | @code{32}. | |
2645 | ||
2646 | @end table | |
2647 | ||
2648 | @section blend | |
2649 | ||
2650 | Blend two video frames into each other. | |
2651 | ||
2652 | It takes two input streams and outputs one stream, the first input is the | |
2653 | "top" layer and second input is "bottom" layer. | |
2654 | Output terminates when shortest input terminates. | |
2655 | ||
2656 | A description of the accepted options follows. | |
2657 | ||
2658 | @table @option | |
2659 | @item c0_mode | |
2660 | @item c1_mode | |
2661 | @item c2_mode | |
2662 | @item c3_mode | |
2663 | @item all_mode | |
2664 | Set blend mode for specific pixel component or all pixel components in case | |
2665 | of @var{all_mode}. Default value is @code{normal}. | |
2666 | ||
2667 | Available values for component modes are: | |
2668 | @table @samp | |
2669 | @item addition | |
2670 | @item and | |
2671 | @item average | |
2672 | @item burn | |
2673 | @item darken | |
2674 | @item difference | |
2675 | @item divide | |
2676 | @item dodge | |
2677 | @item exclusion | |
2678 | @item hardlight | |
2679 | @item lighten | |
2680 | @item multiply | |
2681 | @item negation | |
2682 | @item normal | |
2683 | @item or | |
2684 | @item overlay | |
2685 | @item phoenix | |
2686 | @item pinlight | |
2687 | @item reflect | |
2688 | @item screen | |
2689 | @item softlight | |
2690 | @item subtract | |
2691 | @item vividlight | |
2692 | @item xor | |
2693 | @end table | |
2694 | ||
2695 | @item c0_opacity | |
2696 | @item c1_opacity | |
2697 | @item c2_opacity | |
2698 | @item c3_opacity | |
2699 | @item all_opacity | |
2700 | Set blend opacity for specific pixel component or all pixel components in case | |
2701 | of @var{all_opacity}. Only used in combination with pixel component blend modes. | |
2702 | ||
2703 | @item c0_expr | |
2704 | @item c1_expr | |
2705 | @item c2_expr | |
2706 | @item c3_expr | |
2707 | @item all_expr | |
2708 | Set blend expression for specific pixel component or all pixel components in case | |
2709 | of @var{all_expr}. Note that related mode options will be ignored if those are set. | |
2710 | ||
2711 | The expressions can use the following variables: | |
2712 | ||
2713 | @table @option | |
2714 | @item N | |
2715 | The sequential number of the filtered frame, starting from @code{0}. | |
2716 | ||
2717 | @item X | |
2718 | @item Y | |
2719 | the coordinates of the current sample | |
2720 | ||
2721 | @item W | |
2722 | @item H | |
2723 | the width and height of currently filtered plane | |
2724 | ||
2725 | @item SW | |
2726 | @item SH | |
2727 | Width and height scale depending on the currently filtered plane. It is the | |
2728 | ratio between the corresponding luma plane number of pixels and the current | |
2729 | plane ones. E.g. for YUV4:2:0 the values are @code{1,1} for the luma plane, and | |
2730 | @code{0.5,0.5} for chroma planes. | |
2731 | ||
2732 | @item T | |
2733 | Time of the current frame, expressed in seconds. | |
2734 | ||
2735 | @item TOP, A | |
2736 | Value of pixel component at current location for first video frame (top layer). | |
2737 | ||
2738 | @item BOTTOM, B | |
2739 | Value of pixel component at current location for second video frame (bottom layer). | |
2740 | @end table | |
2741 | ||
2742 | @item shortest | |
2743 | Force termination when the shortest input terminates. Default is @code{0}. | |
2744 | @item repeatlast | |
2745 | Continue applying the last bottom frame after the end of the stream. A value of | |
2746 | @code{0} disable the filter after the last frame of the bottom layer is reached. | |
2747 | Default is @code{1}. | |
2748 | @end table | |
2749 | ||
2750 | @subsection Examples | |
2751 | ||
2752 | @itemize | |
2753 | @item | |
2754 | Apply transition from bottom layer to top layer in first 10 seconds: | |
2755 | @example | |
2756 | blend=all_expr='A*(if(gte(T,10),1,T/10))+B*(1-(if(gte(T,10),1,T/10)))' | |
2757 | @end example | |
2758 | ||
2759 | @item | |
2760 | Apply 1x1 checkerboard effect: | |
2761 | @example | |
2762 | blend=all_expr='if(eq(mod(X,2),mod(Y,2)),A,B)' | |
2763 | @end example | |
2764 | ||
2765 | @item | |
2766 | Apply uncover left effect: | |
2767 | @example | |
2768 | blend=all_expr='if(gte(N*SW+X,W),A,B)' | |
2769 | @end example | |
2770 | ||
2771 | @item | |
2772 | Apply uncover down effect: | |
2773 | @example | |
2774 | blend=all_expr='if(gte(Y-N*SH,0),A,B)' | |
2775 | @end example | |
2776 | ||
2777 | @item | |
2778 | Apply uncover up-left effect: | |
2779 | @example | |
2780 | blend=all_expr='if(gte(T*SH*40+Y,H)*gte((T*40*SW+X)*W/H,W),A,B)' | |
2781 | @end example | |
2782 | @end itemize | |
2783 | ||
2784 | @section boxblur | |
2785 | ||
2786 | Apply a boxblur algorithm to the input video. | |
2787 | ||
2788 | It accepts the following parameters: | |
2789 | ||
2790 | @table @option | |
2791 | ||
2792 | @item luma_radius, lr | |
2793 | @item luma_power, lp | |
2794 | @item chroma_radius, cr | |
2795 | @item chroma_power, cp | |
2796 | @item alpha_radius, ar | |
2797 | @item alpha_power, ap | |
2798 | ||
2799 | @end table | |
2800 | ||
2801 | A description of the accepted options follows. | |
2802 | ||
2803 | @table @option | |
2804 | @item luma_radius, lr | |
2805 | @item chroma_radius, cr | |
2806 | @item alpha_radius, ar | |
2807 | Set an expression for the box radius in pixels used for blurring the | |
2808 | corresponding input plane. | |
2809 | ||
2810 | The radius value must be a non-negative number, and must not be | |
2811 | greater than the value of the expression @code{min(w,h)/2} for the | |
2812 | luma and alpha planes, and of @code{min(cw,ch)/2} for the chroma | |
2813 | planes. | |
2814 | ||
2815 | Default value for @option{luma_radius} is "2". If not specified, | |
2816 | @option{chroma_radius} and @option{alpha_radius} default to the | |
2817 | corresponding value set for @option{luma_radius}. | |
2818 | ||
2819 | The expressions can contain the following constants: | |
2820 | @table @option | |
2821 | @item w | |
2822 | @item h | |
2823 | The input width and height in pixels. | |
2824 | ||
2825 | @item cw | |
2826 | @item ch | |
2827 | The input chroma image width and height in pixels. | |
2828 | ||
2829 | @item hsub | |
2830 | @item vsub | |
2831 | The horizontal and vertical chroma subsample values. For example, for the | |
2832 | pixel format "yuv422p", @var{hsub} is 2 and @var{vsub} is 1. | |
2833 | @end table | |
2834 | ||
2835 | @item luma_power, lp | |
2836 | @item chroma_power, cp | |
2837 | @item alpha_power, ap | |
2838 | Specify how many times the boxblur filter is applied to the | |
2839 | corresponding plane. | |
2840 | ||
2841 | Default value for @option{luma_power} is 2. If not specified, | |
2842 | @option{chroma_power} and @option{alpha_power} default to the | |
2843 | corresponding value set for @option{luma_power}. | |
2844 | ||
2845 | A value of 0 will disable the effect. | |
2846 | @end table | |
2847 | ||
2848 | @subsection Examples | |
2849 | ||
2850 | @itemize | |
2851 | @item | |
2852 | Apply a boxblur filter with the luma, chroma, and alpha radii | |
2853 | set to 2: | |
2854 | @example | |
2855 | boxblur=luma_radius=2:luma_power=1 | |
2856 | boxblur=2:1 | |
2857 | @end example | |
2858 | ||
2859 | @item | |
2860 | Set the luma radius to 2, and alpha and chroma radius to 0: | |
2861 | @example | |
2862 | boxblur=2:1:cr=0:ar=0 | |
2863 | @end example | |
2864 | ||
2865 | @item | |
2866 | Set the luma and chroma radii to a fraction of the video dimension: | |
2867 | @example | |
2868 | boxblur=luma_radius=min(h\,w)/10:luma_power=1:chroma_radius=min(cw\,ch)/10:chroma_power=1 | |
2869 | @end example | |
2870 | @end itemize | |
2871 | ||
2872 | @section codecview | |
2873 | ||
2874 | Visualize information exported by some codecs. | |
2875 | ||
2876 | Some codecs can export information through frames using side-data or other | |
2877 | means. For example, some MPEG based codecs export motion vectors through the | |
2878 | @var{export_mvs} flag in the codec @option{flags2} option. | |
2879 | ||
2880 | The filter accepts the following option: | |
2881 | ||
2882 | @table @option | |
2883 | @item mv | |
2884 | Set motion vectors to visualize. | |
2885 | ||
2886 | Available flags for @var{mv} are: | |
2887 | ||
2888 | @table @samp | |
2889 | @item pf | |
2890 | forward predicted MVs of P-frames | |
2891 | @item bf | |
2892 | forward predicted MVs of B-frames | |
2893 | @item bb | |
2894 | backward predicted MVs of B-frames | |
2895 | @end table | |
2896 | @end table | |
2897 | ||
2898 | @subsection Examples | |
2899 | ||
2900 | @itemize | |
2901 | @item | |
2902 | Visualizes multi-directionals MVs from P and B-Frames using @command{ffplay}: | |
2903 | @example | |
2904 | ffplay -flags2 +export_mvs input.mpg -vf codecview=mv=pf+bf+bb | |
2905 | @end example | |
2906 | @end itemize | |
2907 | ||
2908 | @section colorbalance | |
2909 | Modify intensity of primary colors (red, green and blue) of input frames. | |
2910 | ||
2911 | The filter allows an input frame to be adjusted in the shadows, midtones or highlights | |
2912 | regions for the red-cyan, green-magenta or blue-yellow balance. | |
2913 | ||
2914 | A positive adjustment value shifts the balance towards the primary color, a negative | |
2915 | value towards the complementary color. | |
2916 | ||
2917 | The filter accepts the following options: | |
2918 | ||
2919 | @table @option | |
2920 | @item rs | |
2921 | @item gs | |
2922 | @item bs | |
2923 | Adjust red, green and blue shadows (darkest pixels). | |
2924 | ||
2925 | @item rm | |
2926 | @item gm | |
2927 | @item bm | |
2928 | Adjust red, green and blue midtones (medium pixels). | |
2929 | ||
2930 | @item rh | |
2931 | @item gh | |
2932 | @item bh | |
2933 | Adjust red, green and blue highlights (brightest pixels). | |
2934 | ||
2935 | Allowed ranges for options are @code{[-1.0, 1.0]}. Defaults are @code{0}. | |
2936 | @end table | |
2937 | ||
2938 | @subsection Examples | |
2939 | ||
2940 | @itemize | |
2941 | @item | |
2942 | Add red color cast to shadows: | |
2943 | @example | |
2944 | colorbalance=rs=.3 | |
2945 | @end example | |
2946 | @end itemize | |
2947 | ||
2948 | @section colorchannelmixer | |
2949 | ||
2950 | Adjust video input frames by re-mixing color channels. | |
2951 | ||
2952 | This filter modifies a color channel by adding the values associated to | |
2953 | the other channels of the same pixels. For example if the value to | |
2954 | modify is red, the output value will be: | |
2955 | @example | |
2956 | @var{red}=@var{red}*@var{rr} + @var{blue}*@var{rb} + @var{green}*@var{rg} + @var{alpha}*@var{ra} | |
2957 | @end example | |
2958 | ||
2959 | The filter accepts the following options: | |
2960 | ||
2961 | @table @option | |
2962 | @item rr | |
2963 | @item rg | |
2964 | @item rb | |
2965 | @item ra | |
2966 | Adjust contribution of input red, green, blue and alpha channels for output red channel. | |
2967 | Default is @code{1} for @var{rr}, and @code{0} for @var{rg}, @var{rb} and @var{ra}. | |
2968 | ||
2969 | @item gr | |
2970 | @item gg | |
2971 | @item gb | |
2972 | @item ga | |
2973 | Adjust contribution of input red, green, blue and alpha channels for output green channel. | |
2974 | Default is @code{1} for @var{gg}, and @code{0} for @var{gr}, @var{gb} and @var{ga}. | |
2975 | ||
2976 | @item br | |
2977 | @item bg | |
2978 | @item bb | |
2979 | @item ba | |
2980 | Adjust contribution of input red, green, blue and alpha channels for output blue channel. | |
2981 | Default is @code{1} for @var{bb}, and @code{0} for @var{br}, @var{bg} and @var{ba}. | |
2982 | ||
2983 | @item ar | |
2984 | @item ag | |
2985 | @item ab | |
2986 | @item aa | |
2987 | Adjust contribution of input red, green, blue and alpha channels for output alpha channel. | |
2988 | Default is @code{1} for @var{aa}, and @code{0} for @var{ar}, @var{ag} and @var{ab}. | |
2989 | ||
2990 | Allowed ranges for options are @code{[-2.0, 2.0]}. | |
2991 | @end table | |
2992 | ||
2993 | @subsection Examples | |
2994 | ||
2995 | @itemize | |
2996 | @item | |
2997 | Convert source to grayscale: | |
2998 | @example | |
2999 | colorchannelmixer=.3:.4:.3:0:.3:.4:.3:0:.3:.4:.3 | |
3000 | @end example | |
3001 | @item | |
3002 | Simulate sepia tones: | |
3003 | @example | |
3004 | colorchannelmixer=.393:.769:.189:0:.349:.686:.168:0:.272:.534:.131 | |
3005 | @end example | |
3006 | @end itemize | |
3007 | ||
3008 | @section colormatrix | |
3009 | ||
3010 | Convert color matrix. | |
3011 | ||
3012 | The filter accepts the following options: | |
3013 | ||
3014 | @table @option | |
3015 | @item src | |
3016 | @item dst | |
3017 | Specify the source and destination color matrix. Both values must be | |
3018 | specified. | |
3019 | ||
3020 | The accepted values are: | |
3021 | @table @samp | |
3022 | @item bt709 | |
3023 | BT.709 | |
3024 | ||
3025 | @item bt601 | |
3026 | BT.601 | |
3027 | ||
3028 | @item smpte240m | |
3029 | SMPTE-240M | |
3030 | ||
3031 | @item fcc | |
3032 | FCC | |
3033 | @end table | |
3034 | @end table | |
3035 | ||
3036 | For example to convert from BT.601 to SMPTE-240M, use the command: | |
3037 | @example | |
3038 | colormatrix=bt601:smpte240m | |
3039 | @end example | |
3040 | ||
3041 | @section copy | |
3042 | ||
3043 | Copy the input source unchanged to the output. This is mainly useful for | |
3044 | testing purposes. | |
3045 | ||
3046 | @section crop | |
3047 | ||
3048 | Crop the input video to given dimensions. | |
3049 | ||
3050 | It accepts the following parameters: | |
3051 | ||
3052 | @table @option | |
3053 | @item w, out_w | |
3054 | The width of the output video. It defaults to @code{iw}. | |
3055 | This expression is evaluated only once during the filter | |
3056 | configuration. | |
3057 | ||
3058 | @item h, out_h | |
3059 | The height of the output video. It defaults to @code{ih}. | |
3060 | This expression is evaluated only once during the filter | |
3061 | configuration. | |
3062 | ||
3063 | @item x | |
3064 | The horizontal position, in the input video, of the left edge of the output | |
3065 | video. It defaults to @code{(in_w-out_w)/2}. | |
3066 | This expression is evaluated per-frame. | |
3067 | ||
3068 | @item y | |
3069 | The vertical position, in the input video, of the top edge of the output video. | |
3070 | It defaults to @code{(in_h-out_h)/2}. | |
3071 | This expression is evaluated per-frame. | |
3072 | ||
3073 | @item keep_aspect | |
3074 | If set to 1 will force the output display aspect ratio | |
3075 | to be the same of the input, by changing the output sample aspect | |
3076 | ratio. It defaults to 0. | |
3077 | @end table | |
3078 | ||
3079 | The @var{out_w}, @var{out_h}, @var{x}, @var{y} parameters are | |
3080 | expressions containing the following constants: | |
3081 | ||
3082 | @table @option | |
3083 | @item x | |
3084 | @item y | |
3085 | The computed values for @var{x} and @var{y}. They are evaluated for | |
3086 | each new frame. | |
3087 | ||
3088 | @item in_w | |
3089 | @item in_h | |
3090 | The input width and height. | |
3091 | ||
3092 | @item iw | |
3093 | @item ih | |
3094 | These are the same as @var{in_w} and @var{in_h}. | |
3095 | ||
3096 | @item out_w | |
3097 | @item out_h | |
3098 | The output (cropped) width and height. | |
3099 | ||
3100 | @item ow | |
3101 | @item oh | |
3102 | These are the same as @var{out_w} and @var{out_h}. | |
3103 | ||
3104 | @item a | |
3105 | same as @var{iw} / @var{ih} | |
3106 | ||
3107 | @item sar | |
3108 | input sample aspect ratio | |
3109 | ||
3110 | @item dar | |
3111 | input display aspect ratio, it is the same as (@var{iw} / @var{ih}) * @var{sar} | |
3112 | ||
3113 | @item hsub | |
3114 | @item vsub | |
3115 | horizontal and vertical chroma subsample values. For example for the | |
3116 | pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1. | |
3117 | ||
3118 | @item n | |
3119 | The number of the input frame, starting from 0. | |
3120 | ||
3121 | @item pos | |
3122 | the position in the file of the input frame, NAN if unknown | |
3123 | ||
3124 | @item t | |
3125 | The timestamp expressed in seconds. It's NAN if the input timestamp is unknown. | |
3126 | ||
3127 | @end table | |
3128 | ||
3129 | The expression for @var{out_w} may depend on the value of @var{out_h}, | |
3130 | and the expression for @var{out_h} may depend on @var{out_w}, but they | |
3131 | cannot depend on @var{x} and @var{y}, as @var{x} and @var{y} are | |
3132 | evaluated after @var{out_w} and @var{out_h}. | |
3133 | ||
3134 | The @var{x} and @var{y} parameters specify the expressions for the | |
3135 | position of the top-left corner of the output (non-cropped) area. They | |
3136 | are evaluated for each frame. If the evaluated value is not valid, it | |
3137 | is approximated to the nearest valid value. | |
3138 | ||
3139 | The expression for @var{x} may depend on @var{y}, and the expression | |
3140 | for @var{y} may depend on @var{x}. | |
3141 | ||
3142 | @subsection Examples | |
3143 | ||
3144 | @itemize | |
3145 | @item | |
3146 | Crop area with size 100x100 at position (12,34). | |
3147 | @example | |
3148 | crop=100:100:12:34 | |
3149 | @end example | |
3150 | ||
3151 | Using named options, the example above becomes: | |
3152 | @example | |
3153 | crop=w=100:h=100:x=12:y=34 | |
3154 | @end example | |
3155 | ||
3156 | @item | |
3157 | Crop the central input area with size 100x100: | |
3158 | @example | |
3159 | crop=100:100 | |
3160 | @end example | |
3161 | ||
3162 | @item | |
3163 | Crop the central input area with size 2/3 of the input video: | |
3164 | @example | |
3165 | crop=2/3*in_w:2/3*in_h | |
3166 | @end example | |
3167 | ||
3168 | @item | |
3169 | Crop the input video central square: | |
3170 | @example | |
3171 | crop=out_w=in_h | |
3172 | crop=in_h | |
3173 | @end example | |
3174 | ||
3175 | @item | |
3176 | Delimit the rectangle with the top-left corner placed at position | |
3177 | 100:100 and the right-bottom corner corresponding to the right-bottom | |
3178 | corner of the input image. | |
3179 | @example | |
3180 | crop=in_w-100:in_h-100:100:100 | |
3181 | @end example | |
3182 | ||
3183 | @item | |
3184 | Crop 10 pixels from the left and right borders, and 20 pixels from | |
3185 | the top and bottom borders | |
3186 | @example | |
3187 | crop=in_w-2*10:in_h-2*20 | |
3188 | @end example | |
3189 | ||
3190 | @item | |
3191 | Keep only the bottom right quarter of the input image: | |
3192 | @example | |
3193 | crop=in_w/2:in_h/2:in_w/2:in_h/2 | |
3194 | @end example | |
3195 | ||
3196 | @item | |
3197 | Crop height for getting Greek harmony: | |
3198 | @example | |
3199 | crop=in_w:1/PHI*in_w | |
3200 | @end example | |
3201 | ||
3202 | @item | |
3203 | Appply trembling effect: | |
3204 | @example | |
3205 | 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) | |
3206 | @end example | |
3207 | ||
3208 | @item | |
3209 | Apply erratic camera effect depending on timestamp: | |
3210 | @example | |
3211 | 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)" | |
3212 | @end example | |
3213 | ||
3214 | @item | |
3215 | Set x depending on the value of y: | |
3216 | @example | |
3217 | crop=in_w/2:in_h/2:y:10+10*sin(n/10) | |
3218 | @end example | |
3219 | @end itemize | |
3220 | ||
3221 | @section cropdetect | |
3222 | ||
3223 | Auto-detect the crop size. | |
3224 | ||
3225 | It calculates the necessary cropping parameters and prints the | |
3226 | recommended parameters via the logging system. The detected dimensions | |
3227 | correspond to the non-black area of the input video. | |
3228 | ||
3229 | It accepts the following parameters: | |
3230 | ||
3231 | @table @option | |
3232 | ||
3233 | @item limit | |
3234 | Set higher black value threshold, which can be optionally specified | |
3235 | from nothing (0) to everything (255). An intensity value greater | |
3236 | to the set value is considered non-black. It defaults to 24. | |
3237 | ||
3238 | @item round | |
3239 | The value which the width/height should be divisible by. It defaults to | |
3240 | 16. The offset is automatically adjusted to center the video. Use 2 to | |
3241 | get only even dimensions (needed for 4:2:2 video). 16 is best when | |
3242 | encoding to most video codecs. | |
3243 | ||
3244 | @item reset_count, reset | |
3245 | Set the counter that determines after how many frames cropdetect will | |
3246 | reset the previously detected largest video area and start over to | |
3247 | detect the current optimal crop area. Default value is 0. | |
3248 | ||
3249 | This can be useful when channel logos distort the video area. 0 | |
3250 | indicates 'never reset', and returns the largest area encountered during | |
3251 | playback. | |
3252 | @end table | |
3253 | ||
3254 | @anchor{curves} | |
3255 | @section curves | |
3256 | ||
3257 | Apply color adjustments using curves. | |
3258 | ||
3259 | This filter is similar to the Adobe Photoshop and GIMP curves tools. Each | |
3260 | component (red, green and blue) has its values defined by @var{N} key points | |
3261 | tied from each other using a smooth curve. The x-axis represents the pixel | |
3262 | values from the input frame, and the y-axis the new pixel values to be set for | |
3263 | the output frame. | |
3264 | ||
3265 | By default, a component curve is defined by the two points @var{(0;0)} and | |
3266 | @var{(1;1)}. This creates a straight line where each original pixel value is | |
3267 | "adjusted" to its own value, which means no change to the image. | |
3268 | ||
3269 | The filter allows you to redefine these two points and add some more. A new | |
3270 | curve (using a natural cubic spline interpolation) will be define to pass | |
3271 | smoothly through all these new coordinates. The new defined points needs to be | |
3272 | strictly increasing over the x-axis, and their @var{x} and @var{y} values must | |
3273 | be in the @var{[0;1]} interval. If the computed curves happened to go outside | |
3274 | the vector spaces, the values will be clipped accordingly. | |
3275 | ||
3276 | If there is no key point defined in @code{x=0}, the filter will automatically | |
3277 | insert a @var{(0;0)} point. In the same way, if there is no key point defined | |
3278 | in @code{x=1}, the filter will automatically insert a @var{(1;1)} point. | |
3279 | ||
3280 | The filter accepts the following options: | |
3281 | ||
3282 | @table @option | |
3283 | @item preset | |
3284 | Select one of the available color presets. This option can be used in addition | |
3285 | to the @option{r}, @option{g}, @option{b} parameters; in this case, the later | |
3286 | options takes priority on the preset values. | |
3287 | Available presets are: | |
3288 | @table @samp | |
3289 | @item none | |
3290 | @item color_negative | |
3291 | @item cross_process | |
3292 | @item darker | |
3293 | @item increase_contrast | |
3294 | @item lighter | |
3295 | @item linear_contrast | |
3296 | @item medium_contrast | |
3297 | @item negative | |
3298 | @item strong_contrast | |
3299 | @item vintage | |
3300 | @end table | |
3301 | Default is @code{none}. | |
3302 | @item master, m | |
3303 | Set the master key points. These points will define a second pass mapping. It | |
3304 | is sometimes called a "luminance" or "value" mapping. It can be used with | |
3305 | @option{r}, @option{g}, @option{b} or @option{all} since it acts like a | |
3306 | post-processing LUT. | |
3307 | @item red, r | |
3308 | Set the key points for the red component. | |
3309 | @item green, g | |
3310 | Set the key points for the green component. | |
3311 | @item blue, b | |
3312 | Set the key points for the blue component. | |
3313 | @item all | |
3314 | Set the key points for all components (not including master). | |
3315 | Can be used in addition to the other key points component | |
3316 | options. In this case, the unset component(s) will fallback on this | |
3317 | @option{all} setting. | |
3318 | @item psfile | |
3319 | Specify a Photoshop curves file (@code{.asv}) to import the settings from. | |
3320 | @end table | |
3321 | ||
3322 | To avoid some filtergraph syntax conflicts, each key points list need to be | |
3323 | defined using the following syntax: @code{x0/y0 x1/y1 x2/y2 ...}. | |
3324 | ||
3325 | @subsection Examples | |
3326 | ||
3327 | @itemize | |
3328 | @item | |
3329 | Increase slightly the middle level of blue: | |
3330 | @example | |
3331 | curves=blue='0.5/0.58' | |
3332 | @end example | |
3333 | ||
3334 | @item | |
3335 | Vintage effect: | |
3336 | @example | |
3337 | curves=r='0/0.11 .42/.51 1/0.95':g='0.50/0.48':b='0/0.22 .49/.44 1/0.8' | |
3338 | @end example | |
3339 | Here we obtain the following coordinates for each components: | |
3340 | @table @var | |
3341 | @item red | |
3342 | @code{(0;0.11) (0.42;0.51) (1;0.95)} | |
3343 | @item green | |
3344 | @code{(0;0) (0.50;0.48) (1;1)} | |
3345 | @item blue | |
3346 | @code{(0;0.22) (0.49;0.44) (1;0.80)} | |
3347 | @end table | |
3348 | ||
3349 | @item | |
3350 | The previous example can also be achieved with the associated built-in preset: | |
3351 | @example | |
3352 | curves=preset=vintage | |
3353 | @end example | |
3354 | ||
3355 | @item | |
3356 | Or simply: | |
3357 | @example | |
3358 | curves=vintage | |
3359 | @end example | |
3360 | ||
3361 | @item | |
3362 | Use a Photoshop preset and redefine the points of the green component: | |
3363 | @example | |
3364 | curves=psfile='MyCurvesPresets/purple.asv':green='0.45/0.53' | |
3365 | @end example | |
3366 | @end itemize | |
3367 | ||
3368 | @section dctdnoiz | |
3369 | ||
3370 | Denoise frames using 2D DCT (frequency domain filtering). | |
3371 | ||
3372 | This filter is not designed for real time. | |
3373 | ||
3374 | The filter accepts the following options: | |
3375 | ||
3376 | @table @option | |
3377 | @item sigma, s | |
3378 | Set the noise sigma constant. | |
3379 | ||
3380 | This @var{sigma} defines a hard threshold of @code{3 * sigma}; every DCT | |
3381 | coefficient (absolute value) below this threshold with be dropped. | |
3382 | ||
3383 | If you need a more advanced filtering, see @option{expr}. | |
3384 | ||
3385 | Default is @code{0}. | |
3386 | ||
3387 | @item overlap | |
3388 | Set number overlapping pixels for each block. Since the filter can be slow, you | |
3389 | may want to reduce this value, at the cost of a less effective filter and the | |
3390 | risk of various artefacts. | |
3391 | ||
3392 | If the overlapping value doesn't allow to process the whole input width or | |
3393 | height, a warning will be displayed and according borders won't be denoised. | |
3394 | ||
3395 | Default value is @var{blocksize}-1, which is the best possible setting. | |
3396 | ||
3397 | @item expr, e | |
3398 | Set the coefficient factor expression. | |
3399 | ||
3400 | For each coefficient of a DCT block, this expression will be evaluated as a | |
3401 | multiplier value for the coefficient. | |
3402 | ||
3403 | If this is option is set, the @option{sigma} option will be ignored. | |
3404 | ||
3405 | The absolute value of the coefficient can be accessed through the @var{c} | |
3406 | variable. | |
3407 | ||
3408 | @item n | |
3409 | Set the @var{blocksize} using the number of bits. @code{1<<@var{n}} defines the | |
3410 | @var{blocksize}, which is the width and height of the processed blocks. | |
3411 | ||
3412 | The default value is @var{3} (8x8) and can be raised to @var{4} for a | |
3413 | @var{blocksize} of 16x16. Note that changing this setting has huge consequences | |
3414 | on the speed processing. Also, a larger block size does not necessarily means a | |
3415 | better de-noising. | |
3416 | @end table | |
3417 | ||
3418 | @subsection Examples | |
3419 | ||
3420 | Apply a denoise with a @option{sigma} of @code{4.5}: | |
3421 | @example | |
3422 | dctdnoiz=4.5 | |
3423 | @end example | |
3424 | ||
3425 | The same operation can be achieved using the expression system: | |
3426 | @example | |
3427 | dctdnoiz=e='gte(c, 4.5*3)' | |
3428 | @end example | |
3429 | ||
3430 | Violent denoise using a block size of @code{16x16}: | |
3431 | @example | |
3432 | dctdnoiz=15:n=4 | |
3433 | @end example | |
3434 | ||
3435 | @anchor{decimate} | |
3436 | @section decimate | |
3437 | ||
3438 | Drop duplicated frames at regular intervals. | |
3439 | ||
3440 | The filter accepts the following options: | |
3441 | ||
3442 | @table @option | |
3443 | @item cycle | |
3444 | Set the number of frames from which one will be dropped. Setting this to | |
3445 | @var{N} means one frame in every batch of @var{N} frames will be dropped. | |
3446 | Default is @code{5}. | |
3447 | ||
3448 | @item dupthresh | |
3449 | Set the threshold for duplicate detection. If the difference metric for a frame | |
3450 | is less than or equal to this value, then it is declared as duplicate. Default | |
3451 | is @code{1.1} | |
3452 | ||
3453 | @item scthresh | |
3454 | Set scene change threshold. Default is @code{15}. | |
3455 | ||
3456 | @item blockx | |
3457 | @item blocky | |
3458 | Set the size of the x and y-axis blocks used during metric calculations. | |
3459 | Larger blocks give better noise suppression, but also give worse detection of | |
3460 | small movements. Must be a power of two. Default is @code{32}. | |
3461 | ||
3462 | @item ppsrc | |
3463 | Mark main input as a pre-processed input and activate clean source input | |
3464 | stream. This allows the input to be pre-processed with various filters to help | |
3465 | the metrics calculation while keeping the frame selection lossless. When set to | |
3466 | @code{1}, the first stream is for the pre-processed input, and the second | |
3467 | stream is the clean source from where the kept frames are chosen. Default is | |
3468 | @code{0}. | |
3469 | ||
3470 | @item chroma | |
3471 | Set whether or not chroma is considered in the metric calculations. Default is | |
3472 | @code{1}. | |
3473 | @end table | |
3474 | ||
3475 | @section dejudder | |
3476 | ||
3477 | Remove judder produced by partially interlaced telecined content. | |
3478 | ||
3479 | Judder can be introduced, for instance, by @ref{pullup} filter. If the original | |
3480 | source was partially telecined content then the output of @code{pullup,dejudder} | |
3481 | will have a variable frame rate. May change the recorded frame rate of the | |
3482 | container. Aside from that change, this filter will not affect constant frame | |
3483 | rate video. | |
3484 | ||
3485 | The option available in this filter is: | |
3486 | @table @option | |
3487 | ||
3488 | @item cycle | |
3489 | Specify the length of the window over which the judder repeats. | |
3490 | ||
3491 | Accepts any integer greater than 1. Useful values are: | |
3492 | @table @samp | |
3493 | ||
3494 | @item 4 | |
3495 | If the original was telecined from 24 to 30 fps (Film to NTSC). | |
3496 | ||
3497 | @item 5 | |
3498 | If the original was telecined from 25 to 30 fps (PAL to NTSC). | |
3499 | ||
3500 | @item 20 | |
3501 | If a mixture of the two. | |
3502 | @end table | |
3503 | ||
3504 | The default is @samp{4}. | |
3505 | @end table | |
3506 | ||
3507 | @section delogo | |
3508 | ||
3509 | Suppress a TV station logo by a simple interpolation of the surrounding | |
3510 | pixels. Just set a rectangle covering the logo and watch it disappear | |
3511 | (and sometimes something even uglier appear - your mileage may vary). | |
3512 | ||
3513 | It accepts the following parameters: | |
3514 | @table @option | |
3515 | ||
3516 | @item x | |
3517 | @item y | |
3518 | Specify the top left corner coordinates of the logo. They must be | |
3519 | specified. | |
3520 | ||
3521 | @item w | |
3522 | @item h | |
3523 | Specify the width and height of the logo to clear. They must be | |
3524 | specified. | |
3525 | ||
3526 | @item band, t | |
3527 | Specify the thickness of the fuzzy edge of the rectangle (added to | |
3528 | @var{w} and @var{h}). The default value is 4. | |
3529 | ||
3530 | @item show | |
3531 | When set to 1, a green rectangle is drawn on the screen to simplify | |
3532 | finding the right @var{x}, @var{y}, @var{w}, and @var{h} parameters. | |
3533 | The default value is 0. | |
3534 | ||
3535 | The rectangle is drawn on the outermost pixels which will be (partly) | |
3536 | replaced with interpolated values. The values of the next pixels | |
3537 | immediately outside this rectangle in each direction will be used to | |
3538 | compute the interpolated pixel values inside the rectangle. | |
3539 | ||
3540 | @end table | |
3541 | ||
3542 | @subsection Examples | |
3543 | ||
3544 | @itemize | |
3545 | @item | |
3546 | Set a rectangle covering the area with top left corner coordinates 0,0 | |
3547 | and size 100x77, and a band of size 10: | |
3548 | @example | |
3549 | delogo=x=0:y=0:w=100:h=77:band=10 | |
3550 | @end example | |
3551 | ||
3552 | @end itemize | |
3553 | ||
3554 | @section deshake | |
3555 | ||
3556 | Attempt to fix small changes in horizontal and/or vertical shift. This | |
3557 | filter helps remove camera shake from hand-holding a camera, bumping a | |
3558 | tripod, moving on a vehicle, etc. | |
3559 | ||
3560 | The filter accepts the following options: | |
3561 | ||
3562 | @table @option | |
3563 | ||
3564 | @item x | |
3565 | @item y | |
3566 | @item w | |
3567 | @item h | |
3568 | Specify a rectangular area where to limit the search for motion | |
3569 | vectors. | |
3570 | If desired the search for motion vectors can be limited to a | |
3571 | rectangular area of the frame defined by its top left corner, width | |
3572 | and height. These parameters have the same meaning as the drawbox | |
3573 | filter which can be used to visualise the position of the bounding | |
3574 | box. | |
3575 | ||
3576 | This is useful when simultaneous movement of subjects within the frame | |
3577 | might be confused for camera motion by the motion vector search. | |
3578 | ||
3579 | If any or all of @var{x}, @var{y}, @var{w} and @var{h} are set to -1 | |
3580 | then the full frame is used. This allows later options to be set | |
3581 | without specifying the bounding box for the motion vector search. | |
3582 | ||
3583 | Default - search the whole frame. | |
3584 | ||
3585 | @item rx | |
3586 | @item ry | |
3587 | Specify the maximum extent of movement in x and y directions in the | |
3588 | range 0-64 pixels. Default 16. | |
3589 | ||
3590 | @item edge | |
3591 | Specify how to generate pixels to fill blanks at the edge of the | |
3592 | frame. Available values are: | |
3593 | @table @samp | |
3594 | @item blank, 0 | |
3595 | Fill zeroes at blank locations | |
3596 | @item original, 1 | |
3597 | Original image at blank locations | |
3598 | @item clamp, 2 | |
3599 | Extruded edge value at blank locations | |
3600 | @item mirror, 3 | |
3601 | Mirrored edge at blank locations | |
3602 | @end table | |
3603 | Default value is @samp{mirror}. | |
3604 | ||
3605 | @item blocksize | |
3606 | Specify the blocksize to use for motion search. Range 4-128 pixels, | |
3607 | default 8. | |
3608 | ||
3609 | @item contrast | |
3610 | Specify the contrast threshold for blocks. Only blocks with more than | |
3611 | the specified contrast (difference between darkest and lightest | |
3612 | pixels) will be considered. Range 1-255, default 125. | |
3613 | ||
3614 | @item search | |
3615 | Specify the search strategy. Available values are: | |
3616 | @table @samp | |
3617 | @item exhaustive, 0 | |
3618 | Set exhaustive search | |
3619 | @item less, 1 | |
3620 | Set less exhaustive search. | |
3621 | @end table | |
3622 | Default value is @samp{exhaustive}. | |
3623 | ||
3624 | @item filename | |
3625 | If set then a detailed log of the motion search is written to the | |
3626 | specified file. | |
3627 | ||
3628 | @item opencl | |
3629 | If set to 1, specify using OpenCL capabilities, only available if | |
3630 | FFmpeg was configured with @code{--enable-opencl}. Default value is 0. | |
3631 | ||
3632 | @end table | |
3633 | ||
3634 | @section drawbox | |
3635 | ||
3636 | Draw a colored box on the input image. | |
3637 | ||
3638 | It accepts the following parameters: | |
3639 | ||
3640 | @table @option | |
3641 | @item x | |
3642 | @item y | |
3643 | The expressions which specify the top left corner coordinates of the box. It defaults to 0. | |
3644 | ||
3645 | @item width, w | |
3646 | @item height, h | |
3647 | The expressions which specify the width and height of the box; if 0 they are interpreted as | |
3648 | the input width and height. It defaults to 0. | |
3649 | ||
3650 | @item color, c | |
3651 | Specify the color of the box to write. For the general syntax of this option, | |
3652 | check the "Color" section in the ffmpeg-utils manual. If the special | |
3653 | value @code{invert} is used, the box edge color is the same as the | |
3654 | video with inverted luma. | |
3655 | ||
3656 | @item thickness, t | |
3657 | The expression which sets the thickness of the box edge. Default value is @code{3}. | |
3658 | ||
3659 | See below for the list of accepted constants. | |
3660 | @end table | |
3661 | ||
3662 | The parameters for @var{x}, @var{y}, @var{w} and @var{h} and @var{t} are expressions containing the | |
3663 | following constants: | |
3664 | ||
3665 | @table @option | |
3666 | @item dar | |
3667 | The input display aspect ratio, it is the same as (@var{w} / @var{h}) * @var{sar}. | |
3668 | ||
3669 | @item hsub | |
3670 | @item vsub | |
3671 | horizontal and vertical chroma subsample values. For example for the | |
3672 | pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1. | |
3673 | ||
3674 | @item in_h, ih | |
3675 | @item in_w, iw | |
3676 | The input width and height. | |
3677 | ||
3678 | @item sar | |
3679 | The input sample aspect ratio. | |
3680 | ||
3681 | @item x | |
3682 | @item y | |
3683 | The x and y offset coordinates where the box is drawn. | |
3684 | ||
3685 | @item w | |
3686 | @item h | |
3687 | The width and height of the drawn box. | |
3688 | ||
3689 | @item t | |
3690 | The thickness of the drawn box. | |
3691 | ||
3692 | These constants allow the @var{x}, @var{y}, @var{w}, @var{h} and @var{t} expressions to refer to | |
3693 | each other, so you may for example specify @code{y=x/dar} or @code{h=w/dar}. | |
3694 | ||
3695 | @end table | |
3696 | ||
3697 | @subsection Examples | |
3698 | ||
3699 | @itemize | |
3700 | @item | |
3701 | Draw a black box around the edge of the input image: | |
3702 | @example | |
3703 | drawbox | |
3704 | @end example | |
3705 | ||
3706 | @item | |
3707 | Draw a box with color red and an opacity of 50%: | |
3708 | @example | |
3709 | drawbox=10:20:200:60:red@@0.5 | |
3710 | @end example | |
3711 | ||
3712 | The previous example can be specified as: | |
3713 | @example | |
3714 | drawbox=x=10:y=20:w=200:h=60:color=red@@0.5 | |
3715 | @end example | |
3716 | ||
3717 | @item | |
3718 | Fill the box with pink color: | |
3719 | @example | |
3720 | drawbox=x=10:y=10:w=100:h=100:color=pink@@0.5:t=max | |
3721 | @end example | |
3722 | ||
3723 | @item | |
3724 | Draw a 2-pixel red 2.40:1 mask: | |
3725 | @example | |
3726 | 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 | |
3727 | @end example | |
3728 | @end itemize | |
3729 | ||
3730 | @section drawgrid | |
3731 | ||
3732 | Draw a grid on the input image. | |
3733 | ||
3734 | It accepts the following parameters: | |
3735 | ||
3736 | @table @option | |
3737 | @item x | |
3738 | @item y | |
3739 | The expressions which specify the coordinates of some point of grid intersection (meant to configure offset). Both default to 0. | |
3740 | ||
3741 | @item width, w | |
3742 | @item height, h | |
3743 | The expressions which specify the width and height of the grid cell, if 0 they are interpreted as the | |
3744 | input width and height, respectively, minus @code{thickness}, so image gets | |
3745 | framed. Default to 0. | |
3746 | ||
3747 | @item color, c | |
3748 | Specify the color of the grid. For the general syntax of this option, | |
3749 | check the "Color" section in the ffmpeg-utils manual. If the special | |
3750 | value @code{invert} is used, the grid color is the same as the | |
3751 | video with inverted luma. | |
3752 | ||
3753 | @item thickness, t | |
3754 | The expression which sets the thickness of the grid line. Default value is @code{1}. | |
3755 | ||
3756 | See below for the list of accepted constants. | |
3757 | @end table | |
3758 | ||
3759 | The parameters for @var{x}, @var{y}, @var{w} and @var{h} and @var{t} are expressions containing the | |
3760 | following constants: | |
3761 | ||
3762 | @table @option | |
3763 | @item dar | |
3764 | The input display aspect ratio, it is the same as (@var{w} / @var{h}) * @var{sar}. | |
3765 | ||
3766 | @item hsub | |
3767 | @item vsub | |
3768 | horizontal and vertical chroma subsample values. For example for the | |
3769 | pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1. | |
3770 | ||
3771 | @item in_h, ih | |
3772 | @item in_w, iw | |
3773 | The input grid cell width and height. | |
3774 | ||
3775 | @item sar | |
3776 | The input sample aspect ratio. | |
3777 | ||
3778 | @item x | |
3779 | @item y | |
3780 | The x and y coordinates of some point of grid intersection (meant to configure offset). | |
3781 | ||
3782 | @item w | |
3783 | @item h | |
3784 | The width and height of the drawn cell. | |
3785 | ||
3786 | @item t | |
3787 | The thickness of the drawn cell. | |
3788 | ||
3789 | These constants allow the @var{x}, @var{y}, @var{w}, @var{h} and @var{t} expressions to refer to | |
3790 | each other, so you may for example specify @code{y=x/dar} or @code{h=w/dar}. | |
3791 | ||
3792 | @end table | |
3793 | ||
3794 | @subsection Examples | |
3795 | ||
3796 | @itemize | |
3797 | @item | |
3798 | Draw a grid with cell 100x100 pixels, thickness 2 pixels, with color red and an opacity of 50%: | |
3799 | @example | |
3800 | drawgrid=width=100:height=100:thickness=2:color=red@@0.5 | |
3801 | @end example | |
3802 | ||
3803 | @item | |
3804 | Draw a white 3x3 grid with an opacity of 50%: | |
3805 | @example | |
3806 | drawgrid=w=iw/3:h=ih/3:t=2:c=white@@0.5 | |
3807 | @end example | |
3808 | @end itemize | |
3809 | ||
3810 | @anchor{drawtext} | |
3811 | @section drawtext | |
3812 | ||
3813 | Draw a text string or text from a specified file on top of a video, using the | |
3814 | libfreetype library. | |
3815 | ||
3816 | To enable compilation of this filter, you need to configure FFmpeg with | |
3817 | @code{--enable-libfreetype}. | |
3818 | To enable default font fallback and the @var{font} option you need to | |
3819 | configure FFmpeg with @code{--enable-libfontconfig}. | |
3820 | To enable the @var{text_shaping} option, you need to configure FFmpeg with | |
3821 | @code{--enable-libfribidi}. | |
3822 | ||
3823 | @subsection Syntax | |
3824 | ||
3825 | It accepts the following parameters: | |
3826 | ||
3827 | @table @option | |
3828 | ||
3829 | @item box | |
3830 | Used to draw a box around text using the background color. | |
3831 | The value must be either 1 (enable) or 0 (disable). | |
3832 | The default value of @var{box} is 0. | |
3833 | ||
3834 | @item boxcolor | |
3835 | The color to be used for drawing box around text. For the syntax of this | |
3836 | option, check the "Color" section in the ffmpeg-utils manual. | |
3837 | ||
3838 | The default value of @var{boxcolor} is "white". | |
3839 | ||
3840 | @item borderw | |
3841 | Set the width of the border to be drawn around the text using @var{bordercolor}. | |
3842 | The default value of @var{borderw} is 0. | |
3843 | ||
3844 | @item bordercolor | |
3845 | Set the color to be used for drawing border around text. For the syntax of this | |
3846 | option, check the "Color" section in the ffmpeg-utils manual. | |
3847 | ||
3848 | The default value of @var{bordercolor} is "black". | |
3849 | ||
3850 | @item expansion | |
3851 | Select how the @var{text} is expanded. Can be either @code{none}, | |
3852 | @code{strftime} (deprecated) or | |
3853 | @code{normal} (default). See the @ref{drawtext_expansion, Text expansion} section | |
3854 | below for details. | |
3855 | ||
3856 | @item fix_bounds | |
3857 | If true, check and fix text coords to avoid clipping. | |
3858 | ||
3859 | @item fontcolor | |
3860 | The color to be used for drawing fonts. For the syntax of this option, check | |
3861 | the "Color" section in the ffmpeg-utils manual. | |
3862 | ||
3863 | The default value of @var{fontcolor} is "black". | |
3864 | ||
3865 | @item fontcolor_expr | |
3866 | String which is expanded the same way as @var{text} to obtain dynamic | |
3867 | @var{fontcolor} value. By default this option has empty value and is not | |
3868 | processed. When this option is set, it overrides @var{fontcolor} option. | |
3869 | ||
3870 | @item font | |
3871 | The font family to be used for drawing text. By default Sans. | |
3872 | ||
3873 | @item fontfile | |
3874 | The font file to be used for drawing text. The path must be included. | |
3875 | This parameter is mandatory if the fontconfig support is disabled. | |
3876 | ||
3877 | @item fontsize | |
3878 | The font size to be used for drawing text. | |
3879 | The default value of @var{fontsize} is 16. | |
3880 | ||
3881 | @item text_shaping | |
3882 | If set to 1, attempt to shape the text (for example, reverse the order of | |
3883 | right-to-left text and join Arabic characters) before drawing it. | |
3884 | Otherwise, just draw the text exactly as given. | |
3885 | By default 1 (if supported). | |
3886 | ||
3887 | @item ft_load_flags | |
3888 | The flags to be used for loading the fonts. | |
3889 | ||
3890 | The flags map the corresponding flags supported by libfreetype, and are | |
3891 | a combination of the following values: | |
3892 | @table @var | |
3893 | @item default | |
3894 | @item no_scale | |
3895 | @item no_hinting | |
3896 | @item render | |
3897 | @item no_bitmap | |
3898 | @item vertical_layout | |
3899 | @item force_autohint | |
3900 | @item crop_bitmap | |
3901 | @item pedantic | |
3902 | @item ignore_global_advance_width | |
3903 | @item no_recurse | |
3904 | @item ignore_transform | |
3905 | @item monochrome | |
3906 | @item linear_design | |
3907 | @item no_autohint | |
3908 | @end table | |
3909 | ||
3910 | Default value is "default". | |
3911 | ||
3912 | For more information consult the documentation for the FT_LOAD_* | |
3913 | libfreetype flags. | |
3914 | ||
3915 | @item shadowcolor | |
3916 | The color to be used for drawing a shadow behind the drawn text. For the | |
3917 | syntax of this option, check the "Color" section in the ffmpeg-utils manual. | |
3918 | ||
3919 | The default value of @var{shadowcolor} is "black". | |
3920 | ||
3921 | @item shadowx | |
3922 | @item shadowy | |
3923 | The x and y offsets for the text shadow position with respect to the | |
3924 | position of the text. They can be either positive or negative | |
3925 | values. The default value for both is "0". | |
3926 | ||
3927 | @item start_number | |
3928 | The starting frame number for the n/frame_num variable. The default value | |
3929 | is "0". | |
3930 | ||
3931 | @item tabsize | |
3932 | The size in number of spaces to use for rendering the tab. | |
3933 | Default value is 4. | |
3934 | ||
3935 | @item timecode | |
3936 | Set the initial timecode representation in "hh:mm:ss[:;.]ff" | |
3937 | format. It can be used with or without text parameter. @var{timecode_rate} | |
3938 | option must be specified. | |
3939 | ||
3940 | @item timecode_rate, rate, r | |
3941 | Set the timecode frame rate (timecode only). | |
3942 | ||
3943 | @item text | |
3944 | The text string to be drawn. The text must be a sequence of UTF-8 | |
3945 | encoded characters. | |
3946 | This parameter is mandatory if no file is specified with the parameter | |
3947 | @var{textfile}. | |
3948 | ||
3949 | @item textfile | |
3950 | A text file containing text to be drawn. The text must be a sequence | |
3951 | of UTF-8 encoded characters. | |
3952 | ||
3953 | This parameter is mandatory if no text string is specified with the | |
3954 | parameter @var{text}. | |
3955 | ||
3956 | If both @var{text} and @var{textfile} are specified, an error is thrown. | |
3957 | ||
3958 | @item reload | |
3959 | If set to 1, the @var{textfile} will be reloaded before each frame. | |
3960 | Be sure to update it atomically, or it may be read partially, or even fail. | |
3961 | ||
3962 | @item x | |
3963 | @item y | |
3964 | The expressions which specify the offsets where text will be drawn | |
3965 | within the video frame. They are relative to the top/left border of the | |
3966 | output image. | |
3967 | ||
3968 | The default value of @var{x} and @var{y} is "0". | |
3969 | ||
3970 | See below for the list of accepted constants and functions. | |
3971 | @end table | |
3972 | ||
3973 | The parameters for @var{x} and @var{y} are expressions containing the | |
3974 | following constants and functions: | |
3975 | ||
3976 | @table @option | |
3977 | @item dar | |
3978 | input display aspect ratio, it is the same as (@var{w} / @var{h}) * @var{sar} | |
3979 | ||
3980 | @item hsub | |
3981 | @item vsub | |
3982 | horizontal and vertical chroma subsample values. For example for the | |
3983 | pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1. | |
3984 | ||
3985 | @item line_h, lh | |
3986 | the height of each text line | |
3987 | ||
3988 | @item main_h, h, H | |
3989 | the input height | |
3990 | ||
3991 | @item main_w, w, W | |
3992 | the input width | |
3993 | ||
3994 | @item max_glyph_a, ascent | |
3995 | the maximum distance from the baseline to the highest/upper grid | |
3996 | coordinate used to place a glyph outline point, for all the rendered | |
3997 | glyphs. | |
3998 | It is a positive value, due to the grid's orientation with the Y axis | |
3999 | upwards. | |
4000 | ||
4001 | @item max_glyph_d, descent | |
4002 | the maximum distance from the baseline to the lowest grid coordinate | |
4003 | used to place a glyph outline point, for all the rendered glyphs. | |
4004 | This is a negative value, due to the grid's orientation, with the Y axis | |
4005 | upwards. | |
4006 | ||
4007 | @item max_glyph_h | |
4008 | maximum glyph height, that is the maximum height for all the glyphs | |
4009 | contained in the rendered text, it is equivalent to @var{ascent} - | |
4010 | @var{descent}. | |
4011 | ||
4012 | @item max_glyph_w | |
4013 | maximum glyph width, that is the maximum width for all the glyphs | |
4014 | contained in the rendered text | |
4015 | ||
4016 | @item n | |
4017 | the number of input frame, starting from 0 | |
4018 | ||
4019 | @item rand(min, max) | |
4020 | return a random number included between @var{min} and @var{max} | |
4021 | ||
4022 | @item sar | |
4023 | The input sample aspect ratio. | |
4024 | ||
4025 | @item t | |
4026 | timestamp expressed in seconds, NAN if the input timestamp is unknown | |
4027 | ||
4028 | @item text_h, th | |
4029 | the height of the rendered text | |
4030 | ||
4031 | @item text_w, tw | |
4032 | the width of the rendered text | |
4033 | ||
4034 | @item x | |
4035 | @item y | |
4036 | the x and y offset coordinates where the text is drawn. | |
4037 | ||
4038 | These parameters allow the @var{x} and @var{y} expressions to refer | |
4039 | each other, so you can for example specify @code{y=x/dar}. | |
4040 | @end table | |
4041 | ||
4042 | @anchor{drawtext_expansion} | |
4043 | @subsection Text expansion | |
4044 | ||
4045 | If @option{expansion} is set to @code{strftime}, | |
4046 | the filter recognizes strftime() sequences in the provided text and | |
4047 | expands them accordingly. Check the documentation of strftime(). This | |
4048 | feature is deprecated. | |
4049 | ||
4050 | If @option{expansion} is set to @code{none}, the text is printed verbatim. | |
4051 | ||
4052 | If @option{expansion} is set to @code{normal} (which is the default), | |
4053 | the following expansion mechanism is used. | |
4054 | ||
4055 | The backslash character '\', followed by any character, always expands to | |
4056 | the second character. | |
4057 | ||
4058 | Sequence of the form @code{%@{...@}} are expanded. The text between the | |
4059 | braces is a function name, possibly followed by arguments separated by ':'. | |
4060 | If the arguments contain special characters or delimiters (':' or '@}'), | |
4061 | they should be escaped. | |
4062 | ||
4063 | Note that they probably must also be escaped as the value for the | |
4064 | @option{text} option in the filter argument string and as the filter | |
4065 | argument in the filtergraph description, and possibly also for the shell, | |
4066 | that makes up to four levels of escaping; using a text file avoids these | |
4067 | problems. | |
4068 | ||
4069 | The following functions are available: | |
4070 | ||
4071 | @table @command | |
4072 | ||
4073 | @item expr, e | |
4074 | The expression evaluation result. | |
4075 | ||
4076 | It must take one argument specifying the expression to be evaluated, | |
4077 | which accepts the same constants and functions as the @var{x} and | |
4078 | @var{y} values. Note that not all constants should be used, for | |
4079 | example the text size is not known when evaluating the expression, so | |
4080 | the constants @var{text_w} and @var{text_h} will have an undefined | |
4081 | value. | |
4082 | ||
4083 | @item expr_int_format, eif | |
4084 | Evaluate the expression's value and output as formatted integer. | |
4085 | ||
4086 | The first argument is the expression to be evaluated, just as for the @var{expr} function. | |
4087 | The second argument specifies the output format. Allowed values are 'x', 'X', 'd' and | |
4088 | 'u'. They are treated exactly as in the printf function. | |
4089 | The third parameter is optional and sets the number of positions taken by the output. | |
4090 | It can be used to add padding with zeros from the left. | |
4091 | ||
4092 | @item gmtime | |
4093 | The time at which the filter is running, expressed in UTC. | |
4094 | It can accept an argument: a strftime() format string. | |
4095 | ||
4096 | @item localtime | |
4097 | The time at which the filter is running, expressed in the local time zone. | |
4098 | It can accept an argument: a strftime() format string. | |
4099 | ||
4100 | @item metadata | |
4101 | Frame metadata. It must take one argument specifying metadata key. | |
4102 | ||
4103 | @item n, frame_num | |
4104 | The frame number, starting from 0. | |
4105 | ||
4106 | @item pict_type | |
4107 | A 1 character description of the current picture type. | |
4108 | ||
4109 | @item pts | |
4110 | The timestamp of the current frame. | |
4111 | It can take up to two arguments. | |
4112 | ||
4113 | The first argument is the format of the timestamp; it defaults to @code{flt} | |
4114 | for seconds as a decimal number with microsecond accuracy; @code{hms} stands | |
4115 | for a formatted @var{[-]HH:MM:SS.mmm} timestamp with millisecond accuracy. | |
4116 | ||
4117 | The second argument is an offset added to the timestamp. | |
4118 | ||
4119 | @end table | |
4120 | ||
4121 | @subsection Examples | |
4122 | ||
4123 | @itemize | |
4124 | @item | |
4125 | Draw "Test Text" with font FreeSerif, using the default values for the | |
4126 | optional parameters. | |
4127 | ||
4128 | @example | |
4129 | drawtext="fontfile=/usr/share/fonts/truetype/freefont/FreeSerif.ttf: text='Test Text'" | |
4130 | @end example | |
4131 | ||
4132 | @item | |
4133 | Draw 'Test Text' with font FreeSerif of size 24 at position x=100 | |
4134 | and y=50 (counting from the top-left corner of the screen), text is | |
4135 | yellow with a red box around it. Both the text and the box have an | |
4136 | opacity of 20%. | |
4137 | ||
4138 | @example | |
4139 | drawtext="fontfile=/usr/share/fonts/truetype/freefont/FreeSerif.ttf: text='Test Text':\ | |
4140 | x=100: y=50: fontsize=24: fontcolor=yellow@@0.2: box=1: boxcolor=red@@0.2" | |
4141 | @end example | |
4142 | ||
4143 | Note that the double quotes are not necessary if spaces are not used | |
4144 | within the parameter list. | |
4145 | ||
4146 | @item | |
4147 | Show the text at the center of the video frame: | |
4148 | @example | |
4149 | drawtext="fontsize=30:fontfile=FreeSerif.ttf:text='hello world':x=(w-text_w)/2:y=(h-text_h-line_h)/2" | |
4150 | @end example | |
4151 | ||
4152 | @item | |
4153 | Show a text line sliding from right to left in the last row of the video | |
4154 | frame. The file @file{LONG_LINE} is assumed to contain a single line | |
4155 | with no newlines. | |
4156 | @example | |
4157 | drawtext="fontsize=15:fontfile=FreeSerif.ttf:text=LONG_LINE:y=h-line_h:x=-50*t" | |
4158 | @end example | |
4159 | ||
4160 | @item | |
4161 | Show the content of file @file{CREDITS} off the bottom of the frame and scroll up. | |
4162 | @example | |
4163 | drawtext="fontsize=20:fontfile=FreeSerif.ttf:textfile=CREDITS:y=h-20*t" | |
4164 | @end example | |
4165 | ||
4166 | @item | |
4167 | Draw a single green letter "g", at the center of the input video. | |
4168 | The glyph baseline is placed at half screen height. | |
4169 | @example | |
4170 | drawtext="fontsize=60:fontfile=FreeSerif.ttf:fontcolor=green:text=g:x=(w-max_glyph_w)/2:y=h/2-ascent" | |
4171 | @end example | |
4172 | ||
4173 | @item | |
4174 | Show text for 1 second every 3 seconds: | |
4175 | @example | |
4176 | drawtext="fontfile=FreeSerif.ttf:fontcolor=white:x=100:y=x/dar:enable=lt(mod(t\,3)\,1):text='blink'" | |
4177 | @end example | |
4178 | ||
4179 | @item | |
4180 | Use fontconfig to set the font. Note that the colons need to be escaped. | |
4181 | @example | |
4182 | drawtext='fontfile=Linux Libertine O-40\:style=Semibold:text=FFmpeg' | |
4183 | @end example | |
4184 | ||
4185 | @item | |
4186 | Print the date of a real-time encoding (see strftime(3)): | |
4187 | @example | |
4188 | drawtext='fontfile=FreeSans.ttf:text=%@{localtime:%a %b %d %Y@}' | |
4189 | @end example | |
4190 | ||
4191 | @item | |
4192 | Show text fading in and out (appearing/disappearing): | |
4193 | @example | |
4194 | #!/bin/sh | |
4195 | DS=1.0 # display start | |
4196 | DE=10.0 # display end | |
4197 | FID=1.5 # fade in duration | |
4198 | FOD=5 # fade out duration | |
4199 | 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 @}" | |
4200 | @end example | |
4201 | ||
4202 | @end itemize | |
4203 | ||
4204 | For more information about libfreetype, check: | |
4205 | @url{http://www.freetype.org/}. | |
4206 | ||
4207 | For more information about fontconfig, check: | |
4208 | @url{http://freedesktop.org/software/fontconfig/fontconfig-user.html}. | |
4209 | ||
4210 | For more information about libfribidi, check: | |
4211 | @url{http://fribidi.org/}. | |
4212 | ||
4213 | @section edgedetect | |
4214 | ||
4215 | Detect and draw edges. The filter uses the Canny Edge Detection algorithm. | |
4216 | ||
4217 | The filter accepts the following options: | |
4218 | ||
4219 | @table @option | |
4220 | @item low | |
4221 | @item high | |
4222 | Set low and high threshold values used by the Canny thresholding | |
4223 | algorithm. | |
4224 | ||
4225 | The high threshold selects the "strong" edge pixels, which are then | |
4226 | connected through 8-connectivity with the "weak" edge pixels selected | |
4227 | by the low threshold. | |
4228 | ||
4229 | @var{low} and @var{high} threshold values must be chosen in the range | |
4230 | [0,1], and @var{low} should be lesser or equal to @var{high}. | |
4231 | ||
4232 | Default value for @var{low} is @code{20/255}, and default value for @var{high} | |
4233 | is @code{50/255}. | |
4234 | ||
4235 | @item mode | |
4236 | Define the drawing mode. | |
4237 | ||
4238 | @table @samp | |
4239 | @item wires | |
4240 | Draw white/gray wires on black background. | |
4241 | ||
4242 | @item colormix | |
4243 | Mix the colors to create a paint/cartoon effect. | |
4244 | @end table | |
4245 | ||
4246 | Default value is @var{wires}. | |
4247 | @end table | |
4248 | ||
4249 | @subsection Examples | |
4250 | ||
4251 | @itemize | |
4252 | @item | |
4253 | Standard edge detection with custom values for the hysteresis thresholding: | |
4254 | @example | |
4255 | edgedetect=low=0.1:high=0.4 | |
4256 | @end example | |
4257 | ||
4258 | @item | |
4259 | Painting effect without thresholding: | |
4260 | @example | |
4261 | edgedetect=mode=colormix:high=0 | |
4262 | @end example | |
4263 | @end itemize | |
4264 | ||
4265 | @section extractplanes | |
4266 | ||
4267 | Extract color channel components from input video stream into | |
4268 | separate grayscale video streams. | |
4269 | ||
4270 | The filter accepts the following option: | |
4271 | ||
4272 | @table @option | |
4273 | @item planes | |
4274 | Set plane(s) to extract. | |
4275 | ||
4276 | Available values for planes are: | |
4277 | @table @samp | |
4278 | @item y | |
4279 | @item u | |
4280 | @item v | |
4281 | @item a | |
4282 | @item r | |
4283 | @item g | |
4284 | @item b | |
4285 | @end table | |
4286 | ||
4287 | Choosing planes not available in the input will result in an error. | |
4288 | That means you cannot select @code{r}, @code{g}, @code{b} planes | |
4289 | with @code{y}, @code{u}, @code{v} planes at same time. | |
4290 | @end table | |
4291 | ||
4292 | @subsection Examples | |
4293 | ||
4294 | @itemize | |
4295 | @item | |
4296 | Extract luma, u and v color channel component from input video frame | |
4297 | into 3 grayscale outputs: | |
4298 | @example | |
4299 | 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 | |
4300 | @end example | |
4301 | @end itemize | |
4302 | ||
4303 | @section elbg | |
4304 | ||
4305 | Apply a posterize effect using the ELBG (Enhanced LBG) algorithm. | |
4306 | ||
4307 | For each input image, the filter will compute the optimal mapping from | |
4308 | the input to the output given the codebook length, that is the number | |
4309 | of distinct output colors. | |
4310 | ||
4311 | This filter accepts the following options. | |
4312 | ||
4313 | @table @option | |
4314 | @item codebook_length, l | |
4315 | Set codebook length. The value must be a positive integer, and | |
4316 | represents the number of distinct output colors. Default value is 256. | |
4317 | ||
4318 | @item nb_steps, n | |
4319 | Set the maximum number of iterations to apply for computing the optimal | |
4320 | mapping. The higher the value the better the result and the higher the | |
4321 | computation time. Default value is 1. | |
4322 | ||
4323 | @item seed, s | |
4324 | Set a random seed, must be an integer included between 0 and | |
4325 | UINT32_MAX. If not specified, or if explicitly set to -1, the filter | |
4326 | will try to use a good random seed on a best effort basis. | |
4327 | @end table | |
4328 | ||
4329 | @section fade | |
4330 | ||
4331 | Apply a fade-in/out effect to the input video. | |
4332 | ||
4333 | It accepts the following parameters: | |
4334 | ||
4335 | @table @option | |
4336 | @item type, t | |
4337 | The effect type can be either "in" for a fade-in, or "out" for a fade-out | |
4338 | effect. | |
4339 | Default is @code{in}. | |
4340 | ||
4341 | @item start_frame, s | |
4342 | Specify the number of the frame to start applying the fade | |
4343 | effect at. Default is 0. | |
4344 | ||
4345 | @item nb_frames, n | |
4346 | The number of frames that the fade effect lasts. At the end of the | |
4347 | fade-in effect, the output video will have the same intensity as the input video. | |
4348 | At the end of the fade-out transition, the output video will be filled with the | |
4349 | selected @option{color}. | |
4350 | Default is 25. | |
4351 | ||
4352 | @item alpha | |
4353 | If set to 1, fade only alpha channel, if one exists on the input. | |
4354 | Default value is 0. | |
4355 | ||
4356 | @item start_time, st | |
4357 | Specify the timestamp (in seconds) of the frame to start to apply the fade | |
4358 | effect. If both start_frame and start_time are specified, the fade will start at | |
4359 | whichever comes last. Default is 0. | |
4360 | ||
4361 | @item duration, d | |
4362 | The number of seconds for which the fade effect has to last. At the end of the | |
4363 | fade-in effect the output video will have the same intensity as the input video, | |
4364 | at the end of the fade-out transition the output video will be filled with the | |
4365 | selected @option{color}. | |
4366 | If both duration and nb_frames are specified, duration is used. Default is 0. | |
4367 | ||
4368 | @item color, c | |
4369 | Specify the color of the fade. Default is "black". | |
4370 | @end table | |
4371 | ||
4372 | @subsection Examples | |
4373 | ||
4374 | @itemize | |
4375 | @item | |
4376 | Fade in the first 30 frames of video: | |
4377 | @example | |
4378 | fade=in:0:30 | |
4379 | @end example | |
4380 | ||
4381 | The command above is equivalent to: | |
4382 | @example | |
4383 | fade=t=in:s=0:n=30 | |
4384 | @end example | |
4385 | ||
4386 | @item | |
4387 | Fade out the last 45 frames of a 200-frame video: | |
4388 | @example | |
4389 | fade=out:155:45 | |
4390 | fade=type=out:start_frame=155:nb_frames=45 | |
4391 | @end example | |
4392 | ||
4393 | @item | |
4394 | Fade in the first 25 frames and fade out the last 25 frames of a 1000-frame video: | |
4395 | @example | |
4396 | fade=in:0:25, fade=out:975:25 | |
4397 | @end example | |
4398 | ||
4399 | @item | |
4400 | Make the first 5 frames yellow, then fade in from frame 5-24: | |
4401 | @example | |
4402 | fade=in:5:20:color=yellow | |
4403 | @end example | |
4404 | ||
4405 | @item | |
4406 | Fade in alpha over first 25 frames of video: | |
4407 | @example | |
4408 | fade=in:0:25:alpha=1 | |
4409 | @end example | |
4410 | ||
4411 | @item | |
4412 | Make the first 5.5 seconds black, then fade in for 0.5 seconds: | |
4413 | @example | |
4414 | fade=t=in:st=5.5:d=0.5 | |
4415 | @end example | |
4416 | ||
4417 | @end itemize | |
4418 | ||
4419 | @section field | |
4420 | ||
4421 | Extract a single field from an interlaced image using stride | |
4422 | arithmetic to avoid wasting CPU time. The output frames are marked as | |
4423 | non-interlaced. | |
4424 | ||
4425 | The filter accepts the following options: | |
4426 | ||
4427 | @table @option | |
4428 | @item type | |
4429 | Specify whether to extract the top (if the value is @code{0} or | |
4430 | @code{top}) or the bottom field (if the value is @code{1} or | |
4431 | @code{bottom}). | |
4432 | @end table | |
4433 | ||
4434 | @section fieldmatch | |
4435 | ||
4436 | Field matching filter for inverse telecine. It is meant to reconstruct the | |
4437 | progressive frames from a telecined stream. The filter does not drop duplicated | |
4438 | frames, so to achieve a complete inverse telecine @code{fieldmatch} needs to be | |
4439 | followed by a decimation filter such as @ref{decimate} in the filtergraph. | |
4440 | ||
4441 | The separation of the field matching and the decimation is notably motivated by | |
4442 | the possibility of inserting a de-interlacing filter fallback between the two. | |
4443 | If the source has mixed telecined and real interlaced content, | |
4444 | @code{fieldmatch} will not be able to match fields for the interlaced parts. | |
4445 | But these remaining combed frames will be marked as interlaced, and thus can be | |
4446 | de-interlaced by a later filter such as @ref{yadif} before decimation. | |
4447 | ||
4448 | In addition to the various configuration options, @code{fieldmatch} can take an | |
4449 | optional second stream, activated through the @option{ppsrc} option. If | |
4450 | enabled, the frames reconstruction will be based on the fields and frames from | |
4451 | this second stream. This allows the first input to be pre-processed in order to | |
4452 | help the various algorithms of the filter, while keeping the output lossless | |
4453 | (assuming the fields are matched properly). Typically, a field-aware denoiser, | |
4454 | or brightness/contrast adjustments can help. | |
4455 | ||
4456 | Note that this filter uses the same algorithms as TIVTC/TFM (AviSynth project) | |
4457 | and VIVTC/VFM (VapourSynth project). The later is a light clone of TFM from | |
4458 | which @code{fieldmatch} is based on. While the semantic and usage are very | |
4459 | close, some behaviour and options names can differ. | |
4460 | ||
4461 | The filter accepts the following options: | |
4462 | ||
4463 | @table @option | |
4464 | @item order | |
4465 | Specify the assumed field order of the input stream. Available values are: | |
4466 | ||
4467 | @table @samp | |
4468 | @item auto | |
4469 | Auto detect parity (use FFmpeg's internal parity value). | |
4470 | @item bff | |
4471 | Assume bottom field first. | |
4472 | @item tff | |
4473 | Assume top field first. | |
4474 | @end table | |
4475 | ||
4476 | Note that it is sometimes recommended not to trust the parity announced by the | |
4477 | stream. | |
4478 | ||
4479 | Default value is @var{auto}. | |
4480 | ||
4481 | @item mode | |
4482 | Set the matching mode or strategy to use. @option{pc} mode is the safest in the | |
4483 | sense that it won't risk creating jerkiness due to duplicate frames when | |
4484 | possible, but if there are bad edits or blended fields it will end up | |
4485 | outputting combed frames when a good match might actually exist. On the other | |
4486 | hand, @option{pcn_ub} mode is the most risky in terms of creating jerkiness, | |
4487 | but will almost always find a good frame if there is one. The other values are | |
4488 | all somewhere in between @option{pc} and @option{pcn_ub} in terms of risking | |
4489 | jerkiness and creating duplicate frames versus finding good matches in sections | |
4490 | with bad edits, orphaned fields, blended fields, etc. | |
4491 | ||
4492 | More details about p/c/n/u/b are available in @ref{p/c/n/u/b meaning} section. | |
4493 | ||
4494 | Available values are: | |
4495 | ||
4496 | @table @samp | |
4497 | @item pc | |
4498 | 2-way matching (p/c) | |
4499 | @item pc_n | |
4500 | 2-way matching, and trying 3rd match if still combed (p/c + n) | |
4501 | @item pc_u | |
4502 | 2-way matching, and trying 3rd match (same order) if still combed (p/c + u) | |
4503 | @item pc_n_ub | |
4504 | 2-way matching, trying 3rd match if still combed, and trying 4th/5th matches if | |
4505 | still combed (p/c + n + u/b) | |
4506 | @item pcn | |
4507 | 3-way matching (p/c/n) | |
4508 | @item pcn_ub | |
4509 | 3-way matching, and trying 4th/5th matches if all 3 of the original matches are | |
4510 | detected as combed (p/c/n + u/b) | |
4511 | @end table | |
4512 | ||
4513 | The parenthesis at the end indicate the matches that would be used for that | |
4514 | mode assuming @option{order}=@var{tff} (and @option{field} on @var{auto} or | |
4515 | @var{top}). | |
4516 | ||
4517 | In terms of speed @option{pc} mode is by far the fastest and @option{pcn_ub} is | |
4518 | the slowest. | |
4519 | ||
4520 | Default value is @var{pc_n}. | |
4521 | ||
4522 | @item ppsrc | |
4523 | Mark the main input stream as a pre-processed input, and enable the secondary | |
4524 | input stream as the clean source to pick the fields from. See the filter | |
4525 | introduction for more details. It is similar to the @option{clip2} feature from | |
4526 | VFM/TFM. | |
4527 | ||
4528 | Default value is @code{0} (disabled). | |
4529 | ||
4530 | @item field | |
4531 | Set the field to match from. It is recommended to set this to the same value as | |
4532 | @option{order} unless you experience matching failures with that setting. In | |
4533 | certain circumstances changing the field that is used to match from can have a | |
4534 | large impact on matching performance. Available values are: | |
4535 | ||
4536 | @table @samp | |
4537 | @item auto | |
4538 | Automatic (same value as @option{order}). | |
4539 | @item bottom | |
4540 | Match from the bottom field. | |
4541 | @item top | |
4542 | Match from the top field. | |
4543 | @end table | |
4544 | ||
4545 | Default value is @var{auto}. | |
4546 | ||
4547 | @item mchroma | |
4548 | Set whether or not chroma is included during the match comparisons. In most | |
4549 | cases it is recommended to leave this enabled. You should set this to @code{0} | |
4550 | only if your clip has bad chroma problems such as heavy rainbowing or other | |
4551 | artifacts. Setting this to @code{0} could also be used to speed things up at | |
4552 | the cost of some accuracy. | |
4553 | ||
4554 | Default value is @code{1}. | |
4555 | ||
4556 | @item y0 | |
4557 | @item y1 | |
4558 | These define an exclusion band which excludes the lines between @option{y0} and | |
4559 | @option{y1} from being included in the field matching decision. An exclusion | |
4560 | band can be used to ignore subtitles, a logo, or other things that may | |
4561 | interfere with the matching. @option{y0} sets the starting scan line and | |
4562 | @option{y1} sets the ending line; all lines in between @option{y0} and | |
4563 | @option{y1} (including @option{y0} and @option{y1}) will be ignored. Setting | |
4564 | @option{y0} and @option{y1} to the same value will disable the feature. | |
4565 | @option{y0} and @option{y1} defaults to @code{0}. | |
4566 | ||
4567 | @item scthresh | |
4568 | Set the scene change detection threshold as a percentage of maximum change on | |
4569 | the luma plane. Good values are in the @code{[8.0, 14.0]} range. Scene change | |
4570 | detection is only relevant in case @option{combmatch}=@var{sc}. The range for | |
4571 | @option{scthresh} is @code{[0.0, 100.0]}. | |
4572 | ||
4573 | Default value is @code{12.0}. | |
4574 | ||
4575 | @item combmatch | |
4576 | When @option{combatch} is not @var{none}, @code{fieldmatch} will take into | |
4577 | account the combed scores of matches when deciding what match to use as the | |
4578 | final match. Available values are: | |
4579 | ||
4580 | @table @samp | |
4581 | @item none | |
4582 | No final matching based on combed scores. | |
4583 | @item sc | |
4584 | Combed scores are only used when a scene change is detected. | |
4585 | @item full | |
4586 | Use combed scores all the time. | |
4587 | @end table | |
4588 | ||
4589 | Default is @var{sc}. | |
4590 | ||
4591 | @item combdbg | |
4592 | Force @code{fieldmatch} to calculate the combed metrics for certain matches and | |
4593 | print them. This setting is known as @option{micout} in TFM/VFM vocabulary. | |
4594 | Available values are: | |
4595 | ||
4596 | @table @samp | |
4597 | @item none | |
4598 | No forced calculation. | |
4599 | @item pcn | |
4600 | Force p/c/n calculations. | |
4601 | @item pcnub | |
4602 | Force p/c/n/u/b calculations. | |
4603 | @end table | |
4604 | ||
4605 | Default value is @var{none}. | |
4606 | ||
4607 | @item cthresh | |
4608 | This is the area combing threshold used for combed frame detection. This | |
4609 | essentially controls how "strong" or "visible" combing must be to be detected. | |
4610 | Larger values mean combing must be more visible and smaller values mean combing | |
4611 | can be less visible or strong and still be detected. Valid settings are from | |
4612 | @code{-1} (every pixel will be detected as combed) to @code{255} (no pixel will | |
4613 | be detected as combed). This is basically a pixel difference value. A good | |
4614 | range is @code{[8, 12]}. | |
4615 | ||
4616 | Default value is @code{9}. | |
4617 | ||
4618 | @item chroma | |
4619 | Sets whether or not chroma is considered in the combed frame decision. Only | |
4620 | disable this if your source has chroma problems (rainbowing, etc.) that are | |
4621 | causing problems for the combed frame detection with chroma enabled. Actually, | |
4622 | using @option{chroma}=@var{0} is usually more reliable, except for the case | |
4623 | where there is chroma only combing in the source. | |
4624 | ||
4625 | Default value is @code{0}. | |
4626 | ||
4627 | @item blockx | |
4628 | @item blocky | |
4629 | Respectively set the x-axis and y-axis size of the window used during combed | |
4630 | frame detection. This has to do with the size of the area in which | |
4631 | @option{combpel} pixels are required to be detected as combed for a frame to be | |
4632 | declared combed. See the @option{combpel} parameter description for more info. | |
4633 | Possible values are any number that is a power of 2 starting at 4 and going up | |
4634 | to 512. | |
4635 | ||
4636 | Default value is @code{16}. | |
4637 | ||
4638 | @item combpel | |
4639 | The number of combed pixels inside any of the @option{blocky} by | |
4640 | @option{blockx} size blocks on the frame for the frame to be detected as | |
4641 | combed. While @option{cthresh} controls how "visible" the combing must be, this | |
4642 | setting controls "how much" combing there must be in any localized area (a | |
4643 | window defined by the @option{blockx} and @option{blocky} settings) on the | |
4644 | frame. Minimum value is @code{0} and maximum is @code{blocky x blockx} (at | |
4645 | which point no frames will ever be detected as combed). This setting is known | |
4646 | as @option{MI} in TFM/VFM vocabulary. | |
4647 | ||
4648 | Default value is @code{80}. | |
4649 | @end table | |
4650 | ||
4651 | @anchor{p/c/n/u/b meaning} | |
4652 | @subsection p/c/n/u/b meaning | |
4653 | ||
4654 | @subsubsection p/c/n | |
4655 | ||
4656 | We assume the following telecined stream: | |
4657 | ||
4658 | @example | |
4659 | Top fields: 1 2 2 3 4 | |
4660 | Bottom fields: 1 2 3 4 4 | |
4661 | @end example | |
4662 | ||
4663 | The numbers correspond to the progressive frame the fields relate to. Here, the | |
4664 | first two frames are progressive, the 3rd and 4th are combed, and so on. | |
4665 | ||
4666 | When @code{fieldmatch} is configured to run a matching from bottom | |
4667 | (@option{field}=@var{bottom}) this is how this input stream get transformed: | |
4668 | ||
4669 | @example | |
4670 | Input stream: | |
4671 | T 1 2 2 3 4 | |
4672 | B 1 2 3 4 4 <-- matching reference | |
4673 | ||
4674 | Matches: c c n n c | |
4675 | ||
4676 | Output stream: | |
4677 | T 1 2 3 4 4 | |
4678 | B 1 2 3 4 4 | |
4679 | @end example | |
4680 | ||
4681 | As a result of the field matching, we can see that some frames get duplicated. | |
4682 | To perform a complete inverse telecine, you need to rely on a decimation filter | |
4683 | after this operation. See for instance the @ref{decimate} filter. | |
4684 | ||
4685 | The same operation now matching from top fields (@option{field}=@var{top}) | |
4686 | looks like this: | |
4687 | ||
4688 | @example | |
4689 | Input stream: | |
4690 | T 1 2 2 3 4 <-- matching reference | |
4691 | B 1 2 3 4 4 | |
4692 | ||
4693 | Matches: c c p p c | |
4694 | ||
4695 | Output stream: | |
4696 | T 1 2 2 3 4 | |
4697 | B 1 2 2 3 4 | |
4698 | @end example | |
4699 | ||
4700 | In these examples, we can see what @var{p}, @var{c} and @var{n} mean; | |
4701 | basically, they refer to the frame and field of the opposite parity: | |
4702 | ||
4703 | @itemize | |
4704 | @item @var{p} matches the field of the opposite parity in the previous frame | |
4705 | @item @var{c} matches the field of the opposite parity in the current frame | |
4706 | @item @var{n} matches the field of the opposite parity in the next frame | |
4707 | @end itemize | |
4708 | ||
4709 | @subsubsection u/b | |
4710 | ||
4711 | The @var{u} and @var{b} matching are a bit special in the sense that they match | |
4712 | from the opposite parity flag. In the following examples, we assume that we are | |
4713 | currently matching the 2nd frame (Top:2, bottom:2). According to the match, a | |
4714 | 'x' is placed above and below each matched fields. | |
4715 | ||
4716 | With bottom matching (@option{field}=@var{bottom}): | |
4717 | @example | |
4718 | Match: c p n b u | |
4719 | ||
4720 | x x x x x | |
4721 | Top 1 2 2 1 2 2 1 2 2 1 2 2 1 2 2 | |
4722 | Bottom 1 2 3 1 2 3 1 2 3 1 2 3 1 2 3 | |
4723 | x x x x x | |
4724 | ||
4725 | Output frames: | |
4726 | 2 1 2 2 2 | |
4727 | 2 2 2 1 3 | |
4728 | @end example | |
4729 | ||
4730 | With top matching (@option{field}=@var{top}): | |
4731 | @example | |
4732 | Match: c p n b u | |
4733 | ||
4734 | x x x x x | |
4735 | Top 1 2 2 1 2 2 1 2 2 1 2 2 1 2 2 | |
4736 | Bottom 1 2 3 1 2 3 1 2 3 1 2 3 1 2 3 | |
4737 | x x x x x | |
4738 | ||
4739 | Output frames: | |
4740 | 2 2 2 1 2 | |
4741 | 2 1 3 2 2 | |
4742 | @end example | |
4743 | ||
4744 | @subsection Examples | |
4745 | ||
4746 | Simple IVTC of a top field first telecined stream: | |
4747 | @example | |
4748 | fieldmatch=order=tff:combmatch=none, decimate | |
4749 | @end example | |
4750 | ||
4751 | Advanced IVTC, with fallback on @ref{yadif} for still combed frames: | |
4752 | @example | |
4753 | fieldmatch=order=tff:combmatch=full, yadif=deint=interlaced, decimate | |
4754 | @end example | |
4755 | ||
4756 | @section fieldorder | |
4757 | ||
4758 | Transform the field order of the input video. | |
4759 | ||
4760 | It accepts the following parameters: | |
4761 | ||
4762 | @table @option | |
4763 | ||
4764 | @item order | |
4765 | The output field order. Valid values are @var{tff} for top field first or @var{bff} | |
4766 | for bottom field first. | |
4767 | @end table | |
4768 | ||
4769 | The default value is @samp{tff}. | |
4770 | ||
4771 | The transformation is done by shifting the picture content up or down | |
4772 | by one line, and filling the remaining line with appropriate picture content. | |
4773 | This method is consistent with most broadcast field order converters. | |
4774 | ||
4775 | If the input video is not flagged as being interlaced, or it is already | |
4776 | flagged as being of the required output field order, then this filter does | |
4777 | not alter the incoming video. | |
4778 | ||
4779 | It is very useful when converting to or from PAL DV material, | |
4780 | which is bottom field first. | |
4781 | ||
4782 | For example: | |
4783 | @example | |
4784 | ffmpeg -i in.vob -vf "fieldorder=bff" out.dv | |
4785 | @end example | |
4786 | ||
4787 | @section fifo | |
4788 | ||
4789 | Buffer input images and send them when they are requested. | |
4790 | ||
4791 | It is mainly useful when auto-inserted by the libavfilter | |
4792 | framework. | |
4793 | ||
4794 | It does not take parameters. | |
4795 | ||
4796 | @anchor{format} | |
4797 | @section format | |
4798 | ||
4799 | Convert the input video to one of the specified pixel formats. | |
4800 | Libavfilter will try to pick one that is suitable as input to | |
4801 | the next filter. | |
4802 | ||
4803 | It accepts the following parameters: | |
4804 | @table @option | |
4805 | ||
4806 | @item pix_fmts | |
4807 | A '|'-separated list of pixel format names, such as | |
4808 | "pix_fmts=yuv420p|monow|rgb24". | |
4809 | ||
4810 | @end table | |
4811 | ||
4812 | @subsection Examples | |
4813 | ||
4814 | @itemize | |
4815 | @item | |
4816 | Convert the input video to the @var{yuv420p} format | |
4817 | @example | |
4818 | format=pix_fmts=yuv420p | |
4819 | @end example | |
4820 | ||
4821 | Convert the input video to any of the formats in the list | |
4822 | @example | |
4823 | format=pix_fmts=yuv420p|yuv444p|yuv410p | |
4824 | @end example | |
4825 | @end itemize | |
4826 | ||
4827 | @anchor{fps} | |
4828 | @section fps | |
4829 | ||
4830 | Convert the video to specified constant frame rate by duplicating or dropping | |
4831 | frames as necessary. | |
4832 | ||
4833 | It accepts the following parameters: | |
4834 | @table @option | |
4835 | ||
4836 | @item fps | |
4837 | The desired output frame rate. The default is @code{25}. | |
4838 | ||
4839 | @item round | |
4840 | Rounding method. | |
4841 | ||
4842 | Possible values are: | |
4843 | @table @option | |
4844 | @item zero | |
4845 | zero round towards 0 | |
4846 | @item inf | |
4847 | round away from 0 | |
4848 | @item down | |
4849 | round towards -infinity | |
4850 | @item up | |
4851 | round towards +infinity | |
4852 | @item near | |
4853 | round to nearest | |
4854 | @end table | |
4855 | The default is @code{near}. | |
4856 | ||
4857 | @item start_time | |
4858 | Assume the first PTS should be the given value, in seconds. This allows for | |
4859 | padding/trimming at the start of stream. By default, no assumption is made | |
4860 | about the first frame's expected PTS, so no padding or trimming is done. | |
4861 | For example, this could be set to 0 to pad the beginning with duplicates of | |
4862 | the first frame if a video stream starts after the audio stream or to trim any | |
4863 | frames with a negative PTS. | |
4864 | ||
4865 | @end table | |
4866 | ||
4867 | Alternatively, the options can be specified as a flat string: | |
4868 | @var{fps}[:@var{round}]. | |
4869 | ||
4870 | See also the @ref{setpts} filter. | |
4871 | ||
4872 | @subsection Examples | |
4873 | ||
4874 | @itemize | |
4875 | @item | |
4876 | A typical usage in order to set the fps to 25: | |
4877 | @example | |
4878 | fps=fps=25 | |
4879 | @end example | |
4880 | ||
4881 | @item | |
4882 | Sets the fps to 24, using abbreviation and rounding method to round to nearest: | |
4883 | @example | |
4884 | fps=fps=film:round=near | |
4885 | @end example | |
4886 | @end itemize | |
4887 | ||
4888 | @section framepack | |
4889 | ||
4890 | Pack two different video streams into a stereoscopic video, setting proper | |
4891 | metadata on supported codecs. The two views should have the same size and | |
4892 | framerate and processing will stop when the shorter video ends. Please note | |
4893 | that you may conveniently adjust view properties with the @ref{scale} and | |
4894 | @ref{fps} filters. | |
4895 | ||
4896 | It accepts the following parameters: | |
4897 | @table @option | |
4898 | ||
4899 | @item format | |
4900 | The desired packing format. Supported values are: | |
4901 | ||
4902 | @table @option | |
4903 | ||
4904 | @item sbs | |
4905 | The views are next to each other (default). | |
4906 | ||
4907 | @item tab | |
4908 | The views are on top of each other. | |
4909 | ||
4910 | @item lines | |
4911 | The views are packed by line. | |
4912 | ||
4913 | @item columns | |
4914 | The views are packed by column. | |
4915 | ||
4916 | @item frameseq | |
4917 | The views are temporally interleaved. | |
4918 | ||
4919 | @end table | |
4920 | ||
4921 | @end table | |
4922 | ||
4923 | Some examples: | |
4924 | ||
4925 | @example | |
4926 | # Convert left and right views into a frame-sequential video | |
4927 | ffmpeg -i LEFT -i RIGHT -filter_complex framepack=frameseq OUTPUT | |
4928 | ||
4929 | # Convert views into a side-by-side video with the same output resolution as the input | |
4930 | 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 | |
4931 | @end example | |
4932 | ||
4933 | @section framestep | |
4934 | ||
4935 | Select one frame every N-th frame. | |
4936 | ||
4937 | This filter accepts the following option: | |
4938 | @table @option | |
4939 | @item step | |
4940 | Select frame after every @code{step} frames. | |
4941 | Allowed values are positive integers higher than 0. Default value is @code{1}. | |
4942 | @end table | |
4943 | ||
4944 | @anchor{frei0r} | |
4945 | @section frei0r | |
4946 | ||
4947 | Apply a frei0r effect to the input video. | |
4948 | ||
4949 | To enable the compilation of this filter, you need to install the frei0r | |
4950 | header and configure FFmpeg with @code{--enable-frei0r}. | |
4951 | ||
4952 | It accepts the following parameters: | |
4953 | ||
4954 | @table @option | |
4955 | ||
4956 | @item filter_name | |
4957 | The name of the frei0r effect to load. If the environment variable | |
4958 | @env{FREI0R_PATH} is defined, the frei0r effect is searched for in each of the | |
4959 | directories specified by the colon-separated list in @env{FREIOR_PATH}. | |
4960 | Otherwise, the standard frei0r paths are searched, in this order: | |
4961 | @file{HOME/.frei0r-1/lib/}, @file{/usr/local/lib/frei0r-1/}, | |
4962 | @file{/usr/lib/frei0r-1/}. | |
4963 | ||
4964 | @item filter_params | |
4965 | A '|'-separated list of parameters to pass to the frei0r effect. | |
4966 | ||
4967 | @end table | |
4968 | ||
4969 | A frei0r effect parameter can be a boolean (its value is either | |
4970 | "y" or "n"), a double, a color (specified as | |
4971 | @var{R}/@var{G}/@var{B}, where @var{R}, @var{G}, and @var{B} are floating point | |
4972 | numbers between 0.0 and 1.0, inclusive) or by a color description specified in the "Color" | |
4973 | section in the ffmpeg-utils manual), a position (specified as @var{X}/@var{Y}, where | |
4974 | @var{X} and @var{Y} are floating point numbers) and/or a string. | |
4975 | ||
4976 | The number and types of parameters depend on the loaded effect. If an | |
4977 | effect parameter is not specified, the default value is set. | |
4978 | ||
4979 | @subsection Examples | |
4980 | ||
4981 | @itemize | |
4982 | @item | |
4983 | Apply the distort0r effect, setting the first two double parameters: | |
4984 | @example | |
4985 | frei0r=filter_name=distort0r:filter_params=0.5|0.01 | |
4986 | @end example | |
4987 | ||
4988 | @item | |
4989 | Apply the colordistance effect, taking a color as the first parameter: | |
4990 | @example | |
4991 | frei0r=colordistance:0.2/0.3/0.4 | |
4992 | frei0r=colordistance:violet | |
4993 | frei0r=colordistance:0x112233 | |
4994 | @end example | |
4995 | ||
4996 | @item | |
4997 | Apply the perspective effect, specifying the top left and top right image | |
4998 | positions: | |
4999 | @example | |
5000 | frei0r=perspective:0.2/0.2|0.8/0.2 | |
5001 | @end example | |
5002 | @end itemize | |
5003 | ||
5004 | For more information, see | |
5005 | @url{http://frei0r.dyne.org} | |
5006 | ||
5007 | @section geq | |
5008 | ||
5009 | The filter accepts the following options: | |
5010 | ||
5011 | @table @option | |
5012 | @item lum_expr, lum | |
5013 | Set the luminance expression. | |
5014 | @item cb_expr, cb | |
5015 | Set the chrominance blue expression. | |
5016 | @item cr_expr, cr | |
5017 | Set the chrominance red expression. | |
5018 | @item alpha_expr, a | |
5019 | Set the alpha expression. | |
5020 | @item red_expr, r | |
5021 | Set the red expression. | |
5022 | @item green_expr, g | |
5023 | Set the green expression. | |
5024 | @item blue_expr, b | |
5025 | Set the blue expression. | |
5026 | @end table | |
5027 | ||
5028 | The colorspace is selected according to the specified options. If one | |
5029 | of the @option{lum_expr}, @option{cb_expr}, or @option{cr_expr} | |
5030 | options is specified, the filter will automatically select a YCbCr | |
5031 | colorspace. If one of the @option{red_expr}, @option{green_expr}, or | |
5032 | @option{blue_expr} options is specified, it will select an RGB | |
5033 | colorspace. | |
5034 | ||
5035 | If one of the chrominance expression is not defined, it falls back on the other | |
5036 | one. If no alpha expression is specified it will evaluate to opaque value. | |
5037 | If none of chrominance expressions are specified, they will evaluate | |
5038 | to the luminance expression. | |
5039 | ||
5040 | The expressions can use the following variables and functions: | |
5041 | ||
5042 | @table @option | |
5043 | @item N | |
5044 | The sequential number of the filtered frame, starting from @code{0}. | |
5045 | ||
5046 | @item X | |
5047 | @item Y | |
5048 | The coordinates of the current sample. | |
5049 | ||
5050 | @item W | |
5051 | @item H | |
5052 | The width and height of the image. | |
5053 | ||
5054 | @item SW | |
5055 | @item SH | |
5056 | Width and height scale depending on the currently filtered plane. It is the | |
5057 | ratio between the corresponding luma plane number of pixels and the current | |
5058 | plane ones. E.g. for YUV4:2:0 the values are @code{1,1} for the luma plane, and | |
5059 | @code{0.5,0.5} for chroma planes. | |
5060 | ||
5061 | @item T | |
5062 | Time of the current frame, expressed in seconds. | |
5063 | ||
5064 | @item p(x, y) | |
5065 | Return the value of the pixel at location (@var{x},@var{y}) of the current | |
5066 | plane. | |
5067 | ||
5068 | @item lum(x, y) | |
5069 | Return the value of the pixel at location (@var{x},@var{y}) of the luminance | |
5070 | plane. | |
5071 | ||
5072 | @item cb(x, y) | |
5073 | Return the value of the pixel at location (@var{x},@var{y}) of the | |
5074 | blue-difference chroma plane. Return 0 if there is no such plane. | |
5075 | ||
5076 | @item cr(x, y) | |
5077 | Return the value of the pixel at location (@var{x},@var{y}) of the | |
5078 | red-difference chroma plane. Return 0 if there is no such plane. | |
5079 | ||
5080 | @item r(x, y) | |
5081 | @item g(x, y) | |
5082 | @item b(x, y) | |
5083 | Return the value of the pixel at location (@var{x},@var{y}) of the | |
5084 | red/green/blue component. Return 0 if there is no such component. | |
5085 | ||
5086 | @item alpha(x, y) | |
5087 | Return the value of the pixel at location (@var{x},@var{y}) of the alpha | |
5088 | plane. Return 0 if there is no such plane. | |
5089 | @end table | |
5090 | ||
5091 | For functions, if @var{x} and @var{y} are outside the area, the value will be | |
5092 | automatically clipped to the closer edge. | |
5093 | ||
5094 | @subsection Examples | |
5095 | ||
5096 | @itemize | |
5097 | @item | |
5098 | Flip the image horizontally: | |
5099 | @example | |
5100 | geq=p(W-X\,Y) | |
5101 | @end example | |
5102 | ||
5103 | @item | |
5104 | Generate a bidimensional sine wave, with angle @code{PI/3} and a | |
5105 | wavelength of 100 pixels: | |
5106 | @example | |
5107 | geq=128 + 100*sin(2*(PI/100)*(cos(PI/3)*(X-50*T) + sin(PI/3)*Y)):128:128 | |
5108 | @end example | |
5109 | ||
5110 | @item | |
5111 | Generate a fancy enigmatic moving light: | |
5112 | @example | |
5113 | 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 | |
5114 | @end example | |
5115 | ||
5116 | @item | |
5117 | Generate a quick emboss effect: | |
5118 | @example | |
5119 | format=gray,geq=lum_expr='(p(X,Y)+(256-p(X-4,Y-4)))/2' | |
5120 | @end example | |
5121 | ||
5122 | @item | |
5123 | Modify RGB components depending on pixel position: | |
5124 | @example | |
5125 | geq=r='X/W*r(X,Y)':g='(1-X/W)*g(X,Y)':b='(H-Y)/H*b(X,Y)' | |
5126 | @end example | |
5127 | @end itemize | |
5128 | ||
5129 | @section gradfun | |
5130 | ||
5131 | Fix the banding artifacts that are sometimes introduced into nearly flat | |
5132 | regions by truncation to 8bit color depth. | |
5133 | Interpolate the gradients that should go where the bands are, and | |
5134 | dither them. | |
5135 | ||
5136 | It is designed for playback only. Do not use it prior to | |
5137 | lossy compression, because compression tends to lose the dither and | |
5138 | bring back the bands. | |
5139 | ||
5140 | It accepts the following parameters: | |
5141 | ||
5142 | @table @option | |
5143 | ||
5144 | @item strength | |
5145 | The maximum amount by which the filter will change any one pixel. This is also | |
5146 | the threshold for detecting nearly flat regions. Acceptable values range from | |
5147 | .51 to 64; the default value is 1.2. Out-of-range values will be clipped to the | |
5148 | valid range. | |
5149 | ||
5150 | @item radius | |
5151 | The neighborhood to fit the gradient to. A larger radius makes for smoother | |
5152 | gradients, but also prevents the filter from modifying the pixels near detailed | |
5153 | regions. Acceptable values are 8-32; the default value is 16. Out-of-range | |
5154 | values will be clipped to the valid range. | |
5155 | ||
5156 | @end table | |
5157 | ||
5158 | Alternatively, the options can be specified as a flat string: | |
5159 | @var{strength}[:@var{radius}] | |
5160 | ||
5161 | @subsection Examples | |
5162 | ||
5163 | @itemize | |
5164 | @item | |
5165 | Apply the filter with a @code{3.5} strength and radius of @code{8}: | |
5166 | @example | |
5167 | gradfun=3.5:8 | |
5168 | @end example | |
5169 | ||
5170 | @item | |
5171 | Specify radius, omitting the strength (which will fall-back to the default | |
5172 | value): | |
5173 | @example | |
5174 | gradfun=radius=8 | |
5175 | @end example | |
5176 | ||
5177 | @end itemize | |
5178 | ||
5179 | @anchor{haldclut} | |
5180 | @section haldclut | |
5181 | ||
5182 | Apply a Hald CLUT to a video stream. | |
5183 | ||
5184 | First input is the video stream to process, and second one is the Hald CLUT. | |
5185 | The Hald CLUT input can be a simple picture or a complete video stream. | |
5186 | ||
5187 | The filter accepts the following options: | |
5188 | ||
5189 | @table @option | |
5190 | @item shortest | |
5191 | Force termination when the shortest input terminates. Default is @code{0}. | |
5192 | @item repeatlast | |
5193 | Continue applying the last CLUT after the end of the stream. A value of | |
5194 | @code{0} disable the filter after the last frame of the CLUT is reached. | |
5195 | Default is @code{1}. | |
5196 | @end table | |
5197 | ||
5198 | @code{haldclut} also has the same interpolation options as @ref{lut3d} (both | |
5199 | filters share the same internals). | |
5200 | ||
5201 | More information about the Hald CLUT can be found on Eskil Steenberg's website | |
5202 | (Hald CLUT author) at @url{http://www.quelsolaar.com/technology/clut.html}. | |
5203 | ||
5204 | @subsection Workflow examples | |
5205 | ||
5206 | @subsubsection Hald CLUT video stream | |
5207 | ||
5208 | Generate an identity Hald CLUT stream altered with various effects: | |
5209 | @example | |
5210 | 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 | |
5211 | @end example | |
5212 | ||
5213 | Note: make sure you use a lossless codec. | |
5214 | ||
5215 | Then use it with @code{haldclut} to apply it on some random stream: | |
5216 | @example | |
5217 | ffmpeg -f lavfi -i mandelbrot -i clut.nut -filter_complex '[0][1] haldclut' -t 20 mandelclut.mkv | |
5218 | @end example | |
5219 | ||
5220 | The Hald CLUT will be applied to the 10 first seconds (duration of | |
5221 | @file{clut.nut}), then the latest picture of that CLUT stream will be applied | |
5222 | to the remaining frames of the @code{mandelbrot} stream. | |
5223 | ||
5224 | @subsubsection Hald CLUT with preview | |
5225 | ||
5226 | A Hald CLUT is supposed to be a squared image of @code{Level*Level*Level} by | |
5227 | @code{Level*Level*Level} pixels. For a given Hald CLUT, FFmpeg will select the | |
5228 | biggest possible square starting at the top left of the picture. The remaining | |
5229 | padding pixels (bottom or right) will be ignored. This area can be used to add | |
5230 | a preview of the Hald CLUT. | |
5231 | ||
5232 | Typically, the following generated Hald CLUT will be supported by the | |
5233 | @code{haldclut} filter: | |
5234 | ||
5235 | @example | |
5236 | ffmpeg -f lavfi -i @ref{haldclutsrc}=8 -vf " | |
5237 | pad=iw+320 [padded_clut]; | |
5238 | smptebars=s=320x256, split [a][b]; | |
5239 | [padded_clut][a] overlay=W-320:h, curves=color_negative [main]; | |
5240 | [main][b] overlay=W-320" -frames:v 1 clut.png | |
5241 | @end example | |
5242 | ||
5243 | It contains the original and a preview of the effect of the CLUT: SMPTE color | |
5244 | bars are displayed on the right-top, and below the same color bars processed by | |
5245 | the color changes. | |
5246 | ||
5247 | Then, the effect of this Hald CLUT can be visualized with: | |
5248 | @example | |
5249 | ffplay input.mkv -vf "movie=clut.png, [in] haldclut" | |
5250 | @end example | |
5251 | ||
5252 | @section hflip | |
5253 | ||
5254 | Flip the input video horizontally. | |
5255 | ||
5256 | For example, to horizontally flip the input video with @command{ffmpeg}: | |
5257 | @example | |
5258 | ffmpeg -i in.avi -vf "hflip" out.avi | |
5259 | @end example | |
5260 | ||
5261 | @section histeq | |
5262 | This filter applies a global color histogram equalization on a | |
5263 | per-frame basis. | |
5264 | ||
5265 | It can be used to correct video that has a compressed range of pixel | |
5266 | intensities. The filter redistributes the pixel intensities to | |
5267 | equalize their distribution across the intensity range. It may be | |
5268 | viewed as an "automatically adjusting contrast filter". This filter is | |
5269 | useful only for correcting degraded or poorly captured source | |
5270 | video. | |
5271 | ||
5272 | The filter accepts the following options: | |
5273 | ||
5274 | @table @option | |
5275 | @item strength | |
5276 | Determine the amount of equalization to be applied. As the strength | |
5277 | is reduced, the distribution of pixel intensities more-and-more | |
5278 | approaches that of the input frame. The value must be a float number | |
5279 | in the range [0,1] and defaults to 0.200. | |
5280 | ||
5281 | @item intensity | |
5282 | Set the maximum intensity that can generated and scale the output | |
5283 | values appropriately. The strength should be set as desired and then | |
5284 | the intensity can be limited if needed to avoid washing-out. The value | |
5285 | must be a float number in the range [0,1] and defaults to 0.210. | |
5286 | ||
5287 | @item antibanding | |
5288 | Set the antibanding level. If enabled the filter will randomly vary | |
5289 | the luminance of output pixels by a small amount to avoid banding of | |
5290 | the histogram. Possible values are @code{none}, @code{weak} or | |
5291 | @code{strong}. It defaults to @code{none}. | |
5292 | @end table | |
5293 | ||
5294 | @section histogram | |
5295 | ||
5296 | Compute and draw a color distribution histogram for the input video. | |
5297 | ||
5298 | The computed histogram is a representation of the color component | |
5299 | distribution in an image. | |
5300 | ||
5301 | The filter accepts the following options: | |
5302 | ||
5303 | @table @option | |
5304 | @item mode | |
5305 | Set histogram mode. | |
5306 | ||
5307 | It accepts the following values: | |
5308 | @table @samp | |
5309 | @item levels | |
5310 | Standard histogram that displays the color components distribution in an | |
5311 | image. Displays color graph for each color component. Shows distribution of | |
5312 | the Y, U, V, A or R, G, B components, depending on input format, in the | |
5313 | current frame. Below each graph a color component scale meter is shown. | |
5314 | ||
5315 | @item color | |
5316 | Displays chroma values (U/V color placement) in a two dimensional | |
5317 | graph (which is called a vectorscope). The brighter a pixel in the | |
5318 | vectorscope, the more pixels of the input frame correspond to that pixel | |
5319 | (i.e., more pixels have this chroma value). The V component is displayed on | |
5320 | the horizontal (X) axis, with the leftmost side being V = 0 and the rightmost | |
5321 | side being V = 255. The U component is displayed on the vertical (Y) axis, | |
5322 | with the top representing U = 0 and the bottom representing U = 255. | |
5323 | ||
5324 | The position of a white pixel in the graph corresponds to the chroma value of | |
5325 | a pixel of the input clip. The graph can therefore be used to read the hue | |
5326 | (color flavor) and the saturation (the dominance of the hue in the color). As | |
5327 | the hue of a color changes, it moves around the square. At the center of the | |
5328 | square the saturation is zero, which means that the corresponding pixel has no | |
5329 | color. If the amount of a specific color is increased (while leaving the other | |
5330 | colors unchanged) the saturation increases, and the indicator moves towards | |
5331 | the edge of the square. | |
5332 | ||
5333 | @item color2 | |
5334 | Chroma values in vectorscope, similar as @code{color} but actual chroma values | |
5335 | are displayed. | |
5336 | ||
5337 | @item waveform | |
5338 | Per row/column color component graph. In row mode, the graph on the left side | |
5339 | represents color component value 0 and the right side represents value = 255. | |
5340 | In column mode, the top side represents color component value = 0 and bottom | |
5341 | side represents value = 255. | |
5342 | @end table | |
5343 | Default value is @code{levels}. | |
5344 | ||
5345 | @item level_height | |
5346 | Set height of level in @code{levels}. Default value is @code{200}. | |
5347 | Allowed range is [50, 2048]. | |
5348 | ||
5349 | @item scale_height | |
5350 | Set height of color scale in @code{levels}. Default value is @code{12}. | |
5351 | Allowed range is [0, 40]. | |
5352 | ||
5353 | @item step | |
5354 | Set step for @code{waveform} mode. Smaller values are useful to find out how | |
5355 | many values of the same luminance are distributed across input rows/columns. | |
5356 | Default value is @code{10}. Allowed range is [1, 255]. | |
5357 | ||
5358 | @item waveform_mode | |
5359 | Set mode for @code{waveform}. Can be either @code{row}, or @code{column}. | |
5360 | Default is @code{row}. | |
5361 | ||
5362 | @item waveform_mirror | |
5363 | Set mirroring mode for @code{waveform}. @code{0} means unmirrored, @code{1} | |
5364 | means mirrored. In mirrored mode, higher values will be represented on the left | |
5365 | side for @code{row} mode and at the top for @code{column} mode. Default is | |
5366 | @code{0} (unmirrored). | |
5367 | ||
5368 | @item display_mode | |
5369 | Set display mode for @code{waveform} and @code{levels}. | |
5370 | It accepts the following values: | |
5371 | @table @samp | |
5372 | @item parade | |
5373 | Display separate graph for the color components side by side in | |
5374 | @code{row} waveform mode or one below the other in @code{column} waveform mode | |
5375 | for @code{waveform} histogram mode. For @code{levels} histogram mode, | |
5376 | per color component graphs are placed below each other. | |
5377 | ||
5378 | Using this display mode in @code{waveform} histogram mode makes it easy to | |
5379 | spot color casts in the highlights and shadows of an image, by comparing the | |
5380 | contours of the top and the bottom graphs of each waveform. Since whites, | |
5381 | grays, and blacks are characterized by exactly equal amounts of red, green, | |
5382 | and blue, neutral areas of the picture should display three waveforms of | |
5383 | roughly equal width/height. If not, the correction is easy to perform by | |
5384 | making level adjustments the three waveforms. | |
5385 | ||
5386 | @item overlay | |
5387 | Presents information identical to that in the @code{parade}, except | |
5388 | that the graphs representing color components are superimposed directly | |
5389 | over one another. | |
5390 | ||
5391 | This display mode in @code{waveform} histogram mode makes it easier to spot | |
5392 | relative differences or similarities in overlapping areas of the color | |
5393 | components that are supposed to be identical, such as neutral whites, grays, | |
5394 | or blacks. | |
5395 | @end table | |
5396 | Default is @code{parade}. | |
5397 | ||
5398 | @item levels_mode | |
5399 | Set mode for @code{levels}. Can be either @code{linear}, or @code{logarithmic}. | |
5400 | Default is @code{linear}. | |
5401 | @end table | |
5402 | ||
5403 | @subsection Examples | |
5404 | ||
5405 | @itemize | |
5406 | ||
5407 | @item | |
5408 | Calculate and draw histogram: | |
5409 | @example | |
5410 | ffplay -i input -vf histogram | |
5411 | @end example | |
5412 | ||
5413 | @end itemize | |
5414 | ||
5415 | @anchor{hqdn3d} | |
5416 | @section hqdn3d | |
5417 | ||
5418 | This is a high precision/quality 3d denoise filter. It aims to reduce | |
5419 | image noise, producing smooth images and making still images really | |
5420 | still. It should enhance compressibility. | |
5421 | ||
5422 | It accepts the following optional parameters: | |
5423 | ||
5424 | @table @option | |
5425 | @item luma_spatial | |
5426 | A non-negative floating point number which specifies spatial luma strength. | |
5427 | It defaults to 4.0. | |
5428 | ||
5429 | @item chroma_spatial | |
5430 | A non-negative floating point number which specifies spatial chroma strength. | |
5431 | It defaults to 3.0*@var{luma_spatial}/4.0. | |
5432 | ||
5433 | @item luma_tmp | |
5434 | A floating point number which specifies luma temporal strength. It defaults to | |
5435 | 6.0*@var{luma_spatial}/4.0. | |
5436 | ||
5437 | @item chroma_tmp | |
5438 | A floating point number which specifies chroma temporal strength. It defaults to | |
5439 | @var{luma_tmp}*@var{chroma_spatial}/@var{luma_spatial}. | |
5440 | @end table | |
5441 | ||
5442 | @section hqx | |
5443 | ||
5444 | Apply a high-quality magnification filter designed for pixel art. This filter | |
5445 | was originally created by Maxim Stepin. | |
5446 | ||
5447 | It accepts the following option: | |
5448 | ||
5449 | @table @option | |
5450 | @item n | |
5451 | Set the scaling dimension: @code{2} for @code{hq2x}, @code{3} for | |
5452 | @code{hq3x} and @code{4} for @code{hq4x}. | |
5453 | Default is @code{3}. | |
5454 | @end table | |
5455 | ||
5456 | @section hue | |
5457 | ||
5458 | Modify the hue and/or the saturation of the input. | |
5459 | ||
5460 | It accepts the following parameters: | |
5461 | ||
5462 | @table @option | |
5463 | @item h | |
5464 | Specify the hue angle as a number of degrees. It accepts an expression, | |
5465 | and defaults to "0". | |
5466 | ||
5467 | @item s | |
5468 | Specify the saturation in the [-10,10] range. It accepts an expression and | |
5469 | defaults to "1". | |
5470 | ||
5471 | @item H | |
5472 | Specify the hue angle as a number of radians. It accepts an | |
5473 | expression, and defaults to "0". | |
5474 | ||
5475 | @item b | |
5476 | Specify the brightness in the [-10,10] range. It accepts an expression and | |
5477 | defaults to "0". | |
5478 | @end table | |
5479 | ||
5480 | @option{h} and @option{H} are mutually exclusive, and can't be | |
5481 | specified at the same time. | |
5482 | ||
5483 | The @option{b}, @option{h}, @option{H} and @option{s} option values are | |
5484 | expressions containing the following constants: | |
5485 | ||
5486 | @table @option | |
5487 | @item n | |
5488 | frame count of the input frame starting from 0 | |
5489 | ||
5490 | @item pts | |
5491 | presentation timestamp of the input frame expressed in time base units | |
5492 | ||
5493 | @item r | |
5494 | frame rate of the input video, NAN if the input frame rate is unknown | |
5495 | ||
5496 | @item t | |
5497 | timestamp expressed in seconds, NAN if the input timestamp is unknown | |
5498 | ||
5499 | @item tb | |
5500 | time base of the input video | |
5501 | @end table | |
5502 | ||
5503 | @subsection Examples | |
5504 | ||
5505 | @itemize | |
5506 | @item | |
5507 | Set the hue to 90 degrees and the saturation to 1.0: | |
5508 | @example | |
5509 | hue=h=90:s=1 | |
5510 | @end example | |
5511 | ||
5512 | @item | |
5513 | Same command but expressing the hue in radians: | |
5514 | @example | |
5515 | hue=H=PI/2:s=1 | |
5516 | @end example | |
5517 | ||
5518 | @item | |
5519 | Rotate hue and make the saturation swing between 0 | |
5520 | and 2 over a period of 1 second: | |
5521 | @example | |
5522 | hue="H=2*PI*t: s=sin(2*PI*t)+1" | |
5523 | @end example | |
5524 | ||
5525 | @item | |
5526 | Apply a 3 seconds saturation fade-in effect starting at 0: | |
5527 | @example | |
5528 | hue="s=min(t/3\,1)" | |
5529 | @end example | |
5530 | ||
5531 | The general fade-in expression can be written as: | |
5532 | @example | |
5533 | hue="s=min(0\, max((t-START)/DURATION\, 1))" | |
5534 | @end example | |
5535 | ||
5536 | @item | |
5537 | Apply a 3 seconds saturation fade-out effect starting at 5 seconds: | |
5538 | @example | |
5539 | hue="s=max(0\, min(1\, (8-t)/3))" | |
5540 | @end example | |
5541 | ||
5542 | The general fade-out expression can be written as: | |
5543 | @example | |
5544 | hue="s=max(0\, min(1\, (START+DURATION-t)/DURATION))" | |
5545 | @end example | |
5546 | ||
5547 | @end itemize | |
5548 | ||
5549 | @subsection Commands | |
5550 | ||
5551 | This filter supports the following commands: | |
5552 | @table @option | |
5553 | @item b | |
5554 | @item s | |
5555 | @item h | |
5556 | @item H | |
5557 | Modify the hue and/or the saturation and/or brightness of the input video. | |
5558 | The command accepts the same syntax of the corresponding option. | |
5559 | ||
5560 | If the specified expression is not valid, it is kept at its current | |
5561 | value. | |
5562 | @end table | |
5563 | ||
5564 | @section idet | |
5565 | ||
5566 | Detect video interlacing type. | |
5567 | ||
5568 | This filter tries to detect if the input is interlaced or progressive, | |
5569 | top or bottom field first. | |
5570 | ||
5571 | The filter accepts the following options: | |
5572 | ||
5573 | @table @option | |
5574 | @item intl_thres | |
5575 | Set interlacing threshold. | |
5576 | @item prog_thres | |
5577 | Set progressive threshold. | |
5578 | @end table | |
5579 | ||
5580 | @section il | |
5581 | ||
5582 | Deinterleave or interleave fields. | |
5583 | ||
5584 | This filter allows one to process interlaced images fields without | |
5585 | deinterlacing them. Deinterleaving splits the input frame into 2 | |
5586 | fields (so called half pictures). Odd lines are moved to the top | |
5587 | half of the output image, even lines to the bottom half. | |
5588 | You can process (filter) them independently and then re-interleave them. | |
5589 | ||
5590 | The filter accepts the following options: | |
5591 | ||
5592 | @table @option | |
5593 | @item luma_mode, l | |
5594 | @item chroma_mode, c | |
5595 | @item alpha_mode, a | |
5596 | Available values for @var{luma_mode}, @var{chroma_mode} and | |
5597 | @var{alpha_mode} are: | |
5598 | ||
5599 | @table @samp | |
5600 | @item none | |
5601 | Do nothing. | |
5602 | ||
5603 | @item deinterleave, d | |
5604 | Deinterleave fields, placing one above the other. | |
5605 | ||
5606 | @item interleave, i | |
5607 | Interleave fields. Reverse the effect of deinterleaving. | |
5608 | @end table | |
5609 | Default value is @code{none}. | |
5610 | ||
5611 | @item luma_swap, ls | |
5612 | @item chroma_swap, cs | |
5613 | @item alpha_swap, as | |
5614 | Swap luma/chroma/alpha fields. Exchange even & odd lines. Default value is @code{0}. | |
5615 | @end table | |
5616 | ||
5617 | @section interlace | |
5618 | ||
5619 | Simple interlacing filter from progressive contents. This interleaves upper (or | |
5620 | lower) lines from odd frames with lower (or upper) lines from even frames, | |
5621 | halving the frame rate and preserving image height. | |
5622 | ||
5623 | @example | |
5624 | Original Original New Frame | |
5625 | Frame 'j' Frame 'j+1' (tff) | |
5626 | ========== =========== ================== | |
5627 | Line 0 --------------------> Frame 'j' Line 0 | |
5628 | Line 1 Line 1 ----> Frame 'j+1' Line 1 | |
5629 | Line 2 ---------------------> Frame 'j' Line 2 | |
5630 | Line 3 Line 3 ----> Frame 'j+1' Line 3 | |
5631 | ... ... ... | |
5632 | New Frame + 1 will be generated by Frame 'j+2' and Frame 'j+3' and so on | |
5633 | @end example | |
5634 | ||
5635 | It accepts the following optional parameters: | |
5636 | ||
5637 | @table @option | |
5638 | @item scan | |
5639 | This determines whether the interlaced frame is taken from the even | |
5640 | (tff - default) or odd (bff) lines of the progressive frame. | |
5641 | ||
5642 | @item lowpass | |
5643 | Enable (default) or disable the vertical lowpass filter to avoid twitter | |
5644 | interlacing and reduce moire patterns. | |
5645 | @end table | |
5646 | ||
5647 | @section kerndeint | |
5648 | ||
5649 | Deinterlace input video by applying Donald Graft's adaptive kernel | |
5650 | deinterling. Work on interlaced parts of a video to produce | |
5651 | progressive frames. | |
5652 | ||
5653 | The description of the accepted parameters follows. | |
5654 | ||
5655 | @table @option | |
5656 | @item thresh | |
5657 | Set the threshold which affects the filter's tolerance when | |
5658 | determining if a pixel line must be processed. It must be an integer | |
5659 | in the range [0,255] and defaults to 10. A value of 0 will result in | |
5660 | applying the process on every pixels. | |
5661 | ||
5662 | @item map | |
5663 | Paint pixels exceeding the threshold value to white if set to 1. | |
5664 | Default is 0. | |
5665 | ||
5666 | @item order | |
5667 | Set the fields order. Swap fields if set to 1, leave fields alone if | |
5668 | 0. Default is 0. | |
5669 | ||
5670 | @item sharp | |
5671 | Enable additional sharpening if set to 1. Default is 0. | |
5672 | ||
5673 | @item twoway | |
5674 | Enable twoway sharpening if set to 1. Default is 0. | |
5675 | @end table | |
5676 | ||
5677 | @subsection Examples | |
5678 | ||
5679 | @itemize | |
5680 | @item | |
5681 | Apply default values: | |
5682 | @example | |
5683 | kerndeint=thresh=10:map=0:order=0:sharp=0:twoway=0 | |
5684 | @end example | |
5685 | ||
5686 | @item | |
5687 | Enable additional sharpening: | |
5688 | @example | |
5689 | kerndeint=sharp=1 | |
5690 | @end example | |
5691 | ||
5692 | @item | |
5693 | Paint processed pixels in white: | |
5694 | @example | |
5695 | kerndeint=map=1 | |
5696 | @end example | |
5697 | @end itemize | |
5698 | ||
5699 | @section lenscorrection | |
5700 | ||
5701 | Correct radial lens distortion | |
5702 | ||
5703 | This filter can be used to correct for radial distortion as can result from the use | |
5704 | of wide angle lenses, and thereby re-rectify the image. To find the right parameters | |
5705 | one can use tools available for example as part of opencv or simply trial-and-error. | |
5706 | To use opencv use the calibration sample (under samples/cpp) from the opencv sources | |
5707 | and extract the k1 and k2 coefficients from the resulting matrix. | |
5708 | ||
5709 | Note that effectively the same filter is available in the open-source tools Krita and | |
5710 | Digikam from the KDE project. | |
5711 | ||
5712 | In contrast to the @ref{vignette} filter, which can also be used to compensate lens errors, | |
5713 | this filter corrects the distortion of the image, whereas @ref{vignette} corrects the | |
5714 | brightness distribution, so you may want to use both filters together in certain | |
5715 | cases, though you will have to take care of ordering, i.e. whether vignetting should | |
5716 | be applied before or after lens correction. | |
5717 | ||
5718 | @subsection Options | |
5719 | ||
5720 | The filter accepts the following options: | |
5721 | ||
5722 | @table @option | |
5723 | @item cx | |
5724 | Relative x-coordinate of the focal point of the image, and thereby the center of the | |
5725 | distrortion. This value has a range [0,1] and is expressed as fractions of the image | |
5726 | width. | |
5727 | @item cy | |
5728 | Relative y-coordinate of the focal point of the image, and thereby the center of the | |
5729 | distrortion. This value has a range [0,1] and is expressed as fractions of the image | |
5730 | height. | |
5731 | @item k1 | |
5732 | Coefficient of the quadratic correction term. 0.5 means no correction. | |
5733 | @item k2 | |
5734 | Coefficient of the double quadratic correction term. 0.5 means no correction. | |
5735 | @end table | |
5736 | ||
5737 | The formula that generates the correction is: | |
5738 | ||
5739 | @var{r_src} = @var{r_tgt} * (1 + @var{k1} * (@var{r_tgt} / @var{r_0})^2 + @var{k2} * (@var{r_tgt} / @var{r_0})^4) | |
5740 | ||
5741 | where @var{r_0} is halve of the image diagonal and @var{r_src} and @var{r_tgt} are the | |
5742 | distances from the focal point in the source and target images, respectively. | |
5743 | ||
5744 | @anchor{lut3d} | |
5745 | @section lut3d | |
5746 | ||
5747 | Apply a 3D LUT to an input video. | |
5748 | ||
5749 | The filter accepts the following options: | |
5750 | ||
5751 | @table @option | |
5752 | @item file | |
5753 | Set the 3D LUT file name. | |
5754 | ||
5755 | Currently supported formats: | |
5756 | @table @samp | |
5757 | @item 3dl | |
5758 | AfterEffects | |
5759 | @item cube | |
5760 | Iridas | |
5761 | @item dat | |
5762 | DaVinci | |
5763 | @item m3d | |
5764 | Pandora | |
5765 | @end table | |
5766 | @item interp | |
5767 | Select interpolation mode. | |
5768 | ||
5769 | Available values are: | |
5770 | ||
5771 | @table @samp | |
5772 | @item nearest | |
5773 | Use values from the nearest defined point. | |
5774 | @item trilinear | |
5775 | Interpolate values using the 8 points defining a cube. | |
5776 | @item tetrahedral | |
5777 | Interpolate values using a tetrahedron. | |
5778 | @end table | |
5779 | @end table | |
5780 | ||
5781 | @section lut, lutrgb, lutyuv | |
5782 | ||
5783 | Compute a look-up table for binding each pixel component input value | |
5784 | to an output value, and apply it to the input video. | |
5785 | ||
5786 | @var{lutyuv} applies a lookup table to a YUV input video, @var{lutrgb} | |
5787 | to an RGB input video. | |
5788 | ||
5789 | These filters accept the following parameters: | |
5790 | @table @option | |
5791 | @item c0 | |
5792 | set first pixel component expression | |
5793 | @item c1 | |
5794 | set second pixel component expression | |
5795 | @item c2 | |
5796 | set third pixel component expression | |
5797 | @item c3 | |
5798 | set fourth pixel component expression, corresponds to the alpha component | |
5799 | ||
5800 | @item r | |
5801 | set red component expression | |
5802 | @item g | |
5803 | set green component expression | |
5804 | @item b | |
5805 | set blue component expression | |
5806 | @item a | |
5807 | alpha component expression | |
5808 | ||
5809 | @item y | |
5810 | set Y/luminance component expression | |
5811 | @item u | |
5812 | set U/Cb component expression | |
5813 | @item v | |
5814 | set V/Cr component expression | |
5815 | @end table | |
5816 | ||
5817 | Each of them specifies the expression to use for computing the lookup table for | |
5818 | the corresponding pixel component values. | |
5819 | ||
5820 | The exact component associated to each of the @var{c*} options depends on the | |
5821 | format in input. | |
5822 | ||
5823 | The @var{lut} filter requires either YUV or RGB pixel formats in input, | |
5824 | @var{lutrgb} requires RGB pixel formats in input, and @var{lutyuv} requires YUV. | |
5825 | ||
5826 | The expressions can contain the following constants and functions: | |
5827 | ||
5828 | @table @option | |
5829 | @item w | |
5830 | @item h | |
5831 | The input width and height. | |
5832 | ||
5833 | @item val | |
5834 | The input value for the pixel component. | |
5835 | ||
5836 | @item clipval | |
5837 | The input value, clipped to the @var{minval}-@var{maxval} range. | |
5838 | ||
5839 | @item maxval | |
5840 | The maximum value for the pixel component. | |
5841 | ||
5842 | @item minval | |
5843 | The minimum value for the pixel component. | |
5844 | ||
5845 | @item negval | |
5846 | The negated value for the pixel component value, clipped to the | |
5847 | @var{minval}-@var{maxval} range; it corresponds to the expression | |
5848 | "maxval-clipval+minval". | |
5849 | ||
5850 | @item clip(val) | |
5851 | The computed value in @var{val}, clipped to the | |
5852 | @var{minval}-@var{maxval} range. | |
5853 | ||
5854 | @item gammaval(gamma) | |
5855 | The computed gamma correction value of the pixel component value, | |
5856 | clipped to the @var{minval}-@var{maxval} range. It corresponds to the | |
5857 | expression | |
5858 | "pow((clipval-minval)/(maxval-minval)\,@var{gamma})*(maxval-minval)+minval" | |
5859 | ||
5860 | @end table | |
5861 | ||
5862 | All expressions default to "val". | |
5863 | ||
5864 | @subsection Examples | |
5865 | ||
5866 | @itemize | |
5867 | @item | |
5868 | Negate input video: | |
5869 | @example | |
5870 | lutrgb="r=maxval+minval-val:g=maxval+minval-val:b=maxval+minval-val" | |
5871 | lutyuv="y=maxval+minval-val:u=maxval+minval-val:v=maxval+minval-val" | |
5872 | @end example | |
5873 | ||
5874 | The above is the same as: | |
5875 | @example | |
5876 | lutrgb="r=negval:g=negval:b=negval" | |
5877 | lutyuv="y=negval:u=negval:v=negval" | |
5878 | @end example | |
5879 | ||
5880 | @item | |
5881 | Negate luminance: | |
5882 | @example | |
5883 | lutyuv=y=negval | |
5884 | @end example | |
5885 | ||
5886 | @item | |
5887 | Remove chroma components, turning the video into a graytone image: | |
5888 | @example | |
5889 | lutyuv="u=128:v=128" | |
5890 | @end example | |
5891 | ||
5892 | @item | |
5893 | Apply a luma burning effect: | |
5894 | @example | |
5895 | lutyuv="y=2*val" | |
5896 | @end example | |
5897 | ||
5898 | @item | |
5899 | Remove green and blue components: | |
5900 | @example | |
5901 | lutrgb="g=0:b=0" | |
5902 | @end example | |
5903 | ||
5904 | @item | |
5905 | Set a constant alpha channel value on input: | |
5906 | @example | |
5907 | format=rgba,lutrgb=a="maxval-minval/2" | |
5908 | @end example | |
5909 | ||
5910 | @item | |
5911 | Correct luminance gamma by a factor of 0.5: | |
5912 | @example | |
5913 | lutyuv=y=gammaval(0.5) | |
5914 | @end example | |
5915 | ||
5916 | @item | |
5917 | Discard least significant bits of luma: | |
5918 | @example | |
5919 | lutyuv=y='bitand(val, 128+64+32)' | |
5920 | @end example | |
5921 | @end itemize | |
5922 | ||
5923 | @section mergeplanes | |
5924 | ||
5925 | Merge color channel components from several video streams. | |
5926 | ||
5927 | The filter accepts up to 4 input streams, and merge selected input | |
5928 | planes to the output video. | |
5929 | ||
5930 | This filter accepts the following options: | |
5931 | @table @option | |
5932 | @item mapping | |
5933 | Set input to output plane mapping. Default is @code{0}. | |
5934 | ||
5935 | The mappings is specified as a bitmap. It should be specified as a | |
5936 | hexadecimal number in the form 0xAa[Bb[Cc[Dd]]]. 'Aa' describes the | |
5937 | mapping for the first plane of the output stream. 'A' sets the number of | |
5938 | the input stream to use (from 0 to 3), and 'a' the plane number of the | |
5939 | corresponding input to use (from 0 to 3). The rest of the mappings is | |
5940 | similar, 'Bb' describes the mapping for the output stream second | |
5941 | plane, 'Cc' describes the mapping for the output stream third plane and | |
5942 | 'Dd' describes the mapping for the output stream fourth plane. | |
5943 | ||
5944 | @item format | |
5945 | Set output pixel format. Default is @code{yuva444p}. | |
5946 | @end table | |
5947 | ||
5948 | @subsection Examples | |
5949 | ||
5950 | @itemize | |
5951 | @item | |
5952 | Merge three gray video streams of same width and height into single video stream: | |
5953 | @example | |
5954 | [a0][a1][a2]mergeplanes=0x001020:yuv444p | |
5955 | @end example | |
5956 | ||
5957 | @item | |
5958 | Merge 1st yuv444p stream and 2nd gray video stream into yuva444p video stream: | |
5959 | @example | |
5960 | [a0][a1]mergeplanes=0x00010210:yuva444p | |
5961 | @end example | |
5962 | ||
5963 | @item | |
5964 | Swap Y and A plane in yuva444p stream: | |
5965 | @example | |
5966 | format=yuva444p,mergeplanes=0x03010200:yuva444p | |
5967 | @end example | |
5968 | ||
5969 | @item | |
5970 | Swap U and V plane in yuv420p stream: | |
5971 | @example | |
5972 | format=yuv420p,mergeplanes=0x000201:yuv420p | |
5973 | @end example | |
5974 | ||
5975 | @item | |
5976 | Cast a rgb24 clip to yuv444p: | |
5977 | @example | |
5978 | format=rgb24,mergeplanes=0x000102:yuv444p | |
5979 | @end example | |
5980 | @end itemize | |
5981 | ||
5982 | @section mcdeint | |
5983 | ||
5984 | Apply motion-compensation deinterlacing. | |
5985 | ||
5986 | It needs one field per frame as input and must thus be used together | |
5987 | with yadif=1/3 or equivalent. | |
5988 | ||
5989 | This filter accepts the following options: | |
5990 | @table @option | |
5991 | @item mode | |
5992 | Set the deinterlacing mode. | |
5993 | ||
5994 | It accepts one of the following values: | |
5995 | @table @samp | |
5996 | @item fast | |
5997 | @item medium | |
5998 | @item slow | |
5999 | use iterative motion estimation | |
6000 | @item extra_slow | |
6001 | like @samp{slow}, but use multiple reference frames. | |
6002 | @end table | |
6003 | Default value is @samp{fast}. | |
6004 | ||
6005 | @item parity | |
6006 | Set the picture field parity assumed for the input video. It must be | |
6007 | one of the following values: | |
6008 | ||
6009 | @table @samp | |
6010 | @item 0, tff | |
6011 | assume top field first | |
6012 | @item 1, bff | |
6013 | assume bottom field first | |
6014 | @end table | |
6015 | ||
6016 | Default value is @samp{bff}. | |
6017 | ||
6018 | @item qp | |
6019 | Set per-block quantization parameter (QP) used by the internal | |
6020 | encoder. | |
6021 | ||
6022 | Higher values should result in a smoother motion vector field but less | |
6023 | optimal individual vectors. Default value is 1. | |
6024 | @end table | |
6025 | ||
6026 | @section mp | |
6027 | ||
6028 | Apply an MPlayer filter to the input video. | |
6029 | ||
6030 | This filter provides a wrapper around some of the filters of | |
6031 | MPlayer/MEncoder. | |
6032 | ||
6033 | This wrapper is considered experimental. Some of the wrapped filters | |
6034 | may not work properly and we may drop support for them, as they will | |
6035 | be implemented natively into FFmpeg. Thus you should avoid | |
6036 | depending on them when writing portable scripts. | |
6037 | ||
6038 | The filter accepts the parameters: | |
6039 | @var{filter_name}[:=]@var{filter_params} | |
6040 | ||
6041 | @var{filter_name} is the name of a supported MPlayer filter, | |
6042 | @var{filter_params} is a string containing the parameters accepted by | |
6043 | the named filter. | |
6044 | ||
6045 | The list of the currently supported filters follows: | |
6046 | @table @var | |
6047 | @item eq2 | |
6048 | @item eq | |
6049 | @item fspp | |
6050 | @item ilpack | |
6051 | @item pp7 | |
6052 | @item softpulldown | |
6053 | @item uspp | |
6054 | @end table | |
6055 | ||
6056 | The parameter syntax and behavior for the listed filters are the same | |
6057 | of the corresponding MPlayer filters. For detailed instructions check | |
6058 | the "VIDEO FILTERS" section in the MPlayer manual. | |
6059 | ||
6060 | @subsection Examples | |
6061 | ||
6062 | @itemize | |
6063 | @item | |
6064 | Adjust gamma, brightness, contrast: | |
6065 | @example | |
6066 | mp=eq2=1.0:2:0.5 | |
6067 | @end example | |
6068 | @end itemize | |
6069 | ||
6070 | See also mplayer(1), @url{http://www.mplayerhq.hu/}. | |
6071 | ||
6072 | @section mpdecimate | |
6073 | ||
6074 | Drop frames that do not differ greatly from the previous frame in | |
6075 | order to reduce frame rate. | |
6076 | ||
6077 | The main use of this filter is for very-low-bitrate encoding | |
6078 | (e.g. streaming over dialup modem), but it could in theory be used for | |
6079 | fixing movies that were inverse-telecined incorrectly. | |
6080 | ||
6081 | A description of the accepted options follows. | |
6082 | ||
6083 | @table @option | |
6084 | @item max | |
6085 | Set the maximum number of consecutive frames which can be dropped (if | |
6086 | positive), or the minimum interval between dropped frames (if | |
6087 | negative). If the value is 0, the frame is dropped unregarding the | |
6088 | number of previous sequentially dropped frames. | |
6089 | ||
6090 | Default value is 0. | |
6091 | ||
6092 | @item hi | |
6093 | @item lo | |
6094 | @item frac | |
6095 | Set the dropping threshold values. | |
6096 | ||
6097 | Values for @option{hi} and @option{lo} are for 8x8 pixel blocks and | |
6098 | represent actual pixel value differences, so a threshold of 64 | |
6099 | corresponds to 1 unit of difference for each pixel, or the same spread | |
6100 | out differently over the block. | |
6101 | ||
6102 | A frame is a candidate for dropping if no 8x8 blocks differ by more | |
6103 | than a threshold of @option{hi}, and if no more than @option{frac} blocks (1 | |
6104 | meaning the whole image) differ by more than a threshold of @option{lo}. | |
6105 | ||
6106 | Default value for @option{hi} is 64*12, default value for @option{lo} is | |
6107 | 64*5, and default value for @option{frac} is 0.33. | |
6108 | @end table | |
6109 | ||
6110 | ||
6111 | @section negate | |
6112 | ||
6113 | Negate input video. | |
6114 | ||
6115 | It accepts an integer in input; if non-zero it negates the | |
6116 | alpha component (if available). The default value in input is 0. | |
6117 | ||
6118 | @section noformat | |
6119 | ||
6120 | Force libavfilter not to use any of the specified pixel formats for the | |
6121 | input to the next filter. | |
6122 | ||
6123 | It accepts the following parameters: | |
6124 | @table @option | |
6125 | ||
6126 | @item pix_fmts | |
6127 | A '|'-separated list of pixel format names, such as | |
6128 | apix_fmts=yuv420p|monow|rgb24". | |
6129 | ||
6130 | @end table | |
6131 | ||
6132 | @subsection Examples | |
6133 | ||
6134 | @itemize | |
6135 | @item | |
6136 | Force libavfilter to use a format different from @var{yuv420p} for the | |
6137 | input to the vflip filter: | |
6138 | @example | |
6139 | noformat=pix_fmts=yuv420p,vflip | |
6140 | @end example | |
6141 | ||
6142 | @item | |
6143 | Convert the input video to any of the formats not contained in the list: | |
6144 | @example | |
6145 | noformat=yuv420p|yuv444p|yuv410p | |
6146 | @end example | |
6147 | @end itemize | |
6148 | ||
6149 | @section noise | |
6150 | ||
6151 | Add noise on video input frame. | |
6152 | ||
6153 | The filter accepts the following options: | |
6154 | ||
6155 | @table @option | |
6156 | @item all_seed | |
6157 | @item c0_seed | |
6158 | @item c1_seed | |
6159 | @item c2_seed | |
6160 | @item c3_seed | |
6161 | Set noise seed for specific pixel component or all pixel components in case | |
6162 | of @var{all_seed}. Default value is @code{123457}. | |
6163 | ||
6164 | @item all_strength, alls | |
6165 | @item c0_strength, c0s | |
6166 | @item c1_strength, c1s | |
6167 | @item c2_strength, c2s | |
6168 | @item c3_strength, c3s | |
6169 | Set noise strength for specific pixel component or all pixel components in case | |
6170 | @var{all_strength}. Default value is @code{0}. Allowed range is [0, 100]. | |
6171 | ||
6172 | @item all_flags, allf | |
6173 | @item c0_flags, c0f | |
6174 | @item c1_flags, c1f | |
6175 | @item c2_flags, c2f | |
6176 | @item c3_flags, c3f | |
6177 | Set pixel component flags or set flags for all components if @var{all_flags}. | |
6178 | Available values for component flags are: | |
6179 | @table @samp | |
6180 | @item a | |
6181 | averaged temporal noise (smoother) | |
6182 | @item p | |
6183 | mix random noise with a (semi)regular pattern | |
6184 | @item t | |
6185 | temporal noise (noise pattern changes between frames) | |
6186 | @item u | |
6187 | uniform noise (gaussian otherwise) | |
6188 | @end table | |
6189 | @end table | |
6190 | ||
6191 | @subsection Examples | |
6192 | ||
6193 | Add temporal and uniform noise to input video: | |
6194 | @example | |
6195 | noise=alls=20:allf=t+u | |
6196 | @end example | |
6197 | ||
6198 | @section null | |
6199 | ||
6200 | Pass the video source unchanged to the output. | |
6201 | ||
6202 | @section ocv | |
6203 | ||
6204 | Apply a video transform using libopencv. | |
6205 | ||
6206 | To enable this filter, install the libopencv library and headers and | |
6207 | configure FFmpeg with @code{--enable-libopencv}. | |
6208 | ||
6209 | It accepts the following parameters: | |
6210 | ||
6211 | @table @option | |
6212 | ||
6213 | @item filter_name | |
6214 | The name of the libopencv filter to apply. | |
6215 | ||
6216 | @item filter_params | |
6217 | The parameters to pass to the libopencv filter. If not specified, the default | |
6218 | values are assumed. | |
6219 | ||
6220 | @end table | |
6221 | ||
6222 | Refer to the official libopencv documentation for more precise | |
6223 | information: | |
6224 | @url{http://opencv.willowgarage.com/documentation/c/image_filtering.html} | |
6225 | ||
6226 | Several libopencv filters are supported; see the following subsections. | |
6227 | ||
6228 | @anchor{dilate} | |
6229 | @subsection dilate | |
6230 | ||
6231 | Dilate an image by using a specific structuring element. | |
6232 | It corresponds to the libopencv function @code{cvDilate}. | |
6233 | ||
6234 | It accepts the parameters: @var{struct_el}|@var{nb_iterations}. | |
6235 | ||
6236 | @var{struct_el} represents a structuring element, and has the syntax: | |
6237 | @var{cols}x@var{rows}+@var{anchor_x}x@var{anchor_y}/@var{shape} | |
6238 | ||
6239 | @var{cols} and @var{rows} represent the number of columns and rows of | |
6240 | the structuring element, @var{anchor_x} and @var{anchor_y} the anchor | |
6241 | point, and @var{shape} the shape for the structuring element. @var{shape} | |
6242 | must be "rect", "cross", "ellipse", or "custom". | |
6243 | ||
6244 | If the value for @var{shape} is "custom", it must be followed by a | |
6245 | string of the form "=@var{filename}". The file with name | |
6246 | @var{filename} is assumed to represent a binary image, with each | |
6247 | printable character corresponding to a bright pixel. When a custom | |
6248 | @var{shape} is used, @var{cols} and @var{rows} are ignored, the number | |
6249 | or columns and rows of the read file are assumed instead. | |
6250 | ||
6251 | The default value for @var{struct_el} is "3x3+0x0/rect". | |
6252 | ||
6253 | @var{nb_iterations} specifies the number of times the transform is | |
6254 | applied to the image, and defaults to 1. | |
6255 | ||
6256 | Some examples: | |
6257 | @example | |
6258 | # Use the default values | |
6259 | ocv=dilate | |
6260 | ||
6261 | # Dilate using a structuring element with a 5x5 cross, iterating two times | |
6262 | ocv=filter_name=dilate:filter_params=5x5+2x2/cross|2 | |
6263 | ||
6264 | # Read the shape from the file diamond.shape, iterating two times. | |
6265 | # The file diamond.shape may contain a pattern of characters like this | |
6266 | # * | |
6267 | # *** | |
6268 | # ***** | |
6269 | # *** | |
6270 | # * | |
6271 | # The specified columns and rows are ignored | |
6272 | # but the anchor point coordinates are not | |
6273 | ocv=dilate:0x0+2x2/custom=diamond.shape|2 | |
6274 | @end example | |
6275 | ||
6276 | @subsection erode | |
6277 | ||
6278 | Erode an image by using a specific structuring element. | |
6279 | It corresponds to the libopencv function @code{cvErode}. | |
6280 | ||
6281 | It accepts the parameters: @var{struct_el}:@var{nb_iterations}, | |
6282 | with the same syntax and semantics as the @ref{dilate} filter. | |
6283 | ||
6284 | @subsection smooth | |
6285 | ||
6286 | Smooth the input video. | |
6287 | ||
6288 | The filter takes the following parameters: | |
6289 | @var{type}|@var{param1}|@var{param2}|@var{param3}|@var{param4}. | |
6290 | ||
6291 | @var{type} is the type of smooth filter to apply, and must be one of | |
6292 | the following values: "blur", "blur_no_scale", "median", "gaussian", | |
6293 | or "bilateral". The default value is "gaussian". | |
6294 | ||
6295 | The meaning of @var{param1}, @var{param2}, @var{param3}, and @var{param4} | |
6296 | depend on the smooth type. @var{param1} and | |
6297 | @var{param2} accept integer positive values or 0. @var{param3} and | |
6298 | @var{param4} accept floating point values. | |
6299 | ||
6300 | The default value for @var{param1} is 3. The default value for the | |
6301 | other parameters is 0. | |
6302 | ||
6303 | These parameters correspond to the parameters assigned to the | |
6304 | libopencv function @code{cvSmooth}. | |
6305 | ||
6306 | @anchor{overlay} | |
6307 | @section overlay | |
6308 | ||
6309 | Overlay one video on top of another. | |
6310 | ||
6311 | It takes two inputs and has one output. The first input is the "main" | |
6312 | video on which the second input is overlayed. | |
6313 | ||
6314 | It accepts the following parameters: | |
6315 | ||
6316 | A description of the accepted options follows. | |
6317 | ||
6318 | @table @option | |
6319 | @item x | |
6320 | @item y | |
6321 | Set the expression for the x and y coordinates of the overlayed video | |
6322 | on the main video. Default value is "0" for both expressions. In case | |
6323 | the expression is invalid, it is set to a huge value (meaning that the | |
6324 | overlay will not be displayed within the output visible area). | |
6325 | ||
6326 | @item eof_action | |
6327 | The action to take when EOF is encountered on the secondary input; it accepts | |
6328 | one of the following values: | |
6329 | ||
6330 | @table @option | |
6331 | @item repeat | |
6332 | Repeat the last frame (the default). | |
6333 | @item endall | |
6334 | End both streams. | |
6335 | @item pass | |
6336 | Pass the main input through. | |
6337 | @end table | |
6338 | ||
6339 | @item eval | |
6340 | Set when the expressions for @option{x}, and @option{y} are evaluated. | |
6341 | ||
6342 | It accepts the following values: | |
6343 | @table @samp | |
6344 | @item init | |
6345 | only evaluate expressions once during the filter initialization or | |
6346 | when a command is processed | |
6347 | ||
6348 | @item frame | |
6349 | evaluate expressions for each incoming frame | |
6350 | @end table | |
6351 | ||
6352 | Default value is @samp{frame}. | |
6353 | ||
6354 | @item shortest | |
6355 | If set to 1, force the output to terminate when the shortest input | |
6356 | terminates. Default value is 0. | |
6357 | ||
6358 | @item format | |
6359 | Set the format for the output video. | |
6360 | ||
6361 | It accepts the following values: | |
6362 | @table @samp | |
6363 | @item yuv420 | |
6364 | force YUV420 output | |
6365 | ||
6366 | @item yuv422 | |
6367 | force YUV422 output | |
6368 | ||
6369 | @item yuv444 | |
6370 | force YUV444 output | |
6371 | ||
6372 | @item rgb | |
6373 | force RGB output | |
6374 | @end table | |
6375 | ||
6376 | Default value is @samp{yuv420}. | |
6377 | ||
6378 | @item rgb @emph{(deprecated)} | |
6379 | If set to 1, force the filter to accept inputs in the RGB | |
6380 | color space. Default value is 0. This option is deprecated, use | |
6381 | @option{format} instead. | |
6382 | ||
6383 | @item repeatlast | |
6384 | If set to 1, force the filter to draw the last overlay frame over the | |
6385 | main input until the end of the stream. A value of 0 disables this | |
6386 | behavior. Default value is 1. | |
6387 | @end table | |
6388 | ||
6389 | The @option{x}, and @option{y} expressions can contain the following | |
6390 | parameters. | |
6391 | ||
6392 | @table @option | |
6393 | @item main_w, W | |
6394 | @item main_h, H | |
6395 | The main input width and height. | |
6396 | ||
6397 | @item overlay_w, w | |
6398 | @item overlay_h, h | |
6399 | The overlay input width and height. | |
6400 | ||
6401 | @item x | |
6402 | @item y | |
6403 | The computed values for @var{x} and @var{y}. They are evaluated for | |
6404 | each new frame. | |
6405 | ||
6406 | @item hsub | |
6407 | @item vsub | |
6408 | horizontal and vertical chroma subsample values of the output | |
6409 | format. For example for the pixel format "yuv422p" @var{hsub} is 2 and | |
6410 | @var{vsub} is 1. | |
6411 | ||
6412 | @item n | |
6413 | the number of input frame, starting from 0 | |
6414 | ||
6415 | @item pos | |
6416 | the position in the file of the input frame, NAN if unknown | |
6417 | ||
6418 | @item t | |
6419 | The timestamp, expressed in seconds. It's NAN if the input timestamp is unknown. | |
6420 | ||
6421 | @end table | |
6422 | ||
6423 | Note that the @var{n}, @var{pos}, @var{t} variables are available only | |
6424 | when evaluation is done @emph{per frame}, and will evaluate to NAN | |
6425 | when @option{eval} is set to @samp{init}. | |
6426 | ||
6427 | Be aware that frames are taken from each input video in timestamp | |
6428 | order, hence, if their initial timestamps differ, it is a good idea | |
6429 | to pass the two inputs through a @var{setpts=PTS-STARTPTS} filter to | |
6430 | have them begin in the same zero timestamp, as the example for | |
6431 | the @var{movie} filter does. | |
6432 | ||
6433 | You can chain together more overlays but you should test the | |
6434 | efficiency of such approach. | |
6435 | ||
6436 | @subsection Commands | |
6437 | ||
6438 | This filter supports the following commands: | |
6439 | @table @option | |
6440 | @item x | |
6441 | @item y | |
6442 | Modify the x and y of the overlay input. | |
6443 | The command accepts the same syntax of the corresponding option. | |
6444 | ||
6445 | If the specified expression is not valid, it is kept at its current | |
6446 | value. | |
6447 | @end table | |
6448 | ||
6449 | @subsection Examples | |
6450 | ||
6451 | @itemize | |
6452 | @item | |
6453 | Draw the overlay at 10 pixels from the bottom right corner of the main | |
6454 | video: | |
6455 | @example | |
6456 | overlay=main_w-overlay_w-10:main_h-overlay_h-10 | |
6457 | @end example | |
6458 | ||
6459 | Using named options the example above becomes: | |
6460 | @example | |
6461 | overlay=x=main_w-overlay_w-10:y=main_h-overlay_h-10 | |
6462 | @end example | |
6463 | ||
6464 | @item | |
6465 | Insert a transparent PNG logo in the bottom left corner of the input, | |
6466 | using the @command{ffmpeg} tool with the @code{-filter_complex} option: | |
6467 | @example | |
6468 | ffmpeg -i input -i logo -filter_complex 'overlay=10:main_h-overlay_h-10' output | |
6469 | @end example | |
6470 | ||
6471 | @item | |
6472 | Insert 2 different transparent PNG logos (second logo on bottom | |
6473 | right corner) using the @command{ffmpeg} tool: | |
6474 | @example | |
6475 | 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 | |
6476 | @end example | |
6477 | ||
6478 | @item | |
6479 | Add a transparent color layer on top of the main video; @code{WxH} | |
6480 | must specify the size of the main input to the overlay filter: | |
6481 | @example | |
6482 | color=color=red@@.3:size=WxH [over]; [in][over] overlay [out] | |
6483 | @end example | |
6484 | ||
6485 | @item | |
6486 | Play an original video and a filtered version (here with the deshake | |
6487 | filter) side by side using the @command{ffplay} tool: | |
6488 | @example | |
6489 | ffplay input.avi -vf 'split[a][b]; [a]pad=iw*2:ih[src]; [b]deshake[filt]; [src][filt]overlay=w' | |
6490 | @end example | |
6491 | ||
6492 | The above command is the same as: | |
6493 | @example | |
6494 | ffplay input.avi -vf 'split[b], pad=iw*2[src], [b]deshake, [src]overlay=w' | |
6495 | @end example | |
6496 | ||
6497 | @item | |
6498 | Make a sliding overlay appearing from the left to the right top part of the | |
6499 | screen starting since time 2: | |
6500 | @example | |
6501 | overlay=x='if(gte(t,2), -w+(t-2)*20, NAN)':y=0 | |
6502 | @end example | |
6503 | ||
6504 | @item | |
6505 | Compose output by putting two input videos side to side: | |
6506 | @example | |
6507 | ffmpeg -i left.avi -i right.avi -filter_complex " | |
6508 | nullsrc=size=200x100 [background]; | |
6509 | [0:v] setpts=PTS-STARTPTS, scale=100x100 [left]; | |
6510 | [1:v] setpts=PTS-STARTPTS, scale=100x100 [right]; | |
6511 | [background][left] overlay=shortest=1 [background+left]; | |
6512 | [background+left][right] overlay=shortest=1:x=100 [left+right] | |
6513 | " | |
6514 | @end example | |
6515 | ||
6516 | @item | |
6517 | Mask 10-20 seconds of a video by applying the delogo filter to a section | |
6518 | @example | |
6519 | ffmpeg -i test.avi -codec:v:0 wmv2 -ar 11025 -b:v 9000k | |
6520 | -vf '[in]split[split_main][split_delogo];[split_delogo]trim=start=360:end=371,delogo=0:0:640:480[delogoed];[split_main][delogoed]overlay=eof_action=pass[out]' | |
6521 | masked.avi | |
6522 | @end example | |
6523 | ||
6524 | @item | |
6525 | Chain several overlays in cascade: | |
6526 | @example | |
6527 | nullsrc=s=200x200 [bg]; | |
6528 | testsrc=s=100x100, split=4 [in0][in1][in2][in3]; | |
6529 | [in0] lutrgb=r=0, [bg] overlay=0:0 [mid0]; | |
6530 | [in1] lutrgb=g=0, [mid0] overlay=100:0 [mid1]; | |
6531 | [in2] lutrgb=b=0, [mid1] overlay=0:100 [mid2]; | |
6532 | [in3] null, [mid2] overlay=100:100 [out0] | |
6533 | @end example | |
6534 | ||
6535 | @end itemize | |
6536 | ||
6537 | @section owdenoise | |
6538 | ||
6539 | Apply Overcomplete Wavelet denoiser. | |
6540 | ||
6541 | The filter accepts the following options: | |
6542 | ||
6543 | @table @option | |
6544 | @item depth | |
6545 | Set depth. | |
6546 | ||
6547 | Larger depth values will denoise lower frequency components more, but | |
6548 | slow down filtering. | |
6549 | ||
6550 | Must be an int in the range 8-16, default is @code{8}. | |
6551 | ||
6552 | @item luma_strength, ls | |
6553 | Set luma strength. | |
6554 | ||
6555 | Must be a double value in the range 0-1000, default is @code{1.0}. | |
6556 | ||
6557 | @item chroma_strength, cs | |
6558 | Set chroma strength. | |
6559 | ||
6560 | Must be a double value in the range 0-1000, default is @code{1.0}. | |
6561 | @end table | |
6562 | ||
6563 | @section pad | |
6564 | ||
6565 | Add paddings to the input image, and place the original input at the | |
6566 | provided @var{x}, @var{y} coordinates. | |
6567 | ||
6568 | It accepts the following parameters: | |
6569 | ||
6570 | @table @option | |
6571 | @item width, w | |
6572 | @item height, h | |
6573 | Specify an expression for the size of the output image with the | |
6574 | paddings added. If the value for @var{width} or @var{height} is 0, the | |
6575 | corresponding input size is used for the output. | |
6576 | ||
6577 | The @var{width} expression can reference the value set by the | |
6578 | @var{height} expression, and vice versa. | |
6579 | ||
6580 | The default value of @var{width} and @var{height} is 0. | |
6581 | ||
6582 | @item x | |
6583 | @item y | |
6584 | Specify the offsets to place the input image at within the padded area, | |
6585 | with respect to the top/left border of the output image. | |
6586 | ||
6587 | The @var{x} expression can reference the value set by the @var{y} | |
6588 | expression, and vice versa. | |
6589 | ||
6590 | The default value of @var{x} and @var{y} is 0. | |
6591 | ||
6592 | @item color | |
6593 | Specify the color of the padded area. For the syntax of this option, | |
6594 | check the "Color" section in the ffmpeg-utils manual. | |
6595 | ||
6596 | The default value of @var{color} is "black". | |
6597 | @end table | |
6598 | ||
6599 | The value for the @var{width}, @var{height}, @var{x}, and @var{y} | |
6600 | options are expressions containing the following constants: | |
6601 | ||
6602 | @table @option | |
6603 | @item in_w | |
6604 | @item in_h | |
6605 | The input video width and height. | |
6606 | ||
6607 | @item iw | |
6608 | @item ih | |
6609 | These are the same as @var{in_w} and @var{in_h}. | |
6610 | ||
6611 | @item out_w | |
6612 | @item out_h | |
6613 | The output width and height (the size of the padded area), as | |
6614 | specified by the @var{width} and @var{height} expressions. | |
6615 | ||
6616 | @item ow | |
6617 | @item oh | |
6618 | These are the same as @var{out_w} and @var{out_h}. | |
6619 | ||
6620 | @item x | |
6621 | @item y | |
6622 | The x and y offsets as specified by the @var{x} and @var{y} | |
6623 | expressions, or NAN if not yet specified. | |
6624 | ||
6625 | @item a | |
6626 | same as @var{iw} / @var{ih} | |
6627 | ||
6628 | @item sar | |
6629 | input sample aspect ratio | |
6630 | ||
6631 | @item dar | |
6632 | input display aspect ratio, it is the same as (@var{iw} / @var{ih}) * @var{sar} | |
6633 | ||
6634 | @item hsub | |
6635 | @item vsub | |
6636 | The horizontal and vertical chroma subsample values. For example for the | |
6637 | pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1. | |
6638 | @end table | |
6639 | ||
6640 | @subsection Examples | |
6641 | ||
6642 | @itemize | |
6643 | @item | |
6644 | Add paddings with the color "violet" to the input video. The output video | |
6645 | size is 640x480, and the top-left corner of the input video is placed at | |
6646 | column 0, row 40 | |
6647 | @example | |
6648 | pad=640:480:0:40:violet | |
6649 | @end example | |
6650 | ||
6651 | The example above is equivalent to the following command: | |
6652 | @example | |
6653 | pad=width=640:height=480:x=0:y=40:color=violet | |
6654 | @end example | |
6655 | ||
6656 | @item | |
6657 | Pad the input to get an output with dimensions increased by 3/2, | |
6658 | and put the input video at the center of the padded area: | |
6659 | @example | |
6660 | pad="3/2*iw:3/2*ih:(ow-iw)/2:(oh-ih)/2" | |
6661 | @end example | |
6662 | ||
6663 | @item | |
6664 | Pad the input to get a squared output with size equal to the maximum | |
6665 | value between the input width and height, and put the input video at | |
6666 | the center of the padded area: | |
6667 | @example | |
6668 | pad="max(iw\,ih):ow:(ow-iw)/2:(oh-ih)/2" | |
6669 | @end example | |
6670 | ||
6671 | @item | |
6672 | Pad the input to get a final w/h ratio of 16:9: | |
6673 | @example | |
6674 | pad="ih*16/9:ih:(ow-iw)/2:(oh-ih)/2" | |
6675 | @end example | |
6676 | ||
6677 | @item | |
6678 | In case of anamorphic video, in order to set the output display aspect | |
6679 | correctly, it is necessary to use @var{sar} in the expression, | |
6680 | according to the relation: | |
6681 | @example | |
6682 | (ih * X / ih) * sar = output_dar | |
6683 | X = output_dar / sar | |
6684 | @end example | |
6685 | ||
6686 | Thus the previous example needs to be modified to: | |
6687 | @example | |
6688 | pad="ih*16/9/sar:ih:(ow-iw)/2:(oh-ih)/2" | |
6689 | @end example | |
6690 | ||
6691 | @item | |
6692 | Double the output size and put the input video in the bottom-right | |
6693 | corner of the output padded area: | |
6694 | @example | |
6695 | pad="2*iw:2*ih:ow-iw:oh-ih" | |
6696 | @end example | |
6697 | @end itemize | |
6698 | ||
6699 | @section perspective | |
6700 | ||
6701 | Correct perspective of video not recorded perpendicular to the screen. | |
6702 | ||
6703 | A description of the accepted parameters follows. | |
6704 | ||
6705 | @table @option | |
6706 | @item x0 | |
6707 | @item y0 | |
6708 | @item x1 | |
6709 | @item y1 | |
6710 | @item x2 | |
6711 | @item y2 | |
6712 | @item x3 | |
6713 | @item y3 | |
6714 | Set coordinates expression for top left, top right, bottom left and bottom right corners. | |
6715 | Default values are @code{0:0:W:0:0:H:W:H} with which perspective will remain unchanged. | |
6716 | ||
6717 | The expressions can use the following variables: | |
6718 | ||
6719 | @table @option | |
6720 | @item W | |
6721 | @item H | |
6722 | the width and height of video frame. | |
6723 | @end table | |
6724 | ||
6725 | @item interpolation | |
6726 | Set interpolation for perspective correction. | |
6727 | ||
6728 | It accepts the following values: | |
6729 | @table @samp | |
6730 | @item linear | |
6731 | @item cubic | |
6732 | @end table | |
6733 | ||
6734 | Default value is @samp{linear}. | |
6735 | @end table | |
6736 | ||
6737 | @section phase | |
6738 | ||
6739 | Delay interlaced video by one field time so that the field order changes. | |
6740 | ||
6741 | The intended use is to fix PAL movies that have been captured with the | |
6742 | opposite field order to the film-to-video transfer. | |
6743 | ||
6744 | A description of the accepted parameters follows. | |
6745 | ||
6746 | @table @option | |
6747 | @item mode | |
6748 | Set phase mode. | |
6749 | ||
6750 | It accepts the following values: | |
6751 | @table @samp | |
6752 | @item t | |
6753 | Capture field order top-first, transfer bottom-first. | |
6754 | Filter will delay the bottom field. | |
6755 | ||
6756 | @item b | |
6757 | Capture field order bottom-first, transfer top-first. | |
6758 | Filter will delay the top field. | |
6759 | ||
6760 | @item p | |
6761 | Capture and transfer with the same field order. This mode only exists | |
6762 | for the documentation of the other options to refer to, but if you | |
6763 | actually select it, the filter will faithfully do nothing. | |
6764 | ||
6765 | @item a | |
6766 | Capture field order determined automatically by field flags, transfer | |
6767 | opposite. | |
6768 | Filter selects among @samp{t} and @samp{b} modes on a frame by frame | |
6769 | basis using field flags. If no field information is available, | |
6770 | then this works just like @samp{u}. | |
6771 | ||
6772 | @item u | |
6773 | Capture unknown or varying, transfer opposite. | |
6774 | Filter selects among @samp{t} and @samp{b} on a frame by frame basis by | |
6775 | analyzing the images and selecting the alternative that produces best | |
6776 | match between the fields. | |
6777 | ||
6778 | @item T | |
6779 | Capture top-first, transfer unknown or varying. | |
6780 | Filter selects among @samp{t} and @samp{p} using image analysis. | |
6781 | ||
6782 | @item B | |
6783 | Capture bottom-first, transfer unknown or varying. | |
6784 | Filter selects among @samp{b} and @samp{p} using image analysis. | |
6785 | ||
6786 | @item A | |
6787 | Capture determined by field flags, transfer unknown or varying. | |
6788 | Filter selects among @samp{t}, @samp{b} and @samp{p} using field flags and | |
6789 | image analysis. If no field information is available, then this works just | |
6790 | like @samp{U}. This is the default mode. | |
6791 | ||
6792 | @item U | |
6793 | Both capture and transfer unknown or varying. | |
6794 | Filter selects among @samp{t}, @samp{b} and @samp{p} using image analysis only. | |
6795 | @end table | |
6796 | @end table | |
6797 | ||
6798 | @section pixdesctest | |
6799 | ||
6800 | Pixel format descriptor test filter, mainly useful for internal | |
6801 | testing. The output video should be equal to the input video. | |
6802 | ||
6803 | For example: | |
6804 | @example | |
6805 | format=monow, pixdesctest | |
6806 | @end example | |
6807 | ||
6808 | can be used to test the monowhite pixel format descriptor definition. | |
6809 | ||
6810 | @section pp | |
6811 | ||
6812 | Enable the specified chain of postprocessing subfilters using libpostproc. This | |
6813 | library should be automatically selected with a GPL build (@code{--enable-gpl}). | |
6814 | Subfilters must be separated by '/' and can be disabled by prepending a '-'. | |
6815 | Each subfilter and some options have a short and a long name that can be used | |
6816 | interchangeably, i.e. dr/dering are the same. | |
6817 | ||
6818 | The filters accept the following options: | |
6819 | ||
6820 | @table @option | |
6821 | @item subfilters | |
6822 | Set postprocessing subfilters string. | |
6823 | @end table | |
6824 | ||
6825 | All subfilters share common options to determine their scope: | |
6826 | ||
6827 | @table @option | |
6828 | @item a/autoq | |
6829 | Honor the quality commands for this subfilter. | |
6830 | ||
6831 | @item c/chrom | |
6832 | Do chrominance filtering, too (default). | |
6833 | ||
6834 | @item y/nochrom | |
6835 | Do luminance filtering only (no chrominance). | |
6836 | ||
6837 | @item n/noluma | |
6838 | Do chrominance filtering only (no luminance). | |
6839 | @end table | |
6840 | ||
6841 | These options can be appended after the subfilter name, separated by a '|'. | |
6842 | ||
6843 | Available subfilters are: | |
6844 | ||
6845 | @table @option | |
6846 | @item hb/hdeblock[|difference[|flatness]] | |
6847 | Horizontal deblocking filter | |
6848 | @table @option | |
6849 | @item difference | |
6850 | Difference factor where higher values mean more deblocking (default: @code{32}). | |
6851 | @item flatness | |
6852 | Flatness threshold where lower values mean more deblocking (default: @code{39}). | |
6853 | @end table | |
6854 | ||
6855 | @item vb/vdeblock[|difference[|flatness]] | |
6856 | Vertical deblocking filter | |
6857 | @table @option | |
6858 | @item difference | |
6859 | Difference factor where higher values mean more deblocking (default: @code{32}). | |
6860 | @item flatness | |
6861 | Flatness threshold where lower values mean more deblocking (default: @code{39}). | |
6862 | @end table | |
6863 | ||
6864 | @item ha/hadeblock[|difference[|flatness]] | |
6865 | Accurate horizontal deblocking filter | |
6866 | @table @option | |
6867 | @item difference | |
6868 | Difference factor where higher values mean more deblocking (default: @code{32}). | |
6869 | @item flatness | |
6870 | Flatness threshold where lower values mean more deblocking (default: @code{39}). | |
6871 | @end table | |
6872 | ||
6873 | @item va/vadeblock[|difference[|flatness]] | |
6874 | Accurate vertical deblocking filter | |
6875 | @table @option | |
6876 | @item difference | |
6877 | Difference factor where higher values mean more deblocking (default: @code{32}). | |
6878 | @item flatness | |
6879 | Flatness threshold where lower values mean more deblocking (default: @code{39}). | |
6880 | @end table | |
6881 | @end table | |
6882 | ||
6883 | The horizontal and vertical deblocking filters share the difference and | |
6884 | flatness values so you cannot set different horizontal and vertical | |
6885 | thresholds. | |
6886 | ||
6887 | @table @option | |
6888 | @item h1/x1hdeblock | |
6889 | Experimental horizontal deblocking filter | |
6890 | ||
6891 | @item v1/x1vdeblock | |
6892 | Experimental vertical deblocking filter | |
6893 | ||
6894 | @item dr/dering | |
6895 | Deringing filter | |
6896 | ||
6897 | @item tn/tmpnoise[|threshold1[|threshold2[|threshold3]]], temporal noise reducer | |
6898 | @table @option | |
6899 | @item threshold1 | |
6900 | larger -> stronger filtering | |
6901 | @item threshold2 | |
6902 | larger -> stronger filtering | |
6903 | @item threshold3 | |
6904 | larger -> stronger filtering | |
6905 | @end table | |
6906 | ||
6907 | @item al/autolevels[:f/fullyrange], automatic brightness / contrast correction | |
6908 | @table @option | |
6909 | @item f/fullyrange | |
6910 | Stretch luminance to @code{0-255}. | |
6911 | @end table | |
6912 | ||
6913 | @item lb/linblenddeint | |
6914 | Linear blend deinterlacing filter that deinterlaces the given block by | |
6915 | filtering all lines with a @code{(1 2 1)} filter. | |
6916 | ||
6917 | @item li/linipoldeint | |
6918 | Linear interpolating deinterlacing filter that deinterlaces the given block by | |
6919 | linearly interpolating every second line. | |
6920 | ||
6921 | @item ci/cubicipoldeint | |
6922 | Cubic interpolating deinterlacing filter deinterlaces the given block by | |
6923 | cubically interpolating every second line. | |
6924 | ||
6925 | @item md/mediandeint | |
6926 | Median deinterlacing filter that deinterlaces the given block by applying a | |
6927 | median filter to every second line. | |
6928 | ||
6929 | @item fd/ffmpegdeint | |
6930 | FFmpeg deinterlacing filter that deinterlaces the given block by filtering every | |
6931 | second line with a @code{(-1 4 2 4 -1)} filter. | |
6932 | ||
6933 | @item l5/lowpass5 | |
6934 | Vertically applied FIR lowpass deinterlacing filter that deinterlaces the given | |
6935 | block by filtering all lines with a @code{(-1 2 6 2 -1)} filter. | |
6936 | ||
6937 | @item fq/forceQuant[|quantizer] | |
6938 | Overrides the quantizer table from the input with the constant quantizer you | |
6939 | specify. | |
6940 | @table @option | |
6941 | @item quantizer | |
6942 | Quantizer to use | |
6943 | @end table | |
6944 | ||
6945 | @item de/default | |
6946 | Default pp filter combination (@code{hb|a,vb|a,dr|a}) | |
6947 | ||
6948 | @item fa/fast | |
6949 | Fast pp filter combination (@code{h1|a,v1|a,dr|a}) | |
6950 | ||
6951 | @item ac | |
6952 | High quality pp filter combination (@code{ha|a|128|7,va|a,dr|a}) | |
6953 | @end table | |
6954 | ||
6955 | @subsection Examples | |
6956 | ||
6957 | @itemize | |
6958 | @item | |
6959 | Apply horizontal and vertical deblocking, deringing and automatic | |
6960 | brightness/contrast: | |
6961 | @example | |
6962 | pp=hb/vb/dr/al | |
6963 | @end example | |
6964 | ||
6965 | @item | |
6966 | Apply default filters without brightness/contrast correction: | |
6967 | @example | |
6968 | pp=de/-al | |
6969 | @end example | |
6970 | ||
6971 | @item | |
6972 | Apply default filters and temporal denoiser: | |
6973 | @example | |
6974 | pp=default/tmpnoise|1|2|3 | |
6975 | @end example | |
6976 | ||
6977 | @item | |
6978 | Apply deblocking on luminance only, and switch vertical deblocking on or off | |
6979 | automatically depending on available CPU time: | |
6980 | @example | |
6981 | pp=hb|y/vb|a | |
6982 | @end example | |
6983 | @end itemize | |
6984 | ||
6985 | @section psnr | |
6986 | ||
6987 | Obtain the average, maximum and minimum PSNR (Peak Signal to Noise | |
6988 | Ratio) between two input videos. | |
6989 | ||
6990 | This filter takes in input two input videos, the first input is | |
6991 | considered the "main" source and is passed unchanged to the | |
6992 | output. The second input is used as a "reference" video for computing | |
6993 | the PSNR. | |
6994 | ||
6995 | Both video inputs must have the same resolution and pixel format for | |
6996 | this filter to work correctly. Also it assumes that both inputs | |
6997 | have the same number of frames, which are compared one by one. | |
6998 | ||
6999 | The obtained average PSNR is printed through the logging system. | |
7000 | ||
7001 | The filter stores the accumulated MSE (mean squared error) of each | |
7002 | frame, and at the end of the processing it is averaged across all frames | |
7003 | equally, and the following formula is applied to obtain the PSNR: | |
7004 | ||
7005 | @example | |
7006 | PSNR = 10*log10(MAX^2/MSE) | |
7007 | @end example | |
7008 | ||
7009 | Where MAX is the average of the maximum values of each component of the | |
7010 | image. | |
7011 | ||
7012 | The description of the accepted parameters follows. | |
7013 | ||
7014 | @table @option | |
7015 | @item stats_file, f | |
7016 | If specified the filter will use the named file to save the PSNR of | |
7017 | each individual frame. | |
7018 | @end table | |
7019 | ||
7020 | The file printed if @var{stats_file} is selected, contains a sequence of | |
7021 | key/value pairs of the form @var{key}:@var{value} for each compared | |
7022 | couple of frames. | |
7023 | ||
7024 | A description of each shown parameter follows: | |
7025 | ||
7026 | @table @option | |
7027 | @item n | |
7028 | sequential number of the input frame, starting from 1 | |
7029 | ||
7030 | @item mse_avg | |
7031 | Mean Square Error pixel-by-pixel average difference of the compared | |
7032 | frames, averaged over all the image components. | |
7033 | ||
7034 | @item mse_y, mse_u, mse_v, mse_r, mse_g, mse_g, mse_a | |
7035 | Mean Square Error pixel-by-pixel average difference of the compared | |
7036 | frames for the component specified by the suffix. | |
7037 | ||
7038 | @item psnr_y, psnr_u, psnr_v, psnr_r, psnr_g, psnr_b, psnr_a | |
7039 | Peak Signal to Noise ratio of the compared frames for the component | |
7040 | specified by the suffix. | |
7041 | @end table | |
7042 | ||
7043 | For example: | |
7044 | @example | |
7045 | movie=ref_movie.mpg, setpts=PTS-STARTPTS [main]; | |
7046 | [main][ref] psnr="stats_file=stats.log" [out] | |
7047 | @end example | |
7048 | ||
7049 | On this example the input file being processed is compared with the | |
7050 | reference file @file{ref_movie.mpg}. The PSNR of each individual frame | |
7051 | is stored in @file{stats.log}. | |
7052 | ||
7053 | @anchor{pullup} | |
7054 | @section pullup | |
7055 | ||
7056 | Pulldown reversal (inverse telecine) filter, capable of handling mixed | |
7057 | hard-telecine, 24000/1001 fps progressive, and 30000/1001 fps progressive | |
7058 | content. | |
7059 | ||
7060 | The pullup filter is designed to take advantage of future context in making | |
7061 | its decisions. This filter is stateless in the sense that it does not lock | |
7062 | onto a pattern to follow, but it instead looks forward to the following | |
7063 | fields in order to identify matches and rebuild progressive frames. | |
7064 | ||
7065 | To produce content with an even framerate, insert the fps filter after | |
7066 | pullup, use @code{fps=24000/1001} if the input frame rate is 29.97fps, | |
7067 | @code{fps=24} for 30fps and the (rare) telecined 25fps input. | |
7068 | ||
7069 | The filter accepts the following options: | |
7070 | ||
7071 | @table @option | |
7072 | @item jl | |
7073 | @item jr | |
7074 | @item jt | |
7075 | @item jb | |
7076 | These options set the amount of "junk" to ignore at the left, right, top, and | |
7077 | bottom of the image, respectively. Left and right are in units of 8 pixels, | |
7078 | while top and bottom are in units of 2 lines. | |
7079 | The default is 8 pixels on each side. | |
7080 | ||
7081 | @item sb | |
7082 | Set the strict breaks. Setting this option to 1 will reduce the chances of | |
7083 | filter generating an occasional mismatched frame, but it may also cause an | |
7084 | excessive number of frames to be dropped during high motion sequences. | |
7085 | Conversely, setting it to -1 will make filter match fields more easily. | |
7086 | This may help processing of video where there is slight blurring between | |
7087 | the fields, but may also cause there to be interlaced frames in the output. | |
7088 | Default value is @code{0}. | |
7089 | ||
7090 | @item mp | |
7091 | Set the metric plane to use. It accepts the following values: | |
7092 | @table @samp | |
7093 | @item l | |
7094 | Use luma plane. | |
7095 | ||
7096 | @item u | |
7097 | Use chroma blue plane. | |
7098 | ||
7099 | @item v | |
7100 | Use chroma red plane. | |
7101 | @end table | |
7102 | ||
7103 | This option may be set to use chroma plane instead of the default luma plane | |
7104 | for doing filter's computations. This may improve accuracy on very clean | |
7105 | source material, but more likely will decrease accuracy, especially if there | |
7106 | is chroma noise (rainbow effect) or any grayscale video. | |
7107 | The main purpose of setting @option{mp} to a chroma plane is to reduce CPU | |
7108 | load and make pullup usable in realtime on slow machines. | |
7109 | @end table | |
7110 | ||
7111 | For best results (without duplicated frames in the output file) it is | |
7112 | necessary to change the output frame rate. For example, to inverse | |
7113 | telecine NTSC input: | |
7114 | @example | |
7115 | ffmpeg -i input -vf pullup -r 24000/1001 ... | |
7116 | @end example | |
7117 | ||
7118 | @section removelogo | |
7119 | ||
7120 | Suppress a TV station logo, using an image file to determine which | |
7121 | pixels comprise the logo. It works by filling in the pixels that | |
7122 | comprise the logo with neighboring pixels. | |
7123 | ||
7124 | The filter accepts the following options: | |
7125 | ||
7126 | @table @option | |
7127 | @item filename, f | |
7128 | Set the filter bitmap file, which can be any image format supported by | |
7129 | libavformat. The width and height of the image file must match those of the | |
7130 | video stream being processed. | |
7131 | @end table | |
7132 | ||
7133 | Pixels in the provided bitmap image with a value of zero are not | |
7134 | considered part of the logo, non-zero pixels are considered part of | |
7135 | the logo. If you use white (255) for the logo and black (0) for the | |
7136 | rest, you will be safe. For making the filter bitmap, it is | |
7137 | recommended to take a screen capture of a black frame with the logo | |
7138 | visible, and then using a threshold filter followed by the erode | |
7139 | filter once or twice. | |
7140 | ||
7141 | If needed, little splotches can be fixed manually. Remember that if | |
7142 | logo pixels are not covered, the filter quality will be much | |
7143 | reduced. Marking too many pixels as part of the logo does not hurt as | |
7144 | much, but it will increase the amount of blurring needed to cover over | |
7145 | the image and will destroy more information than necessary, and extra | |
7146 | pixels will slow things down on a large logo. | |
7147 | ||
7148 | @section rotate | |
7149 | ||
7150 | Rotate video by an arbitrary angle expressed in radians. | |
7151 | ||
7152 | The filter accepts the following options: | |
7153 | ||
7154 | A description of the optional parameters follows. | |
7155 | @table @option | |
7156 | @item angle, a | |
7157 | Set an expression for the angle by which to rotate the input video | |
7158 | clockwise, expressed as a number of radians. A negative value will | |
7159 | result in a counter-clockwise rotation. By default it is set to "0". | |
7160 | ||
7161 | This expression is evaluated for each frame. | |
7162 | ||
7163 | @item out_w, ow | |
7164 | Set the output width expression, default value is "iw". | |
7165 | This expression is evaluated just once during configuration. | |
7166 | ||
7167 | @item out_h, oh | |
7168 | Set the output height expression, default value is "ih". | |
7169 | This expression is evaluated just once during configuration. | |
7170 | ||
7171 | @item bilinear | |
7172 | Enable bilinear interpolation if set to 1, a value of 0 disables | |
7173 | it. Default value is 1. | |
7174 | ||
7175 | @item fillcolor, c | |
7176 | Set the color used to fill the output area not covered by the rotated | |
7177 | image. For the generalsyntax of this option, check the "Color" section in the | |
7178 | ffmpeg-utils manual. If the special value "none" is selected then no | |
7179 | background is printed (useful for example if the background is never shown). | |
7180 | ||
7181 | Default value is "black". | |
7182 | @end table | |
7183 | ||
7184 | The expressions for the angle and the output size can contain the | |
7185 | following constants and functions: | |
7186 | ||
7187 | @table @option | |
7188 | @item n | |
7189 | sequential number of the input frame, starting from 0. It is always NAN | |
7190 | before the first frame is filtered. | |
7191 | ||
7192 | @item t | |
7193 | time in seconds of the input frame, it is set to 0 when the filter is | |
7194 | configured. It is always NAN before the first frame is filtered. | |
7195 | ||
7196 | @item hsub | |
7197 | @item vsub | |
7198 | horizontal and vertical chroma subsample values. For example for the | |
7199 | pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1. | |
7200 | ||
7201 | @item in_w, iw | |
7202 | @item in_h, ih | |
7203 | the input video width and height | |
7204 | ||
7205 | @item out_w, ow | |
7206 | @item out_h, oh | |
7207 | the output width and height, that is the size of the padded area as | |
7208 | specified by the @var{width} and @var{height} expressions | |
7209 | ||
7210 | @item rotw(a) | |
7211 | @item roth(a) | |
7212 | the minimal width/height required for completely containing the input | |
7213 | video rotated by @var{a} radians. | |
7214 | ||
7215 | These are only available when computing the @option{out_w} and | |
7216 | @option{out_h} expressions. | |
7217 | @end table | |
7218 | ||
7219 | @subsection Examples | |
7220 | ||
7221 | @itemize | |
7222 | @item | |
7223 | Rotate the input by PI/6 radians clockwise: | |
7224 | @example | |
7225 | rotate=PI/6 | |
7226 | @end example | |
7227 | ||
7228 | @item | |
7229 | Rotate the input by PI/6 radians counter-clockwise: | |
7230 | @example | |
7231 | rotate=-PI/6 | |
7232 | @end example | |
7233 | ||
7234 | @item | |
7235 | Rotate the input by 45 degrees clockwise: | |
7236 | @example | |
7237 | rotate=45*PI/180 | |
7238 | @end example | |
7239 | ||
7240 | @item | |
7241 | Apply a constant rotation with period T, starting from an angle of PI/3: | |
7242 | @example | |
7243 | rotate=PI/3+2*PI*t/T | |
7244 | @end example | |
7245 | ||
7246 | @item | |
7247 | Make the input video rotation oscillating with a period of T | |
7248 | seconds and an amplitude of A radians: | |
7249 | @example | |
7250 | rotate=A*sin(2*PI/T*t) | |
7251 | @end example | |
7252 | ||
7253 | @item | |
7254 | Rotate the video, output size is chosen so that the whole rotating | |
7255 | input video is always completely contained in the output: | |
7256 | @example | |
7257 | rotate='2*PI*t:ow=hypot(iw,ih):oh=ow' | |
7258 | @end example | |
7259 | ||
7260 | @item | |
7261 | Rotate the video, reduce the output size so that no background is ever | |
7262 | shown: | |
7263 | @example | |
7264 | rotate=2*PI*t:ow='min(iw,ih)/sqrt(2)':oh=ow:c=none | |
7265 | @end example | |
7266 | @end itemize | |
7267 | ||
7268 | @subsection Commands | |
7269 | ||
7270 | The filter supports the following commands: | |
7271 | ||
7272 | @table @option | |
7273 | @item a, angle | |
7274 | Set the angle expression. | |
7275 | The command accepts the same syntax of the corresponding option. | |
7276 | ||
7277 | If the specified expression is not valid, it is kept at its current | |
7278 | value. | |
7279 | @end table | |
7280 | ||
7281 | @section sab | |
7282 | ||
7283 | Apply Shape Adaptive Blur. | |
7284 | ||
7285 | The filter accepts the following options: | |
7286 | ||
7287 | @table @option | |
7288 | @item luma_radius, lr | |
7289 | Set luma blur filter strength, must be a value in range 0.1-4.0, default | |
7290 | value is 1.0. A greater value will result in a more blurred image, and | |
7291 | in slower processing. | |
7292 | ||
7293 | @item luma_pre_filter_radius, lpfr | |
7294 | Set luma pre-filter radius, must be a value in the 0.1-2.0 range, default | |
7295 | value is 1.0. | |
7296 | ||
7297 | @item luma_strength, ls | |
7298 | Set luma maximum difference between pixels to still be considered, must | |
7299 | be a value in the 0.1-100.0 range, default value is 1.0. | |
7300 | ||
7301 | @item chroma_radius, cr | |
7302 | Set chroma blur filter strength, must be a value in range 0.1-4.0. A | |
7303 | greater value will result in a more blurred image, and in slower | |
7304 | processing. | |
7305 | ||
7306 | @item chroma_pre_filter_radius, cpfr | |
7307 | Set chroma pre-filter radius, must be a value in the 0.1-2.0 range. | |
7308 | ||
7309 | @item chroma_strength, cs | |
7310 | Set chroma maximum difference between pixels to still be considered, | |
7311 | must be a value in the 0.1-100.0 range. | |
7312 | @end table | |
7313 | ||
7314 | Each chroma option value, if not explicitly specified, is set to the | |
7315 | corresponding luma option value. | |
7316 | ||
7317 | @anchor{scale} | |
7318 | @section scale | |
7319 | ||
7320 | Scale (resize) the input video, using the libswscale library. | |
7321 | ||
7322 | The scale filter forces the output display aspect ratio to be the same | |
7323 | of the input, by changing the output sample aspect ratio. | |
7324 | ||
7325 | If the input image format is different from the format requested by | |
7326 | the next filter, the scale filter will convert the input to the | |
7327 | requested format. | |
7328 | ||
7329 | @subsection Options | |
7330 | The filter accepts the following options, or any of the options | |
7331 | supported by the libswscale scaler. | |
7332 | ||
7333 | See @ref{scaler_options,,the ffmpeg-scaler manual,ffmpeg-scaler} for | |
7334 | the complete list of scaler options. | |
7335 | ||
7336 | @table @option | |
7337 | @item width, w | |
7338 | @item height, h | |
7339 | Set the output video dimension expression. Default value is the input | |
7340 | dimension. | |
7341 | ||
7342 | If the value is 0, the input width is used for the output. | |
7343 | ||
7344 | If one of the values is -1, the scale filter will use a value that | |
7345 | maintains the aspect ratio of the input image, calculated from the | |
7346 | other specified dimension. If both of them are -1, the input size is | |
7347 | used | |
7348 | ||
7349 | If one of the values is -n with n > 1, the scale filter will also use a value | |
7350 | that maintains the aspect ratio of the input image, calculated from the other | |
7351 | specified dimension. After that it will, however, make sure that the calculated | |
7352 | dimension is divisible by n and adjust the value if necessary. | |
7353 | ||
7354 | See below for the list of accepted constants for use in the dimension | |
7355 | expression. | |
7356 | ||
7357 | @item interl | |
7358 | Set the interlacing mode. It accepts the following values: | |
7359 | ||
7360 | @table @samp | |
7361 | @item 1 | |
7362 | Force interlaced aware scaling. | |
7363 | ||
7364 | @item 0 | |
7365 | Do not apply interlaced scaling. | |
7366 | ||
7367 | @item -1 | |
7368 | Select interlaced aware scaling depending on whether the source frames | |
7369 | are flagged as interlaced or not. | |
7370 | @end table | |
7371 | ||
7372 | Default value is @samp{0}. | |
7373 | ||
7374 | @item flags | |
7375 | Set libswscale scaling flags. See | |
7376 | @ref{sws_flags,,the ffmpeg-scaler manual,ffmpeg-scaler} for the | |
7377 | complete list of values. If not explicitly specified the filter applies | |
7378 | the default flags. | |
7379 | ||
7380 | @item size, s | |
7381 | Set the video size. For the syntax of this option, check the "Video size" | |
7382 | section in the ffmpeg-utils manual. | |
7383 | ||
7384 | @item in_color_matrix | |
7385 | @item out_color_matrix | |
7386 | Set in/output YCbCr color space type. | |
7387 | ||
7388 | This allows the autodetected value to be overridden as well as allows forcing | |
7389 | a specific value used for the output and encoder. | |
7390 | ||
7391 | If not specified, the color space type depends on the pixel format. | |
7392 | ||
7393 | Possible values: | |
7394 | ||
7395 | @table @samp | |
7396 | @item auto | |
7397 | Choose automatically. | |
7398 | ||
7399 | @item bt709 | |
7400 | Format conforming to International Telecommunication Union (ITU) | |
7401 | Recommendation BT.709. | |
7402 | ||
7403 | @item fcc | |
7404 | Set color space conforming to the United States Federal Communications | |
7405 | Commission (FCC) Code of Federal Regulations (CFR) Title 47 (2003) 73.682 (a). | |
7406 | ||
7407 | @item bt601 | |
7408 | Set color space conforming to: | |
7409 | ||
7410 | @itemize | |
7411 | @item | |
7412 | ITU Radiocommunication Sector (ITU-R) Recommendation BT.601 | |
7413 | ||
7414 | @item | |
7415 | ITU-R Rec. BT.470-6 (1998) Systems B, B1, and G | |
7416 | ||
7417 | @item | |
7418 | Society of Motion Picture and Television Engineers (SMPTE) ST 170:2004 | |
7419 | ||
7420 | @end itemize | |
7421 | ||
7422 | @item smpte240m | |
7423 | Set color space conforming to SMPTE ST 240:1999. | |
7424 | @end table | |
7425 | ||
7426 | @item in_range | |
7427 | @item out_range | |
7428 | Set in/output YCbCr sample range. | |
7429 | ||
7430 | This allows the autodetected value to be overridden as well as allows forcing | |
7431 | a specific value used for the output and encoder. If not specified, the | |
7432 | range depends on the pixel format. Possible values: | |
7433 | ||
7434 | @table @samp | |
7435 | @item auto | |
7436 | Choose automatically. | |
7437 | ||
7438 | @item jpeg/full/pc | |
7439 | Set full range (0-255 in case of 8-bit luma). | |
7440 | ||
7441 | @item mpeg/tv | |
7442 | Set "MPEG" range (16-235 in case of 8-bit luma). | |
7443 | @end table | |
7444 | ||
7445 | @item force_original_aspect_ratio | |
7446 | Enable decreasing or increasing output video width or height if necessary to | |
7447 | keep the original aspect ratio. Possible values: | |
7448 | ||
7449 | @table @samp | |
7450 | @item disable | |
7451 | Scale the video as specified and disable this feature. | |
7452 | ||
7453 | @item decrease | |
7454 | The output video dimensions will automatically be decreased if needed. | |
7455 | ||
7456 | @item increase | |
7457 | The output video dimensions will automatically be increased if needed. | |
7458 | ||
7459 | @end table | |
7460 | ||
7461 | One useful instance of this option is that when you know a specific device's | |
7462 | maximum allowed resolution, you can use this to limit the output video to | |
7463 | that, while retaining the aspect ratio. For example, device A allows | |
7464 | 1280x720 playback, and your video is 1920x800. Using this option (set it to | |
7465 | decrease) and specifying 1280x720 to the command line makes the output | |
7466 | 1280x533. | |
7467 | ||
7468 | Please note that this is a different thing than specifying -1 for @option{w} | |
7469 | or @option{h}, you still need to specify the output resolution for this option | |
7470 | to work. | |
7471 | ||
7472 | @end table | |
7473 | ||
7474 | The values of the @option{w} and @option{h} options are expressions | |
7475 | containing the following constants: | |
7476 | ||
7477 | @table @var | |
7478 | @item in_w | |
7479 | @item in_h | |
7480 | The input width and height | |
7481 | ||
7482 | @item iw | |
7483 | @item ih | |
7484 | These are the same as @var{in_w} and @var{in_h}. | |
7485 | ||
7486 | @item out_w | |
7487 | @item out_h | |
7488 | The output (scaled) width and height | |
7489 | ||
7490 | @item ow | |
7491 | @item oh | |
7492 | These are the same as @var{out_w} and @var{out_h} | |
7493 | ||
7494 | @item a | |
7495 | The same as @var{iw} / @var{ih} | |
7496 | ||
7497 | @item sar | |
7498 | input sample aspect ratio | |
7499 | ||
7500 | @item dar | |
7501 | The input display aspect ratio. Calculated from @code{(iw / ih) * sar}. | |
7502 | ||
7503 | @item hsub | |
7504 | @item vsub | |
7505 | horizontal and vertical input chroma subsample values. For example for the | |
7506 | pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1. | |
7507 | ||
7508 | @item ohsub | |
7509 | @item ovsub | |
7510 | horizontal and vertical output chroma subsample values. For example for the | |
7511 | pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1. | |
7512 | @end table | |
7513 | ||
7514 | @subsection Examples | |
7515 | ||
7516 | @itemize | |
7517 | @item | |
7518 | Scale the input video to a size of 200x100 | |
7519 | @example | |
7520 | scale=w=200:h=100 | |
7521 | @end example | |
7522 | ||
7523 | This is equivalent to: | |
7524 | @example | |
7525 | scale=200:100 | |
7526 | @end example | |
7527 | ||
7528 | or: | |
7529 | @example | |
7530 | scale=200x100 | |
7531 | @end example | |
7532 | ||
7533 | @item | |
7534 | Specify a size abbreviation for the output size: | |
7535 | @example | |
7536 | scale=qcif | |
7537 | @end example | |
7538 | ||
7539 | which can also be written as: | |
7540 | @example | |
7541 | scale=size=qcif | |
7542 | @end example | |
7543 | ||
7544 | @item | |
7545 | Scale the input to 2x: | |
7546 | @example | |
7547 | scale=w=2*iw:h=2*ih | |
7548 | @end example | |
7549 | ||
7550 | @item | |
7551 | The above is the same as: | |
7552 | @example | |
7553 | scale=2*in_w:2*in_h | |
7554 | @end example | |
7555 | ||
7556 | @item | |
7557 | Scale the input to 2x with forced interlaced scaling: | |
7558 | @example | |
7559 | scale=2*iw:2*ih:interl=1 | |
7560 | @end example | |
7561 | ||
7562 | @item | |
7563 | Scale the input to half size: | |
7564 | @example | |
7565 | scale=w=iw/2:h=ih/2 | |
7566 | @end example | |
7567 | ||
7568 | @item | |
7569 | Increase the width, and set the height to the same size: | |
7570 | @example | |
7571 | scale=3/2*iw:ow | |
7572 | @end example | |
7573 | ||
7574 | @item | |
7575 | Seek Greek harmony: | |
7576 | @example | |
7577 | scale=iw:1/PHI*iw | |
7578 | scale=ih*PHI:ih | |
7579 | @end example | |
7580 | ||
7581 | @item | |
7582 | Increase the height, and set the width to 3/2 of the height: | |
7583 | @example | |
7584 | scale=w=3/2*oh:h=3/5*ih | |
7585 | @end example | |
7586 | ||
7587 | @item | |
7588 | Increase the size, making the size a multiple of the chroma | |
7589 | subsample values: | |
7590 | @example | |
7591 | scale="trunc(3/2*iw/hsub)*hsub:trunc(3/2*ih/vsub)*vsub" | |
7592 | @end example | |
7593 | ||
7594 | @item | |
7595 | Increase the width to a maximum of 500 pixels, | |
7596 | keeping the same aspect ratio as the input: | |
7597 | @example | |
7598 | scale=w='min(500\, iw*3/2):h=-1' | |
7599 | @end example | |
7600 | @end itemize | |
7601 | ||
7602 | @section separatefields | |
7603 | ||
7604 | The @code{separatefields} takes a frame-based video input and splits | |
7605 | each frame into its components fields, producing a new half height clip | |
7606 | with twice the frame rate and twice the frame count. | |
7607 | ||
7608 | This filter use field-dominance information in frame to decide which | |
7609 | of each pair of fields to place first in the output. | |
7610 | If it gets it wrong use @ref{setfield} filter before @code{separatefields} filter. | |
7611 | ||
7612 | @section setdar, setsar | |
7613 | ||
7614 | The @code{setdar} filter sets the Display Aspect Ratio for the filter | |
7615 | output video. | |
7616 | ||
7617 | This is done by changing the specified Sample (aka Pixel) Aspect | |
7618 | Ratio, according to the following equation: | |
7619 | @example | |
7620 | @var{DAR} = @var{HORIZONTAL_RESOLUTION} / @var{VERTICAL_RESOLUTION} * @var{SAR} | |
7621 | @end example | |
7622 | ||
7623 | Keep in mind that the @code{setdar} filter does not modify the pixel | |
7624 | dimensions of the video frame. Also, the display aspect ratio set by | |
7625 | this filter may be changed by later filters in the filterchain, | |
7626 | e.g. in case of scaling or if another "setdar" or a "setsar" filter is | |
7627 | applied. | |
7628 | ||
7629 | The @code{setsar} filter sets the Sample (aka Pixel) Aspect Ratio for | |
7630 | the filter output video. | |
7631 | ||
7632 | Note that as a consequence of the application of this filter, the | |
7633 | output display aspect ratio will change according to the equation | |
7634 | above. | |
7635 | ||
7636 | Keep in mind that the sample aspect ratio set by the @code{setsar} | |
7637 | filter may be changed by later filters in the filterchain, e.g. if | |
7638 | another "setsar" or a "setdar" filter is applied. | |
7639 | ||
7640 | It accepts the following parameters: | |
7641 | ||
7642 | @table @option | |
7643 | @item r, ratio, dar (@code{setdar} only), sar (@code{setsar} only) | |
7644 | Set the aspect ratio used by the filter. | |
7645 | ||
7646 | The parameter can be a floating point number string, an expression, or | |
7647 | a string of the form @var{num}:@var{den}, where @var{num} and | |
7648 | @var{den} are the numerator and denominator of the aspect ratio. If | |
7649 | the parameter is not specified, it is assumed the value "0". | |
7650 | In case the form "@var{num}:@var{den}" is used, the @code{:} character | |
7651 | should be escaped. | |
7652 | ||
7653 | @item max | |
7654 | Set the maximum integer value to use for expressing numerator and | |
7655 | denominator when reducing the expressed aspect ratio to a rational. | |
7656 | Default value is @code{100}. | |
7657 | ||
7658 | @end table | |
7659 | ||
7660 | The parameter @var{sar} is an expression containing | |
7661 | the following constants: | |
7662 | ||
7663 | @table @option | |
7664 | @item E, PI, PHI | |
7665 | These are approximated values for the mathematical constants e | |
7666 | (Euler's number), pi (Greek pi), and phi (the golden ratio). | |
7667 | ||
7668 | @item w, h | |
7669 | The input width and height. | |
7670 | ||
7671 | @item a | |
7672 | These are the same as @var{w} / @var{h}. | |
7673 | ||
7674 | @item sar | |
7675 | The input sample aspect ratio. | |
7676 | ||
7677 | @item dar | |
7678 | The input display aspect ratio. It is the same as | |
7679 | (@var{w} / @var{h}) * @var{sar}. | |
7680 | ||
7681 | @item hsub, vsub | |
7682 | Horizontal and vertical chroma subsample values. For example, for the | |
7683 | pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1. | |
7684 | @end table | |
7685 | ||
7686 | @subsection Examples | |
7687 | ||
7688 | @itemize | |
7689 | ||
7690 | @item | |
7691 | To change the display aspect ratio to 16:9, specify one of the following: | |
7692 | @example | |
7693 | setdar=dar=1.77777 | |
7694 | setdar=dar=16/9 | |
7695 | setdar=dar=1.77777 | |
7696 | @end example | |
7697 | ||
7698 | @item | |
7699 | To change the sample aspect ratio to 10:11, specify: | |
7700 | @example | |
7701 | setsar=sar=10/11 | |
7702 | @end example | |
7703 | ||
7704 | @item | |
7705 | To set a display aspect ratio of 16:9, and specify a maximum integer value of | |
7706 | 1000 in the aspect ratio reduction, use the command: | |
7707 | @example | |
7708 | setdar=ratio=16/9:max=1000 | |
7709 | @end example | |
7710 | ||
7711 | @end itemize | |
7712 | ||
7713 | @anchor{setfield} | |
7714 | @section setfield | |
7715 | ||
7716 | Force field for the output video frame. | |
7717 | ||
7718 | The @code{setfield} filter marks the interlace type field for the | |
7719 | output frames. It does not change the input frame, but only sets the | |
7720 | corresponding property, which affects how the frame is treated by | |
7721 | following filters (e.g. @code{fieldorder} or @code{yadif}). | |
7722 | ||
7723 | The filter accepts the following options: | |
7724 | ||
7725 | @table @option | |
7726 | ||
7727 | @item mode | |
7728 | Available values are: | |
7729 | ||
7730 | @table @samp | |
7731 | @item auto | |
7732 | Keep the same field property. | |
7733 | ||
7734 | @item bff | |
7735 | Mark the frame as bottom-field-first. | |
7736 | ||
7737 | @item tff | |
7738 | Mark the frame as top-field-first. | |
7739 | ||
7740 | @item prog | |
7741 | Mark the frame as progressive. | |
7742 | @end table | |
7743 | @end table | |
7744 | ||
7745 | @section showinfo | |
7746 | ||
7747 | Show a line containing various information for each input video frame. | |
7748 | The input video is not modified. | |
7749 | ||
7750 | The shown line contains a sequence of key/value pairs of the form | |
7751 | @var{key}:@var{value}. | |
7752 | ||
7753 | The following values are shown in the output: | |
7754 | ||
7755 | @table @option | |
7756 | @item n | |
7757 | The (sequential) number of the input frame, starting from 0. | |
7758 | ||
7759 | @item pts | |
7760 | The Presentation TimeStamp of the input frame, expressed as a number of | |
7761 | time base units. The time base unit depends on the filter input pad. | |
7762 | ||
7763 | @item pts_time | |
7764 | The Presentation TimeStamp of the input frame, expressed as a number of | |
7765 | seconds. | |
7766 | ||
7767 | @item pos | |
7768 | The position of the frame in the input stream, or -1 if this information is | |
7769 | unavailable and/or meaningless (for example in case of synthetic video). | |
7770 | ||
7771 | @item fmt | |
7772 | The pixel format name. | |
7773 | ||
7774 | @item sar | |
7775 | The sample aspect ratio of the input frame, expressed in the form | |
7776 | @var{num}/@var{den}. | |
7777 | ||
7778 | @item s | |
7779 | The size of the input frame. For the syntax of this option, check the "Video size" | |
7780 | section in the ffmpeg-utils manual. | |
7781 | ||
7782 | @item i | |
7783 | The type of interlaced mode ("P" for "progressive", "T" for top field first, "B" | |
7784 | for bottom field first). | |
7785 | ||
7786 | @item iskey | |
7787 | This is 1 if the frame is a key frame, 0 otherwise. | |
7788 | ||
7789 | @item type | |
7790 | The picture type of the input frame ("I" for an I-frame, "P" for a | |
7791 | P-frame, "B" for a B-frame, or "?" for an unknown type). | |
7792 | Also refer to the documentation of the @code{AVPictureType} enum and of | |
7793 | the @code{av_get_picture_type_char} function defined in | |
7794 | @file{libavutil/avutil.h}. | |
7795 | ||
7796 | @item checksum | |
7797 | The Adler-32 checksum (printed in hexadecimal) of all the planes of the input frame. | |
7798 | ||
7799 | @item plane_checksum | |
7800 | The Adler-32 checksum (printed in hexadecimal) of each plane of the input frame, | |
7801 | expressed in the form "[@var{c0} @var{c1} @var{c2} @var{c3}]". | |
7802 | @end table | |
7803 | ||
7804 | @section shuffleplanes | |
7805 | ||
7806 | Reorder and/or duplicate video planes. | |
7807 | ||
7808 | It accepts the following parameters: | |
7809 | ||
7810 | @table @option | |
7811 | ||
7812 | @item map0 | |
7813 | The index of the input plane to be used as the first output plane. | |
7814 | ||
7815 | @item map1 | |
7816 | The index of the input plane to be used as the second output plane. | |
7817 | ||
7818 | @item map2 | |
7819 | The index of the input plane to be used as the third output plane. | |
7820 | ||
7821 | @item map3 | |
7822 | The index of the input plane to be used as the fourth output plane. | |
7823 | ||
7824 | @end table | |
7825 | ||
7826 | The first plane has the index 0. The default is to keep the input unchanged. | |
7827 | ||
7828 | Swap the second and third planes of the input: | |
7829 | @example | |
7830 | ffmpeg -i INPUT -vf shuffleplanes=0:2:1:3 OUTPUT | |
7831 | @end example | |
7832 | ||
7833 | @section signalstats | |
7834 | Evaluate various visual metrics that assist in determining issues associated | |
7835 | with the digitization of analog video media. | |
7836 | ||
7837 | By default the filter will log these metadata values: | |
7838 | ||
7839 | @table @option | |
7840 | @item YMIN | |
7841 | Display the minimal Y value contained within the input frame. Expressed in | |
7842 | range of [0-255]. | |
7843 | ||
7844 | @item YLOW | |
7845 | Display the Y value at the 10% percentile within the input frame. Expressed in | |
7846 | range of [0-255]. | |
7847 | ||
7848 | @item YAVG | |
7849 | Display the average Y value within the input frame. Expressed in range of | |
7850 | [0-255]. | |
7851 | ||
7852 | @item YHIGH | |
7853 | Display the Y value at the 90% percentile within the input frame. Expressed in | |
7854 | range of [0-255]. | |
7855 | ||
7856 | @item YMAX | |
7857 | Display the maximum Y value contained within the input frame. Expressed in | |
7858 | range of [0-255]. | |
7859 | ||
7860 | @item UMIN | |
7861 | Display the minimal U value contained within the input frame. Expressed in | |
7862 | range of [0-255]. | |
7863 | ||
7864 | @item ULOW | |
7865 | Display the U value at the 10% percentile within the input frame. Expressed in | |
7866 | range of [0-255]. | |
7867 | ||
7868 | @item UAVG | |
7869 | Display the average U value within the input frame. Expressed in range of | |
7870 | [0-255]. | |
7871 | ||
7872 | @item UHIGH | |
7873 | Display the U value at the 90% percentile within the input frame. Expressed in | |
7874 | range of [0-255]. | |
7875 | ||
7876 | @item UMAX | |
7877 | Display the maximum U value contained within the input frame. Expressed in | |
7878 | range of [0-255]. | |
7879 | ||
7880 | @item VMIN | |
7881 | Display the minimal V value contained within the input frame. Expressed in | |
7882 | range of [0-255]. | |
7883 | ||
7884 | @item VLOW | |
7885 | Display the V value at the 10% percentile within the input frame. Expressed in | |
7886 | range of [0-255]. | |
7887 | ||
7888 | @item VAVG | |
7889 | Display the average V value within the input frame. Expressed in range of | |
7890 | [0-255]. | |
7891 | ||
7892 | @item VHIGH | |
7893 | Display the V value at the 90% percentile within the input frame. Expressed in | |
7894 | range of [0-255]. | |
7895 | ||
7896 | @item VMAX | |
7897 | Display the maximum V value contained within the input frame. Expressed in | |
7898 | range of [0-255]. | |
7899 | ||
7900 | @item SATMIN | |
7901 | Display the minimal saturation value contained within the input frame. | |
7902 | Expressed in range of [0-~181.02]. | |
7903 | ||
7904 | @item SATLOW | |
7905 | Display the saturation value at the 10% percentile within the input frame. | |
7906 | Expressed in range of [0-~181.02]. | |
7907 | ||
7908 | @item SATAVG | |
7909 | Display the average saturation value within the input frame. Expressed in range | |
7910 | of [0-~181.02]. | |
7911 | ||
7912 | @item SATHIGH | |
7913 | Display the saturation value at the 90% percentile within the input frame. | |
7914 | Expressed in range of [0-~181.02]. | |
7915 | ||
7916 | @item SATMAX | |
7917 | Display the maximum saturation value contained within the input frame. | |
7918 | Expressed in range of [0-~181.02]. | |
7919 | ||
7920 | @item HUEMED | |
7921 | Display the median value for hue within the input frame. Expressed in range of | |
7922 | [0-360]. | |
7923 | ||
7924 | @item HUEAVG | |
7925 | Display the average value for hue within the input frame. Expressed in range of | |
7926 | [0-360]. | |
7927 | ||
7928 | @item YDIF | |
7929 | Display the average of sample value difference between all values of the Y | |
7930 | plane in the current frame and corresponding values of the previous input frame. | |
7931 | Expressed in range of [0-255]. | |
7932 | ||
7933 | @item UDIF | |
7934 | Display the average of sample value difference between all values of the U | |
7935 | plane in the current frame and corresponding values of the previous input frame. | |
7936 | Expressed in range of [0-255]. | |
7937 | ||
7938 | @item VDIF | |
7939 | Display the average of sample value difference between all values of the V | |
7940 | plane in the current frame and corresponding values of the previous input frame. | |
7941 | Expressed in range of [0-255]. | |
7942 | @end table | |
7943 | ||
7944 | The filter accepts the following options: | |
7945 | ||
7946 | @table @option | |
7947 | @item stat | |
7948 | @item out | |
7949 | ||
7950 | @option{stat} specify an additional form of image analysis. | |
7951 | @option{out} output video with the specified type of pixel highlighted. | |
7952 | ||
7953 | Both options accept the following values: | |
7954 | ||
7955 | @table @samp | |
7956 | @item tout | |
7957 | Identify @var{temporal outliers} pixels. A @var{temporal outlier} is a pixel | |
7958 | unlike the neighboring pixels of the same field. Examples of temporal outliers | |
7959 | include the results of video dropouts, head clogs, or tape tracking issues. | |
7960 | ||
7961 | @item vrep | |
7962 | Identify @var{vertical line repetition}. Vertical line repetition includes | |
7963 | similar rows of pixels within a frame. In born-digital video vertical line | |
7964 | repetition is common, but this pattern is uncommon in video digitized from an | |
7965 | analog source. When it occurs in video that results from the digitization of an | |
7966 | analog source it can indicate concealment from a dropout compensator. | |
7967 | ||
7968 | @item brng | |
7969 | Identify pixels that fall outside of legal broadcast range. | |
7970 | @end table | |
7971 | ||
7972 | @item color, c | |
7973 | Set the highlight color for the @option{out} option. The default color is | |
7974 | yellow. | |
7975 | @end table | |
7976 | ||
7977 | @subsection Examples | |
7978 | ||
7979 | @itemize | |
7980 | @item | |
7981 | Output data of various video metrics: | |
7982 | @example | |
7983 | ffprobe -f lavfi movie=example.mov,signalstats="stat=tout+vrep+brng" -show_frames | |
7984 | @end example | |
7985 | ||
7986 | @item | |
7987 | Output specific data about the minimum and maximum values of the Y plane per frame: | |
7988 | @example | |
7989 | ffprobe -f lavfi movie=example.mov,signalstats -show_entries frame_tags=lavfi.signalstats.YMAX,lavfi.signalstats.YMIN | |
7990 | @end example | |
7991 | ||
7992 | @item | |
7993 | Playback video while highlighting pixels that are outside of broadcast range in red. | |
7994 | @example | |
7995 | ffplay example.mov -vf signalstats="out=brng:color=red" | |
7996 | @end example | |
7997 | ||
7998 | @item | |
7999 | Playback video with signalstats metadata drawn over the frame. | |
8000 | @example | |
8001 | ffplay example.mov -vf signalstats=stat=brng+vrep+tout,drawtext=fontfile=FreeSerif.ttf:textfile=signalstat_drawtext.txt | |
8002 | @end example | |
8003 | ||
8004 | The contents of signalstat_drawtext.txt used in the command are: | |
8005 | @example | |
8006 | time %@{pts:hms@} | |
8007 | Y (%@{metadata:lavfi.signalstats.YMIN@}-%@{metadata:lavfi.signalstats.YMAX@}) | |
8008 | U (%@{metadata:lavfi.signalstats.UMIN@}-%@{metadata:lavfi.signalstats.UMAX@}) | |
8009 | V (%@{metadata:lavfi.signalstats.VMIN@}-%@{metadata:lavfi.signalstats.VMAX@}) | |
8010 | saturation maximum: %@{metadata:lavfi.signalstats.SATMAX@} | |
8011 | ||
8012 | @end example | |
8013 | @end itemize | |
8014 | ||
8015 | @anchor{smartblur} | |
8016 | @section smartblur | |
8017 | ||
8018 | Blur the input video without impacting the outlines. | |
8019 | ||
8020 | It accepts the following options: | |
8021 | ||
8022 | @table @option | |
8023 | @item luma_radius, lr | |
8024 | Set the luma radius. The option value must be a float number in | |
8025 | the range [0.1,5.0] that specifies the variance of the gaussian filter | |
8026 | used to blur the image (slower if larger). Default value is 1.0. | |
8027 | ||
8028 | @item luma_strength, ls | |
8029 | Set the luma strength. The option value must be a float number | |
8030 | in the range [-1.0,1.0] that configures the blurring. A value included | |
8031 | in [0.0,1.0] will blur the image whereas a value included in | |
8032 | [-1.0,0.0] will sharpen the image. Default value is 1.0. | |
8033 | ||
8034 | @item luma_threshold, lt | |
8035 | Set the luma threshold used as a coefficient to determine | |
8036 | whether a pixel should be blurred or not. The option value must be an | |
8037 | integer in the range [-30,30]. A value of 0 will filter all the image, | |
8038 | a value included in [0,30] will filter flat areas and a value included | |
8039 | in [-30,0] will filter edges. Default value is 0. | |
8040 | ||
8041 | @item chroma_radius, cr | |
8042 | Set the chroma radius. The option value must be a float number in | |
8043 | the range [0.1,5.0] that specifies the variance of the gaussian filter | |
8044 | used to blur the image (slower if larger). Default value is 1.0. | |
8045 | ||
8046 | @item chroma_strength, cs | |
8047 | Set the chroma strength. The option value must be a float number | |
8048 | in the range [-1.0,1.0] that configures the blurring. A value included | |
8049 | in [0.0,1.0] will blur the image whereas a value included in | |
8050 | [-1.0,0.0] will sharpen the image. Default value is 1.0. | |
8051 | ||
8052 | @item chroma_threshold, ct | |
8053 | Set the chroma threshold used as a coefficient to determine | |
8054 | whether a pixel should be blurred or not. The option value must be an | |
8055 | integer in the range [-30,30]. A value of 0 will filter all the image, | |
8056 | a value included in [0,30] will filter flat areas and a value included | |
8057 | in [-30,0] will filter edges. Default value is 0. | |
8058 | @end table | |
8059 | ||
8060 | If a chroma option is not explicitly set, the corresponding luma value | |
8061 | is set. | |
8062 | ||
8063 | @section stereo3d | |
8064 | ||
8065 | Convert between different stereoscopic image formats. | |
8066 | ||
8067 | The filters accept the following options: | |
8068 | ||
8069 | @table @option | |
8070 | @item in | |
8071 | Set stereoscopic image format of input. | |
8072 | ||
8073 | Available values for input image formats are: | |
8074 | @table @samp | |
8075 | @item sbsl | |
8076 | side by side parallel (left eye left, right eye right) | |
8077 | ||
8078 | @item sbsr | |
8079 | side by side crosseye (right eye left, left eye right) | |
8080 | ||
8081 | @item sbs2l | |
8082 | side by side parallel with half width resolution | |
8083 | (left eye left, right eye right) | |
8084 | ||
8085 | @item sbs2r | |
8086 | side by side crosseye with half width resolution | |
8087 | (right eye left, left eye right) | |
8088 | ||
8089 | @item abl | |
8090 | above-below (left eye above, right eye below) | |
8091 | ||
8092 | @item abr | |
8093 | above-below (right eye above, left eye below) | |
8094 | ||
8095 | @item ab2l | |
8096 | above-below with half height resolution | |
8097 | (left eye above, right eye below) | |
8098 | ||
8099 | @item ab2r | |
8100 | above-below with half height resolution | |
8101 | (right eye above, left eye below) | |
8102 | ||
8103 | @item al | |
8104 | alternating frames (left eye first, right eye second) | |
8105 | ||
8106 | @item ar | |
8107 | alternating frames (right eye first, left eye second) | |
8108 | ||
8109 | Default value is @samp{sbsl}. | |
8110 | @end table | |
8111 | ||
8112 | @item out | |
8113 | Set stereoscopic image format of output. | |
8114 | ||
8115 | Available values for output image formats are all the input formats as well as: | |
8116 | @table @samp | |
8117 | @item arbg | |
8118 | anaglyph red/blue gray | |
8119 | (red filter on left eye, blue filter on right eye) | |
8120 | ||
8121 | @item argg | |
8122 | anaglyph red/green gray | |
8123 | (red filter on left eye, green filter on right eye) | |
8124 | ||
8125 | @item arcg | |
8126 | anaglyph red/cyan gray | |
8127 | (red filter on left eye, cyan filter on right eye) | |
8128 | ||
8129 | @item arch | |
8130 | anaglyph red/cyan half colored | |
8131 | (red filter on left eye, cyan filter on right eye) | |
8132 | ||
8133 | @item arcc | |
8134 | anaglyph red/cyan color | |
8135 | (red filter on left eye, cyan filter on right eye) | |
8136 | ||
8137 | @item arcd | |
8138 | anaglyph red/cyan color optimized with the least squares projection of dubois | |
8139 | (red filter on left eye, cyan filter on right eye) | |
8140 | ||
8141 | @item agmg | |
8142 | anaglyph green/magenta gray | |
8143 | (green filter on left eye, magenta filter on right eye) | |
8144 | ||
8145 | @item agmh | |
8146 | anaglyph green/magenta half colored | |
8147 | (green filter on left eye, magenta filter on right eye) | |
8148 | ||
8149 | @item agmc | |
8150 | anaglyph green/magenta colored | |
8151 | (green filter on left eye, magenta filter on right eye) | |
8152 | ||
8153 | @item agmd | |
8154 | anaglyph green/magenta color optimized with the least squares projection of dubois | |
8155 | (green filter on left eye, magenta filter on right eye) | |
8156 | ||
8157 | @item aybg | |
8158 | anaglyph yellow/blue gray | |
8159 | (yellow filter on left eye, blue filter on right eye) | |
8160 | ||
8161 | @item aybh | |
8162 | anaglyph yellow/blue half colored | |
8163 | (yellow filter on left eye, blue filter on right eye) | |
8164 | ||
8165 | @item aybc | |
8166 | anaglyph yellow/blue colored | |
8167 | (yellow filter on left eye, blue filter on right eye) | |
8168 | ||
8169 | @item aybd | |
8170 | anaglyph yellow/blue color optimized with the least squares projection of dubois | |
8171 | (yellow filter on left eye, blue filter on right eye) | |
8172 | ||
8173 | @item irl | |
8174 | interleaved rows (left eye has top row, right eye starts on next row) | |
8175 | ||
8176 | @item irr | |
8177 | interleaved rows (right eye has top row, left eye starts on next row) | |
8178 | ||
8179 | @item ml | |
8180 | mono output (left eye only) | |
8181 | ||
8182 | @item mr | |
8183 | mono output (right eye only) | |
8184 | @end table | |
8185 | ||
8186 | Default value is @samp{arcd}. | |
8187 | @end table | |
8188 | ||
8189 | @subsection Examples | |
8190 | ||
8191 | @itemize | |
8192 | @item | |
8193 | Convert input video from side by side parallel to anaglyph yellow/blue dubois: | |
8194 | @example | |
8195 | stereo3d=sbsl:aybd | |
8196 | @end example | |
8197 | ||
8198 | @item | |
8199 | Convert input video from above bellow (left eye above, right eye below) to side by side crosseye. | |
8200 | @example | |
8201 | stereo3d=abl:sbsr | |
8202 | @end example | |
8203 | @end itemize | |
8204 | ||
8205 | @section spp | |
8206 | ||
8207 | Apply a simple postprocessing filter that compresses and decompresses the image | |
8208 | at several (or - in the case of @option{quality} level @code{6} - all) shifts | |
8209 | and average the results. | |
8210 | ||
8211 | The filter accepts the following options: | |
8212 | ||
8213 | @table @option | |
8214 | @item quality | |
8215 | Set quality. This option defines the number of levels for averaging. It accepts | |
8216 | an integer in the range 0-6. If set to @code{0}, the filter will have no | |
8217 | effect. A value of @code{6} means the higher quality. For each increment of | |
8218 | that value the speed drops by a factor of approximately 2. Default value is | |
8219 | @code{3}. | |
8220 | ||
8221 | @item qp | |
8222 | Force a constant quantization parameter. If not set, the filter will use the QP | |
8223 | from the video stream (if available). | |
8224 | ||
8225 | @item mode | |
8226 | Set thresholding mode. Available modes are: | |
8227 | ||
8228 | @table @samp | |
8229 | @item hard | |
8230 | Set hard thresholding (default). | |
8231 | @item soft | |
8232 | Set soft thresholding (better de-ringing effect, but likely blurrier). | |
8233 | @end table | |
8234 | ||
8235 | @item use_bframe_qp | |
8236 | Enable the use of the QP from the B-Frames if set to @code{1}. Using this | |
8237 | option may cause flicker since the B-Frames have often larger QP. Default is | |
8238 | @code{0} (not enabled). | |
8239 | @end table | |
8240 | ||
8241 | @anchor{subtitles} | |
8242 | @section subtitles | |
8243 | ||
8244 | Draw subtitles on top of input video using the libass library. | |
8245 | ||
8246 | To enable compilation of this filter you need to configure FFmpeg with | |
8247 | @code{--enable-libass}. This filter also requires a build with libavcodec and | |
8248 | libavformat to convert the passed subtitles file to ASS (Advanced Substation | |
8249 | Alpha) subtitles format. | |
8250 | ||
8251 | The filter accepts the following options: | |
8252 | ||
8253 | @table @option | |
8254 | @item filename, f | |
8255 | Set the filename of the subtitle file to read. It must be specified. | |
8256 | ||
8257 | @item original_size | |
8258 | Specify the size of the original video, the video for which the ASS file | |
8259 | was composed. For the syntax of this option, check the "Video size" section in | |
8260 | the ffmpeg-utils manual. Due to a misdesign in ASS aspect ratio arithmetic, | |
8261 | this is necessary to correctly scale the fonts if the aspect ratio has been | |
8262 | changed. | |
8263 | ||
8264 | @item charenc | |
8265 | Set subtitles input character encoding. @code{subtitles} filter only. Only | |
8266 | useful if not UTF-8. | |
8267 | ||
8268 | @item stream_index, si | |
8269 | Set subtitles stream index. @code{subtitles} filter only. | |
8270 | @end table | |
8271 | ||
8272 | If the first key is not specified, it is assumed that the first value | |
8273 | specifies the @option{filename}. | |
8274 | ||
8275 | For example, to render the file @file{sub.srt} on top of the input | |
8276 | video, use the command: | |
8277 | @example | |
8278 | subtitles=sub.srt | |
8279 | @end example | |
8280 | ||
8281 | which is equivalent to: | |
8282 | @example | |
8283 | subtitles=filename=sub.srt | |
8284 | @end example | |
8285 | ||
8286 | To render the default subtitles stream from file @file{video.mkv}, use: | |
8287 | @example | |
8288 | subtitles=video.mkv | |
8289 | @end example | |
8290 | ||
8291 | To render the second subtitles stream from that file, use: | |
8292 | @example | |
8293 | subtitles=video.mkv:si=1 | |
8294 | @end example | |
8295 | ||
8296 | @section super2xsai | |
8297 | ||
8298 | Scale the input by 2x and smooth using the Super2xSaI (Scale and | |
8299 | Interpolate) pixel art scaling algorithm. | |
8300 | ||
8301 | Useful for enlarging pixel art images without reducing sharpness. | |
8302 | ||
8303 | @section swapuv | |
8304 | Swap U & V plane. | |
8305 | ||
8306 | @section telecine | |
8307 | ||
8308 | Apply telecine process to the video. | |
8309 | ||
8310 | This filter accepts the following options: | |
8311 | ||
8312 | @table @option | |
8313 | @item first_field | |
8314 | @table @samp | |
8315 | @item top, t | |
8316 | top field first | |
8317 | @item bottom, b | |
8318 | bottom field first | |
8319 | The default value is @code{top}. | |
8320 | @end table | |
8321 | ||
8322 | @item pattern | |
8323 | A string of numbers representing the pulldown pattern you wish to apply. | |
8324 | The default value is @code{23}. | |
8325 | @end table | |
8326 | ||
8327 | @example | |
8328 | Some typical patterns: | |
8329 | ||
8330 | NTSC output (30i): | |
8331 | 27.5p: 32222 | |
8332 | 24p: 23 (classic) | |
8333 | 24p: 2332 (preferred) | |
8334 | 20p: 33 | |
8335 | 18p: 334 | |
8336 | 16p: 3444 | |
8337 | ||
8338 | PAL output (25i): | |
8339 | 27.5p: 12222 | |
8340 | 24p: 222222222223 ("Euro pulldown") | |
8341 | 16.67p: 33 | |
8342 | 16p: 33333334 | |
8343 | @end example | |
8344 | ||
8345 | @section thumbnail | |
8346 | Select the most representative frame in a given sequence of consecutive frames. | |
8347 | ||
8348 | The filter accepts the following options: | |
8349 | ||
8350 | @table @option | |
8351 | @item n | |
8352 | Set the frames batch size to analyze; in a set of @var{n} frames, the filter | |
8353 | will pick one of them, and then handle the next batch of @var{n} frames until | |
8354 | the end. Default is @code{100}. | |
8355 | @end table | |
8356 | ||
8357 | Since the filter keeps track of the whole frames sequence, a bigger @var{n} | |
8358 | value will result in a higher memory usage, so a high value is not recommended. | |
8359 | ||
8360 | @subsection Examples | |
8361 | ||
8362 | @itemize | |
8363 | @item | |
8364 | Extract one picture each 50 frames: | |
8365 | @example | |
8366 | thumbnail=50 | |
8367 | @end example | |
8368 | ||
8369 | @item | |
8370 | Complete example of a thumbnail creation with @command{ffmpeg}: | |
8371 | @example | |
8372 | ffmpeg -i in.avi -vf thumbnail,scale=300:200 -frames:v 1 out.png | |
8373 | @end example | |
8374 | @end itemize | |
8375 | ||
8376 | @section tile | |
8377 | ||
8378 | Tile several successive frames together. | |
8379 | ||
8380 | The filter accepts the following options: | |
8381 | ||
8382 | @table @option | |
8383 | ||
8384 | @item layout | |
8385 | Set the grid size (i.e. the number of lines and columns). For the syntax of | |
8386 | this option, check the "Video size" section in the ffmpeg-utils manual. | |
8387 | ||
8388 | @item nb_frames | |
8389 | Set the maximum number of frames to render in the given area. It must be less | |
8390 | than or equal to @var{w}x@var{h}. The default value is @code{0}, meaning all | |
8391 | the area will be used. | |
8392 | ||
8393 | @item margin | |
8394 | Set the outer border margin in pixels. | |
8395 | ||
8396 | @item padding | |
8397 | Set the inner border thickness (i.e. the number of pixels between frames). For | |
8398 | more advanced padding options (such as having different values for the edges), | |
8399 | refer to the pad video filter. | |
8400 | ||
8401 | @item color | |
8402 | Specify the color of the unused areaFor the syntax of this option, check the | |
8403 | "Color" section in the ffmpeg-utils manual. The default value of @var{color} | |
8404 | is "black". | |
8405 | @end table | |
8406 | ||
8407 | @subsection Examples | |
8408 | ||
8409 | @itemize | |
8410 | @item | |
8411 | Produce 8x8 PNG tiles of all keyframes (@option{-skip_frame nokey}) in a movie: | |
8412 | @example | |
8413 | ffmpeg -skip_frame nokey -i file.avi -vf 'scale=128:72,tile=8x8' -an -vsync 0 keyframes%03d.png | |
8414 | @end example | |
8415 | The @option{-vsync 0} is necessary to prevent @command{ffmpeg} from | |
8416 | duplicating each output frame to accommodate the originally detected frame | |
8417 | rate. | |
8418 | ||
8419 | @item | |
8420 | Display @code{5} pictures in an area of @code{3x2} frames, | |
8421 | with @code{7} pixels between them, and @code{2} pixels of initial margin, using | |
8422 | mixed flat and named options: | |
8423 | @example | |
8424 | tile=3x2:nb_frames=5:padding=7:margin=2 | |
8425 | @end example | |
8426 | @end itemize | |
8427 | ||
8428 | @section tinterlace | |
8429 | ||
8430 | Perform various types of temporal field interlacing. | |
8431 | ||
8432 | Frames are counted starting from 1, so the first input frame is | |
8433 | considered odd. | |
8434 | ||
8435 | The filter accepts the following options: | |
8436 | ||
8437 | @table @option | |
8438 | ||
8439 | @item mode | |
8440 | Specify the mode of the interlacing. This option can also be specified | |
8441 | as a value alone. See below for a list of values for this option. | |
8442 | ||
8443 | Available values are: | |
8444 | ||
8445 | @table @samp | |
8446 | @item merge, 0 | |
8447 | Move odd frames into the upper field, even into the lower field, | |
8448 | generating a double height frame at half frame rate. | |
8449 | ||
8450 | @item drop_odd, 1 | |
8451 | Only output even frames, odd frames are dropped, generating a frame with | |
8452 | unchanged height at half frame rate. | |
8453 | ||
8454 | @item drop_even, 2 | |
8455 | Only output odd frames, even frames are dropped, generating a frame with | |
8456 | unchanged height at half frame rate. | |
8457 | ||
8458 | @item pad, 3 | |
8459 | Expand each frame to full height, but pad alternate lines with black, | |
8460 | generating a frame with double height at the same input frame rate. | |
8461 | ||
8462 | @item interleave_top, 4 | |
8463 | Interleave the upper field from odd frames with the lower field from | |
8464 | even frames, generating a frame with unchanged height at half frame rate. | |
8465 | ||
8466 | @item interleave_bottom, 5 | |
8467 | Interleave the lower field from odd frames with the upper field from | |
8468 | even frames, generating a frame with unchanged height at half frame rate. | |
8469 | ||
8470 | @item interlacex2, 6 | |
8471 | Double frame rate with unchanged height. Frames are inserted each | |
8472 | containing the second temporal field from the previous input frame and | |
8473 | the first temporal field from the next input frame. This mode relies on | |
8474 | the top_field_first flag. Useful for interlaced video displays with no | |
8475 | field synchronisation. | |
8476 | @end table | |
8477 | ||
8478 | Numeric values are deprecated but are accepted for backward | |
8479 | compatibility reasons. | |
8480 | ||
8481 | Default mode is @code{merge}. | |
8482 | ||
8483 | @item flags | |
8484 | Specify flags influencing the filter process. | |
8485 | ||
8486 | Available value for @var{flags} is: | |
8487 | ||
8488 | @table @option | |
8489 | @item low_pass_filter, vlfp | |
8490 | Enable vertical low-pass filtering in the filter. | |
8491 | Vertical low-pass filtering is required when creating an interlaced | |
8492 | destination from a progressive source which contains high-frequency | |
8493 | vertical detail. Filtering will reduce interlace 'twitter' and Moire | |
8494 | patterning. | |
8495 | ||
8496 | Vertical low-pass filtering can only be enabled for @option{mode} | |
8497 | @var{interleave_top} and @var{interleave_bottom}. | |
8498 | ||
8499 | @end table | |
8500 | @end table | |
8501 | ||
8502 | @section transpose | |
8503 | ||
8504 | Transpose rows with columns in the input video and optionally flip it. | |
8505 | ||
8506 | It accepts the following parameters: | |
8507 | ||
8508 | @table @option | |
8509 | ||
8510 | @item dir | |
8511 | Specify the transposition direction. | |
8512 | ||
8513 | Can assume the following values: | |
8514 | @table @samp | |
8515 | @item 0, 4, cclock_flip | |
8516 | Rotate by 90 degrees counterclockwise and vertically flip (default), that is: | |
8517 | @example | |
8518 | L.R L.l | |
8519 | . . -> . . | |
8520 | l.r R.r | |
8521 | @end example | |
8522 | ||
8523 | @item 1, 5, clock | |
8524 | Rotate by 90 degrees clockwise, that is: | |
8525 | @example | |
8526 | L.R l.L | |
8527 | . . -> . . | |
8528 | l.r r.R | |
8529 | @end example | |
8530 | ||
8531 | @item 2, 6, cclock | |
8532 | Rotate by 90 degrees counterclockwise, that is: | |
8533 | @example | |
8534 | L.R R.r | |
8535 | . . -> . . | |
8536 | l.r L.l | |
8537 | @end example | |
8538 | ||
8539 | @item 3, 7, clock_flip | |
8540 | Rotate by 90 degrees clockwise and vertically flip, that is: | |
8541 | @example | |
8542 | L.R r.R | |
8543 | . . -> . . | |
8544 | l.r l.L | |
8545 | @end example | |
8546 | @end table | |
8547 | ||
8548 | For values between 4-7, the transposition is only done if the input | |
8549 | video geometry is portrait and not landscape. These values are | |
8550 | deprecated, the @code{passthrough} option should be used instead. | |
8551 | ||
8552 | Numerical values are deprecated, and should be dropped in favor of | |
8553 | symbolic constants. | |
8554 | ||
8555 | @item passthrough | |
8556 | Do not apply the transposition if the input geometry matches the one | |
8557 | specified by the specified value. It accepts the following values: | |
8558 | @table @samp | |
8559 | @item none | |
8560 | Always apply transposition. | |
8561 | @item portrait | |
8562 | Preserve portrait geometry (when @var{height} >= @var{width}). | |
8563 | @item landscape | |
8564 | Preserve landscape geometry (when @var{width} >= @var{height}). | |
8565 | @end table | |
8566 | ||
8567 | Default value is @code{none}. | |
8568 | @end table | |
8569 | ||
8570 | For example to rotate by 90 degrees clockwise and preserve portrait | |
8571 | layout: | |
8572 | @example | |
8573 | transpose=dir=1:passthrough=portrait | |
8574 | @end example | |
8575 | ||
8576 | The command above can also be specified as: | |
8577 | @example | |
8578 | transpose=1:portrait | |
8579 | @end example | |
8580 | ||
8581 | @section trim | |
8582 | Trim the input so that the output contains one continuous subpart of the input. | |
8583 | ||
8584 | It accepts the following parameters: | |
8585 | @table @option | |
8586 | @item start | |
8587 | Specify the time of the start of the kept section, i.e. the frame with the | |
8588 | timestamp @var{start} will be the first frame in the output. | |
8589 | ||
8590 | @item end | |
8591 | Specify the time of the first frame that will be dropped, i.e. the frame | |
8592 | immediately preceding the one with the timestamp @var{end} will be the last | |
8593 | frame in the output. | |
8594 | ||
8595 | @item start_pts | |
8596 | This is the same as @var{start}, except this option sets the start timestamp | |
8597 | in timebase units instead of seconds. | |
8598 | ||
8599 | @item end_pts | |
8600 | This is the same as @var{end}, except this option sets the end timestamp | |
8601 | in timebase units instead of seconds. | |
8602 | ||
8603 | @item duration | |
8604 | The maximum duration of the output in seconds. | |
8605 | ||
8606 | @item start_frame | |
8607 | The number of the first frame that should be passed to the output. | |
8608 | ||
8609 | @item end_frame | |
8610 | The number of the first frame that should be dropped. | |
8611 | @end table | |
8612 | ||
8613 | @option{start}, @option{end}, and @option{duration} are expressed as time | |
8614 | duration specifications; see | |
8615 | @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils} | |
8616 | for the accepted syntax. | |
8617 | ||
8618 | Note that the first two sets of the start/end options and the @option{duration} | |
8619 | option look at the frame timestamp, while the _frame variants simply count the | |
8620 | frames that pass through the filter. Also note that this filter does not modify | |
8621 | the timestamps. If you wish for the output timestamps to start at zero, insert a | |
8622 | setpts filter after the trim filter. | |
8623 | ||
8624 | If multiple start or end options are set, this filter tries to be greedy and | |
8625 | keep all the frames that match at least one of the specified constraints. To keep | |
8626 | only the part that matches all the constraints at once, chain multiple trim | |
8627 | filters. | |
8628 | ||
8629 | The defaults are such that all the input is kept. So it is possible to set e.g. | |
8630 | just the end values to keep everything before the specified time. | |
8631 | ||
8632 | Examples: | |
8633 | @itemize | |
8634 | @item | |
8635 | Drop everything except the second minute of input: | |
8636 | @example | |
8637 | ffmpeg -i INPUT -vf trim=60:120 | |
8638 | @end example | |
8639 | ||
8640 | @item | |
8641 | Keep only the first second: | |
8642 | @example | |
8643 | ffmpeg -i INPUT -vf trim=duration=1 | |
8644 | @end example | |
8645 | ||
8646 | @end itemize | |
8647 | ||
8648 | ||
8649 | @section unsharp | |
8650 | ||
8651 | Sharpen or blur the input video. | |
8652 | ||
8653 | It accepts the following parameters: | |
8654 | ||
8655 | @table @option | |
8656 | @item luma_msize_x, lx | |
8657 | Set the luma matrix horizontal size. It must be an odd integer between | |
8658 | 3 and 63. The default value is 5. | |
8659 | ||
8660 | @item luma_msize_y, ly | |
8661 | Set the luma matrix vertical size. It must be an odd integer between 3 | |
8662 | and 63. The default value is 5. | |
8663 | ||
8664 | @item luma_amount, la | |
8665 | Set the luma effect strength. It must be a floating point number, reasonable | |
8666 | values lay between -1.5 and 1.5. | |
8667 | ||
8668 | Negative values will blur the input video, while positive values will | |
8669 | sharpen it, a value of zero will disable the effect. | |
8670 | ||
8671 | Default value is 1.0. | |
8672 | ||
8673 | @item chroma_msize_x, cx | |
8674 | Set the chroma matrix horizontal size. It must be an odd integer | |
8675 | between 3 and 63. The default value is 5. | |
8676 | ||
8677 | @item chroma_msize_y, cy | |
8678 | Set the chroma matrix vertical size. It must be an odd integer | |
8679 | between 3 and 63. The default value is 5. | |
8680 | ||
8681 | @item chroma_amount, ca | |
8682 | Set the chroma effect strength. It must be a floating point number, reasonable | |
8683 | values lay between -1.5 and 1.5. | |
8684 | ||
8685 | Negative values will blur the input video, while positive values will | |
8686 | sharpen it, a value of zero will disable the effect. | |
8687 | ||
8688 | Default value is 0.0. | |
8689 | ||
8690 | @item opencl | |
8691 | If set to 1, specify using OpenCL capabilities, only available if | |
8692 | FFmpeg was configured with @code{--enable-opencl}. Default value is 0. | |
8693 | ||
8694 | @end table | |
8695 | ||
8696 | All parameters are optional and default to the equivalent of the | |
8697 | string '5:5:1.0:5:5:0.0'. | |
8698 | ||
8699 | @subsection Examples | |
8700 | ||
8701 | @itemize | |
8702 | @item | |
8703 | Apply strong luma sharpen effect: | |
8704 | @example | |
8705 | unsharp=luma_msize_x=7:luma_msize_y=7:luma_amount=2.5 | |
8706 | @end example | |
8707 | ||
8708 | @item | |
8709 | Apply a strong blur of both luma and chroma parameters: | |
8710 | @example | |
8711 | unsharp=7:7:-2:7:7:-2 | |
8712 | @end example | |
8713 | @end itemize | |
8714 | ||
8715 | @anchor{vidstabdetect} | |
8716 | @section vidstabdetect | |
8717 | ||
8718 | Analyze video stabilization/deshaking. Perform pass 1 of 2, see | |
8719 | @ref{vidstabtransform} for pass 2. | |
8720 | ||
8721 | This filter generates a file with relative translation and rotation | |
8722 | transform information about subsequent frames, which is then used by | |
8723 | the @ref{vidstabtransform} filter. | |
8724 | ||
8725 | To enable compilation of this filter you need to configure FFmpeg with | |
8726 | @code{--enable-libvidstab}. | |
8727 | ||
8728 | This filter accepts the following options: | |
8729 | ||
8730 | @table @option | |
8731 | @item result | |
8732 | Set the path to the file used to write the transforms information. | |
8733 | Default value is @file{transforms.trf}. | |
8734 | ||
8735 | @item shakiness | |
8736 | Set how shaky the video is and how quick the camera is. It accepts an | |
8737 | integer in the range 1-10, a value of 1 means little shakiness, a | |
8738 | value of 10 means strong shakiness. Default value is 5. | |
8739 | ||
8740 | @item accuracy | |
8741 | Set the accuracy of the detection process. It must be a value in the | |
8742 | range 1-15. A value of 1 means low accuracy, a value of 15 means high | |
8743 | accuracy. Default value is 15. | |
8744 | ||
8745 | @item stepsize | |
8746 | Set stepsize of the search process. The region around minimum is | |
8747 | scanned with 1 pixel resolution. Default value is 6. | |
8748 | ||
8749 | @item mincontrast | |
8750 | Set minimum contrast. Below this value a local measurement field is | |
8751 | discarded. Must be a floating point value in the range 0-1. Default | |
8752 | value is 0.3. | |
8753 | ||
8754 | @item tripod | |
8755 | Set reference frame number for tripod mode. | |
8756 | ||
8757 | If enabled, the motion of the frames is compared to a reference frame | |
8758 | in the filtered stream, identified by the specified number. The idea | |
8759 | is to compensate all movements in a more-or-less static scene and keep | |
8760 | the camera view absolutely still. | |
8761 | ||
8762 | If set to 0, it is disabled. The frames are counted starting from 1. | |
8763 | ||
8764 | @item show | |
8765 | Show fields and transforms in the resulting frames. It accepts an | |
8766 | integer in the range 0-2. Default value is 0, which disables any | |
8767 | visualization. | |
8768 | @end table | |
8769 | ||
8770 | @subsection Examples | |
8771 | ||
8772 | @itemize | |
8773 | @item | |
8774 | Use default values: | |
8775 | @example | |
8776 | vidstabdetect | |
8777 | @end example | |
8778 | ||
8779 | @item | |
8780 | Analyze strongly shaky movie and put the results in file | |
8781 | @file{mytransforms.trf}: | |
8782 | @example | |
8783 | vidstabdetect=shakiness=10:accuracy=15:result="mytransforms.trf" | |
8784 | @end example | |
8785 | ||
8786 | @item | |
8787 | Visualize the result of internal transformations in the resulting | |
8788 | video: | |
8789 | @example | |
8790 | vidstabdetect=show=1 | |
8791 | @end example | |
8792 | ||
8793 | @item | |
8794 | Analyze a video with medium shakiness using @command{ffmpeg}: | |
8795 | @example | |
8796 | ffmpeg -i input -vf vidstabdetect=shakiness=5:show=1 dummy.avi | |
8797 | @end example | |
8798 | @end itemize | |
8799 | ||
8800 | @anchor{vidstabtransform} | |
8801 | @section vidstabtransform | |
8802 | ||
8803 | Video stabilization/deshaking: pass 2 of 2, | |
8804 | see @ref{vidstabdetect} for pass 1. | |
8805 | ||
8806 | Read a file with transform information for each frame and | |
8807 | apply/compensate them. Together with the @ref{vidstabdetect} | |
8808 | filter this can be used to deshake videos. See also | |
8809 | @url{http://public.hronopik.de/vid.stab}. It is important to also use | |
8810 | the unsharp filter, see below. | |
8811 | ||
8812 | To enable compilation of this filter you need to configure FFmpeg with | |
8813 | @code{--enable-libvidstab}. | |
8814 | ||
8815 | @subsection Options | |
8816 | ||
8817 | @table @option | |
8818 | @item input | |
8819 | Set path to the file used to read the transforms. Default value is | |
8820 | @file{transforms.trf}). | |
8821 | ||
8822 | @item smoothing | |
8823 | Set the number of frames (value*2 + 1) used for lowpass filtering the | |
8824 | camera movements. Default value is 10. | |
8825 | ||
8826 | For example a number of 10 means that 21 frames are used (10 in the | |
8827 | past and 10 in the future) to smoothen the motion in the video. A | |
8828 | larger values leads to a smoother video, but limits the acceleration | |
8829 | of the camera (pan/tilt movements). 0 is a special case where a | |
8830 | static camera is simulated. | |
8831 | ||
8832 | @item optalgo | |
8833 | Set the camera path optimization algorithm. | |
8834 | ||
8835 | Accepted values are: | |
8836 | @table @samp | |
8837 | @item gauss | |
8838 | gaussian kernel low-pass filter on camera motion (default) | |
8839 | @item avg | |
8840 | averaging on transformations | |
8841 | @end table | |
8842 | ||
8843 | @item maxshift | |
8844 | Set maximal number of pixels to translate frames. Default value is -1, | |
8845 | meaning no limit. | |
8846 | ||
8847 | @item maxangle | |
8848 | Set maximal angle in radians (degree*PI/180) to rotate frames. Default | |
8849 | value is -1, meaning no limit. | |
8850 | ||
8851 | @item crop | |
8852 | Specify how to deal with borders that may be visible due to movement | |
8853 | compensation. | |
8854 | ||
8855 | Available values are: | |
8856 | @table @samp | |
8857 | @item keep | |
8858 | keep image information from previous frame (default) | |
8859 | @item black | |
8860 | fill the border black | |
8861 | @end table | |
8862 | ||
8863 | @item invert | |
8864 | Invert transforms if set to 1. Default value is 0. | |
8865 | ||
8866 | @item relative | |
8867 | Consider transforms as relative to previsou frame if set to 1, | |
8868 | absolute if set to 0. Default value is 0. | |
8869 | ||
8870 | @item zoom | |
8871 | Set percentage to zoom. A positive value will result in a zoom-in | |
8872 | effect, a negative value in a zoom-out effect. Default value is 0 (no | |
8873 | zoom). | |
8874 | ||
8875 | @item optzoom | |
8876 | Set optimal zooming to avoid borders. | |
8877 | ||
8878 | Accepted values are: | |
8879 | @table @samp | |
8880 | @item 0 | |
8881 | disabled | |
8882 | @item 1 | |
8883 | optimal static zoom value is determined (only very strong movements | |
8884 | will lead to visible borders) (default) | |
8885 | @item 2 | |
8886 | optimal adaptive zoom value is determined (no borders will be | |
8887 | visible), see @option{zoomspeed} | |
8888 | @end table | |
8889 | ||
8890 | Note that the value given at zoom is added to the one calculated here. | |
8891 | ||
8892 | @item zoomspeed | |
8893 | Set percent to zoom maximally each frame (enabled when | |
8894 | @option{optzoom} is set to 2). Range is from 0 to 5, default value is | |
8895 | 0.25. | |
8896 | ||
8897 | @item interpol | |
8898 | Specify type of interpolation. | |
8899 | ||
8900 | Available values are: | |
8901 | @table @samp | |
8902 | @item no | |
8903 | no interpolation | |
8904 | @item linear | |
8905 | linear only horizontal | |
8906 | @item bilinear | |
8907 | linear in both directions (default) | |
8908 | @item bicubic | |
8909 | cubic in both directions (slow) | |
8910 | @end table | |
8911 | ||
8912 | @item tripod | |
8913 | Enable virtual tripod mode if set to 1, which is equivalent to | |
8914 | @code{relative=0:smoothing=0}. Default value is 0. | |
8915 | ||
8916 | Use also @code{tripod} option of @ref{vidstabdetect}. | |
8917 | ||
8918 | @item debug | |
8919 | Increase log verbosity if set to 1. Also the detected global motions | |
8920 | are written to the temporary file @file{global_motions.trf}. Default | |
8921 | value is 0. | |
8922 | @end table | |
8923 | ||
8924 | @subsection Examples | |
8925 | ||
8926 | @itemize | |
8927 | @item | |
8928 | Use @command{ffmpeg} for a typical stabilization with default values: | |
8929 | @example | |
8930 | ffmpeg -i inp.mpeg -vf vidstabtransform,unsharp=5:5:0.8:3:3:0.4 inp_stabilized.mpeg | |
8931 | @end example | |
8932 | ||
8933 | Note the use of the unsharp filter which is always recommended. | |
8934 | ||
8935 | @item | |
8936 | Zoom in a bit more and load transform data from a given file: | |
8937 | @example | |
8938 | vidstabtransform=zoom=5:input="mytransforms.trf" | |
8939 | @end example | |
8940 | ||
8941 | @item | |
8942 | Smoothen the video even more: | |
8943 | @example | |
8944 | vidstabtransform=smoothing=30 | |
8945 | @end example | |
8946 | @end itemize | |
8947 | ||
8948 | @section vflip | |
8949 | ||
8950 | Flip the input video vertically. | |
8951 | ||
8952 | For example, to vertically flip a video with @command{ffmpeg}: | |
8953 | @example | |
8954 | ffmpeg -i in.avi -vf "vflip" out.avi | |
8955 | @end example | |
8956 | ||
8957 | @anchor{vignette} | |
8958 | @section vignette | |
8959 | ||
8960 | Make or reverse a natural vignetting effect. | |
8961 | ||
8962 | The filter accepts the following options: | |
8963 | ||
8964 | @table @option | |
8965 | @item angle, a | |
8966 | Set lens angle expression as a number of radians. | |
8967 | ||
8968 | The value is clipped in the @code{[0,PI/2]} range. | |
8969 | ||
8970 | Default value: @code{"PI/5"} | |
8971 | ||
8972 | @item x0 | |
8973 | @item y0 | |
8974 | Set center coordinates expressions. Respectively @code{"w/2"} and @code{"h/2"} | |
8975 | by default. | |
8976 | ||
8977 | @item mode | |
8978 | Set forward/backward mode. | |
8979 | ||
8980 | Available modes are: | |
8981 | @table @samp | |
8982 | @item forward | |
8983 | The larger the distance from the central point, the darker the image becomes. | |
8984 | ||
8985 | @item backward | |
8986 | The larger the distance from the central point, the brighter the image becomes. | |
8987 | This can be used to reverse a vignette effect, though there is no automatic | |
8988 | detection to extract the lens @option{angle} and other settings (yet). It can | |
8989 | also be used to create a burning effect. | |
8990 | @end table | |
8991 | ||
8992 | Default value is @samp{forward}. | |
8993 | ||
8994 | @item eval | |
8995 | Set evaluation mode for the expressions (@option{angle}, @option{x0}, @option{y0}). | |
8996 | ||
8997 | It accepts the following values: | |
8998 | @table @samp | |
8999 | @item init | |
9000 | Evaluate expressions only once during the filter initialization. | |
9001 | ||
9002 | @item frame | |
9003 | Evaluate expressions for each incoming frame. This is way slower than the | |
9004 | @samp{init} mode since it requires all the scalers to be re-computed, but it | |
9005 | allows advanced dynamic expressions. | |
9006 | @end table | |
9007 | ||
9008 | Default value is @samp{init}. | |
9009 | ||
9010 | @item dither | |
9011 | Set dithering to reduce the circular banding effects. Default is @code{1} | |
9012 | (enabled). | |
9013 | ||
9014 | @item aspect | |
9015 | Set vignette aspect. This setting allows one to adjust the shape of the vignette. | |
9016 | Setting this value to the SAR of the input will make a rectangular vignetting | |
9017 | following the dimensions of the video. | |
9018 | ||
9019 | Default is @code{1/1}. | |
9020 | @end table | |
9021 | ||
9022 | @subsection Expressions | |
9023 | ||
9024 | The @option{alpha}, @option{x0} and @option{y0} expressions can contain the | |
9025 | following parameters. | |
9026 | ||
9027 | @table @option | |
9028 | @item w | |
9029 | @item h | |
9030 | input width and height | |
9031 | ||
9032 | @item n | |
9033 | the number of input frame, starting from 0 | |
9034 | ||
9035 | @item pts | |
9036 | the PTS (Presentation TimeStamp) time of the filtered video frame, expressed in | |
9037 | @var{TB} units, NAN if undefined | |
9038 | ||
9039 | @item r | |
9040 | frame rate of the input video, NAN if the input frame rate is unknown | |
9041 | ||
9042 | @item t | |
9043 | the PTS (Presentation TimeStamp) of the filtered video frame, | |
9044 | expressed in seconds, NAN if undefined | |
9045 | ||
9046 | @item tb | |
9047 | time base of the input video | |
9048 | @end table | |
9049 | ||
9050 | ||
9051 | @subsection Examples | |
9052 | ||
9053 | @itemize | |
9054 | @item | |
9055 | Apply simple strong vignetting effect: | |
9056 | @example | |
9057 | vignette=PI/4 | |
9058 | @end example | |
9059 | ||
9060 | @item | |
9061 | Make a flickering vignetting: | |
9062 | @example | |
9063 | vignette='PI/4+random(1)*PI/50':eval=frame | |
9064 | @end example | |
9065 | ||
9066 | @end itemize | |
9067 | ||
9068 | @section w3fdif | |
9069 | ||
9070 | Deinterlace the input video ("w3fdif" stands for "Weston 3 Field | |
9071 | Deinterlacing Filter"). | |
9072 | ||
9073 | Based on the process described by Martin Weston for BBC R&D, and | |
9074 | implemented based on the de-interlace algorithm written by Jim | |
9075 | Easterbrook for BBC R&D, the Weston 3 field deinterlacing filter | |
9076 | uses filter coefficients calculated by BBC R&D. | |
9077 | ||
9078 | There are two sets of filter coefficients, so called "simple": | |
9079 | and "complex". Which set of filter coefficients is used can | |
9080 | be set by passing an optional parameter: | |
9081 | ||
9082 | @table @option | |
9083 | @item filter | |
9084 | Set the interlacing filter coefficients. Accepts one of the following values: | |
9085 | ||
9086 | @table @samp | |
9087 | @item simple | |
9088 | Simple filter coefficient set. | |
9089 | @item complex | |
9090 | More-complex filter coefficient set. | |
9091 | @end table | |
9092 | Default value is @samp{complex}. | |
9093 | ||
9094 | @item deint | |
9095 | Specify which frames to deinterlace. Accept one of the following values: | |
9096 | ||
9097 | @table @samp | |
9098 | @item all | |
9099 | Deinterlace all frames, | |
9100 | @item interlaced | |
9101 | Only deinterlace frames marked as interlaced. | |
9102 | @end table | |
9103 | ||
9104 | Default value is @samp{all}. | |
9105 | @end table | |
9106 | ||
9107 | @anchor{yadif} | |
9108 | @section yadif | |
9109 | ||
9110 | Deinterlace the input video ("yadif" means "yet another deinterlacing | |
9111 | filter"). | |
9112 | ||
9113 | It accepts the following parameters: | |
9114 | ||
9115 | ||
9116 | @table @option | |
9117 | ||
9118 | @item mode | |
9119 | The interlacing mode to adopt. It accepts one of the following values: | |
9120 | ||
9121 | @table @option | |
9122 | @item 0, send_frame | |
9123 | Output one frame for each frame. | |
9124 | @item 1, send_field | |
9125 | Output one frame for each field. | |
9126 | @item 2, send_frame_nospatial | |
9127 | Like @code{send_frame}, but it skips the spatial interlacing check. | |
9128 | @item 3, send_field_nospatial | |
9129 | Like @code{send_field}, but it skips the spatial interlacing check. | |
9130 | @end table | |
9131 | ||
9132 | The default value is @code{send_frame}. | |
9133 | ||
9134 | @item parity | |
9135 | The picture field parity assumed for the input interlaced video. It accepts one | |
9136 | of the following values: | |
9137 | ||
9138 | @table @option | |
9139 | @item 0, tff | |
9140 | Assume the top field is first. | |
9141 | @item 1, bff | |
9142 | Assume the bottom field is first. | |
9143 | @item -1, auto | |
9144 | Enable automatic detection of field parity. | |
9145 | @end table | |
9146 | ||
9147 | The default value is @code{auto}. | |
9148 | If the interlacing is unknown or the decoder does not export this information, | |
9149 | top field first will be assumed. | |
9150 | ||
9151 | @item deint | |
9152 | Specify which frames to deinterlace. Accept one of the following | |
9153 | values: | |
9154 | ||
9155 | @table @option | |
9156 | @item 0, all | |
9157 | Deinterlace all frames. | |
9158 | @item 1, interlaced | |
9159 | Only deinterlace frames marked as interlaced. | |
9160 | @end table | |
9161 | ||
9162 | The default value is @code{all}. | |
9163 | @end table | |
9164 | ||
9165 | @section zoompan | |
9166 | ||
9167 | Apply Zoom & Pan effect. | |
9168 | ||
9169 | This filter accepts the following options: | |
9170 | ||
9171 | @table @option | |
9172 | @item zoom, z | |
9173 | Set the zoom expression. Default is 1. | |
9174 | ||
9175 | @item x | |
9176 | @item y | |
9177 | Set the x and y expression. Default is 0. | |
9178 | ||
9179 | @item d | |
9180 | Set the duration expression in number of frames. | |
9181 | This sets for how many number of frames effect will last for | |
9182 | single input image. | |
9183 | ||
9184 | @item s | |
9185 | Set the output image size, default is 'hd720'. | |
9186 | @end table | |
9187 | ||
9188 | Each expression can contain the following constants: | |
9189 | ||
9190 | @table @option | |
9191 | @item in_w, iw | |
9192 | Input width. | |
9193 | ||
9194 | @item in_h, ih | |
9195 | Input height. | |
9196 | ||
9197 | @item out_w, ow | |
9198 | Output width. | |
9199 | ||
9200 | @item out_h, oh | |
9201 | Output height. | |
9202 | ||
9203 | @item in | |
9204 | Input frame count. | |
9205 | ||
9206 | @item on | |
9207 | Output frame count. | |
9208 | ||
9209 | @item x | |
9210 | @item y | |
9211 | Last calculated 'x' and 'y' position from 'x' and 'y' expression | |
9212 | for current input frame. | |
9213 | ||
9214 | @item px | |
9215 | @item py | |
9216 | 'x' and 'y' of last output frame of previous input frame or 0 when there was | |
9217 | not yet such frame (first input frame). | |
9218 | ||
9219 | @item zoom | |
9220 | Last calculated zoom from 'z' expression for current input frame. | |
9221 | ||
9222 | @item pzoom | |
9223 | Last calculated zoom of last output frame of previous input frame. | |
9224 | ||
9225 | @item duration | |
9226 | Number of output frames for current input frame. Calculated from 'd' expression | |
9227 | for each input frame. | |
9228 | ||
9229 | @item pduration | |
9230 | number of output frames created for previous input frame | |
9231 | ||
9232 | @item a | |
9233 | Rational number: input width / input height | |
9234 | ||
9235 | @item sar | |
9236 | sample aspect ratio | |
9237 | ||
9238 | @item dar | |
9239 | display aspect ratio | |
9240 | ||
9241 | @end table | |
9242 | ||
9243 | @subsection Examples | |
9244 | ||
9245 | @itemize | |
9246 | @item | |
9247 | Zoom-in up to 1.5 and pan at same time to some spot near center of picture: | |
9248 | @example | |
9249 | 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 | |
9250 | @end example | |
9251 | @end itemize | |
9252 | ||
9253 | @c man end VIDEO FILTERS | |
9254 | ||
9255 | @chapter Video Sources | |
9256 | @c man begin VIDEO SOURCES | |
9257 | ||
9258 | Below is a description of the currently available video sources. | |
9259 | ||
9260 | @section buffer | |
9261 | ||
9262 | Buffer video frames, and make them available to the filter chain. | |
9263 | ||
9264 | This source is mainly intended for a programmatic use, in particular | |
9265 | through the interface defined in @file{libavfilter/vsrc_buffer.h}. | |
9266 | ||
9267 | It accepts the following parameters: | |
9268 | ||
9269 | @table @option | |
9270 | ||
9271 | @item video_size | |
9272 | Specify the size (width and height) of the buffered video frames. For the | |
9273 | syntax of this option, check the "Video size" section in the ffmpeg-utils | |
9274 | manual. | |
9275 | ||
9276 | @item width | |
9277 | The input video width. | |
9278 | ||
9279 | @item height | |
9280 | The input video height. | |
9281 | ||
9282 | @item pix_fmt | |
9283 | A string representing the pixel format of the buffered video frames. | |
9284 | It may be a number corresponding to a pixel format, or a pixel format | |
9285 | name. | |
9286 | ||
9287 | @item time_base | |
9288 | Specify the timebase assumed by the timestamps of the buffered frames. | |
9289 | ||
9290 | @item frame_rate | |
9291 | Specify the frame rate expected for the video stream. | |
9292 | ||
9293 | @item pixel_aspect, sar | |
9294 | The sample (pixel) aspect ratio of the input video. | |
9295 | ||
9296 | @item sws_param | |
9297 | Specify the optional parameters to be used for the scale filter which | |
9298 | is automatically inserted when an input change is detected in the | |
9299 | input size or format. | |
9300 | @end table | |
9301 | ||
9302 | For example: | |
9303 | @example | |
9304 | buffer=width=320:height=240:pix_fmt=yuv410p:time_base=1/24:sar=1 | |
9305 | @end example | |
9306 | ||
9307 | will instruct the source to accept video frames with size 320x240 and | |
9308 | with format "yuv410p", assuming 1/24 as the timestamps timebase and | |
9309 | square pixels (1:1 sample aspect ratio). | |
9310 | Since the pixel format with name "yuv410p" corresponds to the number 6 | |
9311 | (check the enum AVPixelFormat definition in @file{libavutil/pixfmt.h}), | |
9312 | this example corresponds to: | |
9313 | @example | |
9314 | buffer=size=320x240:pixfmt=6:time_base=1/24:pixel_aspect=1/1 | |
9315 | @end example | |
9316 | ||
9317 | Alternatively, the options can be specified as a flat string, but this | |
9318 | syntax is deprecated: | |
9319 | ||
9320 | @var{width}:@var{height}:@var{pix_fmt}:@var{time_base.num}:@var{time_base.den}:@var{pixel_aspect.num}:@var{pixel_aspect.den}[:@var{sws_param}] | |
9321 | ||
9322 | @section cellauto | |
9323 | ||
9324 | Create a pattern generated by an elementary cellular automaton. | |
9325 | ||
9326 | The initial state of the cellular automaton can be defined through the | |
9327 | @option{filename}, and @option{pattern} options. If such options are | |
9328 | not specified an initial state is created randomly. | |
9329 | ||
9330 | At each new frame a new row in the video is filled with the result of | |
9331 | the cellular automaton next generation. The behavior when the whole | |
9332 | frame is filled is defined by the @option{scroll} option. | |
9333 | ||
9334 | This source accepts the following options: | |
9335 | ||
9336 | @table @option | |
9337 | @item filename, f | |
9338 | Read the initial cellular automaton state, i.e. the starting row, from | |
9339 | the specified file. | |
9340 | In the file, each non-whitespace character is considered an alive | |
9341 | cell, a newline will terminate the row, and further characters in the | |
9342 | file will be ignored. | |
9343 | ||
9344 | @item pattern, p | |
9345 | Read the initial cellular automaton state, i.e. the starting row, from | |
9346 | the specified string. | |
9347 | ||
9348 | Each non-whitespace character in the string is considered an alive | |
9349 | cell, a newline will terminate the row, and further characters in the | |
9350 | string will be ignored. | |
9351 | ||
9352 | @item rate, r | |
9353 | Set the video rate, that is the number of frames generated per second. | |
9354 | Default is 25. | |
9355 | ||
9356 | @item random_fill_ratio, ratio | |
9357 | Set the random fill ratio for the initial cellular automaton row. It | |
9358 | is a floating point number value ranging from 0 to 1, defaults to | |
9359 | 1/PHI. | |
9360 | ||
9361 | This option is ignored when a file or a pattern is specified. | |
9362 | ||
9363 | @item random_seed, seed | |
9364 | Set the seed for filling randomly the initial row, must be an integer | |
9365 | included between 0 and UINT32_MAX. If not specified, or if explicitly | |
9366 | set to -1, the filter will try to use a good random seed on a best | |
9367 | effort basis. | |
9368 | ||
9369 | @item rule | |
9370 | Set the cellular automaton rule, it is a number ranging from 0 to 255. | |
9371 | Default value is 110. | |
9372 | ||
9373 | @item size, s | |
9374 | Set the size of the output video. For the syntax of this option, check | |
9375 | the "Video size" section in the ffmpeg-utils manual. | |
9376 | ||
9377 | If @option{filename} or @option{pattern} is specified, the size is set | |
9378 | by default to the width of the specified initial state row, and the | |
9379 | height is set to @var{width} * PHI. | |
9380 | ||
9381 | If @option{size} is set, it must contain the width of the specified | |
9382 | pattern string, and the specified pattern will be centered in the | |
9383 | larger row. | |
9384 | ||
9385 | If a filename or a pattern string is not specified, the size value | |
9386 | defaults to "320x518" (used for a randomly generated initial state). | |
9387 | ||
9388 | @item scroll | |
9389 | If set to 1, scroll the output upward when all the rows in the output | |
9390 | have been already filled. If set to 0, the new generated row will be | |
9391 | written over the top row just after the bottom row is filled. | |
9392 | Defaults to 1. | |
9393 | ||
9394 | @item start_full, full | |
9395 | If set to 1, completely fill the output with generated rows before | |
9396 | outputting the first frame. | |
9397 | This is the default behavior, for disabling set the value to 0. | |
9398 | ||
9399 | @item stitch | |
9400 | If set to 1, stitch the left and right row edges together. | |
9401 | This is the default behavior, for disabling set the value to 0. | |
9402 | @end table | |
9403 | ||
9404 | @subsection Examples | |
9405 | ||
9406 | @itemize | |
9407 | @item | |
9408 | Read the initial state from @file{pattern}, and specify an output of | |
9409 | size 200x400. | |
9410 | @example | |
9411 | cellauto=f=pattern:s=200x400 | |
9412 | @end example | |
9413 | ||
9414 | @item | |
9415 | Generate a random initial row with a width of 200 cells, with a fill | |
9416 | ratio of 2/3: | |
9417 | @example | |
9418 | cellauto=ratio=2/3:s=200x200 | |
9419 | @end example | |
9420 | ||
9421 | @item | |
9422 | Create a pattern generated by rule 18 starting by a single alive cell | |
9423 | centered on an initial row with width 100: | |
9424 | @example | |
9425 | cellauto=p=@@:s=100x400:full=0:rule=18 | |
9426 | @end example | |
9427 | ||
9428 | @item | |
9429 | Specify a more elaborated initial pattern: | |
9430 | @example | |
9431 | cellauto=p='@@@@ @@ @@@@':s=100x400:full=0:rule=18 | |
9432 | @end example | |
9433 | ||
9434 | @end itemize | |
9435 | ||
9436 | @section mandelbrot | |
9437 | ||
9438 | Generate a Mandelbrot set fractal, and progressively zoom towards the | |
9439 | point specified with @var{start_x} and @var{start_y}. | |
9440 | ||
9441 | This source accepts the following options: | |
9442 | ||
9443 | @table @option | |
9444 | ||
9445 | @item end_pts | |
9446 | Set the terminal pts value. Default value is 400. | |
9447 | ||
9448 | @item end_scale | |
9449 | Set the terminal scale value. | |
9450 | Must be a floating point value. Default value is 0.3. | |
9451 | ||
9452 | @item inner | |
9453 | Set the inner coloring mode, that is the algorithm used to draw the | |
9454 | Mandelbrot fractal internal region. | |
9455 | ||
9456 | It shall assume one of the following values: | |
9457 | @table @option | |
9458 | @item black | |
9459 | Set black mode. | |
9460 | @item convergence | |
9461 | Show time until convergence. | |
9462 | @item mincol | |
9463 | Set color based on point closest to the origin of the iterations. | |
9464 | @item period | |
9465 | Set period mode. | |
9466 | @end table | |
9467 | ||
9468 | Default value is @var{mincol}. | |
9469 | ||
9470 | @item bailout | |
9471 | Set the bailout value. Default value is 10.0. | |
9472 | ||
9473 | @item maxiter | |
9474 | Set the maximum of iterations performed by the rendering | |
9475 | algorithm. Default value is 7189. | |
9476 | ||
9477 | @item outer | |
9478 | Set outer coloring mode. | |
9479 | It shall assume one of following values: | |
9480 | @table @option | |
9481 | @item iteration_count | |
9482 | Set iteration cound mode. | |
9483 | @item normalized_iteration_count | |
9484 | set normalized iteration count mode. | |
9485 | @end table | |
9486 | Default value is @var{normalized_iteration_count}. | |
9487 | ||
9488 | @item rate, r | |
9489 | Set frame rate, expressed as number of frames per second. Default | |
9490 | value is "25". | |
9491 | ||
9492 | @item size, s | |
9493 | Set frame size. For the syntax of this option, check the "Video | |
9494 | size" section in the ffmpeg-utils manual. Default value is "640x480". | |
9495 | ||
9496 | @item start_scale | |
9497 | Set the initial scale value. Default value is 3.0. | |
9498 | ||
9499 | @item start_x | |
9500 | Set the initial x position. Must be a floating point value between | |
9501 | -100 and 100. Default value is -0.743643887037158704752191506114774. | |
9502 | ||
9503 | @item start_y | |
9504 | Set the initial y position. Must be a floating point value between | |
9505 | -100 and 100. Default value is -0.131825904205311970493132056385139. | |
9506 | @end table | |
9507 | ||
9508 | @section mptestsrc | |
9509 | ||
9510 | Generate various test patterns, as generated by the MPlayer test filter. | |
9511 | ||
9512 | The size of the generated video is fixed, and is 256x256. | |
9513 | This source is useful in particular for testing encoding features. | |
9514 | ||
9515 | This source accepts the following options: | |
9516 | ||
9517 | @table @option | |
9518 | ||
9519 | @item rate, r | |
9520 | Specify the frame rate of the sourced video, as the number of frames | |
9521 | generated per second. It has to be a string in the format | |
9522 | @var{frame_rate_num}/@var{frame_rate_den}, an integer number, a floating point | |
9523 | number or a valid video frame rate abbreviation. The default value is | |
9524 | "25". | |
9525 | ||
9526 | @item duration, d | |
9527 | Set the duration of the sourced video. See | |
9528 | @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils} | |
9529 | for the accepted syntax. | |
9530 | ||
9531 | If not specified, or the expressed duration is negative, the video is | |
9532 | supposed to be generated forever. | |
9533 | ||
9534 | @item test, t | |
9535 | ||
9536 | Set the number or the name of the test to perform. Supported tests are: | |
9537 | @table @option | |
9538 | @item dc_luma | |
9539 | @item dc_chroma | |
9540 | @item freq_luma | |
9541 | @item freq_chroma | |
9542 | @item amp_luma | |
9543 | @item amp_chroma | |
9544 | @item cbp | |
9545 | @item mv | |
9546 | @item ring1 | |
9547 | @item ring2 | |
9548 | @item all | |
9549 | ||
9550 | @end table | |
9551 | ||
9552 | Default value is "all", which will cycle through the list of all tests. | |
9553 | @end table | |
9554 | ||
9555 | Some examples: | |
9556 | @example | |
9557 | mptestsrc=t=dc_luma | |
9558 | @end example | |
9559 | ||
9560 | will generate a "dc_luma" test pattern. | |
9561 | ||
9562 | @section frei0r_src | |
9563 | ||
9564 | Provide a frei0r source. | |
9565 | ||
9566 | To enable compilation of this filter you need to install the frei0r | |
9567 | header and configure FFmpeg with @code{--enable-frei0r}. | |
9568 | ||
9569 | This source accepts the following parameters: | |
9570 | ||
9571 | @table @option | |
9572 | ||
9573 | @item size | |
9574 | The size of the video to generate. For the syntax of this option, check the | |
9575 | "Video size" section in the ffmpeg-utils manual. | |
9576 | ||
9577 | @item framerate | |
9578 | The framerate of the generated video. It may be a string of the form | |
9579 | @var{num}/@var{den} or a frame rate abbreviation. | |
9580 | ||
9581 | @item filter_name | |
9582 | The name to the frei0r source to load. For more information regarding frei0r and | |
9583 | how to set the parameters, read the @ref{frei0r} section in the video filters | |
9584 | documentation. | |
9585 | ||
9586 | @item filter_params | |
9587 | A '|'-separated list of parameters to pass to the frei0r source. | |
9588 | ||
9589 | @end table | |
9590 | ||
9591 | For example, to generate a frei0r partik0l source with size 200x200 | |
9592 | and frame rate 10 which is overlayed on the overlay filter main input: | |
9593 | @example | |
9594 | frei0r_src=size=200x200:framerate=10:filter_name=partik0l:filter_params=1234 [overlay]; [in][overlay] overlay | |
9595 | @end example | |
9596 | ||
9597 | @section life | |
9598 | ||
9599 | Generate a life pattern. | |
9600 | ||
9601 | This source is based on a generalization of John Conway's life game. | |
9602 | ||
9603 | The sourced input represents a life grid, each pixel represents a cell | |
9604 | which can be in one of two possible states, alive or dead. Every cell | |
9605 | interacts with its eight neighbours, which are the cells that are | |
9606 | horizontally, vertically, or diagonally adjacent. | |
9607 | ||
9608 | At each interaction the grid evolves according to the adopted rule, | |
9609 | which specifies the number of neighbor alive cells which will make a | |
9610 | cell stay alive or born. The @option{rule} option allows one to specify | |
9611 | the rule to adopt. | |
9612 | ||
9613 | This source accepts the following options: | |
9614 | ||
9615 | @table @option | |
9616 | @item filename, f | |
9617 | Set the file from which to read the initial grid state. In the file, | |
9618 | each non-whitespace character is considered an alive cell, and newline | |
9619 | is used to delimit the end of each row. | |
9620 | ||
9621 | If this option is not specified, the initial grid is generated | |
9622 | randomly. | |
9623 | ||
9624 | @item rate, r | |
9625 | Set the video rate, that is the number of frames generated per second. | |
9626 | Default is 25. | |
9627 | ||
9628 | @item random_fill_ratio, ratio | |
9629 | Set the random fill ratio for the initial random grid. It is a | |
9630 | floating point number value ranging from 0 to 1, defaults to 1/PHI. | |
9631 | It is ignored when a file is specified. | |
9632 | ||
9633 | @item random_seed, seed | |
9634 | Set the seed for filling the initial random grid, must be an integer | |
9635 | included between 0 and UINT32_MAX. If not specified, or if explicitly | |
9636 | set to -1, the filter will try to use a good random seed on a best | |
9637 | effort basis. | |
9638 | ||
9639 | @item rule | |
9640 | Set the life rule. | |
9641 | ||
9642 | A rule can be specified with a code of the kind "S@var{NS}/B@var{NB}", | |
9643 | where @var{NS} and @var{NB} are sequences of numbers in the range 0-8, | |
9644 | @var{NS} specifies the number of alive neighbor cells which make a | |
9645 | live cell stay alive, and @var{NB} the number of alive neighbor cells | |
9646 | which make a dead cell to become alive (i.e. to "born"). | |
9647 | "s" and "b" can be used in place of "S" and "B", respectively. | |
9648 | ||
9649 | Alternatively a rule can be specified by an 18-bits integer. The 9 | |
9650 | high order bits are used to encode the next cell state if it is alive | |
9651 | for each number of neighbor alive cells, the low order bits specify | |
9652 | the rule for "borning" new cells. Higher order bits encode for an | |
9653 | higher number of neighbor cells. | |
9654 | For example the number 6153 = @code{(12<<9)+9} specifies a stay alive | |
9655 | rule of 12 and a born rule of 9, which corresponds to "S23/B03". | |
9656 | ||
9657 | Default value is "S23/B3", which is the original Conway's game of life | |
9658 | rule, and will keep a cell alive if it has 2 or 3 neighbor alive | |
9659 | cells, and will born a new cell if there are three alive cells around | |
9660 | a dead cell. | |
9661 | ||
9662 | @item size, s | |
9663 | Set the size of the output video. For the syntax of this option, check the | |
9664 | "Video size" section in the ffmpeg-utils manual. | |
9665 | ||
9666 | If @option{filename} is specified, the size is set by default to the | |
9667 | same size of the input file. If @option{size} is set, it must contain | |
9668 | the size specified in the input file, and the initial grid defined in | |
9669 | that file is centered in the larger resulting area. | |
9670 | ||
9671 | If a filename is not specified, the size value defaults to "320x240" | |
9672 | (used for a randomly generated initial grid). | |
9673 | ||
9674 | @item stitch | |
9675 | If set to 1, stitch the left and right grid edges together, and the | |
9676 | top and bottom edges also. Defaults to 1. | |
9677 | ||
9678 | @item mold | |
9679 | Set cell mold speed. If set, a dead cell will go from @option{death_color} to | |
9680 | @option{mold_color} with a step of @option{mold}. @option{mold} can have a | |
9681 | value from 0 to 255. | |
9682 | ||
9683 | @item life_color | |
9684 | Set the color of living (or new born) cells. | |
9685 | ||
9686 | @item death_color | |
9687 | Set the color of dead cells. If @option{mold} is set, this is the first color | |
9688 | used to represent a dead cell. | |
9689 | ||
9690 | @item mold_color | |
9691 | Set mold color, for definitely dead and moldy cells. | |
9692 | ||
9693 | For the syntax of these 3 color options, check the "Color" section in the | |
9694 | ffmpeg-utils manual. | |
9695 | @end table | |
9696 | ||
9697 | @subsection Examples | |
9698 | ||
9699 | @itemize | |
9700 | @item | |
9701 | Read a grid from @file{pattern}, and center it on a grid of size | |
9702 | 300x300 pixels: | |
9703 | @example | |
9704 | life=f=pattern:s=300x300 | |
9705 | @end example | |
9706 | ||
9707 | @item | |
9708 | Generate a random grid of size 200x200, with a fill ratio of 2/3: | |
9709 | @example | |
9710 | life=ratio=2/3:s=200x200 | |
9711 | @end example | |
9712 | ||
9713 | @item | |
9714 | Specify a custom rule for evolving a randomly generated grid: | |
9715 | @example | |
9716 | life=rule=S14/B34 | |
9717 | @end example | |
9718 | ||
9719 | @item | |
9720 | Full example with slow death effect (mold) using @command{ffplay}: | |
9721 | @example | |
9722 | ffplay -f lavfi life=s=300x200:mold=10:r=60:ratio=0.1:death_color=#C83232:life_color=#00ff00,scale=1200:800:flags=16 | |
9723 | @end example | |
9724 | @end itemize | |
9725 | ||
9726 | @anchor{color} | |
9727 | @anchor{haldclutsrc} | |
9728 | @anchor{nullsrc} | |
9729 | @anchor{rgbtestsrc} | |
9730 | @anchor{smptebars} | |
9731 | @anchor{smptehdbars} | |
9732 | @anchor{testsrc} | |
9733 | @section color, haldclutsrc, nullsrc, rgbtestsrc, smptebars, smptehdbars, testsrc | |
9734 | ||
9735 | The @code{color} source provides an uniformly colored input. | |
9736 | ||
9737 | The @code{haldclutsrc} source provides an identity Hald CLUT. See also | |
9738 | @ref{haldclut} filter. | |
9739 | ||
9740 | The @code{nullsrc} source returns unprocessed video frames. It is | |
9741 | mainly useful to be employed in analysis / debugging tools, or as the | |
9742 | source for filters which ignore the input data. | |
9743 | ||
9744 | The @code{rgbtestsrc} source generates an RGB test pattern useful for | |
9745 | detecting RGB vs BGR issues. You should see a red, green and blue | |
9746 | stripe from top to bottom. | |
9747 | ||
9748 | The @code{smptebars} source generates a color bars pattern, based on | |
9749 | the SMPTE Engineering Guideline EG 1-1990. | |
9750 | ||
9751 | The @code{smptehdbars} source generates a color bars pattern, based on | |
9752 | the SMPTE RP 219-2002. | |
9753 | ||
9754 | The @code{testsrc} source generates a test video pattern, showing a | |
9755 | color pattern, a scrolling gradient and a timestamp. This is mainly | |
9756 | intended for testing purposes. | |
9757 | ||
9758 | The sources accept the following parameters: | |
9759 | ||
9760 | @table @option | |
9761 | ||
9762 | @item color, c | |
9763 | Specify the color of the source, only available in the @code{color} | |
9764 | source. For the syntax of this option, check the "Color" section in the | |
9765 | ffmpeg-utils manual. | |
9766 | ||
9767 | @item level | |
9768 | Specify the level of the Hald CLUT, only available in the @code{haldclutsrc} | |
9769 | source. A level of @code{N} generates a picture of @code{N*N*N} by @code{N*N*N} | |
9770 | pixels to be used as identity matrix for 3D lookup tables. Each component is | |
9771 | coded on a @code{1/(N*N)} scale. | |
9772 | ||
9773 | @item size, s | |
9774 | Specify the size of the sourced video. For the syntax of this option, check the | |
9775 | "Video size" section in the ffmpeg-utils manual. The default value is | |
9776 | "320x240". | |
9777 | ||
9778 | This option is not available with the @code{haldclutsrc} filter. | |
9779 | ||
9780 | @item rate, r | |
9781 | Specify the frame rate of the sourced video, as the number of frames | |
9782 | generated per second. It has to be a string in the format | |
9783 | @var{frame_rate_num}/@var{frame_rate_den}, an integer number, a floating point | |
9784 | number or a valid video frame rate abbreviation. The default value is | |
9785 | "25". | |
9786 | ||
9787 | @item sar | |
9788 | Set the sample aspect ratio of the sourced video. | |
9789 | ||
9790 | @item duration, d | |
9791 | Set the duration of the sourced video. See | |
9792 | @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils} | |
9793 | for the accepted syntax. | |
9794 | ||
9795 | If not specified, or the expressed duration is negative, the video is | |
9796 | supposed to be generated forever. | |
9797 | ||
9798 | @item decimals, n | |
9799 | Set the number of decimals to show in the timestamp, only available in the | |
9800 | @code{testsrc} source. | |
9801 | ||
9802 | The displayed timestamp value will correspond to the original | |
9803 | timestamp value multiplied by the power of 10 of the specified | |
9804 | value. Default value is 0. | |
9805 | @end table | |
9806 | ||
9807 | For example the following: | |
9808 | @example | |
9809 | testsrc=duration=5.3:size=qcif:rate=10 | |
9810 | @end example | |
9811 | ||
9812 | will generate a video with a duration of 5.3 seconds, with size | |
9813 | 176x144 and a frame rate of 10 frames per second. | |
9814 | ||
9815 | The following graph description will generate a red source | |
9816 | with an opacity of 0.2, with size "qcif" and a frame rate of 10 | |
9817 | frames per second. | |
9818 | @example | |
9819 | color=c=red@@0.2:s=qcif:r=10 | |
9820 | @end example | |
9821 | ||
9822 | If the input content is to be ignored, @code{nullsrc} can be used. The | |
9823 | following command generates noise in the luminance plane by employing | |
9824 | the @code{geq} filter: | |
9825 | @example | |
9826 | nullsrc=s=256x256, geq=random(1)*255:128:128 | |
9827 | @end example | |
9828 | ||
9829 | @subsection Commands | |
9830 | ||
9831 | The @code{color} source supports the following commands: | |
9832 | ||
9833 | @table @option | |
9834 | @item c, color | |
9835 | Set the color of the created image. Accepts the same syntax of the | |
9836 | corresponding @option{color} option. | |
9837 | @end table | |
9838 | ||
9839 | @c man end VIDEO SOURCES | |
9840 | ||
9841 | @chapter Video Sinks | |
9842 | @c man begin VIDEO SINKS | |
9843 | ||
9844 | Below is a description of the currently available video sinks. | |
9845 | ||
9846 | @section buffersink | |
9847 | ||
9848 | Buffer video frames, and make them available to the end of the filter | |
9849 | graph. | |
9850 | ||
9851 | This sink is mainly intended for programmatic use, in particular | |
9852 | through the interface defined in @file{libavfilter/buffersink.h} | |
9853 | or the options system. | |
9854 | ||
9855 | It accepts a pointer to an AVBufferSinkContext structure, which | |
9856 | defines the incoming buffers' formats, to be passed as the opaque | |
9857 | parameter to @code{avfilter_init_filter} for initialization. | |
9858 | ||
9859 | @section nullsink | |
9860 | ||
9861 | Null video sink: do absolutely nothing with the input video. It is | |
9862 | mainly useful as a template and for use in analysis / debugging | |
9863 | tools. | |
9864 | ||
9865 | @c man end VIDEO SINKS | |
9866 | ||
9867 | @chapter Multimedia Filters | |
9868 | @c man begin MULTIMEDIA FILTERS | |
9869 | ||
9870 | Below is a description of the currently available multimedia filters. | |
9871 | ||
9872 | @section avectorscope | |
9873 | ||
9874 | Convert input audio to a video output, representing the audio vector | |
9875 | scope. | |
9876 | ||
9877 | The filter is used to measure the difference between channels of stereo | |
9878 | audio stream. A monoaural signal, consisting of identical left and right | |
9879 | signal, results in straight vertical line. Any stereo separation is visible | |
9880 | as a deviation from this line, creating a Lissajous figure. | |
9881 | If the straight (or deviation from it) but horizontal line appears this | |
9882 | indicates that the left and right channels are out of phase. | |
9883 | ||
9884 | The filter accepts the following options: | |
9885 | ||
9886 | @table @option | |
9887 | @item mode, m | |
9888 | Set the vectorscope mode. | |
9889 | ||
9890 | Available values are: | |
9891 | @table @samp | |
9892 | @item lissajous | |
9893 | Lissajous rotated by 45 degrees. | |
9894 | ||
9895 | @item lissajous_xy | |
9896 | Same as above but not rotated. | |
9897 | @end table | |
9898 | ||
9899 | Default value is @samp{lissajous}. | |
9900 | ||
9901 | @item size, s | |
9902 | Set the video size for the output. For the syntax of this option, check the "Video size" | |
9903 | section in the ffmpeg-utils manual. Default value is @code{400x400}. | |
9904 | ||
9905 | @item rate, r | |
9906 | Set the output frame rate. Default value is @code{25}. | |
9907 | ||
9908 | @item rc | |
9909 | @item gc | |
9910 | @item bc | |
9911 | Specify the red, green and blue contrast. Default values are @code{40}, @code{160} and @code{80}. | |
9912 | Allowed range is @code{[0, 255]}. | |
9913 | ||
9914 | @item rf | |
9915 | @item gf | |
9916 | @item bf | |
9917 | Specify the red, green and blue fade. Default values are @code{15}, @code{10} and @code{5}. | |
9918 | Allowed range is @code{[0, 255]}. | |
9919 | ||
9920 | @item zoom | |
9921 | Set the zoom factor. Default value is @code{1}. Allowed range is @code{[1, 10]}. | |
9922 | @end table | |
9923 | ||
9924 | @subsection Examples | |
9925 | ||
9926 | @itemize | |
9927 | @item | |
9928 | Complete example using @command{ffplay}: | |
9929 | @example | |
9930 | ffplay -f lavfi 'amovie=input.mp3, asplit [a][out1]; | |
9931 | [a] avectorscope=zoom=1.3:rc=2:gc=200:bc=10:rf=1:gf=8:bf=7 [out0]' | |
9932 | @end example | |
9933 | @end itemize | |
9934 | ||
9935 | @section concat | |
9936 | ||
9937 | Concatenate audio and video streams, joining them together one after the | |
9938 | other. | |
9939 | ||
9940 | The filter works on segments of synchronized video and audio streams. All | |
9941 | segments must have the same number of streams of each type, and that will | |
9942 | also be the number of streams at output. | |
9943 | ||
9944 | The filter accepts the following options: | |
9945 | ||
9946 | @table @option | |
9947 | ||
9948 | @item n | |
9949 | Set the number of segments. Default is 2. | |
9950 | ||
9951 | @item v | |
9952 | Set the number of output video streams, that is also the number of video | |
9953 | streams in each segment. Default is 1. | |
9954 | ||
9955 | @item a | |
9956 | Set the number of output audio streams, that is also the number of audio | |
9957 | streams in each segment. Default is 0. | |
9958 | ||
9959 | @item unsafe | |
9960 | Activate unsafe mode: do not fail if segments have a different format. | |
9961 | ||
9962 | @end table | |
9963 | ||
9964 | The filter has @var{v}+@var{a} outputs: first @var{v} video outputs, then | |
9965 | @var{a} audio outputs. | |
9966 | ||
9967 | There are @var{n}x(@var{v}+@var{a}) inputs: first the inputs for the first | |
9968 | segment, in the same order as the outputs, then the inputs for the second | |
9969 | segment, etc. | |
9970 | ||
9971 | Related streams do not always have exactly the same duration, for various | |
9972 | reasons including codec frame size or sloppy authoring. For that reason, | |
9973 | related synchronized streams (e.g. a video and its audio track) should be | |
9974 | concatenated at once. The concat filter will use the duration of the longest | |
9975 | stream in each segment (except the last one), and if necessary pad shorter | |
9976 | audio streams with silence. | |
9977 | ||
9978 | For this filter to work correctly, all segments must start at timestamp 0. | |
9979 | ||
9980 | All corresponding streams must have the same parameters in all segments; the | |
9981 | filtering system will automatically select a common pixel format for video | |
9982 | streams, and a common sample format, sample rate and channel layout for | |
9983 | audio streams, but other settings, such as resolution, must be converted | |
9984 | explicitly by the user. | |
9985 | ||
9986 | Different frame rates are acceptable but will result in variable frame rate | |
9987 | at output; be sure to configure the output file to handle it. | |
9988 | ||
9989 | @subsection Examples | |
9990 | ||
9991 | @itemize | |
9992 | @item | |
9993 | Concatenate an opening, an episode and an ending, all in bilingual version | |
9994 | (video in stream 0, audio in streams 1 and 2): | |
9995 | @example | |
9996 | ffmpeg -i opening.mkv -i episode.mkv -i ending.mkv -filter_complex \ | |
9997 | '[0:0] [0:1] [0:2] [1:0] [1:1] [1:2] [2:0] [2:1] [2:2] | |
9998 | concat=n=3:v=1:a=2 [v] [a1] [a2]' \ | |
9999 | -map '[v]' -map '[a1]' -map '[a2]' output.mkv | |
10000 | @end example | |
10001 | ||
10002 | @item | |
10003 | Concatenate two parts, handling audio and video separately, using the | |
10004 | (a)movie sources, and adjusting the resolution: | |
10005 | @example | |
10006 | movie=part1.mp4, scale=512:288 [v1] ; amovie=part1.mp4 [a1] ; | |
10007 | movie=part2.mp4, scale=512:288 [v2] ; amovie=part2.mp4 [a2] ; | |
10008 | [v1] [v2] concat [outv] ; [a1] [a2] concat=v=0:a=1 [outa] | |
10009 | @end example | |
10010 | Note that a desync will happen at the stitch if the audio and video streams | |
10011 | do not have exactly the same duration in the first file. | |
10012 | ||
10013 | @end itemize | |
10014 | ||
10015 | @section ebur128 | |
10016 | ||
10017 | EBU R128 scanner filter. This filter takes an audio stream as input and outputs | |
10018 | it unchanged. By default, it logs a message at a frequency of 10Hz with the | |
10019 | Momentary loudness (identified by @code{M}), Short-term loudness (@code{S}), | |
10020 | Integrated loudness (@code{I}) and Loudness Range (@code{LRA}). | |
10021 | ||
10022 | The filter also has a video output (see the @var{video} option) with a real | |
10023 | time graph to observe the loudness evolution. The graphic contains the logged | |
10024 | message mentioned above, so it is not printed anymore when this option is set, | |
10025 | unless the verbose logging is set. The main graphing area contains the | |
10026 | short-term loudness (3 seconds of analysis), and the gauge on the right is for | |
10027 | the momentary loudness (400 milliseconds). | |
10028 | ||
10029 | More information about the Loudness Recommendation EBU R128 on | |
10030 | @url{http://tech.ebu.ch/loudness}. | |
10031 | ||
10032 | The filter accepts the following options: | |
10033 | ||
10034 | @table @option | |
10035 | ||
10036 | @item video | |
10037 | Activate the video output. The audio stream is passed unchanged whether this | |
10038 | option is set or no. The video stream will be the first output stream if | |
10039 | activated. Default is @code{0}. | |
10040 | ||
10041 | @item size | |
10042 | Set the video size. This option is for video only. For the syntax of this | |
10043 | option, check the "Video size" section in the ffmpeg-utils manual. Default | |
10044 | and minimum resolution is @code{640x480}. | |
10045 | ||
10046 | @item meter | |
10047 | Set the EBU scale meter. Default is @code{9}. Common values are @code{9} and | |
10048 | @code{18}, respectively for EBU scale meter +9 and EBU scale meter +18. Any | |
10049 | other integer value between this range is allowed. | |
10050 | ||
10051 | @item metadata | |
10052 | Set metadata injection. If set to @code{1}, the audio input will be segmented | |
10053 | into 100ms output frames, each of them containing various loudness information | |
10054 | in metadata. All the metadata keys are prefixed with @code{lavfi.r128.}. | |
10055 | ||
10056 | Default is @code{0}. | |
10057 | ||
10058 | @item framelog | |
10059 | Force the frame logging level. | |
10060 | ||
10061 | Available values are: | |
10062 | @table @samp | |
10063 | @item info | |
10064 | information logging level | |
10065 | @item verbose | |
10066 | verbose logging level | |
10067 | @end table | |
10068 | ||
10069 | By default, the logging level is set to @var{info}. If the @option{video} or | |
10070 | the @option{metadata} options are set, it switches to @var{verbose}. | |
10071 | ||
10072 | @item peak | |
10073 | Set peak mode(s). | |
10074 | ||
10075 | Available modes can be cumulated (the option is a @code{flag} type). Possible | |
10076 | values are: | |
10077 | @table @samp | |
10078 | @item none | |
10079 | Disable any peak mode (default). | |
10080 | @item sample | |
10081 | Enable sample-peak mode. | |
10082 | ||
10083 | Simple peak mode looking for the higher sample value. It logs a message | |
10084 | for sample-peak (identified by @code{SPK}). | |
10085 | @item true | |
10086 | Enable true-peak mode. | |
10087 | ||
10088 | If enabled, the peak lookup is done on an over-sampled version of the input | |
10089 | stream for better peak accuracy. It logs a message for true-peak. | |
10090 | (identified by @code{TPK}) and true-peak per frame (identified by @code{FTPK}). | |
10091 | This mode requires a build with @code{libswresample}. | |
10092 | @end table | |
10093 | ||
10094 | @end table | |
10095 | ||
10096 | @subsection Examples | |
10097 | ||
10098 | @itemize | |
10099 | @item | |
10100 | Real-time graph using @command{ffplay}, with a EBU scale meter +18: | |
10101 | @example | |
10102 | ffplay -f lavfi -i "amovie=input.mp3,ebur128=video=1:meter=18 [out0][out1]" | |
10103 | @end example | |
10104 | ||
10105 | @item | |
10106 | Run an analysis with @command{ffmpeg}: | |
10107 | @example | |
10108 | ffmpeg -nostats -i input.mp3 -filter_complex ebur128 -f null - | |
10109 | @end example | |
10110 | @end itemize | |
10111 | ||
10112 | @section interleave, ainterleave | |
10113 | ||
10114 | Temporally interleave frames from several inputs. | |
10115 | ||
10116 | @code{interleave} works with video inputs, @code{ainterleave} with audio. | |
10117 | ||
10118 | These filters read frames from several inputs and send the oldest | |
10119 | queued frame to the output. | |
10120 | ||
10121 | Input streams must have a well defined, monotonically increasing frame | |
10122 | timestamp values. | |
10123 | ||
10124 | In order to submit one frame to output, these filters need to enqueue | |
10125 | at least one frame for each input, so they cannot work in case one | |
10126 | input is not yet terminated and will not receive incoming frames. | |
10127 | ||
10128 | For example consider the case when one input is a @code{select} filter | |
10129 | which always drop input frames. The @code{interleave} filter will keep | |
10130 | reading from that input, but it will never be able to send new frames | |
10131 | to output until the input will send an end-of-stream signal. | |
10132 | ||
10133 | Also, depending on inputs synchronization, the filters will drop | |
10134 | frames in case one input receives more frames than the other ones, and | |
10135 | the queue is already filled. | |
10136 | ||
10137 | These filters accept the following options: | |
10138 | ||
10139 | @table @option | |
10140 | @item nb_inputs, n | |
10141 | Set the number of different inputs, it is 2 by default. | |
10142 | @end table | |
10143 | ||
10144 | @subsection Examples | |
10145 | ||
10146 | @itemize | |
10147 | @item | |
10148 | Interleave frames belonging to different streams using @command{ffmpeg}: | |
10149 | @example | |
10150 | ffmpeg -i bambi.avi -i pr0n.mkv -filter_complex "[0:v][1:v] interleave" out.avi | |
10151 | @end example | |
10152 | ||
10153 | @item | |
10154 | Add flickering blur effect: | |
10155 | @example | |
10156 | select='if(gt(random(0), 0.2), 1, 2)':n=2 [tmp], boxblur=2:2, [tmp] interleave | |
10157 | @end example | |
10158 | @end itemize | |
10159 | ||
10160 | @section perms, aperms | |
10161 | ||
10162 | Set read/write permissions for the output frames. | |
10163 | ||
10164 | These filters are mainly aimed at developers to test direct path in the | |
10165 | following filter in the filtergraph. | |
10166 | ||
10167 | The filters accept the following options: | |
10168 | ||
10169 | @table @option | |
10170 | @item mode | |
10171 | Select the permissions mode. | |
10172 | ||
10173 | It accepts the following values: | |
10174 | @table @samp | |
10175 | @item none | |
10176 | Do nothing. This is the default. | |
10177 | @item ro | |
10178 | Set all the output frames read-only. | |
10179 | @item rw | |
10180 | Set all the output frames directly writable. | |
10181 | @item toggle | |
10182 | Make the frame read-only if writable, and writable if read-only. | |
10183 | @item random | |
10184 | Set each output frame read-only or writable randomly. | |
10185 | @end table | |
10186 | ||
10187 | @item seed | |
10188 | Set the seed for the @var{random} mode, must be an integer included between | |
10189 | @code{0} and @code{UINT32_MAX}. If not specified, or if explicitly set to | |
10190 | @code{-1}, the filter will try to use a good random seed on a best effort | |
10191 | basis. | |
10192 | @end table | |
10193 | ||
10194 | Note: in case of auto-inserted filter between the permission filter and the | |
10195 | following one, the permission might not be received as expected in that | |
10196 | following filter. Inserting a @ref{format} or @ref{aformat} filter before the | |
10197 | perms/aperms filter can avoid this problem. | |
10198 | ||
10199 | @section select, aselect | |
10200 | ||
10201 | Select frames to pass in output. | |
10202 | ||
10203 | This filter accepts the following options: | |
10204 | ||
10205 | @table @option | |
10206 | ||
10207 | @item expr, e | |
10208 | Set expression, which is evaluated for each input frame. | |
10209 | ||
10210 | If the expression is evaluated to zero, the frame is discarded. | |
10211 | ||
10212 | If the evaluation result is negative or NaN, the frame is sent to the | |
10213 | first output; otherwise it is sent to the output with index | |
10214 | @code{ceil(val)-1}, assuming that the input index starts from 0. | |
10215 | ||
10216 | For example a value of @code{1.2} corresponds to the output with index | |
10217 | @code{ceil(1.2)-1 = 2-1 = 1}, that is the second output. | |
10218 | ||
10219 | @item outputs, n | |
10220 | Set the number of outputs. The output to which to send the selected | |
10221 | frame is based on the result of the evaluation. Default value is 1. | |
10222 | @end table | |
10223 | ||
10224 | The expression can contain the following constants: | |
10225 | ||
10226 | @table @option | |
10227 | @item n | |
10228 | The (sequential) number of the filtered frame, starting from 0. | |
10229 | ||
10230 | @item selected_n | |
10231 | The (sequential) number of the selected frame, starting from 0. | |
10232 | ||
10233 | @item prev_selected_n | |
10234 | The sequential number of the last selected frame. It's NAN if undefined. | |
10235 | ||
10236 | @item TB | |
10237 | The timebase of the input timestamps. | |
10238 | ||
10239 | @item pts | |
10240 | The PTS (Presentation TimeStamp) of the filtered video frame, | |
10241 | expressed in @var{TB} units. It's NAN if undefined. | |
10242 | ||
10243 | @item t | |
10244 | The PTS of the filtered video frame, | |
10245 | expressed in seconds. It's NAN if undefined. | |
10246 | ||
10247 | @item prev_pts | |
10248 | The PTS of the previously filtered video frame. It's NAN if undefined. | |
10249 | ||
10250 | @item prev_selected_pts | |
10251 | The PTS of the last previously filtered video frame. It's NAN if undefined. | |
10252 | ||
10253 | @item prev_selected_t | |
10254 | The PTS of the last previously selected video frame. It's NAN if undefined. | |
10255 | ||
10256 | @item start_pts | |
10257 | The PTS of the first video frame in the video. It's NAN if undefined. | |
10258 | ||
10259 | @item start_t | |
10260 | The time of the first video frame in the video. It's NAN if undefined. | |
10261 | ||
10262 | @item pict_type @emph{(video only)} | |
10263 | The type of the filtered frame. It can assume one of the following | |
10264 | values: | |
10265 | @table @option | |
10266 | @item I | |
10267 | @item P | |
10268 | @item B | |
10269 | @item S | |
10270 | @item SI | |
10271 | @item SP | |
10272 | @item BI | |
10273 | @end table | |
10274 | ||
10275 | @item interlace_type @emph{(video only)} | |
10276 | The frame interlace type. It can assume one of the following values: | |
10277 | @table @option | |
10278 | @item PROGRESSIVE | |
10279 | The frame is progressive (not interlaced). | |
10280 | @item TOPFIRST | |
10281 | The frame is top-field-first. | |
10282 | @item BOTTOMFIRST | |
10283 | The frame is bottom-field-first. | |
10284 | @end table | |
10285 | ||
10286 | @item consumed_sample_n @emph{(audio only)} | |
10287 | the number of selected samples before the current frame | |
10288 | ||
10289 | @item samples_n @emph{(audio only)} | |
10290 | the number of samples in the current frame | |
10291 | ||
10292 | @item sample_rate @emph{(audio only)} | |
10293 | the input sample rate | |
10294 | ||
10295 | @item key | |
10296 | This is 1 if the filtered frame is a key-frame, 0 otherwise. | |
10297 | ||
10298 | @item pos | |
10299 | the position in the file of the filtered frame, -1 if the information | |
10300 | is not available (e.g. for synthetic video) | |
10301 | ||
10302 | @item scene @emph{(video only)} | |
10303 | value between 0 and 1 to indicate a new scene; a low value reflects a low | |
10304 | probability for the current frame to introduce a new scene, while a higher | |
10305 | value means the current frame is more likely to be one (see the example below) | |
10306 | ||
10307 | @end table | |
10308 | ||
10309 | The default value of the select expression is "1". | |
10310 | ||
10311 | @subsection Examples | |
10312 | ||
10313 | @itemize | |
10314 | @item | |
10315 | Select all frames in input: | |
10316 | @example | |
10317 | select | |
10318 | @end example | |
10319 | ||
10320 | The example above is the same as: | |
10321 | @example | |
10322 | select=1 | |
10323 | @end example | |
10324 | ||
10325 | @item | |
10326 | Skip all frames: | |
10327 | @example | |
10328 | select=0 | |
10329 | @end example | |
10330 | ||
10331 | @item | |
10332 | Select only I-frames: | |
10333 | @example | |
10334 | select='eq(pict_type\,I)' | |
10335 | @end example | |
10336 | ||
10337 | @item | |
10338 | Select one frame every 100: | |
10339 | @example | |
10340 | select='not(mod(n\,100))' | |
10341 | @end example | |
10342 | ||
10343 | @item | |
10344 | Select only frames contained in the 10-20 time interval: | |
10345 | @example | |
10346 | select=between(t\,10\,20) | |
10347 | @end example | |
10348 | ||
10349 | @item | |
10350 | Select only I frames contained in the 10-20 time interval: | |
10351 | @example | |
10352 | select=between(t\,10\,20)*eq(pict_type\,I) | |
10353 | @end example | |
10354 | ||
10355 | @item | |
10356 | Select frames with a minimum distance of 10 seconds: | |
10357 | @example | |
10358 | select='isnan(prev_selected_t)+gte(t-prev_selected_t\,10)' | |
10359 | @end example | |
10360 | ||
10361 | @item | |
10362 | Use aselect to select only audio frames with samples number > 100: | |
10363 | @example | |
10364 | aselect='gt(samples_n\,100)' | |
10365 | @end example | |
10366 | ||
10367 | @item | |
10368 | Create a mosaic of the first scenes: | |
10369 | @example | |
10370 | ffmpeg -i video.avi -vf select='gt(scene\,0.4)',scale=160:120,tile -frames:v 1 preview.png | |
10371 | @end example | |
10372 | ||
10373 | Comparing @var{scene} against a value between 0.3 and 0.5 is generally a sane | |
10374 | choice. | |
10375 | ||
10376 | @item | |
10377 | Send even and odd frames to separate outputs, and compose them: | |
10378 | @example | |
10379 | select=n=2:e='mod(n, 2)+1' [odd][even]; [odd] pad=h=2*ih [tmp]; [tmp][even] overlay=y=h | |
10380 | @end example | |
10381 | @end itemize | |
10382 | ||
10383 | @section sendcmd, asendcmd | |
10384 | ||
10385 | Send commands to filters in the filtergraph. | |
10386 | ||
10387 | These filters read commands to be sent to other filters in the | |
10388 | filtergraph. | |
10389 | ||
10390 | @code{sendcmd} must be inserted between two video filters, | |
10391 | @code{asendcmd} must be inserted between two audio filters, but apart | |
10392 | from that they act the same way. | |
10393 | ||
10394 | The specification of commands can be provided in the filter arguments | |
10395 | with the @var{commands} option, or in a file specified by the | |
10396 | @var{filename} option. | |
10397 | ||
10398 | These filters accept the following options: | |
10399 | @table @option | |
10400 | @item commands, c | |
10401 | Set the commands to be read and sent to the other filters. | |
10402 | @item filename, f | |
10403 | Set the filename of the commands to be read and sent to the other | |
10404 | filters. | |
10405 | @end table | |
10406 | ||
10407 | @subsection Commands syntax | |
10408 | ||
10409 | A commands description consists of a sequence of interval | |
10410 | specifications, comprising a list of commands to be executed when a | |
10411 | particular event related to that interval occurs. The occurring event | |
10412 | is typically the current frame time entering or leaving a given time | |
10413 | interval. | |
10414 | ||
10415 | An interval is specified by the following syntax: | |
10416 | @example | |
10417 | @var{START}[-@var{END}] @var{COMMANDS}; | |
10418 | @end example | |
10419 | ||
10420 | The time interval is specified by the @var{START} and @var{END} times. | |
10421 | @var{END} is optional and defaults to the maximum time. | |
10422 | ||
10423 | The current frame time is considered within the specified interval if | |
10424 | it is included in the interval [@var{START}, @var{END}), that is when | |
10425 | the time is greater or equal to @var{START} and is lesser than | |
10426 | @var{END}. | |
10427 | ||
10428 | @var{COMMANDS} consists of a sequence of one or more command | |
10429 | specifications, separated by ",", relating to that interval. The | |
10430 | syntax of a command specification is given by: | |
10431 | @example | |
10432 | [@var{FLAGS}] @var{TARGET} @var{COMMAND} @var{ARG} | |
10433 | @end example | |
10434 | ||
10435 | @var{FLAGS} is optional and specifies the type of events relating to | |
10436 | the time interval which enable sending the specified command, and must | |
10437 | be a non-null sequence of identifier flags separated by "+" or "|" and | |
10438 | enclosed between "[" and "]". | |
10439 | ||
10440 | The following flags are recognized: | |
10441 | @table @option | |
10442 | @item enter | |
10443 | The command is sent when the current frame timestamp enters the | |
10444 | specified interval. In other words, the command is sent when the | |
10445 | previous frame timestamp was not in the given interval, and the | |
10446 | current is. | |
10447 | ||
10448 | @item leave | |
10449 | The command is sent when the current frame timestamp leaves the | |
10450 | specified interval. In other words, the command is sent when the | |
10451 | previous frame timestamp was in the given interval, and the | |
10452 | current is not. | |
10453 | @end table | |
10454 | ||
10455 | If @var{FLAGS} is not specified, a default value of @code{[enter]} is | |
10456 | assumed. | |
10457 | ||
10458 | @var{TARGET} specifies the target of the command, usually the name of | |
10459 | the filter class or a specific filter instance name. | |
10460 | ||
10461 | @var{COMMAND} specifies the name of the command for the target filter. | |
10462 | ||
10463 | @var{ARG} is optional and specifies the optional list of argument for | |
10464 | the given @var{COMMAND}. | |
10465 | ||
10466 | Between one interval specification and another, whitespaces, or | |
10467 | sequences of characters starting with @code{#} until the end of line, | |
10468 | are ignored and can be used to annotate comments. | |
10469 | ||
10470 | A simplified BNF description of the commands specification syntax | |
10471 | follows: | |
10472 | @example | |
10473 | @var{COMMAND_FLAG} ::= "enter" | "leave" | |
10474 | @var{COMMAND_FLAGS} ::= @var{COMMAND_FLAG} [(+|"|")@var{COMMAND_FLAG}] | |
10475 | @var{COMMAND} ::= ["[" @var{COMMAND_FLAGS} "]"] @var{TARGET} @var{COMMAND} [@var{ARG}] | |
10476 | @var{COMMANDS} ::= @var{COMMAND} [,@var{COMMANDS}] | |
10477 | @var{INTERVAL} ::= @var{START}[-@var{END}] @var{COMMANDS} | |
10478 | @var{INTERVALS} ::= @var{INTERVAL}[;@var{INTERVALS}] | |
10479 | @end example | |
10480 | ||
10481 | @subsection Examples | |
10482 | ||
10483 | @itemize | |
10484 | @item | |
10485 | Specify audio tempo change at second 4: | |
10486 | @example | |
10487 | asendcmd=c='4.0 atempo tempo 1.5',atempo | |
10488 | @end example | |
10489 | ||
10490 | @item | |
10491 | Specify a list of drawtext and hue commands in a file. | |
10492 | @example | |
10493 | # show text in the interval 5-10 | |
10494 | 5.0-10.0 [enter] drawtext reinit 'fontfile=FreeSerif.ttf:text=hello world', | |
10495 | [leave] drawtext reinit 'fontfile=FreeSerif.ttf:text='; | |
10496 | ||
10497 | # desaturate the image in the interval 15-20 | |
10498 | 15.0-20.0 [enter] hue s 0, | |
10499 | [enter] drawtext reinit 'fontfile=FreeSerif.ttf:text=nocolor', | |
10500 | [leave] hue s 1, | |
10501 | [leave] drawtext reinit 'fontfile=FreeSerif.ttf:text=color'; | |
10502 | ||
10503 | # apply an exponential saturation fade-out effect, starting from time 25 | |
10504 | 25 [enter] hue s exp(25-t) | |
10505 | @end example | |
10506 | ||
10507 | A filtergraph allowing to read and process the above command list | |
10508 | stored in a file @file{test.cmd}, can be specified with: | |
10509 | @example | |
10510 | sendcmd=f=test.cmd,drawtext=fontfile=FreeSerif.ttf:text='',hue | |
10511 | @end example | |
10512 | @end itemize | |
10513 | ||
10514 | @anchor{setpts} | |
10515 | @section setpts, asetpts | |
10516 | ||
10517 | Change the PTS (presentation timestamp) of the input frames. | |
10518 | ||
10519 | @code{setpts} works on video frames, @code{asetpts} on audio frames. | |
10520 | ||
10521 | This filter accepts the following options: | |
10522 | ||
10523 | @table @option | |
10524 | ||
10525 | @item expr | |
10526 | The expression which is evaluated for each frame to construct its timestamp. | |
10527 | ||
10528 | @end table | |
10529 | ||
10530 | The expression is evaluated through the eval API and can contain the following | |
10531 | constants: | |
10532 | ||
10533 | @table @option | |
10534 | @item FRAME_RATE | |
10535 | frame rate, only defined for constant frame-rate video | |
10536 | ||
10537 | @item PTS | |
10538 | The presentation timestamp in input | |
10539 | ||
10540 | @item N | |
10541 | The count of the input frame for video or the number of consumed samples, | |
10542 | not including the current frame for audio, starting from 0. | |
10543 | ||
10544 | @item NB_CONSUMED_SAMPLES | |
10545 | The number of consumed samples, not including the current frame (only | |
10546 | audio) | |
10547 | ||
10548 | @item NB_SAMPLES, S | |
10549 | The number of samples in the current frame (only audio) | |
10550 | ||
10551 | @item SAMPLE_RATE, SR | |
10552 | The audio sample rate. | |
10553 | ||
10554 | @item STARTPTS | |
10555 | The PTS of the first frame. | |
10556 | ||
10557 | @item STARTT | |
10558 | the time in seconds of the first frame | |
10559 | ||
10560 | @item INTERLACED | |
10561 | State whether the current frame is interlaced. | |
10562 | ||
10563 | @item T | |
10564 | the time in seconds of the current frame | |
10565 | ||
10566 | @item POS | |
10567 | original position in the file of the frame, or undefined if undefined | |
10568 | for the current frame | |
10569 | ||
10570 | @item PREV_INPTS | |
10571 | The previous input PTS. | |
10572 | ||
10573 | @item PREV_INT | |
10574 | previous input time in seconds | |
10575 | ||
10576 | @item PREV_OUTPTS | |
10577 | The previous output PTS. | |
10578 | ||
10579 | @item PREV_OUTT | |
10580 | previous output time in seconds | |
10581 | ||
10582 | @item RTCTIME | |
10583 | The wallclock (RTC) time in microseconds.. This is deprecated, use time(0) | |
10584 | instead. | |
10585 | ||
10586 | @item RTCSTART | |
10587 | The wallclock (RTC) time at the start of the movie in microseconds. | |
10588 | ||
10589 | @item TB | |
10590 | The timebase of the input timestamps. | |
10591 | ||
10592 | @end table | |
10593 | ||
10594 | @subsection Examples | |
10595 | ||
10596 | @itemize | |
10597 | @item | |
10598 | Start counting PTS from zero | |
10599 | @example | |
10600 | setpts=PTS-STARTPTS | |
10601 | @end example | |
10602 | ||
10603 | @item | |
10604 | Apply fast motion effect: | |
10605 | @example | |
10606 | setpts=0.5*PTS | |
10607 | @end example | |
10608 | ||
10609 | @item | |
10610 | Apply slow motion effect: | |
10611 | @example | |
10612 | setpts=2.0*PTS | |
10613 | @end example | |
10614 | ||
10615 | @item | |
10616 | Set fixed rate of 25 frames per second: | |
10617 | @example | |
10618 | setpts=N/(25*TB) | |
10619 | @end example | |
10620 | ||
10621 | @item | |
10622 | Set fixed rate 25 fps with some jitter: | |
10623 | @example | |
10624 | setpts='1/(25*TB) * (N + 0.05 * sin(N*2*PI/25))' | |
10625 | @end example | |
10626 | ||
10627 | @item | |
10628 | Apply an offset of 10 seconds to the input PTS: | |
10629 | @example | |
10630 | setpts=PTS+10/TB | |
10631 | @end example | |
10632 | ||
10633 | @item | |
10634 | Generate timestamps from a "live source" and rebase onto the current timebase: | |
10635 | @example | |
10636 | setpts='(RTCTIME - RTCSTART) / (TB * 1000000)' | |
10637 | @end example | |
10638 | ||
10639 | @item | |
10640 | Generate timestamps by counting samples: | |
10641 | @example | |
10642 | asetpts=N/SR/TB | |
10643 | @end example | |
10644 | ||
10645 | @end itemize | |
10646 | ||
10647 | @section settb, asettb | |
10648 | ||
10649 | Set the timebase to use for the output frames timestamps. | |
10650 | It is mainly useful for testing timebase configuration. | |
10651 | ||
10652 | It accepts the following parameters: | |
10653 | ||
10654 | @table @option | |
10655 | ||
10656 | @item expr, tb | |
10657 | The expression which is evaluated into the output timebase. | |
10658 | ||
10659 | @end table | |
10660 | ||
10661 | The value for @option{tb} is an arithmetic expression representing a | |
10662 | rational. The expression can contain the constants "AVTB" (the default | |
10663 | timebase), "intb" (the input timebase) and "sr" (the sample rate, | |
10664 | audio only). Default value is "intb". | |
10665 | ||
10666 | @subsection Examples | |
10667 | ||
10668 | @itemize | |
10669 | @item | |
10670 | Set the timebase to 1/25: | |
10671 | @example | |
10672 | settb=expr=1/25 | |
10673 | @end example | |
10674 | ||
10675 | @item | |
10676 | Set the timebase to 1/10: | |
10677 | @example | |
10678 | settb=expr=0.1 | |
10679 | @end example | |
10680 | ||
10681 | @item | |
10682 | Set the timebase to 1001/1000: | |
10683 | @example | |
10684 | settb=1+0.001 | |
10685 | @end example | |
10686 | ||
10687 | @item | |
10688 | Set the timebase to 2*intb: | |
10689 | @example | |
10690 | settb=2*intb | |
10691 | @end example | |
10692 | ||
10693 | @item | |
10694 | Set the default timebase value: | |
10695 | @example | |
10696 | settb=AVTB | |
10697 | @end example | |
10698 | @end itemize | |
10699 | ||
10700 | @section showcqt | |
10701 | Convert input audio to a video output representing | |
10702 | frequency spectrum logarithmically (using constant Q transform with | |
10703 | Brown-Puckette algorithm), with musical tone scale, from E0 to D#10 (10 octaves). | |
10704 | ||
10705 | The filter accepts the following options: | |
10706 | ||
10707 | @table @option | |
10708 | @item volume | |
10709 | Specify transform volume (multiplier) expression. The expression can contain | |
10710 | variables: | |
10711 | @table @option | |
10712 | @item frequency, freq, f | |
10713 | the frequency where transform is evaluated | |
10714 | @item timeclamp, tc | |
10715 | value of timeclamp option | |
10716 | @end table | |
10717 | and functions: | |
10718 | @table @option | |
10719 | @item a_weighting(f) | |
10720 | A-weighting of equal loudness | |
10721 | @item b_weighting(f) | |
10722 | B-weighting of equal loudness | |
10723 | @item c_weighting(f) | |
10724 | C-weighting of equal loudness | |
10725 | @end table | |
10726 | Default value is @code{16}. | |
10727 | ||
10728 | @item tlength | |
10729 | Specify transform length expression. The expression can contain variables: | |
10730 | @table @option | |
10731 | @item frequency, freq, f | |
10732 | the frequency where transform is evaluated | |
10733 | @item timeclamp, tc | |
10734 | value of timeclamp option | |
10735 | @end table | |
10736 | Default value is @code{384/f*tc/(384/f+tc)}. | |
10737 | ||
10738 | @item timeclamp | |
10739 | Specify the transform timeclamp. At low frequency, there is trade-off between | |
10740 | accuracy in time domain and frequency domain. If timeclamp is lower, | |
10741 | event in time domain is represented more accurately (such as fast bass drum), | |
10742 | otherwise event in frequency domain is represented more accurately | |
10743 | (such as bass guitar). Acceptable value is [0.1, 1.0]. Default value is @code{0.17}. | |
10744 | ||
10745 | @item coeffclamp | |
10746 | Specify the transform coeffclamp. If coeffclamp is lower, transform is | |
10747 | more accurate, otherwise transform is faster. Acceptable value is [0.1, 10.0]. | |
10748 | Default value is @code{1.0}. | |
10749 | ||
10750 | @item gamma | |
10751 | Specify gamma. Lower gamma makes the spectrum more contrast, higher gamma | |
10752 | makes the spectrum having more range. Acceptable value is [1.0, 7.0]. | |
10753 | Default value is @code{3.0}. | |
10754 | ||
10755 | @item fontfile | |
10756 | Specify font file for use with freetype. If not specified, use embedded font. | |
10757 | ||
10758 | @item fontcolor | |
10759 | Specify font color expression. This is arithmetic expression that should return | |
10760 | integer value 0xRRGGBB. The expression can contain variables: | |
10761 | @table @option | |
10762 | @item frequency, freq, f | |
10763 | the frequency where transform is evaluated | |
10764 | @item timeclamp, tc | |
10765 | value of timeclamp option | |
10766 | @end table | |
10767 | and functions: | |
10768 | @table @option | |
10769 | @item midi(f) | |
10770 | midi number of frequency f, some midi numbers: E0(16), C1(24), C2(36), A4(69) | |
10771 | @item r(x), g(x), b(x) | |
10772 | red, green, and blue value of intensity x | |
10773 | @end table | |
10774 | Default value is @code{st(0, (midi(f)-59.5)/12); | |
10775 | st(1, if(between(ld(0),0,1), 0.5-0.5*cos(2*PI*ld(0)), 0)); | |
10776 | r(1-ld(1)) + b(ld(1))} | |
10777 | ||
10778 | @item fullhd | |
10779 | If set to 1 (the default), the video size is 1920x1080 (full HD), | |
10780 | if set to 0, the video size is 960x540. Use this option to make CPU usage lower. | |
10781 | ||
10782 | @item fps | |
10783 | Specify video fps. Default value is @code{25}. | |
10784 | ||
10785 | @item count | |
10786 | Specify number of transform per frame, so there are fps*count transforms | |
10787 | per second. Note that audio data rate must be divisible by fps*count. | |
10788 | Default value is @code{6}. | |
10789 | ||
10790 | @end table | |
10791 | ||
10792 | @subsection Examples | |
10793 | ||
10794 | @itemize | |
10795 | @item | |
10796 | Playing audio while showing the spectrum: | |
10797 | @example | |
10798 | ffplay -f lavfi 'amovie=a.mp3, asplit [a][out1]; [a] showcqt [out0]' | |
10799 | @end example | |
10800 | ||
10801 | @item | |
10802 | Same as above, but with frame rate 30 fps: | |
10803 | @example | |
10804 | ffplay -f lavfi 'amovie=a.mp3, asplit [a][out1]; [a] showcqt=fps=30:count=5 [out0]' | |
10805 | @end example | |
10806 | ||
10807 | @item | |
10808 | Playing at 960x540 and lower CPU usage: | |
10809 | @example | |
10810 | ffplay -f lavfi 'amovie=a.mp3, asplit [a][out1]; [a] showcqt=fullhd=0:count=3 [out0]' | |
10811 | @end example | |
10812 | ||
10813 | @item | |
10814 | A1 and its harmonics: A1, A2, (near)E3, A3: | |
10815 | @example | |
10816 | 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), | |
10817 | asplit[a][out1]; [a] showcqt [out0]' | |
10818 | @end example | |
10819 | ||
10820 | @item | |
10821 | Same as above, but with more accuracy in frequency domain (and slower): | |
10822 | @example | |
10823 | 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), | |
10824 | asplit[a][out1]; [a] showcqt=timeclamp=0.5 [out0]' | |
10825 | @end example | |
10826 | ||
10827 | @item | |
10828 | B-weighting of equal loudness | |
10829 | @example | |
10830 | volume=16*b_weighting(f) | |
10831 | @end example | |
10832 | ||
10833 | @item | |
10834 | Lower Q factor | |
10835 | @example | |
10836 | tlength=100/f*tc/(100/f+tc) | |
10837 | @end example | |
10838 | ||
10839 | @item | |
10840 | Custom fontcolor, C-note is colored green, others are colored blue | |
10841 | @example | |
10842 | fontcolor='if(mod(floor(midi(f)+0.5),12), 0x0000FF, g(1))' | |
10843 | @end example | |
10844 | ||
10845 | @end itemize | |
10846 | ||
10847 | @section showspectrum | |
10848 | ||
10849 | Convert input audio to a video output, representing the audio frequency | |
10850 | spectrum. | |
10851 | ||
10852 | The filter accepts the following options: | |
10853 | ||
10854 | @table @option | |
10855 | @item size, s | |
10856 | Specify the video size for the output. For the syntax of this option, check | |
10857 | the "Video size" section in the ffmpeg-utils manual. Default value is | |
10858 | @code{640x512}. | |
10859 | ||
10860 | @item slide | |
10861 | Specify how the spectrum should slide along the window. | |
10862 | ||
10863 | It accepts the following values: | |
10864 | @table @samp | |
10865 | @item replace | |
10866 | the samples start again on the left when they reach the right | |
10867 | @item scroll | |
10868 | the samples scroll from right to left | |
10869 | @item fullframe | |
10870 | frames are only produced when the samples reach the right | |
10871 | @end table | |
10872 | ||
10873 | Default value is @code{replace}. | |
10874 | ||
10875 | @item mode | |
10876 | Specify display mode. | |
10877 | ||
10878 | It accepts the following values: | |
10879 | @table @samp | |
10880 | @item combined | |
10881 | all channels are displayed in the same row | |
10882 | @item separate | |
10883 | all channels are displayed in separate rows | |
10884 | @end table | |
10885 | ||
10886 | Default value is @samp{combined}. | |
10887 | ||
10888 | @item color | |
10889 | Specify display color mode. | |
10890 | ||
10891 | It accepts the following values: | |
10892 | @table @samp | |
10893 | @item channel | |
10894 | each channel is displayed in a separate color | |
10895 | @item intensity | |
10896 | each channel is is displayed using the same color scheme | |
10897 | @end table | |
10898 | ||
10899 | Default value is @samp{channel}. | |
10900 | ||
10901 | @item scale | |
10902 | Specify scale used for calculating intensity color values. | |
10903 | ||
10904 | It accepts the following values: | |
10905 | @table @samp | |
10906 | @item lin | |
10907 | linear | |
10908 | @item sqrt | |
10909 | square root, default | |
10910 | @item cbrt | |
10911 | cubic root | |
10912 | @item log | |
10913 | logarithmic | |
10914 | @end table | |
10915 | ||
10916 | Default value is @samp{sqrt}. | |
10917 | ||
10918 | @item saturation | |
10919 | Set saturation modifier for displayed colors. Negative values provide | |
10920 | alternative color scheme. @code{0} is no saturation at all. | |
10921 | Saturation must be in [-10.0, 10.0] range. | |
10922 | Default value is @code{1}. | |
10923 | ||
10924 | @item win_func | |
10925 | Set window function. | |
10926 | ||
10927 | It accepts the following values: | |
10928 | @table @samp | |
10929 | @item none | |
10930 | No samples pre-processing (do not expect this to be faster) | |
10931 | @item hann | |
10932 | Hann window | |
10933 | @item hamming | |
10934 | Hamming window | |
10935 | @item blackman | |
10936 | Blackman window | |
10937 | @end table | |
10938 | ||
10939 | Default value is @code{hann}. | |
10940 | @end table | |
10941 | ||
10942 | The usage is very similar to the showwaves filter; see the examples in that | |
10943 | section. | |
10944 | ||
10945 | @subsection Examples | |
10946 | ||
10947 | @itemize | |
10948 | @item | |
10949 | Large window with logarithmic color scaling: | |
10950 | @example | |
10951 | showspectrum=s=1280x480:scale=log | |
10952 | @end example | |
10953 | ||
10954 | @item | |
10955 | Complete example for a colored and sliding spectrum per channel using @command{ffplay}: | |
10956 | @example | |
10957 | ffplay -f lavfi 'amovie=input.mp3, asplit [a][out1]; | |
10958 | [a] showspectrum=mode=separate:color=intensity:slide=1:scale=cbrt [out0]' | |
10959 | @end example | |
10960 | @end itemize | |
10961 | ||
10962 | @section showwaves | |
10963 | ||
10964 | Convert input audio to a video output, representing the samples waves. | |
10965 | ||
10966 | The filter accepts the following options: | |
10967 | ||
10968 | @table @option | |
10969 | @item size, s | |
10970 | Specify the video size for the output. For the syntax of this option, check | |
10971 | the "Video size" section in the ffmpeg-utils manual. Default value | |
10972 | is "600x240". | |
10973 | ||
10974 | @item mode | |
10975 | Set display mode. | |
10976 | ||
10977 | Available values are: | |
10978 | @table @samp | |
10979 | @item point | |
10980 | Draw a point for each sample. | |
10981 | ||
10982 | @item line | |
10983 | Draw a vertical line for each sample. | |
10984 | ||
10985 | @item p2p | |
10986 | Draw a point for each sample and a line between them. | |
10987 | ||
10988 | @item cline | |
10989 | Draw a centered vertical line for each sample. | |
10990 | @end table | |
10991 | ||
10992 | Default value is @code{point}. | |
10993 | ||
10994 | @item n | |
10995 | Set the number of samples which are printed on the same column. A | |
10996 | larger value will decrease the frame rate. Must be a positive | |
10997 | integer. This option can be set only if the value for @var{rate} | |
10998 | is not explicitly specified. | |
10999 | ||
11000 | @item rate, r | |
11001 | Set the (approximate) output frame rate. This is done by setting the | |
11002 | option @var{n}. Default value is "25". | |
11003 | ||
11004 | @item split_channels | |
11005 | Set if channels should be drawn separately or overlap. Default value is 0. | |
11006 | ||
11007 | @end table | |
11008 | ||
11009 | @subsection Examples | |
11010 | ||
11011 | @itemize | |
11012 | @item | |
11013 | Output the input file audio and the corresponding video representation | |
11014 | at the same time: | |
11015 | @example | |
11016 | amovie=a.mp3,asplit[out0],showwaves[out1] | |
11017 | @end example | |
11018 | ||
11019 | @item | |
11020 | Create a synthetic signal and show it with showwaves, forcing a | |
11021 | frame rate of 30 frames per second: | |
11022 | @example | |
11023 | aevalsrc=sin(1*2*PI*t)*sin(880*2*PI*t):cos(2*PI*200*t),asplit[out0],showwaves=r=30[out1] | |
11024 | @end example | |
11025 | @end itemize | |
11026 | ||
11027 | @section split, asplit | |
11028 | ||
11029 | Split input into several identical outputs. | |
11030 | ||
11031 | @code{asplit} works with audio input, @code{split} with video. | |
11032 | ||
11033 | The filter accepts a single parameter which specifies the number of outputs. If | |
11034 | unspecified, it defaults to 2. | |
11035 | ||
11036 | @subsection Examples | |
11037 | ||
11038 | @itemize | |
11039 | @item | |
11040 | Create two separate outputs from the same input: | |
11041 | @example | |
11042 | [in] split [out0][out1] | |
11043 | @end example | |
11044 | ||
11045 | @item | |
11046 | To create 3 or more outputs, you need to specify the number of | |
11047 | outputs, like in: | |
11048 | @example | |
11049 | [in] asplit=3 [out0][out1][out2] | |
11050 | @end example | |
11051 | ||
11052 | @item | |
11053 | Create two separate outputs from the same input, one cropped and | |
11054 | one padded: | |
11055 | @example | |
11056 | [in] split [splitout1][splitout2]; | |
11057 | [splitout1] crop=100:100:0:0 [cropout]; | |
11058 | [splitout2] pad=200:200:100:100 [padout]; | |
11059 | @end example | |
11060 | ||
11061 | @item | |
11062 | Create 5 copies of the input audio with @command{ffmpeg}: | |
11063 | @example | |
11064 | ffmpeg -i INPUT -filter_complex asplit=5 OUTPUT | |
11065 | @end example | |
11066 | @end itemize | |
11067 | ||
11068 | @section zmq, azmq | |
11069 | ||
11070 | Receive commands sent through a libzmq client, and forward them to | |
11071 | filters in the filtergraph. | |
11072 | ||
11073 | @code{zmq} and @code{azmq} work as a pass-through filters. @code{zmq} | |
11074 | must be inserted between two video filters, @code{azmq} between two | |
11075 | audio filters. | |
11076 | ||
11077 | To enable these filters you need to install the libzmq library and | |
11078 | headers and configure FFmpeg with @code{--enable-libzmq}. | |
11079 | ||
11080 | For more information about libzmq see: | |
11081 | @url{http://www.zeromq.org/} | |
11082 | ||
11083 | The @code{zmq} and @code{azmq} filters work as a libzmq server, which | |
11084 | receives messages sent through a network interface defined by the | |
11085 | @option{bind_address} option. | |
11086 | ||
11087 | The received message must be in the form: | |
11088 | @example | |
11089 | @var{TARGET} @var{COMMAND} [@var{ARG}] | |
11090 | @end example | |
11091 | ||
11092 | @var{TARGET} specifies the target of the command, usually the name of | |
11093 | the filter class or a specific filter instance name. | |
11094 | ||
11095 | @var{COMMAND} specifies the name of the command for the target filter. | |
11096 | ||
11097 | @var{ARG} is optional and specifies the optional argument list for the | |
11098 | given @var{COMMAND}. | |
11099 | ||
11100 | Upon reception, the message is processed and the corresponding command | |
11101 | is injected into the filtergraph. Depending on the result, the filter | |
11102 | will send a reply to the client, adopting the format: | |
11103 | @example | |
11104 | @var{ERROR_CODE} @var{ERROR_REASON} | |
11105 | @var{MESSAGE} | |
11106 | @end example | |
11107 | ||
11108 | @var{MESSAGE} is optional. | |
11109 | ||
11110 | @subsection Examples | |
11111 | ||
11112 | Look at @file{tools/zmqsend} for an example of a zmq client which can | |
11113 | be used to send commands processed by these filters. | |
11114 | ||
11115 | Consider the following filtergraph generated by @command{ffplay} | |
11116 | @example | |
11117 | ffplay -dumpgraph 1 -f lavfi " | |
11118 | color=s=100x100:c=red [l]; | |
11119 | color=s=100x100:c=blue [r]; | |
11120 | nullsrc=s=200x100, zmq [bg]; | |
11121 | [bg][l] overlay [bg+l]; | |
11122 | [bg+l][r] overlay=x=100 " | |
11123 | @end example | |
11124 | ||
11125 | To change the color of the left side of the video, the following | |
11126 | command can be used: | |
11127 | @example | |
11128 | echo Parsed_color_0 c yellow | tools/zmqsend | |
11129 | @end example | |
11130 | ||
11131 | To change the right side: | |
11132 | @example | |
11133 | echo Parsed_color_1 c pink | tools/zmqsend | |
11134 | @end example | |
11135 | ||
11136 | @c man end MULTIMEDIA FILTERS | |
11137 | ||
11138 | @chapter Multimedia Sources | |
11139 | @c man begin MULTIMEDIA SOURCES | |
11140 | ||
11141 | Below is a description of the currently available multimedia sources. | |
11142 | ||
11143 | @section amovie | |
11144 | ||
11145 | This is the same as @ref{movie} source, except it selects an audio | |
11146 | stream by default. | |
11147 | ||
11148 | @anchor{movie} | |
11149 | @section movie | |
11150 | ||
11151 | Read audio and/or video stream(s) from a movie container. | |
11152 | ||
11153 | It accepts the following parameters: | |
11154 | ||
11155 | @table @option | |
11156 | @item filename | |
11157 | The name of the resource to read (not necessarily a file; it can also be a | |
11158 | device or a stream accessed through some protocol). | |
11159 | ||
11160 | @item format_name, f | |
11161 | Specifies the format assumed for the movie to read, and can be either | |
11162 | the name of a container or an input device. If not specified, the | |
11163 | format is guessed from @var{movie_name} or by probing. | |
11164 | ||
11165 | @item seek_point, sp | |
11166 | Specifies the seek point in seconds. The frames will be output | |
11167 | starting from this seek point. The parameter is evaluated with | |
11168 | @code{av_strtod}, so the numerical value may be suffixed by an IS | |
11169 | postfix. The default value is "0". | |
11170 | ||
11171 | @item streams, s | |
11172 | Specifies the streams to read. Several streams can be specified, | |
11173 | separated by "+". The source will then have as many outputs, in the | |
11174 | same order. The syntax is explained in the ``Stream specifiers'' | |
11175 | section in the ffmpeg manual. Two special names, "dv" and "da" specify | |
11176 | respectively the default (best suited) video and audio stream. Default | |
11177 | is "dv", or "da" if the filter is called as "amovie". | |
11178 | ||
11179 | @item stream_index, si | |
11180 | Specifies the index of the video stream to read. If the value is -1, | |
11181 | the most suitable video stream will be automatically selected. The default | |
11182 | value is "-1". Deprecated. If the filter is called "amovie", it will select | |
11183 | audio instead of video. | |
11184 | ||
11185 | @item loop | |
11186 | Specifies how many times to read the stream in sequence. | |
11187 | If the value is less than 1, the stream will be read again and again. | |
11188 | Default value is "1". | |
11189 | ||
11190 | Note that when the movie is looped the source timestamps are not | |
11191 | changed, so it will generate non monotonically increasing timestamps. | |
11192 | @end table | |
11193 | ||
11194 | It allows overlaying a second video on top of the main input of | |
11195 | a filtergraph, as shown in this graph: | |
11196 | @example | |
11197 | input -----------> deltapts0 --> overlay --> output | |
11198 | ^ | |
11199 | | | |
11200 | movie --> scale--> deltapts1 -------+ | |
11201 | @end example | |
11202 | @subsection Examples | |
11203 | ||
11204 | @itemize | |
11205 | @item | |
11206 | Skip 3.2 seconds from the start of the AVI file in.avi, and overlay it | |
11207 | on top of the input labelled "in": | |
11208 | @example | |
11209 | movie=in.avi:seek_point=3.2, scale=180:-1, setpts=PTS-STARTPTS [over]; | |
11210 | [in] setpts=PTS-STARTPTS [main]; | |
11211 | [main][over] overlay=16:16 [out] | |
11212 | @end example | |
11213 | ||
11214 | @item | |
11215 | Read from a video4linux2 device, and overlay it on top of the input | |
11216 | labelled "in": | |
11217 | @example | |
11218 | movie=/dev/video0:f=video4linux2, scale=180:-1, setpts=PTS-STARTPTS [over]; | |
11219 | [in] setpts=PTS-STARTPTS [main]; | |
11220 | [main][over] overlay=16:16 [out] | |
11221 | @end example | |
11222 | ||
11223 | @item | |
11224 | Read the first video stream and the audio stream with id 0x81 from | |
11225 | dvd.vob; the video is connected to the pad named "video" and the audio is | |
11226 | connected to the pad named "audio": | |
11227 | @example | |
11228 | movie=dvd.vob:s=v:0+#0x81 [video] [audio] | |
11229 | @end example | |
11230 | @end itemize | |
11231 | ||
11232 | @c man end MULTIMEDIA SOURCES |